feat(rate-limit): implement three-tier rate limiting with burst limits

[samjay8]

Closes #78

Summary

• Added a third rate-limit tier webhook alongside the existing api and auth tiers, with its own configurable limit (default 30 req/min) and burst ceiling (default 5 req/sec)
• Added per-tier burst rate limiting — a per-second spike ceiling that rejects requests immediately when exceeded, independent of the steady-state per-minute limit
• Added rate-limit response headers (X-RateLimit-Limit, X-RateLimit-Reset, Retry-After) from the NestJS ThrottlerGuard, so clients can see their remaining budget
• Applied @ThrottleTierDecorator('webhook') to WebhookController to scope webhook management endpoints to the webhook tier

Scope

Does not touch the SlidingWindowThrottlerGuard (Redis-backed sliding window), the sliding-window spec, or any domain modules beyond the webhook controller tier annotation.

Testing

• npm run typecheck (type safety)
• npm run lint (no new lint errors)
• npm test (new throttler guard spec + existing sliding-window spec)
• npm run build (successful build)

Files changed

• src/common/decorators/throttle-tier.decorator.ts — Extended ThrottleTier union to include 'webhook'
• src/common/guards/throttler.guard.ts — Added burst limiting, rate-limit headers, and webhook tier support
• src/common/guards/throttler.guard.spec.ts — New tests for tier routing, burst limits, tracker scoping
• src/config/env.validation.ts — Added THROTTLE_WEBHOOK_LIMIT, THROTTLE_*_BURST env vars
• src/config/queue.config.ts — Added webhookLimit, apiBurst, authBurst, webhookBurst to config type
• src/app.module.ts — Registered the webhook named throttler
• src/modules/webhooks/webhook.controller.ts — Applied @ThrottleTierDecorator('webhook')
• .env.example — Documented new rate-limit env vars

[drips-wave]

@samjay8 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[mergekeeper]

Needs changes

AstroidThrottlerGuard hardcodes burst limit defaults instead of reading the injected ConfigService values.

• src/common/guards/throttler.guard.ts:138: getBurstLimit uses hardcoded defaults (api: 10, auth: 3, webhook: 5) instead of reading throttle burst configuration from the injected ConfigService.

Reviewed commit: f594be1d27cd9cc3601c34ed7e6af08117bfa392.

[mergekeeper]

Needs changes

AstroidThrottlerGuard hardcodes burst limit defaults instead of reading the injected ConfigService values.

• src/common/guards/throttler.guard.ts:138: getBurstLimit uses hardcoded defaults (api: 10, auth: 3, webhook: 5) instead of reading throttle burst configuration from the injected ConfigService.

Reviewed commit: f594be1d27cd9cc3601c34ed7e6af08117bfa392.

[mergekeeper]

MergeKeeper review

Scope: in scope for linked issue #78.
Verdict: clean

Successfully implemented three-tier rate limiting with webhook tier, burst limits, and corresponding tests.

Reviewed commit: 0af4181ce2ae0c5dac056cb99df31e7cbc8b7723.
CI and merge eligibility are checked separately.

[mergekeeper]

MergeKeeper merge status

Status: blocked
PR state: open
Mergeability: mergeable
Checked commit: 0af4181ce2ae0c5dac056cb99df31e7cbc8b7723.

Reason:
GitHub pull request merge request failed with 405: 4 of 4 required status checks are expected.

Next steps:
This required status check is enforced directly by the repository's branch rules, independent of MergeKeeper's own CI evaluation — a maintainer merge override cannot bypass it unless MergeKeeper is authorized to.

1. Wait for the check to pass, or fix the underlying failure.
2. To let an explicit override bypass this check going forward, add the MergeKeeper GitHub App as a Bypass actor on the ruleset (Settings → Rules → Rulesets → the ruleset → Bypass list).

[mergekeeper]

Approved

Successfully implemented three-tier rate limiting with webhook tier, burst limits, and corresponding tests.