Track residual rate-limit hardening after 1.0 rollout

[dkijania]

Context

Luis approved #185 after the round-1 fixes, but called out several residual hardening items. They are not blockers for the current PR and should not trigger another review cycle there, but they are real follow-up work for the production-ready endpoint.

This issue intentionally does not duplicate the #186 TRUST_PROXY docs blocker; #215 already tracks that release prerequisite.

Follow-up work

• Revisit the x-real-ip fallback. It contradicts the comment that short XFF chains fall back to the socket rather than trusting caller-controlled headers.
• Consider a MAX_BUCKETS cap in addition to TTL pruning. TTL bounds bucket lifetime, but a single window can still grow with unique source IPs.
• Exempt /metrics from rate limiting once P1: Expose Prometheus metrics at /metrics (#173) #191 lands. A throttled scrape creates a metrics gap at exactly the wrong time.
• Normalize probe/metrics paths consistently, e.g. /readiness/ vs /readiness.
• Expose Retry-After and X-RateLimit-* via CORS if browser clients are expected to read backoff hints.
• Add a positive TRUST_PROXY=2 regression test for the GCP external ALB chain shape: caller-supplied prefix, real client IP, forwarding-rule IP.
• Capture the downstream effect of sustained 429s: mina-explorer-api treats 429s as breaker failures, so an over-tight limit can make the archive tier go dark as a step function rather than degrade gradually.

Acceptance criteria

• The trusted source selection no longer relies on untrusted x-real-ip, or the trust boundary is explicit and tested.
• Bucket memory growth has a clear maximum or a documented reason for relying on connection-rate bounds.
• /metrics is not rate-limited when metrics are enabled.
• A GCP ALB TRUST_PROXY=2 test pins the expected client IP selection.
• Browser-visible rate-limit headers and mina-explorer-api breaker behavior are documented in the runbook.

Related

• P0: Add per-IP request rate limiting (#166) #185
• P1: Expose Prometheus metrics at /metrics (#173) #191
• P2: Operations runbook — SLOs, capacity, incidents, failover (#180) #197