Routing Reference ¶

Routing maps HTTP methods and paths to handlers. Stario uses a predictable, order-based router.

Basic Usage ¶

app = Stario(tracer)

app.get("/", home)
app.post("/users", create_user)
app.get("/users/*", get_user)  # Catch-all

Route Types ¶

Sub-Routers & Mounting ¶

Group related routes with Router and mount them at a prefix.

api = Router()
api.get("/users", list_users)
api.get("/users/*", get_user)

app.mount("/api/v1", api)
# Results in: /api/v1/users and /api/v1/users/*

Middleware ¶

Middleware wraps handlers and can be applied at the app, router, or route level.

# App-level (all routes)
app.use(logging_middleware)

# Router-level (all routes in this router)
api = Router()
api.use(auth_middleware)

# Per-route (right-to-left execution)
app.get("/admin", admin_page, auth_middleware, rate_limit)

Error Handlers ¶

Handle exceptions globally or by type.

def handle_404(c: Context, w: Writer, exc: HttpException):
    w.html(Div("Not Found"), status=404)

app.on_error(HttpException, handle_404)

Static Assets ¶

Serve fingerprinted assets with one line:

app.assets("/static", Path(__file__).parent / "static")

# Use in code
href = f"/static/{asset('css/style.css')}"

Matching Rules ¶

1. Registration Order: Routes are matched in the order they were registered.
2. Exact vs Catch-all: Exact paths are checked first.
3. Longest Prefix: For nested routers, the longest matching prefix wins.