Skip to content

docs(backends): show how to make Redis fail fast instead of retrying for seconds - #348

Merged
allen0099 merged 1 commit into
masterfrom
docs/325-redis-retry
Sep 29, 2026
Merged

allen0099 merged 1 commit into
masterfrom
docs/325-redis-retry

Conversation

@allen0099

Copy link
Copy Markdown
Owner

Closes #325

What

With Redis unreachable, @cache fails open, but only after redis-py has given up. redis-py 8's default Retry (10 retries, exponential backoff with jitter, capped at 1 s) makes that slow. Measured with redis-py 8.1.0 (the lockfile version) and the backend's defaults:

Redis state per get/set, defaults with the documented settings
connection refused about 3 to 4.5 s (so about 7 s per cached request, which does both) about 0 s
host not answering (packets dropped) about 15 s about 0.25 s (the connect timeout)

This PR only changes documentation. The backend's defaults stay as they are; a smaller default retry budget is a separate decision.

  • docs/HTTP_CACHING.md, "When the backend fails": explains the cost next to the fail-open text, with an example that passes retry=Retry(NoBackoff(), 0), socket_connect_timeout and socket_timeout through AsyncRedisCacheBackend's keyword arguments.
  • docs/BACKENDS.md, Redis: new "Failing fast when Redis is down" subsection with the same example and the trade-offs: no retry on a transient error, socket_timeout also bounds slow replies, and the settings apply to CacheManager/StateManager/CacheLock/sessions too. It also notes that RedisConfig has no retry field.
  • zh-TW: both changes mirrored in i18n/zh-TW/docs/, with the {#failing-fast-when-redis-is-down} anchor.
  • Test: test_redis_fail_fast_settings_reach_the_client builds the backend exactly as documented, checks that the retry policy and both timeouts reach the redis-py connection kwargs, and checks that a get against a closed port fails in under 1 s. It needs no running server and passes on the lowest env (redis 5.3.0) too.

Changelog

No fragment. The repo has no Documentation changelog section, and no library code changed.

…for seconds

With Redis down, redis-py 8's default retry policy makes every cached
request wait about 7 s before @cache fails open. Document the cost next to
the fail-open text and in the Redis section, with an example that passes
retry=, socket_connect_timeout and socket_timeout through the backend, and
test that those kwargs reach the redis-py client.
@allen0099
allen0099 merged commit c8836d4 into master Sep 29, 2026
12 checks passed
@allen0099
allen0099 deleted the docs/325-redis-retry branch September 29, 2026 06:27
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.

Redis backend: with Redis down each cached request waits ~7 s on redis-py's default retry

1 participant