Add API Rate Limiting to a Laravel App from a Linear Issue

The agent starts from the issue text and the repository, cloned into its own cloud sandbox, and reads before it writes, because a Laravel app often throttles its API already in a way nobody remembers. In a codebase like BookStackApp/BookStack (Laravel ^v13.35.0 on PHP ^8.3.0), the api middleware group in app/Http/Kernel.php already runs ThrottleApiRequests, a subclass of Laravel's ThrottleRequests whose resolveMaxAttempts returns config('api.requests_per_minute'). That value comes from app/Config/api.php as env('API_REQUESTS_PER_MIN', 180), and .env.example.complete documents API_REQUESTS_PER_MIN=180. So two of the three things the issue asks for, a 180 per minute limit and a value set in .env, are already true, and the agent says so instead of adding a second throttle on top.

Then it looks for the gap between the issue and the code. The issue says the limit is per API token; the comment in app/Config/api.php says "per minute by a single user", and one BookStack user can hold several tokens. app/App/Providers/RouteServiceProvider.php also defines RateLimiter::for('api', ...) at Limit::perMinute(60) keyed by user id or IP, but no route names throttle:api (only throttle:public in routes/web.php and throttle:exports in the export controllers), so that 60 per minute limiter never runs and reads like the real one. The agent writes these findings into its plan: key the API limit by the token the request authenticated with, using a named RateLimiter limiter that reads api.requests_per_minute, and remove or reconcile the unused definition so there is one place the API limit lives.

It then makes the change in the files that own it: the limiter in RouteServiceProvider.php, the middleware entry in the api group, the api.php config comment and the .env.example.complete line if the meaning changes. It keeps the headers Laravel's throttle already sends, which BookStack's tests pin down: tests/Api/ApiAuthTest.php asserts x-ratelimit-limit and x-ratelimit-remaining on every request and a 429 with retry-after and a JSON error.code of 429 once the limit is hit, and tests/Api/ApiConfigTest.php changes api.requests_per_minute at runtime and expects the header to follow. The agent adds tests beside those: two tokens for one user each get their own count, and a lower configured limit still answers 429 with the same JSON shape.

Last, it runs the suite the way the project's own CI does. BookStack's phpunit.xml sets DB_CONNECTION to mysql_testing, which app/Config/database.php points at a bookstack-test database on 127.0.0.1, and the workflow in .forgejo/workflows/test-php.yml creates that database and user, runs artisan migrate --force --database=mysql_testing, seeds DummyContentSeeder and then runs ./vendor/bin/phpunit. The agent starts MySQL in the sandbox, repeats those steps, runs composer test, fixes what fails and runs it again before it pushes a branch.

What comes back is a pull request on its own branch whose description starts with what the agent found: in an app shaped like BookStack, that the API was already limited to 180 requests a minute through API_REQUESTS_PER_MIN, that the limit counted per user rather than per token, and that the 60 per minute api limiter in RouteServiceProvider.php was never applied. The diff then touches only the files that own the limit and the new tests in tests/Api/, and the description links back to the Linear issue so the issue shows the work.

The proof is the test run. The session's transcript keeps every command with its output: the MySQL start, the migrate and seed against mysql_testing, and each composer test run, including any that failed before the fix. If the repository runs its PHP tests on GitHub Actions, those checks run on the pull request too; BookStack's own test workflow lives under .forgejo/ and does not run on GitHub, so for a repository like it the transcript is where the passing suite is shown.

Before merging, a reviewer checks that the limit is keyed by what the team actually means by a client (a token, a user or an IP), that no second throttle still runs in front of the API, that the new tests fail when the limiter is removed, and that the documented .env value and its default agree.

In the console, an automation with a linear trigger on linear.issue.labeled and the label agent starts one run per labelled issue, with the issue as its context, in the Project's repository. Changes made by an app integration never fire it, so the agent's own updates do not start new runs.

From your own server, the same run is one POST /o/{org}/sessions per issue: put the repository in resources, and add the issue's https://linear.app/<workspace>/issue/<ID> URL there too to have Rush read it through your Linear connection into the prompt. A webhook on the API key posts run.completed or run.failed when the turn finishes, with the session_url to read the result.

Testing a rate limit means running the app's real suite against a real database, and for a Laravel project that is MySQL with a migrated and seeded test schema. In a Rush sandbox the agent installs Composer dependencies, starts MySQL and creates bookstack-test or whatever your phpunit.xml names on its own disk, so nobody's laptop database is migrated or reset, and the tests that hammer the API until it answers 429 run where they cannot slow anything else down.

A label in Linear becomes a reviewable change with its evidence attached: the transcript shows the agent reading the existing throttle before touching it and every PHPUnit run with its output, and the pull request lists what it left alone. Several labelled issues can run at once, each in its own sandbox with its own branch, up to the key's max_concurrent limit.

My app already has some throttling. Will it add a second limiter?

Does it run the tests against MySQL or SQLite?

Which rate limit headers does the response keep?

What if the issue is wrong about the current state?