Request and context

Context (c) is the per-request bundle your handler receives, and c.req is the inbound Request. Registration, middleware, and c.match are on Routing; outbound bytes are on Responses.

Import Request from stario.http:

from stario.http import Request

Context#

Context is the per-request bundle the framework constructs before your handler runs. You do not instantiate it yourself.

Send the response with w (Writer); read the inbound message from c.req.

alive()#

Long handlers (SSE, slow streams, relay subscribers) should listen for client disconnect and process shutdown. c.closing supports explicit checkpoint loops. async with c.alive(): installs a watcher that cancels the current task when disconnect or app.shutdown completes first (whichever happens first). async for item in c.alive(source): forwards items from an async iterable until the same cancellation path fires.

Exiting alive() suppresses CancelledError only when cancellation came from this watcher, not from unrelated cancellation elsewhere. Do not use async for c.alive() without a source — use the context manager form.

For response I/O during drain, Writer may still write until disconnected is true even when closing is already true.

See Responses for writer phases and Runtime for shutdown timing.

import asyncio

from stario import Context, Writer

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

    async with c.alive():

        while True:

            await asyncio.sleep(0.5)

            # Task is cancelled when the client drops or the server shuts down.

HOME = Route("GET /")

SEND = Route("POST", ROOM + "/send")

app.add(SEND, send)

at.post(SEND.href(room.id))

Request#

Stable view of the request line and headers. The protocol builds it; handlers only read. Reach everything through c.req.

Request fields and accessors#

Body rules#

On body() and stream():

• If Content-Length exceeds the configured maximum, the protocol rejects the message with 413 before your handler runs.

• RequestBodyError(413) if the body exceeds the configured maximum size while reading (default 10 MiB).

• RequestBodyError(408) if idle between chunks exceeds the body read timeout (default 30 seconds). Both RequestBodyError statuses answer themselves with the status and a plain body when nothing was sent.

• ClientDisconnected if the peer closes before the body completes. The connection is aborted without a response body.

Pick one of body() or stream() per request — switching in either direction raises StarioRuntime. You may call body() multiple times after the first read returns the same bytes. A second stream() on the same request also raises StarioRuntime.

Requests with no body (typical GET): body() returns b""; stream() yields no chunks.

Per-route smaller limits: await c.req.body(max_size=65536) only on body() — stream() relies on the server-wide STARIO_REQUESTS_MAX_BODY_BYTES unless you count bytes in the loop.

Forms and JSON bodies#

The body is bytes. Stario does not parse it for you, because the standard library already does. A posted HTML form is application/x-www-form-urlencoded:

from urllib.parse import parse_qs

form = parse_qs((await c.req.body()).decode())

email = form.get("email", [""])[0]

A JSON body goes through the same codec w.json uses:

import stario.json as stario_json

payload = stario_json.loads(await c.req.body())

Validate the result with the library you already use. A Datastar request carries its signals as JSON; read those with read_signals on Datastar. Multipart uploads are on User uploads.

ParsedQuery#

c.req.query is a ParsedQuery, not a flat dict. Repeated keys are preserved.

• query.get("key") — first value or default.

• query.getlist("key") — every value for the key.

• query.as_dict() — one string per key; first value wins by default (same as get). Pass last=True to keep the last value.

• query.as_lists() — full multi-value map.

Use as_dict() or as_lists() when validating the whole query (for example with Pydantic).

Cookie response headers use stario.cookies with w (Cookies).