Skip to content
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

Jump to bottom

Define /http-path #164

Merged
merged 7 commits into from
Jun 5, 2024
Merged

Define /http-path #164

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
a20267c
Define httppath component
MarcoPolo Aug 24, 2023
d57b45d
Expand reserved character set
MarcoPolo Aug 25, 2023
7756753
Update protocols/httppath.md
MarcoPolo Aug 25, 2023
9d3dd76
Rephrase and use examples
MarcoPolo Aug 26, 2023
1adaf28
Rename to http-path
MarcoPolo Apr 15, 2024
94b743a
Update protocols.csv
MarcoPolo May 30, 2024
4eee81a
Rename file
MarcoPolo Jun 5, 2024
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
1 change: 1 addition & 0 deletions protocols.csv
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
37 changes: 37 additions & 0 deletions protocols/http-path.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
```