net/http — Specification¶

1. Introduction¶

net/http is the Go standard library's HTTP/1.1 and HTTP/2 implementation: client, server, transport, multiplexer, header model, cookie jar, and the surrounding utilities. The package implements substantial parts of more than a dozen IETF RFCs — message syntax, semantics, the HTTP/2 binary framing layer, cookies, basic caching directives, ALPN negotiation, and several adjacent specifications. None of those RFCs is the document a Go developer reads to predict behaviour. The practical specification of net/http is the package itself: the stable types, the documented method signatures, the Go 1 compatibility promise that pins them, and the source files under src/net/http/ in the Go tree.

This is unusual. Most "specifications" for an HTTP library cite the wire-level RFC and treat the implementation as one of several conforming candidates. With net/http, the implementation is the contract that production code depends on. The RFCs constrain what the package may do on the wire; the package's exported API — and its documented behaviour around shutdown, redirects, connection pooling, idempotent retries, and HTTP/2 negotiation — constrains what application code may rely on. Both layers matter, but the second is the one Go programmers must internalise.

The framing of this document follows that priority. The wire RFCs are listed for completeness in Section 2; the bulk of the specification — Sections 5 through 12 — describes the stdlib types, their contracts, and the GODEBUG knobs that toggle behaviour at runtime. Section 13 names the source files that hold the authoritative implementation for each subsystem so that a reader pursuing a specific behaviour can go straight to the code.

2. RFCs implemented¶

net/http is not a verified implementation of any single RFC; it tracks a moving target across several. The packages whose implementation falls within net/http itself or within golang.org/x/net/http2 and related supporting modules cover:

The Go project does not publish a conformance matrix mapping each RFC clause to an implementation file. The package's behaviour is the de facto specification; the RFCs are the upper bound on what is permitted on the wire. Several RFC features are intentionally omitted — HTTP/3 (QUIC), HTTP server push at scale, on-disk response caching, the full digest authentication scheme, and early-data (0-RTT) handshake support. Application code that needs these uses third-party modules or golang.org/x packages that sit beside net/http rather than inside it.

References:

• RFC 9110 — https://datatracker.ietf.org/doc/html/rfc9110
• RFC 9112 — https://datatracker.ietf.org/doc/html/rfc9112
• RFC 7540 — https://datatracker.ietf.org/doc/html/rfc7540
• RFC 9113 — https://datatracker.ietf.org/doc/html/rfc9113
• RFC 6265 — https://datatracker.ietf.org/doc/html/rfc6265
• RFC 9111 — https://datatracker.ietf.org/doc/html/rfc9111
• RFC 8446 (TLS 1.3) — https://datatracker.ietf.org/doc/html/rfc8446
• RFC 7301 (ALPN) — https://datatracker.ietf.org/doc/html/rfc7301

3. Stable types under the Go 1 compatibility promise¶

The Go 1 compatibility document at https://go.dev/doc/go1compat binds the exported surface of net/http against breaking changes within the Go 1.x release line. The following types are the load-bearing identities application code depends on:

Sentinel values pinned by the compatibility promise include http.ErrServerClosed, http.ErrHandlerTimeout, http.ErrAbortHandler, http.ErrBodyNotAllowed, http.ErrContentLength, http.ErrHijacked, http.ErrLineTooLong, http.ErrMissingFile, http.ErrNoCookie, http.ErrNoLocation, http.ErrNotMultipart, http.ErrNotSupported, http.ErrShortBody, http.ErrSkipAltProtocol, http.ErrUseLastResponse, http.ErrWriteAfterFlush.

Status code constants (http.StatusOK, http.StatusNotFound, and so on through http.StatusNetworkAuthenticationRequired) and method constants (http.MethodGet through http.MethodTrace) are similarly stable.

4. Subpackages¶

net/http is the trunk; the following subpackages extend it. Stability follows the Go 1 promise except where noted.

golang.org/x/net/http2 is a separate module whose code is vendored into the standard library and exposed through net/http. Its exported API is not directly visible to standard-library consumers; the http.Transport.ForceAttemptHTTP2 and the GODEBUG http2* knobs are the public controls.

Documentation index: https://pkg.go.dev/net/http.

