Overview

This is a discussion to talk about a collection of proposals that collectively move the HTTP/2 client and server implementation currently located in golang.org/x/net/http2 into the standard library.

The change is split across a number of proposals which make various elements of HTTP/1 and HTTP/2 configuration more consistent, add the ability to configure the HTTP/2 implementation to net/http, and finally move the source of truth from x/net to std. The following presents these proposals starting at the highest level (moving HTTP/2 into std) and progressing to lower-level items.

Proposal: Move HTTP/2 into the standard library

I propose that we move the HTTP/2 client and server implementations from golang.org/x/net/http2 into an internal standard library package, net/http/internal/http2. All new development will occur in the standard library package. We will backport fixes to the HTTP/2 implementation into the x/net package until no supported versions of Go use a vendored version of it, at which point we will deprecate it. We will also update the x/net package to forward to std when available.

Background

The net/http package has provided transparent support for the HTTP/2 protocol since Go 1.6.

The source of truth for the net/http package's HTTP/2 implementation is the golang.org/x/net/http2 package. To provide transparent support for HTTP/2, this package is vendored into the standard library. To avoid an import cycle (the http2 package depends on net/http), this vendoring is done by the bundle tool, which converts the entire http2 package into a single source file (h2_bundle.go) which is then included in net/http.

Users can replace the bundled version of the http2 package with the x/net one using http2.ConfigureServer or
http2.ConfigureTransports.

Users who want to tune HTTP/2 configuration settings are required to replace the bundled http2 package in this fashion.

The current design has some advantages, notably that it permits users to acquire new versions of the HTTP/2 implementation outside of the Go release cycle. Users can pick up fixes or new features without the need to upgrade their Go version or wait for a fix to become available in a released version of Go.

This design also has many disadvantages. The relationship between net/http, the bundled HTTP/2 implementation in h2_bundle.go, and golang.org/x/net/http2 is complicated and confusing. The process for backporting HTTP/2 fixes into minor releases is difficult. The process for backporting security fixes is even more so. Users can't configure HTTP/2 settings in net/http servers and clients without importing an external package. Configuring these settings doesn't just change the configuration, it changes the implementation used by net/http.

The fact that net/http and golang.org/x/net/http2 live in separate modules complicates development. Most of the tests in the net/http package exercise both the HTTP/1 and HTTP/2 implementations, but running those tests for a change to the http2 package is difficult. In addition, there are interactions between the two packages which are very difficult to change without breaking some set of users. For example, #52459 is an issue caused by the fact that both the HTTP/1 and HTTP/2 implementations contain a separate retry loop to retry failed requests. The simplest fix for this I can think of is to have a single retry loop that covers both protocols, but making this change without the ability to atomically adjust both packages at the same time is difficult.

Initially developing HTTP/2 support in x/net allowed us to iterate on the package in a place not covered by the compatibility promise and make changes at a pace not limited by the Go release cycle. Now that the package is stable, the costs of keeping it in a separate repository from net/http outweigh the benefits. It's time to make it part of the standard library.

API

The golang.org/x/net/http2 package has a substantial API surface.

We will add new APIs to net/http to preserve the ability to configure HTTP/2 clients and servers. Some configuration settings supported by golang.org/x/net/http2 have proven to not be useful as implemented, and will be deprecated instead.

The following set of proposals evolve the net/http and golang.org/x/net/http2 packages in preparation for replacing the HTTP/2 package. Combined, they bring us to a state where there is no need for users to import golang.org/x/net/http2 other than to get a newer or older version than is bundled in net/http: Every non-deprecated feature of the package is available elsewhere, and all non-deprecated configuration settings can be set from net/http.

• proposal: x/net/http2: move frame operations to x/net/http2/http2frame
• proposal: x/net/http2: deprecate WriteScheduler
• proposal: x/net/http2: deprecate ClientConnPool
• proposal: net/http: HTTP/2 configuration API
• proposal: net/http: support unencrypted HTTP/2 (h2c)
• proposal: net/http: HTTP version selection API
• proposal: x/net/http2: configurable server pings
• proposal: net/http: add per-write timeouts (WriteByteTimeout)

Proposal

We implement the set of API changes above.

We move the HTTP/2 implementation into std. This is technically a bit tricky to do, since there's currently an import cycle between net/http and golang.org/x/net/http2, but I've got a proof of concept implementation that demonstrates that we can do this while keeping http2 in a separate (now internal) package. The required changes are surprisingly small, outside of tests. This step requires no additional API changes.

