Skip to content

Latest commit

 

History

History
98 lines (74 loc) · 4.5 KB

transport-component.md

File metadata and controls

98 lines (74 loc) · 4.5 KB

HTTP Transport Component

Lifecycle Stage Maturity Status Latest Revision
1A Working Draft Active r0, 2023-05-31

Authors: @marcopolo

Interest Group: @marcopolo, @mxinden, @marten-seemann

Table of Contents

Context

This document is only about advertising support for an HTTP transport. It doesn't make any assertions about how libp2p should interact with that transport. That will be defined in a future document.

This exists to clarify the role of the /http component in Multiaddrs early to avoid confusion and conflicting interpretations.

What is an HTTP transport

An HTTP transport is simply a node that can speak some standardized version of HTTP. Intuitively if you can curl it with HTTP, then it speaks HTTP.

Most environments will have a way to create an HTTP Client and Server, and the specific HTTP version used will be opaque. We use the /http component at the end of the multidadr to signal that this server supports an HTTP transport. The end user agent decides on HTTP version to use, based on the multiaddr prefix, application, server negotiation, and specific use case. This follows what existing http:// URL implementations do.

Multiaddr representation

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).

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

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 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. You can use these semantics on any transport including, but not limited to, the HTTP transports like HTTP/1.1, HTTP/2, or HTTP/3.

Recommendation on including HTTP semantics in multiaddrs

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 extra application-level data (as opposed to transport data). The recommendation is to use a new multicodec in the private range for your application. Then apply whatever application parameters to the right of your new multicodec and transport information to the left. E.g. <transport>/myapp/<parameters> or /ip4/127.0.0.1/tcp/8080/http/myapp/custom-prefix/foo%2fbar. Your 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 data. This is one suggestion, and many other strategies would work as well.