Brotli ASGI Middleware

Warnings

• breaking A security vulnerability (GHSA-3qj8-93xh-pwh2) was addressed in v1.4.0. Users on older versions should upgrade immediately to mitigate potential risks related to underlying Starlette dependencies.
  Fix: Upgrade to brotli-asgi version 1.4.0 or newer.
• gotcha Brotli compression can be CPU-intensive at higher quality settings. While it offers better compression ratios, it might increase latency (Time to First Byte) for highly dynamic content. Consider balancing `quality` and `minimum_size` parameters or pre-compressing static assets.
  Fix: Adjust `quality` (e.g., 3-5 for APIs) and `minimum_size` parameters in `BrotliMiddleware`. For static assets, pre-compression with higher quality is often preferred during build processes.
• gotcha The middleware will not apply compression if a `Content-Encoding` header is already set on the response, to prevent double-encoding. Additionally, the correct double-encoding prevention behavior when using `gzip_fallback=True` requires Starlette version >=0.22.0.
  Fix: Ensure responses do not prematurely set `Content-Encoding` if `brotli-asgi` is expected to compress them. Maintain an up-to-date Starlette version, preferably >=0.22.0, for robust fallback handling. The 'avoid double encode' fix was in v1.3.0.
• gotcha The order of middleware in ASGI applications is critical. Ensure `BrotliMiddleware` is placed appropriately, especially relative to other middleware that might modify response bodies or headers (e.g., authentication, CORS).
  Fix: Carefully review your middleware stack. Generally, compression middleware should be applied early enough to process responses, but after any middleware that generates or significantly alters the response content. Consult your ASGI framework's documentation for middleware ordering best practices.
• gotcha To exclude specific routes or handlers from compression, you typically leverage the ASGI framework's (e.g., Starlette, FastAPI) routing capabilities to apply middleware conditionally or to specific sub-applications/routers, rather than relying on a direct exclusion parameter within `BrotliMiddleware` itself.
  Fix: Refer to your ASGI framework's documentation on applying middleware to specific routes or mounted applications. For example, in Starlette/FastAPI, you can add middleware to a `Router` or `Mount` instead of the main application object.

Install

• pip install brotli-asgi Install Brotli-ASGI

Imports

• BrotliMiddleware

  from brotli_asgi import BrotliMiddleware

Quickstart

This example demonstrates how to integrate `BrotliMiddleware` with a FastAPI application. The middleware is added globally, applying Brotli compression to responses that meet the specified criteria (e.g., minimum size). It also configures a gzip fallback for clients that don't support Brotli.

from fastapi import FastAPI
from brotli_asgi import BrotliMiddleware
from starlette.responses import JSONResponse

app = FastAPI()

app.add_middleware(
    BrotliMiddleware,
    quality=4,        # Compression quality (0-11, higher is slower but denser)
    mode="text",      # Compression mode: "generic", "text", or "font"
    minimum_size=400, # Only compress responses larger than this many bytes
    gzip_fallback=True # Fallback to gzip if 'br' is not in Accept-Encoding
)

@app.get("/")
async def home():
    return JSONResponse({"data": "a" * 4000})

# To run this example, you would typically use uvicorn:
# uvicorn your_module_name:app --reload