diff --git a/protocols.csv b/protocols.csv index 2417943..5f5ea91 100644 --- a/protocols.csv +++ b/protocols.csv @@ -28,6 +28,7 @@ code, size, name, comment 465, 0, webtransport, 466, V, certhash, 480, 0, http, HyperText Transfer Protocol +481, V, http-path, Percent-encoded path to an HTTP resource 443, 0, https, Deprecated alias for /tls/http 477, 0, ws, WebSockets 478, 0, wss, Deprecated alias for /tls/ws diff --git a/protocols/http-path.md b/protocols/http-path.md new file mode 100644 index 0000000..433596b --- /dev/null +++ b/protocols/http-path.md @@ -0,0 +1,37 @@ +# `http-path` + +This protocol encodes an HTTP 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 HTTP paths to their Multiaddr string form. + +| HTTP Path | Multiaddr string form | +| --------------- | --------------------------------- | +| / | n/a. This is implied. | +| /user | `/http-path/user` | +| /api/v0/login | `/http-path/api%2Fv0%2Flogin` | +| /tmp/foo/../bar | `/http-path/tmp%2Ffoo%2F..%2Fbar` | +| a%20space | `/http-path/a%2520space` | +| a%2Fslash | `/http-path/a%252Fslash` | + +## Usage + +`/http-path` should be appended to the end of an existing multiaddr, including after the peer id component (p2p). As an example, here's a multiaddr referencing the `.well-known/libp2p` HTTP resource along with a way to reach that peer: + +``` +/ip4/1.2.3.4/tcp/443/tls/http/p2p/12D.../http-path/.well-known%2Flibp2p +``` + +The `/http-path` component can also be appended to just the `/p2p/...` component, and rely on a separate peer discovery mechanism to actually identify the peer's address: + +``` +/p2p/12D.../http-path/.well-known%2Flibp2p +```