@fastls/fastls 0.0.0-stage → 0.10.1

package/dist/websocket.js

@@ -0,0 +1,249 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocket = exports.WebSocketClosed = void 0;
+exports.wsBudget = wsBudget;
+const promises_1 = require("node:timers/promises");
+const errors_js_1 = require("./errors.js");
+const headers_js_1 = require("./headers.js");
+const scheduler_js_1 = require("./scheduler.js");
+class WebSocketClosed extends errors_js_1.FastlsError {
+    code;
+    reason;
+    name = "WebSocketClosed";
+    constructor(code = 1006, reason = "") {
+        super(`WebSocket closed (${code})`);
+        this.code = code;
+        this.reason = reason;
+    }
+}
+exports.WebSocketClosed = WebSocketClosed;
+function wsBudget(value, name, maximum = 86400000) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > maximum)
+        throw new RangeError(`${name} must be 1..${maximum} milliseconds`);
+    return value;
+}
+function closePayload(code, reason) {
+    if (!Number.isInteger(code) || !([1000, 1001, 1002, 1003, 1007, 1008, 1009, 1010, 1011, 1012, 1013, 1014].includes(code) || (code >= 3000 && code <= 4999)))
+        throw new RangeError("invalid WebSocket close code");
+    if (typeof reason !== "string" || /[\uD800-\uDFFF]/u.test(reason))
+        throw new TypeError("close reason must be well-formed Unicode");
+    const text = Buffer.from(reason);
+    if (text.length > 123)
+        throw new RangeError("close reason exceeds 123 UTF-8 bytes");
+    const out = Buffer.allocUnsafe(text.length + 2);
+    out.writeUInt16BE(code);
+    text.copy(out, 2);
+    return out;
+}
+const scratch = Buffer.allocUnsafe(65536);
+class WebSocket {
+    native;
+    handle;
+    release;
+    maxMessageBytes;
+    closeTimeoutMs;
+    notifier;
+    external;
+    controller = new AbortController();
+    closed = false;
+    reading = false;
+    writing = false;
+    failure;
+    last;
+    closing;
+    externalAbort = () => this.abort(new errors_js_1.AbortError(undefined, { cause: this.external?.reason }));
+    headers = new headers_js_1.Headers();
+    subprotocol = "";
+    constructor(native, handle, release, maxMessageBytes, closeTimeoutMs, notifier, external) {
+        this.native = native;
+        this.handle = handle;
+        this.release = release;
+        this.maxMessageBytes = maxMessageBytes;
+        this.closeTimeoutMs = closeTimeoutMs;
+        this.notifier = notifier;
+        this.external = external;
+        external?.addEventListener("abort", this.externalAbort, { once: true });
+        if (external?.aborted)
+            this.externalAbort();
+    }
+    ensure() { if (this.closed)
+        throw this.failure ?? new errors_js_1.FastlsError("WebSocket is closed"); }
+    get info() { if (this.closed && this.last)
+        return this.last; this.ensure(); const info = this.last = this.native.call("info", this.handle); if (info.status)
+        this.headers = new headers_js_1.Headers(info.header_values); return info; }
+    get closeCode() { return (this.closed ? this.last : this.info)?.websocket?.close_code ?? 1006; }
+    get closeReason() { return (this.closed ? this.last : this.info)?.websocket?.close_reason ?? ""; }
+    check(info) {
+        if (info.state === "error")
+            throw (0, errors_js_1.responseError)(info);
+        if (info.state === "eof")
+            throw new WebSocketClosed(info.websocket?.close_code, info.websocket?.close_reason);
+    }
+    wait(probe, signal = this.controller.signal) {
+        return this.notifier ? this.notifier.probe(this.handle, probe, signal) : scheduler_js_1.scheduler.wait(probe, signal);
+    }
+    /** @internal */
+    async opened() {
+        try {
+            const info = await this.wait(() => { const i = this.info; if (i.status === 101 && (i.state === "headers" || i.state === "eof"))
+                return i; this.check(i); return i.state === "pending" ? undefined : i; });
+            this.headers = new headers_js_1.Headers(info.header_values, info.headers);
+            this.subprotocol = info.websocket?.subprotocol ?? "";
+            return this;
+        }
+        catch (error) {
+            this.abort(error instanceof Error ? error : undefined);
+            throw error;
+        }
+    }
+    async write(opcode, data, signal = this.controller.signal) {
+        this.ensure();
+        if (this.writing)
+            throw new errors_js_1.FastlsError("another WebSocket send is active");
+        this.writing = true;
+        try {
+            let accepted = false;
+            await this.wait(() => {
+                const info = this.info;
+                this.check(info);
+                if (accepted)
+                    return !info.websocket.write_pending ? true : undefined;
+                const code = this.native.wsSend(this.handle, opcode, data);
+                if (code < 0) {
+                    this.check(this.info);
+                    throw new errors_js_1.FastlsError("invalid WebSocket send or connection is closing");
+                }
+                if (code !== 0 && code !== 1)
+                    throw new errors_js_1.FastlsError("invalid WebSocket send status");
+                if (code === 0) {
+                    accepted = true;
+                    const next = this.info;
+                    this.check(next);
+                    if (!next.websocket.write_pending)
+                        return true;
+                }
+                return undefined;
+            }, signal);
+        }
+        catch (error) {
+            this.abort(error instanceof Error ? error : undefined);
+            throw error;
+        }
+        finally {
+            this.writing = false;
+        }
+    }
+    send(message) {
+        if (typeof message !== "string" && !(message instanceof Uint8Array))
+            return Promise.reject(new TypeError("WebSocket messages must be strings or bytes"));
+        if (typeof message === "string" && /[\uD800-\uDFFF]/u.test(message))
+            return Promise.reject(new TypeError("WebSocket text must be well-formed Unicode"));
+        if ((typeof message === "string" ? Buffer.byteLength(message) : message.byteLength) > this.maxMessageBytes)
+            return Promise.reject(new RangeError("WebSocket message exceeds maxMessageBytes"));
+        // Copy before any await: accepted data must not observe caller mutation.
+        return this.write(typeof message === "string" ? 1 : 2, Buffer.from(message));
+    }
+    control(opcode, data) {
+        if (!(data instanceof Uint8Array))
+            return Promise.reject(new TypeError("control payload must be bytes"));
+        if (data.byteLength > 125)
+            return Promise.reject(new RangeError("control payload exceeds 125 bytes"));
+        return this.write(opcode, Buffer.from(data));
+    }
+    ping(data = Buffer.alloc(0)) { return this.control(9, data); }
+    pong(data = Buffer.alloc(0)) { return this.control(10, data); }
+    async recv() {
+        this.ensure();
+        if (this.reading)
+            throw new errors_js_1.FastlsError("another WebSocket recv is active");
+        this.reading = true;
+        try {
+            let content = Buffer.alloc(0), length = 0, kind, turns = 0;
+            while (true) {
+                const block = await this.wait(() => {
+                    this.ensure();
+                    const r = this.native.wsRead(this.handle, scratch);
+                    if (r.code === 1)
+                        return undefined;
+                    if (r.code !== 0) {
+                        this.check(this.info);
+                        throw new WebSocketClosed();
+                    }
+                    if (![1, 2].includes(r.opcode))
+                        throw new errors_js_1.FastlsError("invalid WebSocket message opcode");
+                    return { ...r, data: Buffer.from(scratch.subarray(0, r.length)) };
+                });
+                kind ??= block.opcode;
+                if (block.opcode !== kind)
+                    throw new errors_js_1.FastlsError("WebSocket message opcode changed mid-message");
+                const size = length + block.length;
+                if (size > this.maxMessageBytes)
+                    throw new errors_js_1.FastlsError("WebSocket message exceeds maxMessageBytes");
+                if (size > content.length) {
+                    const grown = Buffer.allocUnsafe(Math.min(this.maxMessageBytes, Math.max(size, content.length * 2)));
+                    content.copy(grown, 0, 0, length);
+                    content = grown;
+                }
+                block.data.copy(content, length);
+                length = size;
+                if (block.end) {
+                    const bytes = content.subarray(0, length);
+                    return kind === 1 ? new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes) : Buffer.from(bytes);
+                }
+                if (++turns % 16 === 0)
+                    await (0, promises_1.setImmediate)();
+            }
+        }
+        catch (error) {
+            this.abort(error instanceof Error ? error : undefined);
+            throw error;
+        }
+        finally {
+            this.reading = false;
+        }
+    }
+    closeAsync(code = 1000, reason = "") {
+        const data = closePayload(code, reason);
+        if (this.closing)
+            return this.closing;
+        if (this.closed)
+            return Promise.resolve();
+        this.closing = (async () => {
+            const budget = new AbortController(), timer = setTimeout(() => budget.abort(new errors_js_1.FastlsError("WebSocket close timed out")), this.closeTimeoutMs);
+            const signal = AbortSignal.any([this.controller.signal, budget.signal]);
+            try {
+                if (this.info.state === "headers") {
+                    // A close may interrupt a pending reader/writer after its total budget.
+                    if (!this.writing)
+                        await this.write(8, data, signal);
+                    await this.wait(() => { const info = this.info; return info.state !== "headers" ? true : undefined; }, signal);
+                }
+            }
+            catch { /* Closing always releases the handle, including a stalled peer. */ }
+            finally {
+                clearTimeout(timer);
+                this.abort();
+            }
+        })();
+        return this.closing;
+    }
+    abort(error) {
+        if (this.closed)
+            return;
+        try {
+            this.last = this.native.call("info", this.handle);
+        }
+        catch { /* Retain last metadata on teardown. */ }
+        this.closed = true;
+        this.failure = error;
+        this.external?.removeEventListener("abort", this.externalAbort);
+        this.controller.abort(error ?? new errors_js_1.FastlsError("WebSocket is closed"));
+        try {
+            this.native.call("close", this.handle);
+        }
+        finally {
+            this.release();
+        }
+    }
+}
+exports.WebSocket = WebSocket;

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@fastls/fastls",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.10.1",
+  "description": "Node.js bindings for the Fastls C ABI",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "koffi": "3.3.3",
+    "lossless-json": "4.3.3",
+    "tough-cookie": "6.0.0"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FastTLS/fastls-ffi.git",
+    "directory": "node"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "optionalDependencies": {
+    "@fastls/fastls-win32-x64": "0.10.1",
+    "@fastls/fastls-linux-x64-glibc": "0.10.1",
+    "@fastls/fastls-linux-arm64-glibc": "0.10.1",
+    "@fastls/fastls-darwin-x64": "0.10.1",
+    "@fastls/fastls-darwin-arm64": "0.10.1"
+  }
+}