From b8b2790ff3f20d3286183159bf2de21a46c855bd Mon Sep 17 00:00:00 2001 From: Albert Bausili Date: Tue, 10 Nov 2026 16:05:07 +0100 Subject: [PATCH] docs: request strings are views of the receive buffer on the native engines; RequestHeaders is not a copy (Refs celeris#891) request-handling.md, core-concepts.md and context-api-reference.md called RequestHeaders() a safe-to-retain copy, said x := c.Param("id") copies, and named only Body() and Header() as views. Per celeris doc.go (celeris#920): every request string is a view of the receive buffer on epoll, io_uring and Adaptive over HTTP/1.1, valid until the handler returns; copy with strings.Clone. After Hijack (HTTP/1.1 only) the request strings stay valid, including those read before the call; Detach copies the values the Context holds but not the strings you already read out of it. --- src/content/docs/context-api-reference.md | 4 +- src/content/docs/core-concepts.md | 43 +++++++++++++----- src/content/docs/request-handling.md | 55 ++++++++++++++++------- 3 files changed, 74 insertions(+), 28 deletions(-) diff --git a/src/content/docs/context-api-reference.md b/src/content/docs/context-api-reference.md index 8f171ec..1cba0ae 100644 --- a/src/content/docs/context-api-reference.md +++ b/src/content/docs/context-api-reference.md @@ -33,7 +33,7 @@ These apply to almost everything below. Read them once; the tables assume them. | Rule | What it means | | ---- | ------------- | -| **Context is pooled** | The `*Context` is recycled across requests. Never retain it, and never retain a slice it returns (`Body()`, `RequestHeaders()`, `ResponseHeaders()`) past the handler return — copy first. See [Handling requests](/docs/request-handling). | +| **Context is pooled** | The `*Context` is recycled across requests. Never retain it, and never retain a slice it returns (`Body()`, `RequestHeaders()`, `ResponseHeaders()`) past the handler return — copy first. The request strings (`Param`, `Header`, `Path`, …) are views of the receive buffer on the native engines (`Epoll`, `IOUring`, `Adaptive`) over HTTP/1.1: `strings.Clone` one to keep it. See [Handling requests](/docs/request-handling). | | **Header keys are lowercase** | `Header(key)` lowercases the key for you; response setters lowercase + strip CR/LF/NUL. Both `Header("Content-Type")` and `Header("content-type")` work, but stored keys are always lowercase (HTTP/2 mandates it). | | **Write-once** | The first response method (`JSON`, `Blob`, `NoContent`, `Redirect`, `File*`, `StreamWriter`, …) wins. A second call returns `ErrResponseWritten`. `IsWritten()` reports whether the response has been sent. | | **Status setter is separate** | `Status(code)` stores a code for the `Status*` helpers only. The regular writers (`JSON(code, v)`, `Blob(code, …)`) take their own code and ignore the stored one. | @@ -512,7 +512,7 @@ sentinel — build one with `celeris.NewHTTPError(code, message)` and match it w - **Retaining pooled slices.** `Body()`, `RequestHeaders()`, and `ResponseHeaders()` return views into recycled buffers. Copy (`BodyCopy()`, or a - manual copy) before using them after the handler returns. Never stash the + manual copy) before using them after the handler returns; the same holds for the request strings (`strings.Clone`). Never stash the `*Context` itself. - **`Status(code)` does not write anything.** It only feeds the `Status*` helpers. `c.Status(404)` alone sends nothing; you still need `c.StatusJSON(v)` / diff --git a/src/content/docs/core-concepts.md b/src/content/docs/core-concepts.md index 3f4fc35..ce3f206 100644 --- a/src/content/docs/core-concepts.md +++ b/src/content/docs/core-concepts.md @@ -188,14 +188,27 @@ frameworks that allocate a fresh request object per request. | Returns a view into pooled memory (do **not** retain) | Returns a safe-to-retain copy | | --- | --- | | `c.Body()` — raw request body | `c.BodyCopy()` — fresh copy of the body | -| `c` itself | `c.RequestHeaders()` — copy of all headers | - -String getters (`c.Param`, `c.Header`, `c.Path`, `c.Method`, …) are fine to -*use* inside the handler, but their bytes may be backed by the connection's read -buffer — assign the `string` into your own structure before letting it outlive -the request (a Go `string` copy is just `x := c.Param("id")`). - -The two methods documented for cross-request lifetimes are explicit about it in +| `c.RequestHeaders()` — all headers, valid until the handler returns | `strings.Clone(x)` — a copy of a request string | +| `c.Param`, `c.Header`, `c.Path`, `c.Method`, `c.Query`, … — request strings | | +| `c` itself | | + +The string getters (`c.Param`, `c.Header`, `c.Path`, `c.Method`, …) are fine to +*use* inside the handler, but on the `Epoll`, `IOUring` and `Adaptive` engines over +HTTP/1.1 they are **views of the connection's receive buffer**, not copies. The +engine reuses that buffer for the connection's next request and, once the +connection closes, for another connection, so a string you kept reads other +request bytes, possibly another client's. Assigning it is not a copy: +`x := c.Param("id")` is the same view. Copy it with `strings.Clone` before it +outlives the request: a map key or cache entry, a goroutine or channel, a closure, +a log record the logger may keep, a metric label or a span attribute. +`c.Detach()` copies the values the `Context` holds, not the strings you already +read out of it, and on HTTP/2 it copies neither the headers nor the body. After +`c.Hijack()` (HTTP/1.1 only) the request strings stay valid, including the ones +read before the call: the engine does not give a hijacked connection's receive +buffer to another connection. On every engine the contract is the same: valid +until the handler returns. + +The accessors documented for cross-request lifetimes are explicit about it in source: - `c.BodyCopy()` (`celeris/context_request.go`): "returns a copy of the request body that @@ -204,7 +217,15 @@ source: logging)." `Body()` itself warns the slice "must not be modified or retained after the handler returns." - `c.RequestHeaders()` (`celeris/context_request.go`): "returns all request headers as - key-value pairs. The returned slice is a copy safe for concurrent use." + key-value pairs. Treat the slice as read-only and valid until the handler returns: + on HTTP/1.1 it is the request's own header slice (on HTTP/2 a copy of it), and on + epoll, io_uring and Adaptive the names and values are views of the connection's + receive buffer (see the package documentation). Copy what you keep." It is not a + safe-to-retain copy. +- The package documentation of `celeris` (`celeris/doc.go`) states the rule for the request + strings: they are valid until the handler returns, and on the native engines + over HTTP/1.1 they are views of the receive buffer, so copy one with `strings.Clone` + before anything keeps it past the handler. ```go func enqueue(c *celeris.Context) error { @@ -432,7 +453,7 @@ pooled `Context`, run the pre-baked chain, recycle the `Context`. - **Retaining the Context or its body.** The number-one bug. Anything you pass to a goroutine that outlives the handler must be copied first — use `c.BodyCopy()` - and `c.RequestHeaders()`. See [The Lifetime Rule](#3-the-context-is-pooled). + for the body and `strings.Clone` for a request string or header value. See [The Lifetime Rule](#3-the-context-is-pooled). - **Calling `Use` after routes.** Panics by design. Register all middleware before any route. Same for group `Use`/`Async`/`Sync`, which only affect routes registered after the call. @@ -451,7 +472,7 @@ pooled `Context`, run the pre-baked chain, recycle the `Context`. **Is a `Context` safe to use concurrently within a single request?** No. A `*Context` is single-goroutine by default. If you fan out work, copy the -data you need (`BodyCopy`, `RequestHeaders`) and pass the copies. For long-lived +data you need (`BodyCopy`, `strings.Clone` of the strings) and pass the copies. For long-lived hijacked connections, use `c.Detach()`. **Can I restart a `Server` after `Shutdown`?** diff --git a/src/content/docs/request-handling.md b/src/content/docs/request-handling.md index 987d289..4d8c823 100644 --- a/src/content/docs/request-handling.md +++ b/src/content/docs/request-handling.md @@ -21,21 +21,41 @@ The `Context` is pooled and reused across requests. **Anything that hands back a view into request memory is only valid until your handler returns.** Once the handler returns, the underlying buffers may be recycled for the next request. -This affects exactly two accessors: +This affects the body, the headers, and every string the request hands back: | Accessor | Returns | After handler returns | | --- | --- | --- | | `Body()` | The raw body bytes (zero-copy) | Invalid — may be overwritten | -| `Header(key)` | A header value (substring of the parsed buffer) | Invalid — may be overwritten | +| `Header(key)`, `RequestHeaders()` | A header value, or the header slice (names and values are views of the receive buffer) | Invalid — may be overwritten | +| `Method()`, `Path()`, `Param(key)`, `Query(key)`, `RawQuery()`, `Cookie(name)`, `Host()`, `ClientIP()` and strings derived from them | A request string | Invalid on the native engines over HTTP/1.1 — may read other request bytes (see below) | If you need request data to outlive the handler — async processing, a background -goroutine, deferred logging — copy it first. Two accessors are explicitly -documented as safe to retain: +goroutine, deferred logging — copy it first. One accessor hands you a copy for the +body: -| Safe-to-retain accessor | Returns | +| Accessor | Returns | | --- | --- | | `BodyCopy()` | A fresh heap copy of the body (`[]byte`) | -| `RequestHeaders()` | A copy of all headers as `[][2]string`, safe for concurrent use | + +For a request string, copy it with `strings.Clone` (see the next section). There is +no accessor that returns all the headers as a copy: copy the entries you keep. + +### Request strings are views of the receive buffer + +On the `Epoll`, `IOUring` and `Adaptive` engines over HTTP/1.1, the strings above +are not heap copies: they point into the connection's receive buffer. The engine +reuses that buffer for the connection's next request and, once the connection +closes, for another connection. A string you kept then reads other request bytes, +possibly another client's, and nothing panics or warns. Reading and comparing a +string during the request is fine; copy it with `strings.Clone` before anything +keeps it past the handler: a map key or cache entry, a goroutine or channel, a +closure, a log record the logger may keep, a metric label or a span attribute. +`Detach` copies the values the `Context` holds, but not what you read out of it +before the call or values you stored with `Set` (on HTTP/2 it does not copy the +headers and the body either). After `Hijack` the request's strings stay valid, +including those read before it. See their reference for the details. On every +engine the contract is the same, valid until the handler returns: do not rely on a +copy having been made for you. ```go s.POST("/ingest", func(c *celeris.Context) error { @@ -50,10 +70,13 @@ s.POST("/ingest", func(c *celeris.Context) error { }) ``` -A plain `string(c.Body())` or `c.Header("...")` value you use *within* the -handler is fine — Go copies the bytes into the new string. The rule only bites -when you keep a `[]byte` slice or pass the `Context` itself somewhere that -outlives the request. +A plain `string(c.Body())` you use *within* the handler is fine, and it is a +copy: converting a `[]byte` to a `string` copies the bytes. A string that an +accessor returns (`c.Header("...")`, `c.Param("id")`, `c.Path()`) is **not** +copied by assigning it to a variable: `x := c.Param("id")` is the same view. +The rule bites when you keep one of those strings, keep a `[]byte` slice, or +pass the `Context` itself somewhere that outlives the request; keep +`strings.Clone(x)` instead. ## The request line @@ -152,8 +175,8 @@ cached map. | Method | Behavior | | --- | --- | -| `c.Header(key)` | First value for `key`; **key is lowercased**, value not safe to retain | -| `c.RequestHeaders()` | A copy of all headers as `[][2]string`; safe to retain | +| `c.Header(key)` | First value for `key`; **key is lowercased**, value not safe to retain (`strings.Clone` it to keep it) | +| `c.RequestHeaders()` | All headers as `[][2]string`; read-only, valid until the handler returns (names and values are views of the receive buffer on the native engines over HTTP/1.1), not safe to retain | | `c.ContentLength()` | `Content-Length` as `int64`, or `-1` if absent or invalid | ```go @@ -357,9 +380,11 @@ for larger multipart uploads. Both are described in ## Common pitfalls -- **Retaining `Body()` or a `Header()` value past the handler.** These point - into recycled buffers. Use `BodyCopy()` / `RequestHeaders()` if the data must - outlive the request, and never stash the `*Context` itself. +- **Retaining `Body()`, a `Header()` value, `RequestHeaders()` or any request + string (`Param`, `Path`, `Query`, ...) past the handler.** These point into + recycled buffers. Use `BodyCopy()` for the body and `strings.Clone` for a + string (copy the `RequestHeaders()` entries you need) if the data must outlive + the request, and never stash the `*Context` itself. - **Trusting `QueryInt` to validate.** It returns your default on garbage input rather than an error. Parse the raw `Query` value yourself when malformed input should be a `400`.