Track residual rate-limit hardening after 1.0 rollout

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 #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

• #185
• #191
• #197

Start by locating the rate-limit middleware, existing TRUST_PROXY regression coverage, the metrics route, and the runbook referenced by #191. Trace the proxy, bucket, path, CORS, and breaker behavior described in the follow-up list. Done means every acceptance criterion is implemented or documented and the GCP ALB case is covered by a regression test.