Skip to content

fix(dashboard): show a proxy's 502/503 page as a temporary outage - #31882

Merged
bolichen97 merged 1 commit into
mainfrom
fix/9582-edge-html-unavailable-copy
Nov 7, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/9582-edge-html-unavailable-copy

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: When a tunnel or proxy answers with its own error page while the gateway restarts, the dashboard says the server is temporarily unavailable and to try again, instead of a bare HTTP 502.

Since #9484, an edge or proxy HTML error page no longer leaks its markup into the error message. It falls through to HTTP <status> instead, so a tunnel 502 during a gateway restart reads HTTP 502 in the topbar and in error cards. That is accurate, but it gives no hint that the condition is temporary and worth retrying.

Why it matters

Anyone reaching the dashboard through a tunnel or reverse proxy sees this every time the gateway restarts. A bare status code looks the same as a lasting failure, so the user has no reason to wait and retry rather than go looking for a fault.

Not a goal

  • Changing what a JSON or plain-text error body shows: those keep their own message.
  • Changing a surface that supplies its own sentence for a body with no message (the channel-folder backfill panel, the deploy page's pending confirm/dismiss card).
  • Giving a 504 proxy timeout new copy: the request may have run, so "try again" could repeat it.
  • App clients that build their own error text without the shared toApiError.

What changed (motivation → approach → change)

A proxy's own 502 or 503 page carries no human message, so both shared transports (apiFailure in api/client.ts and toApiError in api/apiError.ts) fell back to HTTP <status>. The 429 tunnel throttle already maps to a catalog sentence in the same module, so this follows that pattern.

A new statusErrText in api/apiError.ts is the fallback both transports now use: an HTML document body on 502 or 503 reads "The server is temporarily unavailable (HTTP 502)", and everything else still reads HTTP <status>. Like the HTTP 502 it replaces, it names only the cause and has no end punctuation: a caller that wraps the message and adds its own period and next step (the Restart notice, the Duplicate alert) then ends the sentence once and gives the advice once, and a 502 after a POST is not told to repeat it. friendlyErrText keeps returning '' for such a body, so callers that use it to ask "did the body carry a message?" keep their own sentence. The deploy page's pending-action card compares against statusErrText instead of the literal HTTP <status>, so it still shows its own "Confirm failed (502)".

The new key api.client.server_temporarily_unavailable_http_status is in en.manual.json, all eleven translated catalogs and the regenerated en-XA pseudolocale, each in its style guide's register. Two comments that said the transport shows HTTP 502 for such a page now say "status line".

Response Before After
HTML page, 502 or 503 HTTP 502 The server is temporarily unavailable (HTTP 502)
HTML page, 504 or 500 HTTP 504 unchanged
JSON {"error": ...} or plain text, any status its message unchanged
Empty body HTTP <status> unchanged

Backwards compatibility

Compatible: only the displayed message for an HTML 502/503 body changes. Status codes, ApiError.body, retry policy and every caller's branching are unchanged.

Removes nothing: the raw page stays on ApiError.body and every other fallback message is the same.

Tests

  • test/apiError.test.ts: an HTML 502 and 503 page give the new sentence through toApiError and keep the raw page on body; an HTML 500 and 504 keep HTTP <status>.
  • test/throttleRetry.test.ts: an HTML 502 through the dashboard's j helper (apiFailure) gives the new sentence.
  • apps/dev-fleet/devFleetApi.test.ts and test/PublishHub.proxyErrorPage.test.tsx: the app client and the publish banner, which used to pin HTTP 502, now pin the new sentence.
  • With both transport lines reverted to HTTP ${r.status}, all five of those cases fail; the deploy-page and backfill-panel tests stay green either way.
  • test/useSessionActions.test.tsx: a Duplicate refused by a proxy HTML 502 page alerts "Try again in a moment." once, with the reason built by the real statusErrText.
  • components/RestartButton.cov80.test.tsx: a restart refused the same way reads "Could not restart — The server is temporarily unavailable (HTTP 502). Wait a moment, …" with one period.

Proof: not provable -- frontend test (prove.py runs Python only)

Manual verification

Built the SPA and served it with every /api call stubbed; the channel create answered with a proxy HTML 502 page. The dialog's error notice reads the new sentence (screenshot below). Catalog parity, style-guide, i18n:check and i18n:render gates pass.

Screenshots / video

New Channel create answered by a proxy's HTML 502 page:

The create dialog's error notice reads: Failed to create channel The server is temporarily unavailable (HTTP 502)

Before this change the same notice read Failed to create channel HTTP 502.

Related Issues

Closes #9582

Sibling sweep

Swept: git grep -n 'friendlyErrText|HTTP ${' -- website/src
Sibling: website/src/api/client.ts -- changed here
Sibling: website/src/api/apiError.ts -- changed here
Sibling: website/src/pages/ArtifactDeployPage.tsx -- changed here
Sibling: website/src/pages/settings/ChannelFolderBackfill.tsx -- not affected -- supplies its own sentence when the body has no message
Sibling: website/src/api/client/apps.ts -- not affected -- registry install stream throws its own text, outside the shared transports
Sibling: website/src/hooks/useSessionActions.ts -- not affected -- wraps the message and adds its own retry sentence, which the cause-only string leaves single
Sibling: website/src/components/RestartButton.tsx -- not affected -- its template adds the period after the reason, which the unpunctuated string leaves single

Pattern harvest

Not generalizable: a single fallback message for one class of proxy response, now decided in one function both transports call.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license (see CONTRIBUTING.md).

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 6, 2026 23:21
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 6, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) November 6, 2026 23:43
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of b5c853a5bfae8819bb7ce17fd32b496c5237c6a1 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. The fallback is decided in one place that both transports call, there is a screenshot of this revision, and nothing outside the patch compares a message against HTTP <status>.

