Runtime

Application

App extends Router with the app entrypoint, error surface, shutdown-aware scheduling, and reverse URLs. The CLI or Server constructs the app; bootstrap(app, span) receives that instance—avoid instantiating App() yourself in normal apps (see Routing for the same pattern). Listener binding and signal handling are documented under Server on this page.

On this page you will find: lifecycle and bootstrap shapes, exception handling and on_error, shutdown-aware tasks, url_for, and static assets below.

Application lifecycle

Bootstrap return shapes at a glance:

• async def bootstrap(app, span) -> None — awaited once; no framework teardown after it returns (unless you use shutdown hooks elsewhere).

• def bootstrap(app, span) -> None — synchronous wiring when you do not need await.

• async def bootstrap(app, span) -> AsyncIterator with exactly one yield — code before yield is startup; code after runs on shutdown.

• Other shapes are normalized via normalize_bootstrap (async context managers, etc.); see the apidoc under Server.

At process level: bootstrap (wire the app before listening), serving, and shutdown. Every bootstrap(app, span) goes through normalize_bootstrap, whether you use Server, stario.testing, or the stario console entry point. Supported return shapes differ in whether a second teardown phase runs after shutdown begins. The normalize_bootstrap apidoc under Server lists every accepted shape, including async context managers.

A synchronous def bootstrap(app: App, span: Span) -> None is supported (no await in the body)—useful for quick wiring when everything you need is synchronous; prefer async def when you need to await setup.

Use span.attr, span.attrs, and span.event during bootstrap while mounting routes or opening resources. The same span object is reused for the whole Server.run() scope, but the startup phase completes with span.end() once the server is running; after that, shutdown logic may repoint span.id to a shutdown span so late telemetry still lands in the right place. See Server.run in the framework source for the exact sequence.

from collections.abc import AsyncIterator

from pathlib import Path

from stario import App, Context, Span, StaticAssets, Writer

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

async def bootstrap(app: App, span: Span) -> None:

    span.attrs({"bootstrap": "await-once"})

    app.mount("/static", StaticAssets(Path("static"), name="static"))

    app.get("/", home, name="home")

async def bootstrap_with_teardown(app: App, span: Span) -> AsyncIterator[None]:

    span.attr("phase", "startup")

    # Open DB pools, clients, …

    yield

    span.attr("phase", "shutdown")

    # Close resources

Point stario serve main:bootstrap (or Server) at whichever function is your real entry (bootstrap or bootstrap_with_teardown above—only one should be the module’s bootstrap export).

Graceful shutdown (typically SIGINT/SIGTERM) stops accepting connections, waits up to graceful_timeout for open connections and for tasks from app.create_task, then closes transports, cancels stragglers, and tears down the listener. Adjust the window on Server (default five seconds). For long request work such as streams or SSE, prefer Writer.alive(). Work that must outlive that wave belongs outside the per-request path or needs an explicit longer grace.

After bootstrap, each inbound message runs App.__call__(context, writer): request span, route resolution, errors, and always writer.end() for keep-alive. Handlers use context and writer, not the bootstrap span.

Exception handling

When a handler or middleware lets an exception propagate, App resolves an on_error handler by walking the exception’s MRO; the most specific registered type wins.

HttpException is the normal way to turn a failed precondition into an HTTP response body (404 text, 400 message, and so on). For redirects (3xx), prefer RedirectException so the Location value is distinct from a body string: from stario import RedirectException, e.g. raise RedirectException(307, "/login"). Both inherit the same default on_error handler (exc.respond(w)). Import from stario import HttpException for non-redirect outcomes (re-exported from stario.exceptions). Replace the default handler only if you want different behavior for every intentional HTTP outcome.

Other errors become a response only while the response has not started (writer.started is false). After the status line and headers are on the wire, the runtime records the failure on the request span and ends the writer; it cannot send a late 5xx or change headers for that exchange.

Use app.on_error for domain or infrastructure types you want mapped to stable responses in one place instead of repeating branches in every handler. Practical patterns: Mapping errors to HTTP responses (how-to) and this Exception handling section.

