Verify the VWS request rate limits against real Vuforia

[adamtheturtle]

Closes #3572.

What real Vuforia does (observed 2026-09-08)

Bursts were sent to read-only VWS endpoints, first from a CI database and then from older databases which CI does not use.

• GET /targets accepts two requests per minute, not the documented one, and the window is a fixed clock minute: two requests at :40 passed, a third was rejected, and a request at :03 of the next minute passed.
• The per-second limits are enforced roughly. Bursts of 40 concurrent GET /summary requests saw 17 to 37 succeed against the documented 15; a burst of 120 GET /targets/{id} saw 74 succeed against 45; a burst of 60 GET /duplicates/{id} saw 11 succeed against 10. There are two Envoy layers, and either may reject.
• Limits are keyed on the server access key in the Authorization header and applied before the signature is checked: bad-secret requests count towards the limit, an unknown key gets its own bucket, and one database's burst does not affect another's. Requests with no Authorization header were not rate limited.
• A rate-limited request gets a 429 with an empty body, no Content-Type, server: envoy and x-envoy-ratelimited: true. x-envoy-upstream-service-time is present only when the inner layer rejected. The TooManyRequests result code never appears.

The test suite had not noticed because pytest-retry and the fixtures retry TooManyRequestsError.

Changes

• DOCUMENTED_REQUEST_RATE_LIMITS.list_targets is now two per minute.
• The mock's 429 is the empty Envoy response.
• The rate limiter runs before authorization, keyed on the access key's database, and ValidatorContext no longer carries it.
• TestRateLimit in test_target_list.py runs against every backend. Each mock gets a fresh database with the limits so the shared database stays unlimited. Passed against real Vuforia locally.
• unverified-behavior.rst drops the never-attempted entry and differences-to-vws.rst records what is observed but not implemented: the clock-aligned window and the loose per-second enforcement.

The pylint spelling failure on subclasses in tests/mock_vws/utils/retries.py at the manual hook stage is pre-existing and not touched here.

🤖 Generated with Claude Code