From a20267c1a107b5665fa34aae1d7044659ce218d3 Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Thu, 24 Aug 2023 16:09:56 -0700 Subject: [PATCH 1/7] Define httppath component --- protocols.csv | 1 + protocols/httppath.md | 40 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 41 insertions(+) create mode 100644 protocols/httppath.md diff --git a/protocols.csv b/protocols.csv index 2417943..beecca9 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, httppath, 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/httppath.md b/protocols/httppath.md new file mode 100644 index 0000000..832a135 --- /dev/null +++ b/protocols/httppath.md @@ -0,0 +1,40 @@ +# `httppath` + +This protocol encodes an HTTP Path to a resource. In the string representation, +characters in the reserved set are percent-encoded ( "/" becomes "%2F"). +Percent-encoding itself is defined by [RFC 3986 Section +2.1](https://datatracker.ietf.org/doc/html/rfc3986#section-2.1). In the binary representation, no escaping is needed as the value is length prefixed. + +To ease implementation and benefit from reusing existing percent-encoding logic +present in many environments (Go's +[url.PathEscape](https://pkg.go.dev/net/url@go1.21.0#PathEscape); JS's +[encodeURIComponent](http://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent); +and Rust's [many +crates](https://crates.io/search?q=percent%20encode&sort=downloads)), it is +acceptable to encode more characters than the reserved set. While it's not +necessary to encode a space " " as %20, it's is acceptable to do so. + +When comparing multiaddrs, implementations should compare their binary +representation to avoid ambiguities over which characters were escaped. + +## Reserved Characters + +| Character | Reason | +| --------- | ----------------------------- | +| / | Multiaddr component separator | +| % | Percent encoding indicator | +| ? | Marks the end of an HTTP path | + +## Usage + +`/httppath` 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.../httppath/.well-known%2Flibp2p +``` + +The `/httppath` 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: + +``` +/ip4/1.2.3.4/tcp/443/tls/http/p2p/12D.../httppath/.well-known%2Flibp2p +``` From d57b45d7295f83b2df83398230cd33e5005eb891 Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Thu, 24 Aug 2023 17:04:43 -0700 Subject: [PATCH 2/7] Expand reserved character set --- protocols/httppath.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/protocols/httppath.md b/protocols/httppath.md index 832a135..183b605 100644 --- a/protocols/httppath.md +++ b/protocols/httppath.md @@ -19,11 +19,14 @@ representation to avoid ambiguities over which characters were escaped. ## Reserved Characters -| Character | Reason | -| --------- | ----------------------------- | -| / | Multiaddr component separator | -| % | Percent encoding indicator | -| ? | Marks the end of an HTTP path | +| Character | Reason | +| --------- | ---------------------------------------------------------------------------------------------------- | +| `/` | Multiaddr component separator | +| `%` | Percent encoding indicator | +| `?` | Marks the end of an HTTP path | +| `#` | Reserved gen-delim character by [rfc3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2) | +| `[` | Reserved gen-delim character by [rfc3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2) | +| `]` | Reserved gen-delim character by [rfc3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2) | ## Usage From 7756753e30e3bad2e6c841d01535898ffa966f9b Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Fri, 25 Aug 2023 10:37:04 -0700 Subject: [PATCH 3/7] Update protocols/httppath.md Co-authored-by: Thomas Eizinger --- protocols/httppath.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/protocols/httppath.md b/protocols/httppath.md index 183b605..0acae33 100644 --- a/protocols/httppath.md +++ b/protocols/httppath.md @@ -39,5 +39,5 @@ representation to avoid ambiguities over which characters were escaped. The `/httppath` 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: ``` -/ip4/1.2.3.4/tcp/443/tls/http/p2p/12D.../httppath/.well-known%2Flibp2p +/p2p/12D.../httppath/.well-known%2Flibp2p ``` From 9d3dd76a0b08381c9c3ca41ee6fdf34478e81673 Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Fri, 25 Aug 2023 17:01:42 -0700 Subject: [PATCH 4/7] Rephrase and use examples --- protocols/httppath.md | 36 +++++++++++++++--------------------- 1 file changed, 15 insertions(+), 21 deletions(-) diff --git a/protocols/httppath.md b/protocols/httppath.md index 0acae33..1f04b1d 100644 --- a/protocols/httppath.md +++ b/protocols/httppath.md @@ -1,32 +1,26 @@ # `httppath` This protocol encodes an HTTP Path to a resource. In the string representation, -characters in the reserved set are percent-encoded ( "/" becomes "%2F"). -Percent-encoding itself is defined by [RFC 3986 Section -2.1](https://datatracker.ietf.org/doc/html/rfc3986#section-2.1). In the binary representation, no escaping is needed as the value is length prefixed. - -To ease implementation and benefit from reusing existing percent-encoding logic -present in many environments (Go's -[url.PathEscape](https://pkg.go.dev/net/url@go1.21.0#PathEscape); JS's -[encodeURIComponent](http://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent); -and Rust's [many -crates](https://crates.io/search?q=percent%20encode&sort=downloads)), it is -acceptable to encode more characters than the reserved set. While it's not -necessary to encode a space " " as %20, it's is acceptable to do so. +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. -## Reserved Characters +## Examples -| Character | Reason | -| --------- | ---------------------------------------------------------------------------------------------------- | -| `/` | Multiaddr component separator | -| `%` | Percent encoding indicator | -| `?` | Marks the end of an HTTP path | -| `#` | Reserved gen-delim character by [rfc3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2) | -| `[` | Reserved gen-delim character by [rfc3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2) | -| `]` | Reserved gen-delim character by [rfc3986](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2) | +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 | `/httppath/user` | +| /api/v0/login | `/httppath/api%2Fv0%2Flogin` | +| /tmp/foo/../bar | `/httppath/tmp%2Ffoo%2F..%2Fbar` | +| a%20space | `/httppath/a%2520space` | +| a%2Fslash | `/httppath/a%252Fslash` | ## Usage From 1adaf282b1df5a4c0eb76d8c7548db75c5763c10 Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Mon, 15 Apr 2024 09:38:04 -0700 Subject: [PATCH 5/7] Rename to http-path --- protocols/httppath.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/protocols/httppath.md b/protocols/httppath.md index 1f04b1d..433596b 100644 --- a/protocols/httppath.md +++ b/protocols/httppath.md @@ -1,4 +1,4 @@ -# `httppath` +# `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 @@ -13,25 +13,25 @@ representation to avoid ambiguities over which characters were escaped. 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 | `/httppath/user` | -| /api/v0/login | `/httppath/api%2Fv0%2Flogin` | -| /tmp/foo/../bar | `/httppath/tmp%2Ffoo%2F..%2Fbar` | -| a%20space | `/httppath/a%2520space` | -| a%2Fslash | `/httppath/a%252Fslash` | +| 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 -`/httppath` 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: +`/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.../httppath/.well-known%2Flibp2p +/ip4/1.2.3.4/tcp/443/tls/http/p2p/12D.../http-path/.well-known%2Flibp2p ``` -The `/httppath` 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: +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.../httppath/.well-known%2Flibp2p +/p2p/12D.../http-path/.well-known%2Flibp2p ``` From 94b743a0fd2e8937fac765455d257f684a917074 Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Thu, 30 May 2024 12:40:07 -0700 Subject: [PATCH 6/7] Update protocols.csv --- protocols.csv | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/protocols.csv b/protocols.csv index beecca9..5f5ea91 100644 --- a/protocols.csv +++ b/protocols.csv @@ -28,7 +28,7 @@ code, size, name, comment 465, 0, webtransport, 466, V, certhash, 480, 0, http, HyperText Transfer Protocol -481, V, httppath, Percent-encoded path to an HTTP resource +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 From 4eee81a400a7d4083b61e2f570cc86ac6c676f04 Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Tue, 4 Jun 2024 18:40:17 -0700 Subject: [PATCH 7/7] Rename file --- protocols/{httppath.md => http-path.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename protocols/{httppath.md => http-path.md} (100%) diff --git a/protocols/httppath.md b/protocols/http-path.md similarity index 100% rename from protocols/httppath.md rename to protocols/http-path.md