Skip to content

Show the Thundermail downtime banner in webmail - #263

Closed
aaspinwall wants to merge 11 commits into
mainfrom
feat/downtime-banner
Closed

aaspinwall wants to merge 11 commits into
mainfrom
feat/downtime-banner

Conversation

@aaspinwall

@aaspinwall aaspinwall commented Nov 18, 2026 •

Copy link
Copy Markdown

What changed?

Webmail now shows the Thundermail downtime banner that operators set on the Keycloak login page. It appears at the top of the login gate, in both the OIDC and app-password views, and as a full-width first row of the signed-in app.

  • Source: Keycloak's built-in theme messages endpoint, GET {keycloak}/resources/{realm}/login/{locale}. It returns every login theme message with the realm's overrides merged in (getEnhancedMessages), as [{"key": "...", "value": "..."}]. The banner is the maintenanceNotice message, and its colour is maintenanceNoticeType (info, warning or critical), from feat(keycloak): downtime banner on the login screen thunderbird-accounts#1491. There is no Accounts endpoint and no Accounts dependency beyond those two theme messages.

  • src/defines.ts: loginMessagesUrl(locale = "en") derives the URL from the existing OIDC_ISSUER by turning …/realms/tbpro into …/resources/tbpro/login/en:

    • prod and alpha (VITE_OIDC_ISSUER=https://auth.tb.pro/realms/tbpro) → https://auth.tb.pro/resources/tbpro/login/en
    • stage and the default (https://auth.stage-thundermail.com/realms/tbpro) → https://auth.stage-thundermail.com/resources/tbpro/login/en
    • local stack (http://localhost:3000/realms/tbpro) → http://localhost:3000/resources/tbpro/login/en, which the dev server already proxies to Keycloak (/resources in vite.config.js)
    • an issuer without /realms/<name> → empty, and nothing is fetched.

    No new environment variable.

  • src/composables/useDowntimeBanner.ts:

    • one fetch on mount, with a 2 s timeout, cache: 'no-store' and credentials: 'omit';
    • finds maintenanceNotice and trims it. Empty or missing means no banner, and that is silent: it is what every load sees when no override is set;
    • maintenanceNoticeType outside info|warning|critical falls back to warning, as the login theme does;
    • a '' in the message is shown as '. The endpoint returns the raw MessageFormat pattern, and the Accounts runbook tells operators to type '' for an apostrophe;
    • a non-OK response, a body that is not a list, a network error or a timeout shows nothing and logs one console.warn('[banner] …'). Nothing in the boot path waits for it.
  • src/App.vue calls the composable once and passes the result as a banner prop to LoginGate and to the shell. The gate is always rendered first, while auth starts, so one load covers both and the banner does not blink out when the gate gives way to the app.

  • src/components/DowntimeBanner.vue only renders the prop, in the services-ui NoticeBar (already a dependency, 1.6.5). The message is plain text; HTML shows literally. overflow-wrap: anywhere makes a long URL wrap on a phone.

  • src/components/LoginGate.vue takes the banner prop and renders it at the top of both views. The existing 12px stack gap spaces it, as it does the alpha warning.

  • Shell layout in src/App.vue:

    • The grid gets a banner row: grid-template-rows: auto auto minmax(0, 1fr).
    • The row's wrapper (.shell__banner) is always rendered, even with no banner, because otherwise the header and content would move up one row and the content row would collapse to zero height. With no banner the row is 0px tall.
    • Below 640px, the explicit rows move down by one: header 1→2, content 2→3, spaces bar 3→4. The folder drawer was offset by --top-nav-height/--spaces-bar-height, which would open it over a banner. It is now placed in the content row (grid-row: 3 / 4; top: 0; bottom: 0), so it opens below the header and banner. With no banner it lands where it did before.
    • A maximized message view is a fixed overlay over the whole shell, so it hides the banner the same way it hides the header (inert, aria-hidden, visibility: hidden). The banner comes back when the view is restored.
  • Tests:

    • 4 composable tests: a set maintenanceNotice with maintenanceNoticeType: critical; an empty or missing maintenanceNotice is null with no warning; a non-OK response is null with one warning; an unknown type falls back to warning.
    • 1 login gate test that renders a banner from the prop.
    • 1 changed app-layout assertion, which now expects the header right after the banner row instead of as the shell's first child.
    • The four suites that mount App stub the composable, so they make no network request.

Implemented by an AI agent from a human-written plan and issue; the author reviewed the design, scope and tests.

Why?

Users who are already signed in never see the Keycloak login page, so they miss the banner that thunderbird/thunderbird-accounts#1491 shows there (#261). Reading the same realm message means one operator action, setting the maintenanceNotice realm override, shows the notice on the login page and in webmail. It is visible on the next webmail load, with no deploy on either side.

Limitations and Notes

  • feat(keycloak): downtime banner on the login screen thunderbird-accounts#1491 must ship first for production to have the maintenanceNotice key. Until then the key is missing, which is the normal "no banner" state: nothing is shown and nothing is logged. Merging first is harmless.
  • If Keycloak is down, there is no banner. The fetch fails (one [banner] warning) and webmail carries on. Maintenance that takes Keycloak down needs a notice outside Keycloak, as the #1491 runbook says.
  • The response is every login theme string, about 44 KB (not compressed by the server today), once per page load. That is acceptable for one request that nothing waits on.
  • It fetches the English messages; a per-locale banner would need the override set for each locale the realm serves.
  • The banner is fetched once per page load. It does not refresh while the tab stays open. There is no dismiss button.
  • Keycloak's MessageFormat rules differ slightly here: a single ' is dropped on the login page but shown in webmail, and {…} breaks the login page but is shown literally in webmail. The runbook already tells operators to use ’/'' and never braces.
  • role="status" is on the bar, which is inserted already filled, so a screen reader may not announce it on insertion. It is the first thing in reading order. Announcement was not tested.
  • The checks below ran on the host, not in the thundermail-dev container, because Docker was not available. CI is authoritative.

Applicable Issues

Closes #261

QA Log

Host-run on Node 24.22.1 (.node-version), not in the dev container. On the host's default Node 26, 278 tests on main already fail, because Node's built-in localStorage hides happy-dom's.

  • curl -sI -H "Origin: https://webmail.thundermail.com" https://auth.tb.pro/resources/tbpro/login/en: 200, application/json, access-control-allow-origin echoes the origin (Keycloak's ThemeResource.getLocalizationTexts builds its CORS response with allowAllOrigins(), so this does not depend on the client's web origins). Same on auth.stage-thundermail.com. Both return 585 entries, 44,672 bytes, and neither has maintenanceNotice yet.
  • npx vue-tsc --noEmit: 0 errors.
  • npx vitest run: 159 files, 2709 tests passed (main: 158 files, 2704).
  • npx eslint src tests/unit: 0 errors (one existing warning in src/stores/mail-store.ts, also on main).
  • npx vite build: exit 0.
  • Each composable test was checked against the line it pins: removing the empty-message return, the response.ok check, the ?? 'warning' fallback, or the '' unescape fails exactly that test.
  • The row change was checked earlier with a static HTML copy of the shell grid rules in headless Chrome at 1280px and 375px, with and without a banner. Without a banner the row is 0px and nothing moves. With a long URL the banner wraps inside 375px. This was not the running app.
  • CI on the head: Typecheck, Unit tests, E2E tests (chromium), E2E tests (firefox), CodeQL.

Not run: the dev container, local e2e against the stack, a visual check of the running app, and screenshots.

Screenshots

None. The local stack needs Docker, which was not available here. To take them:

  1. Start the stack and the dev server as usual (./scripts/local-stack-up.sh, then npm run dev in the dev container). The pinned thunderbird-accounts theme does not define maintenanceNotice yet, but a realm override works without it.
  2. Set the override on the local Keycloak, either:
    • in the admin console (http://keycloak:8999/admin/master/console/, admin / admin): realm tbpro → Realm settings → Localization → Realm overrides → English → Add translation, key maintenanceNotice, value Scheduled maintenance 14:00–16:00 UTC.; optionally maintenanceNoticeType = critical; or
    • via the admin REST API, as #1491's test/e2e/utils/keycloak-admin.ts does:
      curl -X PUT -H "Authorization: Bearer $TOKEN" -H 'Content-Type: text/plain' \
        --data 'Scheduled maintenance 14:00–16:00 UTC.' \
        http://localhost:8999/admin/realms/tbpro/localization/en/maintenanceNotice
    Check curl -s http://localhost:3000/resources/tbpro/login/en | grep maintenanceNotice.
  3. At 1280px and 375px wide, capture:
    • the gate: http://localhost:3000/?app-password stays on the sign-in form with the banner above the alpha warning;
    • the signed-in app (admin@example.org / admin): banner above the header;
    • at 375px, the drawer opened with Show folder list: it starts below the banner;
    • Maximize message view on an open message: the banner is hidden, and it is back after Restore message view.
  4. Delete the override afterwards (console, or the same URL with -X DELETE).

…261)

The banner's row wrapper is always rendered so the header and content keep their rows when there is no banner; the narrow layout's explicit rows and the folder drawer move down one row, and a maximized message view hides the banner like the header.
…d the shell. (#261)

The gate and the shell each fetched it, so a signed-in load requested it twice and the banner blinked out when the gate gave way.
@Sancus

Sancus commented Nov 18, 2026

Copy link
Copy Markdown
Member

Don't worry about this, I'll take care of it.

@Sancus Sancus closed this Nov 18, 2026
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.

Show the Thundermail downtime banner in webmail

2 participants