Files
pipelines/web/src/connection.js
T
alan 84e136436c web: app shell — left destination rail, settings-hosted connection, viewport panes
The layout item's work plus the two defects its review found:
- the wide grid sized the list track from its MAX, so at 600-759px the detail pane
  was clipped to 40-199px; cap the list below 900px and narrow the rail there
  (measured now: detail 232px at 600, 332 at 700, 340 at 900, 880 at 1440);
- the shell said 'Not connected' on a fresh page because the prefilled proxy URL
  validated; the status now reflects a SAVED endpoint ('Not configured' until then)
  and refreshes as the draft changes.

Includes the rail + bottom dock, connection moved into Settings, viewport-only
scrolling with panes that scroll themselves, tab semantics, skip link, h1 per
route, and the design tokens.
2026-10-19 20:03:56 +01:00

197 lines
8.2 KiB
JavaScript

// Pure connection helpers for the browser client: how the persistent connection
// banner reads, what the page does the moment it becomes visible again, whether
// the ping reply's protocol/build can be trusted, and what the live badge says.
//
// Deliberately free of DOM, sockets and timers, so every branch is unit-testable
// in Node and renders identically in the page. The wording and colour roles are
// the Android client's own:
// ui/components/ConnectionBanner.kt — banner copy and container colours
// data/transport/ConnectionRecovery.kt — the foregroundAction policy
// data/ForegroundReconnector.kt — order and liveness check
// ui/components/LiveBadge.kt, ui/RunStream.kt — the live badge words
// ui/screens/SettingsScreen.kt — the built "Connected" line
/** The reconnect affordance, exactly as ConnectionBanner.kt names it. */
export const RECONNECT_LABEL = "Reconnect";
/**
* The one definition of the connecting line: `Connecting (attempt N)…`, shared by
* the persistent banner and the Settings status card so the same app sentence can
* never drift between the two.
*/
export function connectingLabel(attempt) {
return `Connecting (attempt ${attempt ?? 0})\u2026`;
}
/** Idle banner copy, verbatim from ConnectionBanner.kt. */
export const IDLE_BANNER_TEXT =
"Not connected. Enter the server URL in Settings, then connect.";
/** ConnectionBanner.kt's suffix while the client has a retry scheduled. */
export const RETRYING_SUFFIX = " \u00b7 retrying with backoff";
/** What the app does with the connection the moment it becomes visible again. */
export const ForegroundAction = Object.freeze({
/** Leave the connection exactly as it is. */
LeaveAlone: "LeaveAlone",
/** Reconnect now, cancelling any pending reconnect delay. */
Reconnect: "Reconnect",
});
/**
* Derive the persistent banner from the client's connection state.
*
* `tone` names the Material container role the stylesheet paints
* (surfaceVariant for idle/connecting, errorContainer for disconnected,
* primary/ok for connected); `text` is the app's own copy; `action` is the
* reconnect affordance, offered only while idle or disconnected and only when an
* endpoint is configured (ConnectionBanner.kt's `actionEnabled`). ConnectionBanner.kt
* renders nothing once connected, so the page's explicit green "Connected" (the
* primary-coloured state SettingsScreen.kt shows) is the one visible difference.
*
* The disconnected copy is verbatim ConnectionBanner.kt: `Disconnected:
* {message}` plus ` · retrying with backoff` while a retry is scheduled. That
* banner text deliberately omits the attempt number (Android only names it while
* Connecting), so the page surfaces the retry attempt in its header state badge
* instead — see `stateBadge` — rather than diverging from the banner wording.
*/
export function bannerState(connection, { hasEndpoint = false } = {}) {
const c = connection ?? {};
switch (c.kind) {
case "connected":
return { tone: "ok", text: "Connected", action: null };
case "connecting":
return {
tone: "connecting",
text: connectingLabel(c.attempt),
action: null,
};
case "disconnected": {
const reason = String(c.reason ?? "").trim() || "connection closed";
const retry = c.retrying ? RETRYING_SUFFIX : "";
return {
tone: "error",
text: `Disconnected: ${reason}${retry}`,
action: hasEndpoint ? RECONNECT_LABEL : null,
};
}
default:
return {
tone: "idle",
text: IDLE_BANNER_TEXT,
action: hasEndpoint ? RECONNECT_LABEL : null,
};
}
}
/**
* The app's return-to-foreground policy in one place (ConnectionRecovery.kt).
*
* A deliberate Disconnect is the only way the client reaches Idle, so Idle is
* left alone; every other state reconnects. A still-Connected socket is not
* trusted on return — a frozen process or a suspended tab can leave it claiming
* Connected while it answers nothing — so the caller probes it and passes the
* verdict as `confirmedAlive`, which is consulted only for Connected.
*/
export function foregroundAction(state, confirmedAlive) {
switch (state?.kind) {
case "idle":
return ForegroundAction.LeaveAlone;
case "connected":
return confirmedAlive ? ForegroundAction.LeaveAlone : ForegroundAction.Reconnect;
default:
// Connecting and Disconnected both carry their own answer; an unknown state
// is never trusted, so it reconnects like the app's non-Connected states.
return ForegroundAction.Reconnect;
}
}
/**
* Compare the page's protocol with the server's `pong.protocol`. Returns null
* unless both values are present and differ, because a server that omits the
* field (older build) must not be flagged; otherwise a warning naming both.
*/
export function protocolMismatch(clientProtocol, serverProtocol) {
if (!isProtocol(clientProtocol) || !isProtocol(serverProtocol)) return null;
if (Number(clientProtocol) === Number(serverProtocol)) return null;
return `Protocol mismatch: this page speaks protocol ${clientProtocol}, the server reports ${serverProtocol}.`;
}
function isProtocol(value) {
return value !== null && value !== undefined && value !== "" && !Number.isNaN(Number(value));
}
/**
* The compact connection state helper behind the shell's dot+word control and
* the Settings status card. It is the page's own indicator (Android renders the
* same facts in SettingsScreen.kt's connection card): the one job it does that
* ConnectionBanner.kt's banner text does not is name the retry attempt while
* disconnected, so "reason + retrying + attempt" are all visible at a glance.
* `tone` names the dot colour class (ok/warn/bad/idle).
*/
export function stateBadge(connection) {
const c = connection ?? {};
switch (c.kind) {
case "connected":
return { tone: "ok", text: "connected" };
case "connecting":
return { tone: "warn", text: `connecting\u2026 (attempt ${c.attempt ?? 0})` };
case "disconnected": {
const reason = String(c.reason ?? "").trim();
const retry = c.retrying ? (c.attempt ? `attempt ${c.attempt}, retrying` : "retrying") : c.attempt ? `attempt ${c.attempt}` : "";
return { tone: "bad", text: `disconnected${reason ? ` \u2014 ${reason}` : ""}${retry ? ` (${retry})` : ""}` };
}
default:
return { tone: "idle", text: "idle" };
}
}
/**
* Render the server's `pong.build` (version/commit/dirty) for the banner, so a
* stale server is visible at a glance. The shape is SettingsScreen.kt's exactly:
* `Server build {version} ({commit})`. Missing fields are tolerated: nothing is
* shown when there is nothing to say.
*
* No separate dirty marker: internal/buildinfo already folds a dirty tree into
* `version` as a `-dirty` suffix (buildinfo.go), so `Server build v1-dirty (abc)`
* is the honest, non-duplicated form (Android renders no dirty marker either).
*/
export function serverBuildLabel(build) {
const info = build && typeof build === "object" ? build : {};
const version = String(info.version ?? "").trim();
const commit = String(info.commit ?? "").trim();
const parts = [];
if (version) parts.push(version);
if (commit) parts.push(`(${commit})`);
if (!parts.length) return "";
return `Server build ${parts.join(" ")}`;
}
/**
* The live-stream states, exactly RunStream.kt's three words. The page tracks
* this itself (it owns the subscription), so the badge says whether the pushes
* are arriving rather than guessing from whether a run happens to be executing.
*/
export const RunStream = Object.freeze({
Live: "live",
Connecting: "connecting",
Offline: "offline",
});
/**
* The live-stream badge, mirroring LiveBadge.kt / RunStream.kt: the explicit
* stream state maps to the app's own word and dot ("live" / "reconnecting" /
* "not live"). The word always carries the meaning, so colour is never the only
* signal, and the badge is independent of whether any run is executing.
*/
export function liveBadgeState(streamState) {
switch (streamState) {
case RunStream.Live:
return { tone: "live", label: "live" };
case RunStream.Connecting:
return { tone: "reconnecting", label: "reconnecting" };
default:
return { tone: "not-live", label: "not live" };
}
}