📋 Add "Is zae-limiter right for you?" section to guide
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 0
- Forks
- 0
- Avg merge
- 6h 51m
- Merged PRs (30d)
- 104
Description
Summary
Add a decision-helper section to the User Guide main page (docs/guide/index.md or similar) that helps users quickly determine if zae-limiter fits their use case.
Why
- Builds credibility by being honest about trade-offs
- Reduces frustration from users who would have a bad experience
- Attracts ideal users who recognize their exact problem
- Good SEO for "DynamoDB vs Redis rate limiting" type searches
Proposed Content
The 30-second test
Answer these questions:
-
Do you know the cost of each request BEFORE it happens?
- Yes: Consider simpler alternatives
- No (e.g., LLM tokens): Keep reading ✓
-
Do you need sub-50ms latency on rate limit checks?
- Yes: Use in-process or Redis
- No (LLM calls are 100ms+ anyway): Keep reading ✓
-
Are you on AWS or willing to use DynamoDB?
- No: This library won't work for you
- Yes: Keep reading ✓
-
Do you have hierarchical limits (user → org → global)?
- Yes: This is our sweet spot ✓
- No: You might still benefit, but simpler options exist
When NOT to use zae-limiter
| Scenario | Why Not | Better Alternative |
|---|---|---|
| You know consumption upfront | No need for adjust() complexity |
Redis + lua script |
| Sub-millisecond latency required | DynamoDB is 36-51ms p50 | In-process, Redis |
| Not on AWS | DynamoDB lock-in | redis-cell, generic rate limiters |
| Single process/machine | Network overhead not worth it | In-memory counter |
| Simple requests/second limit | Over-engineered | nginx, API gateway throttling |
Note: Latency numbers are from actual benchmarks. See
docs/performance.mdfor details.
When zae-limiter shines
| Scenario | Why It Shines |
|---|---|
| LLM token budgets | adjust() after response completes |
| Hierarchical limits | User → Org → Global cascades |
| Multi-dimension limits | RPM + TPM in single call |
| Distributed systems | DynamoDB handles coordination |
| AWS-native stack | No new dependencies |
| Audit/compliance needs | Built-in audit logging |
Acceptance Criteria
- Section added to guide main page (before installation/quickstart)
- Clear, honest tone about trade-offs
- Links to comparison page for deeper dive
- Latency thresholds based on actual benchmarks from docs/performance.md
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 with docs/guide/index.md and docs/performance.md, then locate the existing comparison page referenced by the issue. Add the decision-helper section before installation or quickstart, keep the trade-offs honest, link to the comparison page, and use benchmark-backed latency thresholds.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 58/100