feat: add rate limiting support with token bucket algorithm

[bornakapusta]

Summary

• Configure global and per-route rate limiters
• Token bucket with total_rps, per_ip_rps, burst settings
• Automatic cleanup of stale per-IP entries
• Returns HTTP 429 with Retry-After header when exceeded
• New metric: gatekeeper_rate_limited_total{route,limiter,reason}
• Helm chart support: rateLimiters, defaultRateLimiter, and per-route rateLimiter values
• Fixed Helm configmap template missing gitlab verifier type (pre-existing bug)

Manual Testing — Minikube + hey

Deployed to minikube with a strict rate limiter (totalRps: 5, perIpRps: 2, burst: 3) applied to the /webhook/direct route. The /webhook/relay route was left without rate limiting for comparison.

Setup

eval $(minikube docker-env)
docker build -t gatekeeperd:dev .
helm upgrade --install gatekeeperd ./charts/gatekeeperd \
  -f config/minikube-gatekeeperd.yaml -n gatekeeper --create-namespace

Config applied via config/minikube-gatekeeperd.yaml:

rateLimiters:
  test-strict:
    totalRps: 5
    perIpRps: 2
    burst: 3

routes:
  - hostname: test.local
    path: /webhook/direct
    rateLimiter: test-strict   # rate limited
    ...
  - hostname: test.local
    path: /webhook/relay       # NOT rate limited
    ...

Pod logs confirmed rate limiter initialization:

{"level":"INFO","msg":"rate limiter loaded","name":"test-strict","total_rps":5,"per_ip_rps":2,"burst":3}

Test Results

Load testing with hey (-host "test.local" to set Host header):

Test	Command	Expected	Result
A — Below limit	hey -n 3 -c 1 -host test.local	All 200s	[200] 3
B — Exceed total RPS	hey -n 100 -c 10 -host test.local	429s after burst	[200] 4, [429] 96
C — Exceed per-IP	hey -n 50 -c 1 -host test.local	429s after burst	[200] 5, [429] 45
D — Unrated route	hey -n 100 -c 10 → /webhook/relay	Zero 429s	[200] 10, [503] 90 (503 = no relay client; zero 429s)

Metrics Verified

gatekeeper_rate_limited_total{limiter="test-strict",reason="per_ip",route="/webhook/direct"} 5
gatekeeper_rate_limited_total{limiter="test-strict",reason="total",route="/webhook/direct"} 136

Both total and per_ip reasons are tracked with correct route and limiter labels.

Test plan

• make test — all tests pass with 100% coverage
• Helm template renders rate_limiters, rate_limiter on routes, default_rate_limiter in global
• helm lint passes with default and minikube values
• Minikube deploy: rate limiter initializes correctly
• Below-limit requests pass through (200)
• Above-limit requests are rejected (429) for both total and per-IP limits
• Unrated routes are unaffected (no 429s)
• Prometheus metrics track rate-limited requests with correct labels

Closes #14

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[github-actions]

Docker Images Built

Images are available for testing:

# gatekeeperd
docker pull ghcr.io/tight-line/gatekeeperd:pr-18-88fd7c0

# gatekeeper-relay
docker pull ghcr.io/tight-line/gatekeeper-relay:pr-18-88fd7c0

docker-compose.yml

GATEKEEPERD_IMAGE=ghcr.io/tight-line/gatekeeperd:pr-18-88fd7c0 \
RELAY_IMAGE=ghcr.io/tight-line/gatekeeper-relay:pr-18-88fd7c0 \
docker-compose --profile relay up

Helm (values override)

image:
  repository: ghcr.io/tight-line/gatekeeperd  # or gatekeeper-relay
  tag: "pr-18-88fd7c0"

Images expire ~15 days after PR closes.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud