TCP Server Connector

Version 20.0.7488


TCP Server Connector



TCP Server Connectors support hosting a generic endpoint for receiving arbitrary data over TCP.

Overview

Each TCP Server Connector listens on a specified port for incoming TCP traffic, either with SSL/TLS encryption or plaintext. The connector is intended for use when Arc needs to receive arbitrary data that does not necessarily fit into the constraints provided by other standard protocols.

Since TCP traffic is a constant stream that does not intrinsically have a ‘start’ or ‘end’ point, the connector must be configured to determine where one message ends and the next begins. The connector supports two approaches:

  • A static string/character delimiter that ends the current message or begins the next message
  • Reading a value in the incoming TCP data to determine how long the message should be

For the second approach, the connector requires an offset (how many bytes after the first byte to begin reading the message length) and a size (how many bytes to read, starting at the offset, to read the length value). If the length of the message is the first value in the ‘header’ for the message, the offset should be 0.

Once the delimiter or length is reached, the connector will push a message into the Arc Flow containing the raw data received over TCP.

The TCP Server Connector can also generate an Arc message when a client connects or disconnects, to alert other processes within the Flow. More information can be found in the Connected and Disconnected Messages section.

For information on sending responses back to TCP clients, please see the Sending Messages section.

Connector Settings

Settings Tab

Configuration

Settings related to the core configuration of the connector.

  • Connector Id The static name of the connector. All connector-specific files are held in a folder by the same name within the Data Directory.
  • Connector Description An optional field to provide free-form description of the connector and its role in the flow.
  • Port The port on which to listen for incoming TCP connections.

Message Decoding

Settings related to distinguishing individual messages from the TCP stream.

  • Message Start Delimiter The character or string indicating the start of a new message.
  • Message End Delimiter The character or string indicating the end of the current message.
  • Message Length Offset The number of bytes to skip before beginning to read the length of the message from the incoming data.
  • Message Length Size The size in bytes of the length value within the incoming data.

TLS Settings

Settings related to SSL/TLS transport security.

  • Enable TLS Whether clients must negotiate SSL/TLS encryption to connect to the TCP server.
  • Server Certificate The SSL/TLS certificate that identifies the TCP server.
  • Certificate Password The password to access the Server Certificate’s private key.

Advanced Tab

Local Folders

Settings that determine where files will be read from and processed to.

  • Input Folder (Send) Files placed here will be converted into an outgoing TCP message by the connector. If Send Automation is enabled, the connector will automatically poll this location for files to trigger a request.
  • Output Folder (Receive) Messages received by the connector will be placed here. If the connector is connected to another connector in the flow, files will not remain here and will instead be passed along to the Input/Send folder for the connected connector.
  • Processed Folder (Sent) The connector will place a copy of processed/sent files here if Save to Sent Folder is enabled. This copy of the file will not be passed along to the next connector in the flow.

Logging

Settings related to the logs maintained by the server.

  • Enable Server Log Whether to maintain server-side logging for connections.
  • Server Log Rotation The interval according to which logs should be archived (compressed and moved to an archive folder).
  • Server Log Rotation The interval according to which logs should be deleted.

Keep Alive

Settings related to keep-alive packets sent by the server to maintain an idle connection.

  • Keep Alive Whether to send keep-alive packets periodically to ensure that idle connections are not closed due to inactivity.
  • Keep Alive Time The length of inactivity that should elapse before sending the first keep-alive packet.
  • Keep Alive Interval The interval between consecutive keep-alive packets.

Other Settings

Settings not included in the previous categories.

  • Connected Messages Whether the connector should generate an Arc message when a client connects. More information can be found in the Connected and Disconnected Messages section.
  • Disconnected Messages Whether the connector should generate an Arc message when a client disconnects. More information can be found in the Connected and Disconnected Messages section.
  • Idle Timeout The length of time the server should wait for an idle client before disconnecting them due to inactivity.
  • Local File Scheme A filemask for determining local file names as they are downloaded by the connector. The following macros may be used to reference contextual information:
    %ConnectorId%, %Filename%, %FilenameNoExt%, %Ext%, %ShortDate%, %LongDate%, %RegexFilename:%, %DateFormat:%.
    As an example: %FilenameNoExt%_%ShortDate%%Ext%
  • Local Host The binding address of the local server, if not the default network interface.
  • Log Level The level of detail included in logs generated for the connector.
  • Max Connections The maximum number of concurrent connectors.
  • Other An arbitrary set of advanced configuration settings.
  • Parent Connector If set to another TCP Server Connector, this connector will inherit settings from that connector. Any local settings will override settings from the parent.
  • Log Messages Whether logs from sent files will include a copy of the file itself.
  • Save to Sent Folder Whether files sent by the connector should be copied to the Sent folder for the connector.
  • SSL/TLS Enabled Protocols The list of SSL/TLS protocols supported when establishing outgoing connections. It is strongly recommended to only use TLS protocols. Some obsolete operating systems do not support TLS 1.2.

Connected and Disconnected Messages

By default, the TCP Server Connector will only generate Arc messages when clients transfer data such that the connector recognizes a full message (according to the settings in the Message Decoding section). The connector can also generate Arc messages when a client connects to the server (if Connected Messages is enabled in the Advanced tab) or disconnects from the server (if Disconnected Messages is enabled in the Advanced tab).

When these special messages are generated, a special header is added to the Arc message:

x-tcpserver-event

This header is set to the value ‘connected’ when clients are connecting, and ‘disconnected’ when clients are disconnecting.

This header value must be checked by later connectors in the Flow to detect whether a message written to the output folder of a TCP Server Connector is one of these special messages.

Sending Messages

The TCP Server Connector also uses a special header value to send messages back to connected clients:

x-tcpserver-connectionid

This header is added to any output messages generated by the connector, set to a ‘Connection ID’ value that uniquely identifies one of the connected clients. Messages that should be sent back to this client must have this same header set to the same value in order to ensure that the message is sent to the appropriate client.

Since this header is already present on any messages written out by the connector, if the message passes through an Arc Flow and arrives back at the Send folder for the TCP Server Connector, it will still have the same ‘Connection ID’ value and will be returned to the same client that sent the original message. If the message cannot be directly routed back to the TCP Server Connector, then the ‘Connection ID’ value must be saved and applied as a header (with the same name listed above) to whatever new messages should be returned to the client.