Responses

This page covers Writer (status, headers, body, streaming, compression), stario.responses helpers, and cookies (set_cookie, delete_cookie). Long-lived handlers coordinate disconnect and shutdown through c.alive() on Context, not on Writer.

Import helpers from their module:

import stario.responses as responses

Writer

The framework builds a Writer for each request and passes it as the second argument to your handler (async def handler(c: Context, w: Writer)). The app and HTTP stack own construction, disconnect futures, compression policy, and the transport hook — do not call Writer(...) in normal application code.

w turns decisions into bytes on the wire: status line, response headers, optional cookies, and the message body.

Response phases

HTTP separates three layers you control in order:

1. Status code — outcome for this response (200, 404, 307, …).

2. Headers — metadata on w.headers before the response starts (Content-Type, Cache-Control, Location, Set-Cookie, …).

3. Body — zero or more bytes after the header block (Content-Length or chunked Transfer-Encoding).

Typical sequence:

• Set values on w.headers while w.started is false.

• Call write_headers(status_code) once to send the status line and headers.

• Send the body with write(data) (repeat for streaming) and finish with end() (optionally passing a last chunk).

• respond(body, content_type, status=200) combines negotiation, Content-Type, Content-Length, headers, and body when the full body is already bytes. content_type is bytes (e.g. b"text/plain; charset=utf-8").

stario.responses helpers perform the right sequence for common cases.

Setting headers (examples)

from stario import Context, Writer

import stario.responses as responses

async def with_cache(c: Context, w: Writer) -> None:

    w.headers.set("Cache-Control", "public, max-age=3600")

    responses.html(w, "<p>Hello</p>")

async def stream_lines(c: Context, w: Writer) -> None:

    w.headers.set("Content-Type", "text/plain; charset=utf-8")

    w.write_headers(200)

    for line in ("one", "two", "three"):

        w.write((line + "\n").encode("utf-8"))

    w.end()

Cookie helpers live in stario.cookies; they mutate w.headers via Set-Cookie. See Cookies.

Once headers are on the wire

After write_headers (or any path that flushes headers), you cannot change status or add headers for that exchange. Log the error, record it on c.span, and clean up server-side; the peer only sees what was already sent.

Read-only state

On w: started, completed, status_code, and closing (transport closing or closed).

On c: disconnected, shutting_down, and closing (handler work should stop when the client left or the app is draining). See Context.

App.__call__ finishes the message in finally with w.end(), or w.abort() if headers were sent and an error occurred.

Compression

Compression policy comes from ServerConfig.compression (Configuration). The writer negotiates with Accept-Encoding; supported tokens are weighted by q values; among ties Stario prefers brotli, then zstd, then gzip. Bodies below min_size skip compression on whole-body (respond) paths; chunked streams negotiate without a minimum body size. Incompressible Content-Type values skip compression on both paths.

Two framing paths matter:

• Content-Length set before write_headers — non-chunked body; bytes written are sent as-is without automatic Content-Encoding on that path.

• No Content-Length before write_headers — chunked transfer; streaming compressor may set Content-Encoding / Vary.

respond() may compress the full body in one pass, then set Content-Length to the compressed size. If Content-Encoding is already set on w.headers, automatic negotiation is skipped.

Response helpers

Module stario.responses wraps Writer with helpers that set status, content type, and headers, write the body (or set up redirects and empty bodies), and finish the response in one call.

html accepts pre-encoded bytes, a str, or Stario markup (HtmlElement) rendered via stario.markup.render. text is for human-readable str only — for arbitrary bytes (files, images), use w.respond(data, b"application/octet-stream") or stream with write_headers + write. redirect requires a 3xx status; json requires JSON-serializable values; unsafe redirect URLs raise StarioError from normalized_location.

For conditional GET (304), set cache validators on w.headers before calling empty:

w.headers.set("ETag", etag)

responses.empty(w, 304)

redirect uses normalized_location for URL safety before setting the Location header. empty sends a zero-length body.

Cookies

Read inbound cookies from c.req.cookies on the request. Write outbound cookies with stario.cookies.set_cookie(w, …) and stario.cookies.delete_cookie(w, …).

delete_cookie must use the same path, domain, secure, httponly, and samesite values as the original set_cookie so browsers match and clear the cookie.

import stario.responses as responses

from stario import Context, Writer

from stario import cookies

async def login(c: Context, w: Writer) -> None:

    token = "..."

    cookies.set_cookie(w, "sid", token, httponly=True, secure=True, path="/app")

    responses.empty(w)

There is no get_cookie on stario.cookies — read c.req.cookies.get("sid") instead.

cookies.set_cookie(w, "sid", token, secure=True, httponly=True, path="/app")

cookies.delete_cookie(w, "sid", secure=True, httponly=True, path="/app")