Docs: Add Failure Modes section documenting on_unavailable behavior
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 0
- Forks
- 0
- Avg merge
- 6h 51m
- Merged PRs (30d)
- 104
Description
Problem
The on_unavailable parameter (ALLOW vs DENY) is an important operational decision, but it's currently only visible in the constructor signature. New users may not discover it until they hit a DynamoDB outage in production.
The docs should proactively explain:
- What happens when the backing store is unavailable
- That this is an inherent trade-off in any external rate limiter (not a zae-limiter-specific flaw)
- How to choose between ALLOW and DENY based on risk profile
Suggested Content
Add a "Failure Modes" section to the getting-started or operations docs:
## What Happens When DynamoDB Is Down?
The `on_unavailable` parameter controls behavior when the backing
store is unreachable:
- `OnUnavailable.ALLOW`: Requests pass through without rate limiting
(fail-open). Use for availability-critical systems where dropping
requests is worse than temporarily losing rate limits.
- `OnUnavailable.DENY`: All requests are rejected with
`RateLimiterUnavailable` (fail-closed). Use for cost-control-critical
systems where unmetered access is unacceptable.
This trade-off is inherent to any external rate limiter — it is not
specific to zae-limiter.
Why This Matters
Users evaluating zae-limiter for multi-tenant platforms (LLM proxies, API gateways) need to understand the failure semantics upfront to make informed architectural decisions. Discovering this only from the API signature is too late.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating the getting-started or operations documentation for zae-limiter and the existing on_unavailable or OnUnavailable references. Add a Failure Modes section covering DynamoDB unavailability, ALLOW and DENY semantics, RateLimiterUnavailable, and the availability-versus-cost-control trade-off; done when users can choose based on their risk profile.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100