Skip to content

docs: add Hosted rate-limit operator guide (#37) - #152

Merged
CodewithJha merged 1 commit into
CodewithJha:mainfrom
BasilZafar11:fix/issue-37-rate-limit-guide
Nov 16, 2026
Merged

CodewithJha merged 1 commit into
CodewithJha:mainfrom
BasilZafar11:fix/issue-37-rate-limit-guide

Conversation

@BasilZafar11

@BasilZafar11 BasilZafar11 commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Fixes #37

Add docs/RATE_LIMITS.md as the Hosted operator field guide: all 11 environment variables and their defaults/types, auth-dependent enablement, endpoint categories, token-bucket refill/burst semantics, per-identity/category keys, proxy identity implications, idle/LRU cleanup, and process-local reset/replica limitations.

Document middleware order, the structured 429 response, integer-second Retry-After rounding, and safe bounded client retry expectations. Distinguish the HTTP contract from automatic client retry support, and link the existing ingestion/pending-file contract. Explain public health/meta rate limiting and the metadata flags for checking enablement.

Link the guide from the docs hub and SECURITY.md. Correct the security summary's type wording: idle cleanup accepts fractional seconds; RPM/burst/key counts require positive integers. No runtime behavior changes.

Type of change

  • Docs / community / DX only

Checklist

  • Read CONTRIBUTING.md and repository policies
  • Linked related issue
  • Core and adapter boundaries unchanged
  • Names/defaults and behavior verified against source
  • Documentation matches current implementation
  • One concern per PR
  • Authorized offline/local verification only

Test plan

  • Ad hoc source/config check: all 11 documented environment names, 10 numeric defaults, and auth-dependent enablement match rate_limit.py / load_rate_limit_config({}).
  • All 7 guide-relative links resolve; docs hub and SECURITY links point to the guide.
  • uv run --locked pytest tests/unit/test_rate_limit.py tests/integration/test_api_hosted_rate_limit.py -q --tb=short: 27 passed.
  • uv run --locked ruff check: passed.
  • git diff --check: passed.

No new tests were added for this documentation-only change. Full backend/web/container/package and CLI smoke gates are left to existing CI. Branch starts at current upstream main 99ed9ad, matching fork main at fetch.

CI results

All seven jobs passed: Python 3.11/3.12 backend tests, Python lint, package build, CLI smoke, web build, and container smoke.

CI run: https://github.com/CodewithJha/mutiny/actions/runs/43666468336

@vercel

vercel Bot commented Nov 15, 2026

Copy link
Copy Markdown

@BasilZafar11 is attempting to deploy a commit to the priyanshu's projects Team on Vercel.

A member of the Team first needs to authorize it.

@CodewithJha CodewithJha left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MERGE READY for #37.

What I verified

  • docs/RATE_LIMITS.md lists all 11 env vars with defaults that match rate_limit.py constants (health/normal/expensive/ingest RPM+burst, max keys, idle seconds). Documents process-local buckets, identity keying, middleware order, and 429 semantics without overselling distributed limits.
  • SECURITY.md and docs index link in. Docs-only against live code. Closes #37.

@CodewithJha
CodewithJha merged commit f735aa4 into CodewithJha:main Nov 16, 2026
7 of 8 checks passed
@CodewithJha

Copy link
Copy Markdown
Owner

Merged — thank you @BasilZafar11. Operators finally have a single field guide for the in-process limiter defaults, identity keys, and Retry-After behavior.

Related open work:

No pressure.

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.

docs: document Hosted rate-limit env vars and Retry-After behavior

2 participants