@diffexai/diffex-client 0.2.0

package/dist/unix.js

@@ -0,0 +1,150 @@
+import { createConnection } from "node:net";
+import { DEFAULT_MAX_FRAME_LENGTH } from "@diffexai/diffex-protocol";
+const MAX_UNIX_SOCKET_PATH_BYTES = process.platform === "linux" ? 107 : 103;
+/** Creates fresh Unix-domain socket transports for DiffexClient connection attempts in Node-compatible runtimes. */
+export function createUnixTransportFactory(options) {
+    if (options.path.length === 0)
+        throw new TypeError("Unix transport path must not be empty");
+    if (Buffer.byteLength(options.path) > MAX_UNIX_SOCKET_PATH_BYTES) {
+        throw new TypeError(`Unix transport path is too long; maximum is ${MAX_UNIX_SOCKET_PATH_BYTES} UTF-8 bytes`);
+    }
+    const maxPendingBytes = options.maxPendingBytes ?? DEFAULT_MAX_FRAME_LENGTH * 4;
+    if (!Number.isSafeInteger(maxPendingBytes) || maxPendingBytes <= 0) {
+        throw new TypeError("Unix transport maxPendingBytes must be a positive safe integer");
+    }
+    if (process.platform === "win32")
+        throw new Error("Unix transport is not supported on Windows");
+    return (handlers) => connectUnixSocket(options.path, maxPendingBytes, handlers);
+}
+function connectUnixSocket(path, maxPendingBytes, handlers) {
+    return new Promise((resolve, reject) => {
+        const socket = createConnection(path);
+        let connected = false;
+        let terminal = false;
+        const close = () => {
+            if (terminal)
+                return;
+            terminal = true;
+            socket.destroy();
+            if (connected)
+                handlers.onClose();
+            else
+                reject(new Error("Unix transport closed before connecting"));
+        };
+        socket.once("connect", () => {
+            if (terminal)
+                return;
+            connected = true;
+            resolve(new UnixByteTransport(socket, maxPendingBytes, () => {
+                terminal = true;
+            }));
+        });
+        socket.on("data", (chunk) => {
+            if (!terminal)
+                handlers.onData(new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength));
+        });
+        socket.once("end", close);
+        socket.once("close", close);
+        socket.once("error", (error) => {
+            if (terminal)
+                return;
+            terminal = true;
+            socket.destroy();
+            if (connected)
+                handlers.onError(error);
+            else
+                reject(error);
+        });
+    });
+}
+class UnixByteTransport {
+    #socket;
+    #maxPendingBytes;
+    #markLocalClose;
+    #closed = false;
+    #pendingBytes = 0;
+    #writeTail = Promise.resolve();
+    constructor(socket, maxPendingBytes, markLocalClose) {
+        this.#socket = socket;
+        this.#maxPendingBytes = maxPendingBytes;
+        this.#markLocalClose = markLocalClose;
+    }
+    send(chunk) {
+        if (!(chunk instanceof Uint8Array)) {
+            return Promise.reject(new TypeError("Unix transport chunks must be Uint8Array"));
+        }
+        if (this.#closed)
+            return Promise.reject(new Error("Unix transport is closed"));
+        if (this.#pendingBytes + chunk.byteLength > this.#maxPendingBytes) {
+            return Promise.reject(new Error("Unix transport exceeded its pending byte limit"));
+        }
+        this.#pendingBytes += chunk.byteLength;
+        const bytes = chunk.slice();
+        const write = this.#writeTail.then(() => this.#write(bytes));
+        const tracked = write.finally(() => {
+            this.#pendingBytes -= bytes.byteLength;
+        });
+        this.#writeTail = tracked.catch(() => { });
+        return tracked;
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#markLocalClose();
+        this.#socket.destroy();
+    }
+    #write(chunk) {
+        if (this.#closed || !this.#socket.writable)
+            return Promise.reject(new Error("Unix transport is closed"));
+        return new Promise((resolve, reject) => {
+            let callbackComplete = false;
+            let drainComplete = false;
+            let requiresDrain;
+            let settled = false;
+            const onDrain = () => {
+                drainComplete = true;
+                finish();
+            };
+            const cleanup = () => {
+                this.#socket.off("drain", onDrain);
+                this.#socket.off("close", onClose);
+            };
+            const fail = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                reject(error);
+            };
+            const finish = () => {
+                if (settled || !callbackComplete || requiresDrain === undefined)
+                    return;
+                if (requiresDrain && !drainComplete)
+                    return;
+                settled = true;
+                cleanup();
+                resolve();
+            };
+            const onClose = () => fail(new Error("Unix transport closed during write"));
+            try {
+                this.#socket.once("close", onClose);
+                const accepted = this.#socket.write(chunk, (error) => {
+                    if (error) {
+                        fail(error);
+                        return;
+                    }
+                    callbackComplete = true;
+                    finish();
+                });
+                requiresDrain = !accepted;
+                if (requiresDrain)
+                    this.#socket.once("drain", onDrain);
+                finish();
+            }
+            catch (error) {
+                fail(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
+}

package/dist/websocket.d.ts

@@ -0,0 +1,42 @@
+import type { ByteTransportFactory } from "./transport.ts";
+type WebSocketData = ArrayBuffer | ArrayBufferView;
+interface WebSocketMessageEvent {
+    readonly data: unknown;
+}
+interface WebSocketCloseEvent {
+    readonly code: number;
+    readonly reason: string;
+}
+interface WebSocketErrorEvent {
+    readonly error?: unknown;
+}
+interface WebSocketLike {
+    binaryType: string;
+    readonly bufferedAmount: number;
+    readonly readyState: number;
+    send(data: WebSocketData): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: "open", listener: () => void, options?: {
+        once?: boolean;
+    }): void;
+    addEventListener(type: "message", listener: (event: WebSocketMessageEvent) => void): void;
+    addEventListener(type: "close", listener: (event: WebSocketCloseEvent) => void, options?: {
+        once?: boolean;
+    }): void;
+    addEventListener(type: "error", listener: (event: WebSocketErrorEvent) => void, options?: {
+        once?: boolean;
+    }): void;
+}
+export interface WebSocketConstructor {
+    new (url: string | URL, protocols?: string | string[]): WebSocketLike;
+    readonly OPEN: number;
+}
+export interface WebSocketTransportOptions {
+    url: string | URL | (() => string | URL | Promise<string | URL>);
+    protocols?: string | string[];
+    maxPendingBytes?: number;
+    webSocket?: WebSocketConstructor;
+}
+/** Creates authenticated browser-compatible WebSocket transports for DiffexClient connection attempts. */
+export declare function createWebSocketTransportFactory(options: WebSocketTransportOptions): ByteTransportFactory;
+export {};

package/dist/websocket.js

@@ -0,0 +1,124 @@
+import { DEFAULT_MAX_FRAME_LENGTH } from "@diffexai/diffex-protocol";
+/** Creates authenticated browser-compatible WebSocket transports for DiffexClient connection attempts. */
+export function createWebSocketTransportFactory(options) {
+    const maxPendingBytes = options.maxPendingBytes ?? DEFAULT_MAX_FRAME_LENGTH * 4;
+    if (!Number.isSafeInteger(maxPendingBytes) || maxPendingBytes <= 0) {
+        throw new TypeError("WebSocket transport maxPendingBytes must be a positive safe integer");
+    }
+    return async (handlers) => {
+        const url = typeof options.url === "function" ? await options.url() : options.url;
+        const WebSocketImpl = options.webSocket ?? resolveGlobalWebSocket();
+        return connectWebSocket(WebSocketImpl, url, options.protocols, maxPendingBytes, handlers);
+    };
+}
+function resolveGlobalWebSocket() {
+    const candidate = globalThis.WebSocket;
+    if (!candidate)
+        throw new Error("WebSocket is not available in this runtime");
+    return candidate;
+}
+function connectWebSocket(WebSocketImpl, url, protocols, maxPendingBytes, handlers) {
+    return new Promise((resolve, reject) => {
+        const socket = protocols === undefined ? new WebSocketImpl(url) : new WebSocketImpl(url, protocols);
+        socket.binaryType = "arraybuffer";
+        let connected = false;
+        let terminal = false;
+        socket.addEventListener("open", () => {
+            if (terminal)
+                return;
+            connected = true;
+            resolve(new WebSocketByteTransport(socket, WebSocketImpl.OPEN, maxPendingBytes, () => {
+                terminal = true;
+            }));
+        }, { once: true });
+        socket.addEventListener("message", (event) => {
+            if (terminal)
+                return;
+            const bytes = binaryMessage(event.data);
+            if (!bytes) {
+                terminal = true;
+                socket.close(1003, "Binary protocol frames required");
+                handlers.onError(new Error("WebSocket transport received a non-binary message"));
+                return;
+            }
+            handlers.onData(bytes);
+        });
+        socket.addEventListener("close", (event) => {
+            if (terminal)
+                return;
+            terminal = true;
+            if (connected)
+                handlers.onClose();
+            else
+                reject(new Error(`WebSocket transport closed before connecting (${event.code}: ${event.reason})`));
+        }, { once: true });
+        socket.addEventListener("error", (event) => {
+            if (terminal)
+                return;
+            terminal = true;
+            const error = event.error instanceof Error ? event.error : new Error("WebSocket transport failed");
+            socket.close();
+            if (connected)
+                handlers.onError(error);
+            else
+                reject(error);
+        }, { once: true });
+    });
+}
+function binaryMessage(data) {
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (ArrayBuffer.isView(data))
+        return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    return undefined;
+}
+class WebSocketByteTransport {
+    #socket;
+    #openState;
+    #maxPendingBytes;
+    #markLocalClose;
+    #closed = false;
+    #pendingBytes = 0;
+    #sendTail = Promise.resolve();
+    constructor(socket, openState, maxPendingBytes, markLocalClose) {
+        this.#socket = socket;
+        this.#openState = openState;
+        this.#maxPendingBytes = maxPendingBytes;
+        this.#markLocalClose = markLocalClose;
+    }
+    send(chunk) {
+        if (!(chunk instanceof Uint8Array)) {
+            return Promise.reject(new TypeError("WebSocket transport chunks must be Uint8Array"));
+        }
+        if (this.#closed || this.#socket.readyState !== this.#openState) {
+            return Promise.reject(new Error("WebSocket transport is closed"));
+        }
+        if (this.#pendingBytes + chunk.byteLength > this.#maxPendingBytes) {
+            return Promise.reject(new Error("WebSocket transport exceeded its pending byte limit"));
+        }
+        const bytes = chunk.slice();
+        this.#pendingBytes += bytes.byteLength;
+        const send = this.#sendTail.then(() => {
+            if (this.#closed || this.#socket.readyState !== this.#openState) {
+                throw new Error("WebSocket transport is closed");
+            }
+            this.#socket.send(bytes);
+            if (this.#socket.bufferedAmount > this.#maxPendingBytes) {
+                this.close();
+                throw new Error("WebSocket transport exceeded its buffered byte limit");
+            }
+        });
+        const tracked = send.finally(() => {
+            this.#pendingBytes -= bytes.byteLength;
+        });
+        this.#sendTail = tracked.catch(() => { });
+        return tracked;
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#markLocalClose();
+        this.#socket.close(1000, "Client closed");
+    }
+}

