Skip to content

Define /unix #174

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 16, 2025
Merged

Define /unix #174

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
91b3f5c
Define `/unix`
achingbrain Oct 28, 2024
df9f077
chore: add slash
achingbrain Oct 29, 2024
4ea4411
docs: just encode the path as-is
achingbrain Jun 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions protocols.csv
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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
36 changes: 36 additions & 0 deletions protocols/unix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.