Changelog¶
Every release, newest first, with what is merged but not yet released at the
top. While the version is 0.x, a minor release may change the API and a patch
release does not; changes that break existing code are listed under
Breaking in the release that makes them.
0.3.0 — 2026-10-06¶
- Authentication, in
oxbrook.auth.auth=on the app, a router, a route or a WebSocket declares who may call it, and the nearest declaration wins:App(auth=...)protects every route that does not sayauth=None. Shipped schemes areAPIKey,Bearer,JWT,BasicandSessionAuth; anything else is a class with oneasync authenticate(request)method.a | baccepts either,.requires("scope")adds a requirement,optional(...)lets anonymous callers through, and the handler gets the caller withDepends(principal). - The framework enforces the rules an app would otherwise get wrong by hand: a
credential that is present and wrong is refused rather than falling through
to the next scheme or to anonymous access; missing or wrong is
401with aWWW-Authenticatechallenge per scheme, known but not allowed is403; an API key reaches the app as its digest; a JWT's algorithm family, audience, issuer and expiry are always checked, and a refusal says "invalid" or "expired" and nothing finer; tokens in the query string are not looked for; Basic is refused over plain HTTP; no credential reaches a log line. - Authentication runs before the request body is read. A refused upload is
answered before it arrives, and the connection survives the refusal.
Middleware outside the check finds the body unread:
request.bodyraises there, andawait request.read()reads it. - One declaration covers every surface: a WebSocket's
auth=is checked before the handshake, a tool call is checked against its route's declaration with the agent's headers, and the OpenAPI document listssecuritySchemesand each operation'ssecurity. - OpenID Connect providers:
OIDC(issuer, audience=...)checks an identity provider's access tokens against the keys its discovery document names, with presets for Keycloak, Auth0, Entra ID, Okta, Cognito, Google and Firebase. Keys are fetched once per process and kept fresh; a rotated-in key is picked up by the first token that uses it, at most one fetch a minute; only the provider's public-key algorithms are accepted, each with its own kind of key; an unreachable provider is503, not401.await scheme.load()fetches the keys at startup. - Roles, apart from scopes:
Principal.roles, filled from a claim named byroles_claim=onJWTandOIDC, and checked by.requires(roles=...). A role never satisfies a scope requirement, or the other way round.claims=on both requires claims to have given values. JWTandOIDCremember a verified token until it expires, so an RSA signature is checked once per token rather than once per request (cache_size=,0to turn it off).- Breaking:
SessionAuthrefuses cross-site requests. A state-changing request authenticated by a session cookie must carrySec-Fetch-Site: same-origin, anOriginnaming the server or one oftrusted_origins(the CORS origins by default), or, with neither header, anX-CSRF-Tokenequal toSessionAuth.csrf_token(session); anything else is403. A script that posts with a session cookie and noOriginnow needs the token.csrf=Falseturns it off. - WebSocket tickets:
Tickets().issue(principal)from an authenticated call, then?ticket=...on the socket URL. Single use, thirty seconds, read only from an upgrade: the one credential allowed in a URL. - Agents see only what they may call, and can log in by themselves.
tools/listleaves out tools whose declaration would refuse the caller.App(mcp_auth=...)gives/mcpa declaration of its own. With anOIDCprovider, the app serves OAuth protected-resource metadata (RFC 9728) at/.well-known/oauth-protected-resource/mcp, and a401from/mcppoints there, so an MCP client finds the provider, gets a token and retries. - Logging people in:
OAuthLoginruns the authorization-code flow with PKCE against an identity provider and leaves a session forSessionAuth.routes(prefix="/auth")gives/auth/login,/auth/callbackand/auth/logout;on_login(request, login)receives aLogin(the provider's subject, email, whether it was verified, the ID token's claims and the tokens) and returns what the session keeps. Presets for Google, Microsoft (any tenant, one tenant, work or personal accounts), GitHub and Keycloak, andOAuthLogin(issuer, ...)for any OpenID Connect provider.stateandnonceare checked and single-use, the callback'sissis checked,nextis followed only to a local path, the session is emptied before the login goes in, and logout is refused across sites. A failed login isLoginFailed. TestClient.call_tool()takesheaders=.- A response header can repeat: a list as a header's value sends it once per item.
Dependsworks on WebSocket handlers. It raisedTypeErroron every connection.-
TestClient.websocket()takesheaders=. -
Every error is RFC 9457 problem details,
application/problem+json, whichever side answered it: anHTTPError, a validation failure, a missing route, a wrong method, a body over the limit, a server at capacity, a timeout, a handler that raised. A client parses one format for all of them.HTTPErrortakestype=,title=,instance=andextensions=; an exception handler can answer by raising one. -
request.locals, a dict for one request alone, where middleware leaves something for a handler or a dependency — the caller it authenticated, a request id.request.stateis shared by every request on a worker loop, so it could never hold that. A tool call starts with a copy of the/mcprequest's. -
A dependency's teardown now sees how the request ended. A generator dependency is finished the way a
withblock is: resumed after itsyieldif the handler returned, and with the handler's exception raised there if it did not. It used to be closed, which raisesGeneratorExitat theyieldevery time — soasync with db.transaction(): yield dbrolled back on every successful request and nothing a handler wrote was kept, while the client was told it succeeded. And an exception raised during teardown, such as a commit that fails, was logged while the handler's200went out; it is now the request's outcome, and exception handlers apply to it. -
One JSON encoding everywhere. A handler's return, a
Reply, anHTTPErrordetail, SSE, WebSockets, durable topics and MCP tool results all encode by pydantic's rules, which models already followed. A plain return of adatetime,UUID,Decimal, enum, database row or list of models was a500and now encodes; timestamps are ISO 8601,Decimala string, NaNnull. -
A database guide, with
examples/database/: asyncpg with a pool per worker loop, a transaction per request, driver errors as responses, SQLAlchemy, and Alembic migrations that are safe for several replicas to run at once. Every part of it is run against PostgreSQL by the test suites, andmake verifynow requires PostgreSQL as it does Redis. -
app.per_worker(total)andapp.workers, for sizing anything aworker_lifespanopens. That hook runs once per worker loop, so a pool written there is multiplied by a loop count the code never chose — and asyncpg's default pool, opened eagerly, is ten connections per loop, which is eighty on an eight-loop host against a PostgreSQL allowing a hundred.per_workerdivides a process-wide budget across the loops, rounding down, and refuses a budget too small to share. The lifespan guide now shows this. -
blocking=Trueon a route runs a plaindefhandler on a threadpool instead of its worker loop. A handler that takes time without awaiting — a sync database driver,requests,boto3, Pillow — freezes every other request its loop is serving; measured, eight such handlers on four loops made an unrelated request wait 1829 ms, and 4 ms with the route declared blocking. The pool is one per process, bounded, sized withapp.run(blocking_threads=…), and starts no thread until a blocking handler runs. A blocking handler cannot be cancelled, so a client that leaves frees the loop but not the thread. Adefhandler on a route that does not declare it is still refused, and the error now names the fix. -
The MCP endpoint speaks both of the protocol's transports. A client that probes with
server/discovergets the 2026-07-28 wire: self-contained requests, no handshake, no session, andsubscriptions/listenanswered with a stream. A client that does not falls back to the handshake wire, whereinitializeissues anMCP-Session-Id, aGETon/mcpopens a server-to-client stream and aDELETEends the session. Both on the one endpoint; neither needs configuring. - An agent can follow a topic rather than polling it, over either wire. The same declaration already serving browsers and WebSocket clients now feeds agents.
Originis validated on every request to/mcp, and a foreign origin is refused with403unless CORS already allows it.- Breaking: the handshake wire now requires a session, so a client that
posted
tools/callto/mcpwithout callinginitializefirst receives400.TestClient.mcp()andTestClient.call_tool()handle this themselves and are unchanged;TestClient.mcp()also takesheaders=now. - Breaking: a value with no JSON form inside a
Reply, anHTTPErrordetail or an MCP tool result is refused with a500, as a plain return always was, rather than sent as itsstr(). The same values inside aReplyalso change form to match a plain return: adatetimeis"2026-09-23T10:00:00Z"rather than"2026-09-23 10:00:00+00:00", an enum is its value rather than"Color.red", and NaN isnullrather than the invalid bareNaN. - Breaking: error bodies change shape.
{"detail": "..."}is now{"type": "about:blank", "title": "...", "status": ..., "detail": "..."}with content typeapplication/problem+json; a422's list moves fromdetailtoerrors, andRequestValidationError.errorsreads it from there. Errors that weretext/plain—404,405,413,426,500,503,504— are problem details too.HTTPError'sdetailmust now be a string, with data inextensions=; with nodetailgiven the body has none, where it used to repeat the status phrase. OpenAPI documents the422asValidationProblem. - Breaking: an exception raised in a dependency's teardown is now the request's outcome rather than a log line, and a dependency that yields twice is an error rather than a logged warning.
- Two handlers with the same name, such as
list_itemson two routers, no longer make the OpenAPI document invalid: each gets its method and path added to itsoperationId. A handler whose name is unique keeps it as before.
0.2.0 — 2026-09-21¶
- Windows, on both interpreter builds, with x86-64 wheels:
pip installand run, with no WSL2 and no container. Ctrl-C, Ctrl-Break and the console closing all shut the server down gracefully, andoxbrook run --reloadstops its server with Ctrl-Break so a reload still drains and still runs lifespan teardown. Windows is a development platform here: nothing on the site is measured there. - A refusal decided before the request body is read — no such route, wrong
method, a path parameter that will not coerce, a body over
max_body, no capacity — now reads the body away briefly before answering. The client gets the answer rather than a connection reset, and the connection survives to carry the next request. - Static mounts refuse names that Windows resolves to something other than a
file under the mount: a drive-relative segment such as
C:passwd, a device name such asCONorNUL, and names ending in a dot or a space. Refused on every platform, so a mount answers the same everywhere.
0.1.0 — 2026-09-16¶
The first release.
REST
Appwithget,post,put,patch,deleteandroutedecorators; handlers areasync def.- A radix-tree router per method. Path and query parameters typed by
annotations —
str,int,float,bool,uuid.UUID,datetime.date,datetime.datetime,list[T]— coerced in Rust, with422before a worker is woken. - Pydantic request and response bodies; forms with
Form(); multipart uploads withUploadFile;BodyStreamfor bodies larger than memory. Routerwith prefixes, nesting and its own middleware.- Middleware,
HTTPError, exception handlers,Dependswith teardown. lifespanper process andworker_lifespanper worker loop.- Signed cookie sessions, CORS, static files with ranges and conditional requests, OpenAPI 3.1 and a documentation page.
Serving
- HTTP/1.1 and HTTP/2; HTTPS with
tls_certandtls_key. - Worker loops on free-threaded CPython 3.14, one loop on the standard build.
max_concurrency,max_connections,max_body,max_message,request_timeoutandshutdown_grace; graceful shutdown onSIGINTandSIGTERM.- Handlers are cancelled when their client leaves before they answer, unless
the route passes
cancel_on_disconnect=False. - The
oxbrookcommand, also installed asoxb:runwith--reload,routes,openapi. - Logging through the standard
loggingmodule, with a JSON formatter and an access log.
Streams
Topicwith fan-out across worker loops and four backpressure policies.SSEresponses and@app.websocketendpoints, with an authorizer that runs before the handshake and an origin check on by default.- Durable topics over Redis with
App(redis_url=...): persisted messages,history(), shared across processes, and consumer groups.
Agents
tool=Trueexposes a route over the Model Context Protocol at/mcp.
Testing
oxbrook.testing.TestClient, which runs the real server, over HTTP or HTTPS.