Enterprise agent platform for building, deploying, and operating AI teammates.
import { act, renderHook } from "@testing-library/react"
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
import { useWidgetSession } from "./use-widget-session"
import { evaluateWidgetScript } from "@/test-utils/widget-script"
export const HOST = "https://chat.example"
export const GRANT = "eyJhbGciOiJIUzI1NiJ9.grant-one.sig"
const EXCHANGE_URL = `${HOST}/v1/external/chat/sessions`
const RECONNECT_URL = `${HOST}/v1/external/chat/sessions/reconnect`
const fetchMock = vi.fn()
function runWidget(attributes: Record<string, string>) {
const script = document.createElement("script")
script.src = `${HOST}/widget.js`
for (const [name, value] of Object.entries(attributes)) {
script.setAttribute(name, value)
}
document.body.appendChild(script)
Object.defineProperty(document, "currentScript", { configurable: true, value: script })
evaluateWidgetScript()
return script
}
function iframeEl(): HTMLIFrameElement | null {
return document.querySelector<HTMLIFrameElement>(".xagent-widget-iframe")
}
function spyOnIframePostMessage(frame = iframeEl()) {
if (!frame?.contentWindow) throw new Error("iframe not mounted")
return vi.spyOn(frame.contentWindow, "postMessage")
}
function fromSpecificIframe(
frame: HTMLIFrameElement | null,
type: string,
extra: Record<string, unknown> = {},
) {
window.dispatchEvent(new MessageEvent("message", {
data: { xagent: true, v: 1, type, ...extra },
origin: HOST,
source: frame?.contentWindow as Window,
}))
}
function fromIframe(type: string, extra: Record<string, unknown> = {}) {
fromSpecificIframe(iframeEl(), type, extra)
}
function bridgeWidgetSessionHook(frame: HTMLIFrameElement) {
const parent = {
postMessage: vi.fn((message: Record<string, unknown>) => {
act(() => {
window.dispatchEvent(new MessageEvent("message", {
data: message,
origin: HOST,
source: frame.contentWindow as Window,
}))
})
}),
}
Object.defineProperty(window, "parent", { configurable: true, value: parent })
const postToIframe = vi.spyOn(frame.contentWindow!, "postMessage").mockImplementation((message) => {
act(() => {
window.dispatchEvent(new MessageEvent("message", {
data: message,
origin: HOST,
source: parent as unknown as MessageEventSource,
}))
})
})
return { parent, postToIframe }
}
function jsonResponse(status: number, body: unknown, headers: Record<string, string> = {}) {
return new Response(JSON.stringify(body), {
status,
headers: { "Content-Type": "application/json", ...headers },
})
}
function directJsonResponse(status: number, data: unknown): Response {
return {
ok: status >= 200 && status < 300,
status,
headers: new Headers(),
json: () => Promise.resolve(data),
} as Response
}
function errorResponse(status: number, code: string) {
return jsonResponse(status, { error: { code, message: "nope" } })
}
// vi.waitFor's condition here (fetchMock call count) goes true the instant
// fetch() is invoked, which happens synchronously during runWidget(). That
// resolves the waitFor promise before the mocked Response's real .json()
// body-read (an inherently async, multi-microtask-tick operation) has settled.
// A macrotask flush lets every already-scheduled microtask (the fetch/json/
// applySession chain) drain before we simulate the iframe's "ready" signal.
function flushAsync() {
return new Promise<void>((resolve) => setTimeout(resolve, 0))
}
function firePageShow(persisted: boolean) {
const event = new Event("pageshow") as PageTransitionEvent & { persisted: boolean }
Object.defineProperty(event, "persisted", { value: persisted })
window.dispatchEvent(event)
}
function firePageHide(persisted: boolean) {
const event = new Event("pagehide") as PageTransitionEvent & { persisted: boolean }
Object.defineProperty(event, "persisted", { value: persisted })
window.dispatchEvent(event)
}
function firePageRestore() {
firePageHide(true)
firePageShow(true)
}
function exchangeBody(overrides: Record<string, unknown> = {}) {
return {
session_token: "st_first",
session_token_expires_at: new Date(Date.now() + 15 * 60_000).toISOString(),
reconnect_token: "rt_first",
session: {
absolute_expires_at: new Date(Date.now() + 8 * 3_600_000).toISOString(),
agent: {
id: 42,
name: "Care Assistant",
description: "Rosters and shifts",
logo_url: `${HOST}/logo.png`,
suggested_prompts: ["What is my next shift?"],
},
},
...overrides,
}
}
describe("widget session mode", () => {
let currentScriptDescriptor: PropertyDescriptor | undefined
let parentDescriptor: PropertyDescriptor | undefined
// runWidget()'s attach() registers message and bfcache lifecycle listeners
// directly on the shared jsdom `window` (vitest reuses one window per test
// file). Without tracking and removing them, a controller from an earlier
// test stays subscribed and reacts to a later test's fromIframe()/
// firePageShow() dispatches, corrupting that later test's fetch-call
// counts. We wrap addEventListener for the duration of each test to record
// every (type, listener) pair the production code registers on window, and
// remove them all in afterEach.
let windowListeners: Array<[string, EventListenerOrEventListenerObject]> = []
let documentListeners: Array<[string, EventListenerOrEventListenerObject]> = []
let realAddEventListener: typeof window.addEventListener
let realDocumentAddEventListener: typeof document.addEventListener
beforeEach(() => {
currentScriptDescriptor = Object.getOwnPropertyDescriptor(document, "currentScript")
parentDescriptor = Object.getOwnPropertyDescriptor(window, "parent")
document.head.innerHTML = ""
document.body.innerHTML = ""
localStorage.clear()
// The grant dedupe registry lives on window and survives between tests in a file.
Reflect.deleteProperty(window as unknown as Record<string, unknown>, "__xagentWidgetGrants")
vi.stubGlobal("fetch", fetchMock)
fetchMock.mockReset()
windowListeners = []
realAddEventListener = window.addEventListener.bind(window)
vi.spyOn(window, "addEventListener").mockImplementation((type, listener, options) => {
windowListeners.push([type, listener as EventListenerOrEventListenerObject])
realAddEventListener(type, listener, options)
})
documentListeners = []
realDocumentAddEventListener = document.addEventListener.bind(document)
vi.spyOn(document, "addEventListener").mockImplementation((type, listener, options) => {
documentListeners.push([type, listener as EventListenerOrEventListenerObject])
realDocumentAddEventListener(type, listener, options)
})
// Transport back-off without jitter: 1000, 1500, 2250, 3375, 5063 ms, ...
vi.spyOn(Math, "random").mockReturnValue(0.5)
})
afterEach(async () => {
for (const container of document.querySelectorAll(".xagent-widget-container")) {
container.remove()
}
// Let each controller's MutationObserver run its production teardown
// before Vitest removes the jsdom globals.
await Promise.resolve()
await Promise.resolve()
for (const [type, listener] of windowListeners) {
window.removeEventListener(type, listener)
}
windowListeners = []
for (const [type, listener] of documentListeners) {
document.removeEventListener(type, listener)
}
documentListeners = []
if (currentScriptDescriptor) {
Object.defineProperty(document, "currentScript", currentScriptDescriptor)
} else {
Reflect.deleteProperty(document, "currentScript")
}
if (parentDescriptor) {
Object.defineProperty(window, "parent", parentDescriptor)
}
vi.useRealTimers()
vi.unstubAllGlobals()
vi.restoreAllMocks()
})
it("harness boots the guest path unchanged", async () => {
fetchMock.mockResolvedValueOnce(jsonResponse(200, { ticket: "t", agent_id: 17 }))
runWidget({ "data-widget-key": "widget-secret" })
await vi.waitFor(() => {
expect(iframeEl()?.src).toContain("/widget/chat/default")
})
})
it("passes data-timezone to the session iframe", () => {
fetchMock.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
runWidget({ "data-encrypted-context": GRANT, "data-timezone": "Australia/Perth" })
expect(iframeEl()?.src).toBe(`${HOST}/widget/chat/session?timezone=Australia%2FPerth`)
})
it("appends data-timezone to the guest iframe URL that already has a query", async () => {
fetchMock.mockResolvedValueOnce(jsonResponse(200, { ticket: "t", agent_id: 17 }))
runWidget({ "data-widget-key": "widget-secret", "data-timezone": "Australia/Perth" })
await vi.waitFor(() => {
expect(iframeEl()?.src).toContain("&timezone=Australia%2FPerth")
})
expect(iframeEl()?.src).toContain("?guest_id=")
})
it("leaves the iframe URL untouched for a blank data-timezone", () => {
fetchMock.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
runWidget({ "data-encrypted-context": GRANT, "data-timezone": " " })
expect(iframeEl()?.src).toBe(`${HOST}/widget/chat/session`)
})
it("still loads the session iframe when data-timezone is malformed", () => {
fetchMock.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
// A lone surrogate makes encodeURIComponent throw; the widget must fall
// back to a plain iframe URL rather than never assigning src.
runWidget({ "data-encrypted-context": GRANT, "data-timezone": "\uD800" })
expect(iframeEl()?.src).toBe(`${HOST}/widget/chat/session`)
})
it("still loads the guest iframe when data-timezone is malformed", async () => {
fetchMock.mockResolvedValueOnce(jsonResponse(200, { ticket: "t", agent_id: 17 }))
runWidget({ "data-widget-key": "widget-secret", "data-timezone": "\uD800" })
await vi.waitFor(() => {
expect(iframeEl()?.src).toContain("/widget/chat/default")
})
expect(iframeEl()?.src).not.toContain("timezone=")
})
it("navigates the iframe to the session URL and exchanges the grant immediately", () => {
fetchMock.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
const observeSpy = vi.spyOn(MutationObserver.prototype, "observe")
runWidget({ "data-encrypted-context": GRANT })
expect(iframeEl()?.src).toBe(`${HOST}/widget/chat/session`)
// Two MutationObservers now exist in session mode: the widget's own
// panel-removal teardown (armed before mode.attach runs) and this
// controller's iframe-connectivity one, both on document.documentElement
// with the same options -- so "was called with these args" alone no
// longer pins this controller's own observer specifically. Assert every
// observe() call has the expected target/options, so a regression in
// either one (e.g. this controller's own observer losing `subtree`, or
// reverting to document.body -- which misses a host framework replacing
// <body> wholesale on navigation) still fails here instead of being
// masked by the other happening to be correct.
expect(observeSpy).toHaveBeenCalledTimes(2)
observeSpy.mock.calls.forEach(([target, options]) => {
expect(target).toBe(document.documentElement)
expect(options).toEqual({ childList: true, subtree: true })
})
expect(fetchMock).toHaveBeenCalledTimes(1)
expect(fetchMock).toHaveBeenCalledWith(EXCHANGE_URL, expect.objectContaining({
method: "POST",
credentials: "omit",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ encrypted_context: GRANT }),
}))
})
it("consumes the response body returned by the session exchange", async () => {
const response = jsonResponse(200, exchangeBody())
fetchMock.mockResolvedValueOnce(response)
runWidget({ "data-encrypted-context": GRANT })
await vi.waitFor(() => {
expect(response.bodyUsed).toBe(true)
})
})
it("sends the opaque grant value verbatim after checking that it is not blank", () => {
const rawGrant = ` ${GRANT}\n`
fetchMock.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
runWidget({ "data-encrypted-context": rawGrant })
expect(fetchMock).toHaveBeenCalledWith(EXCHANGE_URL, expect.objectContaining({
body: JSON.stringify({ encrypted_context: rawGrant }),
}))
})
it("fails closed on an empty grant attribute with no DOM and no network", () => {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
runWidget({ "data-encrypted-context": " " })
expect(fetchMock).not.toHaveBeenCalled()
expect(document.querySelector(".xagent-widget-container")).toBeNull()
expect(document.head.querySelector("style")).toBeNull()
expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("[grant_malformed]"))
})
it.each(["data-widget-key", "data-token"])(
"fails closed when %s coexists with the grant",
(legacyAttribute) => {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
const script = runWidget({ "data-encrypted-context": GRANT, [legacyAttribute]: "legacy" })
expect(fetchMock).not.toHaveBeenCalled()
expect(document.querySelector(".xagent-widget-container")).toBeNull()
expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("[attribute_conflict]"))
expect(script.hasAttribute("data-encrypted-context")).toBe(false)
},
)
it("keeps cosmetic attributes working in session mode", () => {
fetchMock.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
runWidget({ "data-encrypted-context": GRANT, "data-button-color": "rgb(1, 2, 3)" })
expect(document.head.querySelector("style")?.innerHTML).toContain("rgb(1, 2, 3)")
})
it("never writes a guest id in session mode", () => {
fetchMock.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
runWidget({ "data-encrypted-context": GRANT })
expect(localStorage.getItem("xagent_guest_id")).toBeNull()
})
it("removes the grant attribute from the DOM once it is read", () => {
fetchMock.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
const script = runWidget({ "data-encrypted-context": GRANT })
expect(script.hasAttribute("data-encrypted-context")).toBe(false)
})
it("deduplicates the same grant while keeping different grants and message channels isolated", async () => {
const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined)
fetchMock.mockImplementation((_url: string, init: RequestInit) => {
const body = JSON.parse(init.body as string)
const suffix = body.encrypted_context === GRANT ? "first" : "second"
return Promise.resolve(jsonResponse(200, exchangeBody({
session_token: `st_${suffix}`,
reconnect_token: `rt_${suffix}`,
})))
})
runWidget({ "data-encrypted-context": GRANT })
const duplicateScript = runWidget({ "data-encrypted-context": GRANT })
expect(document.querySelectorAll(".xagent-widget-container")).toHaveLength(1)
expect(warnSpy).toHaveBeenCalledWith(expect.stringMatching(
/single-use.*fresh grant.*\[duplicate_init\]/,
))
expect(duplicateScript.hasAttribute("data-encrypted-context")).toBe(false)
runWidget({ "data-encrypted-context": `${GRANT}-other` })
const frames = Array.from(document.querySelectorAll<HTMLIFrameElement>(".xagent-widget-iframe"))
expect(frames).toHaveLength(2)
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2))
await flushAsync()
expect(fetchMock.mock.calls.map((call) => JSON.parse(call[1].body))).toEqual([
{ encrypted_context: GRANT },
{ encrypted_context: `${GRANT}-other` },
])
const firstPost = spyOnIframePostMessage(frames[0])
const secondPost = spyOnIframePostMessage(frames[1])
fromSpecificIframe(frames[1], "ready")
expect(firstPost).not.toHaveBeenCalled()
expect(secondPost).toHaveBeenCalledWith(
expect.objectContaining({ type: "session_update", session_token: "st_second" }),
HOST,
)
})
it("uses the exact 32-bit FNV-1a digest for grant dedupe keys", () => {
fetchMock.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
runWidget({ "data-encrypted-context": "hello" })
expect(
(window as unknown as { __xagentWidgetGrants: Record<string, boolean> })
.__xagentWidgetGrants,
).toEqual({ g4f9f2cab: true })
})
it("pushes session_update to the iframe once it announces ready", async () => {
const body = exchangeBody()
const absoluteExpiresAt = body.session.absolute_expires_at
fetchMock.mockResolvedValueOnce(jsonResponse(200, body))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
await flushAsync()
fromIframe("ready")
expect(post).toHaveBeenCalledTimes(1)
const [message, targetOrigin] = post.mock.calls[0]
expect(targetOrigin).toBe(HOST)
expect(message).toMatchObject({
xagent: true,
v: 1,
type: "session_update",
session_token: "st_first",
absolute_expires_at: absoluteExpiresAt,
agent: { id: 42, name: "Care Assistant" },
})
expect(message).not.toHaveProperty("reconnect_token")
})
describe("session capabilities forwarding", () => {
const capabilities = {
file_uploads: {
allowed_extensions: [".pdf", ".png"],
max_file_bytes: 1024,
max_files_per_message: 2,
},
}
async function exchangeAndReady(body: Record<string, unknown>) {
fetchMock.mockResolvedValueOnce(jsonResponse(200, body))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
await flushAsync()
fromIframe("ready")
return post
}
it("forwards a capabilities object unchanged in session_update", async () => {
const body = exchangeBody()
;(body.session as Record<string, unknown>).capabilities = capabilities
const post = await exchangeAndReady(body)
expect(post).toHaveBeenCalledTimes(1)
expect(post.mock.calls[0][0].capabilities).toEqual(capabilities)
})
it("omits the capabilities key when the exchange has none", async () => {
const post = await exchangeAndReady(exchangeBody())
expect(post).toHaveBeenCalledTimes(1)
expect(post.mock.calls[0][0]).not.toHaveProperty("capabilities")
})
it.each([
["an array", ["x"]],
["a string", "file_uploads"],
["null", null],
])("omits the capabilities key when it is %s and still delivers the session", async (_label, value) => {
const body = exchangeBody()
;(body.session as Record<string, unknown>).capabilities = value
const post = await exchangeAndReady(body)
expect(post).toHaveBeenCalledTimes(1)
expect(post.mock.calls[0][0]).toMatchObject({ type: "session_update", session_token: "st_first" })
expect(post.mock.calls[0][0]).not.toHaveProperty("capabilities")
})
it("overwrites the previous capabilities with the reconnect response", async () => {
const first = exchangeBody()
;(first.session as Record<string, unknown>).capabilities = capabilities
const nextCapabilities = {
file_uploads: {
allowed_extensions: [".csv"],
max_file_bytes: 2048,
max_files_per_message: 3,
},
}
const second = exchangeBody({ session_token: "st_second", reconnect_token: "rt_second" })
;(second.session as Record<string, unknown>).capabilities = nextCapabilities
fetchMock
.mockResolvedValueOnce(jsonResponse(200, first))
.mockResolvedValueOnce(jsonResponse(200, second))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
await flushAsync()
fromIframe("ready")
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2))
await flushAsync()
fromIframe("ready")
expect(post.mock.calls[0][0].capabilities).toEqual(capabilities)
expect(post.mock.calls[1][0]).toMatchObject({ session_token: "st_second" })
expect(post.mock.calls[1][0].capabilities).toEqual(nextCapabilities)
})
})
it("holds only the latest state until ready arrives", async () => {
fetchMock
.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({
session_token: "st_second",
reconnect_token: "rt_second",
})))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
await flushAsync()
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2))
await flushAsync()
expect(post).not.toHaveBeenCalled()
fromIframe("ready")
expect(post).toHaveBeenCalledTimes(1)
expect(post.mock.calls[0][0]).toMatchObject({ session_token: "st_second" })
})
it("re-sends the current state on every ready", async () => {
fetchMock.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
await flushAsync()
fromIframe("ready")
fromIframe("ready")
expect(post).toHaveBeenCalledTimes(2)
expect(post.mock.calls[1][0]).toMatchObject({ type: "session_update", session_token: "st_first" })
expect(post.mock.calls[1][0].session_delivery_id).toBe(post.mock.calls[0][0].session_delivery_id)
})
it("admits three logical recoveries and terminalizes the fourth before fetch", async () => {
fetchMock
.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({ session_token: "st_second", reconnect_token: "rt_second" })))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({ session_token: "st_third", reconnect_token: "rt_third" })))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({ session_token: "st_fourth", reconnect_token: "rt_fourth" })))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
await flushAsync()
fromIframe("ready")
for (let recovery = 0; recovery < 3; recovery += 1) {
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(recovery + 2))
await flushAsync()
}
fromIframe("reconnect_request", { reason: "ws_closed" })
await flushAsync()
expect(fetchMock).toHaveBeenCalledTimes(4)
expect(post).toHaveBeenCalledWith(
expect.objectContaining({ type: "session_terminal", code: "network_unavailable" }),
HOST,
)
})
it("keeps each admitted logical recovery on its own four-request HTTP budget", async () => {
vi.useFakeTimers()
fetchMock
.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
.mockResolvedValueOnce(jsonResponse(502, { error: { code: "upstream_unavailable" } }))
.mockResolvedValueOnce(jsonResponse(502, { error: { code: "upstream_unavailable" } }))
.mockResolvedValueOnce(jsonResponse(502, { error: { code: "upstream_unavailable" } }))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({ session_token: "st_second", reconnect_token: "rt_second" })))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({ session_token: "st_third", reconnect_token: "rt_third" })))
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(0)
fromIframe("ready")
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.advanceTimersByTimeAsync(7_000)
expect(fetchMock.mock.calls.filter(([url]) => url === RECONNECT_URL)).toHaveLength(4)
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.advanceTimersByTimeAsync(0)
expect(fetchMock.mock.calls.filter(([url]) => url === RECONNECT_URL)).toHaveLength(5)
})
it("starts stability only from the exact correlated open and makes duplicate opens idempotent", async () => {
vi.useFakeTimers()
fetchMock.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.advanceTimersByTimeAsync(0)
fromIframe("ready")
const deliveryId = post.mock.calls[0][0].session_delivery_id
await vi.advanceTimersByTimeAsync(59_999)
fromIframe("session_connection_open", { session_delivery_id: deliveryId })
fromIframe("session_connection_open", { session_delivery_id: deliveryId })
await vi.advanceTimersByTimeAsync(59_999)
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.advanceTimersByTimeAsync(0)
expect(fetchMock).toHaveBeenCalledTimes(2)
})
it.each([
[59_999, 2],
[60_000, 3],
])(
"after %i ms of correlated open, admits exactly %i recoveries from the remaining rapid budget",
async (stableMs, admittedRecoveries) => {
vi.useFakeTimers()
// A rotating token, as on the server; a constant one keeps a 30 s deadline alive.
let exchanges = 0
fetchMock.mockImplementation(() => Promise.resolve(jsonResponse(200, exchangeBody({
reconnect_token: `rt_${exchanges++}`,
}))))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.advanceTimersByTimeAsync(0)
fromIframe("ready")
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.advanceTimersByTimeAsync(0)
const deliveryId = post.mock.calls
.filter(([message]) => message.type === "session_update")
.at(-1)?.[0].session_delivery_id
fromIframe("session_connection_open", { session_delivery_id: deliveryId })
await vi.advanceTimersByTimeAsync(stableMs)
for (let recovery = 0; recovery < admittedRecoveries; recovery += 1) {
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.advanceTimersByTimeAsync(0)
}
const requestsAfterAdmissions = fetchMock.mock.calls.length
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.advanceTimersByTimeAsync(0)
expect(requestsAfterAdmissions).toBe(admittedRecoveries + 2)
expect(fetchMock).toHaveBeenCalledTimes(requestsAfterAdmissions)
expect(post).toHaveBeenCalledWith(
expect.objectContaining({ type: "session_terminal", code: "network_unavailable" }),
HOST,
)
},
)
it("arms only current delivery B and treats duplicate B opens as idempotent before and after completion", async () => {
vi.useFakeTimers()
fetchMock
.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({ session_token: "st_second", reconnect_token: "rt_second" })))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({ session_token: "st_third", reconnect_token: "rt_third" })))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({ session_token: "st_fourth", reconnect_token: "rt_fourth" })))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({ session_token: "st_fifth", reconnect_token: "rt_fifth" })))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.advanceTimersByTimeAsync(0)
fromIframe("ready")
const deliveryA = post.mock.calls.at(-1)?.[0].session_delivery_id
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.advanceTimersByTimeAsync(0)
const deliveryB = post.mock.calls.at(-1)?.[0].session_delivery_id
expect(deliveryB).not.toBe(deliveryA)
fromIframe("session_connection_open", { session_delivery_id: deliveryA })
expect(vi.getTimerCount()).toBe(0)
fromIframe("session_connection_open", { session_delivery_id: deliveryB })
expect(vi.getTimerCount()).toBe(1)
await vi.advanceTimersByTimeAsync(55_000)
fromIframe("session_connection_open", { session_delivery_id: deliveryB })
expect(vi.getTimerCount()).toBe(1)
await vi.advanceTimersByTimeAsync(5_000)
expect(vi.getTimerCount()).toBe(0)
fromIframe("ready")
await vi.advanceTimersByTimeAsync(0)
expect(vi.getTimerCount()).toBe(0)
fromIframe("session_connection_open", { session_delivery_id: deliveryB })
expect(vi.getTimerCount()).toBe(0)
for (let recovery = 0; recovery < 3; recovery += 1) {
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.advanceTimersByTimeAsync(0)
}
expect(fetchMock).toHaveBeenCalledTimes(5)
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.advanceTimersByTimeAsync(0)
expect(fetchMock).toHaveBeenCalledTimes(5)
expect(post).toHaveBeenCalledWith(
expect.objectContaining({ type: "session_terminal", code: "network_unavailable" }),
HOST,
)
})
it("a recovery at 59,999 ms invalidates the old stability callback before it can reset rapid count", async () => {
vi.useFakeTimers()
let resolvePreBoundary: (response: Response) => void = () => undefined
fetchMock
.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({
session_token: "st_second",
reconnect_token: "rt_second",
})))
.mockImplementationOnce(() => new Promise<Response>((resolve) => {
resolvePreBoundary = resolve
}))
.mockImplementation(() => Promise.resolve(jsonResponse(200, exchangeBody())))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.advanceTimersByTimeAsync(0)
fromIframe("ready")
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.advanceTimersByTimeAsync(0)
const deliveryId = post.mock.calls
.filter(([message]) => message.type === "session_update")
.at(-1)?.[0].session_delivery_id
fromIframe("session_connection_open", { session_delivery_id: deliveryId })
await vi.advanceTimersByTimeAsync(59_999)
fromIframe("reconnect_request", { reason: "ws_closed" })
expect(fetchMock).toHaveBeenCalledTimes(3)
await vi.advanceTimersByTimeAsync(1)
resolvePreBoundary(jsonResponse(200, exchangeBody({
session_token: "st_third",
reconnect_token: "rt_third",
})))
await vi.advanceTimersByTimeAsync(0)
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.advanceTimersByTimeAsync(0)
expect(fetchMock).toHaveBeenCalledTimes(4)
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.advanceTimersByTimeAsync(0)
expect(fetchMock).toHaveBeenCalledTimes(4)
expect(post).toHaveBeenCalledWith(
expect.objectContaining({ type: "session_terminal", code: "network_unavailable" }),
HOST,
)
})
it("mints a fresh delivery epoch for a healthy bfcache restore and resets only at 60 seconds", async () => {
vi.useFakeTimers()
fetchMock
.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({ session_token: "st_second", reconnect_token: "rt_second" })))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({ session_token: "st_third", reconnect_token: "rt_third" })))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({ session_token: "st_fourth", reconnect_token: "rt_fourth" })))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({ session_token: "st_fifth", reconnect_token: "rt_fifth" })))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.advanceTimersByTimeAsync(0)
fromIframe("ready")
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2))
await vi.advanceTimersByTimeAsync(0)
const oldId = post.mock.calls.at(-1)?.[0].session_delivery_id
fromIframe("session_connection_open", { session_delivery_id: oldId })
firePageHide(true)
firePageShow(true)
const newId = post.mock.calls.at(-1)?.[0].session_delivery_id
expect(newId).not.toBe(oldId)
for (const session_delivery_id of [undefined, null, "", " ", 1, true, {}, []]) {
fromIframe("session_connection_open", { session_delivery_id })
}
fromIframe("session_connection_open", { session_delivery_id: oldId })
fromIframe("session_connection_open", { session_delivery_id: newId })
await vi.advanceTimersByTimeAsync(59_999)
expect(fetchMock).toHaveBeenCalledTimes(2)
await vi.advanceTimersByTimeAsync(1)
for (let recovery = 0; recovery < 3; recovery += 1) {
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(recovery + 3))
await vi.advanceTimersByTimeAsync(0)
}
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.advanceTimersByTimeAsync(0)
expect(fetchMock).toHaveBeenCalledTimes(5)
expect(post).toHaveBeenCalledWith(
expect.objectContaining({ type: "session_terminal", code: "network_unavailable" }),
HOST,
)
})
it("keeps the resumed recovery owner when the canceled wrapper settles before a duplicate signal", async () => {
vi.useFakeTimers()
let frozenSignal: AbortSignal | undefined
fetchMock
.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({
session_token: "st_second",
reconnect_token: "rt_second",
session_token_expires_at: new Date(Date.now() + 61_000).toISOString(),
})))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({
session_token: "st_third",
reconnect_token: "rt_third",
session_token_expires_at: new Date(Date.now() + 61_000).toISOString(),
})))
.mockImplementationOnce((_url: string, init: RequestInit) => {
frozenSignal = init.signal as AbortSignal
return new Promise<Response>((_resolve, reject) => {
frozenSignal?.addEventListener("abort", () => reject(new DOMException("aborted", "AbortError")), { once: true })
})
})
.mockImplementationOnce(() => new Promise<Response>(() => undefined))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.advanceTimersByTimeAsync(0)
fromIframe("ready")
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2))
await vi.advanceTimersByTimeAsync(0)
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(3))
await vi.advanceTimersByTimeAsync(0)
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(4))
await vi.advanceTimersByTimeAsync(2_000)
firePageHide(true)
firePageShow(true)
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(5))
await vi.advanceTimersByTimeAsync(0)
expect(frozenSignal?.aborted).toBe(true)
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.advanceTimersByTimeAsync(0)
expect(fetchMock).toHaveBeenCalledTimes(5)
expect(post).not.toHaveBeenCalledWith(
expect.objectContaining({ type: "session_terminal" }),
HOST,
)
})
it("ignores messages from a foreign origin, a foreign source, or a foreign shape", async () => {
fetchMock.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
window.dispatchEvent(new MessageEvent("message", {
data: { xagent: true, v: 1, type: "ready" },
origin: "https://evil.example",
source: iframeEl()?.contentWindow as Window,
}))
window.dispatchEvent(new MessageEvent("message", {
data: { xagent: true, v: 1, type: "ready" },
origin: HOST,
source: window,
}))
fromIframe("ready", { v: 2 })
window.dispatchEvent(new MessageEvent("message", {
data: { type: "ready" },
origin: HOST,
source: iframeEl()?.contentWindow as Window,
}))
expect(post).not.toHaveBeenCalled()
})
it("keeps malformed and late lifecycle callbacks inert across a live controller's teardown", async () => {
fetchMock.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
runWidget({ "data-encrypted-context": GRANT })
const frame = iframeEl()!
const frameWindow = frame.contentWindow!
const post = spyOnIframePostMessage(frame)
await flushAsync()
for (const data of [null, false, {}, { xagent: false, v: 1 }, { xagent: true, v: 2 }]) {
window.dispatchEvent(new MessageEvent("message", { data, origin: HOST, source: frameWindow }))
}
expect(post).not.toHaveBeenCalled()
fromIframe("ready")
expect(post).toHaveBeenCalledWith(expect.objectContaining({ type: "session_update" }), HOST)
post.mockClear()
firePageHide(false)
firePageShow(false)
firePageShow(true)
expect(post).not.toHaveBeenCalled()
// Browser events may already be queued when the observer disconnects.
// Keep the real registered callbacks to exercise that race, without
// exposing or mutating the controller's private state.
const queued = windowListeners.filter(([type]) => ["pageshow", "pagehide", "message"].includes(type))
frame.remove()
await flushAsync()
for (const [type, listener] of queued) {
const event = type === "message"
? new MessageEvent(type, { data: { xagent: true, v: 1, type: "ready" }, origin: HOST, source: frameWindow })
: Object.assign(new Event(type), { persisted: true })
if (typeof listener === "function") listener.call(window, event)
else listener.handleEvent(event)
}
expect(post).not.toHaveBeenCalled()
expect(fetchMock).toHaveBeenCalledOnce()
})
it("goes terminal and tells the frame when the grant is rejected outright", async () => {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockResolvedValueOnce(errorResponse(401, "signature_invalid"))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.waitFor(() => expect(errorSpy).toHaveBeenCalledWith(
expect.stringContaining("[signature_invalid]"),
))
expect(fetchMock).toHaveBeenCalledTimes(1) // integrity class never retries or reconnects
fromIframe("ready")
expect(post.mock.calls[0][0]).toMatchObject({ type: "session_terminal", code: "signature_invalid" })
})
it("goes terminal on a stale grant when no reconnect token is held", async () => {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockResolvedValueOnce(errorResponse(401, "grant_already_used"))
runWidget({ "data-encrypted-context": GRANT })
await vi.waitFor(() => expect(errorSpy).toHaveBeenCalledWith(
expect.stringContaining("[grant_already_used]"),
))
expect(fetchMock).toHaveBeenCalledTimes(1)
})
it("logs the registered exchange diagnostic reason without forwarding it to the iframe", async () => {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockResolvedValueOnce(jsonResponse(403, {
error: {
code: "agent_not_granted",
reason: "origin_not_allowed",
message: "remote diagnostic must not be logged",
},
}))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.waitFor(() => expect(errorSpy).toHaveBeenCalledWith(
"Xagent Widget: chat unavailable [agent_not_granted/origin_not_allowed] (HTTP 403).",
))
fromIframe("ready")
expect(post.mock.calls[0][0]).toEqual({
xagent: true,
v: 1,
type: "session_terminal",
code: "agent_not_granted",
})
})
it("scopes a registered diagnostic reason to its owning terminal code", async () => {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockResolvedValueOnce(jsonResponse(401, {
error: {
code: "session_expired",
reason: "origin_not_allowed",
},
}))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.waitFor(() => expect(errorSpy.mock.calls).toEqual([[
"Xagent Widget: chat unavailable [session_expired] (HTTP 401).",
]]))
fromIframe("ready")
expect(post.mock.calls[0][0]).toEqual({
xagent: true,
v: 1,
type: "session_terminal",
code: "session_expired",
})
})
it("ignores an inherited synthetic session failure code", async () => {
const syntheticCodeDescriptor = Object.getOwnPropertyDescriptor(Object.prototype, "syntheticCode")
Object.defineProperty(Object.prototype, "syntheticCode", {
configurable: true,
value: "network_unavailable",
})
try {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockResolvedValueOnce(jsonResponse(403, {
error: {
code: "agent_not_granted",
reason: "origin_not_allowed",
},
}))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.waitFor(() => expect(errorSpy.mock.calls).toEqual([[
"Xagent Widget: chat unavailable [agent_not_granted/origin_not_allowed] (HTTP 403).",
]]))
fromIframe("ready")
expect(post.mock.calls[0][0]).toMatchObject({ type: "session_terminal", code: "agent_not_granted" })
} finally {
if (syntheticCodeDescriptor) {
Object.defineProperty(Object.prototype, "syntheticCode", syntheticCodeDescriptor)
} else {
Reflect.deleteProperty(Object.prototype, "syntheticCode")
}
}
})
it("keeps a registered diagnostic intact when Object.prototype has a toString tag", async () => {
const toStringTagDescriptor = Object.getOwnPropertyDescriptor(Object.prototype, Symbol.toStringTag)
Object.defineProperty(Object.prototype, Symbol.toStringTag, {
configurable: true,
value: "polluted",
})
try {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockResolvedValueOnce(jsonResponse(403, {
error: {
code: "agent_not_granted",
reason: "origin_not_allowed",
},
}))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.waitFor(() => expect(errorSpy).toHaveBeenCalledWith(
"Xagent Widget: chat unavailable [agent_not_granted/origin_not_allowed] (HTTP 403).",
))
fromIframe("ready")
expect(post.mock.calls[0][0]).toMatchObject({ type: "session_terminal", code: "agent_not_granted" })
} finally {
if (toStringTagDescriptor) {
Object.defineProperty(Object.prototype, Symbol.toStringTag, toStringTagDescriptor)
} else {
Reflect.deleteProperty(Object.prototype, Symbol.toStringTag)
}
}
})
it("keeps the existing exchange diagnostic unchanged when the reason is absent", async () => {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockResolvedValueOnce(errorResponse(403, "agent_not_granted"))
runWidget({ "data-encrypted-context": GRANT })
await vi.waitFor(() => expect(errorSpy).toHaveBeenCalledWith(
"Xagent Widget: chat unavailable [agent_not_granted] (HTTP 403).",
))
})
it("logs the registered reconnect diagnostic reason without forwarding it to the iframe", async () => {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock
.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
.mockResolvedValueOnce(jsonResponse(403, {
error: {
code: "agent_not_granted",
reason: "origin_not_allowed",
message: "remote diagnostic must not be logged",
},
}))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await flushAsync()
fromIframe("ready")
post.mockClear()
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.waitFor(() => expect(errorSpy).toHaveBeenCalledWith(
"Xagent Widget: chat unavailable [agent_not_granted/origin_not_allowed] (HTTP 403).",
))
expect(post).toHaveBeenCalledWith({
xagent: true,
v: 1,
type: "session_terminal",
code: "agent_not_granted",
}, HOST)
})
it.each([
["root array", () => ["agent_not_granted", "origin_not_allowed"], "unexpected_error"],
["missing error", () => ({}), "unexpected_error"],
["null error", () => ({ error: null }), "unexpected_error"],
["error array", () => ({ error: ["agent_not_granted", "origin_not_allowed"] }), "unexpected_error"],
["non-string code", () => ({ error: { code: 42, reason: "origin_not_allowed", message: "sentinel" } }), "unexpected_error"],
["non-string code array", () => ({ error: { code: ["agent_not_granted"], reason: "origin_not_allowed", message: "sentinel" } }), "unexpected_error"],
["missing reason", () => ({ error: { code: "agent_not_granted", message: "sentinel" } }), "agent_not_granted"],
["null reason", () => ({ error: { code: "agent_not_granted", reason: null, message: "sentinel" } }), "agent_not_granted"],
["non-string reason", () => ({ error: { code: "agent_not_granted", reason: 42, message: "sentinel" } }), "agent_not_granted"],
["non-string reason array", () => ({ error: { code: "agent_not_granted", reason: ["origin_not_allowed"], message: "sentinel" } }), "agent_not_granted"],
["unregistered reason", () => ({ error: { code: "agent_not_granted", reason: "future_reason", message: "sentinel" } }), "agent_not_granted"],
["prototype-key reason", () => ({ error: { code: "agent_not_granted", reason: "toString", message: "sentinel" } }), "agent_not_granted"],
])("suppresses an untrusted %s diagnostic component from a JSON response", async (_case, makeData, expectedCode) => {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockResolvedValueOnce(jsonResponse(403, makeData()))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.waitFor(() => expect(errorSpy).toHaveBeenCalledWith(
`Xagent Widget: chat unavailable [${expectedCode}] (HTTP 403).`,
))
expect(errorSpy).not.toHaveBeenCalledWith(expect.stringContaining("origin_not_allowed"))
expect(errorSpy).not.toHaveBeenCalledWith(expect.stringContaining("sentinel"))
fromIframe("ready")
expect(post.mock.calls[0][0]).toMatchObject({ type: "session_terminal", code: expectedCode })
})
it("fails closed on null-prototype response objects", async () => {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
const error = Object.assign(Object.create(null), {
code: "agent_not_granted",
reason: "origin_not_allowed",
})
const data = Object.assign(Object.create(null), { error })
fetchMock.mockResolvedValueOnce(directJsonResponse(403, data))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.waitFor(() => expect(errorSpy).toHaveBeenCalledWith(
"Xagent Widget: chat unavailable [unexpected_error] (HTTP 403).",
))
expect(errorSpy).not.toHaveBeenCalledWith(expect.stringContaining("origin_not_allowed"))
fromIframe("ready")
expect(post.mock.calls[0][0]).toMatchObject({ type: "session_terminal", code: "unexpected_error" })
})
it.each([
[
"data.error",
"error",
{ code: "agent_not_granted", reason: "origin_not_allowed" },
() => ({}),
"unexpected_error",
],
[
"error.code",
"code",
"agent_not_granted",
() => ({ error: { reason: "origin_not_allowed" } }),
"unexpected_error",
],
[
"error.reason",
"reason",
"origin_not_allowed",
() => ({ error: { code: "agent_not_granted" } }),
"agent_not_granted",
],
])("suppresses an inherited %s diagnostic component from Object.prototype", async (
_boundary,
property,
inheritedValue,
makeData,
expectedCode,
) => {
const descriptor = Object.getOwnPropertyDescriptor(Object.prototype, property)
Object.defineProperty(Object.prototype, property, {
configurable: true,
writable: true,
value: inheritedValue,
})
try {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockResolvedValueOnce(jsonResponse(403, makeData()))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.waitFor(() => expect(errorSpy).toHaveBeenCalledWith(
`Xagent Widget: chat unavailable [${expectedCode}] (HTTP 403).`,
))
expect(errorSpy).not.toHaveBeenCalledWith(expect.stringContaining("origin_not_allowed"))
fromIframe("ready")
expect(post.mock.calls[0][0]).toMatchObject({ type: "session_terminal", code: expectedCode })
} finally {
if (descriptor) {
Object.defineProperty(Object.prototype, property, descriptor)
} else {
Reflect.deleteProperty(Object.prototype, property)
}
}
})
it("does not retry a coded 4xx and reports unexpected_error for an uncoded one", async () => {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockResolvedValueOnce(new Response("<html>payload too large</html>", { status: 413 }))
runWidget({ "data-encrypted-context": GRANT })
await vi.waitFor(() => expect(errorSpy).toHaveBeenCalledWith(
expect.stringContaining("[unexpected_error] (HTTP 413)"),
))
expect(fetchMock).toHaveBeenCalledTimes(1)
})
it.each([
["grant_malformed", 400],
["encryption_required", 400],
["agent_not_granted", 403],
["agent_not_available", 409],
["widget_disabled", 409],
["invalid_input", 422],
["invalid_runtime_context", 422],
])("goes terminal on %s without retrying", async (code, status) => {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockResolvedValueOnce(errorResponse(status as number, code as string))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.waitFor(() => expect(errorSpy).toHaveBeenCalledWith(
expect.stringContaining(`[${code}] (HTTP ${status})`),
))
expect(fetchMock).toHaveBeenCalledTimes(1)
fromIframe("ready")
expect(post.mock.calls[0][0]).toMatchObject({ type: "session_terminal", code })
})
it.each(["future_code_v2", "toString"])(
"fails closed on the unrecognized error code %s",
async (unknownCode) => {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockResolvedValueOnce(errorResponse(403, unknownCode))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.waitFor(() => expect(errorSpy).toHaveBeenCalledWith(
expect.stringContaining("[unexpected_error] (HTTP 403)"),
))
expect(errorSpy).not.toHaveBeenCalledWith(expect.stringContaining(`[${unknownCode}]`))
fromIframe("ready")
expect(post.mock.calls[0][0]).toMatchObject({ type: "session_terminal", code: "unexpected_error" })
},
)
it("fails closed when a successful response is missing required session fields", async () => {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockResolvedValueOnce(jsonResponse(200, { session_token: "st_only" }))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await flushAsync()
fromIframe("ready")
expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("[unexpected_error] (HTTP 200)"))
expect(post).toHaveBeenCalledWith(
expect.objectContaining({ type: "session_terminal", code: "unexpected_error" }),
HOST,
)
expect(post).not.toHaveBeenCalledWith(
expect.objectContaining({ type: "session_update" }),
HOST,
)
})
it("publishes degraded between retryable parent attempts and resumes the same phase on success", async () => {
vi.useFakeTimers()
fetchMock
.mockResolvedValueOnce(jsonResponse(502, { error: { code: "upstream_unavailable" } }))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({ session_token: "st_recovered" })))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
fromIframe("ready")
await vi.advanceTimersByTimeAsync(0)
expect(fetchMock).toHaveBeenCalledTimes(1)
expect(post).toHaveBeenCalledWith(
expect.objectContaining({ type: "session_degraded", code: "network_unavailable" }),
HOST,
)
await vi.advanceTimersByTimeAsync(1_000)
expect(fetchMock).toHaveBeenCalledTimes(2)
expect(post).toHaveBeenCalledWith(
expect.objectContaining({ type: "session_update", session_token: "st_recovered" }),
HOST,
)
})
it("retries an uncoded 5xx with a 1.5x back-off up to a five-minute cap and never terminalizes", async () => {
vi.useFakeTimers()
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockImplementation(() => Promise.resolve(
new Response("<html>bad gateway</html>", { status: 502 }),
))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.advanceTimersByTimeAsync(0)
expect(fetchMock).toHaveBeenCalledTimes(1)
const delays = [
1_000, 1_500, 2_250, 3_375, 5_063, 7_594, 11_391, 17_086, 25_629, 38_443,
57_665, 86_498, 129_746, 194_620, 291_929, 300_000, 300_000,
]
for (const [index, delay] of delays.entries()) {
await vi.advanceTimersByTimeAsync(delay - 1)
expect(fetchMock).toHaveBeenCalledTimes(index + 1)
await vi.advanceTimersByTimeAsync(1)
expect(fetchMock).toHaveBeenCalledTimes(index + 2)
}
expect(errorSpy).not.toHaveBeenCalled()
fromIframe("ready")
expect(post).toHaveBeenLastCalledWith(
expect.objectContaining({ type: "session_degraded", code: "network_unavailable" }),
HOST,
)
expect(post).not.toHaveBeenCalledWith(
expect.objectContaining({ type: "session_terminal" }),
HOST,
)
})
it.each([
["the low", 0, 800],
["the high", 0.999_999, 1_200],
])("keeps the transport back-off within %s jitter bound", async (_bound, random, delay) => {
vi.useFakeTimers()
vi.mocked(Math.random).mockReturnValue(random)
fetchMock.mockImplementation(() => Promise.resolve(
new Response("<html>bad gateway</html>", { status: 502 }),
))
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(delay - 1)
expect(fetchMock).toHaveBeenCalledTimes(1)
await vi.advanceTimersByTimeAsync(1)
expect(fetchMock).toHaveBeenCalledTimes(2)
})
it("retries an unknown coded 5xx as a transport failure", async () => {
vi.useFakeTimers()
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined)
fetchMock.mockImplementation(() => Promise.resolve(errorResponse(503, "future_server_code")))
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(7000)
expect(fetchMock).toHaveBeenCalledTimes(4)
expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("[network_unavailable]"))
expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining("[future_server_code]"))
expect(errorSpy).not.toHaveBeenCalled()
})
it("keeps unknown-5xx retry warnings and degraded frames code-only", async () => {
vi.useFakeTimers()
const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined)
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockImplementation(() => Promise.resolve(jsonResponse(503, {
error: {
code: "future_server_code",
reason: "origin_not_allowed",
message: "retry diagnostic must not be logged",
},
})))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
fromIframe("ready")
// Attempts at 0, 1, 2.5 and 4.75 s.
await vi.advanceTimersByTimeAsync(7_000)
expect(warnSpy.mock.calls).toEqual([
["Xagent Widget: session recovery is retrying [network_unavailable]."],
["Xagent Widget: session recovery is retrying [network_unavailable]."],
["Xagent Widget: session recovery is retrying [network_unavailable]."],
["Xagent Widget: session recovery is retrying [network_unavailable]."],
])
expect(errorSpy).not.toHaveBeenCalled()
expect(post.mock.calls.map(([message]) => message)).toEqual([
{ xagent: true, v: 1, type: "session_degraded", code: "network_unavailable" },
{ xagent: true, v: 1, type: "session_degraded", code: "network_unavailable" },
{ xagent: true, v: 1, type: "session_degraded", code: "network_unavailable" },
{ xagent: true, v: 1, type: "session_degraded", code: "network_unavailable" },
])
})
it("retries a server-supplied network_unavailable 5xx as an unknown transport failure", async () => {
vi.useFakeTimers()
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockImplementation(() => Promise.resolve(errorResponse(503, "network_unavailable")))
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(7_000)
expect(fetchMock).toHaveBeenCalledTimes(4)
expect(errorSpy).not.toHaveBeenCalled()
})
it("honors a known error code on 5xx without status-based retry", async () => {
vi.useFakeTimers()
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockImplementation(() => Promise.resolve(errorResponse(503, "widget_disabled")))
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(7000)
expect(fetchMock).toHaveBeenCalledTimes(1)
expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("[widget_disabled] (HTTP 503)"))
})
it("fails closed on an uncoded 429 instead of guessing rate_limited", async () => {
vi.useFakeTimers()
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockImplementation(() => Promise.resolve(
new Response("<html>too many requests</html>", { status: 429 }),
))
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(3000)
expect(fetchMock).toHaveBeenCalledTimes(1)
expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("[unexpected_error] (HTTP 429)"))
})
it("treats a rejected fetch as the network class", async () => {
vi.useFakeTimers()
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined)
fetchMock.mockRejectedValue(new TypeError("Failed to fetch"))
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(7000)
expect(fetchMock).toHaveBeenCalledTimes(4)
expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("[network_unavailable]"))
expect(errorSpy).not.toHaveBeenCalled()
})
it("aborts each attempt after 5s and keeps retrying", async () => {
vi.useFakeTimers()
const signals: AbortSignal[] = []
fetchMock.mockImplementation((_url: string, init: RequestInit) => {
signals.push(init.signal as AbortSignal)
return new Promise((_resolve, reject) => {
(init.signal as AbortSignal).addEventListener("abort", () => reject(new DOMException("aborted", "AbortError")))
})
})
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(5000)
expect(signals[0].aborted).toBe(true)
expect(fetchMock).toHaveBeenCalledTimes(1)
// Attempts at 6, 12.5, 19.75 and 28.125 s, past the old 30 s budget.
await vi.advanceTimersByTimeAsync(23_125)
expect(fetchMock).toHaveBeenCalledTimes(5)
expect(signals.slice(0, 4).every((signal) => signal.aborted)).toBe(true)
expect(signals[4].aborted).toBe(false)
})
it("keeps the 5s deadline active while the response body is being read", async () => {
vi.useFakeTimers()
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
const signals: AbortSignal[] = []
fetchMock.mockImplementation((_url: string, init: RequestInit) => {
const signal = init.signal as AbortSignal
signals.push(signal)
const body = new ReadableStream<Uint8Array>({
start(controller) {
signal.addEventListener("abort", () => {
controller.error(new DOMException("aborted", "AbortError"))
}, { once: true })
},
})
return Promise.resolve(new Response(body, {
status: 200,
headers: { "Content-Type": "application/json" },
}))
})
runWidget({ "data-encrypted-context": GRANT })
// Attempts at 0, 6, 12.5 and 19.75 s; the last one is aborted at 24.75 s.
await vi.advanceTimersByTimeAsync(27_000)
expect(fetchMock).toHaveBeenCalledTimes(4)
expect(signals).toHaveLength(4)
expect(signals.every((signal) => signal.aborted)).toBe(true)
expect(errorSpy).not.toHaveBeenCalled()
})
it("honors Retry-After on 429 at most twice", async () => {
vi.useFakeTimers()
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockImplementation(() => Promise.resolve(
jsonResponse(429, { error: { code: "rate_limited" } }, { "Retry-After": "3" }),
))
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(0)
expect(fetchMock).toHaveBeenCalledTimes(1)
await vi.advanceTimersByTimeAsync(3000)
expect(fetchMock).toHaveBeenCalledTimes(2)
await vi.advanceTimersByTimeAsync(3000)
expect(fetchMock).toHaveBeenCalledTimes(3)
await vi.advanceTimersByTimeAsync(3000)
expect(fetchMock).toHaveBeenCalledTimes(3)
expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("[rate_limited] (HTTP 429)"))
})
it("keeps rate-limit retry warnings and degraded frames code-only", async () => {
vi.useFakeTimers()
const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined)
fetchMock.mockImplementation(() => Promise.resolve(jsonResponse(429, {
error: {
code: "rate_limited",
reason: "origin_not_allowed",
message: "retry diagnostic must not be logged",
},
}, { "Retry-After": "1" })))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
fromIframe("ready")
await vi.advanceTimersByTimeAsync(0)
expect(warnSpy).toHaveBeenCalledWith(
"Xagent Widget: session recovery is retrying [rate_limited].",
)
expect(post).toHaveBeenCalledWith(
{ xagent: true, v: 1, type: "session_degraded", code: "rate_limited" },
HOST,
)
})
it("honors an HTTP-date Retry-After value", async () => {
vi.useFakeTimers()
vi.setSystemTime(new Date("2026-07-27T00:00:00Z"))
fetchMock.mockImplementation(() => Promise.resolve(jsonResponse(
429,
{ error: { code: "rate_limited" } },
{ "Retry-After": "Mon, 27 Jul 2026 00:00:03 GMT" },
)))
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(2999)
expect(fetchMock).toHaveBeenCalledTimes(1)
await vi.advanceTimersByTimeAsync(1)
expect(fetchMock).toHaveBeenCalledTimes(2)
})
it.each([
["a negative value", "-1"],
["a malformed value", "not-a-date"],
["a missing value", undefined],
])("uses the retry fallback for %s", async (_case, retryAfter) => {
vi.useFakeTimers()
fetchMock.mockImplementation(() => Promise.resolve(jsonResponse(
429,
{ error: { code: "rate_limited" } },
retryAfter ? { "Retry-After": retryAfter } : {},
)))
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(999)
expect(fetchMock).toHaveBeenCalledTimes(1)
await vi.advanceTimersByTimeAsync(1)
expect(fetchMock).toHaveBeenCalledTimes(2)
})
it("keeps the rate-limit budget separate from transport retries", async () => {
vi.useFakeTimers()
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
const rateLimited = () => jsonResponse(
429,
{ error: { code: "rate_limited" } },
{ "Retry-After": "3" },
)
fetchMock
.mockResolvedValueOnce(rateLimited())
.mockResolvedValueOnce(rateLimited())
.mockResolvedValueOnce(new Response("<html>bad gateway</html>", { status: 502 }))
.mockResolvedValueOnce(new Response("<html>bad gateway</html>", { status: 502 }))
.mockResolvedValueOnce(rateLimited())
runWidget({ "data-encrypted-context": GRANT })
// Attempts at 0 and 3 s (429), 6 and 7 s (502), then a third 429 at 8.5 s.
await vi.advanceTimersByTimeAsync(30_000)
expect(fetchMock).toHaveBeenCalledTimes(5)
expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("[rate_limited] (HTTP 429)"))
expect(vi.getTimerCount()).toBe(0)
})
it("does not schedule a 429 retry beyond the exchange deadline", async () => {
vi.useFakeTimers()
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockImplementation(() => Promise.resolve(jsonResponse(
429,
{ error: { code: "rate_limited" } },
{ "Retry-After": "31" },
)))
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(30_000)
expect(fetchMock).toHaveBeenCalledTimes(1)
expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("[rate_limited] (HTTP 429)"))
expect(vi.getTimerCount()).toBe(0)
})
it("coalesces concurrent reconnect requests into a single call and one broadcast", async () => {
fetchMock
.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({
session_token: "st_second",
reconnect_token: "rt_second",
})))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
await flushAsync()
fromIframe("ready")
post.mockClear()
fromIframe("reconnect_request", { reason: "ws_closed" })
fromIframe("reconnect_request", { reason: "ws_closed" })
fromIframe("reconnect_request", { reason: "token_expired" })
await vi.waitFor(() => expect(post).toHaveBeenCalled())
expect(fetchMock).toHaveBeenCalledTimes(2) // one exchange + one reconnect
expect(fetchMock.mock.calls[1][0]).toBe(RECONNECT_URL)
expect(JSON.parse(fetchMock.mock.calls[1][1].body)).toEqual({
reconnect_token: "rt_first",
encrypted_context: GRANT,
})
expect(post).toHaveBeenCalledTimes(1)
expect(post.mock.calls[0][0]).toMatchObject({ session_token: "st_second" })
})
it("restarts a frozen stale-session reconnect with the held reconnect token", async () => {
let frozenReconnectSignal: AbortSignal | undefined
fetchMock
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({
session_token_expires_at: new Date(Date.now() + 30_000).toISOString(),
})))
.mockImplementationOnce((_url: string, init: RequestInit) => {
frozenReconnectSignal = init.signal as AbortSignal
return new Promise(() => undefined)
})
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({
session_token: "st_recovered",
reconnect_token: "rt_recovered",
})))
runWidget({ "data-encrypted-context": GRANT })
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
await flushAsync()
const post = spyOnIframePostMessage()
fromIframe("ready")
post.mockClear()
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2))
firePageRestore()
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(3))
expect(frozenReconnectSignal?.aborted).toBe(true)
expect(fetchMock.mock.calls.map((call) => call[0])).toEqual([
EXCHANGE_URL,
RECONNECT_URL,
RECONNECT_URL,
])
expect(JSON.parse(fetchMock.mock.calls[2][1].body)).toEqual({
reconnect_token: "rt_first",
encrypted_context: GRANT,
})
await vi.waitFor(() => expect(post).toHaveBeenCalledWith(
expect.objectContaining({ type: "session_update", session_token: "st_recovered" }),
HOST,
))
})
it("keeps reconnect requests joined to the replacement exchange across bfcache", async () => {
let resolveFirstExchange: (value: Response) => void = () => undefined
let resolveSecondExchange: (value: Response) => void = () => undefined
let firstExchangeSignal: AbortSignal | undefined
fetchMock
.mockImplementationOnce((_url: string, init: RequestInit) => new Promise<Response>((resolve) => {
resolveFirstExchange = resolve
firstExchangeSignal = init.signal as AbortSignal
}))
.mockImplementationOnce(() => new Promise<Response>((resolve) => {
resolveSecondExchange = resolve
}))
runWidget({ "data-encrypted-context": GRANT })
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
fromIframe("reconnect_request", { reason: "ws_closed" })
firePageRestore()
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2))
expect(firstExchangeSignal?.aborted).toBe(true)
resolveFirstExchange(jsonResponse(200, exchangeBody({
session_token: "st_old",
reconnect_token: "rt_old",
})))
await flushAsync()
fromIframe("reconnect_request", { reason: "token_expired" })
resolveSecondExchange(jsonResponse(200, exchangeBody({
session_token: "st_new",
reconnect_token: "rt_new",
})))
await flushAsync()
expect(fetchMock).toHaveBeenCalledTimes(2)
})
it("keeps the last healthy session without replaying a frozen reconnect", async () => {
vi.useFakeTimers()
vi.spyOn(console, "error").mockImplementation(() => undefined)
let frozenReconnectSignal: AbortSignal | undefined
fetchMock
.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
.mockImplementationOnce((_url: string, init: RequestInit) => {
frozenReconnectSignal = init.signal as AbortSignal
return new Promise(() => undefined)
})
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(0)
const post = spyOnIframePostMessage()
fromIframe("ready")
post.mockClear()
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.advanceTimersByTimeAsync(0)
firePageRestore()
await vi.advanceTimersByTimeAsync(7_000)
expect(frozenReconnectSignal?.aborted).toBe(true)
expect(fetchMock.mock.calls.map((call) => call[0])).toEqual([
EXCHANGE_URL,
RECONNECT_URL,
])
expect(post).toHaveBeenCalledWith(
expect.objectContaining({ type: "session_update", session_token: "st_first" }),
HOST,
)
expect(post).not.toHaveBeenCalledWith(
expect.objectContaining({ type: "session_degraded" }),
HOST,
)
})
it("never fires a deferred reconnect once the exchange it waited on goes terminal", async () => {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockResolvedValueOnce(errorResponse(409, "widget_disabled"))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
// Make the frame ready while the exchange is still pending so both the
// terminal transition and a deferred reconnect continuation could flush.
fromIframe("ready")
// reconnect_request arrives while the exchange is still in flight (its
// response hasn't been parsed yet), so it coalesces via singleFlight and
// defers its own network call until the exchange settles.
fromIframe("reconnect_request", { reason: "ws_closed" })
// The exchange settles into a terminal error.
await vi.waitFor(() => expect(errorSpy).toHaveBeenCalledWith(
expect.stringContaining("[widget_disabled]"),
))
await vi.waitFor(() => expect(post).toHaveBeenCalled())
// Give the deferred reconnect's `wait.then` callback a turn to run: it
// only wakes up after singleFlight clears state.inflight.exchange, which
// happens one more microtask turn after handleResult/goTerminal return.
await Promise.resolve()
await Promise.resolve()
// The deferred reconnect must re-check the terminal latch before firing
// its network call and bail out instead — no second (reconnect) fetch,
// ever, and every broadcast the frame receives is the terminal one.
expect(fetchMock).toHaveBeenCalledTimes(1)
for (const call of post.mock.calls) {
expect(call[0]).toMatchObject({ type: "session_terminal", code: "widget_disabled" })
}
expect(post).toHaveBeenCalledTimes(1)
})
it("answers reconnect_request from a latched terminal state without any network call", async () => {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockResolvedValueOnce(errorResponse(409, "widget_disabled"))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
// Wait for the exchange to actually finish failing (terminal latch set),
// not just for fetch() to have been called — the response body still
// needs to be parsed asynchronously before goTerminal() runs.
await vi.waitFor(() => expect(errorSpy).toHaveBeenCalledWith(
expect.stringContaining("[widget_disabled]"),
))
fromIframe("ready")
post.mockClear()
fromIframe("reconnect_request", { reason: "ws_closed" })
fromIframe("reconnect_request", { reason: "ws_closed" })
expect(fetchMock).toHaveBeenCalledTimes(1)
expect(post).toHaveBeenCalledTimes(2)
expect(post.mock.calls[0][0]).toMatchObject({ type: "session_terminal", code: "widget_disabled" })
})
it("reconnects before handing the frame a token with under 60s left", async () => {
fetchMock
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({
session_token_expires_at: new Date(Date.now() + 30_000).toISOString(),
})))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({ session_token: "st_fresh" })))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
fromIframe("ready")
await vi.waitFor(() => expect(post).toHaveBeenCalled())
expect(fetchMock).toHaveBeenCalledTimes(2)
expect(fetchMock.mock.calls[1][0]).toBe(RECONNECT_URL)
expect(post).toHaveBeenCalledTimes(1)
expect(post.mock.calls[0][0]).toMatchObject({ session_token: "st_fresh" })
})
it.each([
["reconnect_invalid", 401],
["session_expired", 401],
["identity_mismatch", 403],
])("goes terminal on %s from the reconnect endpoint without retrying", async (code, status) => {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock
.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
.mockResolvedValueOnce(errorResponse(status as number, code as string))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
await flushAsync()
fromIframe("ready")
post.mockClear()
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.waitFor(() => expect(errorSpy).toHaveBeenCalledWith(
expect.stringContaining(`[${code}] (HTTP ${status})`),
))
expect(fetchMock).toHaveBeenCalledTimes(2)
expect(fetchMock.mock.calls[1][0]).toBe(RECONNECT_URL)
fromIframe("ready")
expect(post).toHaveBeenCalledWith(
expect.objectContaining({ type: "session_terminal", code }),
HOST,
)
})
it("uses the same transport back-off on the reconnect endpoint", async () => {
vi.useFakeTimers()
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.advanceTimersByTimeAsync(0)
expect(fetchMock).toHaveBeenCalledTimes(1)
fetchMock.mockImplementation(() => Promise.resolve(
new Response("<html>bad gateway</html>", { status: 502 }),
))
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.advanceTimersByTimeAsync(0)
expect(fetchMock).toHaveBeenCalledTimes(2)
expect(fetchMock.mock.calls[1][0]).toBe(RECONNECT_URL)
for (const [index, delay] of [1_000, 1_500, 2_250, 3_375].entries()) {
await vi.advanceTimersByTimeAsync(delay - 1)
expect(fetchMock).toHaveBeenCalledTimes(index + 2)
await vi.advanceTimersByTimeAsync(1)
expect(fetchMock).toHaveBeenCalledTimes(index + 3)
}
fetchMock.mockResolvedValueOnce(jsonResponse(200, exchangeBody({
session_token: "st_second",
reconnect_token: "rt_second",
})))
await vi.advanceTimersByTimeAsync(5_063)
expect(fetchMock.mock.calls.filter(([url]) => url === RECONNECT_URL)).toHaveLength(6)
fromIframe("ready")
expect(post).toHaveBeenLastCalledWith(
expect.objectContaining({ type: "session_update", session_token: "st_second" }),
HOST,
)
expect(errorSpy).not.toHaveBeenCalled()
})
it("restarts a restored reconnect at once and continues its back-off", async () => {
vi.useFakeTimers()
let fourthSignal: AbortSignal | undefined
fetchMock
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({
session_token_expires_at: new Date(Date.now() + 30_000).toISOString(),
})))
.mockResolvedValueOnce(jsonResponse(502, { error: { code: "upstream_unavailable" } }))
.mockResolvedValueOnce(jsonResponse(502, { error: { code: "upstream_unavailable" } }))
.mockResolvedValueOnce(jsonResponse(502, { error: { code: "upstream_unavailable" } }))
.mockImplementationOnce((_url: string, init: RequestInit) => {
fourthSignal = init.signal as AbortSignal
return new Promise<Response>(() => undefined)
})
.mockResolvedValue(jsonResponse(502, { error: { code: "upstream_unavailable" } }))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.advanceTimersByTimeAsync(0)
fromIframe("ready")
await vi.advanceTimersByTimeAsync(7_000)
expect(fetchMock.mock.calls.filter(([url]) => url === RECONNECT_URL)).toHaveLength(4)
firePageRestore()
await vi.advanceTimersByTimeAsync(0)
expect(fourthSignal?.aborted).toBe(true)
expect(fetchMock.mock.calls.filter(([url]) => url === RECONNECT_URL)).toHaveLength(5)
// The fifth failure waits the fourth back-off step, not the first.
await vi.advanceTimersByTimeAsync(3_374)
expect(fetchMock.mock.calls.filter(([url]) => url === RECONNECT_URL)).toHaveLength(5)
await vi.advanceTimersByTimeAsync(1)
expect(fetchMock.mock.calls.filter(([url]) => url === RECONNECT_URL)).toHaveLength(6)
expect(post).not.toHaveBeenCalledWith(
expect.objectContaining({ type: "session_terminal" }),
HOST,
)
})
it("continues a restored reconnect's back-off where it was", async () => {
vi.useFakeTimers()
let secondSignal: AbortSignal | undefined
fetchMock
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({
session_token_expires_at: new Date(Date.now() + 30_000).toISOString(),
})))
.mockResolvedValueOnce(jsonResponse(502, { error: { code: "upstream_unavailable" } }))
.mockImplementationOnce((_url: string, init: RequestInit) => {
secondSignal = init.signal as AbortSignal
return new Promise<Response>((_resolve, reject) => {
;(init.signal as AbortSignal).addEventListener(
"abort",
() => reject(new DOMException("aborted", "AbortError")),
{ once: true },
)
})
})
.mockResolvedValue(jsonResponse(502, { error: { code: "upstream_unavailable" } }))
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(0)
fromIframe("ready")
await vi.advanceTimersByTimeAsync(1_000)
expect(fetchMock.mock.calls.filter(([url]) => url === RECONNECT_URL)).toHaveLength(2)
firePageRestore()
await vi.advanceTimersByTimeAsync(0)
expect(secondSignal?.aborted).toBe(true)
expect(fetchMock.mock.calls.filter(([url]) => url === RECONNECT_URL)).toHaveLength(3)
await vi.advanceTimersByTimeAsync(1_499)
expect(fetchMock.mock.calls.filter(([url]) => url === RECONNECT_URL)).toHaveLength(3)
await vi.advanceTimersByTimeAsync(1)
expect(fetchMock.mock.calls.filter(([url]) => url === RECONNECT_URL)).toHaveLength(4)
})
it("restarts a reconnect restored after a long bfcache suspension", async () => {
vi.useFakeTimers()
const startedAt = new Date("2026-07-28T00:00:00.000Z")
vi.setSystemTime(startedAt)
const reconnectSignals: AbortSignal[] = []
fetchMock
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({
session_token_expires_at: new Date(startedAt.getTime() + 30_000).toISOString(),
})))
.mockImplementation((_url: string, init: RequestInit) => {
reconnectSignals.push(init.signal as AbortSignal)
return new Promise<Response>(() => undefined)
})
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.advanceTimersByTimeAsync(0)
fromIframe("ready")
await vi.advanceTimersByTimeAsync(0)
expect(fetchMock.mock.calls.filter(([url]) => url === RECONNECT_URL)).toHaveLength(1)
firePageHide(true)
vi.setSystemTime(new Date(startedAt.getTime() + 31_000))
firePageShow(true)
await vi.advanceTimersByTimeAsync(0)
expect(reconnectSignals[0]?.aborted).toBe(true)
expect(reconnectSignals[1]?.aborted).toBe(false)
expect(fetchMock.mock.calls.filter(([url]) => url === RECONNECT_URL)).toHaveLength(2)
expect(post).not.toHaveBeenCalledWith(
expect.objectContaining({ type: "session_terminal" }),
HOST,
)
})
it("starts a fresh retry lineage after success rotates the reconnect token", async () => {
vi.useFakeTimers()
fetchMock
.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
.mockResolvedValueOnce(jsonResponse(502, { error: { code: "upstream_unavailable" } }))
.mockResolvedValueOnce(jsonResponse(502, { error: { code: "upstream_unavailable" } }))
.mockResolvedValueOnce(jsonResponse(502, { error: { code: "upstream_unavailable" } }))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({
session_token: "st_second",
reconnect_token: "rt_second",
})))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({
session_token: "st_third",
reconnect_token: "rt_third",
})))
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(0)
fromIframe("ready")
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.advanceTimersByTimeAsync(7_000)
expect(fetchMock.mock.calls.filter(([url]) => url === RECONNECT_URL)).toHaveLength(4)
fromIframe("reconnect_request", { reason: "token_expired" })
await vi.advanceTimersByTimeAsync(0)
const reconnectCalls = fetchMock.mock.calls.filter(([url]) => url === RECONNECT_URL)
expect(reconnectCalls).toHaveLength(5)
expect(JSON.parse(reconnectCalls[4][1].body)).toMatchObject({ reconnect_token: "rt_second" })
})
it("allows two rate-limit retries inside the shared reconnect budget", async () => {
vi.useFakeTimers()
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(0)
fetchMock.mockImplementation(() => Promise.resolve(jsonResponse(
429,
{ error: { code: "rate_limited" } },
{ "Retry-After": "1" },
)))
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.advanceTimersByTimeAsync(3_000)
expect(fetchMock).toHaveBeenCalledTimes(4)
expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("[rate_limited] (HTTP 429)"))
expect(vi.getTimerCount()).toBe(0)
})
it("ignores a late duplicate exchange response after the session moved on", async () => {
// Fake timers must be installed before runWidget() schedules postJson's
// SESSION_TIMEOUT_MS abort timer, or advanceTimersByTimeAsync below has
// nothing to advance and the real timer never fires within the test.
vi.useFakeTimers()
let resolveLate: (value: Response) => void = () => undefined
fetchMock
// The first attempt hangs until the client gives up: postJson's own
// AbortController fires at SESSION_TIMEOUT_MS, and this mock (like the
// "aborts an attempt" test above) must react to that signal the way a
// real fetch would, or withRetry never sees this attempt settle and
// never starts the retry that's supposed to win the race.
.mockImplementationOnce((_url: string, init: RequestInit) => new Promise<Response>((resolve, reject) => {
resolveLate = resolve
;(init.signal as AbortSignal).addEventListener("abort", () => reject(new DOMException("aborted", "AbortError")))
}))
.mockResolvedValueOnce(jsonResponse(200, exchangeBody({ session_token: "st_real" })))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
fromIframe("ready")
// The first attempt times out and the retry wins.
await vi.advanceTimersByTimeAsync(6000)
await vi.waitFor(() => expect(post).toHaveBeenCalled())
vi.useRealTimers()
post.mockClear()
resolveLate(jsonResponse(200, exchangeBody({ session_token: "st_stale", reconnect_token: "rt_stale" })))
await Promise.resolve()
expect(post).not.toHaveBeenCalled()
})
it("cancels a frozen exchange before starting bfcache recovery", async () => {
let resolveFirst: (value: Response) => void = () => undefined
let firstSignal: AbortSignal | undefined
fetchMock.mockImplementationOnce((_url: string, init: RequestInit) => new Promise<Response>((resolve) => {
resolveFirst = resolve
firstSignal = init.signal as AbortSignal
}))
runWidget({ "data-encrypted-context": GRANT })
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
fetchMock.mockResolvedValueOnce(jsonResponse(200, exchangeBody({ session_token: "st_second" })))
firePageRestore()
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2))
expect(firstSignal?.aborted).toBe(true)
const post = spyOnIframePostMessage()
await flushAsync()
fromIframe("ready")
expect(post).toHaveBeenCalledTimes(1)
expect(post.mock.calls[0][0]).toMatchObject({ session_token: "st_second" })
post.mockClear()
resolveFirst(jsonResponse(200, exchangeBody({ session_token: "st_stale", reconnect_token: "rt_stale" })))
await flushAsync()
expect(post).not.toHaveBeenCalled()
fromIframe("ready")
expect(post).toHaveBeenCalledTimes(1)
expect(post.mock.calls[0][0]).toMatchObject({ session_token: "st_second" })
})
it("restarts a restored exchange at once and continues its back-off", async () => {
vi.useFakeTimers()
let fourthSignal: AbortSignal | undefined
fetchMock
.mockResolvedValueOnce(jsonResponse(502, { error: { code: "upstream_unavailable" } }))
.mockResolvedValueOnce(jsonResponse(502, { error: { code: "upstream_unavailable" } }))
.mockResolvedValueOnce(jsonResponse(502, { error: { code: "upstream_unavailable" } }))
.mockImplementationOnce((_url: string, init: RequestInit) => {
fourthSignal = init.signal as AbortSignal
return new Promise<Response>(() => undefined)
})
.mockResolvedValue(jsonResponse(502, { error: { code: "upstream_unavailable" } }))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
fromIframe("ready")
await vi.advanceTimersByTimeAsync(7_000)
expect(fetchMock).toHaveBeenCalledTimes(4)
firePageRestore()
await vi.advanceTimersByTimeAsync(0)
expect(fourthSignal?.aborted).toBe(true)
expect(fetchMock).toHaveBeenCalledTimes(5)
expect(fetchMock.mock.calls[4][0]).toBe(EXCHANGE_URL)
await vi.advanceTimersByTimeAsync(3_374)
expect(fetchMock).toHaveBeenCalledTimes(5)
await vi.advanceTimersByTimeAsync(1)
expect(fetchMock).toHaveBeenCalledTimes(6)
expect(post).not.toHaveBeenCalledWith(
expect.objectContaining({ type: "session_terminal" }),
HOST,
)
})
it("joins the initial exchange for reconnect requests before a reconnect token exists", async () => {
let resolveExchange: (value: Response) => void = () => undefined
fetchMock.mockImplementationOnce(() => new Promise<Response>((resolve) => {
resolveExchange = resolve
}))
runWidget({ "data-encrypted-context": GRANT })
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
fromIframe("reconnect_request", { reason: "ws_closed" })
resolveExchange(jsonResponse(200, exchangeBody()))
await flushAsync()
expect(fetchMock).toHaveBeenCalledTimes(1)
})
it("keeps the iframe nonterminal through a parent-owned 24-second recovery and resumes on the fourth response", async () => {
vi.useFakeTimers()
let resolveFourth: (value: Response) => void = () => undefined
const rejectOnAbort = (_url: string, init: RequestInit) => new Promise<Response>((_resolve, reject) => {
;(init.signal as AbortSignal).addEventListener("abort", () => {
reject(new DOMException("aborted", "AbortError"))
}, { once: true })
})
fetchMock
.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
.mockImplementationOnce(rejectOnAbort)
.mockImplementationOnce(rejectOnAbort)
.mockImplementationOnce(rejectOnAbort)
.mockImplementationOnce(() => new Promise<Response>((resolve) => {
resolveFourth = resolve
}))
runWidget({ "data-encrypted-context": GRANT })
const frame = iframeEl()
if (!frame) throw new Error("iframe not mounted")
const bridge = bridgeWidgetSessionHook(frame)
const { result } = renderHook(() => useWidgetSession())
await vi.advanceTimersByTimeAsync(0)
expect(result.current.status).toBe("active")
act(() => result.current.requestReconnect("ws_closed"))
expect(bridge.parent.postMessage.mock.calls.filter(
([message]) => message.type === "reconnect_request",
)).toHaveLength(1)
// Reconnect attempts at 0, 6, 12.5 and 19.75 s.
await vi.advanceTimersByTimeAsync(22_000)
expect(fetchMock).toHaveBeenCalledTimes(5)
expect(fetchMock.mock.calls.filter(([url]) => url === RECONNECT_URL)).toHaveLength(4)
expect(result.current.status).toBe("degraded")
expect(result.current.terminalCode).toBeNull()
expect(bridge.parent.postMessage.mock.calls.filter(
([message]) => message.type === "reconnect_request",
)).toHaveLength(1)
await vi.advanceTimersByTimeAsync(2_000)
expect(result.current.status).toBe("degraded")
expect(result.current.terminalCode).toBeNull()
fromIframe("ready")
expect(fetchMock).toHaveBeenCalledTimes(5)
expect(result.current.status).toBe("degraded")
expect(result.current.terminalCode).toBeNull()
resolveFourth(jsonResponse(200, exchangeBody({ session_token: "st_fourth" })))
await vi.advanceTimersByTimeAsync(0)
expect(result.current.status).toBe("active")
expect(result.current.session?.token).toBe("st_fourth")
expect(result.current.terminalCode).toBeNull()
})
it("recovers a widget left open across a two-minute backend restart", async () => {
vi.useFakeTimers()
let backendUp = true
fetchMock.mockImplementation(() => {
if (!backendUp) return Promise.reject(new TypeError("Failed to fetch"))
return Promise.resolve(jsonResponse(200, exchangeBody({
session_token: "st_recovered",
reconnect_token: "rt_recovered",
})))
})
runWidget({ "data-encrypted-context": GRANT })
const frame = iframeEl()
if (!frame) throw new Error("iframe not mounted")
const bridge = bridgeWidgetSessionHook(frame)
const { result } = renderHook(() => useWidgetSession())
await vi.advanceTimersByTimeAsync(0)
expect(result.current.status).toBe("active")
// The Session WebSocket drops (1012/1006) and every request fails for 130 s.
backendUp = false
act(() => result.current.requestReconnect("ws_closed"))
await vi.advanceTimersByTimeAsync(130_000)
expect(result.current.status).toBe("degraded")
expect(result.current.terminalCode).toBeNull()
backendUp = true
// The next attempt after the restart runs at about 171 s.
await vi.advanceTimersByTimeAsync(60_000)
expect(result.current.status).toBe("active")
expect(result.current.session?.token).toBe("st_recovered")
expect(bridge.parent.postMessage.mock.calls.filter(
([message]) => message.type === "reconnect_request",
)).toHaveLength(1)
expect(bridge.postToIframe.mock.calls.filter(
([message]) => (message as Record<string, unknown>).type === "session_terminal",
)).toHaveLength(0)
})
it.each([
["a timed-out attempt", "timeout", 10_000],
["an uncoded 504", "504", 10_000],
["an uncoded 502", "502", 57_665],
] as const)("waits for the next attempt after %s late in an outage", async (_case, failure, nextDelay) => {
vi.useFakeTimers()
// Ten refused connections push the back-off to 38.4 s; the eleventh
// attempt fails as `failure` at 113.3 s.
fetchMock.mockImplementation((_url: string, init: RequestInit) => {
const call = fetchMock.mock.calls.length
if (call <= 10 || call > 11) return Promise.reject(new TypeError("Failed to fetch"))
if (failure === "504") return Promise.resolve(new Response("<html>gateway timeout</html>", { status: 504 }))
if (failure === "502") return Promise.resolve(new Response("<html>bad gateway</html>", { status: 502 }))
return new Promise<Response>((_resolve, reject) => {
;(init.signal as AbortSignal).addEventListener(
"abort",
() => reject(new DOMException("aborted", "AbortError")),
{ once: true },
)
})
})
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(113_331)
expect(fetchMock).toHaveBeenCalledTimes(11)
if (failure === "timeout") await vi.advanceTimersByTimeAsync(5_000)
await vi.advanceTimersByTimeAsync(nextDelay - 1)
expect(fetchMock).toHaveBeenCalledTimes(11)
await vi.advanceTimersByTimeAsync(1)
expect(fetchMock).toHaveBeenCalledTimes(12)
// A refused connection afterwards resumes the long back-off.
await vi.advanceTimersByTimeAsync(86_497)
expect(fetchMock).toHaveBeenCalledTimes(12)
await vi.advanceTimersByTimeAsync(1)
expect(fetchMock).toHaveBeenCalledTimes(13)
})
it("points at CSP and CORS once when fetches keep being rejected", async () => {
vi.useFakeTimers()
const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined)
fetchMock.mockRejectedValue(new TypeError("Failed to fetch"))
runWidget({ "data-encrypted-context": GRANT })
// Attempts at 0, 1, 2.5, 4.75, 8.125 and 13.188 s; the sixth is the first
// to fail after five retries.
await vi.advanceTimersByTimeAsync(13_187)
expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining("Content-Security-Policy"))
await vi.advanceTimersByTimeAsync(1)
const hint = `Xagent Widget: session requests keep failing before reaching ${HOST}; `
+ "if the backend is up, check that the page's Content-Security-Policy connect-src "
+ "and CORS allow it [network_unavailable]."
expect(warnSpy).toHaveBeenCalledWith(hint)
await vi.advanceTimersByTimeAsync(120_000)
expect(warnSpy.mock.calls.filter(([message]) => message === hint)).toHaveLength(1)
})
it("does not point at CSP and CORS for server errors", async () => {
vi.useFakeTimers()
const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined)
fetchMock.mockImplementation(() => Promise.resolve(
new Response("<html>bad gateway</html>", { status: 502 }),
))
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(120_000)
expect(warnSpy).toHaveBeenCalled()
expect(warnSpy).not.toHaveBeenCalledWith(expect.stringContaining("Content-Security-Policy"))
})
it.each([
["the page becomes visible", () => {
Object.defineProperty(document, "visibilityState", { configurable: true, value: "visible" })
document.dispatchEvent(new Event("visibilitychange"))
}],
["the network comes back", () => window.dispatchEvent(new Event("online"))],
])("retries a waiting transport failure at once when %s", async (_case, wake) => {
vi.useFakeTimers()
fetchMock.mockImplementation(() => Promise.resolve(
new Response("<html>bad gateway</html>", { status: 502 }),
))
runWidget({ "data-encrypted-context": GRANT })
// Attempts at 0, 1, 2.5, 4.75 and 8.125 s; the next waits 5.063 s.
await vi.advanceTimersByTimeAsync(9_000)
expect(fetchMock).toHaveBeenCalledTimes(5)
wake()
await vi.advanceTimersByTimeAsync(0)
expect(fetchMock).toHaveBeenCalledTimes(6)
// The failed early attempt continues the back-off where it was.
await vi.advanceTimersByTimeAsync(7_593)
expect(fetchMock).toHaveBeenCalledTimes(6)
await vi.advanceTimersByTimeAsync(1)
expect(fetchMock).toHaveBeenCalledTimes(7)
Reflect.deleteProperty(document, "visibilityState")
})
it("does not retry early when the page becomes hidden", async () => {
vi.useFakeTimers()
fetchMock.mockImplementation(() => Promise.resolve(
new Response("<html>bad gateway</html>", { status: 502 }),
))
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(0)
expect(fetchMock).toHaveBeenCalledTimes(1)
Object.defineProperty(document, "visibilityState", { configurable: true, value: "hidden" })
document.dispatchEvent(new Event("visibilitychange"))
await vi.advanceTimersByTimeAsync(0)
Reflect.deleteProperty(document, "visibilityState")
expect(fetchMock).toHaveBeenCalledTimes(1)
})
it("does not shorten a server-requested rate-limit wait", async () => {
vi.useFakeTimers()
fetchMock.mockImplementation(() => Promise.resolve(jsonResponse(
429,
{ error: { code: "rate_limited" } },
{ "Retry-After": "3" },
)))
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(0)
window.dispatchEvent(new Event("online"))
await vi.advanceTimersByTimeAsync(2_999)
expect(fetchMock).toHaveBeenCalledTimes(1)
await vi.advanceTimersByTimeAsync(1)
expect(fetchMock).toHaveBeenCalledTimes(2)
})
it("stops listening for wake events once the widget is removed", async () => {
vi.useFakeTimers()
fetchMock.mockImplementation(() => Promise.resolve(
new Response("<html>bad gateway</html>", { status: 502 }),
))
const removeFromWindow = vi.spyOn(window, "removeEventListener")
const removeFromDocument = vi.spyOn(document, "removeEventListener")
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(0)
expect(fetchMock).toHaveBeenCalledTimes(1)
for (const container of document.querySelectorAll(".xagent-widget-container")) {
container.remove()
}
await vi.advanceTimersByTimeAsync(0)
window.dispatchEvent(new Event("online"))
await vi.advanceTimersByTimeAsync(60_000)
expect(fetchMock).toHaveBeenCalledTimes(1)
expect(removeFromWindow).toHaveBeenCalledWith("online", expect.any(Function))
expect(removeFromDocument).toHaveBeenCalledWith("visibilitychange", expect.any(Function))
})
it("ignores a superseded exchange failure after the replacement exchange succeeds", async () => {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
let resolveFirst: (value: Response) => void = () => undefined
fetchMock.mockImplementationOnce(() => new Promise<Response>((resolve) => {
resolveFirst = resolve
}))
runWidget({ "data-encrypted-context": GRANT })
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
fetchMock.mockResolvedValueOnce(jsonResponse(200, exchangeBody({ session_token: "st_second" })))
firePageRestore()
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2))
const post = spyOnIframePostMessage()
await flushAsync()
fromIframe("ready")
expect(post).toHaveBeenCalledWith(
expect.objectContaining({ type: "session_update", session_token: "st_second" }),
HOST,
)
post.mockClear()
resolveFirst(errorResponse(409, "agent_not_available"))
await flushAsync()
expect(errorSpy).not.toHaveBeenCalledWith(
expect.stringContaining("[agent_not_available]"),
)
expect(post).not.toHaveBeenCalled()
fromIframe("ready")
expect(post).toHaveBeenCalledWith(
expect.objectContaining({ type: "session_update", session_token: "st_second" }),
HOST,
)
})
it("ignores a superseded exchange failure before the replacement exchange succeeds", async () => {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
let resolveFirst: (value: Response) => void = () => undefined
let resolveSecond: (value: Response) => void = () => undefined
fetchMock.mockImplementationOnce(() => new Promise<Response>((resolve) => {
resolveFirst = resolve
}))
runWidget({ "data-encrypted-context": GRANT })
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
fetchMock.mockImplementationOnce(() => new Promise<Response>((resolve) => {
resolveSecond = resolve
}))
firePageRestore()
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2))
const post = spyOnIframePostMessage()
fromIframe("ready")
resolveFirst(errorResponse(409, "agent_not_available"))
await flushAsync()
expect(errorSpy).not.toHaveBeenCalledWith(
expect.stringContaining("[agent_not_available]"),
)
expect(post).not.toHaveBeenCalled()
resolveSecond(jsonResponse(200, exchangeBody({ session_token: "st_second" })))
await flushAsync()
expect(post).toHaveBeenCalledWith(
expect.objectContaining({ type: "session_update", session_token: "st_second" }),
HOST,
)
})
it("publishes the replacement exchange without parking a reconnect operation", async () => {
let resolveFirst: (value: Response) => void = () => undefined
let resolveSecond: (value: Response) => void = () => undefined
fetchMock
.mockImplementationOnce(() => new Promise<Response>((resolve) => {
resolveFirst = resolve
}))
.mockImplementationOnce(() => new Promise<Response>((resolve) => {
resolveSecond = resolve
}))
runWidget({ "data-encrypted-context": GRANT })
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
firePageRestore()
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2))
const post = spyOnIframePostMessage()
fromIframe("ready")
resolveFirst(errorResponse(409, "agent_not_available"))
await flushAsync()
fromIframe("reconnect_request", { reason: "ws_closed" })
expect(fetchMock).toHaveBeenCalledTimes(2)
resolveSecond(jsonResponse(200, exchangeBody({
session_token: "st_second",
reconnect_token: "rt_second",
})))
await flushAsync()
expect(fetchMock).toHaveBeenCalledTimes(2)
expect(post).toHaveBeenCalledWith(
expect.objectContaining({ type: "session_update", session_token: "st_second" }),
HOST,
)
})
it("does not retry a network failure from a superseded exchange", async () => {
vi.useFakeTimers()
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
let rejectFirst: (reason: unknown) => void = () => undefined
fetchMock.mockImplementationOnce(() => new Promise<Response>((_resolve, reject) => {
rejectFirst = reject
}))
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(0)
expect(fetchMock).toHaveBeenCalledTimes(1)
fetchMock.mockResolvedValueOnce(jsonResponse(200, exchangeBody({ session_token: "st_second" })))
firePageRestore()
await vi.advanceTimersByTimeAsync(0)
expect(fetchMock).toHaveBeenCalledTimes(2)
const post = spyOnIframePostMessage()
fromIframe("ready")
expect(post).toHaveBeenCalledWith(
expect.objectContaining({ type: "session_update", session_token: "st_second" }),
HOST,
)
post.mockClear()
fetchMock.mockRejectedValue(new TypeError("Failed to fetch"))
rejectFirst(new TypeError("Failed to fetch"))
await vi.advanceTimersByTimeAsync(7000)
expect(fetchMock).toHaveBeenCalledTimes(2)
expect(errorSpy).not.toHaveBeenCalledWith(
expect.stringContaining("[network_unavailable]"),
)
expect(post).not.toHaveBeenCalled()
fromIframe("ready")
expect(post).toHaveBeenCalledWith(
expect.objectContaining({ type: "session_update", session_token: "st_second" }),
HOST,
)
})
it("ignores a canceled exchange even when it resolves before its replacement", async () => {
let resolveFirst: (value: Response) => void = () => undefined
let resolveSecond: (value: Response) => void = () => undefined
fetchMock.mockImplementationOnce(() => new Promise<Response>((resolve) => {
resolveFirst = resolve
}))
runWidget({ "data-encrypted-context": GRANT })
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
fetchMock.mockImplementationOnce(() => new Promise<Response>((resolve) => {
resolveSecond = resolve
}))
firePageRestore()
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2))
const post = spyOnIframePostMessage()
resolveFirst(jsonResponse(200, exchangeBody({ session_token: "st_first_winner" })))
await flushAsync()
fromIframe("ready")
expect(post).not.toHaveBeenCalled()
resolveSecond(jsonResponse(200, exchangeBody({ session_token: "st_second_late" })))
await flushAsync()
expect(post).toHaveBeenCalledWith(
expect.objectContaining({ type: "session_update", session_token: "st_second_late" }),
HOST,
)
})
it("fails closed when reconnect still returns an already-stale token", async () => {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockImplementation(() => Promise.resolve(jsonResponse(200, exchangeBody({
session_token_expires_at: new Date(Date.now() + 10_000).toISOString(),
}))))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
fromIframe("ready")
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(2))
await flushAsync()
expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("[unexpected_error] (HTTP 200)"))
expect(post).toHaveBeenCalledWith(
expect.objectContaining({ type: "session_terminal", code: "unexpected_error" }),
HOST,
)
expect(post).not.toHaveBeenCalledWith(
expect.objectContaining({ type: "session_update" }),
HOST,
)
})
it("re-runs the load flow when a bfcache restore finds no session", async () => {
vi.useFakeTimers()
// The exchange never settles: the page was frozen mid-flight.
fetchMock.mockImplementationOnce(() => new Promise(() => undefined))
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(0)
expect(fetchMock).toHaveBeenCalledTimes(1)
fetchMock.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
firePageRestore()
await vi.advanceTimersByTimeAsync(0)
expect(fetchMock).toHaveBeenCalledTimes(2)
expect(fetchMock.mock.calls[1][0]).toBe(EXCHANGE_URL)
})
it("processes one persisted pagehide only once across repeated pageshow events", async () => {
vi.useFakeTimers()
let recoverySignal: AbortSignal | undefined
fetchMock
.mockImplementationOnce(() => new Promise(() => undefined))
.mockImplementationOnce((_url: string, init: RequestInit) => {
recoverySignal = init.signal as AbortSignal
return new Promise(() => undefined)
})
runWidget({ "data-encrypted-context": GRANT })
await vi.advanceTimersByTimeAsync(0)
firePageRestore()
await vi.advanceTimersByTimeAsync(0)
expect(fetchMock).toHaveBeenCalledTimes(2)
firePageShow(true)
await vi.advanceTimersByTimeAsync(0)
expect(fetchMock).toHaveBeenCalledTimes(2)
expect(recoverySignal?.aborted).toBe(false)
})
it("does nothing on a bfcache restore with a healthy session", async () => {
fetchMock.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
runWidget({ "data-encrypted-context": GRANT })
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
// vi.waitFor's condition above (fetchMock call count) goes true the
// instant fetch() is invoked, before the mocked Response's .json() body
// read (and the applySession() it feeds) has actually settled — see the
// flushAsync() comment near the top of this file for the same race. A
// macrotask flush here lets state.session actually be populated before
// firePageShow, or this test would spuriously re-trigger the load flow.
await flushAsync()
firePageRestore()
await Promise.resolve()
expect(fetchMock).toHaveBeenCalledTimes(1)
})
it("does nothing on a bfcache restore after a terminal outcome", async () => {
vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockResolvedValueOnce(errorResponse(403, "agent_not_granted"))
runWidget({ "data-encrypted-context": GRANT })
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
// Same race as above: let goTerminal() actually latch state.terminalCode
// before firePageShow, or this test would spuriously re-trigger the load
// flow while the terminal outcome is still mid-flight.
await flushAsync()
firePageRestore()
await Promise.resolve()
expect(fetchMock).toHaveBeenCalledTimes(1)
})
it("keeps retryable rate limits inside the active parent phase", async () => {
vi.useFakeTimers()
vi.spyOn(console, "error").mockImplementation(() => undefined)
fetchMock.mockImplementation(() => Promise.resolve(jsonResponse(
429,
{ error: { code: "rate_limited" } },
{ "Retry-After": "1" },
)))
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
fromIframe("ready")
await vi.advanceTimersByTimeAsync(3_000)
expect(fetchMock).toHaveBeenCalledTimes(3)
expect(post).toHaveBeenCalledWith(
expect.objectContaining({ type: "session_degraded", code: "rate_limited" }),
HOST,
)
post.mockClear()
fromIframe("reconnect_request", { reason: "ws_closed" })
await vi.advanceTimersByTimeAsync(1_000)
expect(fetchMock).toHaveBeenCalledTimes(3)
await vi.advanceTimersByTimeAsync(30_000)
expect(fetchMock).toHaveBeenCalledTimes(3)
})
it("does nothing on a normal (non-persisted) pageshow", async () => {
fetchMock.mockImplementationOnce(() => new Promise(() => undefined))
runWidget({ "data-encrypted-context": GRANT })
firePageShow(false)
await Promise.resolve()
expect(fetchMock).toHaveBeenCalledTimes(1)
})
it("tears down listeners and pending requests when the session iframe leaves the DOM", async () => {
let requestSignal: AbortSignal | undefined
const removeListenerSpy = vi.spyOn(window, "removeEventListener")
fetchMock.mockImplementation((_url: string, init: RequestInit) => {
requestSignal = init.signal as AbortSignal
return new Promise(() => undefined)
})
runWidget({ "data-encrypted-context": GRANT })
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
document.querySelector(".xagent-widget-container")?.remove()
await vi.waitFor(() => expect(requestSignal?.aborted).toBe(true))
expect(removeListenerSpy).toHaveBeenCalledWith("message", expect.any(Function))
expect(removeListenerSpy).toHaveBeenCalledWith("pageshow", expect.any(Function))
expect(removeListenerSpy).toHaveBeenCalledWith("pagehide", expect.any(Function))
firePageRestore()
await flushAsync()
expect(fetchMock).toHaveBeenCalledTimes(1)
})
it("tears down when the iframe is removed from its still-mounted widget subtree", async () => {
let requestSignal: AbortSignal | undefined
fetchMock.mockImplementation((_url: string, init: RequestInit) => {
requestSignal = init.signal as AbortSignal
return new Promise(() => undefined)
})
runWidget({ "data-encrypted-context": GRANT })
await vi.waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(1))
iframeEl()?.remove()
await vi.waitFor(() => expect(requestSignal?.aborted).toBe(true))
})
it("cancels the delivery-stability timer when the session iframe is detached", async () => {
vi.useFakeTimers()
fetchMock.mockResolvedValueOnce(jsonResponse(200, exchangeBody()))
const clearTimeoutSpy = vi.spyOn(window, "clearTimeout")
runWidget({ "data-encrypted-context": GRANT })
const post = spyOnIframePostMessage()
await vi.advanceTimersByTimeAsync(0)
fromIframe("ready")
const deliveryId = post.mock.calls.at(-1)?.[0].session_delivery_id
fromIframe("session_connection_open", { session_delivery_id: deliveryId })
const clearsBeforeDetach = clearTimeoutSpy.mock.calls.length
iframeEl()?.remove()
await Promise.resolve()
await Promise.resolve()
expect(clearTimeoutSpy.mock.calls.length).toBeGreaterThan(clearsBeforeDetach)
})
})