// 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 header's compact connection state badge. 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" }; } }