Context API reference

A categorized index of every Context method for request reading, response writing, and connection control.

This is the lookup table for *celeris.Context — every method grouped by what it does, with its signature, a one-line behaviour note, and a link to the guide that explains it with examples. If you are learning the API for the first time, read the guides instead; come here when you already know what you want and just need the exact signature or a refresher on an edge case.

Every method below lives on *celeris.Context, the single value your handler receives:

func handler(c *celeris.Context) error {
    id := c.Param("id")
    return c.JSON(200, map[string]string{"id": id})
}

Source files: request readers are in celeris/context_request.go, response writers in celeris/context_response.go, flow control and the per-request store (Next/Abort/Set/Get/Context) in celeris/context.go, the Cookie/Param/SameSite types in celeris/types.go, and the error sentinels in celeris/errors.go.

Cross-cutting rules

These apply to almost everything below. Read them once; the tables assume them.

1. Request line and params

The method, path, matched route, query string, and protocol — plus URL parameter accessors. Guide: Handling requests and Routing.

s.GET("/users/:id", func(c *celeris.Context) error {
    id, err := c.ParamInt("id")
    if err != nil {
        return celeris.NewHTTPError(400, "id must be an integer")
    }
    page := c.QueryInt("page", 1)        // ?page=2 → 2; missing → 1
    return c.JSON(200, map[string]int{"id": id, "page": page})
})

Param* reads route captures (/users/:id); Query* reads the ?key=value string. Path() is the concrete request path, FullPath() is the pattern.

2. Headers, cookies, and body

Read request headers, the content length, request cookies, and the raw body. Guide: Handling requests.

func logBody(c *celeris.Context) error {
    body := c.BodyCopy() // safe to keep after the handler returns
    go audit(body)
    return c.Next()
}

Use Body() for synchronous work inside the handler; switch to BodyCopy() the moment the bytes outlive the request (async, logging, goroutines).

3. Binding and forms

Deserialize the body into a struct, or read URL-encoded / multipart form fields. Guide: Binding and validation.

type CreateUser struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

func create(c *celeris.Context) error {
    var in CreateUser
    if err := c.Bind(&in); err != nil {
        if errors.Is(err, celeris.ErrEmptyBody) {
            return celeris.NewHTTPError(400, "request body required")
        }
        return celeris.NewHTTPError(400, "invalid body")
    }
    return c.JSON(201, in)
}

FormValueOk exists as a deprecated alias for FormValueOK — prefer the capitalized form.

4. Identity and connection metadata

Who is calling, over what scheme, and on what connection. Guide: Handling requests.

func ipAllowlist(c *celeris.Context) error {
    if !allowed(c.ClientIP()) {
        return c.AbortWithStatus(403)
    }
    return c.Next()
}

ClientIP() is only trustworthy behind a proxy when you set Config.TrustedProxies (or use the proxy middleware), otherwise the leftmost X-Forwarded-For entry is attacker-controllable. See Security middleware.

5. Writing the response

Status, serializers, raw blobs, headers, cookies, redirects, and file serving. Every writer is write-once and returns ErrResponseWritten on a second call (and ErrDetached after Detach). Guide: Sending responses.

Status

Body serializers

func get(c *celeris.Context) error {
    u, ok := lookup(c.Param("id"))
    if !ok {
        return c.NoContent(404)
    }
    return c.Status(200).StatusJSON(u) // or simply c.JSON(200, u)
}

Response headers and cookies

Serving files

//go:embed assets/*
var assets embed.FS

s.GET("/logo.png", func(c *celeris.Context) error {
    c.Inline("logo.png")
    return c.FileFromFS("assets/logo.png", assets)
})

For untrusted, user-supplied paths use FileFromDir — File and FileFromFS open the path directly and are vulnerable to traversal if you pass raw input. See Static files.

Buffering and capturing (for middleware)

These let middleware inspect or rewrite a downstream response. Guide: Sending responses and Middleware.

6. Streaming and connection control

Incremental writes, taking over the connection, and WebSocket upgrade plumbing. Guides: Streaming responses and Server-Sent Events.

The *StreamWriter returned by StreamWriter() has its own methods:

func sse(c *celeris.Context) error {
    sw := c.StreamWriter()
    if sw == nil {
        return celeris.NewHTTPError(500, "streaming unsupported")
    }
    _ = sw.WriteHeader(200, [][2]string{{"content-type", "text/event-stream"}})

    if c.EngineSupportsAsyncDetach() {
        done := c.Detach()
        go func() {
            defer done() // REQUIRED — or the Context leaks
            defer sw.Close()
            for ev := range events() {
                _, _ = sw.Write(ev)
                _ = sw.Flush()
            }
        }()
        return nil
    }
    // std engine: drive the stream inline until done.
    defer sw.Close()
    for ev := range events() {
        if _, err := sw.Write(ev); err != nil {
            return err
        }
        _ = sw.Flush()
    }
    return nil
}

