feat: raise BackendUnavailableError when the server cannot be reached (#260)

[allen0099]

Fixes #260

Summary

On a transport failure, each network backend raised its own client's exceptions. To handle "the cache is down" around CacheManager, CacheLock or a backend call, you had to know which backend was configured and import redis or pymemcache exceptions.

What changes

• New BackendUnavailableError(CacheXError), exported from fastapi_cachex.
• The Redis and Memcached backends wrap their I/O methods (get, set, delete, delete_many, the atomic primitives, increment, clear*, get_all_keys, get_cache_data) with backends/_unavailable.py. A transport failure is raised again as BackendUnavailableError, chained to the original. Transport failures are:
  • Redis: redis-py ConnectionError (and its subclasses), TimeoutError, and a raw OSError.
  • Memcached: socket errors (OSError: refused, reset, timed out), MemcacheUnexpectedCloseError, and HashClient's "All servers seem to be down" while a server is out of rotation.
• Other errors pass through unchanged: bad input, MemcacheClientError such as an item too large (Handle Memcached "object too large" consistently outside @cache #261), and the existing CacheXError cases. The memory backend never raises it.

Not a breaking change. This answers the issue's first open question. The class raised is built once per original type and inherits from both BackendUnavailableError and that type, so:

• A refused Memcached connection is also a ConnectionRefusedError and OSError, with the same errno. A Redis one is also a redis.exceptions.ConnectionError.
• Existing except redis.exceptions.ConnectionError, except OSError and except MemcacheError clauses keep catching it. The existing suite passes unchanged, including the tests that expect ConnectionRefusedError.
• The runtime classes are named BackendUnavailableError in tracebacks and pickle correctly through __reduce__.

Left as is

• @cache still fails open on any backend error. I did not narrow its catch, as the issue only suggested considering it; that would change behaviour.
• "Item too large" stays with Handle Memcached "object too large" consistently outside @cache #261, the issue's second open question.

Docs (English and zh-TW): a new "When the server is unavailable" section in BACKENDS.md with an example, and links from the Memcached and fail-fast sections. Changelog fragment: 260.added.md.

As in #463, the docs say "before 0.5.1", assuming this ships in the next patch release.

Checklist

• The issue above is assigned to me (maintainer's own issue)

• Tests under tests/ cover the change. tests/backends/test_unavailable.py needs no server; it points at a port nothing listens on. It covers:

  • a Redis refusal, and a Memcached refusal followed by the server out of rotation (exact class, both bases, __cause__, errno)
  • CacheManager propagating the error
  • other errors passing through unchanged
  • a nested call translated only once
  • one runtime class per type
  • a pickle round trip

  Disabling the translation fails the three backend tests.

• A changelog fragment: changelog.d/260.added.md

• uv run pre-commit run --all-files and uv run pytest --cov pass:

  • pytest: 1251 passed, 192 skipped, 93.10% coverage
  • with a live Redis: 1380 passed (Memcached was not available locally, so its live suite is left to CI)
  • mypy strict, mypy tests, mypy scripts and both zensical build --strict runs pass

---

Generated by Claude Code