Darwin API object

DarwinApi

A class used to call Darwin via a Unix socket or a TCP connection handled by HAProxy.

Attributes

• FILTER_CODE_MAP (dict): a dict containing the different filter codes used by Darwin. This dict takes a plugin name as a key, and returns the associated filter code
• DEFAULT_TIMEOUT (float/None): the default timeout (expressed in seconds). If None is set, no timeout is active
• socket (socket.socket): the socket instance used to call Darwin
• **verbose (bool): whether to print debug lines or not

Methods

__init__

__init__(self, socket_type, **kwargs)

Create a darwin.DarwinApi instance, either with a Unix or a TCP socket.

Parameters

• kwargs
  • verbose (bool): whether to print debug lines or not. If not given, the default value is False
  • socket_type (str): the socket type to be used. "tcp" or "unix" (case insensitive)
  • socket_path (str): if the socket type given is "unix", this is the socket path which will be used to connect to Darwin
  • socket_host (str): if the socket type given is "tcp", this is the socket host which will be used to connect to Darwin
  • socket_port (int): if the socket type given is "tcp", this is the socket port which will be used to connect to Darwin
  • timeout (float/None): the timeout (expressed in seconds). If not given, the default timeout is set

get_filter_code

get_filter_code(filter_code)

Return a filter code from a given filter name. This is case insensitive.

Parameters

• filter_name (str): the name of the filter code (case insensitive)

Returns

int: the associated filter code.

call

call(self,
     arguments,
     packet_type="other",
     response_type="no",
     filter_code=DarwinPacket.DARWIN_FILTER_CODE_NO,
     **kwargs)

Perform an API call to Darwin, and return the result. This function is useful to make higher-level API calls to Darwin, compared to the darwin.DarwinApi.low_level_call method.

Parameters

• arguments (list): the list of arguments to be sent to Darwin. Please note that the arguments will be casted to strings
• packet_type (str): the packet type to be sent. "darwin" for any packet coming from a Darwin filter, "other" for everything else
• response_type (str): the response type which tells Darwin what it is expected to do. "no" to not answer anything, "back" to answer back to us, "darwin" to send the answer to the next filter, and "both" to apply both the "back" and "darwin" response types
• filter_code (int/str): the filter code to be provided. If a string is given, darwin.DarwinApi will try to retrieve the filter code associated to it
• kwargs
  • other keyword arguments can be given. This function uses darwin.DarwinAPI.low_level_call internally. For a more advanced use, please refer to the darwin.DarwinApi.low_level_call method documentation

Returns

int: if the call is synchronous, the Darwin result is returned. If no result are available, None is returned. If the call is asynchronous, the event ID is returned.

bulk_call

bulk_call(self,
          data,
          packet_type="other",
          response_type="no",
          filter_code=DarwinPacket.DARWIN_FILTER_CODE_NO,
          **kwargs)

Perform an API call to Darwin, and return the results or the event ID, depending on wheter the call is asynchronous or not.

Parameters

• data (list): list of arguments to send to Darwin
• packet_type (str): the packet type to be sent. "darwin" for any packet coming from a Darwin filter, `"other" for everything else
• response_type (str): the response type which tells Darwin what it is expected to do. "no" to not answer anything, "back" to answer back to us, "darwin" to send the answer to the next filter, and "both" to apply both the "back" and "darwin" response types
• filter_code (int/str): the filter code to be provided. If a string is given, darwin.DarwinApi will try to retrieve the filter code associated to it
• kwargs
  • other keyword arguments can be given. This function uses darwin.DarwinAPI.low_level_call internally. For a more advanced use, please refer to the darwin.DarwinApi.low_level_call method documentation

Returns

list: the Darwin results stored in a list

low_level_call

low_level_call(self, **kwargs)

Perform an API call to Darwin, and return the results.

Parameters

• kwargs
  • socket_type (str): the socket type to be used. "tcp" or "unix"
  • header (darwin.DarwinPacket): if provided, the darwin.DarwinPacket header instance to be sent to Darwin. If no header is given, a header description has to be provided (see the header_descr keyword argument)
  • header_descr (dict): if provided, the Darwin header description to create a darwin.DarwinPacket header instance, which will be sent to Darwin. Please refer to the darwin.DarwinPacket class documentation to know more about Darwin packets creation
  • data (list): the arguments to send to Darwin

Returns

If the call is synchronous the Darwin results are returned as a dictionary:

• "certitude_list": the list of certitudes returned by darwin
• "body": the body of the response

If the call is asynchronous, the event ID is returned.

close

close(self)

Close the Darwin socket.