01a02ecf - Unlisted forwards belong to the upstream backend

CONTRIBUTING.md

@@ -169,10 +169,11 @@ Missing any applicable item = changes requested.
 - HEAD on a listed path is listed. It follows the same local body rules as GET
   and sends an empty response body.
 - Unlisted requests (everything for which `isKnownLocalRequest` is false)
-  remain forwarded. Forwarded requests have **no** 100ms rule. Unknown
-  routes are **never named** in this repository: they are only the
-  complement of the listed allowlist. Do not attach the 100ms budget to the
-  forward path.
+  are forwarded to `BACKEND_URL`. Those routes are **not** endpoints of this process; they belong to the upstream HTTP backend.
+  Forwarding an unknown route does not make it a listed route. Unknown routes are **never named**
+  in this repository: they are only the complement of the listed allowlist.
+  Forwarded requests have **no** 100ms rule. Do not attach the 100ms budget
+  to the forward path.
 - The swagger snapshot is an **allowlist** of paths this process serves, not a
   denylist.
 - Never serve an expired cache body.
@@ -222,7 +223,8 @@ are forwarded and are not in that budget. Nested listed prefixes, HEAD on
 listed paths, and authenticated listed GETs are listed, not unknown.
 `test/test-server.sh` pins `MAX_RESPONSE_MS = 100`, the inbound deadline on
 known routes, that known routes are not forwarded, that unknown routes are
-forwarded, the `ERROR` log, and the background outbound cap. The Node suite
+forwarded and belong to the upstream HTTP backend, the `ERROR` log, and the
+background outbound cap. The Node suite
 rejects any **known-route** helper round-trip over 100ms. A miss is a red
 `test` job, not a review note.
 

README.md

@@ -1,6 +1,6 @@
 # front-api
 
-Public HTTP layer in front of the DFX backend. Listed routes (`GET`/`HEAD /` 302 to swagger, `/version`, a filtered swagger snapshot, GET/HEAD cache, optional Postgres reads for country/language) are completed locally within 100ms, never forwarded, and never wait on `BACKEND_URL` for that client request. Background cache and swagger refresh may ping the upstream HTTP backend. Unlisted traffic is forwarded.
+Public HTTP layer in front of the DFX backend. Listed routes (`GET`/`HEAD /` 302 to swagger, `/version`, a filtered swagger snapshot, GET/HEAD cache, optional Postgres reads for country/language) are completed locally within 100ms, never forwarded, and never wait on `BACKEND_URL` for that client request. Background cache and swagger refresh may ping the upstream HTTP backend. Unlisted traffic is forwarded to the upstream HTTP backend and is **not** an endpoint of this process.
 
 ## Run
 
@@ -49,7 +49,8 @@ is `503` `not served` until a background refresh succeeds — never an
 expired cache body, never a live backend wait on that request.
 
 Everything this process does not list is forwarded to `BACKEND_URL` with
-no 100ms rule. This repository does not name those routes.
+no 100ms rule. Those routes belong to the upstream HTTP backend, not to this process.
+This repository does not name them.
 
 Every **known** HTTP response must finish within 100ms. Forwarding a known
 route is forbidden because that cannot guarantee 100ms. A slower known

REVIEW.md

@@ -132,9 +132,10 @@ Fail if the catalog says `prefix` or `exact` but the code forwards a matching
 nested GET/HEAD request or an authenticated listed GET. Listed authenticated
 GETs must not read the unauthenticated GET cache.
 
-Unknown routes (everything this process does not answer itself) **must**
-be forwarded to `BACKEND_URL`. They have no 100ms rule. This repository
-never names them. Fail if an unknown request is answered with `503`
-`not served` instead of being forwarded, if the 100ms budget is attached
-to the forward path, or if the diff names a route outside the known
-allowlist in docs, comments, catalog notes, or PR text.
+Unknown routes (everything this process does not list) **must**
+be forwarded to `BACKEND_URL`. They are not endpoints of this process; they belong to the upstream HTTP backend.
+They have no 100ms rule. This
+repository never names them. Fail if an unknown request is answered with
+`503` `not served` instead of being forwarded, if the 100ms budget is
+attached to the forward path, or if the diff names a route outside the
+known allowlist in docs, comments, catalog notes, or PR text.

test/test-server.sh

@@ -104,10 +104,15 @@ grep -Fq "(req.url ?? '/')" "$server_js" || fail "known_local: request path fall
 grep -Fq "if (!isKnownLocalRequest(req))" "$server_js" || fail "known_local: budget must not wrap forwarded requests"
 grep -Fq "forbidden** to" "$repo_root/CONTRIBUTING.md" || fail "known_local: CONTRIBUTING must forbid waiting on the backend for known routes"
 grep -Fq "no** 100ms" "$repo_root/CONTRIBUTING.md" || fail "unknown_forward: CONTRIBUTING must say forwarded requests have no 100ms rule"
+grep -Fq 'Those routes are **not** endpoints of this process; they belong to the upstream HTTP backend.' "$repo_root/CONTRIBUTING.md" || fail "unknown_forward: CONTRIBUTING process bullet must say those routes are not endpoints of this process"
+grep -Fq 'Forwarding an unknown route does not make it a listed route.' "$repo_root/CONTRIBUTING.md" || fail "unknown_forward: CONTRIBUTING process bullet must say forwarding an unknown route does not list it"
+grep -Fq 'Unlisted traffic is forwarded to the upstream HTTP backend and is **not** an endpoint of this process.' "$repo_root/README.md" || fail "unknown_forward: README must say unlisted routes are not this process"
+grep -Fq 'Those routes belong to the upstream HTTP backend, not to this process.' "$repo_root/README.md" || fail "unknown_forward: README local-answers must say those routes belong to the upstream HTTP backend"
 grep -Fq 'never forwarded' "$repo_root/README.md" || fail "known_local: README must say listed routes are never forwarded"
 grep -Fq 'must **never wait** on `BACKEND_URL`' "$repo_root/CONTRIBUTING.md" || fail "known_local: listed requests must never wait on BACKEND_URL"
 grep -Fq 'Forwarding a listed route is a hard fail' "$repo_root/REVIEW.md" || fail "known_local: REVIEW must fail listed forwarding"
 grep -q 'Unknown routes' "$repo_root/REVIEW.md" || fail "unknown_forward: REVIEW must require forwarding unknown routes"
+grep -Fq 'They are not endpoints of this process; they belong to the upstream HTTP backend.' "$repo_root/REVIEW.md" || fail "unknown_forward: REVIEW must say unknown routes are not endpoints of this process"
 grep -q 'forbidden' "$repo_root/CONTRIBUTING.md" || fail "max_response_100: CONTRIBUTING must forbid code that cannot meet 100ms on known routes"
 grep -q 'ERROR' "$repo_root/CONTRIBUTING.md" || fail "max_response_100: CONTRIBUTING must require an ERROR log on a deadline miss"
 grep -q 'FRONT_API_EXIT_AFTER_BOOT=1' "$repo_root/test/run-main-coverage.sh" || fail "coverage_100: require.main collection missing"