diff --git a/protocols.csv b/protocols.csv index 5f5ea91..2b6eed9 100644 --- a/protocols.csv +++ b/protocols.csv @@ -13,7 +13,7 @@ code, size, name, comment 132, 16, sctp, 301, 0, udt, 302, 0, utp, -400, V, unix, +400, V, unix, Percent-encoded path to a Unix domain socket 421, V, p2p, preferred over /ipfs 421, V, ipfs, backwards compatibility; equivalent to /p2p 444, 96, onion, @@ -39,4 +39,4 @@ code, size, name, comment 280, 0, webrtc-direct, ICE-lite webrtc transport with SDP munging during connection establishment and without use of a STUN server 281, 0, webrtc, webrtc transport where connection establishment is according to w3c spec 290, 0, p2p-circuit, -777, V, memory, in memory transport for self-dialing and testing; arbitrary +777, V, memory, in memory transport for self-dialing and testing; arbitrary diff --git a/protocols/unix.md b/protocols/unix.md new file mode 100644 index 0000000..a37d18b --- /dev/null +++ b/protocols/unix.md @@ -0,0 +1,37 @@ +# `unix` + +This protocol encodes a Unix domain socket path to a resource. In the string +representation, the path is encoded in a way consistent with a single URI Path +segment per [RFC 3986 Section 3.3](https://datatracker.ietf.org/doc/html/rfc3986#autoid-23). + +Specifically following the grammar of a single `segment-nz`. In the binary +representation, no encoding is needed as the value is length prefixed. + +When comparing multiaddrs, implementations should compare their binary +representation to avoid ambiguities over which characters were escaped. + +## Examples + +The following is a table of examples converting some common Unix paths to their +Multiaddr string form. + +| Unix Path | Multiaddr string form | +| --------------------------- | --------------------------------------- | +| / | `/unix/%2F` | +| /file.socket | `/unix/%2Ffile.socket` | +| /dir/file.socket | `/unix/%2Fdir%2Ffile.socket` | +| /dir/file.socket/p2p/12D... | `/unix/%2Fdir%2Ffile.socket/p2p/12D...` | +| /tmp/foo/../bar | `/unix/%2Ftmp%2Ffoo%2F..%2Fbar` | +| /%2F | `/unix/%252F` | +| /a%20space | `/unix/%2Fa%2520space` | +| /a%2Fslash | `/unix/%2Fa%252Fslash` | +| socket | `/unix/socket` | + +## Usage + +`/unix` would typically be found at the start of a multiaddr, however it may +appear anywhere, for example in the case where we route through some sort of +proxy server or SSH tunnel. + +The absence of a `/` character at the start of the decoded address indicates a +relative path, otherwise the path is absolute.