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.

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

http: Removes section about http paths #636

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
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
39 changes: 12 additions & 27 deletions http/transport-component.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,13 @@ Interest Group: [@marcopolo], [@mxinden], [@marten-seemann]
[@marten-seemann]: https://github.com/marten-seemann

## Table of Contents <!-- omit in toc -->

- [Context](#context)
- [What is an HTTP transport](#what-is-an-http-transport)
- [Multiaddr representation](#multiaddr-representation)
- [HTTP Paths (and other HTTP Semantics)](#http-paths-and-other-http-semantics)
Copy link
Member

@achingbrain achingbrain Oct 8, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This TOC line needs removing since the corresponding section has been removed, or you can regenerate it using Markdown All in One or similar.

- [Recommendation on including HTTP semantics in multiaddrs](#recommendation-on-including-http-semantics-in-multiaddrs)


## Context

This document is only about advertising support for an HTTP transport. It
Expand All @@ -46,41 +46,26 @@ existing `http://` URL implementations do.
The multiaddr of a node with an HTTP transport ends with `/http` and is prefixed
by information that would let an HTTP client know how to reach the server
(remember that multiaddrs are [interpreted right to
left](https://github.com/multiformats/multiaddr#interpreting-multiaddrs)).
left](https://github.com/multiformats/multiaddr#interpreting-multiaddrs)).

The following are examples of multiaddrs for HTTP transport capable nodes:

* `/dns/example.com/tls/http`
* `/ip4/1.2.3.4/tcp/443/tls/http`
* `/ip6/2001:0db8:85a3:0000:0000:8a2e:0370:7334/tcp/443/tls/http`
* `/ip4/1.2.3.4/udp/50781/quic-v1/http`
- `/dns/example.com/tls/http`
- `/ip4/1.2.3.4/tcp/443/tls/http`
- `/ip6/2001:0db8:85a3:0000:0000:8a2e:0370:7334/tcp/443/tls/http`
- `/ip4/1.2.3.4/udp/50781/quic-v1/http`

Note: When we use `/quic-v1/http` or `/tcp/443/tls/http` (or any other
transport) implementations MUST use the correct HTTP ALPN (e.g. `h3` or `h2`
respectively) and not `libp2p` when using the HTTP transport.

## HTTP Paths (and other HTTP Semantics)

It may be tempting to add an HTTP path to end of the multiaddr to specify some
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess this means we do have paths in HTTP Multiaddrs now? Is it worth adding an example of their use?

information about a user protocol. However the `/http` component is not a user
protocol, and it doesn't accept any parameters. It only signals that a node is
capable of an HTTP transport.

The HTTP Path exists in the semantics level. HTTP Semantics are
transport-agnostic, and defined by [RFC
9110](https://httpwg.org/specs/rfc9110.html). You can use these semantics on any
transport including, but not limited to, the HTTP transports like
[HTTP/1.1](https://www.rfc-editor.org/info/rfc7235),
[HTTP/2](https://www.rfc-editor.org/info/rfc9113), or
[HTTP/3](https://www.rfc-editor.org/info/rfc9114).

### Recommendation on including HTTP semantics in multiaddrs
### Recommendation on including HTTP Request semantics in Multiaddrs

In general, it's better to keep the multiaddrs as a way of addressing an
In general, it's better to keep the Multiaddrs as a way of addressing an
endpoint and keep the semantics independent of any specific transport. This way
you can use the same semantics among many specific transports.

However, sometimes it's helpful to share a single multiaddr that contains some
However, sometimes it's helpful to share a single Multiaddr that contains some
extra application-level data (as opposed to transport data). The recommendation
is to use a new [multicodec in the private
range](https://github.com/multiformats/multicodec#private-use-area) for your
Expand All @@ -92,7 +77,7 @@ application has the flexibility to handle the parameters in any way it wants
(e.g. set HTTP headers, an HTTP path prefix, cookies, etc).

This is a bit cumbersome when you are trying to use multiple transports since
you may end up with many multiaddrs with different transports but the same
suffix. A potential solution here is to keep them separate. A list of multiaddrs
for the transports being used, and another multiaddr for the application-level
you may end up with many Multiaddrs with different transports but the same
suffix. A potential solution here is to keep them separate. A list of Multiaddrs
for the transports being used, and another Multiaddr for the application-level
data. This is one suggestion, and many other strategies would work as well.