Support HTTP/2

[Nevon]

Before considering #468, which is a whole other kettle of fish, it would be great for Mappersmith to have a support story for HTTP/2.

But just providing an HTTP2 gateway might not be too useful to people, as they may not know whether the server supports HTTP/1.1 or HTTP/2 and expect both to be callable with "http". Instead I would suggest that the provided gateways, when possible, use HTTP/2 when available and fall back to HTTP/1.1 otherwise. Naturally it should be possible for a user to specify only using one protocol or the other, and simply failing if the server doesn't support that protocol, same as today.

Opportunistic HTTP/2 support

In order for a client and server to agree on a protocol version to use to communicate. There are basically two ways this can happen:

1. When the server and client use TLS (i.e. they intend to use HTTPS) the protocol version is decided using Application Layer Protocol Negotiation (ALPN) where the client sends the protocol it supports in a TLS extension of the ClientHello message and the server responds with the protocol to use in the ServerHello. This is by far the most well-supported mechanism.
2. If the server and client do not use TLS, the client can include an Upgrade header in a regular HTTP request, and if the server responds with a 101 Switching status, the connection will use http2 from that point onwards. I don't know that this method is supported by anything at all.

Current state

• Fetch - I believe, but haven't verified this, that the browser implementation of fetch will use http/2 when available automatically. That being said, I haven't been able to find an authoritative source, and support may vary across browsers. The fetch implementation in node does not support HTTP/2 by default, but it is possible to enable, and I believe that in that case it will do ALPN to pick the protocol version to use.
• HTTP - Does not support HTTP/2. There is an http2 module in node, but there's nothing that will do ALPN and pick the appropriate http module for you.
• XHR - No clue but I highly doubt it supports HTTP/2.

Open questions

• I don't know how tied to HTTP/1.1 the current gateway interface is, and whether it makes sense to make the existing HTTP gateway automatically switch between the different protocols, or if this should be a new HTTP2 gateway with the ability to fall back to HTTP/1.1.
• HTTP/2 very much favors keeping long lived connections that are reused across man requests. I haven't looked into if Mappersmith can just delegate this responsibility down to the module implementing the protocol, or if there's any changes necessary within the gateways themselves to take advantage of this.

[klippx]

Hi @Nevon,

ALPN vs Upgrade header

I think the approach seems sound, this does not sound like a Gateway but rather something that affects both Fetch and HTTP gateway (I agree we can disregard XHR). However, regardless if ALPN is more common than the upgrade header or not, I actually think that it might be used quite a lot; Many HTTP/2 implementations support h2c (HTTP/2 over cleartext), including:

• Node.js http2 module
• nginx with http2 directive
• Various proxy servers and CDNs

But we can always add more things later. But I do not think we shouldn't dismiss this upgrade header.

Successful example of HTTP/2 high level library: got

I think got (mappersmith competitor, also a high level library) made http/2 work by using the native http2 module directly or http2-wrapper which has a similar API. Which means they are either A) using a dependency or B) forcing you to use node v24 but otherwise providing an abstraction similar to mappersmith on top of HTTP/2.

Mappersmith philosophies

1. Mappersmith is isomorphic; it runs in Node and Browser.
2. Mappersmith is zero dependency

This means it supports most runtimes (Node versions or browsers) by avoiding using anything that is tied to a certain Node version or browser runtime (not even Promise, right) which means adding a dependency or doing something runtime (Node) specific can be violation of these principles.

Some options:

• There is fetch-h2 by our friend @grantila https://github.com/grantila/fetch-h2 - Node and browser? IDK.
• http2-wrapper https://github.com/szmarczak/http2-wrapper - Node and browser? IDK.
• Node native http2 API module https://nodejs.org/api/http2.html - Node only, and only since v24

Gateways

Since mappersmith is a high level library, with zero dependencies, we outsource the fetch implementation to libraries such as node-fetch (which doesn't support HTTP/2) or undici (which does not support HTTP/2 either). And here we fall on our own spear, perhaps. If the underlying implementation doesn't support it then it might make things more challenging to provide a high level API abstraction on top of it.

One concern I have is that mappersmith is quite heavily oriented toward object oriented thinking about "requests" and "responses", which might go against the design principle of HTTP/2 streams:

Example:

// HTTP/1.1 request/response pattern
const response = await fetch(url);
// vs HTTP/2 streams are fundamentally different
const stream = session.request({':method': 'GET'});

But as long as we can successfully abstract away those streams and provide the consistent requests/responses, we should be fine.

Your open questions

I don't know how tied to HTTP/1.1 the current gateway interface is, and whether it makes sense to make the existing HTTP gateway automatically switch between the different protocols, or if this should be a new HTTP2 gateway with the ability to fall back to HTTP/1.1.

I think Gateway parts are not too tied to HTTP/1, it just provides some HTTP verbs, and then the complexity of implementing goes in each Gateway instance. I would be more concerned about ClientBuilder which instantiates the gateway, and manages the middleware stack. But I guess as long as the HTTP/2 changes to the Gateways abstract away the streams and calls dispatchResponse with the final response and managing the pool and streams we should be fine there as well!

HTTP/2 very much favors keeping long lived connections that are reused across man requests. I haven't looked into if Mappersmith can just delegate this responsibility down to the module implementing the protocol, or if there's any changes necessary within the gateways themselves to take advantage of this.

I wouldn't know, "it depends", right... For HTTP Gateway it might be one thing, but since Fetch is pluggable, it might be another. IDK if we should manage the connection pool or not in Gateway, I think it could make the most sense, and possibly be more readable or even sharable in the Gateway superclass if we did that.

Thoughts going forward

I think we should leave the original Fetch and HTTP and even Gateway alone if we want to work on this.

I propose that we create a new HTTP2Gateway class that to be used, and that we can enable it with some experimentalHTTP2 config in the global configs object.

That way we can have the liberty of doing something very specific for a certain runtime and even runtime version. We can throw if trying to forge a client with experimentalHTTP2: true in the browser or in node v22 if we decide to lock in on node v24 for instance. I am very open to that!