Skip to content

Raise a backend-independent BackendUnavailableError for transport failures #260

Description

@allen0099

Split out of #228 (fixed for @cache in #259).

Problem

When a backend's transport fails, each backend raises its own client exceptions:

  • Redis raises redis.exceptions.ConnectionError / TimeoutError.
  • Memcached raises pymemcache or socket errors.
  • The memory backend never fails this way.

A caller that wants to handle "the cache is down" has to know which backend is configured and import that client library's exceptions. That is awkward for CacheManager, StateManager, CacheLock and session code, which still let backend errors propagate. #259 sidesteps the question in @cache by catching Exception.

Proposal

  • Add BackendUnavailableError(CacheXError) in fastapi_cachex/exceptions.py.
  • Have the Redis and Memcached backends translate transport-level failures into it and chain the original exception (raise ... from e). Transport-level failures are connection refused/reset, timeouts and a server out of rotation.
  • Leave errors that are not about availability as they are: bad input, serialization, and the existing CacheXError cases.
  • Document which operations can raise it. Consider narrowing @cache's fail-open catch to it plus the known storage-rejection cases.

Open questions

  • Is this a breaking change? Code that catches redis.exceptions.ConnectionError today would stop catching it unless BackendUnavailableError also subclasses the original types, which is not possible across backends. That probably means the 0.4.0 milestone, or a transition period in which the new error is raised alongside a deprecation note.
  • Should "item too large" (Memcached object too large for cache) be a separate CacheXError subclass rather than an availability error?

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    backendsCache backends and their atomic primitivesenhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions