Roadmap: 0.4.0 → 0.5.0 → 1.0 #425

Direction: an HTTP and application cache for FastAPI that gets HTTP semantics right and is safe by default. Nothing else.

0.4.0 ✅ (released 2026-10-02)

• Deprecate fastapi_cachex.session and fastapi_cachex.state; remove them in 0.5.0 #420 deprecate session and OAuth state
• 0.4.0: make BaseCacheBackend.delete() return whether a key was removed #71 BaseCacheBackend.delete() returns whether a key was removed

Correctness of @cache first (0.4.x) ✅

• Split cache.py into smaller modules #422 split cache.py (no API change)
• @cache drops or replays stale headers and cookies set on the shared Response #233 stale headers and cookies on the shared Response
• @cache: a miss ignores a matching If-None-Match and sends a full 200 #237 a miss ignores a matching If-None-Match
• @cache() with no directives sends an empty Cache-Control header #363 / @cache: warn about arguments that cannot cache (no ttl sends an empty Cache-Control; no_store with ttl) #328 empty Cache-Control, and arguments that cannot cache
• @cache: answer HEAD requests from the cached GET response #253 answer HEAD from the cached GET (shipped in 0.5.0)

Close the gaps that matter in production ✅ (shipped in 0.5.0)

• @cache: optional stampede protection on a miss #252 stampede protection on a @cache miss (coalesce=True)
• MemoryBackend: optional size limit with LRU eviction #242 MemoryBackend size limit with LRU eviction
• @cached decorator for plain (non-route) functions #248 @cached for plain functions
• Accept timedelta for ttl #334 timedelta TTLs, @cache: opt-in X-Cache: HIT/MISS debug header #335 X-Cache debug header

0.5.0 ✅ (released 2026-10-14)

• 0.5.0: remove session and OAuth state, and lower the dependency floors #421 remove session and state, and lower the dependency floors (FastAPI 0.128.2+, no direct Starlette or itsdangerous requirement)
• docs: migrating from fastapi-cache2 (long2ice/fastapi-cache) #423 migration guide from fastapi-cache2
• docs: when to use FastAPI-CacheX and when another library fits better #424 comparison page
• Support Python 3.15 in 0.5.0 #459 Python 3.15 support

Release: https://github.com/allen0099/FastAPI-CacheX/releases/tag/v0.5.0. 0.4.1 was the last 0.4.x release.

Towards 1.0

After 0.5.0, aim for an API stability promise. Further changes would then be additive until 2.0.

Settle what would change existing behaviour ✅ (released in 0.5.1, 2026-10-15)

All three landed without a breaking change. Release: https://github.com/allen0099/FastAPI-CacheX/releases/tag/v0.5.1

• An invalid ttl raises CacheXError in @cache but TypeError/ValueError in backends and CacheManager #337 one exception family for an invalid ttl: InvalidTTLError, with TTLTypeError / TTLValueError keeping the TypeError / ValueError bases (feat: one exception family for an invalid ttl (#337) #463)
• Raise a backend-independent BackendUnavailableError for transport failures #260 BackendUnavailableError for transport failures on Redis and Memcached; the error raised is also the client's own exception type (feat: raise BackendUnavailableError when the server cannot be reached (#260) #464)
• Monitoring routes: cached_hits/total_hits/valid_hits count entries, not hits #336 /cached-hits reports entries, total_entries, valid_entries, expired_entries; the *_hits fields are deprecated (feat(routes): entry-named counts in /cached-hits; deprecate the *_hits fields (#336) #465)

To do in 0.6.0: remove the deprecated cached_hits / total_hits / valid_hits / expired_hits fields of /cached-hits, with a section in MIGRATING_0_6.md.

Additive work that fits 0.5.x patch or minor releases

• HTTP semantics: Emit the Cache-Control directives that are defined but never produced #78 / Allow @cache to emit s-maxage, proxy-revalidate and no-transform #144 the Cache-Control directives not produced yet (s-maxage, proxy-revalidate, no-transform), @cache: normaliser for vary= headers to bound the number of entries #310 a normaliser for vary= headers (also the place to let apps hash their own token headers), Invalidate a cached route without hand-building a Request #332 invalidate a route without hand-building a Request
• Backends and app cache: Redis backend: from_url(), username/TLS in RedisConfig, and client injection #244 Redis from_url(), TLS and client injection; Handle Memcached "object too large" consistently outside @cache #261 Memcached "object too large" outside @cache; CacheManager: typed reads, incr, and get_many/set_many #249 typed reads, incr, get_many/set_many; CacheLock: optional automatic renewal and a way to detect a lost lock #250 CacheLock renewal and lost-lock detection; Warn when an explicit MemoryBackend runs under several workers #395 warn on an explicit MemoryBackend under several workers
• Docs and CI: Docs: readers on the PyPI release see behaviour from unreleased versions #330 versioned docs for PyPI readers, docs: testing guide for Secure/__Host- cookies and Redis-backed apps #387 testing guide, Test the built wheel and the documented examples #241 test the built wheel, ci: skip the heavy checks on docs-only pull requests without breaking required checks #222 skip heavy checks on docs-only PRs

Out of scope: sessions, OAuth state, idempotency keys, concurrency limits.