[DESIGN-REVIEWED] b5c853a

Description read

[DESCRIPTION-READ] e138bcd181d11b560d714dd3189b176da8c40f59d9acd0d7b09c06cce8cd3d75

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of b5c853a5bfae8819bb7ce17fd32b496c5237c6a1 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing blocks: this is a copy-only change, the screenshot shows the new sentence, and the blind reader read "temporarily" as "waiting and trying again would work", which is what the PR wants.

Notes

  • The Goal says the dashboard will tell the user to "try again", but api.client.server_temporarily_unavailable_http_status only says the server is down for now. The PR deliberately leaves the retry advice to callers that add their own. In the New Channel dialog nobody adds it, and the blind reader hesitated: "nothing tells me whether trying now is okay … a second click might make two channels." Either have the create-failure notice add the "Try again in a moment." line that Duplicate already uses, or record why this dialog stays silent on retrying.
  • The bold "Failed to create channel" title and the new sentence run together with no stop between them ("reads like one broken sentence"). The notice layout is outside this diff, but this sentence is now the most common thing that notice shows.

[UX-REVIEWED] b5c853a

Description read

[DESCRIPTION-READ] d9cf305563727b3fc3f51390b5d948d1bb3506532cff718e8fcd0a2172e42d71

That sha256 names everything this verdict read: the PR description, plus the 4 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of b5c853a5bfae8819bb7ce17fd32b496c5237c6a1 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

This is a small fix tied to issue #9582. Both shared transports now share one fallback, and nothing in the diff blocks it.

What this change ships

Inventory (5 items) — 5 justified

Intent: when a gateway restarts behind a tunnel or proxy, users should see that the outage is temporary and that they can retry. FIX.

  1. An HTML 502/503 page from a proxy now reads "The server is temporarily unavailable (HTTP 502)" instead of "HTTP 502", in both toApiError and apiFailure — justified
  2. New exported statusErrText, the fallback both transports share (2 transport consumers, plus the deploy-page comparison) — justified
  3. New catalog key api.client.server_temporarily_unavailable_http_status in all locales — justified
  4. The deploy page's pending confirm/dismiss card keeps "Confirm failed (502)" because it now compares against statusErrText — justified
  5. The old pin toBe('HTTP 502') is rewritten. That pin guarded against markup leaking into the message, and the new tests still check this. The description and Edge HTML error pages report as bare HTTP <status> with no human message #9582 name the reversal — justified

[FIRST-PRINCIPLES-REVIEWED] b5c853a

Description read

[DESCRIPTION-READ] 48565742a9f87a651706c4605a56cd890ffc567e3a931fa06bbff0bbab575576

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of b5c853a5bfae8819bb7ce17fd32b496c5237c6a1 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] b5c853a

False positive or not applicable? A repository writer can comment:
/ai-review override gpt b5c853a5bfae8819bb7ce17fd32b496c5237c6a1 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed b5c853a5bfae8819bb7ce17fd32b496c5237c6a1 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] b5c853a

Verdict parsed from the review's SHA-scoped output markers for commit b5c853a5bfae8819bb7ce17fd32b496c5237c6a1.

