fix: document that the frontend server must be a trusted proxy for the public buckets (WR-15)

The resolve and 404 buckets key on the client IP, which is the SSR
server's address unless it is in http.trusted_proxies and forwards
X-Forwarded-For; otherwise they cap the whole site at 600 requests a
minute. The README and the Buckets comment now say so. An authenticated,
unthrottled resolve call would need a new token and a framework way to
skip a bucket, so it is left for a decision.
This commit is contained in:
2026-10-27 15:33:57 +01:00
parent 59c37a8fea
commit cab1b9aef4
2 changed files with 6 additions and 1 deletions

View File

@@ -109,6 +109,8 @@ The pipeline runs normalisation, then redirects on the normalised path (followed
{"action": "redirect", "status": 301, "location": "https://example.com/pages/b", "url": "https://example.com/pages/a", "locale": "", "staging": false, "seo": null}
```
**Behind the frontend server.** The resolve calls and the 404 reports come from the frontend (SSR) server, not from the visitor, so the throttle buckets see that server's address unless it is listed in `http.trusted_proxies` and forwards the visitor's address in `X-Forwarded-For` (the rightmost hop outside the trusted list counts). Without that, `seo-resolve` and `seo-notfound` are caps for the whole site, 600 requests a minute each (about 10 rendered pages a second), and resolve answers `429` beyond them. Put the frontend server in `http.trusted_proxies` and have it forward `X-Forwarded-For`.
`status` is 302 when a temporary redirect takes part. A 410 rule answers `"action": "gone"`, `"status": 410`. A redirect cycle met at runtime (stored past the save check) stops after 10 hops with `not_found` and is logged at most once an hour per cycle (keyed by its rules, not by the requested URL). A path that no published record owns and no URL rule covers answers `"action": "not_found"`, `"status": 404` and `"seo": null` (the home page `/` is always known). A `url` that is neither a path nor an http(s) URL is a `422`. Absolute URLs are built from `golem15.seo.site_url`, or from the request URL when it names the site's host or its `www` twin (for the scheme and host rules), never from the request's Host header.
### The 404 report endpoint