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.

4 files changed, 171 insertions, 0 deletions

diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md
index 78853440..72b7dd94 100644
--- a/docs/ref/SUMMARY.md
+++ b/docs/ref/SUMMARY.md
@@ -1,6 +1,7 @@
 # Summary
 
 - [API](./api.md)
+
   - [Threading Functions](./api/thr/index.md)
     - [nng_mtx](./api/thr/nng_mtx.md)
   - [Utility Functions](./api/util/index.md)
@@ -8,4 +9,9 @@
     - [nng_id_map](./api/util/nng_id_map.md)
     - [nng_msleep](./api/util/nng_msleep.md)
 
+- [Transports](./tran/index.md)
+
+  - [BSD Socket](./tran/socket.md)
+  - [UDP](./tran/udp.md)
+
 [Index](./indexing.md)
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]