2022-03-08 05:58:12 +00:00
|
|
|
# Relay Listeners
|
2022-03-07 16:57:02 +00:00
|
|
|
|
2022-03-08 05:58:12 +00:00
|
|
|
- Relevant schema:
|
|
|
|
|
- [[syndicate-rs]/syndicate-server/protocols/schemas/internalServices.prs](https://git.syndicate-lang.org/syndicate-lang/syndicate-rs/src/branch/main/syndicate-server/protocols/schemas/internalServices.prs)
|
|
|
|
|
- [[syndicate-protocol]/schemas/transportAddress.prs](https://git.syndicate-lang.org/syndicate-lang/syndicate-protocols/src/branch/main/schemas/transportAddress.prs)
|
2022-03-07 16:57:02 +00:00
|
|
|
|
2022-03-08 05:58:12 +00:00
|
|
|
The `syndicate-server` program can be configured to listen on TCP/IP ports and Unix
|
|
|
|
|
sockets[^sock-stream-only] for incoming connections speaking the [Syndicate network
|
|
|
|
|
protocol][protocol].
|
2022-03-07 16:57:02 +00:00
|
|
|
|
2022-03-08 05:58:12 +00:00
|
|
|
[protocol]: ../../protocol.md
|
|
|
|
|
|
|
|
|
|
## <span id="tcpip"></span>TCP/IP and WebSockets
|
|
|
|
|
|
|
|
|
|
Assertions [requiring](../service.md#require-service) 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](../../glossary.md#reference) as the
|
|
|
|
|
[initial ref](../../glossary.md#initial-ref) of incoming connections:
|
|
|
|
|
|
|
|
|
|
```preserves-schema
|
|
|
|
|
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](https://docs.rs/tokio-tungstenite/latest/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.
|
2022-03-07 16:57:02 +00:00
|
|
|
|
|
|
|
|
## Unix sockets
|
2022-03-08 05:58:12 +00:00
|
|
|
|
|
|
|
|
Assertions [requiring](../service.md#require-service) 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](../../glossary.md#reference) as the
|
|
|
|
|
[initial ref](../../glossary.md#initial-ref) of incoming connections:
|
|
|
|
|
|
|
|
|
|
```preserves-schema
|
|
|
|
|
UnixRelayListener = <relay-listener @addr Unix @gatekeeper #!gatekeeper.Resolve> .
|
|
|
|
|
Unix = <unix @path string>.
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Syntax autodetection is as for [TCP/IP](#tcpip), except that WebSockets are not supported over
|
|
|
|
|
Unix sockets.
|
|
|
|
|
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
#### Notes
|
|
|
|
|
|
|
|
|
|
[^sock-stream-only]: Only `SOCK_STREAM` Unix sockets are supported, at present. In future,
|
|
|
|
|
`SOCK_DGRAM` could be useful for e.g. file-descriptor passing.
|
