datalogd.plugins.socket_datafilter module

class datalogd.plugins.socket_datafilter.SocketDataFilter(sinks=[], role='server', host='127.0.0.1', port=45454, buffer_size=1048576, message_encoding='utf8', message_delimiter='x17', structure_type='json')

Bases: datalogd.DataFilter

Send and receive data over a network socket.

The SocketDataFilter bridges data over a network socket. The other end of the connection may be another SocketDataFilter, but can be any application that uses the correct message encoding and structure. The connected sockets don’t have to be on remote computers, and may be used to perform inter-process communications within a single machine.

The SocketDataFilter can also act as either a socket server, or a client. Connections must involve at least one server and one client. Servers will listen on their given port and accept multiple client connections. Clients will only make a single connection to the given server address and port. If a connection can’t be established or is lost, it will be retried indefinitely.

Incoming network data will be forwarded on to all of the SocketDataFilter’s DataSinks, and input from any connected DataSources will be sent on to any network connections. Note that this behaviour is more like a “bridge” than a “filter”.

The network communications protocol is quite basic, but allows some degree of customisation. The defaults are to convert the incoming python data from DataSources to a JSON structure, and encode the resulting string into a byte stream using UTF-8. Network connections are kept open, and messages are separated by an end-of-transmission (EOT, 0x17) byte.

The role parameter selects whether the SocketDataFilter acts as a socket server, or socket client. In server mode (default), a server is started bound to the given host name or address and port number. The server will accept multiple connections, and data will be sent and received from any/all connected clients. If role="client", then the SocketDataFilter will attempt to connect to a server given by the host address and port number.

The host address can be any name or IP address. To only allow connections to/from the local machine, use loopback address of host="127.0.0.1" (default). To allow a server to bind to any network interface, use host="".

The port can be any unused port number, typically a high number between 1024 and 65535.

The buffer_size should be set to the maximum expected size of a data message packet. The default is 1 MiB.

For string (or JSON structured) data, the message_encoding determines how it will be converted to or from a byte stream. The default of "utf8" is typically fine.

By default, network connections will be kept open, with data message packets separated by a delimiter end-of-transmission (EOT, 0x17) byte. This may be changed to a different byte sequence using the message_delimiter parameter. Setting message_delimiter=None will mean than the end of a message packet is expected to be followed by the client closing the network connection. Further messages can be sent if the network socket connection is re-established.

To transmit data through the network, it needs to be converted to a stream of bytes. The structure_type parameter determines how arbitrary python data should be converted to a structure which can be converted to a byte stream. The default is structure_type="json" which will attempt to convert data to or from a JSON object.

Parameters:

• role – Act as either a "server" or "client".
• host – Network name or address to bind to (as a server) or connect to (as a client).
• port – Network port number to listen on (as a server) or connect to (as a client).
• buffer_size – Size of buffer for messages, maximum message size.
• message_encoding – Character encoding used for string data (or JSON encoded structures).
• message_delimiter – Delimiter byte(s) used to separate message packets.
• structure_type – Structure type used to represent data.

receive(data)

Accept the provided data and output it to any connected sockets.

Parameters:data – Data to send to connected sockets.