From 338a31215c9f630526a058e3d5471d407816dc4e Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Wed, 31 May 2023 11:34:37 -0700 Subject: [PATCH 01/15] Add document about /http --- http/transport-component.md | 121 ++++++++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 http/transport-component.md diff --git a/http/transport-component.md b/http/transport-component.md new file mode 100644 index 000000000..b3f854114 --- /dev/null +++ b/http/transport-component.md @@ -0,0 +1,121 @@ +# 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] + +[@marcopolo]: https://github.com/marcopolo +[@mxinden]: https://github.com/mxinden +[@marten-seemann]: https://github.com/marten-seemann + +## Table of Contents +- [Context](#context) +- [What is an HTTP transport](#what-is-an-http-transport) +- [Multiaddr representation](#multiaddr-representation) +- [HTTP Paths](#http-paths) + + +## 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 that is at least HTTP/1.1. Currently that means HTTP/1.1, HTTP/2, and +HTTP/3. 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. The client will negotiate (or [learn +about](https://www.rfc-editor.org/rfc/rfc9114.html#section-3.1.1)) the specific HTTP version to use when communicating +with the HTTP server. + +For this opaque case, we use the `/http` component at the end of the multidadr. +If a node wants to advertise specific HTTP versions it may advertise a +`/http-1.1`, `/http-2`, or `/h3` instead. Although these components are not +currently [registered](https://github.com/multiformats/multiaddr), this document +claims their use. + + +## 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](https://github.com/multiformats/multiaddr#interpreting-multiaddrs)). + +The following are examples of multiaddrs for HTTP transport capable nodes: + +* `/dns/example.com/tls/http` +* `/dns/example.com/https` +* `/ip4/1.2.3.4/tcp/443/https` +* `/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/tls/http` // We can infer this is an HTTP/3 address +* `/ip4/1.2.3.4/udp/50781/quic-v1/http` // Not necessary to specify that the + HTTP endpoint is on top of QUIC, but it is okay if it does. + + +## HTTP Paths + +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 user protocol level. In the HTTP semantics. You can +use these semantics on any transport including, but not limited to, the HTTP +transport. + +For example, say you want to fetch a file using the [IPFS trustless +gateway](https://docs.ipfs.tech/reference/http/gateway/). It may be tempting to +use the following URL to reference a file: + +``` +/ip4/127.0.0.1/tcp/8080/http/httppath/ipfs%2fbafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi +``` + +But `/http` is a transport and it doesn't accept any parameters. It would be the +same as if we used the following multiaddr: + +``` +/ip4/127.0.0.1/udp/1234/quic-v1/httppath/ipfs%2fbafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi +``` + +What does `httppath/` mean here? Does it mean make a `GET` request? How would +you make a `POST` request? What about headers? Does it leave that unspecified +and ask the user to specify that as they would with curl? + +We could be more precise here and specify a `/GET` component to the multiaddr +that accepts parameters and describes what user protocol we are trying to do +here. + +``` +/ip4/127.0.0.1/udp/1234/http/GET/httppath/ipfs%2fbafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi + +or + +/ip4/127.0.0.1/udp/1234/quic-v1/GET/httppath/ipfs%2fbafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi +``` + +This is fine since `httppath` passes the path parameter to `GET` which parses +the rest of the multiaddr as the address of the node to connect to and make an +HTTP GET request which can happen over an HTTP transport or any other transport +(e.g. QUIC streams or yamux+noise+tcp). + +You may end up with a lot of duplicate information if you have many multiaddrs +since each one will have the same suffix of `GET/httppath/...`. Therefore this +isn't recommended, but may be useful if you just need one multiaddr +with some extra protocol information. + +To summarize, HTTP Paths don't make sense appended to an `/http` component, but may make sense +appended to some other custom user protocol component. From c01c0372a487c2319cd48c06dd978615b679c14f Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Thu, 1 Jun 2023 09:40:19 -0700 Subject: [PATCH 02/15] Update http/transport-component.md Co-authored-by: Steve Loeppky --- http/transport-component.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/http/transport-component.md b/http/transport-component.md index b3f854114..053bfde8d 100644 --- a/http/transport-component.md +++ b/http/transport-component.md @@ -76,7 +76,7 @@ The HTTP Path exists in the user protocol level. In the HTTP semantics. You can use these semantics on any transport including, but not limited to, the HTTP transport. -For example, say you want to fetch a file using the [IPFS trustless +For example, say you want to fetch a file using the [IPFS trustless HTTP gateway](https://docs.ipfs.tech/reference/http/gateway/). It may be tempting to use the following URL to reference a file: From 5a8401f11562532b1794fea665ce22c530e39543 Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Thu, 1 Jun 2023 10:06:34 -0700 Subject: [PATCH 03/15] Update http/transport-component.md Co-authored-by: Marcin Rataj --- http/transport-component.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/http/transport-component.md b/http/transport-component.md index 053bfde8d..00a21e3ff 100644 --- a/http/transport-component.md +++ b/http/transport-component.md @@ -72,7 +72,7 @@ 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 user protocol level. In the HTTP semantics. You can +The HTTP Path exists in the user protocol 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 transport. From 29428b2412bc47d78054522edc2803101a7adef7 Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Thu, 1 Jun 2023 10:07:08 -0700 Subject: [PATCH 04/15] Update http/transport-component.md Co-authored-by: Marcin Rataj --- http/transport-component.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/http/transport-component.md b/http/transport-component.md index 00a21e3ff..56012f21a 100644 --- a/http/transport-component.md +++ b/http/transport-component.md @@ -77,7 +77,7 @@ use these semantics on any transport including, but not limited to, the HTTP transport. For example, say you want to fetch a file using the [IPFS trustless HTTP -gateway](https://docs.ipfs.tech/reference/http/gateway/). It may be tempting to +gateway](https://specs.ipfs.tech/http-gateways/trustless-gateway/). It may be tempting to use the following URL to reference a file: ``` From b86967963317a94893d60f639611b59ebdcbd54e Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Thu, 1 Jun 2023 10:07:34 -0700 Subject: [PATCH 05/15] Update http/transport-component.md Co-authored-by: Marcin Rataj --- http/transport-component.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/http/transport-component.md b/http/transport-component.md index 56012f21a..b35df0dd0 100644 --- a/http/transport-component.md +++ b/http/transport-component.md @@ -78,7 +78,7 @@ transport. For example, say you want to fetch a file using the [IPFS trustless HTTP gateway](https://specs.ipfs.tech/http-gateways/trustless-gateway/). It may be tempting to -use the following URL to reference a file: +use the following multiaddr to reference a file: ``` /ip4/127.0.0.1/tcp/8080/http/httppath/ipfs%2fbafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi From c35dd6930b1358e3e3c1caceb4f203b14ab82f10 Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Thu, 1 Jun 2023 10:08:38 -0700 Subject: [PATCH 06/15] Update http/transport-component.md Co-authored-by: Marcin Rataj --- http/transport-component.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/http/transport-component.md b/http/transport-component.md index b35df0dd0..b6fbebbbc 100644 --- a/http/transport-component.md +++ b/http/transport-component.md @@ -74,7 +74,7 @@ capable of an HTTP transport. The HTTP Path exists in the user protocol 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 -transport. +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). For example, say you want to fetch a file using the [IPFS trustless HTTP gateway](https://specs.ipfs.tech/http-gateways/trustless-gateway/). It may be tempting to From 5c515375afa42a38a824e5ab92e802874c0ce9d4 Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Thu, 1 Jun 2023 10:30:50 -0700 Subject: [PATCH 07/15] Remove specific http versions section --- http/transport-component.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/http/transport-component.md b/http/transport-component.md index b6fbebbbc..835a5dbb2 100644 --- a/http/transport-component.md +++ b/http/transport-component.md @@ -40,11 +40,9 @@ about](https://www.rfc-editor.org/rfc/rfc9114.html#section-3.1.1)) the specific with the HTTP server. For this opaque case, we use the `/http` component at the end of the multidadr. -If a node wants to advertise specific HTTP versions it may advertise a -`/http-1.1`, `/http-2`, or `/h3` instead. Although these components are not -currently [registered](https://github.com/multiformats/multiaddr), this document -claims their use. - +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 @@ -60,9 +58,7 @@ The following are examples of multiaddrs for HTTP transport capable nodes: * `/ip4/1.2.3.4/tcp/443/https` * `/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/tls/http` // We can infer this is an HTTP/3 address -* `/ip4/1.2.3.4/udp/50781/quic-v1/http` // Not necessary to specify that the - HTTP endpoint is on top of QUIC, but it is okay if it does. +* `/ip4/1.2.3.4/udp/50781/tls/http` ## HTTP Paths From 275c918ed49fa6a08a0f95d8d74cc2ab69834669 Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Thu, 1 Jun 2023 11:04:26 -0700 Subject: [PATCH 08/15] Remove HTTP/1.1 requirement --- http/transport-component.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/http/transport-component.md b/http/transport-component.md index 835a5dbb2..eefe20c49 100644 --- a/http/transport-component.md +++ b/http/transport-component.md @@ -31,8 +31,7 @@ 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 that is at least HTTP/1.1. Currently that means HTTP/1.1, HTTP/2, and -HTTP/3. Intuitively if you can `curl` it with HTTP, then it speaks HTTP. +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. The client will negotiate (or [learn From 4576c35f0b8bd6425e518f3ffc69af6143cef293 Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Thu, 1 Jun 2023 11:06:27 -0700 Subject: [PATCH 09/15] Remove /https usage --- http/transport-component.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/http/transport-component.md b/http/transport-component.md index eefe20c49..8f844c91d 100644 --- a/http/transport-component.md +++ b/http/transport-component.md @@ -53,8 +53,6 @@ left](https://github.com/multiformats/multiaddr#interpreting-multiaddrs)). The following are examples of multiaddrs for HTTP transport capable nodes: * `/dns/example.com/tls/http` -* `/dns/example.com/https` -* `/ip4/1.2.3.4/tcp/443/https` * `/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/tls/http` From 8fa73c61845f1b1cca444a2adc01d773877e410f Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Thu, 1 Jun 2023 11:11:50 -0700 Subject: [PATCH 10/15] reword section on HTTP version --- http/transport-component.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/http/transport-component.md b/http/transport-component.md index 8f844c91d..4d8a932de 100644 --- a/http/transport-component.md +++ b/http/transport-component.md @@ -34,14 +34,11 @@ 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. The client will negotiate (or [learn -about](https://www.rfc-editor.org/rfc/rfc9114.html#section-3.1.1)) the specific HTTP version to use when communicating -with the HTTP server. - -For this opaque case, we use the `/http` component at the end of the multidadr. -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. +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 From 1842138a88acd47e7f77e9abed8ecfa16fea2fb0 Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Thu, 1 Jun 2023 11:39:40 -0700 Subject: [PATCH 11/15] Reword http paths section --- http/transport-component.md | 58 +++++++++++++++++++++---------------- 1 file changed, 33 insertions(+), 25 deletions(-) diff --git a/http/transport-component.md b/http/transport-component.md index 4d8a932de..e582c49b9 100644 --- a/http/transport-component.md +++ b/http/transport-component.md @@ -66,46 +66,54 @@ The HTTP Path exists in the user protocol level. HTTP Semantics are transport-ag 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). -For example, say you want to fetch a file using the [IPFS trustless HTTP -gateway](https://specs.ipfs.tech/http-gateways/trustless-gateway/). It may be tempting to -use the following multiaddr to reference a file: +For example, say you want to signal that a node supports the [IPFS trustless +HTTP gateway] protocol. It may be tempting to use the following multiaddr to +signal that: ``` -/ip4/127.0.0.1/tcp/8080/http/httppath/ipfs%2fbafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi +/ip4/127.0.0.1/tcp/8080/http/httppath/ipfs ``` But `/http` is a transport and it doesn't accept any parameters. It would be the same as if we used the following multiaddr: ``` -/ip4/127.0.0.1/udp/1234/quic-v1/httppath/ipfs%2fbafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi +/ip4/127.0.0.1/udp/1234/quic-v1/httppath/ipfs ``` -What does `httppath/` mean here? Does it mean make a `GET` request? How would -you make a `POST` request? What about headers? Does it leave that unspecified -and ask the user to specify that as they would with curl? +What does `httppath/` mean here? `/quic-v1` is a transport and doesn't accept +parameters. Who handles the input from `/httppath`? -We could be more precise here and specify a `/GET` component to the multiaddr -that accepts parameters and describes what user protocol we are trying to do -here. +What we're really trying to do here is to highlight that the node that can be +found at those Multiaddrs supports the [IPFS trustless HTTP gateway] protocol. +That can and should be done some other way such as +[identify](https://github.com/libp2p/specs/tree/master/identify) or soon the +[`.well-known/libp2p`](https://github.com/libp2p/specs/pull/529) HTTP endpoint +or some other custom application logic. -``` -/ip4/127.0.0.1/udp/1234/http/GET/httppath/ipfs%2fbafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi +If having this information on the multiaddr is desired and you are willing to +make the tradeoff of potentially multiplying the number of multiaddrs you have +by the number of protocols you want to signal, you could use a multicodec from +the [private use +area](https://github.com/multiformats/multicodec#private-use-area) and append +this to your multiaddr. The result would be something like: -or +``` +myProtocol = 0x300000 -/ip4/127.0.0.1/udp/1234/quic-v1/GET/httppath/ipfs%2fbafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi +/ip4/127.0.0.1/tcp/8080/http/myProtocol +/ip4/127.0.0.1/udp/1234/quic-v1/myProtocol ``` -This is fine since `httppath` passes the path parameter to `GET` which parses -the rest of the multiaddr as the address of the node to connect to and make an -HTTP GET request which can happen over an HTTP transport or any other transport -(e.g. QUIC streams or yamux+noise+tcp). +Note that the problem appears when we want to add another protocol here: +``` +myProtocol = 0x300000 +anotherProtocol = 0x300001 -You may end up with a lot of duplicate information if you have many multiaddrs -since each one will have the same suffix of `GET/httppath/...`. Therefore this -isn't recommended, but may be useful if you just need one multiaddr -with some extra protocol information. +/ip4/127.0.0.1/tcp/8080/http/myProtocol +/ip4/127.0.0.1/udp/1234/quic-v1/myProtocol +/ip4/127.0.0.1/tcp/8080/http/anotherProtocol +/ip4/127.0.0.1/udp/1234/quic-v1/anotherProtocol +``` -To summarize, HTTP Paths don't make sense appended to an `/http` component, but may make sense -appended to some other custom user protocol component. +[IPFS trustless HTTP gateway]: (https://specs.ipfs.tech/http-gateways/trustless-gateway/) From 56e66181b7e18aab3b5dd62eb4265b96f049b0fe Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Tue, 13 Jun 2023 14:30:13 -0700 Subject: [PATCH 12/15] Standardize on `quic-v1/http` --- http/transport-component.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/http/transport-component.md b/http/transport-component.md index e582c49b9..4ebd7b375 100644 --- a/http/transport-component.md +++ b/http/transport-component.md @@ -52,7 +52,7 @@ 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/tls/http` +* `/ip4/1.2.3.4/udp/50781/quic-v1/http` ## HTTP Paths From ec7e4396998498642b4a95fc2819cdcb17384c36 Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Tue, 13 Jun 2023 17:21:19 -0700 Subject: [PATCH 13/15] Rework HTTP path section and add a recommendation --- http/transport-component.md | 90 ++++++++++++++----------------------- 1 file changed, 33 insertions(+), 57 deletions(-) diff --git a/http/transport-component.md b/http/transport-component.md index 4ebd7b375..127d15b06 100644 --- a/http/transport-component.md +++ b/http/transport-component.md @@ -16,7 +16,8 @@ Interest Group: [@marcopolo], [@mxinden], [@marten-seemann] - [Context](#context) - [What is an HTTP transport](#what-is-an-http-transport) - [Multiaddr representation](#multiaddr-representation) -- [HTTP Paths](#http-paths) +- [HTTP Paths (and other HTTP Semantics)](#http-paths-and-other-http-semantics) + - [Recommendation on including HTTP semantics in multiaddrs](#recommendation-on-including-http-semantics-in-multiaddrs) ## Context @@ -55,65 +56,40 @@ The following are examples of multiaddrs for HTTP transport capable nodes: * `/ip4/1.2.3.4/udp/50781/quic-v1/http` -## HTTP Paths +## 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 user protocol 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). - -For example, say you want to signal that a node supports the [IPFS trustless -HTTP gateway] protocol. It may be tempting to use the following multiaddr to -signal that: - -``` -/ip4/127.0.0.1/tcp/8080/http/httppath/ipfs -``` - -But `/http` is a transport and it doesn't accept any parameters. It would be the -same as if we used the following multiaddr: - -``` -/ip4/127.0.0.1/udp/1234/quic-v1/httppath/ipfs -``` - -What does `httppath/` mean here? `/quic-v1` is a transport and doesn't accept -parameters. Who handles the input from `/httppath`? - -What we're really trying to do here is to highlight that the node that can be -found at those Multiaddrs supports the [IPFS trustless HTTP gateway] protocol. -That can and should be done some other way such as -[identify](https://github.com/libp2p/specs/tree/master/identify) or soon the -[`.well-known/libp2p`](https://github.com/libp2p/specs/pull/529) HTTP endpoint -or some other custom application logic. - -If having this information on the multiaddr is desired and you are willing to -make the tradeoff of potentially multiplying the number of multiaddrs you have -by the number of protocols you want to signal, you could use a multicodec from -the [private use -area](https://github.com/multiformats/multicodec#private-use-area) and append -this to your multiaddr. The result would be something like: - -``` -myProtocol = 0x300000 - -/ip4/127.0.0.1/tcp/8080/http/myProtocol -/ip4/127.0.0.1/udp/1234/quic-v1/myProtocol -``` - -Note that the problem appears when we want to add another protocol here: -``` -myProtocol = 0x300000 -anotherProtocol = 0x300001 - -/ip4/127.0.0.1/tcp/8080/http/myProtocol -/ip4/127.0.0.1/udp/1234/quic-v1/myProtocol -/ip4/127.0.0.1/tcp/8080/http/anotherProtocol -/ip4/127.0.0.1/udp/1234/quic-v1/anotherProtocol -``` - -[IPFS trustless HTTP gateway]: (https://specs.ipfs.tech/http-gateways/trustless-gateway/) +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 + +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](https://github.com/multiformats/multicodec#private-use-area) for your +application. Then apply whatever application parameters to the right of your new +multicodec and transport information to the left. E.g. +`/myapp/` +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. From e71d7c5222ad0b7da9970888fbfa169e223afa05 Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Fri, 16 Jun 2023 12:42:51 -0700 Subject: [PATCH 14/15] Add note about ALPN in quic --- http/transport-component.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/http/transport-component.md b/http/transport-component.md index 127d15b06..5fe2e18df 100644 --- a/http/transport-component.md +++ b/http/transport-component.md @@ -55,6 +55,9 @@ The following are examples of multiaddrs for HTTP transport capable nodes: * `/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 any other QUIC version) +implementations MUST use the correct ALPN (e.g. `h3`) and not `libp2p` when +using the HTTP transport. ## HTTP Paths (and other HTTP Semantics) From b15f82e51504363f8b5e19bdeb61edec2ff516e3 Mon Sep 17 00:00:00 2001 From: Marco Munizaga Date: Mon, 10 Jul 2023 10:40:42 -0700 Subject: [PATCH 15/15] Update note --- http/transport-component.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/http/transport-component.md b/http/transport-component.md index 5fe2e18df..d384353de 100644 --- a/http/transport-component.md +++ b/http/transport-component.md @@ -55,9 +55,9 @@ The following are examples of multiaddrs for HTTP transport capable nodes: * `/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 any other QUIC version) -implementations MUST use the correct ALPN (e.g. `h3`) and not `libp2p` when -using the HTTP transport. +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)