WebSocket upgrade family

Low-level hooks for engine-integrated WebSocket support. Most applications use the WebSocket middleware rather than these directly; install all SetWS* callbacks before Detach.

7. Flow control

Drive (or stop) the middleware chain. Guide: Middleware.

func requireAuth(c *celeris.Context) error {
    if !authenticated(c) {
        return c.AbortWithStatus(401) // stops the chain, sends 401
    }
    return c.Next() // run the rest of the chain
}

A middleware that calls Next() wraps the downstream handlers; one that just returns (without Next()) lets the engine advance the chain for it. Don’t call Next() twice in one middleware. See Middleware.

8. Per-request store

A scratch map for passing values from middleware to downstream handlers within a single request. The store is cleared when the Context returns to the pool.

func tagTenant(c *celeris.Context) error {
    c.SetString("tenant", lookupTenant(c.Host()))
    return c.Next()
}

func handler(c *celeris.Context) error {
    tenant, _ := c.GetString("tenant")
    return c.JSON(200, map[string]string{"tenant": tenant})
}

Prefer SetString/GetString for string values — they avoid the per-call interface boxing that Set/Get incur.

9. Request lifecycle and metadata

The standard library request context, the request ID, timing, and a release hook. Guide: Observability.

func handler(c *celeris.Context) error {
    select {
    case <-c.Context().Done(): // deadline hit, or HTTP/2 stream reset
        return c.Context().Err()
    case res := <-doWork(c):
        return c.JSON(200, res)
    }
}

c.Context() carries deadlines you attach (via SetContext) and is cancelled by an HTTP/2 stream reset — but it does not fire on a plain HTTP/1.1 client disconnect: Done() never closes when an H1 peer goes away. To detect a disconnected client while streaming, check the error returned by StreamWriter.Write/Flush rather than relying on ctx.Done(). Use Context() for deadlines and H2 cancellation; use the stream-writer error for H1 disconnect detection. OnRelease is for releasing per-request resources (close a checked-out connection, decrement a gauge) without a defer in every handler.

The Cookie type

SetCookie takes a *celeris.Cookie (celeris/types.go:48-71):

c.SetCookie(&celeris.Cookie{
    Name:     "session",
    Value:    token,
    Path:     "/",
    MaxAge:   3600,
    Secure:   true,
    HTTPOnly: true,
    SameSite: celeris.SameSiteLaxMode,
})

Error sentinels

Match these with errors.Is (celeris/errors.go):

if err := c.JSON(200, payload); err != nil {
    if errors.Is(err, celeris.ErrResponseWritten) {
        // an earlier handler already replied — nothing to do
        return nil
    }
    return err
}

HTTPError (returned by FormFile, File*, Stream, etc.) is a struct, not a sentinel — build one with celeris.NewHTTPError(code, message) and match it with errors.As. See Error handling.

Common pitfalls

• 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 *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) / c.NoContent(404) / a regular writer.
• Double writes. The second response writer returns ErrResponseWritten. If you might write from both middleware and handler, gate on IsWritten().
• Forgetting done() after Detach. The Context leaks from the pool forever. Always defer done() in the spawned goroutine.
• Stream is not streaming. It buffers the whole reader (≤ 100 MB). For incremental output use StreamWriter. See Streaming responses.
• Detach then a normal writer. After Detach, JSON/Blob/etc. return ErrDetached. Write through StreamWriter or the WebSocket/SSE write fns.

FAQ

Param vs Query vs FormValue? Param reads route captures (/users/:id), Query reads the URL query string (?page=2), FormValue reads a parsed request body (url-encoded or multipart).

Why are my header keys lowercase? HTTP/2 mandates lowercase header names, so Celeris normalises everywhere. Header lowercases the key you pass, and the response setters lowercase what they store — read and write with any casing, but expect lowercase back.

Which response method should I default to? JSON(code, v) for APIs, String/HTML for text, Blob when you control the content type and bytes, Respond when the client’s Accept header should decide.

How do I keep the body after the handler returns? BodyCopy() (not Body()), and never keep the *Context. See Handling requests.

See also

• Handling requests — reading method, path, headers, body, and identity with examples.
• Sending responses — serializers, headers, cookies, and the buffer/capture model.
• Binding and validation — Bind* and form parsing in depth.
• Streaming responses and Server-Sent Events — StreamWriter, Detach, and long-lived connections.
• Routing — path patterns and the Param* accessors.
• Error handling — HTTPError and the error safety net.