blackbull.middleware.static

blackbull.middleware.static

StaticFiles

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

Serve files from directory (or root_dir).

index (default None — off): when set to a filename (e.g. 'index.html'), a request that resolves to a directory is served that file from inside the directory if it exists. Off by default so existing exact-path serving is unchanged; the blackbull serve CLI turns it on to match python -m http.server's directory-index behaviour.

cache (default False): when True, file bodies up to _CACHE_MAX_BYTES_PER_FILE are held in an in-memory OrderedDict (capped at _CACHE_MAX_ENTRIES), and the per-request stat() syscall is throttled by _STAT_TTL_S. When False (the default), every request does a fresh stat() and reads the body from disk — matching the behaviour of Starlette / FastAPI / Flask static serving and the requirement HttpArena's standard-mode rules place on static profiles ("read files from disk on every request, no in-memory caching"). Set cache=True only for standalone deployments where BlackBull terminates static traffic directly (i.e. no nginx / CDN in front).

conditional (default True): emit ETag + Last-Modified validators and honour If-None-Match / If-Modified-Since with a 304. Set False to suppress validators (e.g. the blackbull serve --no-etag path).