Guide

The README gets you started. These pages go into the details.

How it works

1. Rules live in your database. You change them in the dashboard, through its JSON API, with Artisan or through the Rule model.
2. A compiler turns them into a versioned manifest stored in your cache, after each change commits. Octane keeps it in memory, and on PHP-FPM, a server's workers share it in APCu, so a process or a server reads the cache about once per manifest.refresh_seconds (ADR-0007). No request ever reads the rules from the database.
3. The dynamic.throttle middleware runs after authentication. It matches every applicable rule and counts each request with a sliding-window counter (ADR-0006). Blocked requests get a normal Laravel 429.

Pages

• Rules: the attributes, examples, your own scope, an endpoint that costs money, and exemptions
• Configuration: the environment variables
• Attaching the middleware: where it runs, excluded paths, responses and headers
• Storage and runtimes: which counter store to use, and APCu on PHP-FPM
• Performance: what a request costs, against no limiter and Laravel's throttle
• Dry-run rules: try a limit on real traffic first
• When something fails: fail open or closed, the cooldown, strict mode
• Why a request is limited: dynamic-throttle:explain
• Health checks: dynamic-throttle:health
• Traffic and blocks: what each rule did, per hour
• Events: RateLimitExceeded, RateLimitWouldBlock, StorageUnavailable, RuleChanged
• During an incident: bypass, scale, and switching one rule off
• The dashboard: where it is, who gets in, and what it refuses
• Testing your app: DynamicThrottle::fake()
• Removing the package: in two deploys, what stays, and cleaning up

When something goes wrong in production, the runbook has the steps: Redis is down, the manifest was evicted, a bad rule blocks /api, or an emergency change was left on.

The design is recorded as Architecture Decision Records, and each feature has a spec.