Middleware reference¶
This page lists the public API of django_bolt.middleware. For a task-based introduction, see Middleware, CORS, Rate limiting and Compression.
Each name on this page is in django_bolt.middleware. BaseMiddleware, Middleware, MiddlewareProtocol, TimingMiddleware, LoggingMiddleware, ErrorHandlerMiddleware, DjangoMiddleware, CompressionConfig and the five decorators are also in django_bolt.
Where middleware goes¶
| Place | Argument | Accepts |
|---|---|---|
BoltAPI |
middleware: list \| None = None |
Middleware classes, DjangoMiddleware, DjangoMiddlewareStack, cors and rate_limit dicts |
BoltAPI |
django_middleware: bool \| list[str] \| dict \| None = None |
See load_django_middleware |
BoltAPI |
compression: CompressionConfig \| None \| False = None |
See CompressionConfig |
Router |
middleware: list \| None = None |
The same as BoltAPI(middleware=...) |
| A route | @middleware(...) |
The same, plus function middleware |
Errors. TypeError for an instance of a middleware class, a class with no __call__, a function middleware outside a route, or an entry of another kind.
ValueError for a dict with no type, or with a type that is not "cors" or "rate_limit".
Python middleware¶
Middleware¶
class Middleware(ABC):
def __init__(self, get_response: GetResponse) -> None: ...
async def process_request(self, request: Request) -> Response: ... # abstract
The base class of a Bolt middleware. Override process_request. Call await self.get_response(request) to run the rest of the chain and the handler.
Return its result, a response object such as JSON, or another value that a handler can return.
get_response() returns an object with status_code: int and headers, a dict whose names ignore letter case.
Bolt makes the instance with the next item of the chain as get_response, and reuses it for many requests.
BaseMiddleware¶
class BaseMiddleware(ABC):
exclude_paths: list[str] | None = None
exclude_methods: list[str] | None = None
def __init__(self, get_response: GetResponse) -> None: ...
async def process_request(self, request: Request) -> Response: ... # abstract
Middleware with two class attributes. A request that matches one of them goes to get_response() and skips process_request.
| Attribute | Description |
|---|---|
exclude_paths |
Path patterns. * matches one segment, with no /. ** matches any text. The pattern matches the whole path. |
exclude_methods |
Method names, in any case |
MiddlewareProtocol¶
A class with __init__(self, get_response) and async __call__(self, request). A class of this form needs no base class. Middleware and BaseMiddleware implement it.
GetResponse is the type of get_response: Callable[[Request], Awaitable[Response]]. MiddlewareType is the type of an entry of a middleware list.
TimingMiddleware¶
A BaseMiddleware. It sets request.state["request_id"] to a new UUID4 string and request.state["start_time"] to time.perf_counter().
It adds the response headers X-Request-ID and X-Response-Time, for example 0.0012s.
LoggingMiddleware¶
LoggingMiddleware(
get_response,
logger: logging.Logger | None = None,
log_body: bool = False,
log_headers: bool = False,
log_level: int = logging.INFO,
)
A BaseMiddleware. It logs a Request: {...} line and a Response: ... line for each request. The default logger is django_bolt.requests.
exclude_paths is ["/health", "/metrics", "/docs", "/openapi.json"]. With log_headers=True, it logs all request headers, also Authorization.
To change an argument, subclass it and pass the value to super().__init__().
This class is not the Rust access log of Bolt. See Logging.
ErrorHandlerMiddleware¶
A BaseMiddleware. It logs an unhandled exception to the django_bolt.errors logger and raises HTTPException(500).
The detail is "Internal Server Error", or the traceback when debug is True. An HTTPException or a validation error passes through.
Decorators¶
Put each decorator below the route decorator. A decorator above it raises TypeError at startup.
middleware¶
@middleware(*middleware_classes)
@middleware(type="cors" | "rate_limit", **options)
@middleware # on a function (request, call_next)
Adds middleware to one route.
- With classes or wrappers, it adds them in order. The first argument runs first.
- With keyword arguments, it adds one dict config.
typeis"cors"or"rate_limit", and the options are the keys of the dict configs. - On an async function
(request, call_next), it returns a route decorator.call_next(request)runs the rest of the chain.
With more than one @middleware on a route, the decorator nearest to the function runs first.
Errors. TypeError for a keyword argument with no type, an entry that is not a middleware, or an option of the wrong type.
ValueError for an unknown type, an option that @cors or @rate_limit refuses, or a second cors or rate_limit config on the function.
skip_middleware¶
Removes middleware from one route. A name ignores letter case.
| Name | Removes |
|---|---|
"cors", "rate_limit", "compression" |
The built-in Rust middleware of that name |
A class, its __name__ or its dotted path |
That Python middleware or Django middleware class |
The __name__ or the dotted path of a function |
That function middleware |
"*" |
Each Bolt middleware, Python and Rust. Not Django middleware. |
@skip_middleware does not remove authentication or guards.
Errors. TypeError for a value that is not a str or a class.
no_compress¶
The same as @skip_middleware("compression"). The route sends no Content-Encoding, for buffered and streaming responses.
cors¶
@cors(
origins: list[str] | str | None = None,
methods: list[str] | None = None,
headers: list[str] | None = None,
credentials: bool = False,
max_age: int = 3600,
origin_regexes: list[str] | str | None = None,
)
Gives one route its own CORS config. Rust adds the headers.
| Parameter | Default | Description |
|---|---|---|
origins |
None |
The allowed origins. ["*"] allows each origin. A string is one origin. |
origin_regexes |
None |
Patterns of allowed origins, in the syntax of the Rust regex crate. Start with ^ and end with $. |
methods |
None |
The methods of a preflight answer. None means GET, POST, PUT, PATCH, DELETE, OPTIONS, QUERY. |
headers |
None |
The request headers of a preflight answer. None means Content-Type, Authorization. |
credentials |
False |
Send access-control-allow-credentials: true |
max_age |
3600 |
The access-control-max-age of a preflight answer, 0 to 4294967295 |
The origins and patterns of the route replace CORS_ALLOWED_ORIGINS and CORS_ALLOWED_ORIGIN_REGEXES. An option that you do not give gets its default, not the value of a setting.
With "*" and credentials=True, Bolt copies the Origin of each request into the answer, and warns with RuntimeWarning.
Errors. ValueError for no origin and no pattern, an empty pattern, a pattern that does not compile, a max_age out of range, a name that is not valid in a header, or a second cors config on the function.
TypeError for an origin or a pattern that is not a str, methods or headers that is not a list of str, a credentials that is not a bool, or a max_age that is not an int.
rate_limit¶
Limits one route with a token bucket in Rust.
| Parameter | Default | Description |
|---|---|---|
rps |
100 |
Tokens added each second. An int of 1 or more. |
burst |
None |
The size of the bucket. None means 2 * rps. An int of 1 or more. |
key |
"ip" |
"ip", "user", "api_key", or the name of a request header. The names have no case. |
A rejected request gets 429 with the headers Retry-After, X-RateLimit-Limit (rps) and X-RateLimit-Burst (burst), and this body:
"ip" uses the client address from BOLT_TRUSTED_PROXIES. An IPv6 client counts per network of BOLT_RATE_LIMIT_IPV6_PREFIX bits (64).
"user" and "api_key" run after authentication. A request with no identity counts per client address. A header key counts all requests with no such header in one bucket.
Errors. TypeError for an rps or burst that is not an int, or a key that is not a str. ValueError for a count less than 1, an empty key, a key that is not a header name, or a second rate_limit config on the function.
Startup raises ValueError for "user" or "api_key" on a route with no auth backend.
Dict configs¶
The API, a router and @middleware(...) take a cors or a rate_limit config as a dict. Each key is a keyword argument of the decorator, plus type.
type |
Keys |
|---|---|
"cors" |
origins, origin_regexes, methods, headers, expose_headers, credentials, max_age |
"rate_limit" |
rps, burst, key |
expose_headers is a list of response headers that the page can read. Only the dict form has it.
A dict of a route needs origins or origin_regexes. A dict of an API or a router with neither keeps the allow list of the outer config.
The most specific config of each type wins: the route, then the router, then the API. A None value is a missing value.
Errors. The checks of the decorator, and TypeError for an unknown key.
CompressionConfig¶
@dataclass
class CompressionConfig:
backend: Literal["gzip", "brotli", "zstd"] = "brotli"
minimum_size: int = 500
gzip_fallback: bool = True
brotli_level: int = 5
brotli_lgwin: int = 14
gzip_level: int = 6
zstd_level: int = 3
The compression config of the server.
| Field | Default | Description |
|---|---|---|
backend |
"brotli" |
The encoding that Bolt uses when the client accepts it |
minimum_size |
500 |
The smallest buffered body, in bytes, that Bolt compresses. No effect on a stream. |
gzip_fallback |
True |
Use gzip when the client does not accept backend |
brotli_level |
5 |
0 to 11. Streaming responses only. |
brotli_lgwin |
14 |
10 to 24. The window is 2 ** brotli_lgwin bytes for each stream. Streaming responses only. |
gzip_level |
6 |
0 to 9. Streaming responses only. |
zstd_level |
3 |
1 to 22. Streaming responses only. |
A buffered response uses fixed levels: brotli 3 with a 4 MiB window, gzip 1 and zstd 3.
The server uses one config. settings.BOLT_COMPRESSION wins when it is set. None or False there turns compression off.
Otherwise the server uses the compression of the first API with compression on. BoltAPI(compression=False) turns it off for that API.
Errors. ValueError for an unknown backend, a negative minimum_size, or a level out of range. BoltAPI(compression=...) raises TypeError for a value that is not a CompressionConfig, None or False. BOLT_COMPRESSION raises ImproperlyConfigured for such a value.
Django middleware¶
DjangoMiddleware¶
Runs one Django middleware class in a Bolt middleware list. A string is the dotted path of the class. Bolt passes init_kwargs to the constructor of the class.
Bolt runs process_request, process_view, process_template_response, process_response and process_exception, and the __call__ of a new-style middleware.
process_view gets the handler as the view. On a request thread (a lane), Bolt makes a second instance of the class in sync mode.
Errors. TypeError for a callable that is not a class. ImportError for a dotted path that does not import. RuntimeError for a class with sync_capable and async_capable both false.
DjangoMiddlewareStack¶
Runs a list of Django middleware classes as one Bolt middleware, in the hook order of Django: each process_request, then each process_view, then each process_response in reverse order.
It converts the request and the response one time for the whole list. An entry can be a dotted path.
Errors. The same as DjangoMiddleware.
load_django_middleware¶
load_django_middleware(config: bool | list[str] | dict = True, *, exclude_defaults: bool = True) -> list
BoltAPI(django_middleware=config) calls it. It returns a list with one DjangoMiddlewareStack, or an empty list.
config |
Classes |
|---|---|
True |
Each entry of settings.MIDDLEWARE, in order |
False or None |
None |
| A list of dotted paths | These classes, in this order. They need not be in settings.MIDDLEWARE. |
{"include": [...]} |
The entries of settings.MIDDLEWARE that are in the list, in the order of the setting |
{"exclude": [...]} |
The entries of settings.MIDDLEWARE that are not in the list |
With exclude_defaults=True, it also leaves out DEFAULT_EXCLUDED_MIDDLEWARE, an empty set.
Errors. ImproperlyConfigured for an entry that is not a dotted path string. ImportError for a path that does not import.
get_django_middleware_setting¶
Returns a copy of settings.MIDDLEWARE, or [].