Merge pull request #164 from multiformats/marco/httppath

Define `/http-path`

Author: MarcoPolo

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

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
+```