Skip to content

feat(proxy): warn when the MemoryBackend fallback is registered implicitly - #347

Merged
allen0099 merged 1 commit into
masterfrom
feat/327-fallback-warning
Sep 29, 2026
Merged

allen0099 merged 1 commit into
masterfrom
feat/327-fallback-warning

Conversation

@allen0099

Copy link
Copy Markdown
Owner

Closes #327

Summary

When @cache, CacheBackend or AppCache registers a MemoryBackend because no backend was set, get_backend_or_fallback() now logs a WARNING on the fastapi_cachex.proxy logger. Before this change it logged only at DEBUG:

No cache backend configured; registering an in-process MemoryBackend. Its cache is per process: under multiple workers, invalidation reaches only one worker and the others keep serving stale entries. Call BackendProxy.set(...) at startup to configure a shared backend, or BackendProxy.set(MemoryBackend()) to keep the in-memory cache without this warning.

  • Once per process. The log call is inside the factory that BackendProxy.get_or_create runs under its lock, so it fires only when the fallback is actually created. Concurrent first callers on worker threads produce a single warning. If the proxy is reset with BackendProxy.set(None) (only tests do this), the next fallback is a new registration and warns again. That is intended.
  • Explicit memory stays silent. BackendProxy.set(MemoryBackend()) never runs the factory, so it does not warn.
  • The warning goes through logging, not warnings, so it doesn't interact with warning filters.

Docs

  • docs/BACKENDS.md "In-memory (default)": describes the warning and how to silence it by setting the backend explicitly.
  • docs/HTTP_CACHING.md and docs/CACHE_FLOW.md: the fallback descriptions now mention the warning.
  • The zh-TW translations of all three pages are updated to match.
  • Changelog fragment: changelog.d/327.changed.md.

Tests

tests/test_fallback_warning.py uses caplog to check that:

  • the implicit fallback through @cache, AppCache and CacheBackend warns exactly once over repeated requests and direct calls;
  • 8 racing first callers on threads (through get_app_cache and get_backend_or_fallback) warn once;
  • the message names BackendProxy.set( and says the cache is per process;
  • after a proxy reset, the next fallback warns again;
  • an explicit BackendProxy.set(MemoryBackend()) does not warn on any of the three paths.

Mutation checks:

  • Moving the log out of the factory into get_backend_or_fallback fails the once tests and the explicit-backend tests.
  • Logging outside the lock, only while no backend is set, fails the concurrent test.

…citly

get_backend_or_fallback() now logs a WARNING from inside the get_or_create factory, so it fires once per registration (once per process unless the proxy is reset). An explicit BackendProxy.set(MemoryBackend()) stays silent.
@allen0099
allen0099 merged commit c728cd5 into master Sep 29, 2026
12 checks passed
@allen0099
allen0099 deleted the feat/327-fallback-warning branch September 29, 2026 06:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Warn when the MemoryBackend fallback is registered implicitly (per-process cache under multiple workers)

1 participant