crossbind 0.0.1 → 2.0.0-beta.50

package/src/assets/js-runtime/adapters/worker-comlink.js

@@ -0,0 +1,309 @@
+/* global WorkerGlobalScope */
+import * as Comlink from 'comlink';
+import { mergeDeep } from '../core.js';
+import {
+    callWithVectorCoercion, wrapWithVectorCoercion, setCoercionModule, unwrapCoercionProxy,
+} from './vector-coercion.js';
+import { patchModuleForExceptionDecode } from './exception-decode.js';
+
+const isWorkerScope = typeof WorkerGlobalScope !== 'undefined'
+    && typeof self !== 'undefined'
+    && self instanceof WorkerGlobalScope;
+
+// === Embind <-> Comlink Bridge ===
+// Worker-side registry: id -> original embind object
+// Main-thread registry: Comlink proxy -> id
+const embindRegistry = new Map();
+const embindProxyIds = new WeakMap();
+let nextEmbindId = 1;
+
+function registerEmbindObject(obj) {
+    const id = nextEmbindId++;
+    embindRegistry.set(id, obj);
+    return id;
+}
+
+// Reorder transfer handlers for correct priority
+const _proxyHandler = Comlink.transferHandlers.get('proxy');
+const _throwHandler = Comlink.transferHandlers.get('throw');
+Comlink.transferHandlers.clear();
+
+// 1. embindProxy: when a proxied embind object is sent back as an argument,
+//    resolve it to the original object on the worker instead of creating a proxy-of-proxy
+Comlink.transferHandlers.set('embindProxy', {
+    canHandle(obj) {
+        return embindProxyIds.has(obj);
+    },
+    serialize(obj) {
+        return [embindProxyIds.get(obj), []];
+    },
+    deserialize(id) {
+        return embindRegistry.get(id);
+    },
+});
+
+// 2. proxy (modified): also registers embind objects created via CONSTRUCT
+Comlink.transferHandlers.set('proxy', {
+    canHandle: _proxyHandler.canHandle,
+    serialize(obj) {
+        if (typeof obj.delete === 'function' && typeof obj.isDeleted === 'function') {
+            // CONSTRUCT results (Comlink marks them with proxy()) are exposed through
+            // the same coercion wrapper as method-returned objects (embindObject
+            // handler), and the registry keeps the RAW object so arguments resolve
+            // back to real embind identities.
+            const raw = unwrapCoercionProxy(obj);
+            const [port, transferables] = _proxyHandler.serialize(wrapWithVectorCoercion(raw));
+            const id = registerEmbindObject(raw);
+            return [{ __embindId: id, __port: port }, transferables];
+        }
+        return _proxyHandler.serialize(obj);
+    },
+    deserialize(data) {
+        if (data != null && typeof data === 'object' && '__embindId' in data) {
+            const proxy = _proxyHandler.deserialize(data.__port);
+            embindProxyIds.set(proxy, data.__embindId);
+            return proxy;
+        }
+        return _proxyHandler.deserialize(data);
+    },
+});
+
+// 3. throw (restored)
+Comlink.transferHandlers.set('throw', _throwHandler);
+
+// 4. embindVector: convert embind vectors to arrays across worker boundary
+Comlink.transferHandlers.set('embindVector', {
+    canHandle(obj) {
+        return obj != null
+            && typeof obj === 'object'
+            && typeof obj.size === 'function'
+            && typeof obj.get === 'function'
+            && typeof obj.delete === 'function';
+    },
+    serialize(obj) {
+        const len = obj.size();
+        const elements = new Array(len);
+        let hasObjects = false;
+        for (let i = 0; i < len; i++) {
+            const elem = obj.get(i);
+            elements[i] = elem;
+            if (!hasObjects && elem !== null && typeof elem === 'object') {
+                hasObjects = true;
+            }
+        }
+        if (!hasObjects) {
+            return [elements, []];
+        }
+        const transferables = [];
+        for (let i = 0; i < len; i++) {
+            const elem = elements[i];
+            if (elem !== null && typeof elem === 'object') {
+                const id = registerEmbindObject(elem);
+                const { port1, port2 } = new MessageChannel();
+                Comlink.expose(wrapWithVectorCoercion(elem), port1);
+                transferables.push(port2);
+                elements[i] = { __comlinkProxy: true, __embindId: id, port: port2 };
+            }
+        }
+        return [elements, transferables];
+    },
+    deserialize(elements) {
+        return elements.map((elem) => {
+            if (elem && typeof elem === 'object' && elem.__comlinkProxy) {
+                elem.port.start();
+                const proxy = Comlink.wrap(elem.port);
+                embindProxyIds.set(proxy, elem.__embindId);
+                return proxy;
+            }
+            return elem;
+        });
+    },
+});
+
+// 4b. embindEnum: embind enum VALUES are class instances (not structured-cloneable) with
+// singleton identity per enumerator. Worker side registers each instance under an id; the
+// main thread gets a frozen, identity-stable token per id, and a token passed back as an
+// argument resolves to the original instance - so `===` survives both directions.
+const enumValueSet = new WeakSet();
+const enumInstanceIds = new WeakMap();
+const enumInstancesById = new Map();
+const enumTokensById = new Map();
+let nextEnumId = 1;
+
+// Worker side, at module-ready: collect enum value instances. embind hangs enumerators off
+// the enum TYPE, which is a FUNCTION (plus a `values` meta map), so both function and
+// object holders are walked; a value qualifies when it is an instance (non-Object
+// constructor) carrying a numeric .value and no lifecycle methods - which excludes HEAP
+// views, FS, class statics and config bags.
+export function registerModuleEnums(m) {
+    for (const key of Object.keys(m)) {
+        const holder = m[key];
+        if (holder == null || (typeof holder !== 'object' && typeof holder !== 'function')
+            || ArrayBuffer.isView(holder)) continue;
+        for (const v of Object.values(holder)) {
+            if (v != null && typeof v === 'object'
+                && typeof v.value === 'number'
+                && typeof v.delete !== 'function'
+                && v.constructor && v.constructor !== Object) {
+                enumValueSet.add(v);
+            }
+        }
+    }
+}
+
+Comlink.transferHandlers.set('embindEnum', {
+    canHandle(obj) {
+        if (obj == null || typeof obj !== 'object') return false;
+        return enumValueSet.has(unwrapCoercionProxy(obj)) || '__embindEnumRef' in obj;
+    },
+    serialize(obj) {
+        const raw = unwrapCoercionProxy(obj);
+        if (enumValueSet.has(raw)) {
+            let id = enumInstanceIds.get(raw);
+            if (!id) {
+                id = nextEnumId;
+                nextEnumId += 1;
+                enumInstanceIds.set(raw, id);
+                enumInstancesById.set(id, raw);
+            }
+            return [{ __embindEnumRef: id, value: raw.value }, []];
+        }
+        return [{ __embindEnumRef: raw.__embindEnumRef, value: raw.value }, []];
+    },
+    deserialize(data) {
+        const real = enumInstancesById.get(data.__embindEnumRef);
+        if (real) return real;
+        let token = enumTokensById.get(data.__embindEnumRef);
+        if (!token) {
+            token = Object.freeze({ __embindEnumRef: data.__embindEnumRef, value: data.value });
+            enumTokensById.set(data.__embindEnumRef, token);
+        }
+        return token;
+    },
+});
+
+// 5. embindObject: proxy other embind objects (Dataset, etc.)
+Comlink.transferHandlers.set('embindObject', {
+    canHandle(obj) {
+        return obj != null
+            && typeof obj === 'object'
+            && typeof obj.delete === 'function'
+            && typeof obj.isDeleted === 'function';
+    },
+    serialize(obj) {
+        const id = registerEmbindObject(obj);
+        const { port1, port2 } = new MessageChannel();
+        Comlink.expose(wrapWithVectorCoercion(obj), port1);
+        return [{ __embindId: id, port: port2 }, [port2]];
+    },
+    deserialize(data) {
+        data.port.start();
+        const proxy = Comlink.wrap(data.port);
+        embindProxyIds.set(proxy, data.__embindId);
+        return proxy;
+    },
+});
+
+// 6. embindProxyArray: a plain JS array that contains proxied embind objects
+//    can't be structured-cloned across the
+//    worker boundary, because the element proxies are functions. Resolve each
+//    registered proxy element back to its worker-side original, the same way the
+//    embindProxy handler does for a single argument.
+Comlink.transferHandlers.set('embindProxyArray', {
+    canHandle(obj) {
+        return Array.isArray(obj) && obj.some((e) => embindProxyIds.has(e));
+    },
+    serialize(arr) {
+        return [
+            arr.map((e) => (embindProxyIds.has(e) ? { __embindRef: embindProxyIds.get(e) } : e)),
+            [],
+        ];
+    },
+    deserialize(arr) {
+        return arr.map((e) => (e != null && typeof e === 'object' && '__embindRef' in e
+            ? embindRegistry.get(e.__embindRef)
+            : e));
+    },
+});
+
+let _worker = null;
+
+function resolveScriptUrl(config) {
+    const fileName = config.paths.js || config.paths.worker;
+    let prefix = '';
+    if (config.path) {
+        prefix = config.path;
+        if (prefix.slice(-1) !== '/') prefix += '/';
+    }
+    let output = prefix + fileName;
+    if (output.substring(0, 4) !== 'http' && output[0] !== '/') output = `/${output}`;
+    return output;
+}
+
+function exposeWorker(systemConfig, createModule) {
+    const workerApi = {
+        async init(userConfig = {}) {
+            const config = mergeDeep(systemConfig, userConfig);
+            const m = await createModule(config);
+            setCoercionModule(m);
+            // Decode on the worker side: a real Error (with the C++ message) survives the
+            // comlink throw handler, a raw WebAssembly.Exception does not.
+            patchModuleForExceptionDecode(m);
+            registerModuleEnums(m);
+            return Comlink.proxy(wrapWithVectorCoercion(m));
+        },
+    };
+    Comlink.expose(workerApi);
+}
+
+async function initWithWorker(config, userConfig) {
+    const scriptUrl = config.workerUrl || resolveScriptUrl(config);
+    _worker = new Worker(scriptUrl);
+    const workerApi = Comlink.wrap(_worker);
+
+    const {
+        logHandler, errorHandler, onRuntimeInitialized, getWasmFunction, useWorker, workerUrl,
+        ...serializableConfig
+    } = userConfig;
+    const module = await workerApi.init(serializableConfig);
+
+    return new Proxy(module, {
+        get(target, prop) {
+            if (prop === 'toArray') {
+                return function toArray(vector) {
+                    if (Array.isArray(vector)) return vector;
+                    return target.toArray(vector);
+                };
+            }
+            if (prop === 'toVector') {
+                return function toVector(classOrName, array = []) {
+                    if (typeof classOrName === 'string') {
+                        return target._createVector(classOrName, array);
+                    }
+                    return target.toVector(classOrName, array);
+                };
+            }
+            return target[prop];
+        },
+    });
+}
+
+function terminate() {
+    if (_worker) {
+        _worker.terminate();
+        _worker = null;
+    }
+}
+
+export default {
+    isWorkerScope,
+    exposeWorker,
+    initWithWorker,
+    terminate,
+};
+
+export {
+    isWorkerScope, exposeWorker, initWithWorker, terminate,
+    // exported for unit tests
+    callWithVectorCoercion, wrapWithVectorCoercion, setCoercionModule,
+};

