Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions src/content/docs/context-api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down Expand Up @@ -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)` /
Expand Down
43 changes: 32 additions & 11 deletions src/content/docs/core-concepts.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 {
Expand Down Expand Up @@ -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.
Expand All @@ -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`?**
Expand Down
55 changes: 40 additions & 15 deletions src/content/docs/request-handling.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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`.
Expand Down
Loading