From 91b3f5c42ae7e760818ef31e0be93ac6f1fcffb2 Mon Sep 17 00:00:00 2001 From: achingbrain Date: Mon, 28 Oct 2024 19:12:08 +0000 Subject: [PATCH 1/2] 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/2] 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