from stario import App, Context, Span, Writer

import stario.responses as responses

class OrderNotFound(Exception):

    pass

def order_not_found(c: Context, w: Writer, exc: OrderNotFound) -> None:

    responses.text(w, "Unknown order", status=404)

async def bootstrap(app: App, span: Span) -> None:

    app.on_error(OrderNotFound, order_not_found)

Shutdown-aware tasks

app.create_task(coro) schedules the coroutine and adds the resulting asyncio.Task to a set that Server tracks during shutdown. That set shares graceful_timeout with open connections. After the window, remaining tasks are cancelled and awaited with gather(..., return_exceptions=True).

Bare asyncio.create_task is not in that set and is easy to orphan on shutdown. Prefer app.create_task for work that should share the server’s graceful window (bootstrap loops, request-adjacent work). The HTTP stack uses this path for dispatch and pipelining.

Reverse URLs

url_for builds a path (and optional query) from the name= on a route or static mount. It matters most when the public URL is not fixed at authoring time, especially fingerprinted static files. Without name= on a mount, there is no reverse entry. Mount and collision details: Routing, Static assets.

from pathlib import Path

from stario import App, Context, Span, StaticAssets, Writer

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

async def bootstrap(app: App, span: Span) -> None:

    app.get("/", home, name="home")

    app.mount("/static", StaticAssets(Path("./static"), name="static"))

After registration, app.url_for("home") is "/" and app.url_for("static:js/app.js") resolves to the fingerprinted URL (the name="static" on the mount defines the static:… reverse keys).

Server

Server is the asyncio listener around an App instance: it builds the app, runs normalize_bootstrap on bootstrap(app, span), binds TCP or Unix, handles signals, serves until SIGINT/SIGTERM, then shuts down with a shared grace window for connections and app.create_task work, forced close, cancellation of remaining tasks, and bootstrap teardown.

Under the hood

run() creates the app once, opens a startup span, enters bootstrap and _server_scope, calls start_serving, then blocks until shutdown. Shutdown records open connections, force-closed transports, and cancelled tasks on the span. The span passed to bootstrap is the same object for the whole run; when shutdown begins, a linked shutdown span is created and the span id is repointed so late telemetry still attributes correctly (see Application).

If event_loop_name is set (for example via stario --loop), it appears as server.event_loop on startup attributes.

Bootstrap contract

normalize_bootstrap() accepts the return shapes documented under Application lifecycle above and wraps them in one async with for Server, tests, and other callers.

Static assets

StaticAssets scans a directory once at construction (usually from bootstrap with app.mount("/static", StaticAssets(...))). That pass fingerprints files, builds metadata, optionally loads small files into RAM, and registers a catch-all route under the prefix. There is no per-request directory walk.

Fingerprinting

Each file is hashed with xxHash64; the public name is {stem}.{digest}{suffix} with relative paths preserved. Requests for logical paths get a 307 to the fingerprinted URL. Immutable responses use strong cache headers by default. That redirect is what browsers see when they hit the logical path; app.url_for("static:…") emits the fingerprinted path directly so HTML does not pay an extra round trip—same behavior as reverse URLs for named routes.

Reverse URLs for static files

Pass name="static" (or another prefix) so each file has a logical key such as static:js/app.js. app.url_for("static:js/app.js") emits the fingerprinted URL in HTML without an extra redirect (Application). Without name=, files are still served but url_for has no entry.

Compression at startup

Eligible files may be pre-compressed at wire-up. Brotli and zstd are preferred for quality on modern clients; gzip is also generated with configurable levels (defaults in code: zstd 9, brotli 9, gzip 7, with window settings tuned for static assets). Already-compressed types (images, fonts, .woff2, and similar) skip recompression. Large files stay on disk and stream without holding full precompressed blobs.

Mounting

StaticAssets is re-exported from the stario package (same as App, Context, etc.).

from pathlib import Path

from stario import App, Span, StaticAssets

async def bootstrap(app: App, span: Span) -> None:

    app.mount("/static", StaticAssets(Path("./static"), name="static"))