milestone 17: real deadlines, validator holes, upstream editor, trusted proxies, contract samples, badvers

docs/reference/api.md

@@ -71,6 +71,18 @@ to the capacity is admitted and the long-run rate holds.
   up, never zero).
 - Loopback addresses (127.0.0.0/8 and ::1) are exempt while
   `web.api_localhost_exempt` is true (the default).
+- The address a bucket keys on is the socket peer, unless that peer is listed in
+  `web.trusted_proxies`. For a listed peer the address is instead the **last**
+  entry of the request's `X-Forwarded-For` — the entry the proxy appended, which
+  is the only one a client cannot write. A request from a trusted proxy with no
+  such header keys on the proxy itself; one whose last entry is not an IP
+  literal is answered 400, because the alternative is granting the proxy's own
+  loopback exemption to whoever sent it. Only `X-Forwarded-For` is read;
+  `Forwarded` (RFC 7239) and the PROXY protocol are not.
+- Without `web.trusted_proxies`, a same-box reverse proxy makes every request
+  loopback, so the default exemption disables the limiter for all remote
+  clients. Set the proxy's address there, or set
+  `web.api_localhost_exempt = false`.
 - Exempt routes, which never consult a bucket: `/metrics` and `/api/health` (a
   Prometheus scrape must never see 429) and `/api/queries/live` (one long-lived
   stream must not drain its address's bucket; it is bounded by the SSE