Size Limits and Caps

## The problem it solves An exported HTTP endpoint reads whatever the client sends. Nothing in `net/http` bounds the size of a request body by default: the server reads request *headers* up to `Server.MaxHeaderBytes` (1 MB by default, `http.DefaultMaxHeaderBytes`), but the body is whatever the handler chooses to read. If a handler does `json.NewDecoder(r.Body).Decode(&v)` or reads the body into a `[]byte`, an anonymous poster sending a multi-gigabyte body decides how much memory the process allocates. On a public webhook receiver, that is a one-request denial of service that needs no credentials. ## What the wrapper does `http.MaxBytesReader(w http.ResponseWriter, r io.ReadCloser, n int64) io.ReadCloser` returns a reader that passes through the first `n` bytes and then fails. Concretely: - Reads that stay within `n` behave exactly like the underlying body. - The read that would cross `n` returns an error of concrete type `*http.MaxBytesError`. That type has a `Limit int64` field holding the limit that was exceeded, so an error message can name the number the caller has to respect. Match it with `errors.As(err, &tooLarge)` where `tooLarge` is a `*http.MaxBytesError` — never by string comparison. - It takes the `ResponseWriter` as its first argument precisely so it can tell the server the request was over-sized. The server then stops trying to consume the remainder of the body before writing the reply and does not keep the connection alive for reuse — otherwise the server would sit there draining the very flood you just rejected. - The returned value is an `io.ReadCloser`, so it is a drop-in replacement for `r.Body`. ## How it is used The idiom is to reassign `r.Body` at the very top of the handler (or in middleware, or with `http.MaxBytesHandler`, which wraps a whole handler with a cap), then decode: ```go r.Body = http.MaxBytesReader(w, r.Body, 1<<20) ``` Order matters. The cap constrains *reads that happen after it*. Wrapping the body after something has already read it into memory accomplishes nothing at all — the allocation is already on the heap. ## What it does not do **It does not send a response.** Many handlers get this wrong and return 400 for an over-sized body, or return 500 because the error fell through to a generic branch. The handler must inspect the error and write `http.Error(w, ..., http.StatusRequestEntityTooLarge)` — status 413 — so the caller learns that the body, not its content, was the problem. **It does not limit structure.** A byte cap says nothing about how many objects that byte count expands into once decoded. A megabyte of deeply nested arrays decoded into an `any` becomes a very large number of small heap objects; a byte cap bounds the input, not the decoded graph. **It is not `Server.MaxHeaderBytes`.** That field bounds the request line and headers the server will accept before the handler ever runs; it has nothing to do with the body. **It is not `io.LimitReader`.** `io.LimitReader` reports a plain `io.EOF` at its limit, which a decoder cannot distinguish from a body that genuinely ended — the request comes back as a syntax error, not as "too large". `http.MaxBytesReader` exists to give an HTTP server a distinguishable, typed failure. ## Choosing the number The limit is a capacity decision, not a style choice: the worst-case memory a body cap allows is roughly the cap multiplied by the number of requests in flight, so 1 MB across 500 concurrent requests is half a gigabyte of body bytes before decoding costs are counted. Pick a number from the observed size distribution of real payloads with headroom, apply it per route where a route legitimately needs more, and document it so a 413 is diagnosable by the caller rather than mysterious.