Skip to content

fix(ui): show the clock failure on the dashboard before a job is refused - #1202

Open
HugoXK wants to merge 2 commits into
mainfrom
dev4/1198-clock-fail-banner
Open

HugoXK wants to merge 2 commits into
mainfrom
dev4/1198-clock-fail-banner

Conversation

@HugoXK

@HugoXK HugoXK commented Nov 21, 2026 •

Copy link
Copy Markdown
Owner

Written-by: Fledge Platform Dev-4

Fixes #1198

The defect

The admission guard refuses every job while clock.state is fail, and /readyz answers 503, but nothing under src/views/ read the clock — grep -i clock src/views/ public/ found no surface at all. On the live host the state is fail with skewSeconds: 1688 against thresholdSeconds: 120, so manual, scheduled and follow-up triggers are all refused and the dashboard says nothing. A user learned it only after pressing Run now and reading the refusal; docs/deploy.md:1615-1618 already promises "the console banner names the measured seconds".

What changed

  • src/app.ts /dashboard passes clock: githubApp.clockState() — the same object the guard reads at src/jobs/service.ts:1291 and /readyz reads at src/app.ts:1218.
  • src/views/pages.ts adds an optional clock input and clockFailAlert(), which emits one AlertView with level: 'critical' and a new kind: 'clock_skew' only when state === 'fail'. alertText renders it through the existing bilingual t(): the measured seconds, the threshold, and the host-clock recovery (timedatectl set-ntp true, then /readyz returns 200 within one measurement window).
  • src/db.ts gives AlertView optional skewSeconds / thresholdSeconds. message is one string and cannot carry the zh/en pair, and Store.alerts never sets either field.
  • docs/architecture.md records the display rule beside the clock section.

/readyz, the CLOCK_SKEW refusal at src/lib/failure.ts:282, the threshold and the refusal contract are untouched.

Why a banner and not a row in the existing alert table

The dashboard's "Needs attention" table is rendered inside <details class="secondary"> ("More: repositories, delivery and jobs"), which is collapsed unless a deep link or a paged list opens it. A critical alert placed there would satisfy a text search and show the user nothing without expanding "More" — exactly the failure this card is about. The banner renders above that section, directly under the masthead, with role="alert".

Absence half

Only fail paints it. ok renders nothing, unknown renders nothing (a young process, or a GitHub outage past the 15-minute reuse window), and not-configured renders nothing (a deployment with no App is not a clock verdict). test/clockFailBanner.test.ts asserts all three across both locales, and asserts an absent reading renders byte-identical to a healthy one.

Ran:

  • npm run check — pass (lint 11 baseline warnings in 8 entries, typecheck, 3268/3268 tests, build)
  • node scripts/version.mjs check — pass (version: 0.4.4 ok)
  • npx tsx --test test/clockFailBanner.test.ts at the base f1c48ed3 — red: zh: expected exactly one clock banner, rendering it 0 times
  • booted instance at this tip: GET /readyz → 503, clock.state: "fail", skewSeconds: 1688, thresholdSeconds: 120; the banner is present at both widths in both locales and document.scrollWidth never exceeds the viewport
    Not run: Docker image, real SMTP, a production deploy (owner action, out of this slice).

Frames

Shot from a Fledge instance booted from this branch. The before run has no GitHub App (clock.state: not-configured), so it shows the dashboard with no clock surface; the after run points GITHUB_API_BASE at a local fake whose Date header is 1688 s behind, which is the offset production reported. Same data directory, login and mock runner in both.

Before — en 1280:
before en 1280

After — en 1280:
after en 1280

Before — zh 1280:
before zh 1280

After — zh 1280:
after zh 1280

Before — en 360:
before en 360

After — en 360:
after en 360

Before — zh 360:
before zh 360

After — zh 360:
after zh 360

Evidence branch evidence/1198-clock-fail-banner carries the frames and a README stating how they were produced. Measured on the after run: 1116x69 at 1280 (x=82, y=414), 328x178 at 360 (x=16, y=545), no horizontal overflow.

Uncertainty and residual risk

  • The banner is dashboard-only. /settings, /admin and the repository page do not carry it; the card scoped one view change, so a user who lands elsewhere first still meets the refusal sentence rather than the banner. Widening it is a separate card.
  • The sentence says "is N seconds from GitHub time", so a negative skewSeconds reads as a clock behind rather than ahead; the number keeps its sign instead of being absolute, because the direction is what tells an operator which way to correct.
  • The alert is not mailed or pushed to the in-app notification list (non-goal in the card). /readyz remains the monitor's signal.
  • AlertView gained two optional fields; every existing constructor keeps compiling and Store.alerts never sets them.

Alternatives considered

  • Render the alert as a row in the existing table (rejected: collapsed section, invisible without expanding "More").
  • Put the wording in AlertView.message (rejected: one string, no zh/en pair, and the existing alertText switch is how every other kind stays bilingual).
  • Build the alert in the route and append it to alerts (rejected: the view owns alert wording, and the route has no translator).

Fledge Platform Dev-4 added 2 commits November 21, 2026 04:40
The admission guard refuses every job while `clock.state` is `fail`, and
`/readyz` answers 503, but nothing under `src/views/` read the clock: a user
learned the platform could not start work only after pressing Run now and
reading the refusal.

The dashboard route now passes the same `clockState()` the guard and `/readyz`
read into `dashboardPage`, which emits one critical `AlertView` when the state
is `fail` and names the measured `skewSeconds` and `thresholdSeconds` in both
locales, with the host-clock recovery step. It renders as a banner above the
collapsed secondary section rather than as a row in the alert table, because
that table lives inside the collapsed section and a refused job is not a
detail a user should have to expand.

Only `fail` paints it: `ok`, `unknown` and `not-configured` render nothing, so
a GitHub outage or an app-less deployment does not produce a permanent red
banner. `/readyz` and the `CLOCK_SKEW` refusal sentence are unchanged.

Docs-not-needed: docs/architecture.md carries the dashboard rule in this commit.
…banner

The banner interpolation sat on its own template line, so an absent clock left
an indented empty line in the rendered HTML and the mock dashboard fixture
drifted. The banner now brings its own leading newline and an absent reading
emits nothing, so the no-banner render is byte-identical to the base and
`mock/` needs no regeneration.

This branch has not been deployed

No deployments
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.

bug: production is in clock fail and the console banner the deploy doc promises does not exist

1 participant