proposal: x/net/http2/h2c: deprecate h2c package

[neild]

Proposal Details

The golang.org/x/net/h2c package provides support for serving unencrypted HTTP/2 connections.

This package was originally created because we were reluctant to support unencrypted HTTP/2 in the standard library, or even in the golang.org/x/net/http2 package. See #14141 for some background.

Go 1.24 includes support for unencrypted HTTP/2 client and server connections. Setting Server.Protocols to a value which includes the UnencryptedHTTP2 protocol enables support for serving unencrypted HTTP/2 connections. Setting Transport.Protocols to a value which includes UnencryptedHTTP2 and not HTTP1 causes the client to use unencrypted HTTP/2 for requests for http:// URLs.

I propose that we deprecate the golang.org/x/net/h2c package.

More details below.

---

RFC 7540 defines two mechanisms for starting an unencrypted HTTP/2 connection.

The first is a protocol upgrade (section 3.2): The client sends an HTTP/1.1 request with an "Upgrade: h2c" header and an "HTTP2-Settings" header containing its HTTP/2 settings. The server may respond to this with an 101 Switching Protocols response followed by converting the connection to HTTP/2.

The second is "with prior knowledge" (section 3.4): The client opens an unencrypted TCP connection and starts the HTTP/2 protocol on it.

RFC 9113 deprecates the protocol upgrade mechanism (section 3.1):

The "h2c" string was previously used as a token for use in the HTTP Upgrade mechanism's Upgrade header field (Section 7.8 of [HTTP]). This usage was never widely deployed and is deprecated by this document. The same applies to the HTTP2-Settings header field, which was used with the upgrade to "h2c".

Go 1.24's net/http package includes support for HTTP/2 with prior knowledge. It does not include support for the deprecated protocol upgrade mechanism, and we have no plans to add such support.

The x/net/http2/h2c package only supports server connections. It supports both protocol upgrade and prior knowledge.

I am not aware of any supported way to make an unencrypted HTTP/2 connection with protocol upgrade with net/http. The h2c package's support for protocol upgrade has no test coverage. Until CL 407454, it was also quite buggy. (See that CL for details.)

Deprecating the h2c package will leave us without any non-deprecated support for protocol upgrade. I think that's fine:

• Protocol upgrade itself is deprecated in RFC 9113.
• Every request that I've seen for unencrypted HTTP/2 support has been in a scenario where the user controls both endpoints, or where the user needs to interact with an endpoint that only speaks HTTP/2.
• Protocol upgrade is extremely difficult to do well, and the h2c package does not do it well. (Notably, it needs to read the entire initial request into memory before performing the upgrade.)
• If we do want to support protocol upgrade in the future (which I don't think we should do), then we should add support for it to net/http.

[gabyhelp]

Related Issues

• net/http: support unencrypted HTTP/2 (h2c) #67816 (closed)
• x/net/http2/h2c: uses obsolete upgrade mechanism #63565
• x/net/http2/h2c: H2C handler uses incorrect headers to detect upgrade #45785 (closed)
• proposal: x/net/http2: Add support for client-side H2C upgrade flow #46249
• proposal: x/net/http2/h2c: allow to disable http upgrade in h2c #68729
• net/http: Protocol upgrade from HTTP1.1 to h2c(HTTP2) when the request contains payload body, is failing. #41445 (closed)
• net/http: do not enable HTTP/2 extended connect by default #71128 (closed)
• Add implementation of h2c into x/net/http2/h2c. #25363 (closed)

Related Code Changes

• net/http: Export Request.IsH2ClientPreface

Related Discussions

• net/http: move HTTP/2 into the standard library

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}