@turingfocus/chat-gateway-tfrobot 0.1.0

package/dist/socket.js

@@ -0,0 +1,654 @@
+import { io } from "socket.io-client";
+import { chatErrorSchema, chatUpdateSchema, createGatewayDeadlineExceededError, isGatewayDeadlineExceeded, sanitizeDiagnosticText, sanitizeRaw, } from "@turingfocus/chat-protocol";
+import { awaitBounded } from "./bounded.js";
+import { chatErrorEventDtoSchema, eventDtoSchema, messageDtoSchema, socketProtocolErrorDtoSchema, stateChangedDtoSchema, } from "./dto.js";
+import { mapEventUpdate, mapMessageUpdate, mapRun, mapUnknownSocketEvent, } from "./mapper.js";
+import { isValidTFRobotSession } from "./types.js";
+const KNOWN_EVENTS = new Set([
+    "chat_error",
+    "chat_event",
+    "chat_message",
+    "connect",
+    "connect_error",
+    "conversation_state_changed",
+    "disconnect",
+    "error",
+]);
+const MAX_TIMER_DELAY = 2_147_483_647;
+const RECONNECT_AUTH_TIMEOUT_MS = 10_000;
+const sameRun = (first, second) => first === second ||
+    (first != null &&
+        second != null &&
+        first.id === second.id &&
+        first.status === second.status &&
+        first.canInterrupt === second.canInterrupt &&
+        first.startedAt === second.startedAt);
+const socketAuthRejectionCode = (reason) => {
+    if (reason === null || typeof reason !== "object")
+        return undefined;
+    const record = reason;
+    const data = record["data"] !== null && typeof record["data"] === "object"
+        ? record["data"]
+        : undefined;
+    const status = data?.["status"] ?? data?.["statusCode"] ?? record["status"];
+    if (status === 401 || status === "401")
+        return "authentication";
+    if (status === 403 || status === "403")
+        return "authorization";
+    const code = String(data?.["code"] ?? record["code"] ?? "").toLowerCase();
+    if (code.includes("forbidden") || code.includes("permission")) {
+        return "authorization";
+    }
+    if (code.includes("auth") ||
+        code.includes("credential") ||
+        code.includes("token")) {
+        return "authentication";
+    }
+    const message = reason instanceof Error && typeof reason.message === "string"
+        ? reason.message.toLowerCase()
+        : "";
+    if (message.includes("connection rejected by server") ||
+        message.includes("not authorized") ||
+        message.includes("unauthorized") ||
+        message.includes("authentication") ||
+        message.includes("invalid token") ||
+        message.includes("jwt")) {
+        return "authentication";
+    }
+    if (message.includes("forbidden") || message.includes("permission denied")) {
+        return "authorization";
+    }
+    return undefined;
+};
+const transportConversationId = (payload) => {
+    if (payload === null || typeof payload !== "object")
+        return undefined;
+    const record = payload;
+    const value = record["conversationId"] ?? record["conversation_id"];
+    if (typeof value === "string" && value.trim().length > 0)
+        return value;
+    return typeof value === "number" && Number.isFinite(value)
+        ? String(value)
+        : undefined;
+};
+const belongsToForeignConversation = (payload, conversationId) => {
+    const target = transportConversationId(payload);
+    return target !== undefined && target !== conversationId;
+};
+const authOf = (session) => {
+    const auth = {};
+    const [field, value] = session.kind === "bearer"
+        ? ["token", session.token]
+        : ["admin_key", session.adminKey];
+    Object.defineProperty(auth, field, {
+        configurable: false,
+        enumerable: true,
+        value,
+        writable: false,
+    });
+    return auth;
+};
+export const createSocketIoFactoryWith = (connect) => ({ getAuth, namespaceUrl, path }) => connect(namespaceUrl, {
+    autoConnect: false,
+    path,
+    reconnection: true,
+    transports: ["websocket"],
+    auth(callback) {
+        void getAuth()
+            .then(callback)
+            .catch(() => callback({}));
+    },
+});
+export const createSocketIoFactory = createSocketIoFactoryWith(io);
+export class TFRobotSocketClient {
+    #active;
+    #disposed = false;
+    #establishmentAbort;
+    #factory;
+    #namespaceUrl;
+    #now;
+    #options;
+    #path;
+    #reconnectStatusLoader;
+    #runs = new Map();
+    constructor(options, reconnectStatusLoader) {
+        this.#options = options;
+        this.#factory = options.socketFactory ?? createSocketIoFactory;
+        this.#path = options.socketPath ?? "/socket.io";
+        this.#now = options.now ?? Date.now;
+        this.#namespaceUrl =
+            options.socketNamespaceUrl ?? this.#defaultNamespaceUrl(options.baseUrl);
+        this.#reconnectStatusLoader = reconnectStatusLoader;
+    }
+    async subscribe(conversationId, options, observer) {
+        if (this.#disposed) {
+            return {
+                ok: false,
+                error: this.#error("conflict", "TFRobot Gateway is disposed", false, conversationId),
+            };
+        }
+        if (isGatewayDeadlineExceeded(options, this.#now())) {
+            return {
+                ok: false,
+                error: createGatewayDeadlineExceededError(conversationId),
+            };
+        }
+        this.#deactivateCurrent();
+        const establishmentAbort = new AbortController();
+        this.#establishmentAbort = establishmentAbort;
+        const authOutcome = await awaitBounded(() => this.#getSocketAuth(conversationId, "connect"), {
+            deadlineAt: options.deadlineAt,
+            now: this.#now,
+            signal: establishmentAbort.signal,
+        });
+        if (this.#establishmentAbort === establishmentAbort) {
+            this.#establishmentAbort = undefined;
+        }
+        switch (authOutcome.kind) {
+            case "aborted": {
+                return {
+                    ok: false,
+                    error: this.#error("conflict", this.#disposed
+                        ? "TFRobot Gateway was disposed during subscription"
+                        : "TFRobot subscription was replaced during authentication", false, conversationId),
+                };
+            }
+            case "deadline": {
+                return {
+                    ok: false,
+                    error: createGatewayDeadlineExceededError(conversationId),
+                };
+            }
+            case "error": {
+                return {
+                    ok: false,
+                    error: this.#error("authentication", authOutcome.reason instanceof Error
+                        ? authOutcome.reason.message
+                        : "Unable to obtain a TFRobot Socket session", true, conversationId),
+                };
+            }
+            case "value": {
+                break;
+            }
+        }
+        if (this.#disposed || establishmentAbort.signal.aborted) {
+            return {
+                ok: false,
+                error: this.#error("conflict", "TFRobot Gateway was disposed during subscription", false, conversationId),
+            };
+        }
+        let firstAuth = authOutcome.value;
+        let authenticationFailure;
+        const connectionAbort = new AbortController();
+        let socket;
+        try {
+            socket = this.#factory({
+                namespaceUrl: this.#namespaceUrl,
+                path: this.#path,
+                getAuth: async () => {
+                    if (connectionAbort.signal.aborted) {
+                        throw new Error("TFRobot Socket session refresh was cancelled");
+                    }
+                    if (firstAuth !== undefined) {
+                        const auth = firstAuth;
+                        firstAuth = undefined;
+                        return auth;
+                    }
+                    const reconnectAuth = await awaitBounded(() => this.#getSocketAuth(conversationId, "reconnect"), {
+                        deadlineAt: this.#now() + RECONNECT_AUTH_TIMEOUT_MS,
+                        now: this.#now,
+                        signal: connectionAbort.signal,
+                    });
+                    if (reconnectAuth.kind === "value")
+                        return reconnectAuth.value;
+                    const reason = reconnectAuth.kind === "error"
+                        ? reconnectAuth.reason
+                        : new Error(reconnectAuth.kind === "deadline"
+                            ? "TFRobot Socket session refresh exceeded its deadline"
+                            : "TFRobot Socket session refresh was cancelled");
+                    authenticationFailure = reason;
+                    throw reason;
+                },
+            });
+        }
+        catch (reason) {
+            connectionAbort.abort();
+            return {
+                ok: false,
+                error: this.#transportError(reason, "Unable to create the TFRobot Socket transport", conversationId),
+            };
+        }
+        const listeners = new Map();
+        let setupFailure;
+        const add = (eventName, listener) => {
+            if (setupFailure !== undefined)
+                return;
+            try {
+                socket.on(eventName, listener);
+                listeners.set(eventName, listener);
+            }
+            catch (reason) {
+                setupFailure = { reason };
+            }
+        };
+        const diagnose = (error) => {
+            try {
+                void Promise.resolve(this.#options.onDiagnostic?.(error)).catch(() => undefined);
+            }
+            catch {
+                // Diagnostics are observational and cannot break the chat stream.
+            }
+        };
+        const report = (error) => {
+            if (!active.active)
+                return;
+            try {
+                observer.error?.(error);
+            }
+            catch {
+                // Host observers are isolated from the transport listener.
+            }
+            diagnose(error);
+        };
+        const next = (update) => {
+            if (!active.active)
+                return;
+            const updateConversationId = update.kind === "snapshot.replace"
+                ? update.snapshot.conversation.id
+                : update.kind === "conversation.upsert"
+                    ? update.conversation.id
+                    : update.conversationId;
+            if (updateConversationId !== undefined &&
+                updateConversationId !== conversationId) {
+                return;
+            }
+            try {
+                observer.next(update);
+            }
+            catch {
+                diagnose(this.#error("unknown", "TFRobot Gateway observer rejected an update", false, conversationId));
+            }
+        };
+        const mapAndNext = (invalidMessage, map) => {
+            let update;
+            try {
+                update = map();
+            }
+            catch {
+                report(this.#error("validation", invalidMessage, false, conversationId));
+                return;
+            }
+            next(update);
+        };
+        let settleEstablishment;
+        let connectedOnce = false;
+        add("connect", () => {
+            if (!active.active)
+                return;
+            if (settleEstablishment !== undefined &&
+                isGatewayDeadlineExceeded(options, this.#now())) {
+                settleEstablishment({
+                    ok: false,
+                    error: createGatewayDeadlineExceededError(conversationId),
+                });
+                return;
+            }
+            const reconnect = connectedOnce;
+            connectedOnce = true;
+            const recoveryRevision = ++active.recoveryRevision;
+            try {
+                socket.emit("join_conversation", {
+                    conversation_id: conversationId,
+                });
+            }
+            catch (reason) {
+                const error = this.#transportError(reason, "Unable to join the TFRobot conversation", conversationId);
+                if (settleEstablishment !== undefined) {
+                    settleEstablishment({ ok: false, error });
+                }
+                else {
+                    report(error);
+                    active.active = false;
+                    active.cleanup();
+                    if (this.#active === active)
+                        this.#active = undefined;
+                }
+                return;
+            }
+            if (settleEstablishment !== undefined &&
+                isGatewayDeadlineExceeded(options, this.#now())) {
+                settleEstablishment({
+                    ok: false,
+                    error: createGatewayDeadlineExceededError(conversationId),
+                });
+                return;
+            }
+            settleEstablishment?.({
+                ok: true,
+                value: {
+                    dispose: () => {
+                        if (!active.active)
+                            return;
+                        active.active = false;
+                        active.cleanup();
+                        if (this.#active === active)
+                            this.#active = undefined;
+                    },
+                },
+            });
+            if (reconnect) {
+                void this.#reconcileRunAfterReconnect(active, conversationId, recoveryRevision, next, report).catch(() => {
+                    report(this.#error("unknown", "TFRobot reconnect reconciliation failed", true, conversationId));
+                });
+            }
+        });
+        add("chat_message", (payload) => {
+            if (belongsToForeignConversation(payload, conversationId))
+                return;
+            const parsed = messageDtoSchema.safeParse(payload);
+            if (!parsed.success) {
+                report(this.#error("validation", "Invalid TFRobot chat_message payload", false, conversationId));
+                return;
+            }
+            mapAndNext("TFRobot chat_message could not be normalized", () => mapMessageUpdate(parsed.data));
+        });
+        add("chat_event", (payload) => {
+            if (belongsToForeignConversation(payload, conversationId))
+                return;
+            const parsed = eventDtoSchema.safeParse(payload);
+            if (!parsed.success) {
+                report(this.#error("validation", "Invalid TFRobot chat_event payload", false, conversationId));
+                return;
+            }
+            mapAndNext("TFRobot chat_event could not be normalized", () => mapEventUpdate(parsed.data));
+        });
+        add("conversation_state_changed", (payload) => {
+            if (belongsToForeignConversation(payload, conversationId))
+                return;
+            const parsed = stateChangedDtoSchema.safeParse(payload);
+            if (!parsed.success) {
+                report(this.#error("validation", "Invalid TFRobot conversation_state_changed payload", false, conversationId));
+                return;
+            }
+            const targetConversationId = String(parsed.data.conversationId);
+            if (targetConversationId !== conversationId)
+                return;
+            active.recoveryRevision += 1;
+            mapAndNext("TFRobot run state could not be normalized", () => {
+                const run = mapRun(targetConversationId, {
+                    working: parsed.data.state === "working",
+                    taskId: parsed.data.taskId,
+                });
+                this.#runs.set(targetConversationId, run);
+                return chatUpdateSchema.parse({
+                    kind: "run.replace",
+                    conversationId: targetConversationId,
+                    run,
+                });
+            });
+        });
+        add("chat_error", (payload) => {
+            if (belongsToForeignConversation(payload, conversationId))
+                return;
+            const parsed = chatErrorEventDtoSchema.safeParse(payload);
+            if (!parsed.success) {
+                report(this.#error("validation", "Invalid TFRobot chat_error payload", false, conversationId));
+                return;
+            }
+            const targetConversationId = String(parsed.data.conversationId);
+            if (targetConversationId !== conversationId)
+                return;
+            report(this.#error("server", typeof parsed.data.error === "string"
+                ? parsed.data.error
+                : "TFRobot run failed", false, targetConversationId, parsed.data));
+        });
+        add("error", (payload) => {
+            const parsed = socketProtocolErrorDtoSchema.safeParse(payload);
+            report(this.#error("validation", parsed.success && typeof parsed.data.message === "string"
+                ? parsed.data.message
+                : "TFRobot Socket protocol error", false, conversationId));
+        });
+        add("connect_error", (reason) => {
+            const injectedError = chatErrorSchema.safeParse(reason);
+            const rejectionCode = socketAuthRejectionCode(reason);
+            const error = authenticationFailure !== undefined
+                ? this.#error("authentication", authenticationFailure instanceof Error
+                    ? authenticationFailure.message
+                    : "Unable to refresh the TFRobot Socket session", true, conversationId)
+                : injectedError.success
+                    ? injectedError.data
+                    : rejectionCode !== undefined
+                        ? this.#error(rejectionCode, reason instanceof Error
+                            ? reason.message
+                            : "TFRobot Socket rejected the session", false, conversationId)
+                        : this.#error("network", reason instanceof Error
+                            ? reason.message
+                            : "TFRobot Socket connection failed", true, conversationId);
+            authenticationFailure = undefined;
+            if (error.code === "authentication" || error.code === "authorization") {
+                void this.#invalidateSession(error, rejectionCode === undefined ? undefined : "rejected");
+            }
+            if (settleEstablishment !== undefined) {
+                settleEstablishment({ ok: false, error });
+                return;
+            }
+            report(error);
+        });
+        add("disconnect", (reason) => {
+            if (reason === "io client disconnect")
+                return;
+            active.recoveryRevision += 1;
+            const injectedError = chatErrorSchema.safeParse(reason);
+            report(injectedError.success
+                ? injectedError.data
+                : this.#error("network", `TFRobot Socket disconnected: ${String(reason)}`, true, conversationId));
+        });
+        const anyListener = (eventName, payload) => {
+            if (KNOWN_EVENTS.has(eventName))
+                return;
+            if (belongsToForeignConversation(payload, conversationId))
+                return;
+            mapAndNext("Unknown TFRobot Socket event could not be normalized", () => mapUnknownSocketEvent(eventName, payload, conversationId, this.#now()));
+        };
+        if (setupFailure === undefined) {
+            try {
+                socket.onAny?.(anyListener);
+            }
+            catch (reason) {
+                setupFailure = { reason };
+            }
+        }
+        const cleanup = () => {
+            connectionAbort.abort();
+            for (const [eventName, listener] of listeners) {
+                try {
+                    socket.off(eventName, listener);
+                }
+                catch {
+                    // Continue releasing every transport resource best-effort.
+                }
+            }
+            try {
+                socket.offAny?.(anyListener);
+            }
+            catch {
+                // Continue to the transport disconnect.
+            }
+            try {
+                socket.disconnect();
+            }
+            catch {
+                // Adapter ownership is cleared even if an injected transport misbehaves.
+            }
+        };
+        if (setupFailure !== undefined) {
+            cleanup();
+            return {
+                ok: false,
+                error: this.#transportError(setupFailure.reason, "Unable to configure the TFRobot Socket transport", conversationId),
+            };
+        }
+        const active = {
+            active: true,
+            cancelEstablishment: () => {
+                settleEstablishment?.({
+                    ok: false,
+                    error: this.#error("conflict", "TFRobot Gateway was disposed during subscription", false, conversationId),
+                });
+            },
+            cleanup,
+            conversationId,
+            observer,
+            recoveryRevision: 0,
+            socket,
+        };
+        this.#active = active;
+        return new Promise((resolve) => {
+            let settled = false;
+            const settle = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                settleEstablishment = undefined;
+                clearTimeout(timeout);
+                if (!result.ok) {
+                    active.active = false;
+                    active.cleanup();
+                    if (this.#active === active)
+                        this.#active = undefined;
+                }
+                resolve(result);
+            };
+            settleEstablishment = settle;
+            const timeout = setTimeout(() => {
+                settle({
+                    ok: false,
+                    error: createGatewayDeadlineExceededError(conversationId),
+                });
+            }, Math.min(MAX_TIMER_DELAY, Math.max(0, options.deadlineAt - this.#now())));
+            if (isGatewayDeadlineExceeded(options, this.#now())) {
+                settle({
+                    ok: false,
+                    error: createGatewayDeadlineExceededError(conversationId),
+                });
+                return;
+            }
+            try {
+                socket.connect();
+            }
+            catch (reason) {
+                settle({
+                    ok: false,
+                    error: this.#transportError(reason, "Unable to connect the TFRobot Socket transport", conversationId),
+                });
+                return;
+            }
+            if (isGatewayDeadlineExceeded(options, this.#now())) {
+                settle({
+                    ok: false,
+                    error: createGatewayDeadlineExceededError(conversationId),
+                });
+            }
+        });
+    }
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.#deactivateCurrent();
+        this.#runs.clear();
+    }
+    rememberRun(conversationId, run) {
+        if (this.#disposed)
+            return;
+        this.#runs.set(conversationId, run);
+    }
+    #deactivateCurrent() {
+        this.#establishmentAbort?.abort();
+        this.#establishmentAbort = undefined;
+        const current = this.#active;
+        if (current === undefined)
+            return;
+        current.cancelEstablishment();
+        current.active = false;
+        current.cleanup();
+        this.#active = undefined;
+    }
+    #defaultNamespaceUrl(baseUrl) {
+        const url = new URL(baseUrl);
+        url.pathname = "/chat";
+        url.search = "";
+        url.hash = "";
+        return url.toString().replace(/\/$/u, "");
+    }
+    async #getSocketAuth(conversationId, purpose) {
+        const session = await this.#options.sessionProvider.getSession({
+            purpose,
+            operation: "subscribe",
+            conversationId,
+        });
+        if (!isValidTFRobotSession(session)) {
+            throw new TypeError("SessionProvider returned invalid TFRobot credentials");
+        }
+        return authOf(session);
+    }
+    async #reconcileRunAfterReconnect(active, conversationId, recoveryRevision, next, report) {
+        const result = await this.#reconnectStatusLoader(conversationId);
+        if (!active.active ||
+            this.#active !== active ||
+            !active.socket.connected ||
+            active.recoveryRevision !== recoveryRevision) {
+            return;
+        }
+        if (!result.ok) {
+            report(result.error);
+            return;
+        }
+        try {
+            const run = mapRun(conversationId, result.value);
+            const previous = this.#runs.get(conversationId);
+            this.#runs.set(conversationId, run);
+            if (sameRun(previous, run))
+                return;
+            next(chatUpdateSchema.parse({
+                kind: "run.replace",
+                conversationId,
+                run,
+            }));
+        }
+        catch {
+            report(this.#error("validation", "Reconnected TFRobot run status could not be normalized", false, conversationId));
+        }
+    }
+    async #invalidateSession(error, reason) {
+        try {
+            await this.#options.sessionProvider.onSessionInvalid?.({
+                reason: reason ?? (error.code === "authorization" ? "forbidden" : "expired"),
+                error,
+            });
+        }
+        catch {
+            // Host refresh/login failures must not replace the Socket error.
+        }
+    }
+    #transportError(reason, fallback, conversationId) {
+        return this.#error("network", reason instanceof Error ? reason.message : fallback, true, conversationId);
+    }
+    #error(code, message, retryable, conversationId, details) {
+        let safeDetails;
+        try {
+            safeDetails = details === undefined ? undefined : sanitizeRaw(details);
+        }
+        catch {
+            safeDetails = undefined;
+        }
+        return chatErrorSchema.parse({
+            code,
+            message: sanitizeDiagnosticText(message),
+            retryable,
+            conversationId,
+            ...(safeDetails === undefined ? {} : { details: safeDetails }),
+        });
+    }
+}
+//# sourceMappingURL=socket.js.map