@diffexai/diffex-client 0.2.0

package/dist/client.js

@@ -0,0 +1,384 @@
+import { encodeClientMessage, ProtocolValidationError, } from "@diffexai/diffex-protocol";
+import { Connection } from "./connection.js";
+import { DiffexClientDisposedError, DiffexDisconnectedError, DiffexServerError, DiffexSessionDetachedError, DiffexSessionOwnershipError, toError, } from "./errors.js";
+import { createPromiseResolvers } from "./promise.js";
+import { SessionHandle, } from "./session-handle.js";
+import { ClientState } from "./state.js";
+export class DiffexClient {
+    #options;
+    #connection;
+    #state;
+    #pendingRequests = new Map();
+    #sessionLeaseCounts = new Map();
+    #exclusiveSessionLeases = new Map();
+    #sessionLeaseGenerations = new Map();
+    #sessionAttachments = new Map();
+    #sessionDetachments = new Map();
+    #sessionCleanupRequired = new Set();
+    #sessionReconciliations = new Map();
+    #connectionStateListeners = new Set();
+    #requestSequence = 0;
+    #disposed = false;
+    #disposePromise;
+    constructor(options) {
+        this.#options = options;
+        this.#state = new ClientState(options.onListenerError);
+        this.#connection = new Connection({
+            transportFactory: options.transportFactory,
+            maxFrameLength: options.maxFrameLength,
+            onHandshake: (snapshot) => this.#state.applyServerSnapshot(snapshot),
+            onMessage: (message) => this.#handleMessage(message),
+            onStateChange: (change) => this.#handleConnectionStateChange(change),
+        });
+    }
+    get disposed() {
+        return this.#disposed;
+    }
+    get connectionState() {
+        return this.#connection.state;
+    }
+    get connected() {
+        return this.#connection.state === "connected";
+    }
+    get snapshot() {
+        return this.#state.snapshot;
+    }
+    static async connect(options) {
+        const client = new DiffexClient(options);
+        try {
+            await client.connect();
+            return client;
+        }
+        catch (error) {
+            await client.dispose();
+            throw error;
+        }
+    }
+    connect() {
+        if (this.#disposed)
+            return Promise.reject(new DiffexClientDisposedError());
+        if (this.#connection.state === "disconnected")
+            this.#state.reset();
+        return this.#connection.connect();
+    }
+    reconnect() {
+        return this.connect();
+    }
+    disconnect(reason = "Client disconnected") {
+        this.#connection.disconnect(reason);
+    }
+    subscribe(listener) {
+        this.#assertNotDisposed();
+        return this.#state.subscribe(listener);
+    }
+    onEvent(listener) {
+        this.#assertNotDisposed();
+        return this.#state.onEvent(listener);
+    }
+    onConnectionStateChange(listener) {
+        this.#assertNotDisposed();
+        this.#connectionStateListeners.add(listener);
+        return () => this.#connectionStateListeners.delete(listener);
+    }
+    async listSessions() {
+        return (await this.#request({ command: "list" })).sessions;
+    }
+    async createSession(options = {}) {
+        const result = await this.#request({ command: "create", ...options });
+        const token = this.#reserveSessionLease(result.session.id, "exclusive");
+        return this.#createSessionLease(result.session.id, token);
+    }
+    async attachSession(sessionId) {
+        return this.acquireSession(sessionId, { mode: "shared" });
+    }
+    async acquireSession(sessionId, options) {
+        this.#assertNotDisposed();
+        const token = this.#reserveSessionLease(sessionId, options.mode);
+        try {
+            const detachment = this.#sessionDetachments.get(sessionId);
+            if (detachment)
+                await detachment.catch(() => { });
+            const reconciled = this.#sessionCleanupRequired.has(sessionId)
+                ? await this.#reconcileSessionCleanup(sessionId)
+                : false;
+            if (reconciled || !this.#state.isSessionAttached(sessionId)) {
+                let attachment = this.#sessionAttachments.get(sessionId);
+                if (!attachment) {
+                    attachment = this.#attachSession(sessionId);
+                    this.#sessionAttachments.set(sessionId, attachment);
+                }
+                try {
+                    await attachment;
+                }
+                finally {
+                    if (this.#sessionAttachments.get(sessionId) === attachment)
+                        this.#sessionAttachments.delete(sessionId);
+                }
+            }
+            return this.#createSessionLease(sessionId, token);
+        }
+        catch (error) {
+            this.#releaseSessionLease(sessionId, token);
+            throw error;
+        }
+    }
+    async #attachSession(sessionId) {
+        const previous = this.#state.forgetSessionSnapshot(sessionId);
+        try {
+            await this.#request({ command: "attach", sessionId });
+        }
+        catch (error) {
+            if (previous)
+                this.#state.restoreSessionSnapshot(previous);
+            throw error;
+        }
+    }
+    #request(command) {
+        if (this.#disposed)
+            return Promise.reject(new DiffexClientDisposedError());
+        if (!this.connected)
+            return Promise.reject(new DiffexDisconnectedError());
+        const id = `request-${++this.#requestSequence}`;
+        const { promise, resolve, reject } = createPromiseResolvers();
+        this.#pendingRequests.set(id, { command, resolve, reject });
+        let frame;
+        try {
+            frame = encodeClientMessage({ type: "request", id, request: command }, { maxFrameLength: this.#connection.maxFrameLength });
+        }
+        catch (error) {
+            this.#takePendingRequest(id)?.reject(toError(error));
+            return promise;
+        }
+        this.#connection.send(frame);
+        return promise;
+    }
+    #createSessionLease(sessionId, token) {
+        const generation = this.#sessionLeaseGenerations.get(sessionId) ?? 0;
+        this.#sessionLeaseGenerations.set(sessionId, generation);
+        let state = "active";
+        let releasePromise;
+        const refreshState = () => {
+            if ((state === "active" || state === "releasing") &&
+                this.#sessionLeaseGenerations.get(sessionId) !== generation) {
+                state = "invalidated";
+            }
+        };
+        const isActive = () => {
+            refreshState();
+            return state === "active" && this.#state.isSessionAttached(sessionId);
+        };
+        const assertActive = () => {
+            this.#assertNotDisposed();
+            if (!this.connected)
+                throw new DiffexDisconnectedError();
+            if (!isActive())
+                throw new DiffexSessionDetachedError(sessionId);
+        };
+        const release = (relinquishOnFailure) => {
+            refreshState();
+            if (state === "released" || state === "invalidated")
+                return Promise.resolve();
+            if (releasePromise)
+                return releasePromise;
+            assertActive();
+            state = "releasing";
+            releasePromise = (async () => {
+                const count = this.#sessionLeaseCounts.get(sessionId) ?? 0;
+                if (count <= 1) {
+                    const detachment = this.#request({ command: "detach", sessionId }).then(() => undefined);
+                    this.#sessionDetachments.set(sessionId, detachment);
+                    try {
+                        await detachment;
+                        this.#releaseSessionLease(sessionId, token);
+                    }
+                    finally {
+                        if (this.#sessionDetachments.get(sessionId) === detachment) {
+                            this.#sessionDetachments.delete(sessionId);
+                        }
+                    }
+                }
+                else {
+                    this.#releaseSessionLease(sessionId, token);
+                }
+                state = "released";
+            })().catch((error) => {
+                refreshState();
+                if (state === "invalidated")
+                    return;
+                if (relinquishOnFailure) {
+                    this.#releaseSessionLease(sessionId, token);
+                    this.#sessionCleanupRequired.add(sessionId);
+                    state = "released";
+                }
+                else {
+                    state = "active";
+                    releasePromise = undefined;
+                }
+                throw error;
+            });
+            return releasePromise;
+        };
+        const callbacks = {
+            isAttached: isActive,
+            getSnapshot: () => (isActive() ? this.#state.getSessionSnapshot(sessionId) : undefined),
+            subscribe: (listener) => {
+                assertActive();
+                return this.#state.subscribeSession(sessionId, (snapshot) => {
+                    if (isActive())
+                        listener(snapshot);
+                });
+            },
+            onEvent: (listener) => {
+                assertActive();
+                return this.#state.onSessionEvent(sessionId, (event) => {
+                    if (isActive() || event.type === "session_removed")
+                        listener(event);
+                });
+            },
+            detach: () => release(false),
+            dispose: () => release(true),
+            request: (command) => {
+                assertActive();
+                return this.#request(command);
+            },
+        };
+        return new SessionHandle(sessionId, callbacks);
+    }
+    #handleMessage(message) {
+        if (message.type === "event") {
+            if (message.event.type === "session_removed")
+                this.#invalidateSessionLeases(message.event.sessionId);
+            this.#state.applyEvent(message.event);
+            return;
+        }
+        const pending = this.#takePendingRequest(message.id);
+        if (!pending) {
+            this.#connection.fail(new ProtocolValidationError("Response has no matching request"));
+            return;
+        }
+        if (!message.ok) {
+            pending.reject(new DiffexServerError(message.error));
+            return;
+        }
+        if (message.result.command !== pending.command.command) {
+            const error = new ProtocolValidationError(`Response command ${message.result.command} does not match ${pending.command.command}`);
+            pending.reject(error);
+            this.#connection.fail(error);
+            return;
+        }
+        this.#state.applyResult(message.result);
+        pending.resolve(message.result);
+    }
+    #handleConnectionStateChange(change) {
+        if (change.state === "disconnected") {
+            this.#state.clearAttachments();
+            this.#invalidateAllSessionLeases();
+            this.#rejectPendingRequests(change.error ?? new DiffexDisconnectedError());
+        }
+        this.#notifyConnectionStateListeners(change);
+    }
+    #takePendingRequest(id) {
+        const request = this.#pendingRequests.get(id);
+        if (request)
+            this.#pendingRequests.delete(id);
+        return request;
+    }
+    #rejectPendingRequests(error) {
+        const requests = [...this.#pendingRequests.values()];
+        this.#pendingRequests.clear();
+        for (const request of requests)
+            request.reject(error);
+    }
+    dispose() {
+        if (this.#disposePromise)
+            return this.#disposePromise;
+        this.#disposed = true;
+        this.#disposePromise = Promise.resolve();
+        const error = new DiffexClientDisposedError();
+        this.#rejectPendingRequests(error);
+        this.#connection.disconnect(error);
+        this.#state.dispose();
+        this.#invalidateAllSessionLeases();
+        this.#connectionStateListeners.clear();
+        return this.#disposePromise;
+    }
+    [Symbol.asyncDispose]() {
+        return this.dispose();
+    }
+    #assertNotDisposed() {
+        if (this.#disposed)
+            throw new DiffexClientDisposedError();
+    }
+    async #reconcileSessionCleanup(sessionId) {
+        if (!this.#sessionCleanupRequired.has(sessionId))
+            return false;
+        let reconciliation = this.#sessionReconciliations.get(sessionId);
+        if (!reconciliation) {
+            reconciliation = this.#request({ command: "detach", sessionId })
+                .then(() => undefined)
+                .then(() => {
+                this.#sessionCleanupRequired.delete(sessionId);
+            })
+                .finally(() => {
+                this.#sessionReconciliations.delete(sessionId);
+            });
+            this.#sessionReconciliations.set(sessionId, reconciliation);
+        }
+        await reconciliation;
+        return true;
+    }
+    #reserveSessionLease(sessionId, mode) {
+        const count = this.#sessionLeaseCounts.get(sessionId) ?? 0;
+        if (mode === "exclusive" && count > 0) {
+            throw new DiffexSessionOwnershipError(sessionId, `Session ${sessionId} already has an active lease`);
+        }
+        if (mode === "shared" && this.#exclusiveSessionLeases.has(sessionId)) {
+            throw new DiffexSessionOwnershipError(sessionId, `Session ${sessionId} has an exclusive lease`);
+        }
+        const token = { mode };
+        this.#sessionLeaseCounts.set(sessionId, count + 1);
+        if (mode === "exclusive")
+            this.#exclusiveSessionLeases.set(sessionId, token);
+        return token;
+    }
+    #releaseSessionLease(sessionId, token) {
+        const count = this.#sessionLeaseCounts.get(sessionId) ?? 0;
+        if (count <= 1)
+            this.#sessionLeaseCounts.delete(sessionId);
+        else
+            this.#sessionLeaseCounts.set(sessionId, count - 1);
+        if (this.#exclusiveSessionLeases.get(sessionId) === token)
+            this.#exclusiveSessionLeases.delete(sessionId);
+    }
+    #invalidateSessionLeases(sessionId) {
+        this.#sessionLeaseCounts.delete(sessionId);
+        this.#exclusiveSessionLeases.delete(sessionId);
+        this.#sessionCleanupRequired.delete(sessionId);
+        this.#sessionLeaseGenerations.set(sessionId, (this.#sessionLeaseGenerations.get(sessionId) ?? 0) + 1);
+    }
+    #invalidateAllSessionLeases() {
+        for (const sessionId of this.#sessionLeaseCounts.keys())
+            this.#invalidateSessionLeases(sessionId);
+        this.#sessionCleanupRequired.clear();
+    }
+    #notifyConnectionStateListeners(change) {
+        for (const listener of this.#connectionStateListeners) {
+            try {
+                listener(change);
+            }
+            catch (error) {
+                this.#reportListenerError(error);
+            }
+        }
+    }
+    #reportListenerError(error) {
+        if (!this.#options.onListenerError)
+            return;
+        try {
+            this.#options.onListenerError(toError(error));
+        }
+        catch {
+            // Diagnostics cannot affect protocol or transport state.
+        }
+    }
+}