5. The http.Handler contract¶

http.Handler is a single-method interface:

type Handler interface {
    ServeHTTP(ResponseWriter, *Request)
}

The server invokes ServeHTTP once per request. The contract:

1. The handler may read r.Body until EOF; it may also choose not to read it. The server is responsible for draining and closing the body after ServeHTTP returns.
2. The handler may write a response via the ResponseWriter in any combination of Header(), WriteHeader(status int), and Write([]byte) calls subject to the ordering rules in Section 6.
3. The handler may return without writing anything; the server synthesises 200 OK with an empty body.
4. The handler must not retain references to r, w, or any of their components after ServeHTTP returns. The values are not safe for use outside the handler call.
5. The handler may panic; the server recovers, logs the panic (unless it equals http.ErrAbortHandler), and aborts the connection without writing further data. http.ErrAbortHandler panics are silent — used when a handler has decided to disconnect mid-response.
6. The handler's goroutine is governed by r.Context(). The context is cancelled when the client disconnects, when the server is shutting down, or when a per-handler timeout fires.

The contract pins what the server guarantees and what the handler must not do; everything else is convention.

Composition rules:

• A handler may delegate to another handler by calling its ServeHTTP with the same w and r (the middleware idiom).
• A handler may construct a new *Request from r (via r.WithContext or r.Clone) before delegating; modifying r in place is permitted but discouraged because downstream code may have captured references to fields.
• A handler may wrap the ResponseWriter in a new type that satisfies ResponseWriter plus the optional interfaces it intends to forward; wrappers that do not forward Flush, Hijack, or Push correctly are the most common cause of broken streaming responses.

http.HandlerFunc is the standard adapter: type HandlerFunc func(ResponseWriter, *Request) with a ServeHTTP method that calls the function. It enables passing function literals where a Handler is required.

6. ResponseWriter contract¶

http.ResponseWriter mediates header construction, status writing, and body streaming. The ordering rules are precise and cause the majority of subtle handler bugs.

Additional rules:

• Headers under the implicit-content-type rule: if the handler does not set Content-Type before the first Write, the server sniffs the first 512 bytes of the body and calls http.DetectContentType, then writes the resulting MIME type.
• Content-Length is set automatically by the server if the entire response body fits in a single Write and the handler has not set it manually.
• Setting a header to a value with invalid bytes (control characters, CR, LF) causes the response to fail; the server treats the connection as broken.
• The ResponseWriter may also satisfy Flusher, Hijacker, Pusher, or CloseNotifier; handlers use type assertions to detect support. As of Go 1.20, http.NewResponseController(w) is the preferred way to access these optional methods without per-interface assertions.

Reference implementation: src/net/http/server.go, the response struct.

7. Server.Shutdown semantics¶

Server.Shutdown(ctx context.Context) error performs a graceful shutdown:

1. Stops accepting new connections on listeners associated with the server.
2. Closes all idle keep-alive connections immediately.
3. Waits for active connections to return to idle state, then closes them.
4. Returns nil when all connections have drained, or the context's error if the context fires first.

Long-running handlers (server-sent events, WebSockets via Hijacker) do not return to idle naturally; the application must observe Server.RegisterOnShutdown(func()) callbacks or Server.BaseContext's cancellation to terminate them voluntarily. If they do not, Shutdown waits until the context expires and then returns the context's error; in-flight handlers are left running on the abandoned connections.

Server.Close() is the abrupt counterpart: closes listeners, then forcibly closes all connections (idle and active), returning immediately. Handlers in flight see write errors on their ResponseWriter and r.Context().Err() set to context.Canceled.

http.ErrServerClosed is returned from ListenAndServe and Serve to signal that Shutdown or Close was the cause of the loop exit, distinguishing graceful termination from a listener error.

Reference: src/net/http/server.go, Server.Shutdown.

8. ServeMux (Go 1.22 syntax)¶

Go 1.22 introduced method-aware and pattern-aware routing for the default mux. Patterns have the form:

[METHOD] [HOST]/[PATH]

Precedence is by specificity, computed from the pattern's structure rather than registration order. The mux rejects ambiguous registrations at registration time with a clear error explaining which two patterns conflict.

