blackbull.middleware.static

blackbull.middleware.static

Static-file middleware.

Import registers additional MIME types process-wide. Usage, containment and cache visibility contracts are in docs/guide/static-files.md.

StaticFiles

Serve files from one directory, as route middleware or on its own.

app.static(url_prefix, root_dir) attaches it to a route; called with three arguments instead of four it is a plain ASGI app that can be mounted anywhere. The difference shows up on a miss: with a call_next the request continues down the chain, and without one it is answered 404.

Only GET and HEAD are served. A resolved path outside the root is a 400, checked after symlinks are followed, so a link pointing out of the tree does not escape it. Under BLACKBULL_ENV=production nothing is served at all — a production deployment is expected to have a proxy or CDN in front, and two things serving the same files is the problem being avoided.

What a hit produces depends on the request and on what is on disk. ETag and Last-Modified are emitted unless conditional is off, and a matching If-None-Match / If-Modified-Since gets a 304 without the body being read. A Range request gets a 206, or a 416 when the range is unsatisfiable. A precompressed sibling (app.js.br, .zst, .gz) is served in place of the original when the client accepts that encoding and the request is not a range request; those responses carry Vary: Accept-Encoding. Files larger than four megabytes stream in chunks rather than being read whole, so peak memory does not follow file size.

docs/guide/static-files.md covers the choices this leaves open — the opt-in cache in particular, and why it is off by default.

__init__(directory=None, *, url_prefix='', root_dir=None, cache=False, index=None, conditional=True)

Serve directory or root_dir; at least one must be supplied.

index=None disables directory indexes. cache=True holds small bodies in a bounded per-worker cache; its validation TTL can delay on-disk edits. conditional=False disables validators and 304 responses. See docs/guide/static-files.md for cache, traversal and production-mode limits.