Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

fix(web): harden WebSocket reconnect lifecycle (#742)

Gener996493a0ff43
diff --git a/src/web/src/lib/analytics.test.ts b/src/web/src/lib/analytics.test.ts
index ee136869e..e669b4505 100644
--- a/src/web/src/lib/analytics.test.ts
+++ b/src/web/src/lib/analytics.test.ts
@@ -31,9 +31,13 @@ import {
trackSettingsUpdated,
trackCanvasLayoutChanged,
trackCommunityWsFrameDropped,
+ trackCommunityWsAuthFailure,
+ trackCommunityWsLifecycleClose,
trackCommunityWsLifecycleRecovery,
+ trackCommunityWsLifecycleStage,
trackCommunityWsReconcileComplete,
trackCommunityWsReconcileFailure,
+ trackCommunityWsRetryScheduled,
} from "./analytics"
describe("analytics utility", () => {
@@ -313,5 +317,59 @@ describe("analytics utility", () => {
suspensionDuration: "over-2m",
})
})
+
+ it("reports normalized close metadata without raw reasons or identities", () => {
+ trackCommunityWsLifecycleClose({
+ initiator: "validation-timeout",
+ code: 1006,
+ wasClean: false,
+ reasonBucket: "abnormal",
+ reason: "token=secret",
+ userId: "user-1",
+ url: "wss://example.test/?token=secret",
+ } as never)
+ expect(mockSendGTMEvent).toHaveBeenCalledWith({
+ event: "community_ws_lifecycle_close",
+ initiator: "validation-timeout",
+ code: 1006,
+ wasClean: false,
+ reasonBucket: "abnormal",
+ })
+ })
+
+ it("reports bounded auth, stage, and retry fields only", () => {
+ trackCommunityWsAuthFailure({
+ failureClass: "credentials",
+ token: "secret",
+ } as never)
+ trackCommunityWsLifecycleStage({
+ stage: "auth",
+ result: "timeout",
+ durationMs: Number.POSITIVE_INFINITY,
+ nonce: "private",
+ } as never)
+ trackCommunityWsRetryScheduled({
+ attempt: 3_000,
+ delayMs: -1,
+ windowMs: 900_000,
+ rawReason: "private",
+ } as never)
+
+ expect(mockSendGTMEvent.mock.calls).toEqual([
+ [{ event: "community_ws_auth_failure", failureClass: "credentials" }],
+ [{
+ event: "community_ws_lifecycle_stage",
+ stage: "auth",
+ result: "timeout",
+ durationMs: 0,
+ }],
+ [{
+ event: "community_ws_retry_scheduled",
+ attempt: 1_000,
+ delayMs: 0,
+ windowMs: 600_000,
+ }],
+ ])
+ })
})
})
diff --git a/src/web/src/lib/analytics.ts b/src/web/src/lib/analytics.ts
index c37f7c08a..6b68153f6 100644
--- a/src/web/src/lib/analytics.ts
+++ b/src/web/src/lib/analytics.ts
@@ -207,6 +207,47 @@ export type CommunityWsSuspensionDurationBucket =
| "under-30s"
| "unknown"
+export type CommunityWsCloseInitiator =
+ | "auth-failure"
+ | "connect-timeout"
+ | "freeze"
+ | "heartbeat-timeout"
+ | "local-retire"
+ | "manual-retry"
+ | "offline"
+ | "remote"
+ | "validation-failure"
+ | "validation-timeout"
+
+export type CommunityWsCloseReasonBucket =
+ | "abnormal"
+ | "going-away"
+ | "normal"
+ | "other"
+ | "policy"
+ | "server-error"
+ | "unknown"
+
+export type CommunityWsAuthFailureClass =
+ | "credentials"
+ | "network"
+ | "server"
+ | "timeout"
+ | "unknown"
+
+export type CommunityWsLifecycleStage = "auth" | "open" | "token" | "validation"
+
+export type CommunityWsLifecycleStageResult =
+ | "aborted"
+ | "failure"
+ | "success"
+ | "timeout"
+
+function boundedCommunityWsInteger(value: number, maximum: number): number {
+ if (!Number.isFinite(value)) return 0
+ return Math.min(Math.max(0, Math.round(value)), maximum)
+}
+
function sendCommunityWsGTMEvent(payload: Record<string, unknown>) {
try {
sendGTMEvent(payload)
@@ -271,6 +312,56 @@ export function trackCommunityWsLifecycleRecovery(params: {
});
}
+export function trackCommunityWsLifecycleClose(params: {
+ initiator: CommunityWsCloseInitiator
+ code: number
+ wasClean: boolean
+ reasonBucket: CommunityWsCloseReasonBucket
+}) {
+ sendCommunityWsGTMEvent({
+ event: "community_ws_lifecycle_close",
+ initiator: params.initiator,
+ code: boundedCommunityWsInteger(params.code, 4999),
+ wasClean: params.wasClean === true,
+ reasonBucket: params.reasonBucket,
+ });
+}
+
+export function trackCommunityWsAuthFailure(params: {
+ failureClass: CommunityWsAuthFailureClass
+}) {
+ sendCommunityWsGTMEvent({
+ event: "community_ws_auth_failure",
+ failureClass: params.failureClass,
+ });
+}
+
+export function trackCommunityWsLifecycleStage(params: {
+ stage: CommunityWsLifecycleStage
+ result: CommunityWsLifecycleStageResult
+ durationMs: number
+}) {
+ sendCommunityWsGTMEvent({
+ event: "community_ws_lifecycle_stage",
+ stage: params.stage,
+ result: params.result,
+ durationMs: boundedCommunityWsInteger(params.durationMs, 600_000),
+ });
+}
+
+export function trackCommunityWsRetryScheduled(params: {
+ attempt: number
+ delayMs: number
+ windowMs: number
+}) {
+ sendCommunityWsGTMEvent({
+ event: "community_ws_retry_scheduled",
+ attempt: boundedCommunityWsInteger(params.attempt, 1_000),
+ delayMs: boundedCommunityWsInteger(params.delayMs, 600_000),
+ windowMs: boundedCommunityWsInteger(params.windowMs, 600_000),
+ });
+}
+
// ─── P3 — Page-Level Behavior ───────────────────────────────────────────────
export function trackLandingCtaClicked(params: { cta_name: string }) {
diff --git a/src/web/src/lib/use-user-ws.test.ts b/src/web/src/lib/use-user-ws.test.ts
index b2ee46949..90fab095f 100644
--- a/src/web/src/lib/use-user-ws.test.ts
+++ b/src/web/src/lib/use-user-ws.test.ts
@@ -6,9 +6,17 @@ import {
import type { UseUserWsOptions } from "./use-user-ws"
const mockTrackCommunityWsLifecycleRecovery = vi.hoisted(() => vi.fn())
+const mockTrackCommunityWsAuthFailure = vi.hoisted(() => vi.fn())
+const mockTrackCommunityWsLifecycleClose = vi.hoisted(() => vi.fn())
+const mockTrackCommunityWsLifecycleStage = vi.hoisted(() => vi.fn())
+const mockTrackCommunityWsRetryScheduled = vi.hoisted(() => vi.fn())
vi.mock("@/lib/analytics", async (importOriginal) => ({
...await importOriginal<typeof import("@/lib/analytics")>(),
+ trackCommunityWsAuthFailure: mockTrackCommunityWsAuthFailure,
+ trackCommunityWsLifecycleClose: mockTrackCommunityWsLifecycleClose,
trackCommunityWsLifecycleRecovery: mockTrackCommunityWsLifecycleRecovery,
+ trackCommunityWsLifecycleStage: mockTrackCommunityWsLifecycleStage,
+ trackCommunityWsRetryScheduled: mockTrackCommunityWsRetryScheduled,
}))
// --- Mock WebSocket ---
@@ -23,7 +31,7 @@ class MockWebSocket {
onopen: (() => void) | null = null
onmessage: ((e: { data: string }) => void) | null = null
onerror: (() => void) | null = null
- onclose: (() => void) | null = null
+ onclose: ((event?: { code: number; reason: string; wasClean: boolean }) => void) | null = null
closed = false
sent: string[] = []
@@ -32,14 +40,23 @@ class MockWebSocket {
MockWebSocket.instances.push(this)
}
send(data: string) { this.sent.push(data) }
- close() { this.closed = true; this.readyState = MockWebSocket.CLOSED; this.onclose?.() }
+ close() {
+ if (this.readyState === MockWebSocket.CLOSING || this.readyState === MockWebSocket.CLOSED) return
+ this.closed = true
+ this.readyState = MockWebSocket.CLOSED
+ this.onclose?.({ code: 1000, reason: "local detail", wasClean: true })
+ }
// Helpers for tests
simulateOpen() { this.readyState = MockWebSocket.OPEN; this.onopen?.() }
simulateMessage(data: unknown) { this.onmessage?.({ data: JSON.stringify(data) }) }
simulateRawMessage(data: string) { this.onmessage?.({ data }) }
simulateError() { this.onerror?.() }
- simulateClose() { this.readyState = MockWebSocket.CLOSED; this.onclose?.() }
+ simulateClose(code = 1006, reason = "remote detail", wasClean = false) {
+ this.closed = true
+ this.readyState = MockWebSocket.CLOSED
+ this.onclose?.({ code, reason, wasClean })
+ }
}
vi.stubGlobal("WebSocket", MockWebSocket)
@@ -79,8 +96,10 @@ const mockDocument = Object.assign(new MockEventTarget(), {
wasDiscarded: false,
})
const mockWindow = Object.assign(new MockEventTarget(), { location: { origin: "http://localhost:3000" } })
+const mockNavigator = { onLine: true }
vi.stubGlobal("document", mockDocument)
vi.stubGlobal("window", mockWindow)
+vi.stubGlobal("navigator", mockNavigator)
// Mock fetch for /api/ws/token
const mockFetch = vi.fn()
@@ -198,6 +217,7 @@ function dispatchWindowFocus() {
}
function resetMockState() {
+ vi.stubGlobal("WebSocket", MockWebSocket)
MockWebSocket.instances = []
mockFetch.mockReset()
effectCleanup = null
@@ -209,7 +229,12 @@ function resetMockState() {
effectCounter = 0
latestHookResult = null
mockTrackCommunityWsLifecycleRecovery.mockReset()
+ mockTrackCommunityWsAuthFailure.mockReset()
+ mockTrackCommunityWsLifecycleClose.mockReset()
+ mockTrackCommunityWsLifecycleStage.mockReset()
+ mockTrackCommunityWsRetryScheduled.mockReset()
mockDocument.visibilityState = "visible"
+ mockNavigator.onLine = true
mockDocument.reset()
mockWindow.reset()
}
@@ -490,6 +515,38 @@ describe("useUserWs", () => {
expect(MockWebSocket.instances).toHaveLength(1)
})
+ it("keeps a hidden socketless page suspended when it goes offline", async () => {
+ setupTokenFetch()
+ mockDocument.visibilityState = "hidden"
+ const onConnectionStateChange = vi.fn()
+
+ await mountHook(vi.fn(), {
+ onConnectionStateChange,
+ requestDaemonStatusOnAuth: false,
+ })
+ mockNavigator.onLine = false
+ mockWindow.dispatch("offline")
+
+ expect(onConnectionStateChange).toHaveBeenLastCalledWith("suspended")
+ expect(mockFetch).not.toHaveBeenCalled()
+ expect(MockWebSocket.instances).toEqual([])
+ })
+
+ it("publishes reconnecting without fetching during a visible offline cold start", async () => {
+ setupTokenFetch()
+ mockNavigator.onLine = false
+ const onConnectionStateChange = vi.fn()
+
+ await mountHook(vi.fn(), {
+ onConnectionStateChange,
+ requestDaemonStatusOnAuth: false,
+ })
+
+ expect(onConnectionStateChange).toHaveBeenLastCalledWith("reconnecting")
+ expect(mockFetch).not.toHaveBeenCalled()
+ expect(MockWebSocket.instances).toEqual([])
+ })
+
it("manual reconnect retires the current socket and starts exactly one fresh generation", async () => {
setupTokenFetch()
const onAuthenticated = vi.fn()
@@ -518,6 +575,57 @@ describe("useUserWs", () => {
expect(MockWebSocket.instances).toHaveLength(2)
})
+ it("reports local retirement and remote close exactly once per socket", async () => {
+ setupTokenFetch()
+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })
+ const first = MockWebSocket.instances[0]!
+ first.simulateOpen()
+ first.simulateMessage({ type: "auth.ok" })
+
+ latestHookResult!.reconnectNow()
+ await flushPromises()
+ first.simulateClose(1000, "duplicate local detail", true)
+
+ expect(mockTrackCommunityWsLifecycleClose.mock.calls
+ .filter(([event]) => event.initiator === "manual-retry"))
+ .toHaveLength(1)
+
+ const replacement = MockWebSocket.instances[1]!
+ replacement.simulateOpen()
+ replacement.simulateMessage({ type: "auth.ok" })
+ replacement.simulateClose(1006, "private remote detail", false)
+ replacement.simulateClose(1006, "duplicate private detail", false)
+
+ expect(mockTrackCommunityWsLifecycleClose.mock.calls
+ .filter(([event]) => event.initiator === "remote"))
+ .toHaveLength(1)
+ expect(JSON.stringify(mockTrackCommunityWsLifecycleClose.mock.calls))
+ .not.toContain("private remote detail")
+ })
+
+ it.each([
+ [1001, "going-away"],
+ [1011, "server-error"],
+ [4321, "other"],
+ ] as const)("normalizes remote close code %i to %s", async (code, reasonBucket) => {
+ setupTokenFetch()
+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })
+ const ws = MockWebSocket.instances[0]!
+ ws.simulateOpen()
+ ws.simulateMessage({ type: "auth.ok" })
+
+ ws.simulateClose(code, "private raw reason", false)
+
+ expect(mockTrackCommunityWsLifecycleClose).toHaveBeenCalledWith({
+ initiator: "remote",
+ code,
+ wasClean: false,
+ reasonBucket,
+ })
+ expect(JSON.stringify(mockTrackCommunityWsLifecycleClose.mock.calls))
+ .not.toContain("private raw reason")
+ })
+
it("manual reconnect invalidates an older pending token before it can create a socket", async () => {
const firstTokenResponse = deferred<{
ok: boolean
@@ -611,6 +719,362 @@ describe("useUserWs", () => {
effectCleanup?.()
})
+ it("classifies HTTP auth failures without recording token or close reason content", async () => {
+ mockFetch.mockResolvedValueOnce({ ok: false, status: 403 })
+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })
+
+ expect(mockTrackCommunityWsAuthFailure).toHaveBeenCalledWith({
+ failureClass: "credentials",
+ })
+ expect(mockTrackCommunityWsLifecycleStage).toHaveBeenCalledWith(expect.objectContaining({
+ stage: "token",
+ result: "failure",
+ }))
+
+ mockFetch.mockResolvedValueOnce({ ok: false, status: 503 })
+ latestHookResult!.reconnectNow()
+ await flushPromises()
+ expect(mockTrackCommunityWsAuthFailure).toHaveBeenCalledWith({
+ failureClass: "server",
+ })
+
+ mockFetch.mockResolvedValueOnce({ ok: false, status: 429 })
+ latestHookResult!.reconnectNow()
+ await flushPromises()
+ expect(mockTrackCommunityWsAuthFailure).toHaveBeenCalledWith({
+ failureClass: "unknown",
+ })
+
+ setupTokenFetch()
+ latestHookResult!.reconnectNow()
+ await flushPromises()
+ const ws = MockWebSocket.instances[0]!
+ ws.simulateOpen()
+ ws.simulateClose(1008, "token=private", false)
+
+ expect(mockTrackCommunityWsLifecycleClose).toHaveBeenCalledWith({
+ initiator: "auth-failure",
+ code: 1008,
+ wasClean: false,
+ reasonBucket: "policy",
+ })
+ expect(JSON.stringify(mockTrackCommunityWsLifecycleClose.mock.calls))
+ .not.toContain("token=private")
+ })
+
+ it("rechecks offline state before foreground validation after telemetry", async () => {
+ setupTokenFetch()
+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })
+ const ws = MockWebSocket.instances[0]!
+ ws.simulateOpen()
+ ws.simulateMessage({ type: "auth.ok" })
+ mockTrackCommunityWsLifecycleRecovery.mockImplementationOnce(() => {
+ mockNavigator.onLine = false
+ mockWindow.dispatch("offline")
+ })
+
+ dispatchWindowFocus()
+
+ expect(connectionPings(ws)).toEqual([])
+ expect(ws.closed).toBe(false)
+ })
+
+ it("rechecks offline state after the reconnecting lifecycle callback", async () => {
+ setupTokenFetch()
+ const onConnectionStateChange = vi.fn((phase: string) => {
+ if (phase === "reconnecting") mockNavigator.onLine = false
+ })
+
+ await mountHook(vi.fn(), {
+ onConnectionStateChange,
+ requestDaemonStatusOnAuth: false,
+ })
+
+ expect(onConnectionStateChange).toHaveBeenCalledWith("reconnecting")
+ expect(mockFetch).not.toHaveBeenCalled()
+ expect(MockWebSocket.instances).toEqual([])
+ })
+
+ it("drops a token body that resolves after navigator becomes offline", async () => {
+ const body = deferred<{ userId: string; token: string }>()
+ mockFetch.mockResolvedValue({
+ ok: true,
+ json: () => body.promise,
+ } as Response)
+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })
+ expect(mockFetch).toHaveBeenCalledOnce()
+
+ mockNavigator.onLine = false
+ body.resolve({ userId: "stale-user", token: "stale-token" })
+ await flushPromises()
+
+ expect(MockWebSocket.instances).toEqual([])
+ })
+
+ it("does not run a scheduled retry if navigator becomes offline before it fires", async () => {
+ mockFetch.mockRejectedValueOnce(new Error("network unavailable"))
+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })
+ expect(mockTrackCommunityWsRetryScheduled).toHaveBeenCalledOnce()
+
+ mockNavigator.onLine = false
+ await vi.advanceTimersByTimeAsync(1_000)
+
+ expect(mockFetch).toHaveBeenCalledOnce()
+ expect(MockWebSocket.instances).toEqual([])
+ })
+
+ it("reports WebSocket constructor failures and schedules a retry", async () => {
+ class ThrowingWebSocket {
+ static CONNECTING = 0
+ static OPEN = 1
+ static CLOSING = 2
+ static CLOSED = 3
+ constructor(_url: string) {
+ throw new Error("constructor failed")
+ }
+ }
+ vi.stubGlobal("WebSocket", ThrowingWebSocket)
+ setupTokenFetch()
+
+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })
+
+ expect(mockTrackCommunityWsLifecycleStage).toHaveBeenCalledWith(expect.objectContaining({
+ stage: "open",
+ result: "failure",
+ }))
+ expect(mockTrackCommunityWsRetryScheduled).toHaveBeenCalledOnce()
+ })
+
+ it("closes without authenticating if navigator becomes offline before open", async () => {
+ setupTokenFetch()
+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })
+ const ws = MockWebSocket.instances[0]!
+
+ mockNavigator.onLine = false
+ ws.simulateOpen()
+
+ expect(ws.closed).toBe(true)
+ expect(ws.sent).toEqual([])
+ expect(mockTrackCommunityWsLifecycleClose).toHaveBeenCalledWith(expect.objectContaining({
+ initiator: "offline",
+ }))
+ })
+
+ it("reports an auth transport failure when the auth frame send throws", async () => {
+ setupTokenFetch()
+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })
+ const ws = MockWebSocket.instances[0]!
+ ws.send = vi.fn(() => { throw new Error("auth send failed") })
+
+ ws.simulateOpen()
+
+ expect(ws.closed).toBe(true)
+ expect(mockTrackCommunityWsLifecycleStage).toHaveBeenCalledWith(expect.objectContaining({
+ stage: "auth",
+ result: "failure",
+ }))
+ expect(mockTrackCommunityWsAuthFailure).toHaveBeenCalledWith({
+ failureClass: "network",
+ })
+ expect(mockTrackCommunityWsLifecycleClose).toHaveBeenCalledWith(expect.objectContaining({
+ initiator: "auth-failure",
+ }))
+ })
+
+ it("retires and retries when the post-auth status frame send throws", async () => {
+ setupTokenFetch()
+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: true })
+ const ws = MockWebSocket.instances[0]!
+ const send = ws.send.bind(ws)
+ ws.send = vi.fn((data: string) => {
+ if (data === JSON.stringify({ type: "check_daemon_status" })) {
+ throw new Error("status send failed")
+ }
+ send(data)
+ })
+ ws.simulateOpen()
+
+ ws.simulateMessage({ type: "auth.ok" })
+
+ expect(ws.closed).toBe(true)
+ expect(mockTrackCommunityWsLifecycleClose).toHaveBeenCalledWith(expect.objectContaining({
+ initiator: "local-retire",
+ }))
+ expect(mockTrackCommunityWsRetryScheduled).toHaveBeenCalledOnce()
+ })
+
+ it("uses offline as a hard gate for pending tokens, retries, and manual recovery", async () => {
+ const firstTokenResponse = deferred<Response>()
+ mockFetch
+ .mockReturnValueOnce(firstTokenResponse.promise)
+ .mockResolvedValue({
+ ok: true,
+ json: () => Promise.resolve({ userId: "online-user", token: "online-token" }),
+ })
+
+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })
+ const firstSignal = (mockFetch.mock.calls[0]?.[1] as RequestInit).signal
+
+ mockNavigator.onLine = false
+ mockWindow.dispatch("offline")
+ latestHookResult!.reconnectNow()
+ dispatchWindowFocus()
+ mockDocument.dispatch("resume")
+ await vi.advanceTimersByTimeAsync(60_000)
+
+ expect(firstSignal?.aborted).toBe(true)
+ expect(mockFetch).toHaveBeenCalledOnce()
+ expect(MockWebSocket.instances).toEqual([])
+
+ firstTokenResponse.resolve({
+ ok: true,
+ json: () => Promise.resolve({ userId: "stale-user", token: "stale-token" }),
+ } as Response)
+ await flushPromises()
+ expect(MockWebSocket.instances).toEqual([])
+
+ mockNavigator.onLine = true
+ mockWindow.dispatch("online")
+ mockWindow.dispatch("online")
+ await flushPromises()
+
+ expect(mockFetch).toHaveBeenCalledTimes(2)
+ expect(MockWebSocket.instances).toHaveLength(1)
+ expect(MockWebSocket.instances[0]?.url).toContain("online-user")
+ })
+
+ it("keeps an authenticated socket silent offline and validates it once online", async () => {
+ setupTokenFetch()
+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })
+ const ws = MockWebSocket.instances[0]!
+ ws.simulateOpen()
+ ws.simulateMessage({ type: "auth.ok" })
+ const fetchCount = mockFetch.mock.calls.length
+
+ mockNavigator.onLine = false
+ mockWindow.dispatch("offline")
+ const offlineFrameCount = ws.sent.length
+ latestHookResult!.send({ type: "check_daemon_status" })
+ latestHookResult!.reconnectNow()
+ dispatchWindowFocus()
+ mockDocument.dispatch("resume")
+ dispatchPageShow(true)
+ await vi.advanceTimersByTimeAsync(60_000)
+
+ expect(ws.closed).toBe(false)
+ expect(ws.sent).toHaveLength(offlineFrameCount)
+ expect(mockFetch).toHaveBeenCalledTimes(fetchCount)
+
+ mockNavigator.onLine = true
+ mockWindow.dispatch("online")
+ mockWindow.dispatch("online")
+ dispatchWindowFocus()
+
+ expect(connectionPings(ws)).toHaveLength(1)
+ expect(MockWebSocket.instances).toEqual([ws])
+ expect(mockFetch).toHaveBeenCalledTimes(fetchCount)
+ })
+
+ it("applies offline cleanup after send observes the browser offline before the event", async () => {
+ setupTokenFetch()
+ const onConnectionStateChange = vi.fn()
+ await mountHook(vi.fn(), {
+ onConnectionStateChange,
+ requestDaemonStatusOnAuth: false,
+ })
+ const ws = MockWebSocket.instances[0]!
+ ws.simulateOpen()
+ ws.simulateMessage({ type: "auth.ok" })
+ const authenticatedTimerCount = vi.getTimerCount()
+ const sentCount = ws.sent.length
+
+ mockNavigator.onLine = false
+ latestHookResult!.send({ type: "check_daemon_status" })
+ expect(ws.sent).toHaveLength(sentCount)
+ expect(vi.getTimerCount()).toBe(authenticatedTimerCount)
+
+ mockWindow.dispatch("offline")
+
+ expect(ws.closed).toBe(false)
+ expect(onConnectionStateChange).toHaveBeenLastCalledWith("suspended")
+ expect(vi.getTimerCount()).toBeLessThan(authenticatedTimerCount)
+
+ await vi.advanceTimersByTimeAsync(60_000)
+ expect(ws.sent).toHaveLength(sentCount)
+ })
+
+ it("publishes reconnecting if a retained authenticated socket closes while offline", async () => {
+ setupTokenFetch()
+ const onConnectionStateChange = vi.fn()
+ await mountHook(vi.fn(), {
+ onConnectionStateChange,
+ requestDaemonStatusOnAuth: false,
+ })
+ const ws = MockWebSocket.instances[0]!
+ ws.simulateOpen()
+ ws.simulateMessage({ type: "auth.ok" })
+ const fetchCount = mockFetch.mock.calls.length
+
+ mockNavigator.onLine = false
+ mockWindow.dispatch("offline")
+ expect(onConnectionStateChange).toHaveBeenLastCalledWith("suspended")
+
+ ws.simulateClose(1012, "offline remote close", false)
+ expect(onConnectionStateChange).toHaveBeenLastCalledWith("reconnecting")
+ await vi.advanceTimersByTimeAsync(60_000)
+
+ expect(mockFetch).toHaveBeenCalledTimes(fetchCount)
+ expect(MockWebSocket.instances).toEqual([ws])
+ })
+
+ it("retires an open pre-auth socket offline and ignores every late frame", async () => {
+ setupTokenFetch()
+ const onAuthenticated = vi.fn()
+ await mountHook(vi.fn(), { onAuthenticated, requestDaemonStatusOnAuth: false })
+ const first = MockWebSocket.instances[0]!
+ first.simulateOpen()
+ expect(first.sent).toContain(JSON.stringify({ type: "auth", token: "tok-123" }))
+
+ mockNavigator.onLine = false
+ mockWindow.dispatch("offline")
+ first.simulateMessage({ type: "auth.ok" })
+ first.simulateMessage({ type: "task.updated", taskId: "stale" })
+ await vi.advanceTimersByTimeAsync(60_000)
+
+ expect(first.closed).toBe(true)
+ expect(onAuthenticated).not.toHaveBeenCalled()
+ expect(mockFetch).toHaveBeenCalledOnce()
+
+ mockNavigator.onLine = true
+ mockWindow.dispatch("online")
+ mockWindow.dispatch("online")
+ await flushPromises()
+ expect(mockFetch).toHaveBeenCalledTimes(2)
+ expect(MockWebSocket.instances).toHaveLength(2)
+ })
+
+ it("cancels a scheduled retry offline and starts one replacement online", async () => {
+ mockFetch.mockRejectedValueOnce(new Error("network unavailable"))
+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })
+ expect(mockTrackCommunityWsRetryScheduled).toHaveBeenCalledOnce()
+
+ mockNavigator.onLine = false
+ mockWindow.dispatch("offline")
+ latestHookResult!.reconnectNow()
+ dispatchWindowFocus()
+ await vi.advanceTimersByTimeAsync(60_000)
+ expect(mockFetch).toHaveBeenCalledOnce()
+
+ setupTokenFetch()
+ mockNavigator.onLine = true
+ mockWindow.dispatch("online")
+ mockWindow.dispatch("online")
+ await flushPromises()
+
+ expect(mockFetch).toHaveBeenCalledTimes(2)
+ expect(MockWebSocket.instances).toHaveLength(1)
+ })
+
it("suppresses reconnect while hidden and reconnects immediately when visible", async () => {
setupTokenFetch()
await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })
@@ -738,7 +1202,7 @@ describe("useUserWs", () => {
dispatchWindowFocus()
await flushPromises()
- expect(closing.closed).toBe(true)
+ expect(closing.closed).toBe(false)
expect(MockWebSocket.instances).toHaveLength(3)
expect(mockTrackCommunityWsLifecycleRecovery).toHaveBeenLastCalledWith({
trigger: "focus",
@@ -748,6 +1212,32 @@ describe("useUserWs", () => {
})
})
+ it("preserves a remote initiator when recovery races a remote closing handshake", async () => {
+ setupTokenFetch()
+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })
+ const ws = MockWebSocket.instances[0]!
+ ws.simulateOpen()
+ ws.simulateMessage({ type: "auth.ok" })
+
+ ws.readyState = MockWebSocket.CLOSING
+ dispatchWindowFocus()
+ await flushPromises()
+ expect(mockTrackCommunityWsLifecycleClose).not.toHaveBeenCalled()
+ expect(MockWebSocket.instances).toHaveLength(2)
+
+ ws.simulateClose(1006, "private remote detail", false)
+
+ expect(mockTrackCommunityWsLifecycleClose).toHaveBeenCalledOnce()
+ expect(mockTrackCommunityWsLifecycleClose).toHaveBeenCalledWith({
+ initiator: "remote",
+ code: 1006,
+ wasClean: false,
+ reasonBucket: "abnormal",
+ })
+ expect(JSON.stringify(mockTrackCommunityWsLifecycleClose.mock.calls))
+ .not.toContain("private remote detail")
+ })
+
it("clears a pending reconnect when the page becomes hidden", async () => {
setupTokenFetch()
await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })
@@ -1081,7 +1571,8 @@ describe("useUserWs", () => {
mockWindow.dispatch("offline")
mockWindow.dispatch("online")
- expect(connectionPings(ws)).toHaveLength(1)
+ expect(connectionPings(ws)).toHaveLength(2)
+ expect(connectionPings(ws)[1]?.nonce).not.toBe(connectionPings(ws)[0]?.nonce)
})
it("keeps a cleared foreground validation timer inert", async () => {
@@ -1310,6 +1801,36 @@ describe("useUserWs", () => {
expect(mockFetch).toHaveBeenCalledTimes(2)
})
+ it("recovers once online after validation observes offline before the offline event", async () => {
+ setupTokenFetch()
+ const onConnectionStateChange = vi.fn()
+ const mod = await mountHook(vi.fn(), {
+ onConnectionStateChange,
+ requestDaemonStatusOnAuth: false,
+ })
+ const ws = MockWebSocket.instances[0]!
+ ws.simulateOpen()
+ ws.simulateMessage({ type: "auth.ok" })
+ dispatchWindowFocus()
+ expect(connectionPings(ws)).toHaveLength(1)
+
+ mockNavigator.onLine = false
+ await vi.advanceTimersByTimeAsync(mod.WS_CONNECTION_VALIDATION_TIMEOUT_MS)
+
+ expect(ws.closed).toBe(true)
+ expect(onConnectionStateChange).toHaveBeenLastCalledWith("reconnecting")
+ expect(mockFetch).toHaveBeenCalledOnce()
+
+ setupTokenFetch()
+ mockNavigator.onLine = true
+ mockWindow.dispatch("online")
+ mockWindow.dispatch("online")
+ await flushPromises()
+
+ expect(mockFetch).toHaveBeenCalledTimes(2)
+ expect(MockWebSocket.instances).toHaveLength(2)
+ })
+
it("treats error as non-authoritative and lets current close start one validation failure chain", async () => {
setupTokenFetch()
const onConnectionStateChange = vi.fn()
@@ -1343,6 +1864,44 @@ describe("useUserWs", () => {
expect(mockFetch).toHaveBeenCalledTimes(2)
})
+ it("uses full jitter, preserves the failure window across manual retries, and resets on auth.ok", async () => {
+ const random = vi.spyOn(Math, "random").mockReturnValue(0.5)
+ mockFetch.mockRejectedValue(new Error("network error"))
+ await mountHook(vi.fn(), { requestDaemonStatusOnAuth: false })
+
+ expect(mockTrackCommunityWsAuthFailure).toHaveBeenCalledWith({
+ failureClass: "network",
+ })
+ expect(mockTrackCommunityWsRetryScheduled).toHaveBeenLastCalledWith({
+ attempt: 1,
+ delayMs: 500,
+ windowMs: 1_000,
+ })
+
+ latestHookResult!.reconnectNow()
+ await flushPromises()
+ expect(mockTrackCommunityWsRetryScheduled).toHaveBeenLastCalledWith({
+ attempt: 2,
+ delayMs: 1_000,
+ windowMs: 2_000,
+ })
+
+ setupTokenFetch()
+ latestHookResult!.reconnectNow()
+ await flushPromises()
+ const ws = MockWebSocket.instances[0]!
+ ws.simulateOpen()
+ ws.simulateMessage({ type: "auth.ok" })
+ ws.simulateClose()
+
+ expect(mockTrackCommunityWsRetryScheduled).toHaveBeenLastCalledWith({
+ attempt: 1,
+ delayMs: 500,
+ windowMs: 1_000,
+ })
+ random.mockRestore()
+ })
+
it("failed connect (fetch rejects) retries with backoff and cleanup prevents further reconnects", async () => {
// All connects will fail
mockFetch.mockRejectedValue(new Error("network error"))
@@ -1659,6 +2218,47 @@ describe("useUserWs", () => {
expect(trace).toEqual(["authenticated", "reconnect", "status", "message"])
})
+ it("does not send or start heartbeat after onAuthenticated synchronously reconnects", async () => {
+ setupTokenFetch()
+ let reconnectDuringCallback = true
+ const onAuthenticated = vi.fn(() => {
+ if (!reconnectDuringCallback) return
+ reconnectDuringCallback = false
+ latestHookResult!.reconnectNow()
+ })
+ await mountHook(vi.fn(), { onAuthenticated, requestDaemonStatusOnAuth: true })
+ const first = MockWebSocket.instances[0]!
+ first.simulateOpen()
+ first.simulateMessage({ type: "auth.ok" })
+ await flushPromises()
+
+ expect(first.closed).toBe(true)
+ expect(first.sent).not.toContain(JSON.stringify({ type: "check_daemon_status" }))
+ expect(MockWebSocket.instances).toHaveLength(2)
+ await vi.advanceTimersByTimeAsync(25_000)
+ expect(first.sent).not.toContain("ping")
+ })
+
+ it("does not continue an old auth.ok after onReconnect synchronously replaces it", async () => {
+ setupTokenFetch()
+ const onReconnect = vi.fn(() => latestHookResult!.reconnectNow())
+ await mountHook(vi.fn(), { onReconnect, requestDaemonStatusOnAuth: true })
+ const first = MockWebSocket.instances[0]!
+ first.simulateOpen()
+ first.simulateMessage({ type: "auth.ok" })
+ first.simulateClose()
+ await vi.advanceTimersByTimeAsync(2_000)
+
+ const replacement = MockWebSocket.instances.at(-1)!
+ replacement.simulateOpen()
+ replacement.simulateMessage({ type: "auth.ok" })
+ await flushPromises()
+
+ expect(replacement.closed).toBe(true)
+ expect(replacement.sent).not.toContain(JSON.stringify({ type: "check_daemon_status" }))
+ expect(MockWebSocket.instances).toHaveLength(3)
+ })
+
it("isolates synchronous throws and asynchronous rejections from lifecycle callbacks", async () => {
setupTokenFetch()
const warn = vi.spyOn(console, "warn").mockImplementation(() => {})
diff --git a/src/web/src/lib/use-user-ws.ts b/src/web/src/lib/use-user-ws.ts
index 4156cf118..e18d0bc7d 100644
--- a/src/web/src/lib/use-user-ws.ts
+++ b/src/web/src/lib/use-user-ws.ts
@@ -10,9 +10,17 @@ import {
type WsMessage,
} from "@alook/shared"
import {
+ trackCommunityWsAuthFailure,
trackCommunityWsFrameDropped,
+ trackCommunityWsLifecycleClose,
trackCommunityWsLifecycleRecovery,
+ trackCommunityWsLifecycleStage,
+ trackCommunityWsRetryScheduled,
+ type CommunityWsAuthFailureClass,
+ type CommunityWsCloseInitiator,
+ type CommunityWsCloseReasonBucket,
type CommunityWsFrameDropReason,
+ type CommunityWsLifecycleStageResult,
type CommunityWsLifecycleRecoveryStrategy,
type CommunityWsLifecycleRecoveryTrigger,
type CommunityWsSocketReadyState,
@@ -33,13 +41,50 @@ type PendingConnectionValidation = {
ws: WebSocket
generation: number
nonce: string
+ startedAt: number
timeout: ReturnType<typeof setTimeout>
}
+type PendingTokenAttempt = {
+ controller: AbortController
+ generation: number
+ startedAt: number
+ reported: boolean
+}
+
function isPageHidden(): boolean {
return typeof document !== "undefined" && document.visibilityState === "hidden"
}
+function isBrowserOffline(): boolean {
+ return typeof navigator !== "undefined" && navigator.onLine === false
+}
+
+function boundedDurationMs(startedAt: number): number {
+ return Math.min(Math.max(0, Date.now() - startedAt), 600_000)
+}
+
+function normalizedCloseCode(code: number | undefined): number {
+ if (code === undefined || !Number.isInteger(code) || code < 0 || code > 4999) return 0
+ return code
+}
+
+function closeReasonBucket(code: number): CommunityWsCloseReasonBucket {
+ if (code === 1000) return "normal"
+ if (code === 1001) return "going-away"
+ if (code === 1005 || code === 1006) return "abnormal"
+ if (code === 1008) return "policy"
+ if (code === 1011) return "server-error"
+ if (code === 0) return "unknown"
+ return "other"
+}
+
+function tokenFailureClass(status: number): CommunityWsAuthFailureClass {
+ if (status === 401 || status === 403) return "credentials"
+ if (status >= 500) return "server"
+ return "unknown"
+}
+
function socketReadyState(ws: WebSocket | null): CommunityWsSocketReadyState {
if (!ws) return "none"
switch (ws.readyState) {
@@ -125,6 +170,7 @@ export function useUserWs(
): { send: (msg: object) => void; reconnectNow: () => void } {
const wsRef = useRef<WebSocket | null>(null)
const reconnectDelay = useRef(WS_RECONNECT_INIT)
+ const reconnectAttemptRef = useRef(0)
const onMessageRef = useRef(onMessage)
const onReconnectRef = useRef(options?.onReconnect)
const onDisconnectRef = useRef(options?.onDisconnect)
@@ -133,7 +179,7 @@ export function useUserWs(
const lastConnectionPhaseRef = useRef<UserWsConnectionPhase | null>(null)
const requestDaemonStatusOnAuthRef = useRef(options?.requestDaemonStatusOnAuth ?? true)
const reconnectTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
- const tokenAbortRef = useRef<AbortController | null>(null)
+ const pendingTokenRef = useRef<PendingTokenAttempt | null>(null)
const tokenTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
const connectTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
const connectStartedAtRef = useRef(0)
@@ -150,6 +196,16 @@ export function useUserWs(
const suspendedAtRef = useRef<number | null>(null)
const sentinelIntervalRef = useRef<ReturnType<typeof setInterval> | null>(null)
const lastSentinelTickAtRef = useRef(0)
+ const offlineRef = useRef(isBrowserOffline())
+ const offlineCleanupAppliedRef = useRef(false)
+ const localCloseInitiatorRef = useRef(new WeakMap<WebSocket, CommunityWsCloseInitiator>())
+ const reportedCloseSocketsRef = useRef(new WeakSet<WebSocket>())
+ const isOffline = useCallback(() => {
+ if (offlineRef.current) return true
+ if (!isBrowserOffline()) return false
+ offlineRef.current = true
+ return true
+ }, [])
useEffect(() => {
onMessageRef.current = onMessage
@@ -182,19 +238,89 @@ export function useUserWs(
onConnectionStateChangeRef.current?.(phase))
}, [])
- const clearConnectionValidation = useCallback(() => {
+ const ownsConnection = useCallback((ws: WebSocket, generation: number) => (
+ ws === wsRef.current && generation === connectionGenerationRef.current
+ ), [])
+
+ const ownsAuthenticatedConnection = useCallback((ws: WebSocket, generation: number) => (
+ ownsConnection(ws, generation)
+ && authenticatedGenerationRef.current === generation
+ && ws.readyState === WebSocket.OPEN
+ ), [ownsConnection])
+
+ const clearConnectionValidation = useCallback((
+ result?: CommunityWsLifecycleStageResult,
+ ) => {
const pending = connectionValidationRef.current
connectionValidationRef.current = null
if (pending) clearTimeout(pending.timeout)
+ if (pending && result) {
+ trackCommunityWsLifecycleStage({
+ stage: "validation",
+ result,
+ durationMs: boundedDurationMs(pending.startedAt),
+ })
+ }
+ }, [])
+
+ const reportTokenAttempt = useCallback((
+ attempt: PendingTokenAttempt,
+ result: CommunityWsLifecycleStageResult,
+ ) => {
+ if (attempt.reported) return
+ attempt.reported = true
+ trackCommunityWsLifecycleStage({
+ stage: "token",
+ result,
+ durationMs: boundedDurationMs(attempt.startedAt),
+ })
}, [])
const abortPendingToken = useCallback(() => {
- tokenAbortRef.current?.abort()
- tokenAbortRef.current = null
+ const attempt = pendingTokenRef.current
+ pendingTokenRef.current = null
+ if (attempt) {
+ reportTokenAttempt(attempt, "aborted")
+ attempt.controller.abort()
+ }
if (tokenTimeoutRef.current !== null) {
clearTimeout(tokenTimeoutRef.current)
tokenTimeoutRef.current = null
}
+ }, [reportTokenAttempt])
+
+ const closeSocket = useCallback((ws: WebSocket, initiator: CommunityWsCloseInitiator) => {
+ if (
+ !localCloseInitiatorRef.current.has(ws)
+ && ws.readyState !== WebSocket.CLOSING
+ && ws.readyState !== WebSocket.CLOSED
+ ) {
+ localCloseInitiatorRef.current.set(ws, initiator)
+ }
+ ws.close()
+ }, [])
+
+ const reportSocketClose = useCallback((
+ ws: WebSocket,
+ event?: Pick<CloseEvent, "code" | "wasClean">,
+ ): CommunityWsCloseInitiator => {
+ const localInitiator = localCloseInitiatorRef.current.get(ws)
+ localCloseInitiatorRef.current.delete(ws)
+ const code = normalizedCloseCode(event?.code)
+ const initiator = localInitiator
+ ?? (authenticatedGenerationRef.current === null && code === 1008
+ ? "auth-failure"
+ : "remote")
+ if (!reportedCloseSocketsRef.current.has(ws)) {
+ reportedCloseSocketsRef.current.add(ws)
+ trackCommunityWsLifecycleClose({
+ initiator,
+ code,
+ wasClean: event?.wasClean === true,
+ reasonBucket: closeReasonBucket(code),
+ })
+ }
+ return initiator
}, [])
const stopHeartbeat = useCallback(() => {
@@ -206,25 +332,36 @@ export function useUserWs(
stopHeartbeat()
if (
isPageHidden()
+ || isOffline()
|| frozenRef.current
- || ws !== wsRef.current
- || generation !== connectionGenerationRef.current
- || authenticatedGenerationRef.current !== generation
- || ws.readyState !== WebSocket.OPEN
+ || !ownsAuthenticatedConnection(ws, generation)
) return
lastMessageAtRef.current = Date.now()
pingIntervalRef.current = setInterval(() => {
- if (ws.readyState === WebSocket.OPEN) ws.send("ping")
+ if (
+ !isOffline()
+ && !isPageHidden()
+ && !frozenRef.current
+ && ownsAuthenticatedConnection(ws, generation)
+ ) ws.send("ping")
}, 25_000)
livenessIntervalRef.current = setInterval(() => {
- if (Date.now() - lastMessageAtRef.current > 30_000) ws.close()
+ if (
+ !isOffline()
+ && ownsAuthenticatedConnection(ws, generation)
+ && Date.now() - lastMessageAtRef.current > 30_000
+ ) closeSocket(ws, "heartbeat-timeout")
}, 5_000)
- }, [stopHeartbeat])
+ }, [closeSocket, isOffline, ownsAuthenticatedConnection, stopHeartbeat])
- const retireSocket = useCallback((reportDisconnect = true) => {
+ const retireSocket = useCallback((
+ reportDisconnect: boolean,
+ initiator: CommunityWsCloseInitiator,
+ validationResult: CommunityWsLifecycleStageResult = "aborted",
+ ) => {
const ws = wsRef.current
wsRef.current = null
- clearConnectionValidation()
+ clearConnectionValidation(validationResult)
if (reportDisconnect && authenticatedGenerationRef.current !== null) {
authenticatedGenerationRef.current = null
disconnectedAtRef.current ??= Date.now()
@@ -232,13 +369,14 @@ export function useUserWs(
}
stopHeartbeat()
if (connectTimeoutRef.current !== null) { clearTimeout(connectTimeoutRef.current); connectTimeoutRef.current = null }
- ws?.close()
- }, [clearConnectionValidation, stopHeartbeat])
+ if (ws) closeSocket(ws, initiator)
+ }, [clearConnectionValidation, closeSocket, stopHeartbeat])
const failConnectionValidation = useCallback((
ws: WebSocket,
generation: number,
nonce: string,
+ result: "failure" | "timeout",
) => {
const pending = connectionValidationRef.current
if (
@@ -249,14 +387,23 @@ export function useUserWs(
|| ws !== wsRef.current
|| generation !== connectionGenerationRef.current
) return
- clearConnectionValidation()
- retireSocket()
- const suspended = isPageHidden() || frozenRef.current
- publishConnectionPhase(suspended ? "suspended" : "reconnecting")
- if (!suspended) void connectRef.current?.()
- }, [clearConnectionValidation, publishConnectionPhase, retireSocket])
+ const initiator = result === "timeout" ? "validation-timeout" : "validation-failure"
+ clearConnectionValidation(result)
+ retireSocket(true, initiator, result)
+ if (generation !== connectionGenerationRef.current) return
+ const parked = isPageHidden() || frozenRef.current
+ publishConnectionPhase(parked ? "suspended" : "reconnecting")
+ if (generation !== connectionGenerationRef.current) return
+ if (!parked && !isOffline()) void connectRef.current?.()
+ }, [clearConnectionValidation, isOffline, publishConnectionPhase, retireSocket])
const validateCurrentConnection = useCallback((ws: WebSocket, generation: number) => {
+ if (
+ isOffline()
+ || isPageHidden()
+ || frozenRef.current
+ || !ownsAuthenticatedConnection(ws, generation)
+ ) return
const current = connectionValidationRef.current
if (
current?.ws === ws
@@ -264,104 +411,197 @@ export function useUserWs(
&& ws === wsRef.current
&& generation === connectionGenerationRef.current
) return
- clearConnectionValidation()
+ clearConnectionValidation("aborted")
stopHeartbeat()
const nonce = crypto.randomUUID()
const pending: PendingConnectionValidation = {
ws,
generation,
nonce,
+ startedAt: Date.now(),
timeout: setTimeout(() => {
- failConnectionValidation(ws, generation, nonce)
+ failConnectionValidation(ws, generation, nonce, "timeout")
}, WS_CONNECTION_VALIDATION_TIMEOUT_MS),
}
connectionValidationRef.current = pending
try {
ws.send(JSON.stringify({ type: "connection.ping", nonce }))
} catch {
- failConnectionValidation(ws, generation, nonce)
+ failConnectionValidation(ws, generation, nonce, "failure")
}
- }, [clearConnectionValidation, failConnectionValidation, stopHeartbeat])
+ }, [
+ clearConnectionValidation,
+ failConnectionValidation,
+ isOffline,
+ ownsAuthenticatedConnection,
+ stopHeartbeat,
+ ])
const scheduleReconnect = useCallback((generation: number) => {
if (generation !== connectionGenerationRef.current) return
- if (isPageHidden() || frozenRef.current) return
+ if (isPageHidden() || isOffline() || frozenRef.current) return
if (reconnectTimerRef.current !== null) {
clearTimeout(reconnectTimerRef.current)
reconnectTimerRef.current = null
}
- const delay = Math.min(reconnectDelay.current, WS_RECONNECT_MAX)
- reconnectDelay.current = Math.min(delay * 2, WS_RECONNECT_MAX)
+ const windowMs = Math.min(reconnectDelay.current, WS_RECONNECT_MAX)
+ const delayMs = Math.floor(Math.random() * windowMs)
+ const attempt = reconnectAttemptRef.current + 1
+ reconnectAttemptRef.current = attempt
+ reconnectDelay.current = Math.min(windowMs * 2, WS_RECONNECT_MAX)
+ trackCommunityWsRetryScheduled({ attempt, delayMs, windowMs })
reconnectTimerRef.current = setTimeout(() => {
- if (generation !== connectionGenerationRef.current) return
+ reconnectTimerRef.current = null
+ if (
+ generation !== connectionGenerationRef.current
+ || isPageHidden()
+ || isOffline()
+ || frozenRef.current
+ ) return
void connectRef.current?.()
- }, delay + Math.random() * 500)
- }, [])
+ }, delayMs)
+ }, [isOffline])
const connect = useCallback(async () => {
- if (isPageHidden() || frozenRef.current) {
- publishConnectionPhase("suspended")
+ if (isPageHidden() || isOffline() || frozenRef.current) {
+ publishConnectionPhase(
+ isPageHidden() || frozenRef.current ? "suspended" : "reconnecting",
+ )
return
}
+ if (pendingTokenRef.current) return
+ const previousGeneration = connectionGenerationRef.current
publishConnectionPhase("reconnecting")
- const generation = connectionGenerationRef.current + 1
+ if (
+ pendingTokenRef.current
+ || previousGeneration !== connectionGenerationRef.current
+ || isPageHidden()
+ || isOffline()
+ || frozenRef.current
+ ) return
+ const generation = previousGeneration + 1
connectionGenerationRef.current = generation
if (reconnectTimerRef.current !== null) {
clearTimeout(reconnectTimerRef.current)
reconnectTimerRef.current = null
}
- tokenAbortRef.current?.abort()
const tokenController = new AbortController()
- tokenAbortRef.current = tokenController
+ const tokenAttempt: PendingTokenAttempt = {
+ controller: tokenController,
+ generation,
+ startedAt: Date.now(),
+ reported: false,
+ }
+ pendingTokenRef.current = tokenAttempt
let tokenTimedOut = false
tokenTimeoutRef.current = setTimeout(() => {
+ if (pendingTokenRef.current !== tokenAttempt) return
tokenTimedOut = true
+ pendingTokenRef.current = null
+ tokenTimeoutRef.current = null
+ reportTokenAttempt(tokenAttempt, "timeout")
+ trackCommunityWsAuthFailure({ failureClass: "timeout" })
tokenController.abort()
+ scheduleReconnect(generation)
}, WS_TOKEN_TIMEOUT_MS)
let userId: string
let authToken: string
let wsPort: number = WS_DO_PORT_DEFAULT
+ let tokenResponseReceived = false
try {
const res = await fetch("/api/ws/token", { signal: tokenController.signal })
+ tokenResponseReceived = true
+ if (
+ pendingTokenRef.current !== tokenAttempt
+ || generation !== connectionGenerationRef.current
+ || isOffline()
+ ) return
if (!res.ok) {
- if (generation !== connectionGenerationRef.current) return
+ reportTokenAttempt(tokenAttempt, "failure")
+ trackCommunityWsAuthFailure({ failureClass: tokenFailureClass(res.status) })
console.warn("[ws] token fetch failed:", res.status)
scheduleReconnect(generation)
return
}
const body = await res.json() as { userId: string; token: string; wsPort?: number }
- if (generation !== connectionGenerationRef.current) return
+ if (
+ pendingTokenRef.current !== tokenAttempt
+ || generation !== connectionGenerationRef.current
+ || isOffline()
+ ) return
+ reportTokenAttempt(tokenAttempt, "success")
userId = body.userId
authToken = body.token
if (body.wsPort) wsPort = body.wsPort
} catch (err) {
- if (generation !== connectionGenerationRef.current) return
- if (tokenController.signal.aborted && !tokenTimedOut) return
+ if (
+ pendingTokenRef.current !== tokenAttempt
+ || generation !== connectionGenerationRef.current
+ || isOffline()
+ ) return
+ if (tokenController.signal.aborted || tokenTimedOut) return
+ reportTokenAttempt(tokenAttempt, "failure")
+ trackCommunityWsAuthFailure({
+ failureClass: tokenResponseReceived ? "unknown" : "network",
+ })
console.warn("[ws] token fetch error:", err)
scheduleReconnect(generation)
return
} finally {
- if (tokenAbortRef.current === tokenController) {
+ if (pendingTokenRef.current === tokenAttempt) {
if (tokenTimeoutRef.current !== null) {
clearTimeout(tokenTimeoutRef.current)
tokenTimeoutRef.current = null
}
- tokenAbortRef.current = null
+ pendingTokenRef.current = null
}
}
+ if (generation !== connectionGenerationRef.current || isOffline()) return
+
const wsBaseUrl = useLocalServices
? websocketUrl("user", { local: true, port: wsPort })
: websocketUrl("user", { local: false, origin: location.origin })
const url = `${wsBaseUrl}?userId=${userId}`
+ const socketStartedAt = Date.now()
+ let openedAt = 0
+ let openStageReported = false
+ let authStageReported = false
+ let authFailureReported = false
+ const reportOpenStage = (result: CommunityWsLifecycleStageResult) => {
+ if (openStageReported) return
+ openStageReported = true
+ trackCommunityWsLifecycleStage({
+ stage: "open",
+ result,
+ durationMs: boundedDurationMs(socketStartedAt),
+ })
+ }
+ const reportAuthStage = (result: CommunityWsLifecycleStageResult) => {
+ if (authStageReported || openedAt === 0) return
+ authStageReported = true
+ trackCommunityWsLifecycleStage({
+ stage: "auth",
+ result,
+ durationMs: boundedDurationMs(openedAt),
+ })
+ }
+ const reportAuthFailure = (failureClass: CommunityWsAuthFailureClass) => {
+ if (authFailureReported) return
+ authFailureReported = true
+ trackCommunityWsAuthFailure({ failureClass })
+ }
+
let ws: WebSocket
try {
- if (generation !== connectionGenerationRef.current) return
- retireSocket()
+ if (generation !== connectionGenerationRef.current || isOffline()) return
+ retireSocket(true, "local-retire")
+ if (generation !== connectionGenerationRef.current || isOffline()) return
ws = new WebSocket(url)
} catch (err) {
if (generation !== connectionGenerationRef.current) return
+ reportOpenStage("failure")
console.warn("[ws] WebSocket creation failed:", err)
scheduleReconnect(generation)
return
@@ -369,18 +609,35 @@ export function useUserWs(
wsRef.current = ws
connectStartedAtRef.current = Date.now()
connectTimeoutRef.current = setTimeout(() => {
- if (ws !== wsRef.current || generation !== connectionGenerationRef.current) return
- ws.close()
+ if (!ownsConnection(ws, generation)) return
+ if (openedAt === 0) {
+ reportOpenStage("timeout")
+ } else {
+ reportAuthStage("timeout")
+ reportAuthFailure("timeout")
+ }
+ closeSocket(ws, "connect-timeout")
}, WS_CONNECTION_VALIDATION_TIMEOUT_MS)
ws.onopen = () => {
- if (ws !== wsRef.current || generation !== connectionGenerationRef.current) return
- reconnectDelay.current = WS_RECONNECT_INIT
- ws.send(JSON.stringify({ type: "auth", token: authToken }))
+ if (!ownsConnection(ws, generation)) return
+ if (isOffline()) {
+ closeSocket(ws, "offline")
+ return
+ }
+ openedAt = Date.now()
+ reportOpenStage("success")
+ try {
+ ws.send(JSON.stringify({ type: "auth", token: authToken }))
+ } catch {
+ reportAuthStage("failure")
+ reportAuthFailure("network")
+ closeSocket(ws, "auth-failure")
+ }
}
ws.onmessage = (e) => {
- if (ws !== wsRef.current || generation !== connectionGenerationRef.current) return
+ if (!ownsConnection(ws, generation) || isOffline()) return
lastMessageAtRef.current = Date.now()
if (typeof e.data !== "string") {
reportDroppedFrame("invalid-json")
@@ -412,8 +669,12 @@ export function useUserWs(
&& pending.nonce === msg.nonce
&& authenticatedGenerationRef.current === generation
) {
- clearConnectionValidation()
+ clearConnectionValidation("success")
publishConnectionPhase("authenticated")
+ if (
+ isOffline()
+ || !ownsAuthenticatedConnection(ws, generation)
+ ) return
startHeartbeat(ws, generation)
}
return
@@ -423,6 +684,7 @@ export function useUserWs(
reportDroppedFrame("duplicate-auth-ok", msg)
return
}
+ reportAuthStage("success")
authenticatedGenerationRef.current = generation
if (connectTimeoutRef.current !== null) {
clearTimeout(connectTimeoutRef.current)
@@ -435,14 +697,28 @@ export function useUserWs(
: Math.max(0, Date.now() - disconnectedAtRef.current)
disconnectedAtRef.current = null
publishConnectionPhase("authenticated")
+ if (!ownsAuthenticatedConnection(ws, generation) || isOffline()) return
runLifecycleCallback("authenticated", onAuthenticatedRef.current)
+ if (!ownsAuthenticatedConnection(ws, generation) || isOffline()) return
if (isReconnect) {
runLifecycleCallback("reconnect", () =>
onReconnectRef.current?.({ reconnectDurationMs }))
+ if (!ownsAuthenticatedConnection(ws, generation) || isOffline()) return
}
+ reconnectDelay.current = WS_RECONNECT_INIT
+ reconnectAttemptRef.current = 0
if (requestDaemonStatusOnAuthRef.current) {
- ws.send(JSON.stringify({ type: "check_daemon_status" }))
+ try {
+ ws.send(JSON.stringify({ type: "check_daemon_status" }))
+ } catch {
+ retireSocket(true, "local-retire")
+ if (generation === connectionGenerationRef.current) {
+ scheduleReconnect(generation)
+ }
+ return
+ }
}
+ if (!ownsAuthenticatedConnection(ws, generation) || isOffline()) return
startHeartbeat(ws, generation)
return
}
@@ -472,28 +748,67 @@ export function useUserWs(
ws.onerror = () => {}
- ws.onclose = () => {
- if (ws !== wsRef.current) return
+ ws.onclose = (event) => {
+ const initiator = reportSocketClose(ws, event)
+ const timeout = initiator === "connect-timeout"
+ const aborted = initiator === "freeze"
+ || initiator === "local-retire"
+ || initiator === "manual-retry"
+ || initiator === "offline"
+ if (!openStageReported) reportOpenStage(timeout ? "timeout" : aborted ? "aborted" : "failure")
+ if (openedAt !== 0 && !authStageReported) {
+ reportAuthStage(timeout ? "timeout" : aborted ? "aborted" : "failure")
+ if (initiator === "auth-failure") {
+ const code = normalizedCloseCode(event?.code)
+ reportAuthFailure(code === 1008 ? "credentials" : "network")
+ } else if (initiator === "remote") {
+ const code = normalizedCloseCode(event?.code)
+ reportAuthFailure(code === 1008 ? "credentials" : code === 1011 ? "server" : "network")
+ }
+ }
+ if (!ownsConnection(ws, generation)) return
const validation = connectionValidationRef.current
- if (
+ const failedValidation = Boolean(
validation?.ws === ws
&& validation.generation === generation
- ) {
- failConnectionValidation(ws, generation, validation.nonce)
- return
+ )
+ if (failedValidation) {
+ clearConnectionValidation("failure")
}
const wasAuthenticated = authenticatedGenerationRef.current === generation
+ wsRef.current = null
if (wasAuthenticated) {
authenticatedGenerationRef.current = null
disconnectedAtRef.current ??= Date.now()
runLifecycleCallback("disconnect", onDisconnectRef.current)
+ if (generation !== connectionGenerationRef.current) return
}
stopHeartbeat()
if (connectTimeoutRef.current !== null) { clearTimeout(connectTimeoutRef.current); connectTimeoutRef.current = null }
- publishConnectionPhase(isPageHidden() || frozenRef.current ? "suspended" : "reconnecting")
- scheduleReconnect(generation)
+ publishConnectionPhase(
+ isPageHidden() || frozenRef.current ? "suspended" : "reconnecting",
+ )
+ if (generation !== connectionGenerationRef.current) return
+ if (failedValidation && !isPageHidden() && !isOffline() && !frozenRef.current) {
+ void connectRef.current?.()
+ } else {
+ scheduleReconnect(generation)
+ }
}
- }, [clearConnectionValidation, failConnectionValidation, publishConnectionPhase, retireSocket, scheduleReconnect, startHeartbeat, stopHeartbeat])
+ }, [
+ clearConnectionValidation,
+ closeSocket,
+ isOffline,
+ ownsAuthenticatedConnection,
+ ownsConnection,
+ publishConnectionPhase,
+ reportSocketClose,
+ reportTokenAttempt,
+ retireSocket,
+ scheduleReconnect,
+ startHeartbeat,
+ stopHeartbeat,
+ ])
useEffect(() => {
connectRef.current = connect
@@ -502,7 +817,7 @@ export function useUserWs(
const suspendConnection = useCallback((retireAuthenticatedSocket: boolean) => {
connectionValidationNeededRef.current = true
suspendedAtRef.current ??= Date.now()
- clearConnectionValidation()
+ clearConnectionValidation("aborted")
stopHeartbeat()
publishConnectionPhase("suspended")
if (reconnectTimerRef.current !== null) {
@@ -511,21 +826,59 @@ export function useUserWs(
}
const generation = connectionGenerationRef.current
+ const ws = wsRef.current
const authenticated = authenticatedGenerationRef.current === generation
- if (!retireAuthenticatedSocket && authenticated) return
+ if (!retireAuthenticatedSocket && authenticated && ws?.readyState === WebSocket.OPEN) return
connectionGenerationRef.current += 1
abortPendingToken()
- retireSocket(retireAuthenticatedSocket)
+ retireSocket(
+ retireAuthenticatedSocket,
+ retireAuthenticatedSocket ? "freeze" : "local-retire",
+ )
}, [abortPendingToken, clearConnectionValidation, publishConnectionPhase, retireSocket, stopHeartbeat])
+ const suspendForOffline = useCallback(() => {
+ offlineRef.current = true
+ if (offlineCleanupAppliedRef.current) return
+ offlineCleanupAppliedRef.current = true
+ connectionValidationNeededRef.current = true
+ suspendedAtRef.current ??= Date.now()
+ clearConnectionValidation("aborted")
+ stopHeartbeat()
+ if (reconnectTimerRef.current !== null) {
+ clearTimeout(reconnectTimerRef.current)
+ reconnectTimerRef.current = null
+ }
+ abortPendingToken()
+
+ const ws = wsRef.current
+ const generation = connectionGenerationRef.current
+ const retainAuthenticatedSocket = ws
+ ? ownsAuthenticatedConnection(ws, generation)
+ : false
+ if (!retainAuthenticatedSocket) {
+ connectionGenerationRef.current += 1
+ retireSocket(true, "offline")
+ }
+ const parked = retainAuthenticatedSocket || isPageHidden() || frozenRef.current
+ publishConnectionPhase(parked ? "suspended" : "reconnecting")
+ }, [
+ abortPendingToken,
+ clearConnectionValidation,
+ ownsAuthenticatedConnection,
+ publishConnectionPhase,
+ retireSocket,
+ stopHeartbeat,
+ ])
+
const trackLifecycleRecovery = useCallback((
trigger: CommunityWsLifecycleRecoveryTrigger,
strategy: CommunityWsLifecycleRecoveryStrategy,
readyState: CommunityWsSocketReadyState,
now: number,
) => {
- if (isPageHidden() || frozenRef.current) return
+ if (isPageHidden() || isOffline() || frozenRef.current) return
trackCommunityWsLifecycleRecovery({
trigger,
strategy,
@@ -533,12 +886,21 @@ export function useUserWs(
suspensionDuration: suspensionDurationBucket(suspendedAtRef.current, now),
})
suspendedAtRef.current = null
- }, [])
+ }, [isOffline])
const requestForegroundRecovery = useCallback((
trigger: CommunityWsLifecycleRecoveryTrigger,
forceValidation: boolean,
) => {
+ if (isOffline()) {
+ connectionValidationNeededRef.current = true
+ const ws = wsRef.current
+ const generation = connectionGenerationRef.current
+ if (!ws || !ownsAuthenticatedConnection(ws, generation)) {
+ publishConnectionPhase("reconnecting")
+ }
+ return
+ }
if (isPageHidden()) {
suspendConnection(false)
return
@@ -548,8 +910,7 @@ export function useUserWs(
const recoveryNeeded = forceValidation || connectionValidationNeededRef.current
if (!recoveryNeeded) return
- reconnectDelay.current = WS_RECONNECT_INIT
- if (tokenAbortRef.current) return
+ if (pendingTokenRef.current) return
const ws = wsRef.current
const generation = connectionGenerationRef.current
@@ -575,14 +936,23 @@ export function useUserWs(
reconnectTimerRef.current = null
}
const readyState = socketReadyState(ws)
- retireSocket()
+ retireSocket(true, "local-retire")
+ if (generation !== connectionGenerationRef.current || isOffline()) return
trackLifecycleRecovery(trigger, "replace", readyState, Date.now())
void connectRef.current?.()
- }, [retireSocket, suspendConnection, trackLifecycleRecovery, validateCurrentConnection])
+ }, [
+ isOffline,
+ ownsAuthenticatedConnection,
+ publishConnectionPhase,
+ retireSocket,
+ suspendConnection,
+ trackLifecycleRecovery,
+ validateCurrentConnection,
+ ])
useEffect(() => {
const mountedAt = Date.now()
- if (isPageHidden()) suspendedAtRef.current = mountedAt
+ if (isPageHidden() || isOffline()) suspendedAtRef.current = mountedAt
lastSentinelTickAtRef.current = mountedAt
void connect()
const onVisibilityChange = () => {
@@ -604,8 +974,14 @@ export function useUserWs(
if (event.target !== window) return
requestForegroundRecovery("focus", true)
}
- const onOnline = () => requestForegroundRecovery("online", false)
- const onOffline = () => { connectionValidationNeededRef.current = true }
+ const onOnline = () => {
+ if (!offlineRef.current) return
+ offlineRef.current = false
+ offlineCleanupAppliedRef.current = false
+ connectionValidationNeededRef.current = true
+ requestForegroundRecovery("online", true)
+ }
+ const onOffline = () => suspendForOffline()
if (typeof document !== "undefined") {
document.addEventListener("visibilitychange", onVisibilityChange)
document.addEventListener("freeze", onFreeze)
@@ -623,6 +999,7 @@ export function useUserWs(
lastSentinelTickAtRef.current = now
if (
isPageHidden()
+ || isOffline()
|| elapsedMs < WS_FOREGROUND_SUSPENSION_GAP_MS
) return
requestForegroundRecovery("sentinel", true)
@@ -644,7 +1021,7 @@ export function useUserWs(
sentinelIntervalRef.current = null
}
connectionGenerationRef.current += 1
- clearConnectionValidation()
+ clearConnectionValidation("aborted")
abortPendingToken()
if (reconnectTimerRef.current !== null) {
clearTimeout(reconnectTimerRef.current)
@@ -652,41 +1029,60 @@ export function useUserWs(
}
if (connectTimeoutRef.current !== null) { clearTimeout(connectTimeoutRef.current); connectTimeoutRef.current = null }
stopHeartbeat()
- retireSocket(false)
+ retireSocket(false, "local-retire")
}
}, [
abortPendingToken,
clearConnectionValidation,
connect,
+ isOffline,
requestForegroundRecovery,
retireSocket,
stopHeartbeat,
suspendConnection,
+ suspendForOffline,
])
const send = useCallback((msg: object) => {
const ws = wsRef.current
- if (ws && ws.readyState === WebSocket.OPEN) {
+ if (!isOffline() && ws?.readyState === WebSocket.OPEN) {
ws.send(JSON.stringify(msg))
}
- }, [])
+ }, [isOffline])
const reconnectNow = useCallback(() => {
- clearConnectionValidation()
+ clearConnectionValidation("aborted")
if (reconnectTimerRef.current !== null) {
clearTimeout(reconnectTimerRef.current)
reconnectTimerRef.current = null
}
abortPendingToken()
- reconnectDelay.current = WS_RECONNECT_INIT
- retireSocket()
+ if (isOffline()) {
+ connectionValidationNeededRef.current = true
+ stopHeartbeat()
+ const ws = wsRef.current
+ const generation = connectionGenerationRef.current
+ publishConnectionPhase(
+ ws && ownsAuthenticatedConnection(ws, generation) ? "suspended" : "reconnecting",
+ )
+ return
+ }
+ retireSocket(true, "manual-retry")
if (isPageHidden() || frozenRef.current) {
connectionGenerationRef.current += 1
publishConnectionPhase("suspended")
return
}
void connectRef.current?.()
- }, [abortPendingToken, clearConnectionValidation, publishConnectionPhase, retireSocket])
+ }, [
+ abortPendingToken,
+ clearConnectionValidation,
+ isOffline,
+ ownsAuthenticatedConnection,
+ publishConnectionPhase,
+ retireSocket,
+ stopHeartbeat,
+ ])
return { send, reconnectNow }
}
diff --git a/src/web/src/test/e2e/ws.test.ts b/src/web/src/test/e2e/ws.test.ts
index 29b3a430a..8640f97fe 100644
--- a/src/web/src/test/e2e/ws.test.ts
+++ b/src/web/src/test/e2e/ws.test.ts
@@ -117,6 +117,24 @@ describe("ws (dev direct to ws-do)", () => {
ws.close()
})
+ it("echoes the exact authenticated connection-validation nonce", async () => {
+ if (!available) return
+
+ const ws = await openWs(userId)
+ ws.send(JSON.stringify({ type: "auth", token }))
+ await waitForMessage<{ type: string }>(ws, (message) => message.type === "auth.ok")
+
+ const nonce = randomUUID()
+ const pong = waitForMessage<{ type: string; nonce?: string }>(
+ ws,
+ (message) => message.type === "connection.pong",
+ )
+ ws.send(JSON.stringify({ type: "connection.ping", nonce }))
+
+ await expect(pong).resolves.toEqual({ type: "connection.pong", nonce })
+ ws.close()
+ })
+
it("closes with 1008 on invalid token", async () => {
if (!available) return