UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

695 lines (638 loc) • 34.8 kB
import type { Server, ServerWebSocket, WebSocketHandler } from "bun"; import { formatErrorResponse } from "../../bridge"; import { resolveResponsesApiAuth, type RequestPolicyView } from "../auth-cors"; import { isDraining } from "../lifecycle"; import { buildResponsesWsData, selectForwardHeaders, type LinkSocketBinding, type WsData } from "../ws-bridge"; import { tryReserveCodexWebSocket } from "../../codex/websocket-registry"; import type { AdmissionReservation } from "../../lib/admission"; import { sessionLaneIdFromRequest } from "../request-log-conversation"; import { classifyUsageClient } from "../../usage/client"; import type { LinkActivity, LinkSocketActivity } from "../../link/child-activity"; import type { ActivityHolds, FingerprintMark, StoredMark } from "../../link/ws-activity-holds"; import type { LinkTrafficBook } from "../../link/traffic"; import type { LinkWsCloseReason, LinkWsCounters, LinkWsRefusal } from "../../link/status-projection"; import type { LinkTurnObserver } from "../link-turn"; import { resultKeysOf } from "../../codex/websocket-activity"; import { LINK_WS_AGE_CLOSE, LINK_WS_DISABLED_CLOSE, LINK_WS_IDLE_CLOSE, LINK_WS_LIMITS, LINK_WS_REVOKED_CLOSE, type LinkWebsocketLimits, linkWebsocketLimitOverrides, } from "./link-websocket-limits"; /** * The Responses WebSocket over a Remote Link, Home side (design T4 section 2). * * A link upgrade is admitted only on a relay session that link-relay-sessions.ts has just consumed * and verified on the same TCP connection (S1, S4). Admission is one synchronous function; every * frame the socket later receives re-runs the authorization check before the shared handler sees * it (S3), so a revoked link, a rotated or removed key, or an edited links.json stops new turns at * the next frame and running ones at the next sweep. */ /** The verified relay session an upgrade arrived on. release is the session's drain lease. */ export interface LinkSessionGrant { keyId: string; linkId: string; fingerprint: string; release: () => void; } /** handled: false leaves the request on today's path (the hub-link route table refuses it with 404). */ export type LinkUpgradeOutcome = { handled: false } | { handled: true; response: Response | undefined }; type LeaseState = "reserved" | "upgrading" | "upgraded" | "released" | "closed"; /** * The single owner of every lease one link upgrade holds (design 2.3). Leases are released in * reverse order, exactly once: by a refusal, abort, throw or failed upgrade before the socket * exists, or by the socket's close callback after it does. Nothing else releases them. */ export class LinkUpgradeLeases { private current: LeaseState = "reserved"; private readonly releases: Array<() => void>; constructor(session: () => void) { this.releases = [session]; } get state(): LeaseState { return this.current; } /** Adds a lease while admission is still deciding; after that a late lease is returned at once. */ add(release: () => void): void { if (this.current === "reserved") this.releases.push(release); else release(); } upgrading(): void { if (this.current === "reserved") this.current = "upgrading"; } upgraded(): void { if (this.current === "upgrading") this.current = "upgraded"; } /** Refusal, abort, throw or failed upgrade. No effect once the socket owns the leases. */ release(): void { if (this.current !== "reserved" && this.current !== "upgrading") return; this.current = "released"; this.drain(); } /** The socket's close callback. */ closed(): void { if (this.current === "upgraded") { this.current = "closed"; this.drain(); } else this.release(); } private drain(): void { while (this.releases.length) { const release = this.releases.pop()!; try { release(); } catch { /* one failed release must not keep the others */ } } } } /** Design 2.3 step 1: exactly a Codex Responses upgrade, with nothing a browser or an extension adds. */ export function linkResponsesUpgradeShape(req: Request): boolean { if (req.method !== "GET") return false; let url: URL; try { url = new URL(req.url); } catch { return false; } if (url.pathname !== "/v1/responses" || url.search !== "") return false; const headers = req.headers; if (headers.get("upgrade")?.toLowerCase() !== "websocket") return false; if (!(headers.get("connection") ?? "").toLowerCase().split(",").some(token => token.trim() === "upgrade")) return false; if (headers.get("sec-websocket-version") !== "13" || !headers.get("sec-websocket-key")) return false; return !headers.has("origin") && !headers.has("sec-websocket-protocol") && !headers.has("sec-websocket-extensions"); } export interface LinkWebsocketTimers { setInterval(callback: () => void, ms: number): unknown; clearInterval(handle: unknown): void; } export interface LinkWebsocketGateDeps { /** linkResponsesWebsocketEnabled(config), read on every upgrade and every sweep. */ enabled(): boolean; /** The hub-link request policy (the same view serve-options admits link requests with). */ policy(): RequestPolicyView; /** * The authorization check: an uncached, fail-closed links.json read still names (linkId, keyId), * and the key still has the fingerprint the session was proved with. Must not throw or await. */ authorized(identity: { keyId: string; linkId: string; fingerprint: string }): boolean; draining?: () => boolean; reserveSocket?: () => AdmissionReservation<ServerWebSocket<WsData>> | null; limits?: Partial<LinkWebsocketLimits>; timers?: LinkWebsocketTimers; /** Wall clock for idle, age and the drain deadline. */ now?: () => number; /** The per-link activity book: a busy link socket counts in flight there (design T4 section 5). */ activity?: LinkActivity; /** Durable holds: a busy close leaves one, and the crash fence is armed before the first upgrade. */ holds?: ActivityHolds; /** * The Home's per-link traffic book (the HTTP relay's): each link socket is one request in it, counted from open to close * in the Child's units (message payload bytes each way); complete when any close frame ended it, where the Child also * counts its own overload, binary and protocol closes as incomplete. */ traffic?: LinkTrafficBook; } /** What the gate keeps per open link socket. */ interface SocketState { openedAt: number; /** When the socket last became idle; null while busy. */ idleSince: number | null; /** When this socket started draining after the switch went off; null while on. */ drainingSince: number | null; /** A create arrived while a turn ran during the drain: close once the turn ends. */ closeAfterTurn: boolean; book: LinkSocketActivity | null; unsubscribe: () => void; /** HMAC of the socket's own thread id; undefined until known, null when it has none. */ threadHash: string | null | undefined; /** Closed by revocation: such a close leaves no hold (design 5). */ revoked: boolean; /** Turns that entered the pipeline on this socket; the first one is logged as continuation full, reason first. */ turnsSeen: number; /** * One entry per turn that entered the pipeline, keyed by the handler's turn id and written and * cleared only by that turn's own observer and cleanup: "pending" until expansion, then its * fingerprint, or "unknown" when expansion or hashing failed or Codex sent no turn id, and "done" * once its own terminal arrived (no longer cut work). The turn's cleanup removes the entry. */ captures: Map<number, FingerprintMark | "pending" | "unknown" | "done">; } function bodyRecord(body: unknown): Record<string, unknown> { return body && typeof body === "object" && !Array.isArray(body) ? body as Record<string, unknown> : {}; } function inputItems(body: Record<string, unknown>): unknown[] { return Array.isArray(body.input) ? body.input : body.input === undefined ? [] : [body.input]; } /** Codex's own turn id (client_metadata.turn_id); optional on Codex's side. */ function turnIdOf(body: Record<string, unknown>): string | null { const metadata = bodyRecord(body.client_metadata); return typeof metadata.turn_id === "string" && metadata.turn_id ? metadata.turn_id : null; } /** Design 5 capture: the expanded input's length and HMAC, with the turn reference. */ export function fingerprintCapture(holds: ActivityHolds, body: unknown): FingerprintMark | "unknown" { const record = bodyRecord(body); const turnId = turnIdOf(record); if (!turnId) return "unknown"; try { const items = inputItems(record); if (items.length === 0) return "unknown"; return { n: items.length, inputHmac: holds.inputHmac(items), turnRef: holds.turnRef(turnId) }; } catch { return "unknown"; } } /** * Rules (a)-(c): the fingerprinted marks of this link that a request re-sends: an inference request * (generate is not false) of the same own thread and turn whose expanded input starts with the cut * request's input. Rule (d), an upstream-completed terminal, is checked by the caller at the end. */ export function marksResent(holds: ActivityHolds, linkId: string, threadHash: string | null, body: unknown): StoredMark[] { const record = bodyRecord(body); if (!threadHash || record.generate === false || !holds.hasMarks(linkId)) return []; const turnId = turnIdOf(record); if (!turnId) return []; try { const items = inputItems(record); return holds.markCandidates(linkId, threadHash, holds.turnRef(turnId)) .filter(mark => items.length >= mark.n && holds.inputHmac(items.slice(0, mark.n)) === mark.inputHmac); } catch { return []; } } /** Rule (d): only a terminal the upstream itself reported as completed releases a running mark; no provenance is not enough. */ export function upstreamCompleted(status: string | undefined, source: string | undefined): boolean { return status === "completed" && source === "upstream"; } /** Design 9.1: the hashed thread and turn refs of a link request; a ref that cannot be made is left out. */ export function linkLogRefs(holds: ActivityHolds, linkId: string, threadId: string, body: unknown): { threadRef?: string; turnRef?: string } { const turnId = turnIdOf(bodyRecord(body)); const ref = (kind: "thread" | "turn", id: string | null): string | null => { if (!id) return null; try { return holds.logRef(kind, linkId, id); } catch { return null; } }; const threadRef = ref("thread", threadId || threadIdOf(bodyRecord(body))); const turnRef = ref("turn", turnId); return { ...(threadRef ? { threadRef } : {}), ...(turnRef ? { turnRef } : {}) }; } function threadIdOf(body: Record<string, unknown>): string | null { const metadata = bodyRecord(body.client_metadata); return typeof metadata.thread_id === "string" && metadata.thread_id ? metadata.thread_id : null; } const defaultTimers: LinkWebsocketTimers = { setInterval(callback, ms) { const handle = setInterval(callback, ms); (handle as { unref?: () => void }).unref?.(); return handle; }, clearInterval(handle) { clearInterval(handle as ReturnType<typeof setInterval>); }, }; function capacityRefusal(): Response { return formatErrorResponse(426, "upgrade_required", "Remote Link WebSocket capacity reached; use HTTP.", { code: "link_websocket_capacity" }); } function unauthorized(): Response { return formatErrorResponse(401, "authentication_error", "opencodex API key required"); } export function createLinkWebsocketGate(deps: LinkWebsocketGateDeps) { const limits: LinkWebsocketLimits = { ...LINK_WS_LIMITS, ...linkWebsocketLimitOverrides(), ...deps.limits }; const timers = deps.timers ?? defaultTimers; const draining = deps.draining ?? isDraining; // A full shared gate lets a link upgrade reclaim an idle link socket, never a local one. const reserveSocket = deps.reserveSocket ?? (() => tryReserveCodexWebSocket({ reclaim: "link" })); const now = deps.now ?? Date.now; const states = new WeakMap<ServerWebSocket<WsData>, SocketState>(); // Admission counts open plus upgrading sockets; a lease in the bundle gives each slot back. const admitted = new Map<string, number>(); let admittedTotal = 0; let reservedBytes = 0; // Open sockets, by link, for the revocation hooks and the sweep. const sockets = new Map<string, Set<ServerWebSocket<WsData>>>(); let sweepHandle: unknown; // False from last-link close() until the next bind: a session reserved before close() must not // become a socket close() never sees, or the listener drain would wait on it forever. let accepting = true; // Upgraded but not yet opened: Bun runs open() after the fetch returns, so a revoke or close() in // between must still reach the socket. The value is the close it owes when it opens. const pending = new Map<LinkSocketBinding, { code: number; reason: string } | null>(); // Design 9.3: display-only counters per link, in memory, reset at restart; reasons are closed sets. const counted = new Map<string, { upgrades: number; refused: Partial<Record<LinkWsRefusal, number>>; closes: Partial<Record<LinkWsCloseReason, number>> }>(); const tally = (linkId: string, create: boolean) => { let entry = counted.get(linkId); if (!entry && create) { entry = { upgrades: 0, refused: {}, closes: {} }; counted.set(linkId, entry); } return entry; }; // Why the gate itself closed a socket; a close the gate did not start is classified by its code. const fencedBy = new WeakMap<LinkSocketBinding, LinkWsCloseReason>(); const FENCE_REASONS = new Map<{ code: number; reason: string }, LinkWsCloseReason>([ [LINK_WS_REVOKED_CLOSE, "revoked"], [LINK_WS_DISABLED_CLOSE, "disabled"], [LINK_WS_IDLE_CLOSE, "idle"], [LINK_WS_AGE_CLOSE, "age"], ]); const authorized = (identity: { keyId: string; linkId: string; fingerprint: string }): boolean => { try { return deps.authorized(identity); } catch { return false; } }; const fence = (ws: ServerWebSocket<WsData>, close: { code: number; reason: string }): void => { const link = ws.data.link; if (!link || link.fenced) return; link.fenced = true; const why = FENCE_REASONS.get(close); if (why) fencedBy.set(link, why); const state = states.get(ws); if (state && close === LINK_WS_REVOKED_CLOSE) state.revoked = true; if (ws.data.responsesActivity) ws.data.responsesActivity.closing = true; try { ws.data.cancel?.(); } catch { /* the close below still ends the socket */ } try { ws.close(close.code, close.reason); } catch { /* already closing */ } }; const allSockets = (): ServerWebSocket<WsData>[] => [...sockets.values()].flatMap(set => [...set]); const enabledNow = (): boolean => { try { return deps.enabled(); } catch { return false; } }; /** Design 2.5: drain starts once, at the first sweep or frame that sees the switch off. */ const startDrain = (state: SocketState): void => { if (state.drainingSince === null) state.drainingSince = now(); }; const pastDeadline = (state: SocketState): boolean => state.drainingSince !== null && now() - state.drainingSince >= limits.drainDeadlineMs; /** * Re-evaluated whenever the socket's activity changes, and by the sweep. A busy socket is never * closed here: drain and age wait for the running turn, and idle closes need idle. */ const settle = (ws: ServerWebSocket<WsData>, state: SocketState, fromSweep: boolean): void => { const link = ws.data.link; const activity = ws.data.responsesActivity; if (!link || link.fenced || !activity) return; if (state.drainingSince !== null) { if (state.closeAfterTurn && !activity.running) { fence(ws, LINK_WS_DISABLED_CLOSE); return; } if (activity.idle) { fence(ws, LINK_WS_DISABLED_CLOSE); return; } if (pastDeadline(state)) { if (activity.running) state.closeAfterTurn = true; else fence(ws, LINK_WS_DISABLED_CLOSE); } return; } if (!activity.idle) return; if (now() - state.openedAt >= limits.maxAgeMs) { fence(ws, LINK_WS_AGE_CLOSE); return; } if (fromSweep && state.idleSince !== null && now() - state.idleSince >= limits.idleCloseMs) fence(ws, LINK_WS_IDLE_CLOSE); }; const observe = (ws: ServerWebSocket<WsData>, state: SocketState): void => { const activity = ws.data.responsesActivity; if (!activity) return; const idle = activity.idle; if (idle && state.idleSince === null) state.idleSince = now(); if (!idle) state.idleSince = null; state.book?.busy(!idle); settle(ws, state, false); }; /** * The drain rule for one frame on a draining socket (design 2.5). Only a create is decided here; * anything else goes to the shared handler as usual. Parses only while draining. */ const admitWhileDraining = (ws: ServerWebSocket<WsData>, state: SocketState, raw: string | Buffer): boolean => { let frame: Record<string, unknown> | null = null; try { frame = JSON.parse(typeof raw === "string" ? raw : raw.toString()) as Record<string, unknown>; } catch { frame = null; } if (!frame || frame.type !== "response.create") return true; const activity = ws.data.responsesActivity; if (!activity) { fence(ws, LINK_WS_DISABLED_CLOSE); return false; } // A running turn is never cancelled by the drain: the frame is dropped and the socket closes after it. if (activity.running) { state.closeAfterTurn = true; return false; } if (!pastDeadline(state) && !activity.untracked && activity.returnsPending(frame.input)) return true; fence(ws, LINK_WS_DISABLED_CLOSE); return false; }; /** * Learns the socket's own thread from its first create when the handshake carried none. Release * itself happens only when the shared handler admits a turn (onAccepted, below), so a warmup or a * refused create never releases a hold. */ const learnThread = (state: SocketState, raw: string | Buffer): void => { const holds = deps.holds!; if (state.threadHash !== undefined) return; let frame: Record<string, unknown>; try { frame = JSON.parse(typeof raw === "string" ? raw : raw.toString()) as Record<string, unknown>; } catch { return; } if (frame.type !== "response.create") return; if (state.threadHash === undefined) { const metadata = frame.client_metadata as Record<string, unknown> | undefined; const threadId = metadata && typeof metadata.thread_id === "string" && metadata.thread_id ? metadata.thread_id : null; try { state.threadHash = threadId ? holds.threadHash(threadId) : null; } catch { state.threadHash = null; } } }; /** Design 5: a socket that closes while busy, for any reason except revocation, leaves a hold. */ const holdOnClose = (ws: ServerWebSocket<WsData>): void => { const holds = deps.holds; const link = ws.data.link; const state = states.get(ws); const activity = ws.data.responsesActivity; if (!holds || !link || !state || state.revoked || !activity) return; const pendingKeys = activity.pendingKeys(); if (!activity.running && pendingKeys.length === 0 && !activity.untracked) return; // Snapshot, in this task, every turn's capture: a fingerprint becomes a mark released on its own; // a turn that closed before its capture, or could not be fingerprinted, becomes an unknown mark. const marks: FingerprintMark[] = []; let unknown = 0; for (const capture of state.captures.values()) { if (typeof capture === "object") marks.push(capture); else if (capture !== "done") unknown += 1; } unknown += Math.max(0, activity.runningTurns - state.captures.size); holds.add(link.linkId, { threadHash: state.threadHash ?? null, pendingKeys, runningMarks: unknown, marks, untracked: activity.untracked }); }; const sweep = (): void => { const on = enabledNow(); for (const ws of allSockets()) { const link = ws.data.link; if (!link || link.fenced) continue; if (!authorized(link)) { fence(ws, LINK_WS_REVOKED_CLOSE); continue; } const state = states.get(ws); if (!state) continue; if (!on) startDrain(state); settle(ws, state, true); } }; const track = (ws: ServerWebSocket<WsData>, linkId: string): void => { let set = sockets.get(linkId); if (!set) { set = new Set(); sockets.set(linkId, set); } set.add(ws); if (sweepHandle === undefined) sweepHandle = timers.setInterval(sweep, limits.sweepIntervalMs); }; const untrack = (ws: ServerWebSocket<WsData>, linkId: string): void => { const set = sockets.get(linkId); if (set?.delete(ws) && set.size === 0) sockets.delete(linkId); if (sockets.size === 0 && sweepHandle !== undefined) { timers.clearInterval(sweepHandle); sweepHandle = undefined; } }; const admitSlot = (linkId: string): (() => void) | null => { const perLink = admitted.get(linkId) ?? 0; if (perLink >= limits.perLinkSockets || admittedTotal >= limits.totalSockets) return null; admitted.set(linkId, perLink + 1); admittedTotal += 1; return () => { const left = (admitted.get(linkId) ?? 1) - 1; if (left > 0) admitted.set(linkId, left); else admitted.delete(linkId); admittedTotal -= 1; }; }; const reserveMemory = (): (() => void) | null => { if (reservedBytes + limits.socketReservationBytes > limits.memoryBudgetBytes) return null; reservedBytes += limits.socketReservationBytes; return () => { reservedBytes -= limits.socketReservationBytes; }; }; return { /** * Called by link-relay-sessions.ts right after it consumed and verified a session, for a request * that carries an Upgrade header. Synchronous: no await between the checks and server.upgrade. */ upgrade<T>(req: Request, server: Server<T>, grant: LinkSessionGrant): LinkUpgradeOutcome { if (!linkResponsesUpgradeShape(req)) return { handled: false }; let on = false; try { on = deps.enabled(); } catch { on = false; } // Off: the request keeps today's path and today's refusal, byte for byte. if (!on) return { handled: false }; const leases = new LinkUpgradeLeases(grant.release); let binding: LinkSocketBinding | undefined; const refuse = (response: Response, reason: LinkWsRefusal): LinkUpgradeOutcome => { leases.release(); const entry = tally(grant.linkId, true)!; entry.refused[reason] = (entry.refused[reason] ?? 0) + 1; return { handled: true, response }; }; try { if (req.signal.aborted) return refuse(formatErrorResponse(426, "upgrade_required", "The upgrade request was aborted."), "aborted"); if (!accepting || draining()) return refuse(formatErrorResponse(503, "server_error", "The Home is shutting down.", { code: "server_draining" }), "draining"); // S2: the credential on the upgrade is the key the relay proof was made with. const admission = resolveResponsesApiAuth(req, deps.policy()); if (!admission || admission.kind !== "configured" || admission.keyId !== grant.keyId) return refuse(unauthorized(), "unauthorized"); if (!authorized(grant)) return refuse(unauthorized(), "unauthorized"); // Design 5: the crash fence is durable before any link socket exists; without it, no upgrade. if (deps.holds && !deps.holds.arm()) { return refuse(formatErrorResponse(426, "upgrade_required", "Remote Link WebSocket activity cannot be recorded; use HTTP.", { code: "link_websocket_unavailable" }), "unavailable"); } const memory = reserveMemory(); if (!memory) return refuse(capacityRefusal(), "memory"); leases.add(memory); const slot = admitSlot(grant.linkId); if (!slot) return refuse(capacityRefusal(), "cap"); leases.add(slot); const socketLease = reserveSocket(); if (!socketLease) return refuse(capacityRefusal(), "cap"); leases.add(() => socketLease.release()); const data = buildResponsesWsData( selectForwardHeaders(req.headers), admission, socketLease, sessionLaneIdFromRequest(req.headers), classifyUsageClient(req.headers), ); // A Remote Link socket is never local, even though its tunnel arrives on a loopback socket. Object.assign(data, { peerLocal: false }); binding = { linkId: grant.linkId, keyId: grant.keyId, fingerprint: grant.fingerprint, fenced: false, leases }; data.nativeControlDisabled = true; data.link = binding; if (req.signal.aborted) return refuse(formatErrorResponse(426, "upgrade_required", "The upgrade request was aborted."), "aborted"); leases.upgrading(); pending.set(binding, null); if (!(server as unknown as Server<WsData>).upgrade(req, { data })) { pending.delete(binding); return refuse(formatErrorResponse(426, "upgrade_required", "WebSocket upgrade failed"), "failed"); } leases.upgraded(); tally(grant.linkId, true)!.upgrades += 1; return { handled: true, response: undefined }; } catch { if (binding) pending.delete(binding); return refuse(formatErrorResponse(426, "upgrade_required", "WebSocket upgrade failed"), "failed"); } }, /** The link listener's websocket handler: the shared Responses handler behind the link checks. */ handler(base: WebSocketHandler<WsData>): WebSocketHandler<WsData> { return { ...base, maxPayloadLength: limits.maxMessageBytes, backpressureLimit: limits.backpressureLimitBytes, closeOnBackpressureLimit: false, idleTimeout: 0, perMessageDeflate: false, open(ws) { const link = ws.data.link; if (!link) { ws.close(1011, "link socket without a binding"); return; } const owed = pending.get(link) ?? null; pending.delete(link); track(ws, link.linkId); link.traffic = deps.traffic?.begin(link.linkId); base.open?.(ws); const state: SocketState = { openedAt: now(), idleSince: null, drainingSince: null, closeAfterTurn: false, book: deps.activity?.beginSocket(link.linkId) ?? null, unsubscribe: () => {}, threadHash: undefined, revoked: false, captures: new Map(), turnsSeen: 0, }; if (deps.holds) { const holds = deps.holds; const linkId = link.linkId; // One observer per turn, created when the turn enters the pipeline (websocket-handler.ts). ws.data.linkTurnObserver = (turnId: number): LinkTurnObserver => { state.captures.set(turnId, "pending"); const ordinal = ++state.turnsSeen; let resent: StoredMark[] = []; const own = (value: FingerprintMark | "unknown" | "done"): void => { if (state.captures.has(turnId)) state.captures.set(turnId, value); }; return { expanded(body, chain) { // A delta left for the upstream proves nothing about the full input: unknown, and no match. if (chain === "unexpanded") { own("unknown"); resent = []; return; } own(fingerprintCapture(holds, body)); resent = marksResent(holds, linkId, state.threadHash ?? null, body); }, expansionFailed() { own("unknown"); }, // The link WebSocket exists only while the feature is on: its turns read the upstream as the socket drains (#8601). pacedReads: true, logFields: body => ({ transport: "websocket", first: ordinal === 1, ...linkLogRefs(holds, linkId, ws.data.headers?.get("thread-id")?.trim() ?? "", body) }), terminal(status, source) { // The turn's own entry ends with its own terminal, superseded or not. own("done"); if (resent.length && state.threadHash && upstreamCompleted(status, source)) holds.releaseMarks(linkId, state.threadHash, resent); }, }; }; // The turn's cleanup (websocket-handler.ts): its entry goes, whether or not a terminal came. ws.data.linkTurnEnded = (turnId: number): void => { state.captures.delete(turnId); }; } // Codex sends its own thread id on the handshake; a socket without it may name one in its // first create's client_metadata (observeForHolds). const threadId = ws.data.headers?.get("thread-id"); if (deps.holds && threadId) { // A reference key that cannot be loaded leaves the hold operator-only rather than failing the socket. try { state.threadHash = deps.holds.threadHash(threadId); } catch { state.threadHash = null; } } states.set(ws, state); const activity = ws.data.responsesActivity; if (activity) { // A refused or failed turn on this socket leaves its results owed (design 5). activity.restoreRefusedResults = true; const stopChange = activity.onChange(() => observe(ws, state)); // An admitted turn may return results a closed socket of this link and own thread waited for. // Each turn settles only holds that existed when it began (another socket may reuse an id later). const beganAt = new WeakMap<object, number>(); const stopBegin = deps.holds ? activity.onBegin(input => { if (input && typeof input === "object") beganAt.set(input, deps.holds!.sequence()); }) : () => {}; const stopAccepted = deps.holds ? activity.onAccepted(input => { const holds = deps.holds!; const began = input && typeof input === "object" ? beganAt.get(input) : undefined; if (began !== undefined && holds.releasable(link.linkId)) holds.observe(link.linkId, state.threadHash ?? null, resultKeysOf(input), began); }) : () => {}; state.unsubscribe = () => { stopChange(); stopBegin(); stopAccepted(); }; observe(ws, state); } // A revoke or last-link close() that ran between the upgrade and now still applies. if (owed) fence(ws, owed); else if (!accepting) fence(ws, LINK_WS_REVOKED_CLOSE); }, // Bun calls drain when the send buffer empties; a link pump waits for it (design 6.2). drain(ws) { ws.data.link?.drained?.(); base.drain?.(ws); }, message(ws, raw) { const link = ws.data.link; // Every message that reached the Home counts, as the Child counts every write that completed, fenced or not. link?.traffic?.toHome(typeof raw === "string" ? Buffer.byteLength(raw) : raw.byteLength); if (!link || link.fenced) return; // S3: every message, of any type, before the shared handler can admit a turn. if (!authorized(link)) { fence(ws, LINK_WS_REVOKED_CLOSE); return; } const state = states.get(ws); if (state) { if (!enabledNow()) startDrain(state); if (state.drainingSince !== null && !admitWhileDraining(ws, state, raw)) return; if (deps.holds) learnThread(state, raw); } return base.message?.(ws, raw); }, close(ws, code, reason) { try { // Snapshot before the shared close cancels the turn: a busy socket leaves a hold. holdOnClose(ws); // A link pump waiting for a drain stops waiting once the socket is gone. ws.data.link?.drained?.(); base.close?.(ws, code, reason); } finally { const link = ws.data.link; const state = states.get(ws); if (state) { state.unsubscribe(); state.book?.end(); states.delete(ws); } if (link) { pending.delete(link); untrack(ws, link.linkId); // Counted only for a link still known: a removed link's counters are not recreated by its last closes. const entry = tally(link.linkId, false); const why: LinkWsCloseReason = fencedBy.get(link) ?? (code === 1000 || code === 1001 ? "client" : code === 1006 ? "dropped" : "other"); if (entry) entry.closes[why] = (entry.closes[why] ?? 0) + 1; // Complete when a close ended it, from either side; a socket dropped without one (1006, 1015) is incomplete. try { link.traffic?.end(code !== 1006 && code !== 1015); } catch { /* accounting never keeps a lease */ } link.leases.closed(); } } }, }; }, /** Design 9.3: one link's live counters (display only). */ transport(linkId: string): LinkWsCounters { const entry = counted.get(linkId); return { open: sockets.get(linkId)?.size ?? 0, upgrades: entry?.upgrades ?? 0, refused: { ...entry?.refused }, closes: { ...entry?.closes } }; }, /** A removed link's counters go with it. */ forgetTransport(linkId: string): void { counted.delete(linkId); }, /** The Home's own revoke path, in the same task as its commit. Returns how many were closed. */ closeLink(linkId: string): number { const set = [...(sockets.get(linkId) ?? [])]; for (const ws of set) fence(ws, LINK_WS_REVOKED_CLOSE); let owed = 0; for (const binding of pending.keys()) { if (binding.linkId !== linkId) continue; pending.set(binding, LINK_WS_REVOKED_CLOSE); owed += 1; } return set.length + owed; }, /** Last link removed: no new link socket, and every open one closes before the listener drains. */ closeAll(): number { accepting = false; const all = allSockets(); for (const ws of all) fence(ws, LINK_WS_REVOKED_CLOSE); for (const binding of pending.keys()) pending.set(binding, LINK_WS_REVOKED_CLOSE); return all.length + pending.size; }, /** A listener bound again after close() accepts link upgrades again. */ accept(): void { accepting = true; }, sweep, /** Process stop: the listener closes the sockets; only the timer is ours to clear. */ dispose(): void { if (sweepHandle !== undefined) timers.clearInterval(sweepHandle); sweepHandle = undefined; }, snapshot(): { open: number; admitted: number; reservedBytes: number; sweeping: boolean } { return { open: allSockets().length, admitted: admittedTotal, reservedBytes, sweeping: sweepHandle !== undefined }; }, }; } export type LinkWebsocketGate = ReturnType<typeof createLinkWebsocketGate>;