Hijacking and Upgrades

## The interface `net/http` normally owns the TCP connection under a handler: it parses the request, frames whatever you write into a response, decides whether the connection can be reused for the next request, and eventually closes it. Hijacking is the escape hatch that hands that ownership to your handler so you can speak some other protocol over the same socket — an interactive attach or terminal session, a custom line protocol, any upgrade you implement by hand. The surface is one interface: ```go type Hijacker interface { Hijack() (net.Conn, *bufio.ReadWriter, error) } ``` The default HTTP/1.x `ResponseWriter` implements it, so the idiom is a comma-ok assertion: ```go hj, ok := w.(http.Hijacker) if !ok { /* not hijackable */ } conn, brw, err := hj.Hijack() ``` Since Go 1.20 there is also `http.NewResponseController(w).Hijack()`, which returns an error matching `http.ErrNotSupported` rather than making you branch on a failed type assertion. ## What comes back **`net.Conn`** — the actual connection. For a plaintext listener that is a `*net.TCPConn`; behind `ListenAndServeTLS` it is a `*tls.Conn`. Reads and writes on it are raw bytes: no status line, no chunked framing, no header parsing. **`*bufio.ReadWriter`** — the reader and writer net/http was already using on that connection, embedded together as `struct { *bufio.Reader; *bufio.Writer }`. The reader half matters enormously: the server may have read past the end of the request head, so bytes the client has already sent can be sitting in that buffer rather than in the kernel socket. The writer half is buffered, so nothing you write through it reaches the client until you `Flush`. **`error`** — non-nil when this connection cannot be hijacked at all. ## What net/http stops doing After a successful `Hijack`, the server library does nothing further with that connection. Concretely: - It writes no response. If you never write a status line, the client just waits. - `w.Write` and `w.WriteHeader` no longer reach the client; writes return `http.ErrHijacked`. - `r.Body` must not be read after the call — the request body, if any, is now just bytes on the connection you own. - Keep-alive is over: this connection will never carry another request through the mux. - Nothing closes the socket. The handler returning does not close it; only your `Close` does. - The connection reports `http.StateHijacked` to a `Server.ConnState` hook, and that is a terminal state — no `StateClosed` ever follows it. That last group is why the usual shape is `defer conn.Close()` in whichever goroutine owns the connection last. Forget it and you have a socket that lives until the process exits or the peer disappears. ## Where it is unavailable **HTTP/2.** A single HTTP/2 connection multiplexes many streams, so there is no per-request connection to hand over; the HTTP/2 `ResponseWriter` simply does not implement `http.Hijacker` and the assertion fails. A handler that must hijack has to be served over HTTP/1.1 — which is why hand-rolled upgrades and h2 are mutually exclusive on the same route. **Test doubles.** `httptest.ResponseRecorder` has no `Hijack` method either, so a hijacking handler cannot be exercised by passing it a recorder. Test it against a real socket with `httptest.NewServer`. ## When it is the right tool Only when you genuinely need the raw bidirectional byte stream. If the requirement is "push data to the client as it is produced", an ordinary streamed response that the server still frames keeps every guarantee net/http offers you. Hijacking is for the case where the bytes after the handshake are no longer HTTP at all, and it costs you the server's timeouts, its connection accounting and its shutdown handling — all of which you must then reimplement.