False positive or not applicable? A repository writer can comment:
/ai-review override fable b5c853a5bfae8819bb7ce17fd32b496c5237c6a1 false-positive: <reason, 20 to 500 characters>

@bolichen97
bolichen97 force-pushed the fix/9582-edge-html-unavailable-copy branch from 9453bfa to abbceba Compare November 7, 2026 07:36
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in website/src/api/apiError.ts, website/src/api/client.ts and the 13 locale catalogs this PR edits (0984ba7 -> b65af1a); CI re-running. The patch is unchanged: same added and removed lines, only the surrounding context moved. The previous head's CI run never finished because its Lint Gate job sat queued with no runner from 2026-11-06T23:29Z, so the tests behind it had not run. On the new base: tsc -p tsconfig.app.json, eslint on the touched files, i18n-check, lint:i18n and the 76 related vitest files (1620 tests) pass.

[operator: bolichen97]

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 7, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

[operator: bolichen97] Backend Tests shard 2 (Linux and Windows), and the Coverage Gate behind them, are red on test/test_security_gate_liveness.py::test_the_package_stays_within_its_line_budget: the security package is 34,855 lines on main against a budget of 34,845. That is red on main too, and this PR does not touch that package. #32183 fixes it. This PR waits for that fix, then rebases onto it.

The Opus finding on the repeated "Try again in a moment." sentence is valid. It gets fixed in that same push.

A tunnel or proxy answers with its own HTML page while the gateway
restarts, and since #9484 that page reads as a bare "HTTP 502", which
looks like a lasting failure. When such a page arrives with 502 or 503,
the dashboard and app clients now say the server is temporarily
unavailable, in every shipped language. Like the "HTTP 502" it replaces,
the text names only the cause and has no end punctuation, so a message
that wraps it keeps its own period and retry advice and says each once.
A 504 keeps "HTTP 504", since the request may have run. A JSON or
plain-text body keeps its own message, and a caller with a sentence of
its own keeps it.

Closes #9582
@bolichen97
bolichen97 force-pushed the fix/9582-edge-html-unavailable-copy branch from abbceba to b5c853a Compare November 7, 2026 14:54
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in website/src/i18n/locales/*.json (the 13 catalogs this PR edits) and website/src/api/client.ts since this head's CI ran (b65af1a -> d27a5fd); CI re-running. The same push carries the fix for the Opus finding; its disposition follows.
[operator: bolichen97]

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=76c76196f13b: the outage text carried its own "Try again in a moment."

fixed in b5c853a: the transport's outage text names only the cause, "The server is temporarily unavailable (HTTP {{status}})", with no retry sentence and no end punctuation, in all 13 catalogs (en-XA regenerated).
A template that wraps the message keeps its own period and next step, so the Duplicate alert gives "Try again in a moment." once and the Restart notice ends its sentence once; the class sweep covered every English template that puts a wrapped error before its own punctuation.
Tests: useSessionActions.test.tsx (Duplicate) and RestartButton.cov80.test.tsx (Restart), both fed by the real statusErrText; the Restart test fails on the old value.
[operator: bolichen97]

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 7, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved: PR Readiness passed on b5c853a, and all five review lanes (Opus 5.5, GPT 6.1, Design, UX, First Principles) report no blocking finding on this head. No conflict and no open change request.

@bolichen97
bolichen97 merged commit b3be506 into main Nov 7, 2026
99 checks passed
@bolichen97
bolichen97 deleted the fix/9582-edge-html-unavailable-copy branch November 7, 2026 19:47
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 7, 2026
bolichen97 added a commit that referenced this pull request Nov 9, 2026
…1882)

A tunnel or proxy answers with its own HTML page while the gateway
restarts, and since #9484 that page reads as a bare "HTTP 502", which
looks like a lasting failure. When such a page arrives with 502 or 503,
the dashboard and app clients now say the server is temporarily
unavailable, in every shipped language. Like the "HTTP 502" it replaces,
the text names only the cause and has no end punctuation, so a message
that wraps it keeps its own period and retry advice and says each once.
A 504 keeps "HTTP 504", since the request may have run. A JSON or
plain-text body keeps its own message, and a caller with a sentence of
its own keeps it.

Closes #9582

(cherry picked from commit b3be506)

Backport note: RestartButton.cov80.test.tsx keeps release's imports and
window.confirm stub (main's confirmAction dialog helper and within
import come from a later change not on release), so the new 502 case
drops its confirmAction step.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Edge HTML error pages report as bare HTTP <status> with no human message

2 participants