package/src/assets/js-runtime/browser.js

@@ -0,0 +1,16 @@
+import Module from 'crossbind/module';
+import systemConfig from 'crossbind/systemConfig';
+
+import { createInitCrossbind, composeAdapters } from './core.js';
+import urlPath from './adapters/path-url.js';
+import browserFs from './adapters/fs-browser.js';
+import workerComlink from './adapters/worker-comlink.js';
+
+const adapter = composeAdapters([urlPath, browserFs]);
+
+export default createInitCrossbind({
+    Module,
+    systemConfig,
+    adapter,
+    worker: workerComlink,
+});

package/src/assets/js-runtime/core.js

@@ -0,0 +1,193 @@
+import { setCoercionModule, wrapModuleForCoercion } from './adapters/vector-coercion.js';
+import { patchModuleForExceptionDecode } from './adapters/exception-decode.js';
+
+export function isObject(item) {
+    return (item && typeof item === 'object' && !Array.isArray(item));
+}
+
+export function mergeDeep(target, ...sources) {
+    if (!sources.length) return target;
+    const source = sources.shift();
+
+    if (isObject(target) && isObject(source)) {
+        for (const key in source) {
+            if (isObject(source[key])) {
+                if (!target[key]) Object.assign(target, { [key]: {} });
+                mergeDeep(target[key], source[key]);
+            } else {
+                Object.assign(target, { [key]: source[key] });
+            }
+        }
+    }
+
+    return mergeDeep(target, ...sources);
+}
+
+export function composeAdapters(adapters) {
+    const composed = {};
+    const extendFns = [];
+    const readyFns = [];
+    for (const a of adapters) {
+        if (!a) continue;
+        if (a.getDefaultPathPrefix) composed.getDefaultPathPrefix = a.getDefaultPathPrefix;
+        if (a.getDataPath) composed.getDataPath = a.getDataPath;
+        if (a.finalizePath) composed.finalizePath = a.finalizePath;
+        if (a.extendModule) extendFns.push(a.extendModule);
+        if (a.onModuleReady) readyFns.push(a.onModuleReady);
+    }
+    if (extendFns.length) {
+        composed.extendModule = (m, config) => extendFns.forEach((fn) => fn(m, config));
+    }
+    if (readyFns.length) {
+        composed.onModuleReady = async (m, config) => {
+            for (const fn of readyFns) {
+                await fn(m, config);
+            }
+        };
+    }
+    return composed;
+}
+
+function buildLocateFile(config, adapter) {
+    return function locateFile(fileName) {
+        let path = fileName;
+        if (config.paths && config.paths.wasm && fileName.endsWith('.wasm')) {
+            path = config.paths.wasm;
+        } else if (config.paths && config.paths.data && (fileName.endsWith('.data.txt') || fileName.endsWith('.data'))) {
+            path = config.paths.data;
+        }
+
+        let prefix = '';
+        if (config.path) {
+            prefix = config.path;
+            if (prefix.slice(-1) !== '/') prefix += '/';
+        } else if (adapter.getDefaultPathPrefix) {
+            prefix = adapter.getDefaultPathPrefix();
+        }
+
+        let output = prefix + path;
+        if (output.endsWith('.data')) output += '.txt';
+        if (adapter.finalizePath) output = adapter.finalizePath(output);
+
+        return output;
+    };
+}
+
+export function createBaseModule(Module, config, adapter) {
+    return new Promise((resolve, reject) => {
+        const locateFile = buildLocateFile(config, adapter);
+        const dataPath = adapter.getDataPath ? adapter.getDataPath() : '/crossbind';
+
+        const m = {
+            print(text) {
+                if (config.logHandler) {
+                    config.logHandler(text, 'stdout');
+                } else {
+                    console.debug(`wasm stdout: ${text}`);
+                }
+            },
+            printErr(text) {
+                if (config.errorHandler) {
+                    config.errorHandler(text, 'stderr');
+                } else {
+                    console.error(`wasm stderr: ${text}`);
+                }
+            },
+            locateFile,
+            preRun: [
+                ({ ENV }) => {
+                    if (ENV && config && config.env) {
+                        Object.entries(config.env).forEach(([key, value]) => {
+                            ENV[key] = value?.replace('_CROSSBIND_DATA_PATH_', dataPath);
+                        });
+                    }
+                },
+            ],
+            unmount() {},
+            toArray(vector) {
+                if (Array.isArray(vector)) return vector;
+                const len = vector.size();
+                const output = new Array(len);
+                for (let i = 0; i < len; i += 1) {
+                    output[i] = vector.get(i);
+                }
+                return output;
+            },
+            toVector(classOrName, array = []) {
+                const VectorClass = typeof classOrName === 'string' ? m[classOrName] : classOrName;
+                const vector = new VectorClass();
+                array.forEach((item) => {
+                    vector.push_back(item);
+                });
+                return vector;
+            },
+        };
+
+        if (adapter.extendModule) adapter.extendModule(m, config);
+
+        if (config.getWasmFunction) {
+            m.instantiateWasm = function instantiateWasm(info, receive) {
+                const instance = new WebAssembly.Instance(config.getWasmFunction(), info);
+                receive(instance);
+                return instance.exports;
+            };
+        }
+
+        // onModuleReady may need to await async setup (e.g. the OPFS preflight in
+        // fs-browser), which emscripten's onRuntimeInitialized callback cannot, so
+        // both hooks run after the factory settles - adapter first, then the user's.
+        Module(m).then(async (mod) => {
+            if (adapter.onModuleReady) await adapter.onModuleReady(mod, config);
+            if (config.onRuntimeInitialized) config.onRuntimeInitialized(mod);
+            return mod;
+        }).then(resolve).catch(reject);
+    });
+}
+
+export function createInitCrossbind({
+    Module, systemConfig, adapter, worker,
+}) {
+    let crossbindPromise;
+
+    function createModule(config) {
+        return createBaseModule(Module, config, adapter);
+    }
+
+    if (worker && worker.isWorkerScope) {
+        worker.exposeWorker(systemConfig, createModule);
+    }
+
+    function initNative(userConfig = {}) {
+        if (crossbindPromise) return crossbindPromise;
+
+        const config = mergeDeep(systemConfig, userConfig);
+
+        if (worker && config.useWorker && !worker.isWorkerScope) {
+            crossbindPromise = worker.initWithWorker(config, userConfig);
+        } else {
+            // Direct (non-worker) mode: wrap the module so plain-array arguments coerce to
+            // embind vectors like they do in worker mode. Narrow wrapper — only the module's
+            // own calls, leaving HEAP*/FS/returned objects raw (see wrapModuleForCoercion).
+            crossbindPromise = createModule(config).then((m) => {
+                setCoercionModule(m);
+                // Instance/static methods stay raw in direct mode, so the decode has to
+                // land on the class prototypes themselves.
+                patchModuleForExceptionDecode(m);
+                return wrapModuleForCoercion(m);
+            });
+        }
+
+        return crossbindPromise;
+    }
+
+    initNative.terminate = function terminate() {
+        if (worker && worker.terminate) worker.terminate();
+        crossbindPromise = null;
+    };
+
+    if (typeof globalThis === 'object') {
+        globalThis.Crossbind = { initNative };
+    }
+
+    return initNative;
+}

