Skip to main content
Version: edge

tcp

The tcp_server and tcp_client connectors allow TCP-based clients and servers to be integrated with tremor.

tcp_server

This connector listens for incoming TCP connections on the host and port configured in url. Each connection starts its own stream of events. Each TCP packet is received into a local buffer of buf_size bytes, which should be equal or bigger than the maximum expected packet size. Each packet is processed by the configured preprocessors and codec.

Each event will contain information about the TCP connection it comes from in a metadata record accessible via $tcp_server. The record is of the following form:

{
"tls": true, // boolean, indicating if this connection has tls configured or not
"peer": {
"host": "127.0.0.1", // ip of the connection peer
"port": 443 // port of the connection peer
}
}

When a connection is established and events are received, it is possible to send events to any open connection. In order to achieve this, a pipeline needs to be connected to the in port of this connector and send events to it. There are multiple ways to target a certain connection with a specific event:

  • Send the event you just received from the tcp_server right back to it. It will be able to track the the event to its TCP connection. You can even do this with an aggregate event coming from a select with a window. If an event is the result of events from multiple TCP connections, it will send the event back down to each TCP connection.
  • Attach the same metadata you receive on the connection under $tcp_server to the event you want to send to that connection.

Configuration

OptionDescriptionTypeRequiredDefault value
urlHost and port to listen on.stringyes
tlsOptional Transport Level Security configuration. See TLS configuration.recordnoNo TLS configured.
buf_sizeTCP receive buffer size. This should be greater than or equal to the expected maximum packet size.positive integerno8192
backlogThe maximum size of the queue of pending connections not yet accepted.positive integerno128
socket_optionsSee TCP socket options.recordnoSee TCP socket options defaults

Example:

config.troy
define connector `tcp-in` from tcp_server
with
codec = "string",
config = {
"url": "localhost:4242",
"socket_options": {
# tweaking the Nagle alhorithm, true by default
"TCP_NODELAY": false,
# enable multiple tcp servers sharing the same port
"SO_REUSEPORT": true
},
# Optional Transport Level Security configuration
# "tls" = { ... }

# Data buffer size ( default: 8K, limits maximum message size )
# "buf_size" = "16K",
}
end;

tcp_client

This connector establishes and maintains one TCP connection to the host and port configured in url. Every event this connector receives via its in port will be sent to that connection. It will emit events for the data it receives on that connection on the out port of this connector. Emitted events contain information about the TCP connection they originate from in the metadata available via $tcp_client. It is a record of the following form:

{
"tls": false, // whether or not TLS is configured on the connection
"peer": {
"host": "::1", // ip address of the connection peer
"port": 12345 // port of the connection peer
}
}

Configuration

OptionDescriptionTypeRequiredDefault value
urlHost and port to connect to.stringyes
tlsOptional Transport Level Security configuration. See TLS configuration.record or booleannoNo TLS configured.
buf_sizeTCP receive buffer size. This should be greater than or equal to the expected maximum packet size.positive integerno8192
socket_optionsSee TCP socket options.recordnoSee TCP socket options defaults

Example:

config.troy
define connector `tcp-out` from tcp_client
with
codec = "yaml",
postprocessors = ["base64"],
config = {
"url": "localhost:4242",

# Optional Transport Level Security configuration
# "tls" = { ... },

# Data buffer size ( default: 8K, limits maximum message size )
# "buf_size" = "16_000",
}
end;