Relay Listeners

The syndicate-server program can be configured to listen on TCP/IP ports and Unix sockets1 for incoming connections speaking the Syndicate network protocol.

TCP/IP and WebSockets

Assertions requiring a service with name matching TcpRelayListener cause the server to start a TCP server socket on the given addr's host and port, exposing the gatekeeper entity reference as the initial ref of incoming connections:

TcpRelayListener = <relay-listener @addr Tcp @gatekeeper #:gatekeeper.Resolve> .
Tcp = <tcp @host string @port int>.

When a new connection arrives, the first byte is examined to see what kind of connection it is and which Preserves syntax it will use.

  • If it is ASCII "G" (0x47), it cannot be the start of a protocol packet, so it is interpreted as the start of a WebSocket connection and handed off to the tokio_tungstenite WebSocket library. Within the WebSocket's context, each packet must be encoded as a binary packet using Preserves binary syntax.

  • Otherwise, if it could start a valid UTF-8 sequence, the connection will be a plain TCP/IP link using the Preserves text syntax.

  • Otherwise, it's a byte which cannot be part of a valid UTF-8 sequence, so it is interpreted as a Preserves binary syntax tag: the connection will be a plain TCP/IP link using Preserves binary syntax.

Unix sockets

Assertions requiring a service with name matching UnixRelayListener cause the server to start a Unix server socket on the given addr's path, exposing the gatekeeper entity reference as the initial ref of incoming connections:

UnixRelayListener = <relay-listener @addr Unix @gatekeeper #:gatekeeper.Resolve> .
Unix = <unix @path string>.

Syntax autodetection is as for TCP/IP, except that WebSockets are not supported over Unix sockets.

Notes

1

Only SOCK_STREAM Unix sockets are supported, at present. In future, SOCK_DGRAM could be useful for e.g. file-descriptor passing.