Wildcards bound by {name} are read with r.PathValue("name") string. The catch-all {name...} form binds the remainder of the path.

The old (pre-1.22) mux behaviour can be restored with GODEBUG=httpmuxgo121=1 for the lifetime of the process. The compatibility knob is intended for migration; new code should adopt the 1.22 syntax.

Reference: src/net/http/pattern.go, src/net/http/routing_tree.go, src/net/http/server.go (the ServeMux type).

Proposal: https://github.com/golang/go/issues/61410.

9. Client redirect policy¶

http.Client.CheckRedirect func(req *Request, via []*Request) error controls redirect handling. Default behaviour:

1. The client follows redirects for 301, 302, 303, 307, 308 status codes.
2. The default policy stops after 10 redirects and returns the most recent response wrapped in an error containing http.ErrUseLastResponse semantics.
3. The client copies certain headers from the original request to the redirect target (Authorization, Cookie, WWW-Authenticate) only when the target host is the same as the source host. Cross-host redirects strip sensitive headers.
4. For 303 redirects, the method becomes GET and the body is dropped, per RFC 9110. For 307 and 308, the method and body are preserved; for 301 and 302, the historical behaviour (POST becomes GET) is followed for compatibility with widely deployed implementations.

To customise:

client := &http.Client{
    CheckRedirect: func(req *Request, via []*Request) error {
        if len(via) >= 3 {
            return http.ErrUseLastResponse // stop redirecting; return the response
        }
        return nil
    },
}

Returning http.ErrUseLastResponse causes the client to return the latest response and a nil error; the caller receives the redirect response itself rather than following it. Returning any other error aborts and propagates the error to the caller.

Setting Client.CheckRedirect to func(*Request, []*Request) error { return http.ErrUseLastResponse } disables redirects entirely.

Reference: src/net/http/client.go, Client.do.

10. Transport — connection pooling, retries, cancellation¶

http.Transport is the default RoundTripper and the core of the HTTP/1.1 and HTTP/2 client. Key semantics:

Connection pool. The transport maintains a pool of idle keep-alive connections keyed by (scheme, host, proxy). Configuration:

Idempotent retry. The transport retries a request once on a fresh connection if all of the following hold:

1. The request method is idempotent (GET, HEAD, OPTIONS, TRACE, PUT, DELETE) or carries a non-nil Request.GetBody set by the caller (and the request body is replayable).
2. The first attempt used a pooled connection that the server closed before sending any response bytes.
3. The error is one of a small set recognised as "fresh connection problem" rather than a deliberate server response.

The retry happens transparently; the caller sees one successful response and no indication that the first attempt was discarded. Non-idempotent requests (POST without GetBody) are never retried by the transport.

Cancellation. Two mechanisms:

1. Request.Context() — cancelling the context aborts the in-flight request, closes the underlying connection, and causes RoundTrip to return the context's error. This is the modern idiom.
2. Request.Cancel (deprecated) — a chan struct{} whose close cancels the request. Pre-context API; new code uses contexts.

Client.Timeout sets an upper bound on the entire request lifecycle (dial, write, response head, full body read). Exceeding it cancels the underlying request context. Finer-grained limits live on Transport: DialContext carries its own deadline, TLSHandshakeTimeout (default 10s), ResponseHeaderTimeout (no default), ExpectContinueTimeout (default 1s), and IdleConnTimeout (default 90s).

HTTP/2 specifics. When the transport upgrades a connection to HTTP/2, the pool stores one multiplexed connection per host and dispatches requests as streams. The retry rules above apply to stream errors that resemble fresh-connection errors (REFUSED_STREAM, GOAWAY with no streams processed). MaxIdleConnsPerHost is interpreted differently because a single HTTP/2 connection carries many concurrent streams; the per-stream limit is governed by the peer's SETTINGS_MAX_CONCURRENT_STREAMS.

Reference: src/net/http/transport.go.

11. HTTP/2 enabling¶

HTTP/2 is enabled automatically under these conditions:

1. The client and server both speak TLS.
2. The TLS handshake negotiates the h2 ALPN token (RFC 7301), which both peers offer by default in Go.
3. The http.Transport has not had TLSNextProto set to a non-nil map that omits h2. Setting TLSNextProto to a non-nil map without an h2 entry disables HTTP/2.

