{"id":5753,"library":"brotli-asgi","title":"Brotli ASGI Middleware","description":"brotli-asgi is an ASGI middleware that provides Brotli response compression for ASGI applications like Starlette and FastAPI. It offers faster and more dense compression than GZip, making it a drop-in replacement for the GZipMiddleware. As of v1.6.0, it remains actively maintained with periodic updates for dependencies and occasional feature enhancements.","status":"active","version":"1.6.0","language":"en","source_language":"en","source_url":"https://github.com/fullonic/brotli-asgi","tags":["asgi","middleware","compression","brotli","fastapi","starlette"],"install":[{"cmd":"pip install brotli-asgi","lang":"bash","label":"Install Brotli-ASGI"}],"dependencies":[{"reason":"Runtime dependency for ASGI application integration.","package":"starlette","optional":false},{"reason":"Core library for Brotli compression algorithm.","package":"brotli","optional":false}],"imports":[{"symbol":"BrotliMiddleware","correct":"from brotli_asgi import BrotliMiddleware"}],"quickstart":{"code":"from fastapi import FastAPI\nfrom brotli_asgi import BrotliMiddleware\nfrom starlette.responses import JSONResponse\n\napp = FastAPI()\n\napp.add_middleware(\n    BrotliMiddleware,\n    quality=4,        # Compression quality (0-11, higher is slower but denser)\n    mode=\"text\",      # Compression mode: \"generic\", \"text\", or \"font\"\n    minimum_size=400, # Only compress responses larger than this many bytes\n    gzip_fallback=True # Fallback to gzip if 'br' is not in Accept-Encoding\n)\n\n@app.get(\"/\")\nasync def home():\n    return JSONResponse({\"data\": \"a\" * 4000})\n\n# To run this example, you would typically use uvicorn:\n# uvicorn your_module_name:app --reload","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to brotli-asgi version 1.4.0 or newer.","message":"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.","severity":"breaking","affected_versions":"<1.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.3.0 (for behavior change), <1.0.0 (for Starlette version reliance)"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}