package/dist/cloud.d.ts

@@ -0,0 +1,57 @@
+import type { ByteTransportFactory } from "./transport.ts";
+import { type WebSocketConstructor } from "./websocket.ts";
+export type CloudSessionStatus = "creating" | "running" | "stopping" | "stopped" | "failed" | "deleting" | "deleted";
+export interface CloudSession {
+    session_id: string;
+    status: CloudSessionStatus;
+    created_at: string;
+    updated_at: string;
+}
+export interface CloudRuntimeAttachment {
+    url: string;
+    expires_at: string;
+    protocol_version: number;
+}
+interface CloudFetchResponse {
+    readonly ok: boolean;
+    readonly status: number;
+    json(): Promise<unknown>;
+}
+export type CloudFetch = (input: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}) => Promise<CloudFetchResponse>;
+export interface DiffexCloudClientOptions {
+    baseUrl: string | URL;
+    accessToken: string | (() => string | Promise<string>);
+    fetch?: CloudFetch;
+}
+export interface CloudTransportOptions {
+    maxPendingBytes?: number;
+    webSocket?: WebSocketConstructor;
+}
+export declare class DiffexCloudApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId?: string;
+    constructor(input: {
+        status: number;
+        code: string;
+        message: string;
+        requestId?: string;
+    });
+}
+/** Authenticated control-plane client for hosted Diffex session lifecycle and attachment. */
+export declare class DiffexCloudClient {
+    #private;
+    constructor(options: DiffexCloudClientOptions);
+    createSession(): Promise<CloudSession>;
+    listSessions(): Promise<CloudSession[]>;
+    getSession(sessionId: string): Promise<CloudSession>;
+    createAttachment(sessionId: string): Promise<CloudRuntimeAttachment>;
+    stopSession(sessionId: string): Promise<CloudSession>;
+    deleteSession(sessionId: string): Promise<void>;
+    createTransportFactory(sessionId: string, options?: CloudTransportOptions): ByteTransportFactory;
+}
+export {};

