From 91b3f5c42ae7e760818ef31e0be93ac6f1fcffb2 Mon Sep 17 00:00:00 2001 From: achingbrain Date: Mon, 28 Oct 2024 19:12:08 +0000 Subject: [PATCH 1/3] Define `/unix` Adds a protocol note for how to encode paths to Unix domain sockets as strings, that may include the delimiting character of `/`. This allows us to append other tuples to the multiaddr while also ensuring we can round-trip the address to a string and back. This doesn't affect the binary representation of the multiaddr since everything is length-delimited. Takes inspiration from #164 and proposes using URI encoding for the segment, the same as the `/http-path` component. One difference is if the path is to represent the filesystem root, it must be included in the value portion of the tuple, otherwise it can be omitted. --- protocols.csv | 4 ++-- protocols/unix.md | 36 ++++++++++++++++++++++++++++++++++++ 2 files changed, 38 insertions(+), 2 deletions(-) create mode 100644 protocols/unix.md 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..080dbc7 --- /dev/null +++ b/protocols/unix.md @@ -0,0 +1,36 @@ +# `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/file.socket` | +| /dir/file.socket | `/unix/dir%2Ffile.socket` | +| /dir/file.socket/p2p/12D... | `/unix/dir%2Ffile.socket/p2p/12D...` | +| /tmp/foo/../bar | `/unix/tmp%2Ffoo%2F..%2Fbar` | +| /%2F | `/unix/%252F` | +| a%20space | `/unix/a%2520space` | +| a%2Fslash | `/unix/a%252Fslash` | + +## 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 leading `/` character of the path can be omitted, unless it is the only +character in the path, in which case it must be escaped as normal. From df9f077a8aca384efa7b9c3d1bf3c4888070f9c2 Mon Sep 17 00:00:00 2001 From: Alex Potsides Date: Tue, 29 Oct 2024 17:09:23 +0000 Subject: [PATCH 2/3] chore: add slash --- protocols/unix.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/protocols/unix.md b/protocols/unix.md index 080dbc7..5225e2d 100644 --- a/protocols/unix.md +++ b/protocols/unix.md @@ -23,8 +23,8 @@ Multiaddr string form. | /dir/file.socket/p2p/12D... | `/unix/dir%2Ffile.socket/p2p/12D...` | | /tmp/foo/../bar | `/unix/tmp%2Ffoo%2F..%2Fbar` | | /%2F | `/unix/%252F` | -| a%20space | `/unix/a%2520space` | -| a%2Fslash | `/unix/a%252Fslash` | +| /a%20space | `/unix/a%2520space` | +| /a%2Fslash | `/unix/a%252Fslash` | ## Usage From 4ea4411a85586445144a504700339a93b6f072b4 Mon Sep 17 00:00:00 2001 From: achingbrain Date: Thu, 12 Jun 2025 14:31:44 +0300 Subject: [PATCH 3/3] docs: just encode the path as-is --- protocols/unix.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/protocols/unix.md b/protocols/unix.md index 5225e2d..a37d18b 100644 --- a/protocols/unix.md +++ b/protocols/unix.md @@ -18,13 +18,14 @@ Multiaddr string form. | Unix Path | Multiaddr string form | | --------------------------- | --------------------------------------- | | / | `/unix/%2F` | -| /file.socket | `/unix/file.socket` | -| /dir/file.socket | `/unix/dir%2Ffile.socket` | -| /dir/file.socket/p2p/12D... | `/unix/dir%2Ffile.socket/p2p/12D...` | -| /tmp/foo/../bar | `/unix/tmp%2Ffoo%2F..%2Fbar` | +| /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/a%2520space` | -| /a%2Fslash | `/unix/a%252Fslash` | +| /a%20space | `/unix/%2Fa%2520space` | +| /a%2Fslash | `/unix/%2Fa%252Fslash` | +| socket | `/unix/socket` | ## Usage @@ -32,5 +33,5 @@ Multiaddr string form. appear anywhere, for example in the case where we route through some sort of proxy server or SSH tunnel. -The leading `/` character of the path can be omitted, unless it is the only -character in the path, in which case it must be escaped as normal. +The absence of a `/` character at the start of the decoded address indicates a +relative path, otherwise the path is absolute.