App¶
App
¶
App(
title: str = "Oxbrook",
version: str = "0.1.0",
description: str = "",
openapi_url: str | None = "/openapi.json",
docs_url: str | None = "/docs",
mcp_url: str | None = "/mcp",
debug: bool = False,
access_log: bool = False,
redis_url: str | None = None,
lifespan: Any = None,
worker_lifespan: Any = None,
cors: CORS | None = None,
websocket_origins: Any = None,
auth: Any = None,
mcp_auth: Any = UNSET,
)
openapi_url and docs_url can each be set to None to disable them.
debug returns handler exception text in the 500 response. Leave it off
outside development: exception messages routinely carry connection
strings, file paths and user data.
access_log adds one log line per request. Opt-in: it costs something
per request, and many deployments already log at the proxy.
redis_url enables durable topics. Nothing connects until the first
durable topic is used.
mcp_url is where agents reach the service over the Model Context
Protocol. It exposes only routes marked tool=True, plus topics as
readable resources. Set it to None to turn the endpoint off entirely.
lifespan runs once around the server's life and worker_lifespan runs
on every worker loop; what they yield is request.state. Two, because
a connection pool belongs to the loop that made it and a server has
several loops. See the lifespan guide.
cors lets pages on other origins call the app from a browser. Applied
in Rust, to every response including the ones no handler produced.
websocket_origins lists the other origins whose pages may open a
WebSocket. Browsers do not apply CORS to sockets and send cookies with
the handshake, so without a check any website could open an
authenticated socket as the user. A socket is accepted with no
Origin (not a browser), from this server's own origin, or from a
listed one; anything else is refused with 403 before an authorizer or
handler runs. Left unset, the list is the CORS origins, excluding *.
["*"] turns the check off.
auth protects every route that does not declare its own, including
WebSockets and MCP tool calls; a route that should stay public says
auth=None. See oxbrook.auth. The OpenAPI document and the docs page
stay public; turn them off with openapi_url=None and docs_url=None
if the API's shape is not for everyone.
mcp_auth guards the MCP endpoint itself, apart from auth: who may
connect, list tools, and read topics as resources. Each tool is still
guarded by its own route's declaration, and the tool list shows a
caller only the tools it may call. Left unset, /mcp follows auth.
When either names an OIDC provider, the endpoint also serves OAuth
protected-resource metadata, and a 401 from it points there, so an
MCP client can find where to log in.
Source code in python/oxbrook/_app.py
50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 | |
worker_lifespan
instance-attribute
¶
route
¶
route(
method: str,
path: str,
tool: bool = False,
*,
cancel_on_disconnect: bool = True,
blocking: bool = False,
auth: Any = UNSET,
)
Register a route.
auth declares who may call it, overriding its routers' and the app's;
auth=None makes it public. See oxbrook.auth.
blocking=True lets the handler be a plain def and runs it on a
threadpool instead of its worker loop. A worker loop serves many
requests at once by interleaving them at every await, so a handler
that takes time without awaiting — a sync database driver,
requests, boto3, Pillow — freezes every other request that loop is
serving. Declaring the route blocking is what keeps it off the loop,
and it is opt-in so that the cost is visible where the route is.
The threadpool is shared by the whole process and bounded, so blocking calls queue rather than multiplying threads. A blocking handler cannot be cancelled once it has started: a thread inside a blocking call cannot be interrupted, so a client that leaves frees the loop but not the thread.
tool=True also exposes it to agents over MCP. Opt-in on purpose:
every route being agent-callable by default would mean an
administrative delete endpoint is agent-callable by default.
A handler is cancelled when its client disconnects, or its request
times out, before it has answered: asyncio.CancelledError is raised
at the handler's next await, and finally blocks and dependency
teardown run as usual. Its answer could no longer reach anyone, and
left running it would hold a worker's capacity for nothing. Wrap a
step that must finish in asyncio.shield, or pass
cancel_on_disconnect=False to let the whole handler run to the end.
Once a handler has answered — including a stream that has started —
this no longer applies.
Source code in python/oxbrook/_app.py
get
¶
post
¶
post(
path: str,
tool: bool = False,
*,
cancel_on_disconnect: bool = True,
blocking: bool = False,
auth: Any = UNSET,
)
Source code in python/oxbrook/_app.py
put
¶
static
¶
static(
prefix: str,
directory: Any,
*,
index: str | None = "index.html",
fallback: str | None = None,
dotfiles: bool = False,
cache_control: str | None = None,
) -> None
Serve the files in directory under the URL prefix.
app.static("/assets", "public")
app.static("/", "frontend/dist", fallback="index.html")
Served in Rust, streamed from disk, with conditional and range requests answered. A file request never wakes a Python worker, and middleware does not run for it.
index is served for a directory; None makes directories 404. A path
naming a directory without its trailing slash is redirected to it.
fallback is served, with status 200, for a page load under the prefix
that matches no file: no file extension, and Accept including
text/html, as a browser sends when loading a page. That is how a
single-page app's client-side routes load. A missing app.js is still
404, and so is a mistyped API call from fetch, which does not ask for
HTML.
dotfiles allows files and directories whose names start with a dot.
Off by default: .env and .git are the files most likely to sit in a
static directory by accident.
cache_control sets that header on every file served.
directory resolves from the working directory when relative, and must
exist now. Paths that leave the directory — .., encoded or not, or a
symlink pointing outside it — are answered 404.
Source code in python/oxbrook/_app.py
patch
¶
patch(
path: str,
tool: bool = False,
*,
cancel_on_disconnect: bool = True,
blocking: bool = False,
auth: Any = UNSET,
)
Source code in python/oxbrook/_app.py
delete
¶
delete(
path: str,
tool: bool = False,
*,
cancel_on_disconnect: bool = True,
blocking: bool = False,
auth: Any = UNSET,
)
Source code in python/oxbrook/_app.py
include
¶
include(router: Router, prefix: str = '') -> None
Mount a router's routes, under prefix if given.
app.include(users.router, prefix="/api/v1")
Every route is validated against its full path here, and checked against the routes already registered, so a conflict between two modules fails at this call rather than at startup. Include after the router is fully declared: it cannot change afterwards.
Source code in python/oxbrook/_app.py
middleware
¶
Register middleware, which runs around every HTTP handler.
@app.middleware
async def require_key(request, call_next):
if request.header("x-api-key") != SECRET:
return Reply({"error": "unauthorized"}, status=401)
return await call_next(request)
Runs outermost-first in registration order. WebSocket routes are not wrapped: their handshake completes before the handler runs, so there is nothing useful to intercept yet.
Source code in python/oxbrook/_app.py
exception_handler
¶
Register how an exception becomes a response.
@app.exception_handler(LookupError)
async def missing(request, exc):
return Reply({"error": "not found"}, status=404)
Applies to the class and its subclasses; the most specific registered class wins. Raised by a handler, a dependency, body validation, an authorizer or middleware, the exception is mapped before middleware sees the result, so the access log records the real status.
Registering HTTPError or RequestValidationError replaces the
built-in response for it. See oxbrook.HTTPError.
Source code in python/oxbrook/_app.py
per_worker
¶
One worker loop's share of a process-wide budget.
Anything worker_lifespan opens is opened once per loop, so a number
written there is multiplied by however many loops this process runs —
which is decided by the machine, not by the code. A pool of ten on an
eight-loop host is eighty connections, and a database that allows a
hundred has room for one such process.
Say what the process may use and divide it here:
async def worker_lifespan(app):
pool = await asyncpg.create_pool(
DSN, min_size=1, max_size=app.per_worker(40)
)
try:
yield {"db": pool}
finally:
await pool.close()
Rounds down, because going over a budget for connections is the dangerous direction: forty across three loops is thirteen each, not fourteen. A loop cannot have less than one, so a budget smaller than the number of loops cannot be honoured and says so rather than returning zero.
Source code in python/oxbrook/_app.py
websocket
¶
Register a WebSocket endpoint.
auth is checked before the handshake, as for any route, so a caller
who is refused gets a real 401 or 403 rather than a socket that
opens and closes. Browsers cannot set headers on a WebSocket, so for a
page the credential is a cookie — SessionAuth. The check runs when
the socket opens: a connection can outlive the credential that opened
it.
authorize runs after auth, before the handshake, and can refuse the upgrade,
which the handler cannot: by the time it runs, the 101 has been sent
and the client believes it is connected. Return None or True to
accept; raise HTTPError, or return a Response/Reply, to refuse.
async def members_only(request):
if not valid(request.header("authorization")):
raise HTTPError(401, headers={"www-authenticate": "Bearer"})
@app.websocket("/ws", authorize=members_only)
async def feed(request, ws): ...
The handler takes the request and the socket. Oxbrook performs the handshake, so the socket is already open when the handler runs, and the connection closes when it returns.
@app.websocket("/ws")
async def echo(request, ws):
async for message in ws:
await ws.send(message)
Source code in python/oxbrook/_app.py
backend
¶
The shared Redis backend, connected lazily on first use.
Source code in python/oxbrook/_app.py
topic
¶
topic(
name: str,
maxsize: int | None = None,
policy: str | None = None,
durable: bool = False,
) -> Topic
Get or create a named topic.
Shared across every worker loop in the process, so a message emitted by
one handler reaches subscribers running on all of them. durable=True
additionally shares it across processes and records it in Redis, which
needs App(redis_url=...).
maxsize, policy and durable apply only when the topic is first
created.
Source code in python/oxbrook/_app.py
capabilities
¶
The capabilities this service exposes to agents.
Built from the routes marked tool=True, without starting a server, so
it can be inspected or checked into a test.
Source code in python/oxbrook/_app.py
openapi
¶
The OpenAPI 3.1 document for the routes registered so far.
Built from the same metadata the router uses, so it cannot describe an endpoint the server would not accept. Callable without running the server, which makes it usable for client generation in CI.
Source code in python/oxbrook/_app.py
run
¶
run(
host: str = "127.0.0.1",
port: int = 8000,
workers: int | None = None,
max_concurrency: int = DEFAULT_MAX_CONCURRENCY,
max_body: int = DEFAULT_MAX_BODY,
request_timeout: float = DEFAULT_REQUEST_TIMEOUT,
shutdown_grace: float = DEFAULT_SHUTDOWN_GRACE,
max_connections: int = DEFAULT_MAX_CONNECTIONS,
max_message: int = DEFAULT_MAX_MESSAGE,
blocking_threads: int | None = None,
*,
tls_cert: str | PathLike[str] | None = None,
tls_key: str | PathLike[str] | None = None,
http2: bool = True,
) -> None
Serve until interrupted.
max_concurrency bounds the requests a single worker loop will accept
at once, counting both those queued and those already running. When
every worker is at its limit the server answers 503 rather than growing
without bound. Lower it for slow handlers, where a deep backlog only
adds latency before an inevitable client timeout; raise it to absorb
larger bursts of fast requests.
max_body caps a request body; anything larger is answered 413 without
being buffered. max_message does the same for a single WebSocket
message, where the connection is closed rather than answered.
request_timeout is how long to wait for a handler's first response
before answering 504, and the handler is then cancelled unless its route
says cancel_on_disconnect=False. It does not cut short a stream that
has already started, so SSE and WebSocket are unaffected. Zero disables
it.
shutdown_grace is how long Ctrl-C waits for in-flight requests to
finish before stopping anyway.
max_connections caps sockets held open. At the limit the server stops
accepting rather than refusing, so the wait lands in the OS backlog.
tls_cert and tls_key are PEM files, the certificate chain with the
server's certificate first and its private key. Given both, the server
speaks HTTPS only; they are read once, at startup.
http2 serves HTTP/2 alongside HTTP/1.1: negotiated through ALPN over
TLS, and recognised by its opening bytes on a plain connection, where
only clients configured for it will use it. False serves HTTP/1.1
alone.
blocking_threads sizes the one threadpool every blocking=True route
shares. The default is min(32, cpu + 4) — what CPython would give a
single event loop, given to all of them together rather than to each.
Raise it for handlers that mostly wait on a network or a disk; it
bounds how many blocking calls run at once, and the rest queue.
Source code in python/oxbrook/_app.py
build_server
¶
build_server(
host: str = "127.0.0.1",
port: int = 8000,
workers: int | None = None,
max_concurrency: int = DEFAULT_MAX_CONCURRENCY,
max_body: int = DEFAULT_MAX_BODY,
request_timeout: float = DEFAULT_REQUEST_TIMEOUT,
shutdown_grace: float = DEFAULT_SHUTDOWN_GRACE,
max_connections: int = DEFAULT_MAX_CONNECTIONS,
max_message: int = DEFAULT_MAX_MESSAGE,
announce: bool = False,
blocking_threads: int | None = None,
*,
tls_cert: str | PathLike[str] | None = None,
tls_key: str | PathLike[str] | None = None,
http2: bool = True,
)
Prepare a server without starting it.
run uses this; so does the test client, which needs to start the
server on one thread and stop it from another. The lifespans run inside
serve, not here.
Source code in python/oxbrook/_app.py
Router
¶
A group of routes with a shared prefix, middleware and auth=.
auth applies to every route on the router and on routers it
includes, unless one declares its own; a route's auth=None makes it
public even here. See oxbrook.auth.
Source code in python/oxbrook/_routers.py
route
¶
route(
method: str,
path: str,
tool: bool = False,
*,
cancel_on_disconnect: bool = True,
blocking: bool = False,
auth: Any = UNSET,
)
Register a route. See App.route.
Source code in python/oxbrook/_routers.py
get
¶
get(
path: str,
tool: bool = False,
*,
cancel_on_disconnect: bool = True,
blocking: bool = False,
auth: Any = UNSET,
)
Source code in python/oxbrook/_routers.py
post
¶
post(
path: str,
tool: bool = False,
*,
cancel_on_disconnect: bool = True,
blocking: bool = False,
auth: Any = UNSET,
)
Source code in python/oxbrook/_routers.py
put
¶
put(
path: str,
tool: bool = False,
*,
cancel_on_disconnect: bool = True,
blocking: bool = False,
auth: Any = UNSET,
)
Source code in python/oxbrook/_routers.py
patch
¶
patch(
path: str,
tool: bool = False,
*,
cancel_on_disconnect: bool = True,
blocking: bool = False,
auth: Any = UNSET,
)
Source code in python/oxbrook/_routers.py
delete
¶
delete(
path: str,
tool: bool = False,
*,
cancel_on_disconnect: bool = True,
blocking: bool = False,
auth: Any = UNSET,
)
Source code in python/oxbrook/_routers.py
websocket
¶
Register a WebSocket endpoint. See App.websocket.
Source code in python/oxbrook/_routers.py
middleware
¶
Middleware for this router's routes only, inside the app's own.
Covers routes on routers included into this one as well. Like app middleware it wraps a socket's authorizer, not the socket handler.
Source code in python/oxbrook/_routers.py
HTTPError
¶
HTTPError(
status: int,
detail: str | None = None,
headers: dict[str, str] | None = None,
*,
type: str = "about:blank",
title: str | None = None,
instance: str | None = None,
extensions: dict[str, Any] | None = None,
)
Bases: Exception
Raise to answer with an error status.
raise HTTPError(404, "no such user")
raise HTTPError(401, headers={"www-authenticate": "Bearer"})
raise HTTPError(
409,
"a note with that title already exists",
type="https://api.example.com/problems/duplicate",
extensions={"existing_id": 7},
)
The response is RFC 9457 problem details, application/problem+json:
type, title, status, and detail and instance when given, then
any extensions.
detail is sent to the client, so it is for messages written for the
client, and it is a string: data for a program to read goes in
extensions. This is the one exception whose text is returned; an
unhandled exception's never is.
type is a URI naming the kind of problem, for clients that branch on
it. Left as about:blank, the problem means no more than its status, and
title is the status's name.
Source code in python/oxbrook/_errors.py
RequestValidationError
¶
Bases: Exception
A request body failed validation. Carries a ready-to-send JSON body.