zeroae / zeroae/zae-limiter

Docs: Add Failure Modes section documenting on_unavailable behavior

Open
#385 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.