alti3/litestar-caching

Caching

Execution Workflow

1. Identify handlers whose responses are deterministic, expensive, and safe to replay.
2. Choose the route-level cache mode: cache=True, an explicit TTL in seconds, or CACHE_FOREVER.
3. Set app-level ResponseCacheConfig for default_expiration, store selection, and global key/filter behavior.
4. Design cache keys around every dimension that changes the payload: path, query params, method, tenant, locale, auth scope, feature flags, or headers.
5. Decide how stale data is controlled for mutable resources: short TTL, explicit delete, or versioned keys.
6. Verify hits, misses, and stale-data behavior with tests before treating the cache as production-safe.

Core Rules

• Cache only responses that are safe to reuse for another equivalent request.
• Prefer short, explicit TTLs for mutable data.
• Treat cache=True as "use ResponseCacheConfig.default_expiration", not as "cache forever."
• Use CACHE_FOREVER only for truly immutable or explicitly versioned resources.
• Never cache personalized or permission-scoped responses unless the cache key fully partitions that context.
• Keep key builders deterministic and stable across processes.
• Use cache_response_filter to control which responses are written to cache after the status code is known.
• Do not assume Litestar provides automatic write-side invalidation for your domain objects; design it deliberately.

Decision Guide

• Use cache=True when the app-wide default TTL is correct for the route.
• Use cache=<seconds> when a route needs a specific freshness window.
• Use CACHE_FOREVER when the payload is immutable, content-addressed, or versioned externally.
• Use app-level ResponseCacheConfig for baseline TTL, default key builder, named store selection, and response-write filtering.
• Use route-level cache_key_builder= when one handler needs extra key dimensions without changing the whole app.
• Keep the default key builder when the response varies only by method, path, and query params.
• Override the key builder when the response varies by headers, tenant, locale, auth identity, or feature flags.
• Use a distributed store such as Redis when multiple app instances must share cache state.

Reference Files

Read only the sections you need:

• For route-level cache modes, ResponseCacheConfig, default expiration, and store wiring, read references/route-and-config-patterns.md.
• For custom cache key builders, tenant/user safety, and invalidation/versioning strategy, read references/key-builder-and-invalidation.md.
• For cache_response_filter examples and test patterns that prove cache correctness, read references/filter-and-testing-patterns.md.

Recommended Defaults

• Start with cache=True plus an explicit app-level default_expiration.
• Keep the default MemoryStore only for single-process or low-stakes cases.
• Move to a named shared store for horizontally scaled deployments.
• Include every response-shaping input in the cache key before enabling caching on auth-, locale-, or tenant-sensitive routes.
• Cache successful GET responses by default; be conservative with anything else.
• Prefer short TTLs over complex invalidation when freshness requirements allow it.

Anti-Patterns

• Caching mutation endpoints or non-idempotent workflows.
• Using cache=True without noticing that default_expiration=None makes the entry indefinite.
• Reusing the default key builder on endpoints whose response varies by headers, cookies, auth, or tenant.
• Caching permission-gated responses without identity or scope in the key.
• Assuming a shared cache while still using per-process memory storage in a multi-instance deployment.
• Using CACHE_FOREVER for mutable business data without explicit invalidation or versioning.
• Treating cache_response_filter as a substitute for good key design.

Validation Checklist

• Confirm the route is deterministic for the chosen cache key.
• Confirm TTL or forever-caching semantics match product freshness requirements.
• Confirm the configured store is shared or local by intent.
• Confirm the key builder covers all inputs that can change the payload.
• Confirm cache_response_filter allows and rejects the expected status codes and methods.
• Confirm cache hits occur on equivalent requests and miss on materially different ones.
• Confirm stale-data behavior is acceptable after writes, deployments, and worker restarts.
• Confirm tests cover both correctness and isolation for tenant-, locale-, or auth-scoped data.

Cross-Skill Handoffs

• Use litestar-stores for backend store lifecycle, namespacing, and TTL policy beyond response caching.
• Use litestar-testing to lock down cache hits, misses, and stale-data boundaries.
• Use litestar-security or litestar-authentication when response visibility depends on user identity or permissions.
• Use litestar-responses when response metadata or specialized response containers affect what is safe to cache.

Litestar References

• https://docs.litestar.dev/2/usage/caching.html
• https://docs.litestar.dev/2/reference/config.html#litestar.config.response_cache.ResponseCacheConfig
• https://docs.litestar.dev/2/reference/config.html#litestar.config.response_cache.default_cache_key_builder