package/dist/cloud.js

@@ -0,0 +1,188 @@
+import { PROTOCOL_VERSION } from "@diffexai/diffex-protocol";
+import { createWebSocketTransportFactory } from "./websocket.js";
+export class DiffexCloudApiError extends Error {
+    status;
+    code;
+    requestId;
+    constructor(input) {
+        super(input.message);
+        this.name = "DiffexCloudApiError";
+        this.status = input.status;
+        this.code = input.code;
+        this.requestId = input.requestId;
+    }
+}
+/** Authenticated control-plane client for hosted Diffex session lifecycle and attachment. */
+export class DiffexCloudClient {
+    #baseUrl;
+    #accessToken;
+    #fetch;
+    constructor(options) {
+        this.#baseUrl = normalizedBaseUrl(options.baseUrl);
+        this.#accessToken = options.accessToken;
+        this.#fetch = options.fetch ?? requiredFetch();
+    }
+    async createSession() {
+        const value = await this.#request("POST", "/v1/cloud/sessions", {});
+        return sessionResponse(value);
+    }
+    async listSessions() {
+        const value = record(await this.#request("GET", "/v1/cloud/sessions"));
+        if (!Array.isArray(value.sessions))
+            throw invalidResponse();
+        return value.sessions.map(cloudSession);
+    }
+    async getSession(sessionId) {
+        return sessionResponse(await this.#request("GET", sessionPath(sessionId)));
+    }
+    async createAttachment(sessionId) {
+        const value = record(await this.#request("POST", `${sessionPath(sessionId)}/attach`, {}));
+        return cloudAttachment(value.attachment);
+    }
+    async stopSession(sessionId) {
+        return sessionResponse(await this.#request("POST", `${sessionPath(sessionId)}/stop`, {}));
+    }
+    async deleteSession(sessionId) {
+        await this.#request("DELETE", sessionPath(sessionId));
+    }
+    createTransportFactory(sessionId, options = {}) {
+        assertSessionId(sessionId);
+        return createWebSocketTransportFactory({
+            url: async () => (await this.createAttachment(sessionId)).url,
+            ...(options.maxPendingBytes === undefined ? {} : { maxPendingBytes: options.maxPendingBytes }),
+            ...(options.webSocket === undefined ? {} : { webSocket: options.webSocket }),
+        });
+    }
+    async #request(method, path, body) {
+        const token = await resolveAccessToken(this.#accessToken);
+        const response = await this.#fetch(new URL(path, this.#baseUrl).toString(), {
+            method,
+            headers: {
+                authorization: `Bearer ${token}`,
+                accept: "application/json",
+                ...(body === undefined ? {} : { "content-type": "application/json" }),
+            },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        if (response.status === 204)
+            return undefined;
+        const value = await response.json().catch(() => undefined);
+        if (!response.ok)
+            throw apiError(response.status, value);
+        return value;
+    }
+}
+function normalizedBaseUrl(input) {
+    const value = new URL(input);
+    if (value.username ||
+        value.password ||
+        (value.protocol !== "https:" && !(value.protocol === "http:" && isLoopbackHostname(value.hostname)))) {
+        throw new TypeError("Diffex cloud baseUrl must use HTTPS outside localhost");
+    }
+    value.pathname = value.pathname.endsWith("/") ? value.pathname : `${value.pathname}/`;
+    value.search = "";
+    value.hash = "";
+    return value;
+}
+function requiredFetch() {
+    const candidate = globalThis.fetch;
+    if (!candidate)
+        throw new Error("fetch is not available in this runtime");
+    return (input, init) => candidate(input, init);
+}
+async function resolveAccessToken(input) {
+    const value = typeof input === "function" ? await input() : input;
+    const token = value.trim();
+    if (!token)
+        throw new Error("Diffex cloud access token is empty");
+    return token;
+}
+function sessionPath(sessionId) {
+    assertSessionId(sessionId);
+    return `/v1/cloud/sessions/${encodeURIComponent(sessionId)}`;
+}
+function assertSessionId(sessionId) {
+    if (!sessionId.trim())
+        throw new TypeError("Diffex cloud session ID is required");
+}
+function sessionResponse(input) {
+    return cloudSession(record(input).session);
+}
+function cloudSession(input) {
+    const value = record(input);
+    const sessionId = stringValue(value.session_id);
+    const status = stringValue(value.status);
+    const createdAt = isoTimestamp(value.created_at);
+    const updatedAt = isoTimestamp(value.updated_at);
+    if (!isCloudSessionStatus(status))
+        throw invalidResponse();
+    return { session_id: sessionId, status, created_at: createdAt, updated_at: updatedAt };
+}
+function cloudAttachment(input) {
+    const value = record(input);
+    const url = stringValue(value.url);
+    const parsedUrl = new URL(url);
+    if (parsedUrl.username ||
+        parsedUrl.password ||
+        (parsedUrl.protocol !== "wss:" && !(parsedUrl.protocol === "ws:" && isLoopbackHostname(parsedUrl.hostname)))) {
+        throw invalidResponse();
+    }
+    const protocolVersion = value.protocol_version;
+    if (protocolVersion !== PROTOCOL_VERSION) {
+        throw new DiffexCloudApiError({
+            status: 409,
+            code: "unsupported_protocol_version",
+            message: `Diffex cloud requires protocol version ${String(protocolVersion)}; this client supports ${String(PROTOCOL_VERSION)}`,
+        });
+    }
+    return {
+        url,
+        expires_at: isoTimestamp(value.expires_at),
+        protocol_version: Number(protocolVersion),
+    };
+}
+function isLoopbackHostname(hostname) {
+    const normalized = hostname.toLowerCase().replace(/^\[(.*)\]$/u, "$1");
+    return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1";
+}
+function isCloudSessionStatus(value) {
+    return ["creating", "running", "stopping", "stopped", "failed", "deleting", "deleted"].includes(value);
+}
+function apiError(status, input) {
+    const error = optionalRecord(optionalRecord(input)?.error);
+    return new DiffexCloudApiError({
+        status,
+        code: typeof error?.code === "string" ? error.code : "request_failed",
+        message: typeof error?.message === "string" ? error.message : `Diffex cloud request failed (${status})`,
+        ...(typeof error?.requestId === "string" ? { requestId: error.requestId } : {}),
+    });
+}
+function record(input) {
+    const value = optionalRecord(input);
+    if (!value)
+        throw invalidResponse();
+    return value;
+}
+function optionalRecord(input) {
+    return typeof input === "object" && input !== null && !Array.isArray(input)
+        ? input
+        : undefined;
+}
+function stringValue(input) {
+    if (typeof input !== "string" || !input)
+        throw invalidResponse();
+    return input;
+}
+function isoTimestamp(input) {
+    const value = stringValue(input);
+    if (Number.isNaN(Date.parse(value)))
+        throw invalidResponse();
+    return value;
+}
+function invalidResponse() {
+    return new DiffexCloudApiError({
+        status: 502,
+        code: "invalid_response",
+        message: "Diffex cloud returned an invalid response",
+    });
+}

package/dist/connection.d.ts

@@ -0,0 +1,23 @@
+import { type ServerMessage, type ServerSnapshot } from "@diffexai/diffex-protocol";
+import type { ByteTransportFactory } from "./transport.ts";
+import type { ConnectionState, ConnectionStateChange } from "./types.ts";
+interface ConnectionOptions {
+    transportFactory: ByteTransportFactory;
+    maxFrameLength?: number;
+    onHandshake(snapshot: ServerSnapshot): void;
+    onMessage(message: Exclude<ServerMessage, {
+        type: "hello" | "hello_error";
+    }>): void;
+    onStateChange(change: ConnectionStateChange): void;
+}
+export declare class Connection {
+    #private;
+    constructor(options: ConnectionOptions);
+    get state(): ConnectionState;
+    get maxFrameLength(): number;
+    connect(): Promise<ServerSnapshot>;
+    disconnect(reason?: string | Error): void;
+    fail(error: Error): void;
+    send(frame: Uint8Array): void;
+}
+export {};