diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 89912c8..8ab649c 100644 --- a/CONTRIBUTING.md +++ b/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. diff --git a/README.md b/README.md index 369ad79..df66150 100644 --- a/README.md +++ b/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 diff --git a/REVIEW.md b/REVIEW.md index 2fc5a6b..12e034f 100644 --- a/REVIEW.md +++ b/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. diff --git a/test/test-server.sh b/test/test-server.sh index bc0026f..716b521 100755 --- a/test/test-server.sh +++ b/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"