@rybosome/tspice 0.0.3 → 0.0.8

package/dist/worker/transport/createWorkerTransport.js

@@ -0,0 +1,398 @@
+import { deserializeError, tspiceRpcDisposeType, tspiceRpcRequestType, tspiceRpcResponseType, } from "../../transport/rpc/protocol.js";
+import { decodeRpcValue, encodeRpcValue } from "../../transport/rpc/valueCodec.js";
+import { canQueueMacrotask, queueMacrotask } from "../../transport/rpc/taskScheduling.js";
+function createAbortError() {
+    // DOMException is the most accurate in browser contexts, but isn't guaranteed
+    // to exist in all runtimes (e.g. some test environments).
+    try {
+        return new DOMException("Aborted", "AbortError");
+    }
+    catch {
+        const err = new Error("Aborted");
+        err.name = "AbortError";
+        return err;
+    }
+}
+function createNoMacrotaskSchedulerError() {
+    return new Error("Worker transport cannot schedule macrotask settlement (MessageChannel/setTimeout missing). " +
+        "Refusing to settle responses synchronously because it would break dispose ordering guarantees.");
+}
+/**
+ * Create a `SpiceTransport` backed by a `Worker`.
+ *
+ * ## Macrotask settlement ordering
+ *
+ * Worker responses are resolved/rejected on a later macrotask (via
+ * `queueMacrotask(...)`) so that calling `dispose()` in the same tick
+ * deterministically wins.
+ *
+ * Implications:
+ * - Requests never resolve/reject on the same tick a response is received.
+ * - A response received in the current tick may be ignored if `dispose()` is
+ *   called before the next tick.
+ * - If no macrotask scheduler exists in the runtime (no `MessageChannel` and no `setTimeout`),
+ *   the transport fails closed by rejecting requests rather than settling synchronously.
+ */
+export function createWorkerTransport(opts) {
+    let worker;
+    // Retain a reference for best-effort dispose signaling even after terminal
+    // teardown clears `worker`.
+    let workerForDisposeSignal;
+    let disposed = false;
+    let terminalError;
+    // If we ever discover we can't schedule a macrotask, we permanently fail
+    // closed (reject) to avoid violating settlement ordering guarantees.
+    let canScheduleMacrotask;
+    const terminateOnDispose = opts.terminateOnDispose ?? (typeof opts.worker === "function" ? true : false);
+    const signalDispose = opts.signalDispose ?? terminateOnDispose;
+    let didSignalDispose = false;
+    const signalDisposeOnce = () => {
+        if (didSignalDispose)
+            return;
+        didSignalDispose = true;
+        if (!signalDispose)
+            return;
+        const w = worker ?? workerForDisposeSignal;
+        if (!w)
+            return;
+        try {
+            const msg = { type: tspiceRpcDisposeType };
+            w.postMessage(msg);
+        }
+        catch {
+            // ignore
+        }
+    };
+    const pendingById = new Map();
+    // Requests with a received response that are awaiting next-macrotask
+    // settlement. Keeping these separate from `pendingById` lets us remove a
+    // request from the timeout/abort race immediately upon response receipt,
+    // while still allowing `dispose()` (and worker errors) to deterministically
+    // win before settlement.
+    const queuedSettlementById = new Map();
+    // Whether a single macrotask has been queued to settle all currently-queued responses.
+    let settlementQueued = false;
+    let nextId = 1;
+    const formatRequestContext = (op, id) => id === undefined ? `(op=${op})` : `(op=${op}, id=${id})`;
+    const ensureCanScheduleMacrotask = () => {
+        if (canScheduleMacrotask === undefined) {
+            // Fail fast before posting any messages if the runtime lacks a macrotask
+            // scheduler.
+            canScheduleMacrotask = canQueueMacrotask();
+        }
+        if (canScheduleMacrotask === false) {
+            throw createNoMacrotaskSchedulerError();
+        }
+    };
+    const rejectAllPending = (getReason) => {
+        for (const [id, pending] of pendingById) {
+            pendingById.delete(id);
+            pending.rejectAndCleanup(getReason(pending, id));
+        }
+        // Queued settlements already ran `cleanup()` when their response was received.
+        for (const [id, settlement] of Array.from(queuedSettlementById)) {
+            queuedSettlementById.delete(id);
+            const pending = settlement.pending;
+            pending.reject(getReason(pending, id));
+            // Explicitly drop response payload references to help GC.
+            settlement.value = undefined;
+            settlement.error = undefined;
+        }
+    };
+    const terminalTeardown = (err, opts) => {
+        if (terminalError)
+            return;
+        terminalError = err;
+        // Terminal teardown transitions the transport into a disposed state even if
+        // the caller never explicitly invoked `dispose()`.
+        disposed = true;
+        // Prevent any future settlement work from being queued.
+        settlementQueued = false;
+        rejectAllPending(opts?.getReason ?? (() => err));
+        // Prefer the latest live worker for any best-effort dispose signaling.
+        if (worker)
+            workerForDisposeSignal = worker;
+        const w = worker;
+        worker = undefined;
+        if (!w)
+            return;
+        w.removeEventListener("message", onMessage);
+        w.removeEventListener("error", onError);
+        w.removeEventListener("messageerror", onMessageError);
+        if (!terminateOnDispose)
+            return;
+        if (opts?.deferTerminate) {
+            const ok = queueMacrotask(() => {
+                try {
+                    w.terminate();
+                }
+                catch {
+                    // ignore
+                }
+            }, { allowSyncFallback: false });
+            // No scheduler: explicitly fall back to a synchronous terminate so we
+            // don't leave an owned worker running.
+            if (!ok) {
+                try {
+                    w.terminate();
+                }
+                catch {
+                    // ignore
+                }
+            }
+            return;
+        }
+        try {
+            w.terminate();
+        }
+        catch {
+            // ignore
+        }
+    };
+    const hardFailNoMacrotaskScheduler = (err) => {
+        // Permanently fail closed.
+        canScheduleMacrotask = false;
+        if (terminalError)
+            return;
+        // Best-effort: if configured, attempt to notify the worker to dispose any
+        // server-side resources *before* we remove listeners/terminate.
+        signalDisposeOnce();
+        terminalTeardown(err);
+    };
+    const flushQueuedSettlements = () => {
+        settlementQueued = false;
+        for (const [id, settlement] of Array.from(queuedSettlementById)) {
+            queuedSettlementById.delete(id);
+            const pending = settlement.pending;
+            const op = pending.op;
+            const kind = settlement.kind;
+            // Drop references to response payloads as soon as possible.
+            let value = settlement.value;
+            let error = settlement.error;
+            settlement.value = undefined;
+            settlement.error = undefined;
+            if (disposed) {
+                pending.reject(new Error(`Worker transport disposed ${formatRequestContext(op, id)}`));
+                continue;
+            }
+            if (kind === "resolve") {
+                pending.resolve(value);
+                value = undefined;
+                continue;
+            }
+            pending.reject(error);
+            error = undefined;
+        }
+    };
+    const scheduleSettlementMacrotask = () => {
+        if (settlementQueued)
+            return;
+        settlementQueued = true;
+        const ok = queueMacrotask(flushQueuedSettlements, { allowSyncFallback: false });
+        if (ok) {
+            canScheduleMacrotask = true;
+            return;
+        }
+        // No macrotask scheduler available. Hard-fail and tear down rather than
+        // settling synchronously and violating ordering guarantees.
+        hardFailNoMacrotaskScheduler(createNoMacrotaskSchedulerError());
+    };
+    const onMessage = (ev) => {
+        const msg = ev?.data;
+        if (!msg || msg.type !== tspiceRpcResponseType || typeof msg.id !== "number")
+            return;
+        const id = msg.id;
+        const pending = pendingById.get(id);
+        if (!pending)
+            return;
+        // Remove immediately so a queued timeout handler can't win after we've
+        // already received a legitimate response.
+        pendingById.delete(id);
+        // Clean up request-specific resources immediately (abort listeners, timers),
+        // but defer settling to a macrotask so `dispose()` can deterministically win.
+        pending.cleanup();
+        // If we already know we can't schedule macrotasks, reject immediately.
+        if (canScheduleMacrotask === false) {
+            pending.reject(createNoMacrotaskSchedulerError());
+            return;
+        }
+        const op = pending.op;
+        // Extract response fields up-front so the deferred macrotask doesn't close
+        // over the full `msg` payload.
+        let kind;
+        let value = undefined;
+        let error = undefined;
+        if (msg.ok === true) {
+            if (!("value" in msg)) {
+                kind = "reject";
+                error = new Error(`Malformed worker response: ok=true but missing value ${formatRequestContext(op, id)}`);
+            }
+            else {
+                kind = "resolve";
+                value = decodeRpcValue(msg.value);
+            }
+        }
+        else if (msg.ok === false) {
+            if (!("error" in msg)) {
+                kind = "reject";
+                error = new Error(`Malformed worker response: ok=false but missing error ${formatRequestContext(op, id)}`);
+            }
+            else {
+                kind = "reject";
+                error = deserializeError(msg.error);
+            }
+        }
+        else {
+            kind = "reject";
+            error = new Error(`Malformed worker response: missing ok flag ${formatRequestContext(op, id)}`);
+        }
+        queuedSettlementById.set(id, { pending, kind, value, error });
+        scheduleSettlementMacrotask();
+    };
+    const onError = (ev) => {
+        let message;
+        try {
+            message = ev?.message;
+        }
+        catch {
+            // ignore
+        }
+        const safeMessage = typeof message === "string" && message.length > 0 ? message : "Worker error";
+        terminalTeardown(new Error(safeMessage), {
+            getReason: (pending, id) => new Error(`${safeMessage} ${formatRequestContext(pending.op, id)}`),
+        });
+    };
+    const onMessageError = (_ev) => {
+        const err = new Error("Worker message deserialization failed");
+        terminalTeardown(err, {
+            getReason: (pending, id) => new Error(`Worker message deserialization failed ${formatRequestContext(pending.op, id)}`),
+        });
+    };
+    const ensureWorker = () => {
+        ensureCanScheduleMacrotask();
+        if (!worker) {
+            // Lazily construct/attach so transports can be created in environments
+            // that don't immediately support `Worker`.
+            try {
+                worker = typeof opts.worker === "function" ? opts.worker() : opts.worker;
+            }
+            catch (err) {
+                const out = new Error("Failed to create Worker");
+                out.cause = err;
+                throw out;
+            }
+            workerForDisposeSignal = worker;
+            worker.addEventListener("message", onMessage);
+            worker.addEventListener("error", onError);
+            worker.addEventListener("messageerror", onMessageError);
+        }
+        return worker;
+    };
+    const dispose = () => {
+        // Idempotent. Even if we're already in a terminal state, callers should be
+        // able to invoke `dispose()` and still get a best-effort dispose signal.
+        if (disposed) {
+            signalDisposeOnce();
+            return;
+        }
+        disposed = true;
+        // Best-effort: tell the worker it should dispose any server-side resources.
+        //
+        // This is intentionally opt-in for shared workers; `tspice:dispose` is a
+        // global cleanup signal and may affect other clients.
+        signalDisposeOnce();
+        if (terminalError)
+            return;
+        terminalTeardown(new Error("Worker transport disposed"), {
+            getReason: (pending, id) => new Error(`Worker transport disposed ${formatRequestContext(pending.op, id)}`),
+            deferTerminate: true,
+        });
+    };
+    const request = async (op, args, requestOpts) => {
+        if (terminalError)
+            throw terminalError;
+        if (disposed)
+            throw new Error(`Worker transport disposed ${formatRequestContext(op)}`);
+        if (canScheduleMacrotask === false)
+            throw createNoMacrotaskSchedulerError();
+        const id = nextId++;
+        const w = ensureWorker();
+        const timeoutMs = requestOpts?.timeoutMs ?? opts.timeoutMs;
+        const signal = requestOpts?.signal;
+        if (timeoutMs !== undefined && timeoutMs > 0) {
+            const hasTimers = typeof setTimeout === "function" && typeof clearTimeout === "function";
+            if (!hasTimers) {
+                throw new Error(`Worker request timeoutMs=${timeoutMs} requires timers (setTimeout/clearTimeout) ${formatRequestContext(op, id)}`);
+            }
+        }
+        return await new Promise((resolve, reject) => {
+            let requestTimeout;
+            // Cleanup is intentionally idempotent. It may be called from multiple
+            // paths (timeout, abort, response receipt, or dispose()) depending on
+            // ordering.
+            let didCleanup = false;
+            let onAbort;
+            const cleanup = () => {
+                if (didCleanup)
+                    return;
+                didCleanup = true;
+                if (requestTimeout !== undefined) {
+                    clearTimeout(requestTimeout);
+                    requestTimeout = undefined;
+                }
+                if (signal && onAbort)
+                    signal.removeEventListener("abort", onAbort);
+            };
+            const rejectAndCleanup = (reason) => {
+                cleanup();
+                reject(reason);
+            };
+            const pending = {
+                op,
+                resolve,
+                reject,
+                cleanup,
+                rejectAndCleanup,
+            };
+            pendingById.set(id, pending);
+            onAbort = () => {
+                if (pendingById.get(id) !== pending)
+                    return;
+                pendingById.delete(id);
+                pending.rejectAndCleanup(createAbortError());
+            };
+            if (signal) {
+                if (signal.aborted) {
+                    pendingById.delete(id);
+                    pending.rejectAndCleanup(createAbortError());
+                    return;
+                }
+                signal.addEventListener("abort", onAbort);
+            }
+            if (timeoutMs !== undefined && timeoutMs > 0) {
+                requestTimeout = setTimeout(() => {
+                    if (pendingById.get(id) !== pending)
+                        return;
+                    pendingById.delete(id);
+                    pending.rejectAndCleanup(new Error(`Worker request timed out after ${timeoutMs}ms ${formatRequestContext(op, id)}`));
+                }, timeoutMs);
+            }
+            const msg = { type: tspiceRpcRequestType, id, op, args };
+            try {
+                w.postMessage({ ...msg, args: args.map(encodeRpcValue) });
+            }
+            catch (err) {
+                if (pendingById.get(id) === pending)
+                    pendingById.delete(id);
+                const out = new Error(`Worker postMessage failed ${formatRequestContext(op, id)}`);
+                out.cause = err;
+                pending.rejectAndCleanup(out);
+            }
+        });
+    };
+    return {
+        request,
+        dispose,
+    };
+}
+//# sourceMappingURL=createWorkerTransport.js.map