On the server side, http.Server.TLSNextProto similarly controls HTTP/2 availability; leaving it nil enables HTTP/2 automatically when serving over TLS. The HTTP/2 implementation is golang.org/x/net/http2, vendored into the stdlib; calling http2.ConfigureServer or http2.ConfigureTransport explicitly is required only when configuring HTTP/2-specific knobs (max concurrent streams, initial window size).

Plaintext HTTP/2 (h2c) is not enabled by default. The golang.org/x/net/http2/h2c package provides an opt-in handler wrapper.

http.Transport.ForceAttemptHTTP2 = true causes HTTP/2 to be attempted even when a custom TLSClientConfig or DialContext is set; without this flag, customising those fields silently disables HTTP/2.

Detection of which protocol a connection ended up using is via Response.Proto ("HTTP/1.1" or "HTTP/2.0") and Response.ProtoMajor / ProtoMinor. Server-side, the same fields appear on the incoming Request and may be used by handlers that need to vary behaviour by protocol (for example, declining HTTP/2 server push for clients that did not negotiate it).

Reference: src/net/http/h2_bundle.go (the vendored golang.org/x/net/http2 source).

12. GODEBUG knobs¶

GODEBUG is the runtime configuration channel for behavioural toggles. The net/http-relevant knobs:

Default values follow the GODEBUG default version policy in https://go.dev/doc/godebug: knobs introduced for a release default to the new behaviour for code that declares that release in go.mod, and to the legacy behaviour for older go.mod versions.

Reference: https://pkg.go.dev/runtime#hdr-Environment_Variables and the per-release "Changes to the standard library" section of the release notes.

13. Source files of authoritative interest¶

The path prefix src/net/http/ is rooted at the Go source tree (https://github.com/golang/go/tree/master/src/net/http).

Subpackage entry points:

The canonical browser link for any of these: https://github.com/golang/go/blob/master/src/net/http/server.go and analogues.

14. Compatibility scope¶

The Go 1 compatibility promise (https://go.dev/doc/go1compat) covers the exported identifiers of net/http and its subpackages excluding internal/. Specifically:

Behavioural changes that are not breaking under the promise but do affect application code: changes to MIME sniffing, changes to default header normalisation, changes to default cipher suites, and changes to redirect-header propagation rules across cross-host hops. These are documented in the release notes for the affected version.

15. Notable proposals¶

The issue tracker at https://github.com/golang/go/issues?q=is%3Aissue+label%3Anet%2Fhttp is the live index.

16. Bug reporting¶

net/http bugs are filed on the Go issue tracker. The intake path:

1. Reproduce against gotip (go install golang.org/dl/gotip@latest && gotip download && gotip <build>) or against the latest stable release.
2. Reduce to a minimal program — ideally one that uses httptest.Server so the report is self-contained.
3. File at https://github.com/golang/go/issues/new/choose selecting the "Bug Report" template.
4. Apply or request the NeedsInvestigation and net/http labels.
5. For security-sensitive issues (request smuggling, header injection, TLS bypass), use the private disclosure channel at https://go.dev/security rather than the public tracker.

The active maintainers for net/http are listed in src/net/http/CONTRIBUTORS historically and in the per-file blame on github.com/golang/go currently; the package owners are part of the Go team and respond on the tracker.

The release-notes index at https://go.dev/doc/devel/release records all net/http changes per release; the "Changes to the standard library" section of each minor release is the authoritative changelog.

Reading order for a developer approaching the net/http source for the first time:

1. server.go first — it contains the connection state machine, the Handler and ResponseWriter types, and the Server shutdown logic. Most behavioural questions resolve here.
2. transport.go next — the client-side counterpart and the most complex file in the package by control flow.
3. request.go and response.go — message reading and writing; small enough to read in one sitting once the server and transport context is understood.
4. pattern.go and routing_tree.go for the post-1.22 mux implementation.
5. h2_bundle.go last and only when needed; it is large, machine-bundled, and exists mainly to keep golang.org/x/net/http2 in lockstep with the stdlib.