package/distribution-components.json

@@ -0,0 +1,16 @@
+[
+  {
+    "name": "@diffexai/diffex-client",
+    "version": "0.2.0",
+    "sourceCommit": "e3f96b95ebc7fdad96220e315ec144f74383de22",
+    "license": "Apache-2.0",
+    "portions": "Diffex contributions; Pi-derived portions retain MIT terms in LICENSE",
+    "notice": "LICENSE",
+    "noticeSha256": "35a4476d361a333186451f77937c9a070027ab3a83e3661fad4ccca8ac2b0a99"
+  },
+  {
+    "name": "@diffexai/diffex-protocol",
+    "version": "^0.2.0",
+    "distribution": "resolved separately by package manager; not bundled in this npm tarball"
+  }
+]

package/distribution-files.json

@@ -0,0 +1,102 @@
+{
+  "sourceCommit": "e3f96b95ebc7fdad96220e315ec144f74383de22",
+  "algorithm": "sha256",
+  "files": [
+    {
+      "path": "dist/client.d.ts",
+      "sha256": "d129da89227c4c2ec85566693f5596535c589348593974fa53742507a295a5c3"
+    },
+    {
+      "path": "dist/client.js",
+      "sha256": "b4ea00041469ce9b0959d8fa0560769bdd3751669bbf12bea5970eef0eb3c704"
+    },
+    {
+      "path": "dist/cloud.d.ts",
+      "sha256": "4f3b497020a08d5f5fa967d916a174c5357ae0351bc33f973ff6dbfa65f97484"
+    },
+    {
+      "path": "dist/cloud.js",
+      "sha256": "0b69877596d402dbba21482ecf861a8139832fa7b92ceba7585f24466735302b"
+    },
+    {
+      "path": "dist/connection.d.ts",
+      "sha256": "4575d98b9aa96d7d597ba36f2058de92cfa40abf4cf31918def4d9af5b87d382"
+    },
+    {
+      "path": "dist/connection.js",
+      "sha256": "a473c9463cd050b467dcdae2f69b994488b09fbfb2724facd6888a4fc996250c"
+    },
+    {
+      "path": "dist/errors.d.ts",
+      "sha256": "3f51d09d4f7182f16e644171d7b677e53fc5c4129175a202090fd0c388e6f81e"
+    },
+    {
+      "path": "dist/errors.js",
+      "sha256": "b95eb6cd279adf2e5d004096f688fd95f7871ac518a02dd97d6d72095c581c63"
+    },
+    {
+      "path": "dist/index.d.ts",
+      "sha256": "ce080e9967e6e9762b55036459255093f76da8a5c36929e8d8ff3ff7b7b7638f"
+    },
+    {
+      "path": "dist/index.js",
+      "sha256": "18dfab689d3f9f8837f3e6aaa2c7071f8916535e8879975ef1510193ac65fda8"
+    },
+    {
+      "path": "dist/promise.d.ts",
+      "sha256": "fda1d50aeb352e40207ec7d868008d66145300111f567d6b1a4bbfed2e514388"
+    },
+    {
+      "path": "dist/promise.js",
+      "sha256": "5f419928b687ac9e50174e8b88d009815e4689e1ee447b7e84de254731d2fe70"
+    },
+    {
+      "path": "dist/session-handle.d.ts",
+      "sha256": "c2739c9cab31c8d09be6d18792623ca0d57528bddee867de407d3a35646da4e4"
+    },
+    {
+      "path": "dist/session-handle.js",
+      "sha256": "906eedd65ea5235af8a5e4da5ecfc4cd7c5765e6c44c1d752bc1fe583f6ad6c7"
+    },
+    {
+      "path": "dist/state.d.ts",
+      "sha256": "e953045245a6679e909a53333271ef5cc30f84c84b50d568de3fa973cb54e328"
+    },
+    {
+      "path": "dist/state.js",
+      "sha256": "ad96a633dcbc517cdb1332b46fcfcef745523d4a1c5ccb945fff8cdab5316239"
+    },
+    {
+      "path": "dist/transport.d.ts",
+      "sha256": "89390f23871babf64e807a7d2b751e9da413a6a5bafeb48572fcc41dc080199b"
+    },
+    {
+      "path": "dist/transport.js",
+      "sha256": "8e609bb71c20b858c77f0e9f90bb1319db8477b13f9f965f1a1e18524bf50881"
+    },
+    {
+      "path": "dist/types.d.ts",
+      "sha256": "6a55a5a3d36ec1941afe3413488bce80612980eb246fde95d5e50ec11dcfa511"
+    },
+    {
+      "path": "dist/types.js",
+      "sha256": "8e609bb71c20b858c77f0e9f90bb1319db8477b13f9f965f1a1e18524bf50881"
+    },
+    {
+      "path": "dist/unix.d.ts",
+      "sha256": "721f19d9f726c27f62e23b47fee331072f45f7e1e7db2f234f47ec6c86c5c3ea"
+    },
+    {
+      "path": "dist/unix.js",
+      "sha256": "fdd40193e2d1d29267b47efa2506c0162807476402a7a3722190851002950bc3"
+    },
+    {
+      "path": "dist/websocket.d.ts",
+      "sha256": "6d0e19b1ecd9229f1e8160670707178574c50c112d13510d072d9e258792b706"
+    },
+    {
+      "path": "dist/websocket.js",
+      "sha256": "a9a3b3a488122ec0bdb01c8e6ed991d94cae6306cbb074d7fb2dfe21bcb46faa"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+	"name": "@diffexai/diffex-client",
+	"version": "0.2.0",
+	"description": "Transport-neutral client for remote Diffex sessions over framed CBOR bytes",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./unix": {
+			"types": "./dist/unix.d.ts",
+			"import": "./dist/unix.js"
+		},
+		"./websocket": {
+			"types": "./dist/websocket.d.ts",
+			"import": "./dist/websocket.js"
+		},
+		"./cloud": {
+			"types": "./dist/cloud.d.ts",
+			"import": "./dist/cloud.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"sideEffects": false,
+	"files": [
+		"dist",
+		"README.md",
+		"CHANGELOG.md",
+		"LICENSE",
+		"NOTICE",
+		"THIRD-PARTY-NOTICES.txt",
+		"distribution-components.json",
+		"distribution-files.json"
+	],
+	"scripts": {
+		"clean": "shx rm -rf dist",
+		"build": "tsgo -p tsconfig.build.json",
+		"test": "vitest --run",
+		"typecheck": "tsgo -p tsconfig.test.json",
+		"prepublishOnly": "npm run clean && npm run build",
+		"prepack": "node ../../scripts/prepare-distribution.mjs packages/client"
+	},
+	"keywords": [
+		"diffex",
+		"client",
+		"protocol",
+		"cbor",
+		"binary"
+	],
+	"author": "DiffexAI",
+	"license": "Apache-2.0",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/diffexai/diffex.git",
+		"directory": "packages/client"
+	},
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"dependencies": {
+		"@diffexai/diffex-protocol": "^0.2.0"
+	},
+	"devDependencies": {
+		"shx": "0.4.0",
+		"vitest": "4.1.9"
+	}
+}