We update golang.org/x/net/http2 to forward to the implementation in std when available.

Once no supported Go version uses a vendored golang.org/x/net/http2, we deprecate golang.org/x/net/http2.

Backports

We backport fixes for security issues and serious problems with no workaround. (https://github.com/golang/go/wiki/MinorReleases)

For HTTP/2, we have generally considered the ability to import and use a newer version of golang.org/x/net/http2 to be a workaround, and therefore only backport fixes for HTTP/2 security issues.

Once HTTP/2 moves into the standard library, this will not be a viable workaround. We will therefore need to backport fixes for serious, non-security HTTP/2 problems in the future.

For so long as there are supported Go versions that vendor golang.org/x/net/http2, we will also need to backport fixes to that package. Once no supported Go versions vendor http2 and the package is deprecated, we will stop backporting changes to it and include a warning about the lack of security fixes in the deprecation notice.

Backwards compatibility and migration

Existing users select the HTTP/2 implementation in golang.org/x/net/http2 by using the http2.Server and/or http2.Transport directly, or by using http2.ConfigureServer and/or http2.ConfigureTransports to instruct a net/http Server and/or Transport to use the non-bundled implementation.

Users select the golang.org/x/net/http2 implementation in this fashion to configure HTTP/2 parameters, to upgrade to a newer version of the HTTP/2 implementation than provided by their Go version, or to pin to a specific version of the HTTP/2 implementation. There is no way to distinguish between these use cases (which is one of the problems with the current situation).

For all existing versions of golang.org/x/net/http2, we will preserve the existing behavior: A user who selects this implementation will get it, overriding the standard library implementation.

Newer versions of golang.org/x/net/http2, when used with a Go version that contains non-vendored HTTP/2 implementation, will use the standard library HTTP/2 implementation unless the configuration uses a feature not supported by the standard library (http2.Server.NewWriteScheduler or http2.Transport.ConnPool).

proposal: x/net/http2: move frame operations to x/net/http2/http2frame

The golang.org/x/net/http2 package includes support for reading and writing HTTP/2 frames. The http2.Framer type reads and writes frames, and a number of additional types represent specific frames.

Frame support adds a large amount of API surface that few users need. Users who send and receive HTTP/2 requests operate at a higher level than framing, which is an internal protocol detail.

I propose moving Framer and all of its ancillary types into a new golang.org/x/net/http2/http2frame package and eventually deprecating the versions in http2.

Specifically, the following types will move into the new package:

• ContinuationFrame
• DataFrame
• Frame
• FrameHeader
• FrameType
• FrameWriteRequest
• Framer
• GoAwayFrame
• HeadersFrame
• HeadersFrameParam
• MetaHeadersFrame
• PingFrame
• PriorityFrame
• PriorityParam
• PushPromiseFrame
• PushPromiseParam
• RSTStreamFrame
• SettingsFrame
• UnknownFrame
• WindowUpdateFrame

Alternatively, we could deprecate the frame types and provide no alternative. I have not done the analysis to see how many, if any, users this would affect; I suspect the number is very low, but not zero.

proposal: x/net/http2: deprecate WriteScheduler

The http2.WriteScheduler interface type defines a scheduler used to select the order in which data is written to HTTP/2 streams. The Server.NewWriteScheduler configuration setting selects a write scheduler to use for server connections. Client connections do not permit configuring the write scheduler.

The package includes three implementations of this interface: Round robin (the default), random, and priority. The priority write scheduler is known to be buggy and the HTTP/2 stream prioritization scheme it implements is deprecated; see #58804 (comment).

Support for user-defined write schedulers is used seldom, if ever, and substantially constrains the HTTP/2 implementation.

Users should not need to configure the HTTP/2 implementation at this level. Of the current set of scheduler options, there is a clear correct choice: The round robin scheduler outperforms the random scheduler, and the priority scheduler is buggy and we have no plans to fix it. If we come up with a better scheduler, we should just make it the default. If we do discover a reason for users to configure this, we can and should provide a simpler configuration setting than what exists now.

I propose deprecating the write scheduler selection mechanism, consisting of the following types and functions:

• FrameWriteRequest
• NewPriorityWriteScheduler
• NewRandomWriteScheduler
• OpenStreamOptions
• PriorityWriteSchedulerConfig
• Server.NewWriteScheduler
• WriteScheduler

I propose that we add a deprecation notice to these types and functions today, and remove support for them in one year. After removing support, servers will ignore the value of the NewWriteScheduler field.

proposal: x/net/http2: deprecate ClientConnPool

The http2.ClientConnPool interface type and associated types define an API for a user-defined client connection pool. This interface does not sufficiently describe the features required by a useful connection pool. It has no mechanism for notifying the pool when a request on a pooled connection has completed. It has no mechanism for adding a connection to the pool, so connections created by the net/http package and upgraded to HTTP/2 by ALPN cannot be pooled.

We cannot evolve the ClientConnPool interface to address its limitations, because adding methods to the interface is not backwards compatible.

There might be value in supporting user-defined connection pools, but ClientConnPool is not a good basis for that feature.

I propose that we add a deprecation notice to ClientConnPool and Transport.ConnPool today, and remove support for it in one year. After removing support, transports will ignore the value of the ConnPool configuration field.

proposal: net/http: HTTP/2 configuration API

Configuring HTTP/2-specific protocol options currently requires users to import the golang.org/x/net/http2 package and call http2.ConfigureServer or http2.ConfigureTransports.

Configuring options in this fashion has the side effect of replacing the bundled HTTP/2 implementation in net/http with the one in golang.org/x/net/http2.

I propose adding HTTP/2 configuration options to net/http, permitting HTTP/2 servers and clients to be configured without importing an external package and separating configuration from version selection.

Parameters common to servers and clients

Many of the HTTP/2 settings are identical for server and client connections. For example, the MaxDecoderHeaderTableSize field of http2.Server and http2.Transport sets the SETTINGS_HEADER_TABLE_SIZE setting sent to the peer. We will unify these settings into a single configuration struct, and add this configuration to http.Server and http.Transport.

type HTTP2Config struct {
	// MaxConcurrentStreams optionally specifies the number of
	// concurrent streams that a peer may have open at a
	// time (SETTINGS_MAX_CONCURRENT_STREAMS).
	// If zero, MaxConcurrentStreams defaults to at least 100.
	MaxConcurrentStreams uint32

	// MaxDecoderHeaderTableSize optionally specifies the http2
	// SETTINGS_HEADER_TABLE_SIZE to send in the initial settings frame. It
	// informs the remote endpoint of the maximum size of the header compression
	// table used to decode header blocks, in octets. If zero, the default value
	// of 4096 is used.
	MaxDecoderHeaderTableSize uint32

	// MaxEncoderHeaderTableSize optionally specifies an upper limit for the
	// header compression table used for encoding request headers. Received
	// SETTINGS_HEADER_TABLE_SIZE settings are capped at this limit. If zero,
	// the default value of 4096 is used.
	MaxEncoderHeaderTableSize uint32

	// MaxReadFrameSize optionally specifies the largest frame
	// this endpoint is willing to read (SETTINGS_MAX_FRAME_SIZE).
	// A valid value is between 16k and 16M, inclusive.
	// If zero or otherwise invalid, a default value is used.
	MaxReadFrameSize uint32

	// MaxUploadBufferPerConnection is the size of the initial flow
	// control window for each connection. The HTTP/2 spec does not
	// allow this to be smaller than 65535 or larger than 2^32-1.
	// If the value is outside this range, a default value will be
	// used instead.
	MaxUploadBufferPerConnection int32

	// MaxUploadBufferPerStream is the size of the initial flow control
	// window for each stream. The HTTP/2 spec does not allow this to
	// be larger than 2^32-1. If the value is zero or larger than the
	// maximum, a default value will be used instead.
	MaxUploadBufferPerStream int32

	// SendPingTimeout is the timeout after which a health check using a ping
	// frame will be carried out if no frame is received on the connection.
	// If zero, no health check is performed.
	SendPingTimeout time.Duration

	// PingTimeout is the timeout after which the connection will be closed
	// if a response to a ping is not received.
	// If zero, a default of 15 seconds is used.
	PingTimeout time.Duration

	// PermitProhibitedCipherSuites, if true, permits the use of
	// cipher suites prohibited by the HTTP/2 spec.
	PermitProhibitedCipherSuites bool

	// CountError, if non-nil, is called on HTTP/2 errors.
	// It's intended to increment a metric for monitoring, such
	// as an expvar or Prometheus metric.
	// The errType consists of only ASCII word characters.
	CountError func(errType string)
}

type Server struct { // contains unchanged fields
	HTTP2 HTTP2Config
}

type Transport struct { // contains unchanged fields
	HTTP2 HTTP2Config
}

The SendPingTimeout and PingTimeout fields presume #XXXX is accepted, adding support for configurable pings to HTTP/2 servers.

Concurrent request limit

The http2.Transport.StrictMaxConcurrentStreams field controls whether a new connection should be opened to a server if an existing connection has exceeded its stream limit. For example, if an HTTP/2 server advertises a stream limit of 100 concurrent streams, then the 101st concurrent stream opened by the client will block waiting for an existing stream to complete when StrictMaxConcurrentStreams is true, or create a new connection when it is false. There is no equivalent to this setting for HTTP/1 connections, which only support a single concurrent request per connection. We will add this setting to http.Transport, since it could be used to configure HTTP/3 connections (if and when we support HTTP/3):

type Transport struct { // contains unchanged fields
	// StrictMaxConcurrentRequests controls whether an HTTP/2 server's
	// concurrency limit should be respected globally.
	// If true, new requests sent when an connection's concurrency limit has been exceeded
	// will block until an existing request completes.
	// If false, an additional connection will be opened if all existing connections are at their limit.
	StrictMaxConcurrentRequests bool
}

Settings common to HTTP/1 and HTTP/2

Some HTTP/2 settings can already be configured via parameters on http.Server and http.Transport, and require no new API surface.

The following fields exist on both http and http2 versions of the type:

• Server.IdleTimeout
• Server.WriteByteTimeout (assuming #XXXX is accepted)
• Transport.DialTLS
• Transport.DialTLSContext
• Transport.DisableCompression
• Transport.WriteByteTimeout (assuming #XXXX is accepted)

The default value of the http2.Transport.MaxHeaderListSize field is set by http.Transport.MaxResponseHeaderBytes.

Assuming #XXXX is accepted, the AllowHTTP field of http2.Transport will be supplanted by http.Transport.Protocols.

proposal: net/http: support unencrypted HTTP/2 (h2c)

This proposal depends on the version selection API proposed in #XXXX.

The net/http package does not directly support unencrypted HTTP/2, sometimes referred to as "h2c".

Users may send HTTP/2 requests over an unencrypted connection by setting http2.Transport.AllowHTTP and providing a DialTLS function which opens an unencrypted connection. Users may accept unencrypted HTTP/2 requests by using the golang.org/x/net/http2/h2c package.

Neither of these mechanisms is very clean: Returning an unencrypted connection from DialTLS is unfortunate, and the interactions between net/http, h2c, and golang.org/x/net/http2 are fairly complicated.

I propose adding support for unencrypted HTTP/2 as a first-class feature to net/http.

HTTP/2 will be enabled by a new http.Protocol value:

const (
	// HTTP2 is the HTTP/2 protocol over an unsecured TCP connection.
	UnencryptedHTTP2 Protocol
)

When Server.Protocol contains UnencryptedHTTP2, the server will accept HTTP/2 requests on its unencrypted port(s).

When Protocols contains both HTTP1 and UnencryptedHTTP2, both Server and Transport will support the Upgrade: h2c header specified in RFC 7540 Section 3.2. The server will upgrade HTTP/1 requests with Upgrade: h2c to unencrypted HTTP/2, and the transport will send an Upgrade: h2c header.

When Transport.Protocol contains UnencryptedHTTP2 but not HTTP1, the transport will use unencrypted HTTP/2 for requests for http:// URLs ("Starting HTTP/2 with prior knowledge", RFC 7540 Section 3.4).

http2.Transport.AllowHTTP

The HTTP/2 http2.Transport.AllowHTTP setting controls whether the transport permits requests using the http:// scheme. When Protocols contains UnencryptedHTTP1, the transport will ignore this setting and always permit http:// requests.

Backwards compatibility

The golang.org/x/net/http2/h2c package enables unencrypted HTTP/2 on a per-handler basis, while the proposed API here enables it on a per-server basis. In addition, the h2c package has the side effect of selecting the HTTP/2 implementation in golang.org/x/net/http2 rather than the one bundled in net/http.

For these reasons, it is not possible to duplicate the behavior of the h2c package using the new API.

Instead, we will change the handler created by h2c.NewHandler as follows:

If the Server for a request has a Protocol field containing UnencryptedHTTP2, then pass through the request unchanged and allow the net/http package to manage protocol selection.
Otherwise, behave as today, hijacking the request and directing it to the golang.org/x/net/http2 package.

Deprecation of Upgrade: h2c

The Upgrade: h2c upgrade path was deprecated by RFC 9113.

The h2c package provides server support for Upgrade: h2c, but I don't believe we have existing client support for this path.

We could choose to support only HTTP/2 with prior knowledge (RFC 9113, Section 3.3). In this case, when Transport.Protocols contains both HTTP1 and UnencryptedHTTP2, the transport will select whichever appears first in the list.

proposal: net/http: HTTP version selection API

I propose adding a new mechanism for selecting what HTTP versions will be used by a net/http Server or Transport.

package http

// A Protocol is an HTTP protocol.
type Protocol int

const (
	// HTTP1 is the HTTP/1.0 and HTTP/1.1 protocols.
	// HTTP1 is supported on both unsecured TCP and TLS connections.
	HTTP1 Protocol = iota

	// HTTP2 is the HTTP/2 protocol over a TLS connection.
	HTTP2
)

type Server struct { // contains unchanged fields
	// Protocols is a list of protocols accepted by the server in preference order.
	// If the list is empty, the default is {HTTP2, HTTP1}.
	// If TLSNextProto is non-nil and does not contain an "h2" entry, then the default is {HTTP1}.
	Protocols []Protocol
}

type Transport struct { // contains unchanged fields
	// Protocols is a list of protocols attempted by the transport in preference order.
	// If the list is empty, the default is {HTTP2, HTTP1}.
	// If TLSNextProto is non-nil and does not contain an "h2" entry, then the default is {HTTP1}.
	Protocols []Protocol
}

Background

By default, a net/http server listening on a TLS connection will accept both HTTP/1 and HTTP/2 requests, and a net/http client sending HTTPS requests will use HTTP/2 when available and HTTP/1 otherwise.

Users may disable HTTP/2 support by setting Server.TLSNextProto or Transport.TLSNextProto to an empty map.

Users may disable HTTP/1 support by using an http2.Server or http2.Transport directly.

The net/http package does not currently directly support HTTP/3, but if and when it does, there will need to be a mechanism for enabling or disabling HTTP/3.

The existing APIs for selecting a protocol version are confusing, inconsistent, expose internal implementation details, and don't generalize well to additional protocol versions. The above proposal replaces them with a single, clear mechanism that allows for future expansion.

Backwards compatibility

Programs which disable HTTP/2 support by setting TLSNextProto will continue to work as they do today, since doing so limits the default protocol set to HTTP/1.

Programs which use http2.Server or http2.Transport directly will behave as they do today.

The http2.ConfigureServer and http2.ConfigureTransports functions configure an HTTP/1 server or transport to use HTTP/2. We will modify these functions to add HTTP2 to the Protocols list when the list is non-empty and does not contain HTTP2.

proposal: x/net/http2: configurable server pings

A HTTP/2 client or server may send PING frames to its peer. (RFC 9113 Section 6.7)

The http2.ReadIdleTimeout and http2.PingTimeout fields configure an HTTP/2 client to send a PING when a connection has been idle for some amount of time, and to close the connection if no response is received.

The http2.Server does not support sending PINGs on idle connections.

I propose adding the ability to configure servers to send pings as well. This setting will be off by default.

package http2

type Server struct { // contains unchanged fields
	// ReadIdleTimeout is the timeout after which a health check using a ping
	// frame will be carried out if no frame is received on the connection.
	// If zero, no health check is performed.
	ReadIdleTimeout time.Duration

	// PingTimeout is the timeout after which the connection will be closed
	// if a response to a ping is not received.
	// If zero, a default of 15 seconds is used.
	PingTimeout time.Duration
}

proposal: net/http: add per-write timeouts (WriteByteTimeout)

HTTP/2 transports have a Transport.WriteByteTimeout configuration setting, which sets the maximum time a single write to a connection may take. The timeout begins when a write is made, and is extended whenever any data is written.

This setting can be used to detect unresponsive connections when the timeout for an entire request may be large or unbounded.

I propose extending this feature to apply to HTTP/1 server and client connections, and HTTP/2 server connections.

package http

type Server struct { // contains unchanged fields
	// WriteByteTimeout is the timeout after which the connection will be
	// closed if no data can be written to it. The timeout begins when data is
	// available to write, and is extended whenever any bytes are written.
	WriteByteTimeout time.Duration
}

type Transport struct { // contains unchanged fields
	// WriteByteTimeout is the timeout after which the connection will be
	// closed if no data can be written to it. The timeout begins when data is
	// available to write, and is extended whenever any bytes are written.
	WriteByteTimeout time.Duration
}