package/dist/worker/transport/exposeTransportToWorker.d.ts

@@ -0,0 +1,51 @@
+import type { SpiceTransport } from "../../transport/types.js";
+type WorkerGlobalScopeLike = {
+    addEventListener(type: "message", listener: (ev: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: "message", listener: (ev: {
+        data: unknown;
+    }) => void): void;
+    postMessage(msg: unknown): void;
+    close?: () => void;
+};
+/** Expose a {@link SpiceTransport} inside a Worker, handling RPC request/response messaging. */
+export declare function exposeTransportToWorker(opts: {
+    transport: SpiceTransport;
+    /**
+     * Override the Worker global scope for testing.
+     *
+     * Defaults to `globalThis`.
+     */
+    self?: WorkerGlobalScopeLike;
+    /** Optional cleanup hook called when a dispose message is received. */
+    onDispose?: () => void | Promise<void>;
+    /** Whether to call `self.close()` after disposing. Defaults to `true`. */
+    closeOnDispose?: boolean;
+    /**
+     * Maximum number of in-flight `transport.request()` calls allowed at once.
+     * Additional requests are queued (FIFO) until prior requests settle.
+     *
+     * Defaults to `Infinity`.
+     */
+    maxConcurrentRequests?: number;
+    /**
+     * Maximum number of queued requests allowed when `maxConcurrentRequests` is
+     * finite.
+     *
+     * When `maxConcurrentRequests` is finite, additional requests are queued
+     * (FIFO) until prior requests settle.
+     *
+     * When the queue is full, new incoming requests are immediately rejected
+     * with an RPC error response.
+     *
+     * Defaults:
+     * - `Infinity` when `maxConcurrentRequests` is `Infinity` (preserves existing behavior)
+     * - `1000` when `maxConcurrentRequests` is finite
+     */
+    maxQueuedRequests?: number;
+}): {
+    dispose: () => void;
+};
+export {};
+//# sourceMappingURL=exposeTransportToWorker.d.ts.map

package/dist/worker/transport/exposeTransportToWorker.js

@@ -0,0 +1,196 @@
+import { serializeError, tspiceRpcDisposeType, tspiceRpcRequestType, tspiceRpcResponseType, } from "../../transport/rpc/protocol.js";
+import { decodeRpcValue, encodeRpcValue } from "../../transport/rpc/valueCodec.js";
+import { queueMacrotask } from "../../transport/rpc/taskScheduling.js";
+/** Expose a {@link SpiceTransport} inside a Worker, handling RPC request/response messaging. */
+export function exposeTransportToWorker(opts) {
+    const self = opts.self ?? globalThis;
+    let disposed = false;
+    const maxConcurrentRequests = opts.maxConcurrentRequests ?? Infinity;
+    if (maxConcurrentRequests !== Infinity) {
+        // Guard against deadlocking the queue when `maxConcurrentRequests` is 0/NaN/etc.
+        if (!Number.isFinite(maxConcurrentRequests) || maxConcurrentRequests < 1) {
+            throw new Error("exposeTransportToWorker(): maxConcurrentRequests must be >= 1");
+        }
+        // Prefer integers for deterministic queue semantics.
+        if (!Number.isInteger(maxConcurrentRequests)) {
+            throw new Error("exposeTransportToWorker(): maxConcurrentRequests must be an integer");
+        }
+    }
+    let inFlight = 0;
+    const defaultMaxQueuedRequests = maxConcurrentRequests === Infinity ? Infinity : 1000;
+    const maxQueuedRequests = opts.maxQueuedRequests ?? defaultMaxQueuedRequests;
+    if (maxQueuedRequests !== Infinity) {
+        if (!Number.isFinite(maxQueuedRequests) || maxQueuedRequests < 0) {
+            throw new Error("exposeTransportToWorker(): maxQueuedRequests must be >= 0");
+        }
+        if (!Number.isInteger(maxQueuedRequests)) {
+            throw new Error("exposeTransportToWorker(): maxQueuedRequests must be an integer");
+        }
+    }
+    // FIFO queue with a moving head index to avoid O(n) `shift()`.
+    const queued = [];
+    let queuedHead = 0;
+    const queuedSize = () => queued.length - queuedHead;
+    const FAIL_QUEUED_REQUESTS_CHUNK_SIZE = 100;
+    const failQueuedRequests = async (reqs, err) => {
+        // Best-effort (avoid throwing during disposal).
+        try {
+            for (let i = 0; i < reqs.length; i += FAIL_QUEUED_REQUESTS_CHUNK_SIZE) {
+                const end = Math.min(i + FAIL_QUEUED_REQUESTS_CHUNK_SIZE, reqs.length);
+                for (let j = i; j < end; j++) {
+                    const q = reqs[j];
+                    const res = {
+                        type: tspiceRpcResponseType,
+                        id: q.id,
+                        ok: false,
+                        // Serialize per response so each postMessage gets a fresh object.
+                        error: serializeError(err),
+                    };
+                    self.postMessage(res);
+                }
+                // Yield between chunks so disposing a huge queue doesn't block the
+                // worker for an unbounded amount of time.
+                if (end < reqs.length) {
+                    await new Promise((resolve) => {
+                        queueMacrotask(resolve, { allowSyncFallback: true });
+                    });
+                }
+            }
+        }
+        catch {
+            // ignore
+        }
+    };
+    const clearQueue = () => {
+        queued.length = 0;
+        queuedHead = 0;
+    };
+    const maybeCompactQueue = () => {
+        // Periodically compact to avoid unbounded memory growth from a large queue.
+        if (queuedHead === 0)
+            return;
+        if (queuedHead < 100)
+            return;
+        queued.splice(0, queuedHead);
+        queuedHead = 0;
+    };
+    const drain = () => {
+        if (disposed)
+            return;
+        while (inFlight < maxConcurrentRequests && queuedHead < queued.length) {
+            const req = queued[queuedHead];
+            queuedHead += 1;
+            runRequest(req);
+        }
+        maybeCompactQueue();
+    };
+    const runRequest = (req) => {
+        inFlight += 1;
+        void (async () => {
+            try {
+                const value = await opts.transport.request(req.op, req.args.map(decodeRpcValue));
+                if (disposed)
+                    return;
+                const res = {
+                    type: tspiceRpcResponseType,
+                    id: req.id,
+                    ok: true,
+                    value: encodeRpcValue(value),
+                };
+                self.postMessage(res);
+            }
+            catch (err) {
+                if (disposed)
+                    return;
+                const res = {
+                    type: tspiceRpcResponseType,
+                    id: req.id,
+                    ok: false,
+                    error: serializeError(err),
+                };
+                self.postMessage(res);
+            }
+            finally {
+                inFlight -= 1;
+                drain();
+            }
+        })();
+    };
+    const onMessage = (ev) => {
+        const msg = ev.data;
+        if (!msg || typeof msg.type !== "string")
+            return;
+        if (msg.type === tspiceRpcDisposeType) {
+            // Dispose is a one-way signal; ignore any further traffic.
+            if (disposed)
+                return;
+            disposed = true;
+            const queuedToFail = queued.slice(queuedHead);
+            clearQueue();
+            void (async () => {
+                try {
+                    await failQueuedRequests(queuedToFail, new Error("Worker disposed"));
+                    await opts.onDispose?.();
+                }
+                finally {
+                    self.removeEventListener("message", onMessage);
+                    const closeOnDispose = opts.closeOnDispose ?? true;
+                    if (closeOnDispose) {
+                        try {
+                            self.close?.();
+                        }
+                        catch {
+                            // ignore
+                        }
+                    }
+                }
+            })();
+            return;
+        }
+        // Ignore any further traffic after disposal (including in-flight requests
+        // that may finish later).
+        if (disposed)
+            return;
+        if (msg.type === tspiceRpcRequestType) {
+            const req = msg;
+            const id = req.id;
+            const op = req.op;
+            const args = req.args;
+            if (typeof id !== "number" || typeof op !== "string" || !Array.isArray(args)) {
+                return;
+            }
+            const queuedReq = { id, op, args };
+            if (inFlight < maxConcurrentRequests) {
+                runRequest(queuedReq);
+            }
+            else {
+                if (queuedSize() >= maxQueuedRequests) {
+                    const res = {
+                        type: tspiceRpcResponseType,
+                        id,
+                        ok: false,
+                        error: serializeError(new Error(`Worker backpressure queue overflow (maxQueuedRequests=${maxQueuedRequests})`)),
+                    };
+                    self.postMessage(res);
+                    return;
+                }
+                queued.push(queuedReq);
+            }
+            return;
+        }
+    };
+    self.addEventListener("message", onMessage);
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        const queuedToFail = queued.slice(queuedHead);
+        clearQueue();
+        void failQueuedRequests(queuedToFail, new Error("Worker disposed"));
+        // Note: this does not cancel any in-flight `transport.request()` calls; it
+        // just prevents any further responses from being posted.
+        self.removeEventListener("message", onMessage);
+    };
+    return { dispose };
+}
+//# sourceMappingURL=exposeTransportToWorker.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rybosome/tspice",
-  "version": "0.0.3",
+  "version": "0.0.8",
   "license": "MIT",
   "type": "module",
   "imports": {
@@ -23,9 +23,9 @@
     }
   },
   "optionalDependencies": {
-    "@rybosome/tspice-native-darwin-arm64": "0.0.3",
-    "@rybosome/tspice-native-darwin-x64": "0.0.3",
-    "@rybosome/tspice-native-linux-x64-gnu": "0.0.3"
+    "@rybosome/tspice-native-darwin-arm64": "0.0.8",
+    "@rybosome/tspice-native-darwin-x64": "0.0.8",
+    "@rybosome/tspice-native-linux-x64-gnu": "0.0.8"
   },
   "files": [
     "dist",