Enterprise agent platform for building, deploying, and operating AI teammates.
import { readFileSync } from "node:fs"
import { resolve } from "node:path"
import { StrictMode, useLayoutEffect } from "react"
import { act, cleanup, renderHook, waitFor } from "@testing-library/react"
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
import {
DEAD_AFTER_MS,
MessageDeliveryError,
RECONNECT_BASE_DELAY_MS,
RECONNECT_CLOSE_REASON,
RECONNECT_MAX_DELAY_MS,
classifyClose,
reconnectDelayMs,
type ConnectionPhaseFacts,
type WebSocketConnection,
deriveConnectionPhase,
resolveReportedTimezone,
useWebSocket,
} from "./use-websocket"
import { refreshStoredAccessToken } from "@/lib/api-wrapper"
import { AUTH_CACHE_KEY, readAuthCache, readAuthSessionSnapshot, type AuthSessionSnapshot } from "@/lib/auth-cache"
const authState = vi.hoisted(() => ({
user: { id: "user-1" } as { id: string } | null,
token: "token" as string | null,
refreshToken: "refresh-token" as string | null,
session: {
sessionId: "test-lineage",
credentialRevision: 0,
profileRevision: 0,
userId: "user-1",
accessToken: "token",
refreshToken: "refresh-token",
profileFingerprint: '[null,null,null]',
} as AuthSessionSnapshot,
refreshAccessToken: vi.fn<(expectedSession?: AuthSessionSnapshot) => Promise<boolean>>(),
}))
vi.mock("@/contexts/auth-context", () => ({
useAuth: () => authState,
}))
class MockWebSocket {
static OPEN = 1
static CLOSING = 2
static CLOSED = 3
static instances: MockWebSocket[] = []
static constructorError: Error | null = null
readyState = 0
protocol = ""
onopen: (() => void) | null = null
onclose: ((event: CloseEvent) => void) | null = null
onerror: ((event: Event) => void) | null = null
onmessage: ((event: MessageEvent) => void) | null = null
send = vi.fn()
close = vi.fn(() => {
this.readyState = MockWebSocket.CLOSED
})
constructor(
public url: string,
public protocols?: string | string[],
) {
if (MockWebSocket.constructorError) throw MockWebSocket.constructorError
MockWebSocket.instances.push(this)
}
open() {
this.readyState = MockWebSocket.OPEN
this.onopen?.()
}
receive(payload: unknown) {
this.onmessage?.({ data: JSON.stringify(payload) } as MessageEvent)
}
triggerError() {
this.onerror?.(new Event("error"))
}
triggerClose(code = 1006, reason = "network lost") {
this.readyState = MockWebSocket.CLOSED
this.onclose?.({ code, reason } as CloseEvent)
}
}
const sessionConnections = new Map<string, WebSocketConnection>()
const sessionConnection = (
overrides: Partial<WebSocketConnection> = {},
): WebSocketConnection => {
const key = JSON.stringify(overrides)
const existing = sessionConnections.get(key)
if (existing) return existing
const connection: WebSocketConnection = {
identity: "widget-session:1",
url: "wss://embed.example/v1/external/chat/sessions/ws",
protocols: ["xagent-session-v1", "xagent-session-token.st_secret"],
expectedProtocol: "xagent-session-v1",
chatTaskIdMode: "omit",
credentialOwner: { kind: "external" },
...overrides,
}
sessionConnections.set(key, connection)
return connection
}
const deferred = <T,>() => {
let resolve!: (value: T) => void
let reject!: (reason?: unknown) => void
const promise = new Promise<T>((resolvePromise, rejectPromise) => {
resolve = resolvePromise
reject = rejectPromise
})
return { promise, reject, resolve }
}
function writeAuthCache(
user: { id: string; username: string; email?: string | null; is_admin?: boolean } | null,
token: string | null,
refreshToken: string | null = null,
expiresIn?: number,
refreshExpiresIn?: number,
) {
if (!user || !token) {
localStorage.removeItem(AUTH_CACHE_KEY)
return
}
const now = Date.now()
localStorage.setItem(AUTH_CACHE_KEY, JSON.stringify({
schemaVersion: 2, sessionId: `test-${Math.random()}`, credentialRevision: 0, profileRevision: 0,
user, token, refreshToken, timestamp: now,
expiresAt: expiresIn ? now + expiresIn * 1000 : undefined,
refreshExpiresAt: refreshExpiresIn ? now + refreshExpiresIn * 1000 : undefined,
}))
}
// Hooks left mounted keep their real reconnect timers and would open sockets
// into a later test's MockWebSocket.instances.
afterEach(() => cleanup())
describe("useWebSocket message delivery", () => {
it("reports malformed explicit credentials without throwing during render or retrying", async () => {
const onConnectionFailure = vi.fn()
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost", taskId: 1, token: "invalid+/=credential",
onConnectionFailure,
}))
await waitFor(() => expect(result.current.connectionError).toBeInstanceOf(Error))
expect(MockWebSocket.instances).toHaveLength(0)
expect(onConnectionFailure).toHaveBeenCalledWith(expect.objectContaining({ recoverable: false }))
expect(String(result.current.connectionError)).not.toContain("invalid+/=")
})
beforeEach(() => {
MockWebSocket.instances = []
MockWebSocket.constructorError = null
sessionConnections.clear()
localStorage.clear()
authState.user = { id: "user-1" }
authState.token = "token"
authState.refreshToken = "refresh-token"
authState.session = {
sessionId: "test-lineage",
credentialRevision: 0,
profileRevision: 0,
userId: "user-1",
accessToken: "token",
refreshToken: "refresh-token",
profileFingerprint: '[null,null,null]',
}
authState.refreshAccessToken.mockReset()
vi.stubGlobal("WebSocket", MockWebSocket)
})
afterEach(() => {
vi.restoreAllMocks()
vi.unstubAllGlobals()
})
it("rejects without clearing the caller when the socket is not open", async () => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
autoConnect: false,
}))
await expect(result.current.sendChatMessage("keep this draft")).rejects.toMatchObject({
message: "Message not sent: the connection is not ready.",
disposition: "not_sent",
errorCode: "connection_not_ready",
})
})
it("returns not_sent when no current open socket owns a raw protocol write", async () => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
autoConnect: false,
}))
expect(result.current.sendMessage({ type: "new_conversation" })).toBe("not_sent")
})
it("returns not_sent when a socket closes between the open check and raw write", async () => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
socket.send.mockImplementationOnce(() => {
socket.readyState = MockWebSocket.CLOSED
throw new Error("socket closed during write")
})
expect(result.current.sendMessage({ type: "new_conversation" })).toBe("not_sent")
})
it("resolves only after the server accepts the durable message", async () => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
let delivery!: Promise<{ client_message_id: string; turn_id: string }>
act(() => {
delivery = result.current.sendChatMessage("durable guidance")
})
expect(socket.send).toHaveBeenCalledOnce()
const sent = JSON.parse(socket.send.mock.calls[0][0])
expect(sent.client_message_id).toBeTruthy()
let settled = false
void delivery.finally(() => {
settled = true
})
await Promise.resolve()
expect(settled).toBe(false)
act(() => {
socket.receive({
type: "message_accepted",
client_message_id: sent.client_message_id,
turn_id: sent.client_message_id,
})
})
await expect(delivery).resolves.toEqual({
client_message_id: sent.client_message_id,
turn_id: sent.client_message_id,
})
})
it("serializes the interaction request id with the caller's delivery id", async () => {
const { result } = renderHook(() => useWebSocket({
connection: sessionConnection(),
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
socket.protocol = "xagent-session-v1"
act(() => socket.open())
let delivery!: Promise<{ client_message_id: string; turn_id: string }>
act(() => {
delivery = result.current.sendChatMessage(
"City: Sydney",
undefined,
true,
"answer-q1",
"inputreq_0011223344556677889900aabbccddee",
)
})
expect(JSON.parse(socket.send.mock.calls[0][0])).toMatchObject({
type: "chat",
message: "City: Sydney",
client_message_id: "answer-q1",
request_id: "inputreq_0011223344556677889900aabbccddee",
})
act(() => socket.receive({
type: "message_accepted",
client_message_id: "answer-q1",
turn_id: "answer-q1",
}))
await expect(delivery).resolves.toEqual({
client_message_id: "answer-q1",
turn_id: "answer-q1",
})
})
it("assigns idempotency keys to pause and resume commands", async () => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
act(() => {
result.current.pauseTask()
result.current.resumeTask()
})
const pause = JSON.parse(socket.send.mock.calls[0][0])
const resume = JSON.parse(socket.send.mock.calls[1][0])
expect(pause.command_id).toBeTruthy()
expect(resume.command_id).toBeTruthy()
expect(resume.command_id).not.toBe(pause.command_id)
})
it.each(["input_review_blocked", "input_review_unavailable"])(
"surfaces %s after a durable send acknowledgement",
async (errorCode) => {
const onMessage = vi.fn()
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
onMessage,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const delivery = result.current.sendChatMessage("Draft", undefined, false, "reviewed-turn")
act(() => socket.receive({
type: "message_accepted", client_message_id: "reviewed-turn", turn_id: "reviewed-turn",
}))
await expect(delivery).resolves.toMatchObject({ turn_id: "reviewed-turn" })
act(() => socket.receive({
type: "message_rejected",
client_message_id: "reviewed-turn",
turn_id: "reviewed-turn",
rejection_outcome: "not_accepted",
error_code: errorCode,
retry_with_new_id: errorCode === "input_review_unavailable",
}))
expect(onMessage).toHaveBeenCalledWith(expect.objectContaining({
type: "error",
data: expect.objectContaining({ error_code: errorCode, turn_id: "reviewed-turn" }),
}))
},
)
it("allows an unacknowledged draft to retry with the same id", async () => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
legacyErrorProse: "trusted",
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const first = result.current.sendChatMessage(
"retry me",
undefined,
false,
"stable-turn-1",
)
act(() => {
socket.receive({
type: "message_rejected",
client_message_id: "stable-turn-1",
message: "temporary failure",
rejection_outcome: "not_accepted",
})
})
await expect(first).rejects.toMatchObject({
message: "temporary failure",
disposition: "rejected",
})
const retry = result.current.sendChatMessage(
"retry me",
undefined,
false,
"stable-turn-1",
)
expect(socket.send).toHaveBeenCalledTimes(2)
act(() => {
socket.receive({
type: "message_accepted",
client_message_id: "stable-turn-1",
turn_id: "stable-turn-1",
})
})
await expect(retry).resolves.toEqual({
client_message_id: "stable-turn-1",
turn_id: "stable-turn-1",
})
})
it("marks a coded backend rejection as localizable and user facing", async () => {
// The clarification form only shows a rejection reason that is marked
// user facing; if this flag regresses, the visitor drops back to the
// generic "Failed to send response" toast.
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const delivery = result.current.sendChatMessage(
"answer",
undefined,
false,
"rejected-with-reason",
)
act(() => {
socket.receive({
type: "message_rejected",
client_message_id: "rejected-with-reason",
error_code: "guidance_in_progress",
message: "A previous guidance message is still being applied. Please wait for it to finish.",
rejection_outcome: "not_accepted",
})
})
await expect(delivery).rejects.toMatchObject({
message: "A previous guidance message is still being applied. Please wait for it to finish.",
disposition: "rejected",
userFacing: true,
errorCode: "guidance_in_progress",
})
})
it("preserves absent-code rejection prose for a trusted legacy transport", async () => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
legacyErrorProse: "trusted",
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const delivery = result.current.sendChatMessage(
"answer",
undefined,
false,
"trusted-legacy-rejection",
)
act(() => {
socket.receive({
type: "message_rejected",
client_message_id: "trusted-legacy-rejection",
message: "Legacy actionable authenticated rejection",
rejection_outcome: "not_accepted",
})
})
await expect(delivery).rejects.toMatchObject({
message: "Legacy actionable authenticated rejection",
disposition: "rejected",
userFacing: true,
errorCode: null,
})
})
it("hides absent-code rejection prose for an untrusted legacy transport", async () => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
legacyErrorProse: "untrusted",
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const delivery = result.current.sendChatMessage(
"answer",
undefined,
false,
"untrusted-legacy-rejection",
)
act(() => {
socket.receive({
type: "message_rejected",
client_message_id: "untrusted-legacy-rejection",
message: "provider token=secret",
rejection_outcome: "not_accepted",
})
})
await expect(delivery).rejects.toMatchObject({
message: "Message was rejected.",
disposition: "rejected",
userFacing: false,
errorCode: "message_not_accepted",
})
})
it("keeps a rejection without a backend reason marked as not user facing", async () => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const delivery = result.current.sendChatMessage(
"answer",
undefined,
false,
"rejected-no-reason",
)
act(() => {
socket.receive({
type: "message_rejected",
client_message_id: "rejected-no-reason",
rejection_outcome: "not_accepted",
})
})
await expect(delivery).rejects.toMatchObject({
message: "Message was rejected.",
disposition: "rejected",
userFacing: false,
errorCode: "message_not_accepted",
})
})
it("does not trust a rejection carrying an unknown error code", async () => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
legacyErrorProse: "trusted",
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const delivery = result.current.sendChatMessage(
"answer",
undefined,
false,
"rejected-unknown-code",
)
act(() => {
socket.receive({
type: "message_rejected",
client_message_id: "rejected-unknown-code",
error_code: "provider_secret",
message: "token=secret",
rejection_outcome: "not_accepted",
})
})
await expect(delivery).rejects.toMatchObject({
message: "Message was rejected.",
disposition: "rejected",
userFacing: false,
errorCode: "message_not_accepted",
})
})
it.each([
["object", {}],
["number", 7],
["array", ["provider_secret"]],
["boolean", false],
["null", null],
])("does not trust a rejection carrying a malformed %s error code", async (_label, malformedCode) => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
legacyErrorProse: "trusted",
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const delivery = result.current.sendChatMessage(
"answer",
undefined,
false,
"rejected-malformed-code",
)
act(() => {
socket.receive({
type: "message_rejected",
client_message_id: "rejected-malformed-code",
error_code: malformedCode,
message: "provider token=secret",
rejection_outcome: "not_accepted",
})
})
await expect(delivery).rejects.toMatchObject({
message: "Message was rejected.",
disposition: "rejected",
userFacing: false,
errorCode: "message_not_accepted",
})
})
it("gives a trusted rejection with blank prose and no code the not-accepted code", async () => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
legacyErrorProse: "trusted",
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const delivery = result.current.sendChatMessage(
"answer",
undefined,
false,
"rejected-blank-prose",
)
act(() => {
socket.receive({
type: "message_rejected",
client_message_id: "rejected-blank-prose",
message: " ",
rejection_outcome: "not_accepted",
})
})
await expect(delivery).rejects.toMatchObject({
message: "Message was rejected.",
disposition: "rejected",
userFacing: false,
errorCode: "message_not_accepted",
})
})
it.each([
"upload_failed",
"connection_not_ready",
])("gives a definitive rejection naming the client-only code %s the not-accepted code", async (clientOnlyCode) => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
legacyErrorProse: "trusted",
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const delivery = result.current.sendChatMessage(
"answer",
undefined,
false,
"rejected-client-only-code",
)
act(() => {
socket.receive({
type: "message_rejected",
client_message_id: "rejected-client-only-code",
error_code: clientOnlyCode,
message: "token=secret",
rejection_outcome: "not_accepted",
})
})
await expect(delivery).rejects.toMatchObject({
message: "Message was rejected.",
disposition: "rejected",
userFacing: false,
errorCode: "message_not_accepted",
})
})
it.each([
["an unrecognised code with an explicit outcome_unknown outcome", { error_code: "provider_secret", rejection_outcome: "outcome_unknown" }],
["an unrecognised code with no outcome field", { error_code: "provider_secret" }],
["a client-only code with an outcome_unknown outcome", { error_code: "connection_not_ready", rejection_outcome: "outcome_unknown" }],
])("shows the outcome-unknown code for %s", async (_label, frame) => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const delivery = result.current.sendChatMessage(
"answer",
undefined,
false,
"rejected-outcome-unknown",
)
act(() => {
socket.receive({
type: "message_rejected",
client_message_id: "rejected-outcome-unknown",
message: "token=secret",
...frame,
})
})
await expect(delivery).rejects.toMatchObject({
message: "Message was rejected.",
disposition: "outcome_unknown",
userFacing: false,
errorCode: "message_outcome_unknown",
})
})
it("rejects concurrent reuse of a pending client message id without replacing its owner", async () => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const first = result.current.sendChatMessage(
"first owner",
undefined,
false,
"shared-pending-id",
)
const second = result.current.sendChatMessage(
"second owner",
undefined,
false,
"shared-pending-id",
)
await expect(second).rejects.toThrow("already pending")
expect(socket.send).toHaveBeenCalledOnce()
act(() => socket.receive({
type: "message_accepted",
client_message_id: "shared-pending-id",
}))
await expect(first).resolves.toEqual({
client_message_id: "shared-pending-id",
turn_id: "shared-pending-id",
})
})
it("marks definitive rejections so the composer can use a fresh id", async () => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
legacyErrorProse: "trusted",
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const delivery = result.current.sendChatMessage(
"retry with a new id",
undefined,
false,
"failed-turn-1",
)
act(() => {
socket.receive({
type: "message_rejected",
client_message_id: "failed-turn-1",
message: "previous delivery failed",
retry_with_new_id: true,
rejection_outcome: "not_accepted",
})
})
await expect(delivery).rejects.toMatchObject({
message: "previous delivery failed",
retryWithNewId: true,
disposition: "rejected",
})
})
it("forwards a personal unknown notice after inbox acceptance without resending", async () => {
const onMessage = vi.fn()
const { result } = renderHook(() => useWebSocket({ url: "ws://localhost", taskId: 1, onMessage }))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const delivery = result.current.sendChatMessage("uncertain", undefined, false, "original-id")
act(() => socket.receive({ type: "message_accepted", client_message_id: "original-id" }))
await delivery
act(() => {
socket.receive({ type: "message_rejected", client_message_id: "original-id", rejection_outcome: "outcome_unknown", error_code: "message_outcome_unknown" })
socket.receive({ type: "error", task_id: 1, client_message_id: "original-id", turn_id: "original-id", error_code: "message_outcome_unknown" })
})
expect(onMessage).toHaveBeenCalledWith(expect.objectContaining({
type: "error", task_id: 1,
data: expect.objectContaining({ client_message_id: "original-id", error_code: "message_outcome_unknown" }),
}))
expect(socket.send).toHaveBeenCalledTimes(1)
})
it("allows the same text to be sent again after the first ack", async () => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const first = result.current.sendChatMessage("ok")
const firstPayload = JSON.parse(socket.send.mock.calls[0][0])
act(() => {
socket.receive({
type: "message_accepted",
client_message_id: firstPayload.client_message_id,
})
})
await first
const second = result.current.sendChatMessage("ok")
expect(socket.send).toHaveBeenCalledTimes(2)
const secondPayload = JSON.parse(socket.send.mock.calls[1][0])
expect(secondPayload.client_message_id).not.toBe(firstPayload.client_message_id)
act(() => {
socket.receive({
type: "message_accepted",
client_message_id: secondPayload.client_message_id,
})
})
await second
})
it("rejects a pending delivery when the socket closes", async () => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const delivery = result.current.sendChatMessage("keep after disconnect")
act(() => socket.triggerClose())
await expect(delivery).rejects.toMatchObject({
message: "Connection closed before the message was accepted.",
disposition: "outcome_unknown",
errorCode: "message_outcome_unknown",
connectionLost: true,
})
})
it.each([
["retires the connection when nothing at all arrives", false],
["keeps the connection when any frame but no acknowledgement arrives", true],
] as const)("%s for 30 seconds after a send", async (_name, frameAfterSend) => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
vi.useFakeTimers()
try {
const delivery = result.current.sendChatMessage("timeout draft")
const rejection = expect(delivery).rejects.toMatchObject({
message: frameAfterSend
? "Message delivery was not acknowledged. Your draft was kept."
: "Connection lost before the message was accepted.",
disposition: "outcome_unknown",
errorCode: "message_outcome_unknown",
connectionLost: !frameAfterSend,
})
if (frameAfterSend) act(() => socket.receive({ type: "heartbeat" }))
await act(async () => {
vi.advanceTimersByTime(30000)
})
await rejection
expect(socket.close.mock.calls).toEqual(frameAfterSend ? [] : [[1000, "Connection liveness timeout"]])
expect(result.current.connectionPhase).toBe(frameAfterSend ? "connected" : "reconnecting")
} finally {
vi.useRealTimers()
}
})
it.each([
[undefined, "outcome_unknown"],
["pending", "outcome_unknown"],
["unexpected", "outcome_unknown"],
])("fails closed for a rejected wire outcome of %s", async (rejectionOutcome, disposition) => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
legacyErrorProse: "trusted",
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const delivery = result.current.sendChatMessage("ambiguous draft", undefined, false, "ambiguous-turn")
act(() => socket.receive({
type: "message_rejected",
client_message_id: "ambiguous-turn",
message: "ambiguous delivery",
...(rejectionOutcome === undefined ? {} : { rejection_outcome: rejectionOutcome }),
}))
await expect(delivery).rejects.toMatchObject({
message: "ambiguous delivery",
disposition,
})
})
})
describe("MessageDeliveryError display code", () => {
it.each([
["an unknown outcome with no code", "outcome_unknown", false, undefined, "message_outcome_unknown"],
["an unknown outcome with an explicit null code", "outcome_unknown", false, null, "message_outcome_unknown"],
["a user-facing unknown outcome with no code", "outcome_unknown", true, undefined, null],
["an unknown outcome with an explicit code", "outcome_unknown", false, "task_busy", "task_busy"],
["a not-sent failure with no code", "not_sent", false, undefined, null],
["a rejection with no code", "rejected", false, undefined, null],
] as const)("derives the code for %s", (_label, disposition, userFacing, errorCode, expected) => {
const error = new MessageDeliveryError("diagnostic text", disposition, {
userFacing,
...(errorCode === undefined ? {} : { errorCode }),
})
expect(error.errorCode).toBe(expected)
// Only the code is derived; every other field keeps its input.
expect(error.retryWithNewId).toBe(false)
expect(error.userFacing).toBe(userFacing)
expect(error.message).toBe("diagnostic text")
})
})
describe("useWebSocket normalized connections", () => {
beforeEach(() => {
MockWebSocket.instances = []
MockWebSocket.constructorError = null
localStorage.clear()
authState.user = { id: "user-1" }
authState.token = "token"
authState.refreshToken = "refresh-token"
authState.session = {
sessionId: "test-lineage",
credentialRevision: 0,
profileRevision: 0,
userId: "user-1",
accessToken: "token",
refreshToken: "refresh-token",
profileFingerprint: '[null,null,null]',
}
authState.refreshAccessToken.mockReset()
vi.stubGlobal("WebSocket", MockWebSocket)
})
afterEach(() => {
vi.useRealTimers()
vi.restoreAllMocks()
vi.unstubAllGlobals()
})
it("normalizes an undefined connection without putting login credentials in its URL", async () => {
renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 7,
connection: undefined,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
expect(MockWebSocket.instances[0].url).toBe("ws://localhost/ws/chat/7?liveness=heartbeat")
expect(MockWebSocket.instances[0].protocols).toEqual(["xagent-auth-v1", "xagent-auth-token.token"])
})
it("carries an explicit public guest token in the handshake header, never the built URL", async () => {
const buildWebSocketUrl = vi.fn(({ baseUrl, taskId }: { baseUrl: string; taskId: number }) =>
`${baseUrl}/api/widget/chat/ws/${taskId}`)
renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 7,
token: "guest.jwt-token",
buildWebSocketUrl,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
expect(buildWebSocketUrl).toHaveBeenCalledWith({ baseUrl: "ws://localhost", taskId: 7 })
expect(MockWebSocket.instances[0].url).toBe("ws://localhost/api/widget/chat/ws/7")
expect(MockWebSocket.instances[0].url).not.toContain("guest.jwt-token")
expect(MockWebSocket.instances[0].protocols).toEqual([
"xagent-auth-v1",
"xagent-auth-token.guest.jwt-token",
])
})
it("keeps the task id in the legacy chat frame", async () => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 7,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const delivery = result.current.sendChatMessage("legacy", undefined, false, "legacy-turn")
expect(JSON.parse(socket.send.mock.calls[0][0])).toEqual({
type: "chat",
message: "legacy",
task_id: 7,
client_message_id: "legacy-turn",
context: { timezone: expect.any(String) },
})
act(() => socket.receive({
type: "message_accepted",
client_message_id: "legacy-turn",
}))
await delivery
})
it("reports the browser timezone so the agent clock can render local time", async () => {
// Pinned, not read back from Intl: asserting against the same source the
// code reads makes the test tautological on a UTC host.
const resolvedOptions = vi
.spyOn(Intl.DateTimeFormat.prototype, "resolvedOptions")
.mockReturnValue({ timeZone: "America/New_York" } as Intl.ResolvedDateTimeFormatOptions)
try {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 7,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const delivery = result.current.sendChatMessage("what is tomorrow", undefined, false, "tz-turn")
const sent = JSON.parse(socket.send.mock.calls[0][0])
expect(sent.context).toEqual({ timezone: "America/New_York" })
act(() => socket.receive({
type: "message_accepted",
client_message_id: "tz-turn",
}))
await delivery
} finally {
resolvedOptions.mockRestore()
}
})
it("prefers the embedder-declared timezone from the iframe URL over the browser zone", async () => {
const resolvedOptions = vi
.spyOn(Intl.DateTimeFormat.prototype, "resolvedOptions")
.mockReturnValue({ timeZone: "America/New_York" } as Intl.ResolvedDateTimeFormatOptions)
window.history.replaceState({}, "", "/widget/chat/session?timezone=Australia%2FPerth")
try {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 7,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const delivery = result.current.sendChatMessage("hi", undefined, false, "declared-turn")
const sent = JSON.parse(socket.send.mock.calls[0][0])
expect(sent.context).toEqual({ timezone: "Australia/Perth" })
act(() => socket.receive({
type: "message_accepted",
client_message_id: "declared-turn",
}))
await delivery
} finally {
resolvedOptions.mockRestore()
window.history.replaceState({}, "", "/")
}
})
it("falls back to the browser zone when the declared timezone is blank", async () => {
const resolvedOptions = vi
.spyOn(Intl.DateTimeFormat.prototype, "resolvedOptions")
.mockReturnValue({ timeZone: "America/New_York" } as Intl.ResolvedDateTimeFormatOptions)
window.history.replaceState({}, "", "/widget/chat/session?timezone=%20%20")
try {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 7,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const delivery = result.current.sendChatMessage("hi", undefined, false, "blank-declared")
const sent = JSON.parse(socket.send.mock.calls[0][0])
expect(sent.context).toEqual({ timezone: "America/New_York" })
act(() => socket.receive({
type: "message_accepted",
client_message_id: "blank-declared",
}))
await delivery
} finally {
resolvedOptions.mockRestore()
window.history.replaceState({}, "", "/")
}
})
it("omits the context entirely when the browser cannot resolve a timezone", async () => {
const resolvedOptions = vi
.spyOn(Intl.DateTimeFormat.prototype, "resolvedOptions")
.mockReturnValue({ timeZone: "" } as Intl.ResolvedDateTimeFormatOptions)
try {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 7,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const delivery = result.current.sendChatMessage("hi", undefined, false, "no-tz-turn")
const sent = JSON.parse(socket.send.mock.calls[0][0])
expect("context" in sent).toBe(false)
act(() => socket.receive({
type: "message_accepted",
client_message_id: "no-tz-turn",
}))
await delivery
} finally {
resolvedOptions.mockRestore()
}
})
it("keeps a same-id retry bound to the zone of its first attempt", async () => {
const resolvedOptions = vi
.spyOn(Intl.DateTimeFormat.prototype, "resolvedOptions")
.mockReturnValue({ timeZone: "Australia/Melbourne" } as Intl.ResolvedDateTimeFormatOptions)
try {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 7,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const first = result.current.sendChatMessage("same", undefined, false, "retry-id")
expect(JSON.parse(socket.send.mock.calls[0][0]).context)
.toEqual({ timezone: "Australia/Melbourne" })
// Unknown outcome: the command may already be executing server-side, so
// the client retries under the same id.
act(() => socket.receive({
type: "message_rejected",
client_message_id: "retry-id",
message: "connection lost",
}))
await expect(first).rejects.toThrow()
resolvedOptions.mockReturnValue(
{ timeZone: "America/New_York" } as Intl.ResolvedDateTimeFormatOptions,
)
const retry = result.current.sendChatMessage("same", undefined, true, "retry-id")
expect(JSON.parse(socket.send.mock.calls[1][0]).context)
.toEqual({ timezone: "Australia/Melbourne" })
act(() => socket.receive({
type: "message_accepted",
client_message_id: "retry-id",
}))
await retry
// A genuinely new id picks up the current zone.
const fresh = result.current.sendChatMessage("next", undefined, false, "fresh-id")
expect(JSON.parse(socket.send.mock.calls[2][0]).context)
.toEqual({ timezone: "America/New_York" })
act(() => socket.receive({
type: "message_accepted",
client_message_id: "fresh-id",
}))
await fresh
} finally {
resolvedOptions.mockRestore()
}
})
it("frees the attempt zone after a not-sent failure so a same-id retry re-resolves", async () => {
const resolvedOptions = vi
.spyOn(Intl.DateTimeFormat.prototype, "resolvedOptions")
.mockReturnValue({ timeZone: "Australia/Melbourne" } as Intl.ResolvedDateTimeFormatOptions)
try {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 7,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
socket.send.mockImplementationOnce(() => {
throw new Error("socket closed during write")
})
const failed = result.current.sendChatMessage("same", undefined, false, "reuse-id")
await expect(failed).rejects.toThrow()
// Nothing reached the server, so the same id is free to adopt the new zone.
resolvedOptions.mockReturnValue(
{ timeZone: "America/New_York" } as Intl.ResolvedDateTimeFormatOptions,
)
const retry = result.current.sendChatMessage("same", undefined, false, "reuse-id")
// calls[0] is the throwing send (still records its args); the retry is calls[1].
expect(JSON.parse(socket.send.mock.calls[1][0]).context)
.toEqual({ timezone: "America/New_York" })
act(() => socket.receive({
type: "message_accepted",
client_message_id: "reuse-id",
}))
await retry
} finally {
resolvedOptions.mockRestore()
}
})
it("keeps a same-id retry context-free when the first attempt had no zone", async () => {
const resolvedOptions = vi
.spyOn(Intl.DateTimeFormat.prototype, "resolvedOptions")
.mockReturnValue({ timeZone: "" } as Intl.ResolvedDateTimeFormatOptions)
try {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 7,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const first = result.current.sendChatMessage("same", undefined, false, "omit-id")
expect("context" in JSON.parse(socket.send.mock.calls[0][0])).toBe(false)
act(() => socket.receive({
type: "message_rejected",
client_message_id: "omit-id",
message: "connection lost",
}))
await expect(first).rejects.toThrow()
resolvedOptions.mockReturnValue(
{ timeZone: "America/New_York" } as Intl.ResolvedDateTimeFormatOptions,
)
const retry = result.current.sendChatMessage("same", undefined, true, "omit-id")
expect("context" in JSON.parse(socket.send.mock.calls[1][0])).toBe(false)
act(() => socket.receive({
type: "message_accepted",
client_message_id: "omit-id",
}))
await retry
} finally {
resolvedOptions.mockRestore()
}
})
it("frees the attempt zone when a late accepted ack follows a timeout", async () => {
const resolvedOptions = vi
.spyOn(Intl.DateTimeFormat.prototype, "resolvedOptions")
.mockReturnValue({ timeZone: "Australia/Melbourne" } as Intl.ResolvedDateTimeFormatOptions)
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 7,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
vi.useFakeTimers()
try {
const first = result.current.sendChatMessage("same", undefined, false, "late-id")
first.catch(() => {})
expect(JSON.parse(socket.send.mock.calls[0][0]).context)
.toEqual({ timezone: "Australia/Melbourne" })
act(() => socket.receive({ type: "status_update" }))
await act(async () => {
vi.advanceTimersByTime(30000)
})
await expect(first).rejects.toMatchObject({ disposition: "outcome_unknown" })
resolvedOptions.mockReturnValue(
{ timeZone: "America/New_York" } as Intl.ResolvedDateTimeFormatOptions,
)
// Late terminal ack for the same id after the timeout removed the pending
// entry: the binding must be released.
act(() => socket.receive({
type: "message_accepted",
client_message_id: "late-id",
}))
const retry = result.current.sendChatMessage("same", undefined, true, "late-id")
expect(JSON.parse(socket.send.mock.calls[1][0]).context)
.toEqual({ timezone: "America/New_York" })
act(() => socket.receive({
type: "message_accepted",
client_message_id: "late-id",
}))
await retry
} finally {
vi.useRealTimers()
resolvedOptions.mockRestore()
}
})
it("frees the attempt zone when a late not_accepted reject follows a timeout", async () => {
const resolvedOptions = vi
.spyOn(Intl.DateTimeFormat.prototype, "resolvedOptions")
.mockReturnValue({ timeZone: "Australia/Melbourne" } as Intl.ResolvedDateTimeFormatOptions)
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 7,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
vi.useFakeTimers()
try {
const first = result.current.sendChatMessage("same", undefined, false, "late-rej")
first.catch(() => {})
expect(JSON.parse(socket.send.mock.calls[0][0]).context)
.toEqual({ timezone: "Australia/Melbourne" })
act(() => socket.receive({ type: "status_update" }))
await act(async () => {
vi.advanceTimersByTime(30000)
})
await expect(first).rejects.toMatchObject({ disposition: "outcome_unknown" })
resolvedOptions.mockReturnValue(
{ timeZone: "America/New_York" } as Intl.ResolvedDateTimeFormatOptions,
)
act(() => socket.receive({
type: "message_rejected",
client_message_id: "late-rej",
message: "rejected outright",
rejection_outcome: "not_accepted",
}))
const retry = result.current.sendChatMessage("same", undefined, true, "late-rej")
expect(JSON.parse(socket.send.mock.calls[1][0]).context)
.toEqual({ timezone: "America/New_York" })
act(() => socket.receive({
type: "message_accepted",
client_message_id: "late-rej",
}))
await retry
} finally {
vi.useRealTimers()
resolvedOptions.mockRestore()
}
})
it("keeps the attempt zone after a timeout until a terminal ack arrives", async () => {
const resolvedOptions = vi
.spyOn(Intl.DateTimeFormat.prototype, "resolvedOptions")
.mockReturnValue({ timeZone: "Australia/Melbourne" } as Intl.ResolvedDateTimeFormatOptions)
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 7,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
vi.useFakeTimers()
try {
const first = result.current.sendChatMessage("same", undefined, false, "keep-id")
first.catch(() => {})
expect(JSON.parse(socket.send.mock.calls[0][0]).context)
.toEqual({ timezone: "Australia/Melbourne" })
act(() => socket.receive({ type: "status_update" }))
await act(async () => {
vi.advanceTimersByTime(30000)
})
await expect(first).rejects.toMatchObject({ disposition: "outcome_unknown" })
resolvedOptions.mockReturnValue(
{ timeZone: "America/New_York" } as Intl.ResolvedDateTimeFormatOptions,
)
// A late outcome_unknown reject must NOT release the binding: a same-id
// retry is still permitted and must reuse the first attempt's zone.
act(() => socket.receive({
type: "message_rejected",
client_message_id: "keep-id",
message: "still ambiguous",
}))
const retry = result.current.sendChatMessage("same", undefined, true, "keep-id")
expect(JSON.parse(socket.send.mock.calls[1][0]).context)
.toEqual({ timezone: "Australia/Melbourne" })
act(() => socket.receive({
type: "message_accepted",
client_message_id: "keep-id",
}))
await retry
} finally {
vi.useRealTimers()
resolvedOptions.mockRestore()
}
})
it("sends without a context when Intl itself throws", async () => {
const resolvedOptions = vi
.spyOn(Intl.DateTimeFormat.prototype, "resolvedOptions")
.mockImplementation(() => {
throw new RangeError("ICU unavailable")
})
try {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 7,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const delivery = result.current.sendChatMessage("hi", undefined, false, "throw-turn")
const sent = JSON.parse(socket.send.mock.calls[0][0])
expect("context" in sent).toBe(false)
expect(sent.message).toBe("hi")
act(() => socket.receive({
type: "message_accepted",
client_message_id: "throw-turn",
}))
await delivery
} finally {
resolvedOptions.mockRestore()
}
})
it("treats an explicit null connection as disabled even when legacy inputs exist", async () => {
renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 7,
connection: null,
}))
await Promise.resolve()
expect(MockWebSocket.instances).toHaveLength(0)
})
it("constructs the exact Session URL and subprotocols and requires the server echo", async () => {
const onConnect = vi.fn()
const connection = sessionConnection()
const { result } = renderHook(() => useWebSocket({ connection, onConnect }))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
expect(socket.url).toBe("wss://embed.example/v1/external/chat/sessions/ws")
expect(socket.url).not.toContain("st_secret")
expect(socket.protocols).toEqual([
"xagent-session-v1",
"xagent-session-token.st_secret",
])
socket.protocol = "xagent-session-v1"
act(() => socket.open())
expect(result.current.isConnected).toBe(true)
expect(onConnect).toHaveBeenCalledOnce()
})
it("passes the opened socket's own task to onConnect", async () => {
const onConnect = vi.fn()
renderHook(() => useWebSocket({ url: "ws://localhost", taskId: 7, onConnect }))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
act(() => MockWebSocket.instances[0].open())
expect(onConnect).toHaveBeenCalledOnce()
expect(onConnect).toHaveBeenCalledWith(7)
})
it("sanitizes a WebSocket constructor failure before logging or exposing it", async () => {
const secret = "xagent-session-token.st_constructor_secret"
MockWebSocket.constructorError = new Error(`constructor rejected ${secret}`)
const consoleError = vi.spyOn(console, "error").mockImplementation(() => {})
const onError = vi.fn()
const onConnectionFailure = vi.fn()
const { result } = renderHook(() => useWebSocket({
connection: sessionConnection({
protocols: ["xagent-session-v1", secret],
}),
onError,
onConnectionFailure,
}))
await waitFor(() => expect(result.current.connectionError).not.toBeNull())
expect(onError).toHaveBeenCalledOnce()
expect(onConnectionFailure).toHaveBeenCalledWith({
recoverable: false,
error: result.current.connectionError,
})
const exposed = [
result.current.connectionError?.message,
...onError.mock.calls.map(([error]) => (error as Error).message),
...consoleError.mock.calls.flat().map(String),
].join(" ")
expect(exposed).not.toContain(secret)
expect(result.current.connectionError?.message).toBe(
"Failed to create WebSocket connection.",
)
})
it("fails closed when the server omits the required Session subprotocol echo", async () => {
const onConnect = vi.fn()
const onError = vi.fn()
const onConnectionFailure = vi.fn()
const { result } = renderHook(() => useWebSocket({
connection: sessionConnection(),
onConnect,
onError,
onConnectionFailure,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
expect(result.current.isConnected).toBe(false)
expect(onConnect).not.toHaveBeenCalled()
expect(onError).toHaveBeenCalledOnce()
expect(onConnectionFailure).toHaveBeenCalledWith({
recoverable: false,
error: result.current.connectionError,
})
expect(socket.close).toHaveBeenCalled()
})
it.each(["legacy error", "typed owner"] as const)(
"isolates a throwing %s callback while closing a protocol mismatch",
async (throwingCallback) => {
const secret = `callback-secret-${throwingCallback}`
const order: string[] = []
const consoleError = vi.spyOn(console, "error").mockImplementation(() => {})
const onError = vi.fn(() => {
order.push("legacy")
if (throwingCallback === "legacy error") {
throw new Error(secret)
}
})
const onConnectionFailure = vi.fn(() => {
order.push("typed")
if (throwingCallback === "typed owner") {
throw new Error(secret)
}
})
renderHook(() => useWebSocket({
connection: sessionConnection(),
onError,
onConnectionFailure,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
expect(() => act(() => socket.open())).not.toThrow()
expect(order).toEqual(["typed", "legacy"])
expect(onConnectionFailure).toHaveBeenCalledOnce()
expect(onError).toHaveBeenCalledOnce()
expect(socket.close).toHaveBeenCalledWith(
1002,
"WebSocket subprotocol mismatch",
)
expect(consoleError.mock.calls.flat().map(String).join(" "))
.not.toContain(secret)
},
)
it("classifies a physical socket error as a recoverable connection failure", async () => {
const onError = vi.fn()
const onConnectionFailure = vi.fn()
const { result } = renderHook(() => useWebSocket({
connection: sessionConnection(),
onError,
onConnectionFailure,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
socket.protocol = "xagent-session-v1"
act(() => socket.open())
act(() => socket.triggerError())
expect(result.current.isConnected).toBe(false)
expect(onError).toHaveBeenCalledOnce()
expect(onConnectionFailure).toHaveBeenCalledWith({
recoverable: true,
error: result.current.connectionError,
})
})
it("sends and acknowledges taskless Session chat without a task id", async () => {
const { result } = renderHook(() => useWebSocket({
connection: sessionConnection(),
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
socket.protocol = "xagent-session-v1"
act(() => socket.open())
const delivery = result.current.sendChatMessage(
"create lazily",
undefined,
false,
"session-turn-1",
)
const sent = JSON.parse(socket.send.mock.calls[0][0])
expect(sent).toEqual({
type: "chat",
message: "create lazily",
context: { timezone: expect.any(String) },
client_message_id: "session-turn-1",
})
act(() => socket.receive({
type: "message_accepted",
client_message_id: "session-turn-1",
turn_id: "server-turn-1",
}))
await expect(delivery).resolves.toEqual({
client_message_id: "session-turn-1",
turn_id: "server-turn-1",
})
})
it("offers an explicit unbound Session binding on the initial physical connection", async () => {
renderHook(() => useWebSocket({
connection: sessionConnection({
taskBindingMode: "session-subprotocol",
}),
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
expect(MockWebSocket.instances[0].protocols).toEqual([
"xagent-session-v1",
"xagent-session-token.st_secret",
"xagent-session-binding-v1",
"xagent-session-task.unbound",
])
})
it("offers the current bound task when establishing a replacement physical connection", async () => {
const connection = sessionConnection({
taskBindingMode: "session-subprotocol",
})
const hook = renderHook(
({ taskId }: { taskId: number | undefined }) => useWebSocket({
connection,
taskId,
}),
{ initialProps: { taskId: undefined as number | undefined } },
)
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
expect(MockWebSocket.instances[0].protocols).toContain(
"xagent-session-task.unbound",
)
hook.rerender({ taskId: 42 })
expect(MockWebSocket.instances).toHaveLength(1)
act(() => hook.result.current.disconnect())
act(() => hook.result.current.connect())
expect(MockWebSocket.instances).toHaveLength(2)
expect(MockWebSocket.instances[1].protocols).toEqual([
"xagent-session-v1",
"xagent-session-token.st_secret",
"xagent-session-binding-v1",
"xagent-session-task.42",
])
})
it.each([4001, 4003, 1011])(
"runs the Session close delegate first and suppresses legacy handling for %s",
async (code) => {
vi.useFakeTimers()
authState.refreshAccessToken.mockResolvedValue(true)
const order: string[] = []
const onError = vi.fn()
const { result } = renderHook(() => useWebSocket({
connection: sessionConnection(),
onConnectionClose: () => {
order.push("delegate")
return "handled"
},
onDisconnect: () => {
order.push("disconnect")
},
onError,
}))
await act(async () => {
await vi.advanceTimersByTimeAsync(0)
})
const socket = MockWebSocket.instances[0]
socket.protocol = "xagent-session-v1"
act(() => socket.open())
const delivery = result.current.sendChatMessage("pending")
const rejection = expect(delivery).rejects.toThrow("Connection closed")
act(() => socket.triggerClose(code))
await rejection
await act(async () => {
await vi.runAllTimersAsync()
})
expect(order).toEqual(["delegate"])
expect(result.current.isConnected).toBe(false)
expect(authState.refreshAccessToken).not.toHaveBeenCalled()
expect(onError).not.toHaveBeenCalled()
expect(MockWebSocket.instances).toHaveLength(1)
},
)
it("retires a pre-open owner before a close delegate synchronously reconnects", async () => {
let reconnect!: () => void
const onConnectionClose = vi.fn(() => {
reconnect()
return "handled" as const
})
const { result } = renderHook(() => {
const webSocket = useWebSocket({
connection: sessionConnection(),
onConnectionClose,
})
reconnect = webSocket.connect
return webSocket
})
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const oldSocket = MockWebSocket.instances[0]
act(() => oldSocket.triggerClose(1011))
expect(onConnectionClose).toHaveBeenCalledOnce()
expect(MockWebSocket.instances).toHaveLength(2)
expect(result.current.isConnected).toBe(false)
})
it("rejects old delivery and preparation before a close delegate replaces the owner", async () => {
const upload = deferred<Array<{ file_id: string }>>()
let reconnect!: () => void
const hook = renderHook(() => {
const webSocket = useWebSocket({
url: "ws://localhost",
taskId: 1,
uploadFiles: vi.fn(() => upload.promise),
onConnectionClose: () => {
reconnect()
return "handled" as const
},
})
reconnect = webSocket.connect
return webSocket
})
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const oldSocket = MockWebSocket.instances[0]
act(() => oldSocket.open())
const pending = hook.result.current.sendChatMessage("pending", undefined, false, "old-delivery")
const preparing = hook.result.current.sendChatMessage(
"preparing",
[new File(["data"], "data.txt")],
false,
"old-preparation",
)
act(() => oldSocket.triggerClose(4001))
await expect(pending).rejects.toThrow("Connection closed")
await expect(preparing).rejects.toThrow("Connection closed")
expect(MockWebSocket.instances).toHaveLength(2)
const replacement = MockWebSocket.instances[1]
act(() => replacement.open())
await act(async () => {
upload.resolve([{ file_id: "late-upload" }])
await Promise.resolve()
})
expect(replacement.readyState).toBe(MockWebSocket.OPEN)
})
it("fails closed and sanitizes when the Session close delegate throws", async () => {
const secret = "xagent-session-token.st_close_delegate_secret"
authState.refreshAccessToken.mockResolvedValue(true)
const onError = vi.fn()
const onConnectionFailure = vi.fn()
const onDisconnect = vi.fn()
const consoleError = vi.spyOn(console, "error").mockImplementation(() => {})
const { result } = renderHook(() => useWebSocket({
connection: sessionConnection(),
onConnectionClose: () => {
throw new Error(`close delegate leaked ${secret}`)
},
onDisconnect,
onError,
onConnectionFailure,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
socket.protocol = "xagent-session-v1"
act(() => socket.open())
vi.useFakeTimers()
const delivery = result.current.sendChatMessage(
"pending",
undefined,
false,
"close-handler-pending",
)
const deliveryOutcome = delivery.then(
() => "resolved",
error => `rejected:${(error as Error).message}`,
)
let escaped: unknown
try {
act(() => socket.triggerClose(4001))
} catch (error) {
escaped = error
}
expect(escaped).toBeUndefined()
expect(await deliveryOutcome).toContain("Connection closed")
expect(result.current.isConnected).toBe(false)
expect(result.current.connectionError).not.toBeNull()
expect(onError).toHaveBeenCalledOnce()
expect(onConnectionFailure).toHaveBeenCalledWith({
recoverable: false,
error: result.current.connectionError,
})
expect(onDisconnect).not.toHaveBeenCalled()
expect(authState.refreshAccessToken).not.toHaveBeenCalled()
await act(async () => {
await vi.runAllTimersAsync()
})
expect(MockWebSocket.instances).toHaveLength(1)
const exposed = [
result.current.connectionError?.message,
...onError.mock.calls.map(([error]) => (error as Error).message),
...consoleError.mock.calls.flat().map(String),
].join(" ")
expect(exposed).not.toContain(secret)
})
it("keeps legacy auth refresh, retry, pause, resume, and status behavior", async () => {
vi.spyOn(Math, "random").mockReturnValue(0.5)
authState.refreshAccessToken.mockResolvedValue(false)
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 9,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const first = MockWebSocket.instances[0]
act(() => first.open())
act(() => {
result.current.pauseTask()
result.current.resumeTask()
result.current.requestStatus()
})
expect(first.send.mock.calls.map(([frame]) => JSON.parse(frame))).toEqual([
expect.objectContaining({ type: "pause_task", task_id: 9 }),
expect.objectContaining({ type: "resume_task", task_id: 9 }),
{ type: "status_request", task_id: 9 },
])
act(() => first.triggerClose(4001))
expect(authState.refreshAccessToken).toHaveBeenCalledOnce()
expect(authState.refreshAccessToken).toHaveBeenCalledWith(expect.objectContaining({
sessionId: "test-lineage", credentialRevision: 0, accessToken: "token", userId: "user-1",
}))
const retryHook = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 10,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(2))
const retrySocket = MockWebSocket.instances[1]
act(() => retrySocket.open())
vi.useFakeTimers()
act(() => retrySocket.triggerClose(1011))
await act(async () => {
await vi.advanceTimersByTimeAsync(1000)
})
expect(MockWebSocket.instances).toHaveLength(3)
retryHook.unmount()
})
it.each([
["unmount", "resolve"],
["unmount", "reject"],
["disconnect", "resolve"],
["disconnect", "reject"],
["replacement", "resolve"],
["replacement", "reject"],
] as const)(
"ignores late auth work after %s when refresh will %s",
async (lifecycle, settlement) => {
const refresh = deferred<boolean>()
authState.refreshAccessToken.mockReturnValue(refresh.promise)
const onError = vi.fn()
const consoleError = vi.spyOn(console, "error").mockImplementation(() => {})
const hook = renderHook(
({ taskId }) => useWebSocket({
url: "ws://localhost",
taskId,
onError,
}),
{ initialProps: { taskId: 1 } },
)
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const oldSocket = MockWebSocket.instances[0]
act(() => oldSocket.open())
vi.useFakeTimers()
act(() => oldSocket.triggerClose(4001))
expect(authState.refreshAccessToken).toHaveBeenCalledOnce()
expect(authState.refreshAccessToken).toHaveBeenCalledWith(expect.objectContaining({
sessionId: "test-lineage", credentialRevision: 0, accessToken: "token", userId: "user-1",
}))
let expectedSocketCount = 1
if (lifecycle === "unmount") {
hook.unmount()
} else if (lifecycle === "disconnect") {
act(() => hook.result.current.disconnect())
} else {
hook.rerender({ taskId: 2 })
expectedSocketCount = 2
const replacementSocket = MockWebSocket.instances[1]
act(() => replacementSocket.open())
}
await act(async () => {
if (settlement === "resolve") {
refresh.resolve(true)
} else {
refresh.reject(
new Error("refresh failed xagent-session-token.st_refresh_secret"),
)
}
await Promise.resolve()
})
await act(async () => {
await vi.runAllTimersAsync()
})
expect(MockWebSocket.instances).toHaveLength(expectedSocketCount)
expect(onError).not.toHaveBeenCalled()
expect(consoleError.mock.calls.flat().join(" ")).not.toContain(
"st_refresh_secret",
)
if (lifecycle !== "unmount") hook.unmount()
},
)
it.each([
["an explicit legacy token", {
url: "ws://localhost",
taskId: 1,
token: "token",
}, "ws://localhost/ws/chat/1?liveness=heartbeat"],
["an explicit empty legacy token", {
url: "ws://localhost",
taskId: 1,
token: "",
}, "ws://localhost/ws/chat/1?liveness=heartbeat"],
["an explicit Session descriptor", {
connection: sessionConnection(),
}, "wss://embed.example/v1/external/chat/sessions/ws"],
] as const)(
"never refreshes AuthContext credentials for %s",
async (_name, options, expectedUrl) => {
vi.useFakeTimers()
authState.refreshAccessToken.mockResolvedValue(true)
const onError = vi.fn()
const hook = renderHook(() => useWebSocket({ ...options, onError }))
await act(async () => {
await vi.advanceTimersByTimeAsync(0)
})
const socket = MockWebSocket.instances[0]
expect(socket.url).toBe(expectedUrl)
if ("connection" in options) socket.protocol = "xagent-session-v1"
act(() => socket.open())
act(() => socket.triggerClose(4001))
await act(async () => {
await vi.runAllTimersAsync()
})
expect(authState.refreshAccessToken).not.toHaveBeenCalled()
expect(onError).toHaveBeenCalledOnce()
expect((onError.mock.calls[0][0] as Error).message).toBe("Authentication failed")
expect(MockWebSocket.instances).toHaveLength(1)
hook.unmount()
},
)
it("reconnects an auth-owned descriptor with the refreshed token only once", async () => {
const refresh = deferred<boolean>()
authState.token = "old-auth-token"
authState.session = {
...authState.session,
accessToken: "old-auth-token",
}
authState.refreshAccessToken.mockReturnValue(refresh.promise)
const hook = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const oldSocket = MockWebSocket.instances[0]
expect(oldSocket.url).toBe("ws://localhost/ws/chat/1?liveness=heartbeat")
expect(oldSocket.protocols).toEqual(["xagent-auth-v1", "xagent-auth-token.old-auth-token"])
act(() => oldSocket.open())
vi.useFakeTimers()
act(() => oldSocket.triggerClose(4001))
expect(authState.refreshAccessToken).toHaveBeenCalledWith(expect.objectContaining({
accessToken: "old-auth-token", userId: "user-1",
}))
authState.token = "new-auth-token"
hook.rerender()
expect(MockWebSocket.instances).toHaveLength(2)
const refreshedSocket = MockWebSocket.instances[1]
expect(refreshedSocket.url).toBe("ws://localhost/ws/chat/1?liveness=heartbeat")
expect(refreshedSocket.protocols).toEqual(["xagent-auth-v1", "xagent-auth-token.new-auth-token"])
act(() => refreshedSocket.open())
await act(async () => {
refresh.resolve(true)
await Promise.resolve()
await vi.advanceTimersByTimeAsync(1000)
})
expect(MockWebSocket.instances).toHaveLength(2)
hook.unmount()
})
it("does not reuse a replacement user's token for an uncommitted old descriptor", async () => {
const aliceUser = {
id: "user-a",
username: "alice",
email: null,
is_admin: false,
}
const bobUser = {
id: "user-b",
username: "bob",
email: null,
is_admin: false,
}
writeAuthCache(aliceUser, "user-a-token", "user-a-refresh", 120, 240)
authState.session = readAuthSessionSnapshot()
authState.user = { id: aliceUser.id }
authState.token = "user-a-token"
authState.refreshAccessToken.mockImplementation(
async (expectedSession) => {
if (!expectedSession) return false
const result = await refreshStoredAccessToken(expectedSession)
return result.accessToken !== null
},
)
const onError = vi.fn()
const hook = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
onError,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const oldSocket = MockWebSocket.instances[0]
act(() => oldSocket.open())
vi.useFakeTimers()
writeAuthCache(bobUser, "user-b-token", "user-b-refresh", 120, 240)
act(() => oldSocket.triggerClose(4001))
await act(async () => {
await Promise.resolve()
await vi.advanceTimersByTimeAsync(1000)
})
expect(authState.refreshAccessToken).toHaveBeenCalledWith(expect.objectContaining({
accessToken: "user-a-token", userId: "user-a",
}))
expect(readAuthCache()).toMatchObject({
token: "user-b-token",
user: { id: "user-b" },
})
expect(onError).toHaveBeenCalledOnce()
expect(MockWebSocket.instances).toHaveLength(1)
hook.unmount()
})
it("retires a closing owner before a same-descriptor replacement claims its id", async () => {
const oldUpload = deferred<Array<{ file_id: string }>>()
const uploadFiles = vi.fn(() => oldUpload.promise)
const onDisconnect = vi.fn()
const hook = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
uploadFiles,
onDisconnect,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const oldSocket = MockWebSocket.instances[0]
act(() => oldSocket.open())
let oldSettled = false
const oldOutcome = hook.result.current.sendChatMessage(
"old upload",
[new File(["old"], "old.txt")],
false,
"same-attempt-id",
).then(
() => "resolved",
error => `rejected:${(error as Error).message}`,
).finally(() => {
oldSettled = true
})
oldSocket.readyState = MockWebSocket.CLOSING
act(() => hook.result.current.connect())
expect(MockWebSocket.instances).toHaveLength(2)
const replacementSocket = MockWebSocket.instances[1]
act(() => replacementSocket.open())
await act(async () => {
await Promise.resolve()
})
const oldSettledBeforeUploadCompleted = oldSettled
const replacementDelivery = hook.result.current.sendChatMessage(
"replacement",
undefined,
false,
"same-attempt-id",
)
const replacementOutcome = replacementDelivery.then(
ack => ack,
error => `rejected:${(error as Error).message}`,
)
await act(async () => {
oldUpload.resolve([{ file_id: "stale-upload" }])
await Promise.resolve()
})
act(() => {
oldSocket.triggerClose(1000, "late old close")
replacementSocket.receive({
type: "message_accepted",
client_message_id: "same-attempt-id",
})
})
expect(oldSettledBeforeUploadCompleted).toBe(true)
expect(await oldOutcome).toContain("replaced")
await expect(replacementOutcome).resolves.toMatchObject({
client_message_id: "same-attempt-id",
})
expect(oldSocket.close).toHaveBeenCalledOnce()
expect(onDisconnect).toHaveBeenCalledOnce()
hook.unmount()
})
it("does not preserve a closing owner when its replacement constructor fails", async () => {
const oldUpload = deferred<Array<{ file_id: string }>>()
const uploadFiles = vi.fn(() => oldUpload.promise)
const onDisconnect = vi.fn()
const onError = vi.fn()
const consoleError = vi.spyOn(console, "error").mockImplementation(() => {})
const hook = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
uploadFiles,
onDisconnect,
onError,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const oldSocket = MockWebSocket.instances[0]
act(() => oldSocket.open())
let oldSettled = false
const oldOutcome = hook.result.current.sendChatMessage(
"old upload",
[new File(["old"], "old.txt")],
false,
"constructor-failure-id",
).then(
() => "resolved",
error => `rejected:${(error as Error).message}`,
).finally(() => {
oldSettled = true
})
oldSocket.readyState = MockWebSocket.CLOSING
MockWebSocket.constructorError = new Error("constructor secret")
act(() => hook.result.current.connect())
await act(async () => {
await Promise.resolve()
})
const oldSettledBeforeUploadCompleted = oldSettled
MockWebSocket.constructorError = null
act(() => hook.result.current.connect())
expect(MockWebSocket.instances).toHaveLength(2)
const replacementSocket = MockWebSocket.instances[1]
act(() => replacementSocket.open())
await act(async () => {
oldUpload.resolve([{ file_id: "stale-upload" }])
await Promise.resolve()
})
act(() => oldSocket.triggerClose(1000, "late old close"))
expect(oldSettledBeforeUploadCompleted).toBe(true)
expect(await oldOutcome).toContain("replaced")
expect(oldSocket.close).toHaveBeenCalledOnce()
expect(onDisconnect).toHaveBeenCalledOnce()
expect(onError).toHaveBeenCalledOnce()
expect(consoleError.mock.calls.flat().join(" ")).not.toContain("constructor secret")
expect(hook.result.current.isConnected).toBe(true)
hook.unmount()
})
it.each([
["failed", false],
["successful", true],
] as const)(
"fences a stale %s auth refresh after a same-descriptor manual connect",
async (_settlement, refreshSucceeded) => {
const refresh = deferred<boolean>()
authState.refreshAccessToken.mockReturnValue(refresh.promise)
const onError = vi.fn()
const hook = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
onError,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const oldSocket = MockWebSocket.instances[0]
act(() => oldSocket.open())
vi.useFakeTimers()
act(() => oldSocket.triggerClose(4001))
expect(authState.refreshAccessToken).toHaveBeenCalledOnce()
expect(authState.refreshAccessToken).toHaveBeenCalledWith(expect.objectContaining({
sessionId: "test-lineage", credentialRevision: 0, accessToken: "token", userId: "user-1",
}))
act(() => hook.result.current.connect())
expect(MockWebSocket.instances).toHaveLength(2)
const currentSocket = MockWebSocket.instances[1]
act(() => currentSocket.open())
if (refreshSucceeded) {
act(() => currentSocket.triggerClose(1000, "current socket closed cleanly"))
}
await act(async () => {
refresh.resolve(refreshSucceeded)
await Promise.resolve()
await vi.advanceTimersByTimeAsync(1000)
})
expect(onError).not.toHaveBeenCalled()
expect(MockWebSocket.instances).toHaveLength(2)
hook.unmount()
},
)
it.each([
"default close",
"explicit disconnect",
"descriptor replacement",
"unmount",
] as const)(
"notifies the socket-owning disconnect callback exactly once on %s",
async (operation) => {
const owningDisconnect = vi.fn()
const latestDisconnect = vi.fn()
const initialConnection = sessionConnection()
const hook = renderHook(
({ connection, onDisconnect }) => useWebSocket({
connection,
onDisconnect,
}),
{
initialProps: {
connection: initialConnection,
onDisconnect: owningDisconnect,
},
},
)
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const ownedSocket = MockWebSocket.instances[0]
ownedSocket.protocol = "xagent-session-v1"
act(() => ownedSocket.open())
if (operation === "descriptor replacement") {
hook.rerender({
connection: sessionConnection({
url: "wss://embed.example/v1/external/chat/sessions/replacement/ws",
}),
onDisconnect: latestDisconnect,
})
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(2))
} else {
hook.rerender({
connection: sessionConnection(),
onDisconnect: latestDisconnect,
})
expect(MockWebSocket.instances).toHaveLength(1)
if (operation === "default close") {
act(() => ownedSocket.triggerClose(1006))
} else if (operation === "explicit disconnect") {
act(() => hook.result.current.disconnect())
} else {
hook.unmount()
}
}
act(() => ownedSocket.triggerClose(1011))
expect(owningDisconnect).toHaveBeenCalledOnce()
expect(latestDisconnect).not.toHaveBeenCalled()
if (operation !== "unmount") hook.unmount()
},
)
it.each([
"default close",
"explicit disconnect",
"descriptor replacement",
"unmount",
] as const)(
"finishes owner retirement when the disconnect callback throws on %s",
async (operation) => {
const secret = "disconnect callback raw secret"
const oldUpload = deferred<Array<{ file_id: string }>>()
const uploadFiles = vi.fn(() => oldUpload.promise)
const throwingDisconnect = vi.fn<() => void>(() => {
throw new Error(secret)
})
const safeDisconnect = vi.fn()
const consoleError = vi.spyOn(console, "error").mockImplementation(() => {})
const hook = renderHook(
({ taskId, onDisconnect }) => useWebSocket({
url: "ws://localhost",
taskId,
uploadFiles,
onDisconnect,
}),
{
initialProps: {
taskId: 1,
onDisconnect: throwingDisconnect,
},
},
)
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const oldSocket = MockWebSocket.instances[0]
act(() => oldSocket.open())
const pendingOutcome = hook.result.current.sendChatMessage(
"pending",
undefined,
false,
"throwing-disconnect-pending",
).then(
() => "resolved",
error => `rejected:${(error as Error).message}`,
)
const preparationOutcome = hook.result.current.sendChatMessage(
"preparing",
[new File(["data"], "data.txt")],
false,
"throwing-disconnect-preparation",
).then(
() => "resolved",
error => `rejected:${(error as Error).message}`,
)
let escaped: unknown
try {
if (operation === "default close") {
act(() => oldSocket.triggerClose(1006))
} else if (operation === "explicit disconnect") {
act(() => hook.result.current.disconnect())
} else if (operation === "descriptor replacement") {
hook.rerender({
taskId: 2,
onDisconnect: safeDisconnect,
})
} else {
hook.unmount()
}
} catch (error) {
escaped = error
}
await act(async () => {
await Promise.resolve()
})
const stateWasDisconnected = operation === "unmount"
? true
: hook.result.current.isConnected === false
await act(async () => {
oldUpload.resolve([{ file_id: "late-file" }])
await Promise.resolve()
})
let replacementContinued = operation === "unmount"
if (operation !== "unmount" && escaped === undefined) {
if (operation !== "descriptor replacement") {
hook.rerender({
taskId: 1,
onDisconnect: safeDisconnect,
})
act(() => hook.result.current.connect())
}
replacementContinued = MockWebSocket.instances.length === 2
if (replacementContinued) {
act(() => MockWebSocket.instances[1].open())
}
hook.unmount()
} else if (operation !== "unmount") {
hook.unmount()
}
expect(escaped).toBeUndefined()
expect(stateWasDisconnected).toBe(true)
expect(oldSocket.readyState).toBe(MockWebSocket.CLOSED)
expect(await pendingOutcome).toContain("rejected:")
expect(await preparationOutcome).toContain("rejected:")
expect(throwingDisconnect).toHaveBeenCalledOnce()
expect(replacementContinued).toBe(true)
expect(consoleError).toHaveBeenCalledWith(
"WebSocket disconnect handler failed",
)
const exposed = [
String(escaped),
...consoleError.mock.calls.flat().map(String),
].join(" ")
expect(exposed).not.toContain(secret)
},
)
it("uses the normalized connection object as lifecycle identity", async () => {
const connection = sessionConnection()
const hook = renderHook(
({ connection }) => useWebSocket({ connection }),
{ initialProps: { connection } },
)
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
hook.rerender({ connection })
expect(MockWebSocket.instances).toHaveLength(1)
hook.rerender({ connection: { ...connection } })
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(2))
})
it("retires a stalled handshake before reporting its structured transport failure", async () => {
vi.useFakeTimers()
const onConnectionFailure = vi.fn()
const { result } = renderHook(() => useWebSocket({
connection: sessionConnection(),
onConnectionFailure,
}))
await act(async () => {
await vi.advanceTimersByTimeAsync(0)
})
expect(MockWebSocket.instances).toHaveLength(1)
const socket = MockWebSocket.instances[0]
act(() => vi.advanceTimersByTime(10_000))
expect(socket.close).toHaveBeenCalled()
expect(result.current.isConnected).toBe(false)
expect(onConnectionFailure).toHaveBeenCalledWith(expect.objectContaining({
recoverable: true,
}))
})
it("retires an errored owner before its failure callback can synchronously retry", async () => {
let retry!: () => void
const onConnectionFailure = vi.fn(() => retry())
const { result } = renderHook(() => {
const webSocket = useWebSocket({
connection: sessionConnection(),
onConnectionFailure,
})
retry = webSocket.connect
return webSocket
})
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
act(() => MockWebSocket.instances[0].triggerError())
expect(onConnectionFailure).toHaveBeenCalledOnce()
expect(MockWebSocket.instances).toHaveLength(2)
expect(result.current.isConnected).toBe(false)
})
it("forwards the owning Session identity with close and transport-failure callbacks", async () => {
const onSessionConnectionClose = vi.fn(() => "handled" as const)
const onSessionConnectionFailure = vi.fn()
const connection = sessionConnection({ identity: "widget-session:owner-a" })
const closeHook = renderHook(() => useWebSocket({
connection,
onSessionConnectionClose,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const closeSocket = MockWebSocket.instances[0]
closeSocket.protocol = "xagent-session-v1"
act(() => closeSocket.open())
act(() => closeSocket.triggerClose(1006))
expect(onSessionConnectionClose).toHaveBeenCalledWith(
expect.objectContaining({ code: 1006 }),
"widget-session:owner-a",
)
closeHook.unmount()
MockWebSocket.instances = []
const failureHook = renderHook(() => useWebSocket({
connection,
onSessionConnectionFailure,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
act(() => MockWebSocket.instances[0].triggerError())
expect(onSessionConnectionFailure).toHaveBeenCalledWith(
expect.objectContaining({ recoverable: true }),
"widget-session:owner-a",
)
failureHook.unmount()
})
it("bounds 4001 refresh retries across socket opens without resetting on open", async () => {
authState.refreshAccessToken.mockResolvedValue(true)
const onConnectionFailure = vi.fn()
const hook = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
onConnectionFailure,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
vi.useFakeTimers()
for (let index = 0; index < 3; index += 1) {
const socket = MockWebSocket.instances[index]
act(() => socket.open())
act(() => socket.triggerClose(4001))
await act(async () => {
await Promise.resolve()
await vi.advanceTimersByTimeAsync(1_000)
})
}
expect(MockWebSocket.instances).toHaveLength(4)
const exhaustedSocket = MockWebSocket.instances[3]
act(() => exhaustedSocket.open())
act(() => exhaustedSocket.triggerClose(4001))
await act(async () => {
await Promise.resolve()
await vi.runOnlyPendingTimersAsync()
})
expect(MockWebSocket.instances).toHaveLength(4)
expect(onConnectionFailure).toHaveBeenCalledWith({
recoverable: false,
error: expect.objectContaining({
message: "Authentication failed after token refresh retries",
}),
})
hook.unmount()
})
it("keeps an exhausted 4001 retry budget across an auth credential revision", async () => {
authState.refreshAccessToken.mockResolvedValue(true)
const onError = vi.fn()
const hook = renderHook(() => useWebSocket({ url: "ws://localhost", taskId: 1, onError }))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
vi.useFakeTimers()
for (let index = 0; index < 3; index += 1) {
const socket = MockWebSocket.instances[index]
act(() => socket.open())
act(() => socket.triggerClose(4001))
await act(async () => {
await Promise.resolve()
await vi.advanceTimersByTimeAsync(1_000)
})
}
authState.token = "advanced-token"
authState.session = {
...authState.session,
accessToken: "advanced-token",
credentialRevision: 1,
}
hook.rerender()
expect(MockWebSocket.instances).toHaveLength(5)
const revisedSocket = MockWebSocket.instances[4]
act(() => revisedSocket.open())
act(() => revisedSocket.triggerClose(4001))
expect(authState.refreshAccessToken).toHaveBeenCalledTimes(3)
expect(onError).toHaveBeenCalledWith(expect.objectContaining({
message: "Authentication failed after token refresh retries",
}))
hook.unmount()
})
it("keeps an exhausted 4001 retry budget across a null connection gap for the same auth session", async () => {
authState.refreshAccessToken.mockResolvedValue(true)
const onError = vi.fn()
const hook = renderHook(
({ connection }: { connection: WebSocketConnection | null | undefined }) => useWebSocket({
url: "ws://localhost",
taskId: 1,
connection,
onError,
}),
{ initialProps: { connection: undefined } as { connection: WebSocketConnection | null | undefined } },
)
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
vi.useFakeTimers()
for (let index = 0; index < 3; index += 1) {
const socket = MockWebSocket.instances[index]
act(() => socket.open())
act(() => socket.triggerClose(4001))
await act(async () => {
await Promise.resolve()
await vi.advanceTimersByTimeAsync(1_000)
})
}
hook.rerender({ connection: null })
hook.rerender({ connection: undefined })
expect(MockWebSocket.instances).toHaveLength(5)
const sameSessionSocket = MockWebSocket.instances[4]
act(() => sameSessionSocket.open())
act(() => sameSessionSocket.triggerClose(4001))
expect(authState.refreshAccessToken).toHaveBeenCalledTimes(3)
expect(onError).toHaveBeenCalledWith(expect.objectContaining({
message: "Authentication failed after token refresh retries",
}))
hook.unmount()
})
it("does not replenish an exhausted auth retry budget from external socket activity", async () => {
authState.refreshAccessToken.mockResolvedValue(true)
const onError = vi.fn()
const hook = renderHook(
({ connection }: { connection: WebSocketConnection | undefined }) => useWebSocket({
url: "ws://localhost",
taskId: 1,
connection,
onError,
}),
{ initialProps: { connection: undefined } as { connection: WebSocketConnection | undefined } },
)
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
vi.useFakeTimers()
for (let index = 0; index < 3; index += 1) {
const socket = MockWebSocket.instances[index]
act(() => socket.open())
act(() => socket.triggerClose(4001))
await act(async () => {
await Promise.resolve()
await vi.advanceTimersByTimeAsync(1_000)
})
}
hook.rerender({ connection: sessionConnection() })
expect(MockWebSocket.instances).toHaveLength(5)
const externalSocket = MockWebSocket.instances[4]
externalSocket.protocol = "xagent-session-v1"
act(() => {
externalSocket.open()
externalSocket.receive({ type: "task_info", task_id: 1 })
})
hook.rerender({ connection: undefined })
expect(MockWebSocket.instances).toHaveLength(6)
const sameSessionSocket = MockWebSocket.instances[5]
act(() => sameSessionSocket.open())
act(() => sameSessionSocket.triggerClose(4001))
expect(authState.refreshAccessToken).toHaveBeenCalledTimes(3)
expect(onError).toHaveBeenCalledWith(expect.objectContaining({
message: "Authentication failed after token refresh retries",
}))
hook.unmount()
})
it("resets an exhausted 4001 retry budget for a new auth session lineage", async () => {
authState.refreshAccessToken.mockResolvedValue(true)
const hook = renderHook(() => useWebSocket({ url: "ws://localhost", taskId: 1 }))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
vi.useFakeTimers()
for (let index = 0; index < 3; index += 1) {
const socket = MockWebSocket.instances[index]
act(() => socket.open())
act(() => socket.triggerClose(4001))
await act(async () => {
await Promise.resolve()
await vi.advanceTimersByTimeAsync(1_000)
})
}
authState.token = "replacement-token"
authState.session = {
...authState.session,
sessionId: "replacement-lineage",
accessToken: "replacement-token",
credentialRevision: 0,
}
hook.rerender()
expect(MockWebSocket.instances).toHaveLength(5)
const replacementSocket = MockWebSocket.instances[4]
act(() => replacementSocket.open())
act(() => replacementSocket.triggerClose(4001))
await act(async () => {
await Promise.resolve()
await vi.advanceTimersByTimeAsync(1_000)
})
expect(authState.refreshAccessToken).toHaveBeenCalledTimes(4)
expect(MockWebSocket.instances).toHaveLength(6)
hook.unmount()
})
it("keeps a stale auth refresh result from affecting a replacement session lineage", async () => {
const refresh = deferred<boolean>()
authState.refreshAccessToken.mockReturnValue(refresh.promise)
const onError = vi.fn()
const hook = renderHook(() => useWebSocket({ url: "ws://localhost", taskId: 1, onError }))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const oldSocket = MockWebSocket.instances[0]
act(() => oldSocket.open())
vi.useFakeTimers()
act(() => oldSocket.triggerClose(4001))
expect(authState.refreshAccessToken).toHaveBeenCalledWith(expect.objectContaining({
sessionId: "test-lineage",
}))
authState.token = "replacement-token"
authState.session = {
...authState.session,
sessionId: "replacement-lineage",
accessToken: "replacement-token",
credentialRevision: 0,
}
hook.rerender()
expect(MockWebSocket.instances).toHaveLength(2)
act(() => MockWebSocket.instances[1].open())
await act(async () => {
refresh.resolve(true)
await Promise.resolve()
await vi.advanceTimersByTimeAsync(1_000)
})
expect(MockWebSocket.instances).toHaveLength(2)
expect(onError).not.toHaveBeenCalled()
hook.unmount()
})
it("does not replenish the 4001 retry budget after valid socket activity", async () => {
authState.refreshAccessToken.mockResolvedValue(true)
const hook = renderHook(() => useWebSocket({ url: "ws://localhost", taskId: 1 }))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
vi.useFakeTimers()
for (let index = 0; index < 2; index += 1) {
const socket = MockWebSocket.instances[index]
act(() => socket.open())
act(() => socket.triggerClose(4001))
await act(async () => {
await Promise.resolve()
await vi.advanceTimersByTimeAsync(1_000)
})
}
const activitySocket = MockWebSocket.instances[2]
act(() => {
activitySocket.open()
activitySocket.receive({ type: "task_info", task_id: 1 })
})
for (let index = 2; index < 3; index += 1) {
const socket = MockWebSocket.instances[index]
act(() => socket.triggerClose(4001))
await act(async () => {
await Promise.resolve()
await vi.advanceTimersByTimeAsync(1_000)
})
}
expect(authState.refreshAccessToken).toHaveBeenCalledTimes(3)
expect(MockWebSocket.instances).toHaveLength(4)
hook.unmount()
})
it.each([
["authorization expired", "authorization expired"],
["", "Access denied"],
])("reports 4003 close reason %j or the access-denied fallback through structured failure", async (reason, expectedMessage) => {
const onError = vi.fn()
const onConnectionFailure = vi.fn()
const { result } = renderHook(() => useWebSocket({
connection: sessionConnection(),
onError,
onConnectionFailure,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
socket.protocol = "xagent-session-v1"
act(() => socket.open())
act(() => socket.triggerClose(4003, reason))
expect(result.current.connectionError?.message).toBe(expectedMessage)
expect(onError).toHaveBeenCalledWith(expect.objectContaining({ message: expectedMessage }))
expect(onConnectionFailure).toHaveBeenCalledWith({
recoverable: false,
error: expect.objectContaining({ message: expectedMessage }),
})
})
it.each([
["external credentials", () => sessionConnection()],
["missing auth lineage", () => ({
...sessionConnection(),
credentialOwner: {
kind: "auth-context" as const,
accessToken: "access",
userId: "user-1",
},
})],
])("reports permanent 4001 %s through structured failure", async (_name, makeConnection) => {
const onConnectionFailure = vi.fn()
const onError = vi.fn()
const connection = makeConnection()
const { result } = renderHook(() => useWebSocket({
connection,
onConnectionFailure,
onError,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
socket.protocol = "xagent-session-v1"
act(() => socket.open())
act(() => socket.triggerClose(4001))
expect(result.current.connectionError?.message).toMatch(/authentication/i)
expect(onConnectionFailure).toHaveBeenCalledWith({
recoverable: false,
error: expect.objectContaining({ message: result.current.connectionError?.message }),
})
expect(onError).toHaveBeenCalledOnce()
})
it.each([
["returns false", () => authState.refreshAccessToken.mockResolvedValue(false)],
["rejects", () => authState.refreshAccessToken.mockRejectedValue(new Error("refresh failed"))],
["throws", () => authState.refreshAccessToken.mockImplementation(() => {
throw new Error("refresh threw")
})],
] as const)("reports a 4001 refresh that %s through structured failure", async (_name, configureRefresh) => {
configureRefresh()
const onConnectionFailure = vi.fn()
const onError = vi.fn()
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
onConnectionFailure,
onError,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
act(() => socket.triggerClose(4001))
await waitFor(() => expect(onConnectionFailure).toHaveBeenCalledOnce())
expect(result.current.connectionError?.message).toMatch(/authentication failed/i)
expect(onError).toHaveBeenCalledOnce()
})
it("resets the transport reconnect delay after explicit disconnect without resetting auth refresh", async () => {
vi.spyOn(Math, "random").mockReturnValue(0.5)
const { result } = renderHook(() => useWebSocket({ url: "ws://localhost", taskId: 1 }))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
vi.useFakeTimers()
const first = MockWebSocket.instances[0]
act(() => first.open())
act(() => first.triggerClose(1011))
act(() => result.current.disconnect())
act(() => result.current.connect())
expect(MockWebSocket.instances).toHaveLength(2)
const second = MockWebSocket.instances[1]
act(() => second.open())
act(() => second.triggerClose(1011))
await act(async () => {
await vi.advanceTimersByTimeAsync(1_000)
})
expect(MockWebSocket.instances).toHaveLength(3)
})
it("does not suppress a retry for an arbitrary close reason", async () => {
vi.spyOn(Math, "random").mockReturnValue(0.5)
const hook = renderHook(() => useWebSocket({ url: "ws://localhost", taskId: 1 }))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
vi.useFakeTimers()
const socket = MockWebSocket.instances[0]
act(() => socket.open())
act(() => socket.triggerClose(1011, "Component unmounting"))
await act(async () => vi.advanceTimersByTimeAsync(1_000))
expect(MockWebSocket.instances).toHaveLength(2)
hook.unmount()
})
it("replaces the socket when an auth-owned credential changes", async () => {
const secret = "xagent-session-token.st_descriptor_secret"
const first = sessionConnection({
credentialOwner: {
kind: "auth-context",
accessToken: "first-access-token",
userId: "user-1",
},
protocols: ["xagent-session-v1", secret],
})
const { rerender } = renderHook(
({ connection }) => useWebSocket({ connection }),
{ initialProps: { connection: first } },
)
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
rerender({ connection: {
...first,
credentialOwner: {
kind: "auth-context",
accessToken: "second-access-token",
userId: "user-1",
},
} })
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(2))
})
it("starts a new lifecycle when a caller replaces the descriptor for a profile-only auth revision", async () => {
const first = sessionConnection({ credentialOwner: {
kind: "auth-context", accessToken: "access", userId: "user-1",
session: { ...authState.session, profileRevision: 0 },
} })
const firstOwner = first.credentialOwner
if (firstOwner.kind !== "auth-context") throw new Error("expected auth owner")
const { rerender } = renderHook(({ connection }) => useWebSocket({ connection }), { initialProps: { connection: first } })
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
rerender({ connection: { ...first, credentialOwner: {
...firstOwner, session: { ...authState.session, profileRevision: 1, profileFingerprint: '["alice",null,null]' },
} } })
await Promise.resolve()
expect(MockWebSocket.instances).toHaveLength(2)
})
it("replaces a socket when its auth credential revision changes", async () => {
const first = sessionConnection({ credentialOwner: {
kind: "auth-context", accessToken: "access", userId: "user-1",
session: { ...authState.session, credentialRevision: 0 },
} })
const firstOwner = first.credentialOwner
if (firstOwner.kind !== "auth-context") throw new Error("expected auth owner")
const { rerender } = renderHook(({ connection }) => useWebSocket({ connection }), { initialProps: { connection: first } })
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
rerender({ connection: { ...first, credentialOwner: {
...firstOwner, accessToken: "new-access", session: { ...authState.session, accessToken: "new-access", credentialRevision: 1 },
} } })
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(2))
})
it("replaces a socket for the known former descriptor-hash collision pair", async () => {
const first = sessionConnection({
protocols: ["xagent-session-v1", "xagent-session-token.st_collision_0073zx"],
})
const { rerender } = renderHook(
({ connection }) => useWebSocket({ connection }),
{ initialProps: { connection: first } },
)
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
rerender({
connection: {
...first,
protocols: ["xagent-session-v1", "xagent-session-token.st_collision_00apad"],
},
})
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(2))
})
it("replaces sockets for every connection field without exposing descriptor material", async () => {
const secretQuery = "bearer-query-secret"
const secretProtocol = "xagent-session-token.st_fingerprint_secret"
const connection: WebSocketConnection = {
identity: "identity-1",
url: `wss://embed.example/ws?token=${secretQuery}`,
protocols: ["xagent-session-v1", secretProtocol],
expectedProtocol: "xagent-session-v1",
taskId: 1,
chatTaskIdMode: "required",
credentialOwner: {
kind: "auth-context",
accessToken: "access-token-1",
userId: "user-1",
},
}
const variants: WebSocketConnection[] = [
{ ...connection, identity: "identity-2" },
{ ...connection, url: "wss://embed.example/ws?token=changed-query-secret" },
{ ...connection, protocols: ["xagent-session-v1", "xagent-session-token.changed"] },
{ ...connection, expectedProtocol: "xagent-session-v2" },
{ ...connection, taskId: 2 },
{ ...connection, chatTaskIdMode: "omit" },
{ ...connection, credentialOwner: { kind: "external" } },
{ ...connection, credentialOwner: { kind: "auth-context", accessToken: "access-token-2", userId: "user-1" } },
{ ...connection, credentialOwner: { kind: "auth-context", accessToken: "access-token-1", userId: "user-2" } },
]
for (const currentConnection of variants) {
MockWebSocket.instances = []
const hook = renderHook(
({ descriptor }) => useWebSocket({ connection: descriptor }),
{ initialProps: { descriptor: connection } },
)
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
hook.rerender({ descriptor: currentConnection })
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(2))
const exposed = JSON.stringify(hook.result.current)
expect(exposed).not.toContain(secretQuery)
expect(exposed).not.toContain(secretProtocol)
expect(exposed).not.toContain("access-token-1")
hook.unmount()
}
})
it("keeps the callback snapshot that owned a socket attempt", async () => {
const firstFailure = vi.fn()
const replacementFailure = vi.fn()
const hook = renderHook(
({ onConnectionFailure }) => useWebSocket({
connection: sessionConnection(),
onConnectionFailure,
}),
{ initialProps: { onConnectionFailure: firstFailure } },
)
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
hook.rerender({ onConnectionFailure: replacementFailure })
act(() => MockWebSocket.instances[0].triggerError())
expect(firstFailure).toHaveBeenCalledOnce()
expect(replacementFailure).not.toHaveBeenCalled()
})
it("makes stale open, message, error, and close callbacks inert after replacement", async () => {
const onConnect = vi.fn()
const onMessage = vi.fn()
const onError = vi.fn()
const onDisconnect = vi.fn()
const onConnectionClose = vi.fn(() => "handled" as const)
const { result, rerender } = renderHook(
({ connection }) => useWebSocket({
connection,
onConnect,
onMessage,
onError,
onDisconnect,
onConnectionClose,
}),
{ initialProps: { connection: sessionConnection() } },
)
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const oldSocket = MockWebSocket.instances[0]
rerender({ connection: sessionConnection({ identity: "widget-session:2" }) })
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(2))
const currentSocket = MockWebSocket.instances[1]
currentSocket.protocol = "xagent-session-v1"
act(() => currentSocket.open())
onConnect.mockClear()
onMessage.mockClear()
onError.mockClear()
onDisconnect.mockClear()
onConnectionClose.mockClear()
oldSocket.protocol = "xagent-session-v1"
act(() => {
oldSocket.open()
oldSocket.receive({ type: "task_info", task_id: 999 })
oldSocket.triggerError()
oldSocket.triggerClose(1011)
})
expect(result.current.isConnected).toBe(true)
expect(result.current.lastMessage).toBeNull()
expect(onConnect).not.toHaveBeenCalled()
expect(onMessage).not.toHaveBeenCalled()
expect(onError).not.toHaveBeenCalled()
expect(onDisconnect).not.toHaveBeenCalled()
expect(onConnectionClose).not.toHaveBeenCalled()
expect(MockWebSocket.instances).toHaveLength(2)
})
it("rejects only old pending delivery on replacement and ignores its late ack", async () => {
const { result, rerender } = renderHook(
({ connection }) => useWebSocket({ connection }),
{ initialProps: { connection: sessionConnection() } },
)
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const oldSocket = MockWebSocket.instances[0]
oldSocket.protocol = "xagent-session-v1"
act(() => oldSocket.open())
const oldDelivery = result.current.sendChatMessage(
"old",
undefined,
false,
"shared-id",
)
const oldRejection = expect(oldDelivery).rejects.toMatchObject({
message: expect.stringContaining("replaced"),
connectionLost: true,
})
rerender({ connection: sessionConnection({ identity: "widget-session:2" }) })
await oldRejection
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(2))
const currentSocket = MockWebSocket.instances[1]
currentSocket.protocol = "xagent-session-v1"
act(() => currentSocket.open())
const currentDelivery = result.current.sendChatMessage(
"new",
undefined,
false,
"shared-id",
)
let currentSettled = false
void currentDelivery.finally(() => {
currentSettled = true
})
act(() => {
oldSocket.receive({
type: "message_accepted",
client_message_id: "shared-id",
})
oldSocket.triggerClose(1011)
})
await Promise.resolve()
expect(currentSettled).toBe(false)
act(() => currentSocket.receive({
type: "message_accepted",
client_message_id: "shared-id",
}))
await expect(currentDelivery).resolves.toMatchObject({
client_message_id: "shared-id",
})
})
it("invalidates pending and dedupe state on delivery generation without reconnecting", async () => {
const connection = sessionConnection()
const { result, rerender } = renderHook(
({ deliveryGeneration }) => useWebSocket({
connection,
deliveryGeneration,
}),
{ initialProps: { deliveryGeneration: 0 } },
)
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
socket.protocol = "xagent-session-v1"
act(() => socket.open())
const oldDelivery = result.current.sendChatMessage("same text")
const oldRejection = expect(oldDelivery).rejects.toMatchObject({
message: expect.stringContaining("generation"),
connectionLost: false,
})
rerender({ deliveryGeneration: 1 })
await oldRejection
expect(MockWebSocket.instances).toHaveLength(1)
const replacementDelivery = result.current.sendChatMessage("same text")
expect(socket.send).toHaveBeenCalledTimes(2)
const replacementFrame = JSON.parse(socket.send.mock.calls[1][0])
act(() => socket.receive({
type: "message_accepted",
client_message_id: replacementFrame.client_message_id,
}))
await expect(replacementDelivery).resolves.toMatchObject({
client_message_id: replacementFrame.client_message_id,
})
})
it("commits the generation fence before a consumer layout effect can acknowledge", async () => {
const connection = sessionConnection()
const { result, rerender } = renderHook(
({ acknowledgeOnCommit, deliveryGeneration }) => {
const webSocket = useWebSocket({
connection,
deliveryGeneration,
})
useLayoutEffect(() => {
if (!acknowledgeOnCommit) return
MockWebSocket.instances[0]?.receive({
type: "message_accepted",
client_message_id: "layout-fence-id",
})
}, [acknowledgeOnCommit, deliveryGeneration])
return webSocket
},
{
initialProps: {
acknowledgeOnCommit: false,
deliveryGeneration: 0,
},
},
)
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
socket.protocol = "xagent-session-v1"
act(() => socket.open())
const oldDelivery = result.current.sendChatMessage(
"old generation",
undefined,
false,
"layout-fence-id",
)
const outcome = oldDelivery.then(
() => "resolved",
error => `rejected:${(error as Error).message}`,
)
rerender({
acknowledgeOnCommit: true,
deliveryGeneration: 1,
})
expect(await outcome).toContain("generation")
expect(MockWebSocket.instances).toHaveLength(1)
})
it("keeps duplicate detection local to each hook", async () => {
const first = renderHook(() => useWebSocket({
connection: sessionConnection({ identity: "shared-identity" }),
}))
const second = renderHook(() => useWebSocket({
connection: sessionConnection({ identity: "shared-identity" }),
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(2))
const firstSocket = MockWebSocket.instances[0]
const secondSocket = MockWebSocket.instances[1]
firstSocket.protocol = "xagent-session-v1"
secondSocket.protocol = "xagent-session-v1"
act(() => {
firstSocket.open()
secondSocket.open()
})
const firstDelivery = first.result.current.sendChatMessage("same")
const secondDelivery = second.result.current.sendChatMessage("same")
expect(firstSocket.send).toHaveBeenCalledOnce()
expect(secondSocket.send).toHaveBeenCalledOnce()
const firstFrame = JSON.parse(firstSocket.send.mock.calls[0][0])
const secondFrame = JSON.parse(secondSocket.send.mock.calls[0][0])
act(() => {
firstSocket.receive({
type: "message_accepted",
client_message_id: firstFrame.client_message_id,
})
secondSocket.receive({
type: "message_accepted",
client_message_id: secondFrame.client_message_id,
})
})
await Promise.all([firstDelivery, secondDelivery])
})
it("uses the current socket for retained raw protocol sends", async () => {
const { result, rerender } = renderHook(
({ connection }) => useWebSocket({ connection }),
{ initialProps: { connection: sessionConnection() } },
)
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const oldSocket = MockWebSocket.instances[0]
oldSocket.protocol = "xagent-session-v1"
act(() => oldSocket.open())
const sendRaw = result.current.sendMessage
rerender({ connection: sessionConnection({ identity: "widget-session:2" }) })
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(2))
const currentSocket = MockWebSocket.instances[1]
currentSocket.protocol = "xagent-session-v1"
act(() => currentSocket.open())
act(() => sendRaw({ type: "new_conversation" }))
expect(oldSocket.send).not.toHaveBeenCalled()
expect(currentSocket.send).toHaveBeenCalledWith(
JSON.stringify({ type: "new_conversation" }),
)
})
it("fails taskless file delivery before any upload", async () => {
const uploadFiles = vi.fn()
const { result } = renderHook(() => useWebSocket({
connection: sessionConnection(),
uploadFiles,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
socket.protocol = "xagent-session-v1"
act(() => socket.open())
const file = new File(["secret"], "secret.txt", { type: "text/plain" })
await expect(
result.current.sendChatMessage("with file", [file])
).rejects.toMatchObject({
message: "File delivery is not supported for this connection.",
disposition: "not_sent",
})
expect(uploadFiles).not.toHaveBeenCalled()
expect(socket.send).not.toHaveBeenCalled()
})
describe("Session chat frames with file ids", () => {
const FILE_A = "0b1e5c9e-3f1a-4a63-9b0e-6c1d2f3a4b5c"
const FILE_B = "7d2f0c1a-8b3e-4c55-a1f0-2e9d4b6c8a10"
const openSessionSocket = async () => {
const hook = renderHook(() => useWebSocket({ connection: sessionConnection() }))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
socket.protocol = "xagent-session-v1"
act(() => socket.open())
return { ...hook, socket }
}
const frames = (socket: MockWebSocket) =>
socket.send.mock.calls.map((call) => JSON.parse(call[0] as string) as Record<string, unknown>)
it("sends file_ids and client_message_id without files or a task id", async () => {
const { result, socket } = await openSessionSocket()
const delivery = result.current.sendChatMessage(
"see attached", undefined, false, "msg-1", undefined,
{ fileIds: [FILE_A, FILE_B], maxFileIds: 5 },
)
const frame = frames(socket)[0]
expect(frame).toMatchObject({
type: "chat",
message: "see attached",
client_message_id: "msg-1",
file_ids: [FILE_A, FILE_B],
})
expect(frame).not.toHaveProperty("files")
expect(frame).not.toHaveProperty("task_id")
expect(frame).not.toHaveProperty("request_id")
act(() => socket.receive({ type: "message_accepted", client_message_id: "msg-1" }))
await delivery
})
it.each([
["no attachments argument", undefined],
["an empty file id list", { fileIds: [] as string[], maxFileIds: 5 }],
])("omits the file_ids key for %s", async (_label, attachments) => {
const { result, socket } = await openSessionSocket()
const delivery = result.current.sendChatMessage(
"plain", undefined, false, "msg-2", undefined, attachments,
)
expect(frames(socket)[0]).not.toHaveProperty("file_ids")
act(() => socket.receive({ type: "message_accepted", client_message_id: "msg-2" }))
await delivery
})
it("refuses to send file ids together with a request id", async () => {
const { result, socket } = await openSessionSocket()
await expect(result.current.sendChatMessage(
"answer", undefined, false, "msg-3", "request-1",
{ fileIds: [FILE_A], maxFileIds: 5 },
)).rejects.toMatchObject({ disposition: "not_sent" })
expect(socket.send).not.toHaveBeenCalled()
})
it("refuses more file ids than the advertised limit", async () => {
const { result, socket } = await openSessionSocket()
await expect(result.current.sendChatMessage(
"too many", undefined, false, "msg-4", undefined,
{ fileIds: [FILE_A, FILE_B], maxFileIds: 1 },
)).rejects.toMatchObject({ disposition: "not_sent" })
expect(socket.send).not.toHaveBeenCalled()
})
it("refuses file ids when the caller supplies no limit", async () => {
const { result, socket } = await openSessionSocket()
await expect(result.current.sendChatMessage(
"no limit", undefined, false, "msg-5", undefined, { fileIds: [FILE_A] },
)).rejects.toMatchObject({ disposition: "not_sent" })
expect(socket.send).not.toHaveBeenCalled()
})
it.each(["file-1", FILE_A.toUpperCase()])("refuses the malformed file id %s", async (fileId) => {
const { result, socket } = await openSessionSocket()
await expect(result.current.sendChatMessage(
"bad id", undefined, false, "msg-6", undefined, { fileIds: [fileId], maxFileIds: 5 },
)).rejects.toMatchObject({ disposition: "not_sent" })
expect(socket.send).not.toHaveBeenCalled()
})
it("refuses file ids on a connection that carries a task id", async () => {
const { result } = renderHook(() => useWebSocket({ url: "ws://localhost", taskId: 7 }))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
await expect(result.current.sendChatMessage(
"task bound", undefined, false, "msg-7", undefined, { fileIds: [FILE_A], maxFileIds: 5 },
)).rejects.toMatchObject({ disposition: "not_sent" })
expect(socket.send).not.toHaveBeenCalled()
})
it("sends identical file_ids when the same client message id is sent again", async () => {
const { result, socket } = await openSessionSocket()
const attachments = { fileIds: [FILE_A, FILE_B], maxFileIds: 5 }
const first = result.current.sendChatMessage("again", undefined, false, "msg-8", undefined, attachments)
act(() => socket.receive({
type: "message_rejected",
client_message_id: "msg-8",
error_code: "message_attachment_unavailable",
}))
await expect(first).rejects.toThrow()
const second = result.current.sendChatMessage("again", undefined, true, "msg-8", undefined, attachments)
const [firstFrame, secondFrame] = frames(socket)
expect(secondFrame.file_ids).toEqual(firstFrame.file_ids)
expect(secondFrame.file_ids).toEqual([FILE_A, FILE_B])
act(() => socket.receive({ type: "message_accepted", client_message_id: "msg-8" }))
await second
})
})
describe("chat frames with a conversation source", () => {
const SOURCE_REFUSALS = {
connection: "A conversation source is not supported for this connection.",
request: "A conversation source cannot accompany an answer to a request.",
value: "Message not sent: the conversation source is not valid.",
} as const
const SOURCES = [undefined, 1, 2147483647, 0, -1, 2147483648, 1.5, Number.NaN] as const
const CONNECTIONS = ["omit", "required"] as const
const REQUEST_IDS = [undefined, "request-1"] as const
const CASES = SOURCES.flatMap((source) => CONNECTIONS.flatMap((mode) => (
REQUEST_IDS.map((requestId) => [source, mode, requestId] as const)
)))
const openSocket = async (mode: "omit" | "required") => {
const hook = mode === "omit"
? renderHook(() => useWebSocket({ connection: sessionConnection() }))
: renderHook(() => useWebSocket({ url: "ws://localhost", taskId: 7 }))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
if (mode === "omit") socket.protocol = "xagent-session-v1"
act(() => socket.open())
return { ...hook, socket }
}
// The refusal a frame shape meets first, in the order the checks run.
const expectedRefusal = (
source: number | undefined,
mode: "omit" | "required",
requestId: string | undefined,
): string | null => {
if (source === undefined) return null
if (mode !== "omit") return SOURCE_REFUSALS.connection
if (requestId) return SOURCE_REFUSALS.request
if (!Number.isInteger(source) || source < 1 || source > 2147483647) return SOURCE_REFUSALS.value
return null
}
it.each(CASES)(
"handles source %s on a %s connection with request id %s",
async (source, mode, requestId) => {
const { result, socket } = await openSocket(mode)
const clientMessageId = "msg-source"
const refusal = expectedRefusal(source, mode, requestId)
const delivery = source === undefined
? result.current.sendChatMessage("continue", undefined, false, clientMessageId, requestId)
: result.current.sendChatMessage(
"continue", undefined, false, clientMessageId, requestId, undefined, source,
)
if (refusal) {
const outcome = delivery.then(() => "delivered", (error: unknown) => error)
// Checked before awaiting: a frame that went out would wait for an ack.
await act(async () => {})
expect(socket.send).not.toHaveBeenCalled()
expect(await outcome).toMatchObject({ message: refusal, disposition: "not_sent" })
return
}
expect(socket.send).toHaveBeenCalledTimes(1)
const raw = socket.send.mock.calls[0][0] as string
const timezone = resolveReportedTimezone()
// The frame a send without a source has always produced, key order included.
const unchanged: Record<string, unknown> = {
type: "chat",
message: "continue",
client_message_id: clientMessageId,
...(requestId ? { request_id: requestId } : {}),
...(timezone ? { context: { timezone } } : {}),
...(mode === "required" ? { task_id: 7 } : {}),
}
if (source === undefined) {
expect(raw).toBe(JSON.stringify(unchanged))
} else {
const frame = JSON.parse(raw) as Record<string, unknown>
expect(frame.source_task_id).toBe(source)
const rest = { ...frame }
delete rest.source_task_id
expect(rest).toStrictEqual(unchanged)
}
act(() => socket.receive({ type: "message_accepted", client_message_id: clientMessageId }))
await delivery
},
)
it("sends file ids and a conversation source in the same frame", async () => {
const fileId = "0b1e5c9e-3f1a-4a63-9b0e-6c1d2f3a4b5c"
const { result, socket } = await openSocket("omit")
const delivery = result.current.sendChatMessage(
"with both", undefined, false, "msg-both", undefined, { fileIds: [fileId], maxFileIds: 5 }, 101,
)
const frame = JSON.parse(socket.send.mock.calls[0][0] as string) as Record<string, unknown>
expect(frame).toMatchObject({ file_ids: [fileId], source_task_id: 101 })
act(() => socket.receive({ type: "message_accepted", client_message_id: "msg-both" }))
await delivery
})
})
it("rejects a coded unsuccessful 2xx batch upload before sending chat", async () => {
const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
new Response(JSON.stringify({
success: false,
error_code: "upload_too_large",
detail: "private proxy detail",
}), {
status: 200,
headers: { "Content-Type": "application/json" },
}),
)
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
await expect(result.current.sendChatMessage(
"with file",
[new File(["data"], "data.txt")],
)).rejects.toMatchObject({
errorCode: "upload_too_large",
message: "File is too large. Please reduce the upload size and try again.",
userFacing: true,
})
expect(socket.send).not.toHaveBeenCalled()
fetchMock.mockRestore()
})
it("rejects a malformed oversized upload result before sending chat", async () => {
const fetchMock = vi.spyOn(globalThis, "fetch").mockResolvedValue(
new Response(JSON.stringify({
success: true,
files: [
{ file_id: 123, filename: "bad.txt" },
{ file_id: "file-2", filename: "second.txt" },
{ file_id: "file-3", filename: "extra.txt" },
],
}), {
status: 200,
headers: { "Content-Type": "application/json" },
}),
)
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const outcome = result.current.sendChatMessage(
"with files",
[
new File(["one"], "first.txt"),
new File(["two"], "second.txt"),
],
).then(
() => null,
error => error,
)
await waitFor(() => expect(fetchMock).toHaveBeenCalledOnce())
await expect(outcome).resolves.toMatchObject({
errorCode: "upload_failed",
userFacing: true,
})
expect(socket.send).not.toHaveBeenCalled()
fetchMock.mockRestore()
})
it("rejects an incomplete custom upload result before sending chat", async () => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
uploadFiles: vi.fn().mockResolvedValue([]),
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
await expect(result.current.sendChatMessage(
"with file",
[new File(["data"], "data.txt")],
)).rejects.toMatchObject({
errorCode: "upload_failed",
userFacing: true,
})
expect(socket.send).not.toHaveBeenCalled()
})
it.each([
{
name: "blank",
uploadResult: [{ file_id: " " }, { file_id: "file-2" }],
},
{
name: "duplicate",
uploadResult: [{ file_id: "file-1" }, { file_id: " file-1 " }],
},
])("rejects $name custom upload identifiers before sending chat", async ({ uploadResult }) => {
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
uploadFiles: vi.fn().mockResolvedValue(uploadResult),
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
await expect(result.current.sendChatMessage(
"with files",
[
new File(["first"], "first.txt"),
new File(["second"], "second.txt"),
],
)).rejects.toMatchObject({
errorCode: "upload_failed",
userFacing: true,
})
expect(socket.send).not.toHaveBeenCalled()
})
it("claims a client message id before awaiting its upload", async () => {
const upload = deferred<Array<{ file_id: string }>>()
const uploadFiles = vi.fn(() => upload.promise)
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
uploadFiles,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const file = new File(["data"], "data.txt")
const first = result.current.sendChatMessage(
"first owner",
[file],
false,
"shared-upload-id",
)
const second = result.current.sendChatMessage(
"second owner",
[file],
false,
"shared-upload-id",
)
const secondOutcome = second.then(
() => "resolved",
error => `rejected:${(error as Error).message}`,
)
await act(async () => {
upload.resolve([{ file_id: "uploaded-file" }])
await Promise.resolve()
})
act(() => socket.receive({
type: "message_accepted",
client_message_id: "shared-upload-id",
}))
await expect(first).resolves.toMatchObject({
client_message_id: "shared-upload-id",
})
expect(await secondOutcome).toContain("already pending")
expect(uploadFiles).toHaveBeenCalledOnce()
expect(socket.send).toHaveBeenCalledOnce()
})
it("releases an upload claim after preparation fails", async () => {
const uploadFiles = vi.fn()
.mockRejectedValueOnce(new Error("upload failed"))
.mockResolvedValueOnce([{ file_id: "uploaded-file" }])
const { result } = renderHook(() => useWebSocket({
url: "ws://localhost",
taskId: 1,
uploadFiles,
}))
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const file = new File(["data"], "data.txt")
await expect(result.current.sendChatMessage(
"first attempt",
[file],
false,
"retry-upload-id",
)).rejects.toThrow("upload failed")
const retry = result.current.sendChatMessage(
"retry",
[file],
false,
"retry-upload-id",
)
await waitFor(() => expect(socket.send).toHaveBeenCalledOnce())
act(() => socket.receive({
type: "message_accepted",
client_message_id: "retry-upload-id",
}))
await expect(retry).resolves.toMatchObject({
client_message_id: "retry-upload-id",
})
expect(uploadFiles).toHaveBeenCalledTimes(2)
})
it("rejects replaced upload preparation promptly and preserves the replacement claim", async () => {
const oldUpload = deferred<Array<{ file_id: string }>>()
const replacementUpload = deferred<Array<{ file_id: string }>>()
const unexpectedThirdUpload = deferred<Array<{ file_id: string }>>()
const uploadFiles = vi.fn()
.mockReturnValueOnce(oldUpload.promise)
.mockReturnValueOnce(replacementUpload.promise)
.mockReturnValueOnce(unexpectedThirdUpload.promise)
const { result, rerender } = renderHook(
({ taskId }) => useWebSocket({
url: "ws://localhost",
taskId,
uploadFiles,
}),
{ initialProps: { taskId: 1 } },
)
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const oldSocket = MockWebSocket.instances[0]
act(() => oldSocket.open())
const file = new File(["data"], "data.txt")
let oldSettled = false
const oldOutcome = result.current.sendChatMessage(
"old owner",
[file],
false,
"reclaimed-upload-id",
).then(
() => "resolved",
error => `rejected:${(error as Error).message}`,
).finally(() => {
oldSettled = true
})
rerender({ taskId: 2 })
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(2))
const replacementSocket = MockWebSocket.instances[1]
act(() => replacementSocket.open())
const replacementDelivery = result.current.sendChatMessage(
"replacement owner",
[file],
false,
"reclaimed-upload-id",
)
await act(async () => {
await Promise.resolve()
})
const oldSettledBeforeUploadCompleted = oldSettled
await act(async () => {
oldUpload.resolve([{ file_id: "stale-file" }])
await Promise.resolve()
})
const duplicateOutcome = result.current.sendChatMessage(
"must not steal replacement",
[file],
false,
"reclaimed-upload-id",
).then(
() => "resolved",
error => `rejected:${(error as Error).message}`,
)
await act(async () => {
replacementUpload.resolve([{ file_id: "replacement-file" }])
unexpectedThirdUpload.resolve([{ file_id: "unexpected-file" }])
await Promise.resolve()
})
act(() => replacementSocket.receive({
type: "message_accepted",
client_message_id: "reclaimed-upload-id",
}))
expect(oldSettledBeforeUploadCompleted).toBe(true)
expect(await oldOutcome).toContain("connection changed")
expect(await duplicateOutcome).toContain("already pending")
expect(uploadFiles).toHaveBeenCalledTimes(2)
expect(oldSocket.send).not.toHaveBeenCalled()
expect(replacementSocket.send).toHaveBeenCalledOnce()
await expect(replacementDelivery).resolves.toMatchObject({
client_message_id: "reclaimed-upload-id",
})
})
it("releases upload preparation on a delivery generation change", async () => {
const oldUpload = deferred<Array<{ file_id: string }>>()
const currentUpload = deferred<Array<{ file_id: string }>>()
const uploadFiles = vi.fn()
.mockReturnValueOnce(oldUpload.promise)
.mockReturnValueOnce(currentUpload.promise)
const { result, rerender } = renderHook(
({ deliveryGeneration }) => useWebSocket({
url: "ws://localhost",
taskId: 1,
deliveryGeneration,
uploadFiles,
}),
{ initialProps: { deliveryGeneration: 0 } },
)
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const socket = MockWebSocket.instances[0]
act(() => socket.open())
const file = new File(["data"], "data.txt")
let oldSettled = false
const oldOutcome = result.current.sendChatMessage(
"old generation",
[file],
false,
"generation-upload-id",
).then(
() => "resolved",
error => `rejected:${(error as Error).message}`,
).finally(() => {
oldSettled = true
})
rerender({ deliveryGeneration: 1 })
const currentDelivery = result.current.sendChatMessage(
"current generation",
[file],
false,
"generation-upload-id",
)
await act(async () => {
await Promise.resolve()
})
const oldSettledBeforeUploadCompleted = oldSettled
await act(async () => {
oldUpload.resolve([{ file_id: "stale-file" }])
currentUpload.resolve([{ file_id: "current-file" }])
await Promise.resolve()
})
act(() => socket.receive({
type: "message_accepted",
client_message_id: "generation-upload-id",
}))
expect(oldSettledBeforeUploadCompleted).toBe(true)
expect(await oldOutcome).toContain("generation")
expect(uploadFiles).toHaveBeenCalledTimes(2)
await expect(currentDelivery).resolves.toMatchObject({
client_message_id: "generation-upload-id",
})
})
it("fails closed when an upload completes after its connection was replaced", async () => {
let finishUpload!: (files: Array<{ file_id: string }>) => void
const uploadFiles = vi.fn(() => new Promise<Array<{ file_id: string }>>((resolve) => {
finishUpload = resolve
}))
const { result, rerender } = renderHook(
({ taskId }) => useWebSocket({
url: "ws://localhost",
taskId,
uploadFiles,
}),
{ initialProps: { taskId: 1 } },
)
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(1))
const oldSocket = MockWebSocket.instances[0]
act(() => oldSocket.open())
const delivery = result.current.sendChatMessage(
"upload",
[new File(["data"], "data.txt")],
)
const rejection = expect(delivery).rejects.toThrow("connection changed")
await waitFor(() => expect(uploadFiles).toHaveBeenCalledOnce())
rerender({ taskId: 2 })
await waitFor(() => expect(MockWebSocket.instances).toHaveLength(2))
await act(async () => {
finishUpload([{ file_id: "uploaded-file" }])
await Promise.resolve()
})
expect(oldSocket.send).not.toHaveBeenCalled()
await rejection
})
describe("resending after a lost connection", () => {
const mountOpen = () => {
const hook = renderHook(
({ taskId }) => useWebSocket({ url: "ws://localhost", taskId }),
{ initialProps: { taskId: 1 } },
)
act(() => MockWebSocket.instances[0].open())
return hook
}
it.each([
["a transport error", true, () => MockWebSocket.instances[0].triggerError()],
["a caller disconnect", false, (hook: ReturnType<typeof mountOpen>) => hook.result.current.disconnect()],
["an unmount", false, (hook: ReturnType<typeof mountOpen>) => hook.unmount()],
] as const)("marks a pending delivery ended by %s as connectionLost=%s", async (_name, connectionLost, end) => {
vi.spyOn(console, "error").mockImplementation(() => {})
const hook = mountOpen()
const outcome = expect(hook.result.current.sendChatMessage("hi")).rejects.toMatchObject({ connectionLost })
act(() => end(hook))
await outcome
})
it("replacing a closing owner rejects its pending delivery as connectionLost", async () => {
const hook = mountOpen()
const outcome = expect(hook.result.current.sendChatMessage("hi")).rejects.toMatchObject({ connectionLost: true })
// Closed from outside without an onclose event.
MockWebSocket.instances[0].readyState = MockWebSocket.CLOSED
act(() => hook.result.current.connect())
await outcome
})
it.each([
["reuses the upload for the same task", 1, "t1", 1],
["uploads again for another task", 2, "t1", 2],
["uploads again for another login", 1, "t2", 2],
] as const)("a same-id retry %s", async (_name, retryTaskId, retryToken, uploads) => {
const uploadFiles = vi.fn(async () => [{ file_id: "f1" }])
const files = [new File(["a"], "a.txt")]
const hook = renderHook(
({ taskId, token }) => useWebSocket({ url: "ws://localhost", taskId, token, uploadFiles }),
{ initialProps: { taskId: 1, token: "t1" } },
)
const [first] = MockWebSocket.instances
act(() => first.open())
const lost = hook.result.current.sendChatMessage("hi", files, false, "retry-id").catch(() => undefined)
await waitFor(() => expect(first.send).toHaveBeenCalledOnce())
// A clean close schedules no automatic reconnect, so only the explicit
// connect or descriptor change below creates the second socket.
act(() => first.triggerClose(1000))
await lost
if (retryTaskId === 1 && retryToken === "t1") act(() => hook.result.current.connect())
else hook.rerender({ taskId: retryTaskId, token: retryToken })
const second = MockWebSocket.instances[1]
act(() => second.open())
void hook.result.current.sendChatMessage("hi", files, false, "retry-id").catch(() => undefined)
await waitFor(() => expect(second.send).toHaveBeenCalledOnce())
expect(uploadFiles).toHaveBeenCalledTimes(uploads)
expect(second.send.mock.calls[0][0]).toBe(first.send.mock.calls[0][0].replace('"task_id":1', `"task_id":${retryTaskId}`))
})
it("keeps an earlier unknown-outcome attempt's upload when a later same-id attempt is not sent", async () => {
let uploadCount = 0
const uploadFiles = vi.fn(async () => [{ file_id: `f${++uploadCount}` }])
const files = [new File(["a"], "a.txt")]
const hook = renderHook(() => useWebSocket({ url: "ws://localhost", taskId: 1, token: "t1", uploadFiles }))
const [first] = MockWebSocket.instances
act(() => first.open())
const lost = hook.result.current.sendChatMessage("hi", files, false, "retry-id").catch(() => undefined)
await waitFor(() => expect(first.send).toHaveBeenCalledOnce())
act(() => first.triggerClose(1000))
await lost
act(() => hook.result.current.connect())
const second = MockWebSocket.instances[1]
act(() => second.open())
second.send.mockImplementationOnce(() => { throw new Error("send failed") })
await expect(hook.result.current.sendChatMessage("hi", files, false, "retry-id"))
.rejects.toMatchObject({ disposition: "not_sent" })
void hook.result.current.sendChatMessage("hi", files, false, "retry-id").catch(() => undefined)
await waitFor(() => expect(second.send).toHaveBeenCalledTimes(2))
expect(uploadFiles).toHaveBeenCalledOnce()
expect(second.send.mock.calls[1][0]).toBe(first.send.mock.calls[0][0])
})
it("keeps an earlier unknown-outcome attempt's upload when a later same-id attempt fails while preparing", async () => {
let uploadCount = 0
const uploadFiles = vi.fn(async () => [{ file_id: `f${++uploadCount}` }])
const files = [new File(["a"], "a.txt")]
const hook = renderHook(() => useWebSocket({ url: "ws://localhost", taskId: 1, token: "t1", uploadFiles }))
const [first] = MockWebSocket.instances
act(() => first.open())
const lost = hook.result.current.sendChatMessage("hi", files, false, "retry-id").catch(() => undefined)
await waitFor(() => expect(first.send).toHaveBeenCalledOnce())
act(() => first.triggerClose(1000))
await lost
act(() => hook.result.current.connect())
const second = MockWebSocket.instances[1]
act(() => second.open())
// The cached upload holds one file id for two files, so preparation fails.
const twoFiles = [new File(["a"], "a.txt"), new File(["b"], "b.txt")]
await expect(hook.result.current.sendChatMessage("hi", twoFiles, false, "retry-id"))
.rejects.toMatchObject({ disposition: "not_sent" })
void hook.result.current.sendChatMessage("hi", files, false, "retry-id").catch(() => undefined)
await waitFor(() => expect(second.send).toHaveBeenCalledOnce())
expect(uploadFiles).toHaveBeenCalledOnce()
expect(second.send.mock.calls[0][0]).toBe(first.send.mock.calls[0][0])
})
it.each([
["an acceptance", true, { type: "message_accepted" }],
["a rejection that was not accepted", true, { type: "message_rejected", rejection_outcome: "not_accepted" }],
["a rejection with an unknown outcome", false, { type: "message_rejected" }],
] as const)("a same-id send after %s uploads again: %s", async (_name, uploadsAgain, ack) => {
const uploadFiles = vi.fn(async () => [{ file_id: "f1" }])
const files = [new File(["a"], "a.txt")]
const hook = renderHook(() => useWebSocket({ url: "ws://localhost", taskId: 1, token: "t1", uploadFiles }))
const [socket] = MockWebSocket.instances
act(() => socket.open())
const settled = hook.result.current.sendChatMessage("hi", files, false, "ack-id").catch(() => undefined)
await waitFor(() => expect(socket.send).toHaveBeenCalledOnce())
act(() => socket.receive({ ...ack, client_message_id: "ack-id" }))
await settled
void hook.result.current.sendChatMessage("hi", files, false, "ack-id").catch(() => undefined)
await waitFor(() => expect(socket.send).toHaveBeenCalledTimes(2))
expect(uploadFiles).toHaveBeenCalledTimes(uploadsAgain ? 2 : 1)
})
it("treats the same user with another session id as another login", () => {
const hook = renderHook(() => useWebSocket({ url: "ws://localhost", taskId: 1 }))
const before = hook.result.current.getLoginIdentity()
authState.session = { ...authState.session, sessionId: "other-lineage" }
hook.rerender()
expect(hook.result.current.getLoginIdentity()).not.toBe(before)
})
it("login identity never carries credentials and moves only with the principal", () => {
const external = (token: string): WebSocketConnection => ({
identity: "legacy-task:7",
url: "ws://h/api/widget/chat/ws/7",
loginToken: token,
taskId: 7,
chatTaskIdMode: "required",
credentialOwner: { kind: "external" },
})
const hook = renderHook(
({ connection }) => useWebSocket({ connection }),
{ initialProps: { connection: external("secret-abc") }, wrapper: StrictMode },
)
const identity = () => hook.result.current.getLoginIdentity()
const first = identity()
expect(first).toMatch(/^external:\d+$/)
expect(first).not.toMatch(/secret-abc|token|ws:\/\//)
hook.rerender({ connection: external("secret-xyz") })
const second = identity()
expect(second).not.toMatch(/secret|token|ws:\/\//)
// One credential change moves the generation by exactly one, even when React renders twice.
expect(Number(second?.split(":")[1]) - Number(first?.split(":")[1])).toBe(1)
hook.rerender({ connection: external("secret-xyz") })
expect(identity()).toBe(second)
})
})
describe("dead-connection detection and reconnect", () => {
const ACK = { type: "connection_capabilities", capabilities: ["heartbeat"] }
const HEARTBEAT = { type: "heartbeat" }
// Synchronous on purpose: React's async act helper draws from Math.random,
// which would consume the values the jitter tests pin.
const advance = (ms: number) => act(() => {
vi.advanceTimersByTime(ms)
})
const socketAt = (index: number) => MockWebSocket.instances[index]
const expectReconnectAfter = (delay: number, margin = 1) => {
const count = MockWebSocket.instances.length
advance(delay - margin)
expect(MockWebSocket.instances).toHaveLength(count)
advance(margin)
expect(MockWebSocket.instances).toHaveLength(count + 1)
}
const mountChat = (extra: Record<string, unknown> = {}) => renderHook(
(props: Record<string, unknown>) => useWebSocket({
url: "ws://localhost",
taskId: 7,
...extra,
...props,
}),
{ initialProps: {} as Record<string, unknown> },
)
beforeEach(() => {
vi.useFakeTimers()
})
it("keeps the widget.js stable window at twice the dead threshold", () => {
const widgetScript = readFileSync(resolve(process.cwd(), "public/widget.js"), "utf8")
const stableWindow = Number(/var SESSION_STABLE_CONNECTION_MS = (\d+);/.exec(widgetScript)?.[1])
expect(stableWindow).toBe(2 * DEAD_AFTER_MS)
})
describe("dead rule", () => {
it.each([
["a heartbeat frame", (socket: MockWebSocket) => socket.receive(HEARTBEAT)],
["a frame that failed to parse", (socket: MockWebSocket) => socket.onmessage?.({ data: "{not json" } as MessageEvent)],
] as const)("keeps the connection 29,999 ms after %s", (_name, sendFrame) => {
vi.spyOn(console, "error").mockImplementation(() => {})
const hook = mountChat()
const socket = socketAt(0)
act(() => socket.open())
act(() => socket.receive(ACK))
advance(15_000)
act(() => sendFrame(socket))
advance(29_999)
expect(socket.close).not.toHaveBeenCalled()
expect(hook.result.current.connectionPhase).toBe("connected")
})
it("retires at 30,000 ms, reports the stream as unavailable, and hides liveness frames", () => {
const onMessage = vi.fn()
const hook = mountChat({ onMessage })
const socket = socketAt(0)
act(() => socket.open())
act(() => {
socket.receive(ACK)
socket.receive({ type: "trace_event", task_id: 7, stream_run_id: "run-1", data: {} })
socket.receive(HEARTBEAT)
})
advance(30_000)
expect(socket.close).toHaveBeenCalledWith(1000, "Connection liveness timeout")
expect(hook.result.current.isConnected).toBe(false)
const types = onMessage.mock.calls.map(([message]) => message.type)
expect(types).not.toContain("connection_capabilities")
expect(types).not.toContain("heartbeat")
expect(onMessage).toHaveBeenCalledWith(expect.objectContaining({ type: "stream_unavailable", task_id: 7 }))
})
it.each([
["no capability array", "heartbeat"],
["other capabilities", ["other"]],
])("does not enable the rule when the acknowledgement lists %s", (_name, capabilities) => {
const hook = mountChat()
const socket = socketAt(0)
act(() => socket.open())
act(() => socket.receive({ type: "connection_capabilities", capabilities }))
advance(120_000)
expect(socket.close).not.toHaveBeenCalled()
expect(hook.result.current.connectionPhase).toBe("connected")
})
})
describe("connection capabilities", () => {
it.each([
["heartbeat", ["heartbeat"], ["heartbeat"], true],
["heartbeat and attach completion", ["heartbeat", "conversation_attached"], ["heartbeat", "conversation_attached"], true],
["attach completion only", ["conversation_attached"], ["conversation_attached"], false],
["an empty list", [], [], false],
["no capability array", "heartbeat", [], false],
["non-string entries", [1, "conversation_attached", null], ["conversation_attached"], false],
] as const)("reports connection capabilities to the caller: %s", (_name, capabilities, reported, heartbeat) => {
const onConnectionCapabilities = vi.fn()
const onMessage = vi.fn()
mountChat({ onConnectionCapabilities, onMessage })
const socket = socketAt(0)
act(() => socket.open())
act(() => socket.receive({ type: "connection_capabilities", capabilities }))
expect(onConnectionCapabilities.mock.calls).toEqual([[reported]])
expect(onMessage.mock.calls.map(([message]) => message.type)).not.toContain("connection_capabilities")
advance(DEAD_AFTER_MS)
if (heartbeat) {
expect(socket.close).toHaveBeenCalledWith(1000, "Connection liveness timeout")
} else {
expect(socket.close).not.toHaveBeenCalled()
}
})
it("reports connection capabilities to the caller only for the current socket", () => {
vi.spyOn(Math, "random").mockReturnValue(0.5)
const onConnectionCapabilities = vi.fn()
mountChat({ onConnectionCapabilities })
const first = socketAt(0)
act(() => first.open())
act(() => first.triggerClose(1006))
advance(RECONNECT_BASE_DELAY_MS)
const second = socketAt(1)
act(() => second.open())
act(() => first.receive({ type: "connection_capabilities", capabilities: ["heartbeat", "conversation_attached"] }))
expect(onConnectionCapabilities).not.toHaveBeenCalled()
act(() => second.receive({ type: "connection_capabilities", capabilities: ["heartbeat"] }))
expect(onConnectionCapabilities.mock.calls).toEqual([[["heartbeat"]]])
})
})
it("reconnect chain backs off to the cap and never gives up", () => {
const random = vi.spyOn(Math, "random")
.mockReturnValueOnce(0)
.mockReturnValueOnce(0.9999)
.mockReturnValue(0.5)
const hook = mountChat()
const phase = () => hook.result.current.connectionPhase
const first = socketAt(0)
act(() => first.open())
act(() => first.receive(ACK))
expect(phase()).toBe("connected")
act(() => first.triggerClose(1006))
// Only the retry timer remains: the dead-connection timer is gone.
expect(vi.getTimerCount()).toBe(1)
expect(phase()).toBe("reconnecting")
expectReconnectAfter(800)
expect(phase()).toBe("reconnecting")
// Reconnects fail by error, handshake timeout, 1006 and error.
act(() => socketAt(1).triggerError())
expect(phase()).toBe("reconnecting")
expectReconnectAfter(1_800)
advance(9_998)
expect(phase()).toBe("reconnecting")
advance(2)
expect(phase()).toBe("reconnecting")
expectReconnectAfter(2_250)
act(() => socketAt(3).triggerClose(1006))
expectReconnectAfter(3_375)
act(() => socketAt(4).triggerError())
expectReconnectAfter(5_063)
// Keep failing well past the old five-attempt budget: the delay grows
// by 1.5x until it settles at the five-minute cap.
const delays: number[] = []
for (let attempt = 6; attempt <= 20; attempt++) {
act(() => socketAt(attempt - 1).triggerError())
const delay = Math.round(RECONNECT_BASE_DELAY_MS * 1.5 ** (attempt - 1))
expectReconnectAfter(Math.min(delay, RECONNECT_MAX_DELAY_MS))
expect(phase()).toBe("reconnecting")
delays.push(Math.min(delay, RECONNECT_MAX_DELAY_MS))
}
expect(delays.at(-1)).toBe(RECONNECT_MAX_DELAY_MS)
expect(delays.filter(delay => delay === RECONNECT_MAX_DELAY_MS).length).toBeGreaterThan(1)
// The server comes back: the chain ends connected.
act(() => socketAt(20).open())
expect(phase()).toBe("connected")
expect(MockWebSocket.instances).toHaveLength(21)
expect(random).toHaveBeenCalledTimes(20)
})
it("recovers a page left open across a two-minute backend restart", () => {
vi.spyOn(Math, "random").mockReturnValue(0.5)
const onConnect = vi.fn()
const hook = mountChat({ onConnect })
act(() => socketAt(0).open())
act(() => socketAt(0).receive(ACK))
expect(onConnect).toHaveBeenCalledTimes(1)
// The backend is killed: 1006, then nginx answers every upgrade with 502.
const restartMs = 130_000
const downSince = Date.now()
act(() => socketAt(0).triggerClose(1006, ""))
while (Date.now() - downSince < restartMs) {
const count = MockWebSocket.instances.length
advance(1_000)
if (MockWebSocket.instances.length > count) {
act(() => socketAt(count).triggerError())
}
expect(hook.result.current.connectionPhase).toBe("reconnecting")
}
// The backend is back: the next scheduled attempt succeeds on its own,
// well within a minute of the restart ending.
const count = MockWebSocket.instances.length
const backSince = Date.now()
while (MockWebSocket.instances.length === count) advance(1_000)
expect(Date.now() - backSince).toBeLessThan(60_000)
act(() => socketAt(count).open())
expect(hook.result.current.connectionPhase).toBe("connected")
// onConnect is the caller's cue to reload history and resynchronize.
expect(onConnect).toHaveBeenCalledTimes(2)
})
describe("close codes", () => {
it.each([
["1006 abnormal closure", 1006, "network lost"],
["1001 going away", 1001, ""],
["1011 internal error", 1011, "Internal server error"],
["1012 service restart", 1012, ""],
["1013 try again later", 1013, ""],
["1000 with the reconnect reason", 1000, RECONNECT_CLOSE_REASON],
["4008 connection rate limit", 4008, "Too many connection attempts"],
] as const)("reconnects after %s", (_name, code, reason) => {
vi.spyOn(Math, "random").mockReturnValue(0.5)
const hook = mountChat()
act(() => socketAt(0).open())
act(() => socketAt(0).triggerClose(code, reason))
expect(hook.result.current.connectionPhase).toBe("reconnecting")
expectReconnectAfter(1_000)
})
it.each([
["1000 normal closure", 1000, "", "idle-or-lost"],
["4003 access denied", 4003, "Access denied", "error"],
["1008 policy violation", 1008, "", "error"],
["1002 protocol error", 1002, "", "error"],
["an unknown application code", 4404, "Session not found", "error"],
] as const)("does not reconnect after %s", (_name, code, reason, outcome) => {
const onConnectionFailure = vi.fn()
const hook = mountChat({ onConnectionFailure })
act(() => socketAt(0).open())
act(() => socketAt(0).triggerClose(code, reason))
advance(RECONNECT_MAX_DELAY_MS * 2)
expect(MockWebSocket.instances).toHaveLength(1)
expect(hook.result.current.connectionPhase).toBe("lost")
if (outcome === "error") {
expect(onConnectionFailure).toHaveBeenCalledWith(
expect.objectContaining({ recoverable: false }),
)
expect(hook.result.current.connectionError?.message).toBe(
reason || `WebSocket closed with code ${code}`,
)
} else {
expect(onConnectionFailure).not.toHaveBeenCalled()
}
})
})
describe("retry now when the page or the network comes back", () => {
const setVisibility = (state: DocumentVisibilityState) => {
Object.defineProperty(document, "visibilityState", {
configurable: true,
get: () => state,
})
document.dispatchEvent(new Event("visibilitychange"))
}
afterEach(() => {
Object.defineProperty(document, "visibilityState", {
configurable: true,
get: () => "visible",
})
})
// Five failed attempts leave a 7.6 s back-off waiting.
const failFiveTimes = () => {
act(() => socketAt(0).open())
act(() => socketAt(0).triggerClose(1006))
for (const delay of [1_000, 1_500, 2_250, 3_375, 5_063]) {
expectReconnectAfter(delay)
act(() => socketAt(MockWebSocket.instances.length - 1).triggerError())
}
expect(MockWebSocket.instances).toHaveLength(6)
}
beforeEach(() => {
vi.spyOn(Math, "random").mockReturnValue(0.5)
})
it.each([
["the page becomes visible", () => setVisibility("visible")],
["the browser goes back online", () => window.dispatchEvent(new Event("online"))],
] as const)("retries at once when %s", (_name, trigger) => {
const hook = mountChat()
failFiveTimes()
act(() => trigger())
expect(MockWebSocket.instances).toHaveLength(7)
expect(vi.getTimerCount()).toBe(1) // only the new handshake timer
expect(hook.result.current.connectionPhase).toBe("reconnecting")
act(() => socketAt(6).open())
expect(hook.result.current.connectionPhase).toBe("connected")
})
it("continues the back-off when the immediate retry fails", () => {
mountChat()
failFiveTimes()
act(() => window.dispatchEvent(new Event("online")))
act(() => socketAt(6).triggerError())
// The early retry used the sixth attempt; the seventh waits 11.4 s.
expectReconnectAfter(11_391)
})
it("does nothing when the page is hidden", () => {
mountChat()
failFiveTimes()
act(() => setVisibility("hidden"))
expect(MockWebSocket.instances).toHaveLength(6)
expectReconnectAfter(7_594)
})
it("leaves a healthy connection alone", () => {
mountChat()
act(() => socketAt(0).open())
act(() => socketAt(0).receive(ACK))
act(() => setVisibility("visible"))
act(() => window.dispatchEvent(new Event("online")))
expect(socketAt(0).close).not.toHaveBeenCalled()
expect(MockWebSocket.instances).toHaveLength(1)
})
it("does not retry a connection that closed for good", () => {
const hook = mountChat()
act(() => socketAt(0).open())
act(() => socketAt(0).triggerClose(4003, "Access denied"))
act(() => setVisibility("visible"))
act(() => window.dispatchEvent(new Event("online")))
expect(MockWebSocket.instances).toHaveLength(1)
expect(hook.result.current.connectionPhase).toBe("lost")
})
it.each([
["a transport error", (socket: MockWebSocket) => socket.triggerError()],
["an abnormal closure", (socket: MockWebSocket) => socket.triggerClose(1006)],
["a handshake timeout", () => vi.advanceTimersByTime(10_000)],
] as const)("retries a first connection lost to %s at once", (_name, fail) => {
const hook = mountChat()
act(() => {
fail(socketAt(0))
})
expect(hook.result.current.connectionPhase).toBe("reconnecting")
act(() => window.dispatchEvent(new Event("online")))
expect(MockWebSocket.instances).toHaveLength(2)
expect(hook.result.current.connectionPhase).toBe("reconnecting")
act(() => socketAt(1).open())
expect(hook.result.current.connectionPhase).toBe("connected")
})
it("continues a first connection's back-off after a failed early retry", () => {
mountChat()
act(() => socketAt(0).triggerError())
act(() => setVisibility("visible"))
expect(MockWebSocket.instances).toHaveLength(2)
act(() => socketAt(1).triggerError())
expectReconnectAfter(1_500)
})
it.each([
["closed normally", (socket: MockWebSocket) => socket.triggerClose(1000, "")],
["was denied access", (socket: MockWebSocket) => socket.triggerClose(4003, "Access denied")],
] as const)("does not retry a first connection that %s", (_name, close) => {
const hook = mountChat()
act(() => close(socketAt(0)))
advance(RECONNECT_MAX_DELAY_MS * 2)
act(() => setVisibility("visible"))
act(() => window.dispatchEvent(new Event("online")))
expect(MockWebSocket.instances).toHaveLength(1)
expect(hook.result.current.connectionPhase).toBe("lost")
})
it("does not retry after the caller disconnected", () => {
const hook = mountChat()
act(() => socketAt(0).triggerError())
act(() => hook.result.current.disconnect())
act(() => window.dispatchEvent(new Event("online")))
expect(MockWebSocket.instances).toHaveLength(1)
expect(hook.result.current.connectionPhase).toBe("idle")
})
it("replaces a connection whose dead timer a background tab held back", () => {
mountChat()
act(() => socketAt(0).open())
act(() => socketAt(0).receive(ACK))
// The clock moves past the dead window without the timer firing.
vi.setSystemTime(Date.now() + DEAD_AFTER_MS)
act(() => setVisibility("visible"))
expect(socketAt(0).close).toHaveBeenCalledWith(1000, "Connection liveness timeout")
expect(MockWebSocket.instances).toHaveLength(2)
})
})
describe("first connection failures", () => {
beforeEach(() => {
vi.spyOn(Math, "random").mockReturnValue(0.5)
})
it.each([
["a transport error", (socket: MockWebSocket) => socket.triggerError()],
["an abnormal closure", (socket: MockWebSocket) => socket.triggerClose(1006)],
["a 1012 service restart", (socket: MockWebSocket) => socket.triggerClose(1012)],
["a handshake timeout", () => vi.advanceTimersByTime(10_000)],
] as const)("retries a first connection that fails with %s on the ordinary back-off", (_name, fail) => {
const onConnect = vi.fn()
const hook = mountChat({ onConnect })
expect(hook.result.current.connectionPhase).toBe("connecting")
act(() => {
fail(socketAt(0))
})
expect(hook.result.current.connectionPhase).toBe("reconnecting")
expectReconnectAfter(1_000)
act(() => socketAt(1).triggerError())
expectReconnectAfter(1_500)
act(() => socketAt(2).open())
expect(hook.result.current.connectionPhase).toBe("connected")
expect(onConnect).toHaveBeenCalledTimes(1)
})
it("connects a page loaded while the backend is down once it is back", () => {
const onConnect = vi.fn()
const hook = mountChat({ onConnect })
// Every upgrade fails for 130 s, starting with the first one.
const restartMs = 130_000
const downSince = Date.now()
act(() => socketAt(0).triggerError())
while (Date.now() - downSince < restartMs) {
const count = MockWebSocket.instances.length
advance(1_000)
if (MockWebSocket.instances.length > count) {
act(() => socketAt(count).triggerError())
}
expect(hook.result.current.connectionPhase).toBe("reconnecting")
}
const count = MockWebSocket.instances.length
const backSince = Date.now()
while (MockWebSocket.instances.length === count) advance(1_000)
expect(Date.now() - backSince).toBeLessThan(60_000)
act(() => socketAt(count).open())
expect(hook.result.current.connectionPhase).toBe("connected")
expect(onConnect).toHaveBeenCalledTimes(1)
})
it.each([
["1000 normal closure", 1000, ""],
["4003 access denied", 4003, "Access denied"],
["1008 policy violation", 1008, ""],
["an unknown application code", 4404, "Session not found"],
] as const)("does not retry a first connection closed with %s", (_name, code, reason) => {
const hook = mountChat()
act(() => socketAt(0).triggerClose(code, reason))
advance(RECONNECT_MAX_DELAY_MS * 2)
expect(MockWebSocket.instances).toHaveLength(1)
expect(hook.result.current.connectionPhase).toBe("lost")
})
it("starts a newly selected task's back-off from the first step", () => {
const hook = mountChat()
act(() => socketAt(0).open())
act(() => socketAt(0).triggerClose(1006))
expect(hook.result.current.connectionPhase).toBe("reconnecting")
hook.rerender({ taskId: 8 })
expect(MockWebSocket.instances).toHaveLength(2)
act(() => socketAt(1).triggerError())
expectReconnectAfter(1_000)
})
it("reconnects an opened connection that only reports a transport error", () => {
vi.spyOn(Math, "random").mockReturnValue(0.5)
mountChat()
act(() => socketAt(0).open())
act(() => socketAt(0).triggerError())
expectReconnectAfter(1_000)
})
})
it.each([
["a heartbeat connection with frames spanning 29,999 ms", true, 29_999, 1_500],
["a heartbeat connection with frames spanning 30,000 ms", true, 30_000, 1_000],
["a connection without heartbeat open for 29,999 ms", false, 29_999, 1_500],
["a connection without heartbeat open for 30,000 ms", false, 30_000, 1_000],
] as const)("back-off reset rules: restarts the back-off for %s", (_name, heartbeat, span, expectedDelay) => {
vi.spyOn(Math, "random").mockReturnValue(0.5)
mountChat()
// Spend one attempt on an opened key.
act(() => socketAt(0).open())
act(() => socketAt(0).triggerClose(1006))
advance(1_000)
const socket = socketAt(1)
act(() => socket.open())
if (heartbeat) {
// The span counts from the first frame, 5 s after open.
advance(5_000)
act(() => socket.receive(ACK))
advance(15_000)
act(() => socket.receive(HEARTBEAT))
advance(span - 15_000)
act(() => socket.receive(HEARTBEAT))
} else {
advance(span)
}
act(() => socket.triggerClose(1006))
expectReconnectAfter(expectedDelay)
})
it("session transport hands dead connections to its owner", () => {
const onSessionConnectionFailure = vi.fn()
const hook = mountChat({
url: undefined,
taskId: undefined,
connection: sessionConnection(),
onSessionConnectionFailure,
})
const socket = socketAt(0)
socket.protocol = "xagent-session-v1"
act(() => socket.open())
act(() => socket.receive(ACK))
advance(150_000)
expect(onSessionConnectionFailure.mock.calls).toEqual([
[expect.objectContaining({ recoverable: true }), "widget-session:1"],
])
expect(MockWebSocket.instances).toHaveLength(1)
expect(hook.result.current.connectionPhase).toBe("lost")
})
// One row per remaining way a socket is retired with a reconnect in view;
// the dead rule is the test above. The embedding page owns every Session
// reconnect and hands over a new connection identity with each one.
it.each([
["a handshake timeout", () => {
vi.advanceTimersByTime(10_000)
}],
["a server close its owner leaves to the default policy", (socket: MockWebSocket) => {
socket.open()
socket.triggerClose(1006)
}],
["a transport error", (socket: MockWebSocket) => {
socket.open()
socket.triggerError()
}],
] as const)("session transport never schedules its own reconnect after %s", (_name, retire) => {
vi.spyOn(console, "error").mockImplementation(() => {})
mountChat({
url: undefined,
taskId: undefined,
connection: sessionConnection(),
onSessionConnectionClose: () => "default",
onSessionConnectionFailure: vi.fn(),
})
const socket = socketAt(0)
socket.protocol = "xagent-session-v1"
act(() => retire(socket))
expect(vi.getTimerCount()).toBe(0)
advance(RECONNECT_MAX_DELAY_MS + 1)
expect(MockWebSocket.instances).toHaveLength(1)
})
describe("connection phase", () => {
const base: ConnectionPhaseFacts = {
hasDescriptor: true,
autoConnect: true,
stoppedByCaller: false,
ownerOpen: false,
ownerInFlight: false,
retryPending: false,
lifecycleEnded: false,
}
it.each([
["no descriptor", { hasDescriptor: false, ownerOpen: true }, "idle"],
["stopped by the caller, even with a timer", { stoppedByCaller: true, retryPending: true }, "idle"],
["auto connect off and no connection object", { autoConnect: false, retryPending: true }, "idle"],
["auto connect off with a connection object", { autoConnect: false, ownerInFlight: true }, "connecting"],
["an open connection, even with a timer", { ownerOpen: true, retryPending: true }, "connected"],
["a timer waiting", { retryPending: true }, "reconnecting"],
["an unopened connection after a failed cycle", { ownerInFlight: true, lifecycleEnded: true }, "reconnecting"],
["an unopened connection in a fresh cycle", { ownerInFlight: true }, "connecting"],
["nothing yet in a fresh cycle", {}, "connecting"],
["nothing left after a failed cycle", { lifecycleEnded: true }, "lost"],
] as const)("derives the phase for %s", (_name, facts, expected) => {
expect(deriveConnectionPhase({ ...base, ...facts })).toBe(expected)
})
it("drops a waiting retry when the caller connects again", () => {
const hook = mountChat()
act(() => socketAt(0).open())
act(() => socketAt(0).triggerClose(1006))
expect(hook.result.current.connectionPhase).toBe("reconnecting")
// A manual connect starts a new cycle; the old cycle's retry goes with it.
act(() => hook.result.current.connect())
expect(MockWebSocket.instances).toHaveLength(2)
act(() => socketAt(1).triggerClose(1000))
expect(hook.result.current.connectionPhase).toBe("lost")
advance(1_200)
expect(MockWebSocket.instances).toHaveLength(2)
expect(hook.result.current.connectionPhase).toBe("lost")
})
it("reads connecting, not reconnecting, when the caller connects again after a failure", () => {
const hook = mountChat()
act(() => socketAt(0).triggerError())
expect(hook.result.current.connectionPhase).toBe("reconnecting")
// No disconnect() in between: the caller starts a new cycle directly.
act(() => hook.result.current.connect())
expect(MockWebSocket.instances).toHaveLength(2)
expect(hook.result.current.connectionPhase).toBe("connecting")
act(() => socketAt(1).open())
expect(hook.result.current.connectionPhase).toBe("connected")
// The retry the failure left waiting was dropped with the old cycle.
advance(RECONNECT_MAX_DELAY_MS)
expect(MockWebSocket.instances).toHaveLength(2)
})
})
describe("descriptor changes keep the connection key", () => {
beforeEach(() => {
vi.spyOn(Math, "random").mockReturnValue(0.5)
})
it.each([
["on a healthy connection is a reconnect that counts as an attempt", false, 1_500],
["while a retry timer waits still counts as one attempt", true, 2_250],
] as const)("a routine descriptor change %s", (_name, dead, expectedDelay) => {
const hook = mountChat()
act(() => socketAt(0).open())
if (dead) {
act(() => socketAt(0).receive(ACK))
advance(30_000)
expect(hook.result.current.connectionPhase).toBe("reconnecting")
}
authState.session = { ...authState.session }
hook.rerender({})
expect(MockWebSocket.instances).toHaveLength(2)
expect(hook.result.current.connectionPhase).toBe("connecting")
act(() => socketAt(1).triggerError())
expectReconnectAfter(expectedDelay)
})
it("starts a fresh key when another account takes over the same task", () => {
const hook = mountChat()
act(() => socketAt(0).open())
// Spend one reconnect attempt under the old principal first.
act(() => socketAt(0).triggerClose(1006))
authState.user = { id: "user-2" }
authState.token = "token-2"
authState.session = { ...authState.session, accessToken: "token-2", userId: "user-2" }
hook.rerender({})
expect(MockWebSocket.instances).toHaveLength(2)
// The old principal's key would wait 1.5 s; the new key starts over.
act(() => socketAt(1).triggerError())
expectReconnectAfter(1_000)
expect(hook.result.current.connectionPhase).toBe("reconnecting")
})
it("shows connecting, not reconnecting, after a caller disconnect and connect", () => {
const hook = mountChat()
act(() => socketAt(0).open())
expect(hook.result.current.connectionPhase).toBe("connected")
act(() => hook.result.current.disconnect())
expect(hook.result.current.connectionPhase).toBe("idle")
act(() => hook.result.current.connect())
expect(MockWebSocket.instances).toHaveLength(2)
expect(hook.result.current.connectionPhase).toBe("connecting")
})
})
})
})
describe("reconnect policy", () => {
it.each([
[1, 1_000],
[2, 1_500],
[3, 2_250],
[5, 5_063],
[10, 38_443],
[14, 194_620],
[15, 291_929],
[16, RECONNECT_MAX_DELAY_MS],
[100, RECONNECT_MAX_DELAY_MS],
[10_000, RECONNECT_MAX_DELAY_MS],
])("waits a nominal back-off for attempt %i", (attempt, expected) => {
expect(reconnectDelayMs(attempt, 0.5)).toBe(expected)
})
it("spreads each delay by 20 percent either way", () => {
expect(reconnectDelayMs(1, 0)).toBe(800)
expect(reconnectDelayMs(1, 0.999999)).toBe(1_200)
expect(reconnectDelayMs(1_000, 0)).toBe(240_000)
expect(reconnectDelayMs(1_000, 0.999999)).toBe(360_000)
})
it.each([
[1000, "", "intentional"],
[1000, RECONNECT_CLOSE_REASON, "retry"],
[1001, "", "retry"],
[1005, "", "retry"],
[1006, "", "retry"],
[1009, "", "retry"],
[1011, "", "retry"],
[1012, "", "retry"],
[1012, RECONNECT_CLOSE_REASON, "retry"],
[1013, "", "retry"],
[1014, "", "retry"],
[1002, "", "permanent"],
[1003, "", "permanent"],
[1007, "", "permanent"],
[1008, "", "permanent"],
[1010, "", "permanent"],
[1015, "", "permanent"],
[4001, "", "reauthenticate"],
[4003, "Access denied", "permanent"],
[4003, RECONNECT_CLOSE_REASON, "permanent"],
[4004, "", "permanent"],
[4008, "", "retry"],
[4999, "", "permanent"],
[3000, "", "retry"],
] as const)("classifies close code %i (reason %j) as %s", (code, reason, expected) => {
expect(classifyClose({ code, reason })).toBe(expected)
})
})