Runtime

The runtime layer runs your bootstrap on an App, serves connections, and drains work on shutdown.

App#

App extends Router with shutdown signaling and shutdown-aware task tracking; the protocol dispatches through its compiled route table. serve or Server constructs the instance; bootstrap(app, span) receives that object. App() requires a running event loop — do not construct it at import time.

Process settings are in Configuration. Static files are in Files and assets.

Application lifecycle#

Bootstrap must be an async generator with exactly one yield. Code before yield runs at startup; code after runs during teardown. The framework advances the generator with anext() so server failures in the scoped body do not enter teardown through generator .athrow().

Synchronous def bootstrap without yield, coroutine-only bootstrap, and multi-yield generators are rejected with StarioError.

from collections.abc import AsyncIterator

from pathlib import Path

from stario import App, Assets, Context, Route, Span, Writer

HOME = Route("GET /")

ASSETS = Assets(Path("static"), "/static")

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

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

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

    app.add(HOME, home)

    await ASSETS.attach(app)

    yield

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

Pass that function to serve() — asyncio.run(serve(bootstrap)) in main.py, or uvloop.run(serve(bootstrap)). Use span.attr, span.attrs, span.event, and span.step during bootstrap while wiring routes or opening resources.

After bootstrap, each inbound message runs the handler its route resolved to: request span, route resolution, error handling, and w.end() on success, or w.abort() when headers were sent and an error occurred. Handlers use c and w, not the bootstrap span. Shutdown timing is documented under Server — Shutdown sequence. For file-watched reload during development, see Hot reload.

Exception handling#

When a handler or middleware lets an exception propagate, two of Stario's own exceptions answer themselves before the response starts: RedirectException calls w.redirect, and RequestBodyError calls w.text with its 413 or 408 status. ClientDisconnected aborts with no response body.

Your own exception types map through catch_errors middleware — see Error handling. Use the w.* methods for intentional bodies in the handler.

RedirectException validates location when w.redirect runs. An unsafe URL records failure on the request span and falls back to 500.

ClientDisconnected is raised when the peer closes while the request body is still uploading. For long-lived responses, prefer c.closing or c.alive() over catching this exception in every path.

StarioError and StarioRuntime are not registered on App; if they propagate uncaught before headers are sent, the client receives 500.

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

from stario import App, Context, Span, Writer

from stario.http.middleware import catch_errors

class OrderNotFound(Exception):

    pass

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

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

async def bootstrap(app: App, span: Span):

    app.use("/", catch_errors(OrderNotFound, respond=order_not_found))

    yield

Shutdown-aware tasks#

app.create_task(coro) schedules the coroutine and retains the resulting asyncio.Task until it completes. Server awaits that set during shutdown alongside open connections, sharing graceful_shutdown_timeout.

app.shutting_down is true once signal_shutdown() runs — from a signal handler, a worker thread, or TestClient. await app.shutdown attaches the calling loop on first use and completes when signal_shutdown() runs — use it inside tasks started with app.create_task when you need cooperative teardown without a Writer.

Bare asyncio.create_task is not tracked and may be orphaned on shutdown. Prefer app.create_task for bootstrap loops and request-adjacent background work.

await app.drain_tasks() waits until every create_task work item finishes (common in tests after the HTTP response returns). Do not call it from inside a tracked task or you risk deadlock.

serve#

serve(bootstrap, *, config=None, tracer=None) is the async in-process entry. It builds a Server and serves until SIGINT, SIGTERM, or app.signal_shutdown(). It does not start an event loop — wrap it with the implementation you want:

import asyncio

from stario import serve

if __name__ == "__main__":

    asyncio.run(serve(bootstrap))

Use uvloop.run(serve(bootstrap)) for uvloop. On an existing loop, await serve(bootstrap).

When config is omitted, serve() calls ServerConfig.from_env() and the STARIO_* variables apply; a ServerConfig you pass is used as-is and the environment is not read. When tracer is omitted, serve() reads STARIO_TRACER via tracer_from_env() and scopes that tracer to the call. A tracer you pass in must already be entered; serve() does not close it. Server always takes an open tracer and a ServerConfig.

Server#

Server is the asyncio listener around an App instance. It creates the app, runs bootstrap through bootstrap_run, binds TCP or Unix, handles signals, serves until SIGINT/SIGTERM, then drains connections and tasks before socket teardown.

stario.serve is the usual embedding path. Server.serve() is the async method it awaits. Enter a tracer you pass in; the server does not close it.

import asyncio

from stario import ServerConfig

from stario.http.server import Server

with tracer:

    asyncio.run(Server(bootstrap, tracer, config=ServerConfig(port=9000)).serve())

One Server instance supports one serve() — create a new instance to restart.

server.event_loop on the startup span is the loop that is actually running (asyncio or uvloop).

With config.threads > 1 (STARIO_THREADS), Server runs that many SO_REUSEPORT listeners — one event loop per OS thread, all sharing the one App. >1 requires free-threaded Python 3.14t, or STARIO_THREADS_ALLOW_GIL=1 as an opt-in on a GIL build. config.pin_threads (STARIO_PIN_THREADS) pins each worker to a CPU where the OS allows. signal_shutdown() wakes every attached loop, so all workers drain together.

Bootstrap contract#

bootstrap_run(bootstrap, app, span) enters startup (anext on the user generator), yields for the server scope, then advances the generator once more for teardown. If startup raises before yield, post-yield teardown does not run. See stario.http.bootstrap for the exact error messages when yield is missing or duplicated.

Shutdown sequence#

On SIGINT or SIGTERM, Server stops accepting new connections and drains work before bootstrap teardown — the code after yield. The window is graceful_shutdown_timeout from Configuration, default five seconds. Total wall time can exceed that value by up to about one second during force-close.

1. Stop accepting — the listener closes; in-flight connections remain.

2. Close idle keep-alive sockets — connections with no active handler close immediately, so drain does not wait on idle peers.

3. Graceful wait — until open connections and app.create_task work finish, or the timeout elapses. A second SIGINT/SIGTERM during this phase sets urgent drain mode: it short-circuits the remaining graceful wait, while force-close and task cancellation still run.

4. Force-close — remaining transports are closed in a loop capped at min(graceful_shutdown_timeout, 1s).

5. Cancel stragglers — pending app.create_task coroutines are cancelled.

6. Bootstrap teardown — the generator after yield runs; close pools, flush clients, and so on.

The shutdown span records server.shutdown.open_connections, server.shutdown.urgent, server.shutdown.idle_closed, server.shutdown.force_closed, server.shutdown.stale_connections, and server.shutdown.cancelled_tasks, then a server.shutdown.closed event.

Long-lived handlers should use c.alive() or check c.closing / app.shutting_down so SSE and relay loops exit during phase 3. Background work started with app.create_task is awaited in the same drain window.