package/src/assets/js-runtime/edge.js

@@ -0,0 +1,18 @@
+import Module from 'crossbind/module';
+import systemConfig from 'crossbind/systemConfig';
+
+import { createInitCrossbind, composeAdapters } from './core.js';
+import pathFs from './adapters/path-fs.js';
+
+const adapter = composeAdapters([
+    pathFs({
+        defaultPathPrefix: '',
+        dataPath: '/crossbind',
+    }),
+]);
+
+export default createInitCrossbind({
+    Module,
+    systemConfig,
+    adapter,
+});

package/src/assets/js-runtime/node.js

@@ -0,0 +1,20 @@
+import Module from 'crossbind/module';
+import systemConfig from 'crossbind/systemConfig';
+
+import { createInitCrossbind, composeAdapters } from './core.js';
+import pathFs from './adapters/path-fs.js';
+import nodeFs from './adapters/fs-node.js';
+
+const adapter = composeAdapters([
+    pathFs({
+        defaultPathPrefix: `${__dirname}/`,
+        dataPath: `${__dirname}/data`,
+    }),
+    nodeFs,
+]);
+
+export default createInitCrossbind({
+    Module,
+    systemConfig,
+    adapter,
+});

package/src/assets/packaging/crossbind-package.podspec

@@ -0,0 +1,17 @@
+require "json"
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.module_name  = "___PROJECT_MODULE_NAME___"
+  s.name         = "___PROJECT_NAME___"
+  s.version      = package["nativeVersion"]
+  s.summary      = "___PROJECT_NAME___ package"
+  s.homepage     = "https://crossbind.dev"
+  s.author       = "___PROJECT_NAME___ Authors"
+  s.source       = { :http => "https://crossbind.dev" }
+  s.vendored_frameworks = ___PROJECT_FRAMEWORKS___
+  s.resources = ___PROJECT_RESOURCES___
+  # arm64-only iOS simulator slice; drop x86_64 to avoid linker errors on consumer apps.
+  # Cargo producers add a -force_load so their init-array constructors survive dead-strip.
+  s.user_target_xcconfig = { 'EXCLUDED_ARCHS[sdk=iphonesimulator*]' => 'x86_64'___PROJECT_LDFLAGS___ }
+end

