@rybosome/tspice 0.0.7 → 0.0.8

package/dist/worker/browser/createSpiceWorkerClient.js

@@ -0,0 +1,99 @@
+import { createSpiceAsyncFromTransport } from "../../clients/createSpiceAsyncFromTransport.js";
+import { createWorkerTransport, } from "../transport/createWorkerTransport.js";
+import { createSpiceWorker } from "./createSpiceWorker.js";
+function getDisposeFn(value) {
+    if (value === null)
+        return undefined;
+    const t = typeof value;
+    if (t !== "object" && t !== "function")
+        return undefined;
+    const dispose = value.dispose;
+    return typeof dispose === "function" ? dispose : undefined;
+}
+function isPromiseLike(value) {
+    if (value === null)
+        return false;
+    const t = typeof value;
+    if (t !== "object" && t !== "function")
+        return false;
+    return typeof value.then === "function";
+}
+/** Create a {@link SpiceWorkerClient} that communicates with a tspice Web Worker via RPC. */
+export function createSpiceWorkerClient(opts) {
+    const workerInput = opts?.worker ?? (() => createSpiceWorker());
+    const worker = typeof workerInput === "function" ? workerInput() : workerInput;
+    const terminateOnDispose = opts?.terminateOnDispose ??
+        (typeof workerInput === "function" ? true : false);
+    const baseTransport = createWorkerTransport({
+        worker,
+        ...(opts?.timeoutMs === undefined ? {} : { timeoutMs: opts.timeoutMs }),
+        terminateOnDispose,
+        ...(opts?.signalDispose === undefined
+            ? {}
+            : { signalDispose: opts.signalDispose }),
+    });
+    const transport = opts?.wrapTransport
+        ? opts.wrapTransport(baseTransport)
+        : baseTransport;
+    const spice = createSpiceAsyncFromTransport(transport);
+    let disposePromise;
+    const disposeAsync = () => {
+        if (disposePromise)
+            return disposePromise;
+        disposePromise = (async () => {
+            try {
+                // If a wrapper transport supports cleanup, run it before disposing the
+                // underlying worker transport.
+                if (transport !== baseTransport) {
+                    const wrapperDispose = getDisposeFn(transport);
+                    if (wrapperDispose) {
+                        const result = wrapperDispose.call(transport);
+                        if (isPromiseLike(result))
+                            await result;
+                    }
+                }
+            }
+            finally {
+                baseTransport.dispose();
+            }
+        })();
+        return disposePromise;
+    };
+    const dispose = () => {
+        // Fire-and-forget. Ensure we don't surface unhandled rejections if wrapper
+        // cleanup fails.
+        void disposeAsync().catch((err) => {
+            try {
+                opts?.onDisposeError?.(err);
+            }
+            catch (callbackErr) {
+                if (typeof console !== "undefined" &&
+                    typeof console.error === "function") {
+                    // Log both: the original disposal failure and the error thrown by the
+                    // error callback.
+                    try {
+                        console.error("createSpiceWorkerClient.dispose(): disposeAsync() failed", err);
+                    }
+                    catch {
+                        // ignore
+                    }
+                    try {
+                        console.error("createSpiceWorkerClient.dispose(): onDisposeError threw", callbackErr);
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+            }
+        });
+    };
+    return {
+        worker,
+        baseTransport,
+        transport,
+        spice,
+        dispose,
+        disposeAsync,
+    };
+}
+//# sourceMappingURL=createSpiceWorkerClient.js.map

package/dist/worker/browser/spiceWorkerEntry.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=spiceWorkerEntry.d.ts.map

package/dist/worker/browser/spiceWorkerEntry.js

@@ -0,0 +1,129 @@
+import { createSpiceAsync } from "../../spice.js";
+import { exposeTransportToWorker } from "../transport/exposeTransportToWorker.js";
+const getWorkerConfig = () => {
+    const cfg = globalThis
+        .__TSPICE_WORKER_CONFIG__;
+    if (!cfg || typeof cfg !== "object")
+        return undefined;
+    return cfg;
+};
+const blockedStringKeys = new Set([
+    // Promise / thenable
+    "then",
+    // Prototype / constructor escapes
+    "__proto__",
+    "prototype",
+    "constructor",
+    // Common stringification / inspection hooks
+    "toJSON",
+    "inspect",
+    // Object.prototype keys (avoid accidental RPC calls during introspection)
+    "toString",
+    "valueOf",
+    "toLocaleString",
+    "hasOwnProperty",
+    "isPrototypeOf",
+    "propertyIsEnumerable",
+    "__defineGetter__",
+    "__defineSetter__",
+    "__lookupGetter__",
+    "__lookupSetter__",
+]);
+const isSafeRpcKey = (key) => /^[A-Za-z_$][\w$]*$/.test(key);
+const allowedKitMethodList = [
+    "loadKernel",
+    "unloadKernel",
+    "kclear",
+    "toolkitVersion",
+    "utcToEt",
+    "etToUtc",
+    "frameTransform",
+    "getState",
+];
+const defaultAllowlist = {
+    // NOTE: `kit` is deliberately allowlisted because it's a small, curated API.
+    // `raw` is intentionally not allowlisted here (see module comment below).
+    kit: new Set(allowedKitMethodList),
+};
+function createSpiceTransportFromSpiceAsync(spice, opts) {
+    const allowlist = opts?.allowlist ?? defaultAllowlist;
+    return {
+        request: async (op, args) => {
+            const dot = op.indexOf(".");
+            if (dot <= 0 || dot === op.length - 1) {
+                throw new Error(`Invalid op: ${op}`);
+            }
+            const namespace = op.slice(0, dot);
+            const method = op.slice(dot + 1);
+            if (namespace !== "raw" && namespace !== "kit") {
+                throw new Error(`Unknown namespace: ${namespace}`);
+            }
+            if (!isSafeRpcKey(method) || blockedStringKeys.has(method)) {
+                throw new Error(`Invalid method name: ${method}`);
+            }
+            const ns = namespace;
+            const nsAllowlist = allowlist[ns];
+            if (nsAllowlist && !nsAllowlist.has(method)) {
+                throw new Error(`Disallowed op: ${op}`);
+            }
+            const target = spice[ns];
+            const fn = target[method];
+            if (typeof fn !== "function") {
+                throw new Error(`Unknown op: ${op}`);
+            }
+            // `spice.raw` and `spice.kit` are proxies that return bound/wrapped
+            // functions, but use Reflect.apply to be defensive about `this`.
+            return await Reflect.apply(fn, target, args);
+        },
+    };
+}
+// NOTE: This file is meant to be loaded as a Web Worker module.
+// It intentionally has no exports and runs as a side-effect.
+//
+// Security/design note:
+// - This worker entry is intended for internal workspace use.
+// - By default, it exposes:
+//   - `kit.*` as a small, curated allowlist (see `allowedKitMethodList`), and
+//   - `raw.*` without an allowlist (subject to the blocked key checks above).
+// - If you need a tighter RPC capability set (especially for `raw.*`), create
+//   a custom worker entry and provide an explicit allowlist.
+//
+// IMPORTANT: `exposeTransportToWorker()` must run synchronously so the worker's
+// `message` handler is installed immediately. Otherwise, early RPC messages from
+// the main thread can be dropped while the WASM backend is still initializing.
+let spicePromise;
+let transportPromise;
+const getSpicePromise = () => {
+    if (spicePromise)
+        return spicePromise;
+    const config = getWorkerConfig();
+    const wasmUrl = config?.wasmUrl;
+    spicePromise = createSpiceAsync({
+        backend: "wasm",
+        ...(wasmUrl === undefined ? {} : { wasmUrl }),
+    });
+    return spicePromise;
+};
+const getTransportPromise = () => (transportPromise ??= getSpicePromise().then((spice) => createSpiceTransportFromSpiceAsync(spice)));
+exposeTransportToWorker({
+    transport: {
+        request: async (op, args) => (await getTransportPromise()).request(op, args),
+    },
+    onDispose: async () => {
+        // Best-effort cleanup. Worker termination also releases resources, but this
+        // helps callers who keep the worker alive.
+        if (!spicePromise) {
+            return;
+        }
+        try {
+            const spice = await getSpicePromise();
+            await spice.raw.kclear();
+        }
+        catch {
+            // ignore
+        }
+    },
+});
+// Kick off init after the `message` handler has been installed.
+void getTransportPromise();
+//# sourceMappingURL=spiceWorkerEntry.js.map

package/dist/worker/browser/spiceWorkerInlineSource.d.ts

@@ -0,0 +1,2 @@
+export declare const SPICE_WORKER_INLINE_SOURCE: string;
+//# sourceMappingURL=spiceWorkerInlineSource.d.ts.map