From 5b3b466a6e25973842871bd99cfecd25deba3396 Mon Sep 17 00:00:00 2001 From: TaprootFreak <142087526+TaprootFreak@users.noreply.github.com> Date: Mon, 24 Aug 2026 11:00:40 +0200 Subject: [PATCH 1/4] Treat unlisted forwards as upstream endpoints A route this process does not list and therefore forwards belongs to the upstream HTTP backend. Forwarding it does not make it a listed route. --- CONTRIBUTING.md | 13 ++++++++----- README.md | 5 +++-- REVIEW.md | 13 +++++++------ test/test-server.sh | 2 ++ 4 files changed, 20 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 89912c8..02f9a9c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -169,10 +169,12 @@ 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 +224,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..92c4a69 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..959424e 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..a9a6277 100755 --- a/test/test-server.sh +++ b/test/test-server.sh @@ -104,6 +104,8 @@ 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 'belong to the upstream HTTP backend' "$repo_root/CONTRIBUTING.md" || fail "unknown_forward: forwarded unlisted routes belong to the upstream backend" +grep -Fq 'not** an endpoint of this process' "$repo_root/README.md" || fail "unknown_forward: README must say unlisted routes are not this process" 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" From 9ed9583483d122faefff6eeeaa1902e0b785edd3 Mon Sep 17 00:00:00 2001 From: TaprootFreak <142087526+TaprootFreak@users.noreply.github.com> Date: Mon, 24 Aug 2026 11:21:03 +0200 Subject: [PATCH 2/4] Pin unlisted-forward ownership in REVIEW and CONTRIBUTING Grep pins now lock the process bullet, both README sentences, and the REVIEW fail rule so unlisted forwards stay upstream endpoints. --- test/test-server.sh | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/test/test-server.sh b/test/test-server.sh index a9a6277..3fb77c2 100755 --- a/test/test-server.sh +++ b/test/test-server.sh @@ -104,12 +104,17 @@ 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 'belong to the upstream HTTP backend' "$repo_root/CONTRIBUTING.md" || fail "unknown_forward: forwarded unlisted routes belong to the upstream backend" +grep -Fq 'Those routes are **not** endpoints of this' "$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' "$repo_root/CONTRIBUTING.md" || fail "unknown_forward: CONTRIBUTING process bullet must say forwarding an unknown route does not list it" grep -Fq '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' "$repo_root/README.md" || fail "unknown_forward: README local-answers must say those routes belong to the upstream HTTP backend" +grep -Fq 'this process. This repository does not name them.' "$repo_root/README.md" || fail "unknown_forward: README local-answers must say those routes do not belong to this process" 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 'not endpoints of this process' "$repo_root/REVIEW.md" || fail "unknown_forward: REVIEW must say unknown routes are not endpoints of this process" +grep -Fq 'belong to the upstream HTTP backend' "$repo_root/REVIEW.md" || fail "unknown_forward: REVIEW must say unknown routes belong to the upstream HTTP backend" 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" From a884f3fa8bd9bbee6a71428d27defde6d0a379a0 Mon Sep 17 00:00:00 2001 From: TaprootFreak <142087526+TaprootFreak@users.noreply.github.com> Date: Mon, 24 Aug 2026 11:38:53 +0200 Subject: [PATCH 3/4] Pin full ownership sentences for unlisted forwards Rewrap the CONTRIBUTING, README, and REVIEW ownership clauses onto single lines so grep pins lock the complete wording, not a prefix. --- CONTRIBUTING.md | 5 ++--- README.md | 4 ++-- REVIEW.md | 4 ++-- test/test-server.sh | 10 ++++------ 4 files changed, 10 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 02f9a9c..8ab649c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -169,9 +169,8 @@ 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) - 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** + 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. diff --git a/README.md b/README.md index 92c4a69..df66150 100644 --- a/README.md +++ b/README.md @@ -49,8 +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. Those routes belong to the upstream HTTP backend, not to -this process. This repository does not name them. +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 959424e..12e034f 100644 --- a/REVIEW.md +++ b/REVIEW.md @@ -133,8 +133,8 @@ 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 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 +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 diff --git a/test/test-server.sh b/test/test-server.sh index 3fb77c2..46885ac 100755 --- a/test/test-server.sh +++ b/test/test-server.sh @@ -104,17 +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' "$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' "$repo_root/CONTRIBUTING.md" || fail "unknown_forward: CONTRIBUTING process bullet must say forwarding an unknown route does not list it" +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 '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' "$repo_root/README.md" || fail "unknown_forward: README local-answers must say those routes belong to the upstream HTTP backend" -grep -Fq 'this process. This repository does not name them.' "$repo_root/README.md" || fail "unknown_forward: README local-answers must say those routes do not belong to 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 'not endpoints of this process' "$repo_root/REVIEW.md" || fail "unknown_forward: REVIEW must say unknown routes are not endpoints of this process" -grep -Fq 'belong to the upstream HTTP backend' "$repo_root/REVIEW.md" || fail "unknown_forward: REVIEW must say unknown routes belong to the upstream HTTP backend" +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" From b3a6b900e350534460c177cc4a784450cd814df9 Mon Sep 17 00:00:00 2001 From: TaprootFreak <142087526+TaprootFreak@users.noreply.github.com> Date: Mon, 24 Aug 2026 11:45:35 +0200 Subject: [PATCH 4/4] Pin the full README lede for unlisted forwards The ownership grep now matches the complete unlisted-traffic sentence, not only the bold suffix. --- test/test-server.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/test-server.sh b/test/test-server.sh index 46885ac..716b521 100755 --- a/test/test-server.sh +++ b/test/test-server.sh @@ -106,7 +106,7 @@ grep -Fq "forbidden** to" "$repo_root/CONTRIBUTING.md" || fail "known_local: CON 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 'not** an endpoint of this process' "$repo_root/README.md" || fail "unknown_forward: README must say unlisted routes are not this process" +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"