8.11 net/http Internals — Specification¶

A one-page reference for the contracts that govern net/http. The sections below are the rules; the longer files in this leaf are the explanations.

1. Handler interface¶

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

Rules:

1. ServeHTTP runs in a goroutine owned by the server (one per conn).
2. The server recovers panics from ServeHTTP. A panic of http.ErrAbortHandler is silent; any other value is logged with a stack trace.
3. ServeHTTP should not retain r or w past return.
4. The server may have already started writing the response when ServeHTTP returns; do not call methods on w after return.

2. ResponseWriter interface¶

type ResponseWriter interface {
    Header() Header
    Write([]byte) (int, error)
    WriteHeader(statusCode int)
}

Rules:

1. Header() returns a map valid for setting headers until the first Write or WriteHeader. After commit, mutations are silently ignored except for trailers.
2. WriteHeader may be called at most once. Subsequent calls are logged ("superfluous WriteHeader") and ignored.
3. The first Write calls WriteHeader(http.StatusOK) if not yet called.
4. Write may auto-set Content-Type from the first 512 bytes via DetectContentType if not already set.
5. Write returns an error if the conn is broken; the handler should stop writing but continue normally otherwise.
6. Status codes 1xx (except 101) are interim and may be written multiple times via Write1xx / WriteHeader (Go 1.21+).
7. After hijack, Write/WriteHeader/Header panic or no-op; do not call them.

3. Request semantics¶

Rules:

1. The handler should not modify r. To pass a modified copy, use r.Clone(ctx) or r.WithContext(ctx).
2. Reading r.Body past handler return returns an error; reads inside the handler may block on the network.
3. r.ParseForm may be called multiple times; subsequent calls are no-ops.
4. r.ParseMultipartForm(maxMem) reads at most maxMem into memory; the rest spills to a temp file in os.TempDir.

4. Server configuration¶

type Server struct {
    Addr              string
    Handler           Handler
    TLSConfig         *tls.Config
    ReadTimeout       time.Duration
    ReadHeaderTimeout time.Duration
    WriteTimeout      time.Duration
    IdleTimeout       time.Duration
    MaxHeaderBytes    int
    TLSNextProto      map[string]func(*Server, *tls.Conn, Handler)
    ConnState         func(net.Conn, ConnState)
    BaseContext       func(net.Listener) context.Context
    ConnContext       func(ctx context.Context, c net.Conn) context.Context
    ErrorLog          *log.Logger
    DisableGeneralOptionsHandler bool
}

Defaults:

Lifecycle methods:

ListenAndServe returns http.ErrServerClosed after Shutdown — treat as success.

5. ConnState transitions¶

StateNew → StateActive ⇄ StateIdle → StateClosed
                    ↘ StateHijacked → (terminal)

ConnState callback runs in the conn goroutine; do not block.

6. Client and Transport¶

Client.Timeout: total wall-clock budget covering dial, TLS, request write, response headers, response body. Zero = no timeout.

Transport pool keys: (scheme, host:port, proxyURL, isH2). Idle conns recycled per LRU.

RoundTripper contract:

1. Do not modify the input Request.
2. On nil error, return non-nil Response whose Body reads the response. Caller closes Body.
3. On non-nil error, return nil Response, or a non-nil Response with closed-or-nil Body.
4. Honor req.Context() for cancellation.

7. Body framing¶

Server sends one of:

• Content-Length: N — exactly N body bytes follow.
• Transfer-Encoding: chunked — chunks until terminating zero-length chunk.
• Connection: close — body until conn closes.

Server picks based on:

• Handler set Content-Length header → use that (subject to truncation rules).
• Handler Write returned for the entire response before flush → compute and set Content-Length.
• Handler streams (multiple flushes) → chunked.
• HTTP/1.0 → Connection: close.

8. Optional ResponseWriter interfaces¶

http.NewResponseController(w) is the modern, wrapper-safe way to call these. Wrappers should implement Unwrap() ResponseWriter so the controller can find the underlying writer.

9. MaxBytesReader¶

r.Body = http.MaxBytesReader(w, r.Body, max)

• Subsequent reads return *MaxBytesError once max is exceeded.
• The underlying conn is marked for close on response complete.

10. ServeMux (Go 1.22+) pattern syntax¶

[METHOD] [HOST]/[PATH]

Conflicting patterns at registration → panic.

11. Hop-by-hop headers (RFC 7230)¶

Stripped by ReverseProxy automatically:

• Connection
• Keep-Alive
• Proxy-Authenticate
• Proxy-Authorization
• Te
• Trailers
• Transfer-Encoding
• Upgrade

Plus any header name listed in Connection:.

12. Errors and sentinels¶

13. Request.Context cancellation triggers¶

The context is canceled when any of:

• The client closes the conn (TCP RST/FIN).
• The handler returns.
• The server is Shutdown or Closed.
• A BaseContext ancestor is canceled.

Handlers that propagate the context to downstream calls (DB, HTTP) get cancellation for free.

14. Cross-references¶

• junior.md, middle.md, senior.md, professional.md — narrative coverage of the rules above.
• ../10-net/specification.md — the underlying Conn and Listener rules.