Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/RateLimit/Adapters/FileRateLimitAdapter.php`:
- Around line 37-54: The current read-modify-write in FileRateLimitAdapter.php
(using $this->cache->get($key) then local ++ then $this->cache->set(...)) is
racy; change it to an atomic update: use your cache client's atomic increment
(e.g. $this->cache->increment or Redis INCR) on $key to bump the count and set
the TTL/expiration for reset_at in the same atomic operation, ensuring $resetAt
is computed once and stored alongside the counter; if the cache client has no
atomic increment, implement a CAS/compare-and-set loop or obtain a short-lived
lock around the increment/reset logic (using the cache's lock facility) so
updates to $key (and fields 'count' and 'reset_at') cannot be lost under
concurrency.
- Around line 34-41: In FileRateLimitAdapter::hit validate inputs at the start
of the method: check that $limit and $interval are integers >= 1 and throw an
InvalidArgumentException (or similar) if either is < 1 so the method fails fast
instead of producing fallback windows; update the hit(string $key, int $limit,
int $interval) implementation to perform these checks before computing $now,
reading $data, or setting $resetAt.

In `@src/RateLimit/Adapters/RedisRateLimitAdapter.php`:
- Around line 34-57: The hit method in RedisRateLimitAdapter currently does a
non-atomic get→modify→set sequence (in hit), which allows lost increments under
concurrency; change it to perform an atomic increment and set the TTL only when
the key is first created by using Redis primitives (INCR + EXPIRE or a small Lua
script that INCRs and calls EXPIRE when count==1). If Quantum\Cache\Cache
doesn't expose raw Redis commands, inject a raw Redis client (e.g., \Redis or
\Predis\Client) into RedisRateLimitAdapter and use that client to execute the
atomic INCR and conditional EXPIRE/EVAL; ensure hit returns count <= $limit
based on the atomic result and that the TTL equals the provided $interval.

In `@src/RateLimit/RateLimitMiddleware.php`:
- Line 62: The middleware sets Retry-After using the full window ($interval)
rather than time left; update the rate limiter interface and implementations to
provide the remaining time and use that in RateLimitMiddleware: add a new method
remainingSeconds(string $key): int to RateLimitAdapterInterface (keeping hit():
bool unchanged for compatibility), implement remainingSeconds in
FileRateLimitAdapter and RedisRateLimitAdapter to return max(0, reset_at -
time()), and modify RateLimitMiddleware (the code that currently calls
setHeader('Retry-After', (string) $interval)) to call remainingSeconds($key) and
use that value for the Retry-After header so clients receive the actual
remaining window seconds.

In `@src/Router/Route.php`:
- Around line 155-160: The rateLimit method currently accepts non-positive
integers; update Route::rateLimit to validate that both $limit and $interval are
positive (>0) and throw an InvalidArgumentException (or similar) when either is
non-positive, before assigning $this->rateLimit; include a clear message
referencing the invalid parameter name so callers know which argument failed
validation.

---

Nitpick comments:
In `@tests/Unit/Router/RouteTest.php`:
- Around line 128-143: Add new unit tests in RouteTest to assert that invalid
rate-limit inputs are rejected: create tests that call Route::rateLimit with
limit <= 0 and interval <= 0 (and both invalid) and assert the expected failure
behavior (e.g., exception thrown or null/empty result depending on project
convention). Update or add test methods alongside
testRouteRateLimitConfigurationIsStored and the similar block later to cover
each invalid case separately, referencing Route::rateLimit and
Route::getRateLimit to verify state does not accept invalid values. Ensure the
tests assert the concrete expected outcome your codebase uses for validation
(specific exception class or return value) so future changes will fail the tests
if invalid values are allowed.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@tests/Unit/RateLimit/RateLimiterTest.php`:
- Around line 11-58: The test suite misses asserting that RateLimiter::buildKey
trims whitespace for the method and IP parts; update Test class RateLimiterTest
by extending testRateLimiterBuildsNormalizedKey (or add a new small assertion)
to call $limiter->buildKey with padded method and ip (e.g., ' POST ' and '
127.0.0.1 ') and assert the normalized result equals
'POST:/api/posts:127.0.0.1', ensuring buildKey's trimming behavior for method
and ip is covered.

In `@tests/Unit/RateLimit/RateLimitMiddlewareTest.php`:
- Around line 25-28: Tests currently mutate RateLimiterFactory::instances via
setPrivateProperty which couples tests to internals; instead, obtain a
RateLimiterFactory instance through the Di container and inject a test instance
(RateLimiter with ToggleAdapter) using a public setter or factory method on
RateLimiterFactory (or register a test binding in Di to return a preconfigured
RateLimiterFactory), replace the setPrivateProperty usage in the test, and add a
tearDown() that resets the factory state or rebinds the original Di registration
to avoid state leakage between tests; refer to RateLimiterFactory, instances,
RateLimiter, ToggleAdapter and the test's tearDown for changes.
- Around line 31-58: The test currently doesn't verify the constructed
rate-limit key because the ToggleAdapter swallows the $key; modify the
ToggleAdapter (used by RateLimiter) to store the last received key in a public
property (e.g., lastKey) whenever its increment/check methods are called, then
in testRateLimitMiddlewareBlocksWith429AndHeaders instantiate that
ToggleAdapter, register it with the factory via factory->setAdapter('file', new
RateLimiter($adapter)), run the middleware apply calls as before, and add
assertions against $adapter->lastKey to assert it contains the HTTP method
("GET"), the route pattern ("/posts") and the client IP (as provided by
request()), so the test validates the key shape produced by
RateLimitMiddleware/RateLimiter.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/Unit/RateLimit/Adapters/FileRateLimitAdapterTest.php`:
- Around line 92-95: The test in FileRateLimitAdapterTest writes an invalid JSON
file using a hardcoded filename pattern md5('test' . 'broken') . '.rate' which
mirrors the adapter's current key scheme and can lead to a false positive if the
adapter's naming changes; change the test to stop relying on the adapter's
internal filename: either (A) use a test-only helper on the adapter to obtain
the exact state filename for key "broken" (e.g., call
adapter->stateFileForKey('broken') or similar) and write the invalid JSON to
that path before asserting adapter->retryAfter('broken') === 0, or (B) add an
explicit comment documenting the assumed filename scheme and derive the filename
via a public method or protected accessor exposed only for tests so the test
targets the adapter's actual file naming (referencing FileRateLimitAdapterTest,
retryAfter, and the adapter instance).
- Around line 63-80: The testFileAdapterCreatesStorageDirectoryWhenMissing test
can leak the rate_limit_tests_missing directory if the assertion fails; update
the test to ensure cleanup always runs by wrapping the adapter creation and
assertion in a try/finally block so fs()->removeDirectory($path) is called in
the finally clause; reference the local $path variable, fs() helper and the
FileRateLimitAdapter instantiation so the directory is removed regardless of
assertion outcome.