Skip to content

Commit 8f9c2ee

Browse files
authored
Define /unix (#174)
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 percent encoding for the segment, the same as the `/http-path` component.
1 parent 9b7b3fa commit 8f9c2ee

File tree

2 files changed

+39
-2
lines changed

2 files changed

+39
-2
lines changed

protocols.csv

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ code, size, name, comment
1313
132, 16, sctp,
1414
301, 0, udt,
1515
302, 0, utp,
16-
400, V, unix,
16+
400, V, unix, Percent-encoded path to a Unix domain socket
1717
421, V, p2p, preferred over /ipfs
1818
421, V, ipfs, backwards compatibility; equivalent to /p2p
1919
444, 96, onion,
@@ -39,4 +39,4 @@ code, size, name, comment
3939
280, 0, webrtc-direct, ICE-lite webrtc transport with SDP munging during connection establishment and without use of a STUN server
4040
281, 0, webrtc, webrtc transport where connection establishment is according to w3c spec
4141
290, 0, p2p-circuit,
42-
777, V, memory, in memory transport for self-dialing and testing; arbitrary
42+
777, V, memory, in memory transport for self-dialing and testing; arbitrary

protocols/unix.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# `unix`
2+
3+
This protocol encodes a Unix domain socket path to a resource. In the string
4+
representation, the path is encoded in a way consistent with a single URI Path
5+
segment per [RFC 3986 Section 3.3](https://datatracker.ietf.org/doc/html/rfc3986#autoid-23).
6+
7+
Specifically following the grammar of a single `segment-nz`. In the binary
8+
representation, no encoding is needed as the value is length prefixed.
9+
10+
When comparing multiaddrs, implementations should compare their binary
11+
representation to avoid ambiguities over which characters were escaped.
12+
13+
## Examples
14+
15+
The following is a table of examples converting some common Unix paths to their
16+
Multiaddr string form.
17+
18+
| Unix Path | Multiaddr string form |
19+
| --------------------------- | --------------------------------------- |
20+
| / | `/unix/%2F` |
21+
| /file.socket | `/unix/%2Ffile.socket` |
22+
| /dir/file.socket | `/unix/%2Fdir%2Ffile.socket` |
23+
| /dir/file.socket/p2p/12D... | `/unix/%2Fdir%2Ffile.socket/p2p/12D...` |
24+
| /tmp/foo/../bar | `/unix/%2Ftmp%2Ffoo%2F..%2Fbar` |
25+
| /%2F | `/unix/%252F` |
26+
| /a%20space | `/unix/%2Fa%2520space` |
27+
| /a%2Fslash | `/unix/%2Fa%252Fslash` |
28+
| socket | `/unix/socket` |
29+
30+
## Usage
31+
32+
`/unix` would typically be found at the start of a multiaddr, however it may
33+
appear anywhere, for example in the case where we route through some sort of
34+
proxy server or SSH tunnel.
35+
36+
The absence of a `/` character at the start of the decoded address indicates a
37+
relative path, otherwise the path is absolute.

0 commit comments

Comments
 (0)