From 515ffaacd8f46bb3abd814d869a699c25cc205ba Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sun, 6 Oct 2024 17:45:39 -0700 Subject: Initial swag at UDP transport docs, also converted socket transport to mdbook This has a lot of TODO links, because there are missing pieces still of course. --- docs/ref/tran/index.md | 4 +++ docs/ref/tran/socket.md | 71 ++++++++++++++++++++++++++++++++++++++ docs/ref/tran/udp.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 165 insertions(+) create mode 100644 docs/ref/tran/index.md create mode 100644 docs/ref/tran/socket.md create mode 100644 docs/ref/tran/udp.md (limited to 'docs/ref/tran') diff --git a/docs/ref/tran/index.md b/docs/ref/tran/index.md new file mode 100644 index 00000000..25f32a7f --- /dev/null +++ b/docs/ref/tran/index.md @@ -0,0 +1,4 @@ +# Transports + +- [BSD Socket](socket.md) +- [UDP](udp.md) diff --git a/docs/ref/tran/socket.md b/docs/ref/tran/socket.md new file mode 100644 index 00000000..cfb31ca3 --- /dev/null +++ b/docs/ref/tran/socket.md @@ -0,0 +1,71 @@ +# BSD Socket Transport (Experimental) + +The {{i:_socket_ transport}} supports communication between +peers across arbitrary BSD sockets, such as those that are +created with [`nng_socket_pair()`][nng_socket_pair]. + +This transport only supports [listeners][listener], +using [`nng_listener_create()`][nng_listener_create]. + +> [!NOTE] +> Attempts to create [dialers][dialer] using this transport will result in `NNG_ENOTSUP`. + +The socket file descriptor is passed to the listener using +the {{i:`NNG_OPT_SOCKET_FD`}} option (as an integer). +Setting this option will cause the listener to create a [pipe][pipe] +backed by the file descriptor. + +The protocol between peers using this transport is compatible with the protocol used +for the [_tcp_][tcp] transport, but this is an implementation detail and subject to change without notice. +{{footnote: Specifically it is not compatible with the [_ipc_][ipc] transport.}} + +> [!NOTE] +> This transport is _experimental_, and at present is only supported on POSIX platforms. +> {{footnote: Windows lacks a suitable `socketpair()` equivalent function we could use.}} + +## Registration + +No special action is necessary to register this transport. + +## URI Format + +This transport uses the URL {{i:`socket://`}}, without further qualification. + +## Socket Address + +The socket address will be of family {{i:`NNG_AF_UNSPEC`}}. +There are no further socket details available. + +## Transport Options + +The following transport option is available: + +- {{i:`NNG_OPT_SOCKET_FD`}}: \ + (int) \ + \ + This is a write-only option, that may be set multiple times on a listener. + Each time this is set, the listener will create a [pipe][pipe] backed by the given file + descriptor passed as an argument. + +Additionally, the following options may be supported on pipes when the platform supports them: + +- [`NNG_OPT_PEER_GID`][NNG_OPT_PEER_GID] +- [`NNG_OPT_PEER_PID`][NNG_OPT_PEER_PID] +- [`NNG_OPT_PEER_UID`][NNG_OPT_PEER_UID] +- [`NNG_OPT_PEER_ZONEID`][NNG_OPT_PEER_ZONEID] + +[ipc]: [ipc.md] +[tcp]: [tcp.md] +[pipe]: [TODO.md] +[listener]: [TODO.md] +[dialer]: [TODO.md] +[nng_sockaddr]: [TODO.md] +[nng_listener_create]: [TODO.md] +[nng_socket_pair]: [TODO.md] +[NNG_OPT_LOCADDR]: [TODO.md] +[NNG_OPT_REMADDR]: [TODO.md] +[NNG_OPT_URL]: [TODO.md] +[NNG_OPT_PEER_GID]: [TODO.md] +[NNG_OPT_PEER_PID]: [TODO.md] +[NNG_OPT_PEER_UID]: [TODO.md] +[NNG_OPT_PEER_ZONEID]: [TODO.md] diff --git a/docs/ref/tran/udp.md b/docs/ref/tran/udp.md new file mode 100644 index 00000000..4579c88a --- /dev/null +++ b/docs/ref/tran/udp.md @@ -0,0 +1,90 @@ +# UDP Transport (Experimental) + +The {{i:_udp_ transport}} supports communication between peers using {{i:UDP}}. + +UDP is a very light-weight connection-less, unreliable, unordered delivery mechanism. + +Both IPv4 and {{i:IPv6}} are supported when the underlying platform also supports it. + +## Maximum Message Size + +This transport maps each SP message to a single UDP packet. +In order to allow room for network headers, we thus limit the maximum +message size to 65000 bytes, minus the overhead for any SP protocol headers. + +However, applications are _strongly_ encouraged to only use this transport for +very much smaller messages, ideally those that will fit within a single network +packet without requiring fragmentation and reassembly. + +For Ethernet without jumbo frames, this typically means an {{i:MTU}} of a little +less than 1500 bytes. (Specifically, 1452, which allows 28 bytes for IP and UDP, +and 20 bytes for the this transport). +Other link layers may have different MTUs. + +> [!NOTE] +> This transport is _experimental_. + +## URI Format + +This transport uses URIs using the scheme {{i:`udp://`}}, followed by +an IP address or hostname, followed by a colon and finally a +TCP {{i:port number}}. +For example, to contact port 80 on the localhost either of the following URIs +could be used: `udp://127.0.0.1:80` or `udp://localhost:80`. + +A URI may be restricted to IPv6 using the scheme `udp6://`, and may +be restricted to IPv4 using the scheme `udp4://`. + +> [!NOTE] +> Specifying `udp6://` may not prevent IPv4 hosts from being used with +> IPv4-in-IPv6 addresses, particularly when using a wildcard hostname with +> listeners. +> The details of this varies across operating systems. + +> [!TIP] +> We recommend using either numeric IP addresses, or names that are +> specific to either IPv4 or IPv6 to prevent confusion and surprises. + +When specifying IPv6 addresses, the address must be enclosed in +square brackets (`[]`) to avoid confusion with the final colon +separating the port. + +For example, the same port 80 on the IPv6 loopback address (`::1`) would +be specified as `udp://[::1]:80`. + +The special value of 0 ({{i:`INADDR_ANY`}}) +can be used for a listener to indicate that it should listen on all +interfaces on the host. +A short-hand for this form is to either omit the address, or specify +the asterisk (`*`) character. +For example, the following three URIs are all equivalent, +and could be used to listen to port 9999 on the host: + +1. `udp://0.0.0.0:9999` +2. `udp://*:9999` +3. `udp://:9999` + +## Socket Address + +When using an [`nng_sockaddr`][nng_sockaddr] structure, +the actual structure is either of type +[`nng_sockaddr_in`][nng_sockaddr_in] (for IPv4) or +[`nng_sockaddr_in6`][nng_sockaddr_in6] (for IPv6). + +## Transport Options + +The following transport options are supported by this transport, +where supported by the underlying platform. + +- [`NNG_OPT_LOCADDR`][NNG_OPT_LOCADDR] +- [`NNG_OPT_REMADDR`][NNG_OPT_REMADDR] +- [`NNG_OPT_URL`][NNG_OPT_URL] + +TOOD: Document other options. + +[nng_sockaddr]: [TODO.md] +[nng_sockaddr_in]: [TODO.md] +[nng_sockaddr_in6]: [TODO.md] +[NNG_OPT_LOCADDR]: [TODO.md] +[NNG_OPT_REMADDR]: [TODO.md] +[NNG_OPT_URL]: [TODO.md] -- cgit v1.2.3-70-g09d2