package/src/assets/wasi-runtime/stubs.c

@@ -0,0 +1,84 @@
+/* Clean-failing stubs for symbols the WASI libc lacks; keeps command modules free of undefined imports. */
+
+#include <errno.h>
+#include <stddef.h>
+#include <stdio.h>
+#include <string.h>
+
+#include <netinet/in.h>
+#include <sys/socket.h>
+
+/* Compiled by the C++ driver at the command link; keep C linkage. */
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* No dynamic loading on WASI; loaders treat NULL as "plugin unavailable". */
+void *dlopen(const char *file, int mode)
+{
+    (void)file;
+    (void)mode;
+    return NULL;
+}
+
+char *dlerror(void)
+{
+    return (char *)"dynamic loading is not supported on WASI";
+}
+
+void *dlsym(void *handle, const char *symbol)
+{
+    (void)handle;
+    (void)symbol;
+    return NULL;
+}
+
+int dlclose(void *handle)
+{
+    (void)handle;
+    return -1;
+}
+
+/* WASI has no ambient /tmp; POSIX lets tmpfile fail, callers must handle NULL (libtiff's fax2ps does). */
+FILE *tmpfile(void)
+{
+    errno = ENOTSUP;
+    return NULL;
+}
+
+/* No fork on WASI; registering handlers is safely a no-op (PROJ registers one). */
+int pthread_atfork(void (*prepare)(void), void (*parent)(void), void (*child)(void))
+{
+    (void)prepare;
+    (void)parent;
+    (void)child;
+    return 0;
+}
+
+/* wasmtime (46/47) traps in mid-connect getsockname/getpeername; zeroed shadows keep libcurl alive - drop when the runtime catches up. */
+static int crossbind_zeroed_inet(struct sockaddr *addr, socklen_t *len)
+{
+    struct sockaddr_in a;
+    memset(&a, 0, sizeof a);
+    a.sin_family = AF_INET;
+    socklen_t n = *len < (socklen_t)sizeof a ? *len : (socklen_t)sizeof a;
+    memcpy(addr, &a, n);
+    *len = (socklen_t)sizeof a;
+    return 0;
+}
+
+int getsockname(int fd, struct sockaddr *addr, socklen_t *len)
+{
+    (void)fd;
+    return crossbind_zeroed_inet(addr, len);
+}
+
+int getpeername(int fd, struct sockaddr *addr, socklen_t *len)
+{
+    (void)fd;
+    return crossbind_zeroed_inet(addr, len);
+}
+
+#ifdef __cplusplus
+}
+#endif