Swarmauri Middleware Cachecontrol

Middleware for managing HTTP cache headers and client-side caching behavior.

Features

• Configurable max_age that controls how long clients may cache responses.
• Toggle caching on or off at runtime with the enabled flag.
• Adds Cache-Control, timestamp-based ETag, and Vary: Accept-Encoding headers to successful responses.
• Inspects If-Modified-Since and If-None-Match request headers to short-circuit unchanged responses with 304 Not Modified.

Installation

Install the package with your preferred Python packaging tool:

pip install swarmauri_middleware_cachecontrol

poetry add swarmauri_middleware_cachecontrol

uv pip install swarmauri_middleware_cachecontrol

Usage

CacheControlMiddleware accepts two primary configuration options:

• max_age: Maximum cache lifetime (in seconds) communicated to clients. Defaults to 3600.
• enabled: When False, the middleware skips all cache headers and lets responses pass through untouched. Defaults to True.

When enabled, the middleware injects cache headers into outgoing responses and mirrors conditional request headers to return 304 Not Modified when the client already has fresh content. Integrate it with FastAPI or Starlette by instantiating the middleware once and delegating to its dispatch method from an @app.middleware("http") handler.

Example

The snippet below shows how to register the middleware with FastAPI and inspect the generated headers using TestClient:

from fastapi import FastAPI, Request
from fastapi.testclient import TestClient

from swarmauri_middleware_cachecontrol import CacheControlMiddleware

app = FastAPI()
cache_control = CacheControlMiddleware(max_age=60)


@app.middleware("http")
async def apply_cache_control(request: Request, call_next):
    return await cache_control.dispatch(request, call_next)


@app.get("/status")
def status() -> dict[str, str]:
    return {"state": "fresh"}


def main() -> None:
    client = TestClient(app)
    response = client.get("/status")
    response.raise_for_status()

    print("Cache-Control:", response.headers["Cache-Control"])
    print("ETag:", response.headers["ETag"])
    print("Vary:", response.headers["Vary"])
    print("Payload:", response.json())


if __name__ == "__main__":
    main()

Want to help?

If you want to contribute to swarmauri-sdk, read up on our guidelines for contributing that will help you get started.