crossbind 0.0.1 → 2.0.0-beta.51

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

@@ -0,0 +1,12 @@
+#include <emscripten.h>
+#include <emscripten/bind.h>
+#include <emscripten/wasmfs.h>
+
+void crossbind_init_opfs() {
+  backend_t opfs_backend = wasmfs_create_opfs_backend();
+  wasmfs_create_directory("/opfs", 0777, opfs_backend);
+}
+
+EMSCRIPTEN_BINDINGS(Browser) {
+  emscripten::function("crossbind_init_opfs", &crossbind_init_opfs);
+};

package/src/assets/cpp-runtime/commonBridges.cpp

@@ -0,0 +1,17 @@
+#include <emscripten/bind.h>
+
+EMSCRIPTEN_BINDINGS(CommonBridges) {
+  emscripten::register_vector<char>("VectorChar");
+  emscripten::register_vector<unsigned char>("VectorUChar");
+  emscripten::register_vector<short>("VectorShort");
+  emscripten::register_vector<int>("VectorInt");
+  emscripten::register_vector<int64_t>("VectorInt64");
+  emscripten::register_vector<float>("VectorFloat");
+  emscripten::register_vector<double>("VectorDouble");
+  emscripten::register_vector<std::string>("VectorString");
+
+  emscripten::register_map<int, int>("MapIntInt");
+  emscripten::register_map<int, std::string>("MapIntString");
+  emscripten::register_map<std::string, std::string>("MapStringString");
+  emscripten::register_map<std::string, int>("MapStringInt");
+};

package/src/assets/cpp-runtime/crossbindEmptySource.cpp

@@ -0,0 +1,9 @@
+// Placeholder TU so the static archive always exports at least one symbol;
+// otherwise ranlib emits "has no symbols" warnings.
+//
+// `inline` gives the variable C++17 vague/COMDAT linkage so the same file
+// compiled into multiple libraries can be linked into one binary without
+// ODR conflicts. `[[gnu::used]]` (clang/gcc) forces the compiler to emit
+// the symbol even though nothing references it; without it, the optimizer
+// drops the inline variable and the warning persists.
+[[maybe_unused, gnu::used]] inline int crossbind_empty_source_marker = 0;

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

@@ -0,0 +1,19 @@
+#include <emscripten.h>
+#include <emscripten/wasmfs.h>
+#include <limits.h>
+#include <unistd.h>
+
+backend_t wasmfs_create_root_dir(void) {
+  return wasmfs_create_node_backend("/");
+}
+
+void wasmfs_before_preload(void) {
+  backend_t mem = wasmfs_create_memory_backend();
+  wasmfs_create_directory("/memfs", 0777, mem);
+}
+
+__attribute__((constructor)) static void setup_cwd(void) {
+  char cwd[PATH_MAX];
+  EM_ASM({ stringToUTF8(process.cwd(), $0, $1); }, cwd, (int)sizeof(cwd));
+  chdir(cwd);
+}

package/src/assets/js-runtime/adapters/exception-decode.js

@@ -0,0 +1,79 @@
+// === wasm-EH exception decoding (shared by the worker and direct runtimes) ===
+// Builds link with -fwasm-exceptions, so an uncaught C++ exception reaches JS as a raw
+// WebAssembly.Exception with no .message. The glue exports getExceptionMessage (via
+// -sEXPORT_EXCEPTION_HANDLING_HELPERS), which decodes it back into [type, what()]. This
+// adapter turns such values into real JS Errors at the binding boundary; anything else
+// passes through untouched, so it is safe to apply on every call path.
+let decodeModule = null;
+
+export function setExceptionDecodeModule(m) {
+    decodeModule = m;
+}
+
+export function decodeCppException(value) {
+    const m = decodeModule;
+    if (m == null
+        || typeof m.getExceptionMessage !== 'function'
+        || typeof WebAssembly === 'undefined'
+        || typeof WebAssembly.Exception !== 'function'
+        || !(value instanceof WebAssembly.Exception)) {
+        return value;
+    }
+    try {
+        const [type, message] = m.getExceptionMessage(value);
+        const error = new Error(message ? `${type}: ${message}` : `${type}`);
+        error.cppType = type;
+        error.cppMessage = message;
+        return error;
+    } catch (decodeFailure) {
+        return value;
+    }
+}
+
+const STATIC_SKIP = new Set(['prototype', 'name', 'length', 'caller', 'arguments', 'argCount']);
+
+function wrapOwnMethod(holder, name) {
+    const desc = Object.getOwnPropertyDescriptor(holder, name);
+    if (!desc || typeof desc.value !== 'function' || desc.writable === false) return;
+    const original = desc.value;
+    function decoded(...args) {
+        let result;
+        try {
+            result = original.apply(this, args);
+        } catch (e) {
+            throw decodeCppException(e);
+        }
+        if (result && typeof result.then === 'function') {
+            // Async (JSPI-style) binding: decode the rejection reason as well.
+            return result.then(undefined, (e) => { throw decodeCppException(e); });
+        }
+        return result;
+    }
+    // Overload dispatch reads properties (e.g. overloadTable) off the exposed function.
+    Object.assign(decoded, original);
+    Object.defineProperty(holder, name, { ...desc, value: decoded });
+}
+
+// Direct (non-worker) mode exposes embind class instances raw, so a thrown C++ exception in
+// an instance or static method never crosses a wrapper. Patching each bound class's
+// prototype and statics once at module-ready keeps object identity intact (embind checks
+// prototypes, not method identity) while every call site gains the decode.
+export function patchModuleForExceptionDecode(m) {
+    setExceptionDecodeModule(m);
+    if (m == null || typeof m !== 'object') return m;
+    for (const key of Object.keys(m)) {
+        const Cls = m[key];
+        if (typeof Cls !== 'function') continue;
+        if (Cls.prototype) {
+            // Static-only classes are common (pure class_function surfaces), so statics are
+            // wrapped below regardless of whether the prototype carries any method.
+            Object.getOwnPropertyNames(Cls.prototype)
+                .filter((n) => n !== 'constructor')
+                .forEach((n) => wrapOwnMethod(Cls.prototype, n));
+        }
+        Object.getOwnPropertyNames(Cls)
+            .filter((n) => !STATIC_SKIP.has(n))
+            .forEach((n) => wrapOwnMethod(Cls, n));
+    }
+    return m;
+}

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

@@ -0,0 +1,173 @@
+/* global WorkerGlobalScope */
+import * as Comlink from 'comlink';
+
+const STATIC_PATHS = {
+    opfs: '/opfs',
+    memfs: '/memfs',
+};
+
+const isWorkerScope = typeof WorkerGlobalScope !== 'undefined'
+    && typeof self !== 'undefined'
+    && self instanceof WorkerGlobalScope;
+
+const isBrowserSupportOPFS = typeof navigator !== 'undefined'
+    && navigator.storage
+    && navigator.storage.getDirectory;
+
+// Presence of the API does not guarantee a working backend: Playwright's WebKit
+// rejects getDirectory() with UnknownError, and storage-restricted contexts
+// reject too. false only after the onModuleReady preflight actually failed.
+let isOpfsFunctional = true;
+
+export default {
+    extendModule(m, config) {
+        // Hand the pthread spawn script to the glue via a crossbind-specific key. Using emscripten's
+        // own mainScriptUrlOrBlob aborts emsdk 6 debug builds ("supplied but not included in
+        // INCOMING_MODULE_JS_API") on single-thread targets; a custom key is not validated, and
+        // buildWasm rewrites the pthread bootstrap to read it (falling back to _scriptName).
+        const pthreadScript = config.paths.worker || config.paths.js;
+        if (pthreadScript) {
+            m.crossbindMainScript = m.locateFile(pthreadScript);
+        }
+
+        m.getDefaultPath = () => STATIC_PATHS[(config.fs?.opfs !== false && isOpfsFunctional) ? 'opfs' : 'memfs'];
+
+        m.getFinalPath = function getFinalPath(path) {
+            let returnPath = path;
+            if (!path.startsWith('/')) {
+                throw new Error(`Path ${path} does not start with /`);
+            }
+
+            const opfsConfigured = config.fs?.opfs !== false;
+
+            let backend;
+            Object.entries(STATIC_PATHS).forEach(([key, value]) => {
+                if (path.startsWith(value)) {
+                    backend = key;
+                }
+            });
+            if (!backend) {
+                throw new Error(`Path ${path} does not start with any of the static paths: ${Object.values(STATIC_PATHS).join(', ')}`);
+            }
+            if (backend === 'opfs' && !opfsConfigured) {
+                throw new Error(`Path ${path} starts with ${STATIC_PATHS.opfs} but OPFS is disabled. Enable fs.opfs in config to mount under ${STATIC_PATHS.opfs}/.`);
+            }
+            if (backend === 'opfs' && !isWorkerScope) {
+                throw new Error(`Path ${path} starts with ${STATIC_PATHS.opfs} but OPFS is only available inside a Worker scope. Enable useWorker or mount under ${STATIC_PATHS.memfs}/ instead. Falling back to ${STATIC_PATHS.memfs}/.`);
+            }
+            if (backend === 'opfs' && (!isBrowserSupportOPFS || !isOpfsFunctional)) {
+                console.error(`Path ${path} starts with ${STATIC_PATHS.opfs} but OPFS is not usable in this browser. Falling back to ${STATIC_PATHS.memfs}/.`);
+                returnPath = returnPath.replace(STATIC_PATHS.opfs, STATIC_PATHS.memfs);
+            }
+
+            return returnPath;
+        };
+
+        m.getRandomPath = function getRandomPath(startPath = m.getDefaultPath()) {
+            const appName = config.general?.name;
+            const rand = Math.floor(Math.random() * 1000000);
+            const path = m.getFinalPath(`${startPath}/${appName}/automounted/${rand}`);
+            m.FS.mkdirTree(path);
+            return path;
+        };
+
+        m.autoMountFiles = function autoMountFiles(files, parentPath = null) {
+            return new Promise((resolve, reject) => {
+                if (files.length === 0) {
+                    resolve([]);
+                    return;
+                }
+
+                const mountPath = parentPath ? m.getFinalPath(parentPath) : m.getRandomPath();
+                m.FS.mkdirTree(mountPath);
+
+                (async () => {
+                    try {
+                        const paths = [];
+                        for (const f of files) {
+                            const filePath = `${mountPath}/${f.name}`;
+                            const stream = m.FS.open(filePath, 'w');
+                            const reader = f.stream().getReader();
+                            let offset = 0;
+
+                            while (true) {
+                                const { done, value } = await reader.read();
+                                if (done) break;
+                                m.FS.write(stream, value, 0, value.length, offset);
+                                offset += value.length;
+                            }
+
+                            m.FS.close(stream);
+                            paths.push(filePath);
+                        }
+                        resolve(paths);
+                    } catch (e) {
+                        reject(e);
+                    }
+                })();
+            });
+        };
+
+        m.getFileBytes = function getFileBytes(path) {
+            if (!path) return new Uint8Array();
+            return m.FS.readFile(path, { encoding: 'binary' });
+        };
+
+        m.getFileList = function getFileList(path = m.getDefaultPath()) {
+            const fileList = [];
+            for (const name of m.FS.readdir(path)) {
+                if (name === '.' || name === '..') continue;
+                const fullPath = path === '/' ? `/${name}` : `${path}/${name}`;
+                const stat = m.FS.stat(fullPath);
+                const type = stat.mode & 0o170000;
+                if (type === 0o040000) {
+                    fileList.push(...m.getFileList(fullPath));
+                } else if (type === 0o100000) {
+                    fileList.push({ path: fullPath, size: stat.size });
+                }
+            }
+            return fileList;
+        };
+
+        m._createVector = function _createVector(className, array = []) {
+            const vector = m.toVector(className, array);
+            return Comlink.proxy(vector);
+        };
+    },
+
+    async onModuleReady(m, config) {
+        const appName = config.general?.name;
+        try {
+            m.FS.mkdirTree(`${STATIC_PATHS.memfs}/${appName}/automounted`);
+        } catch (e) {
+            console.error(e);
+        }
+
+        if (!(isWorkerScope && isBrowserSupportOPFS && config.fs?.opfs !== false && typeof m.crossbind_init_opfs === 'function')) {
+            return;
+        }
+
+        // crossbind_init_opfs() blocks until the OPFS root opens; if the backend is
+        // broken, that rejection is swallowed inside the WASMFS proxy pthread and
+        // init deadlocks with no signal. Probe the root here first instead.
+        try {
+            await navigator.storage.getDirectory();
+        } catch (error) {
+            isOpfsFunctional = false;
+            console.error(`OPFS is present but not functional in this environment (${error}). Falling back to ${STATIC_PATHS.memfs}/.`);
+            return;
+        }
+
+        m.crossbind_init_opfs();
+        if (appName) {
+            const appDir = `${STATIC_PATHS.opfs}/${appName}/automounted`;
+            try {
+                m.FS.mkdirTree(appDir);
+            } catch (e) {
+                console.error(e);
+            }
+        }
+    },
+};
+
+export { STATIC_PATHS, isWorkerScope, isBrowserSupportOPFS };

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

@@ -0,0 +1,28 @@
+export default {
+    extendModule(m) {
+        m.getPreloadedPackage = function getPreloadedPackage(packageName) {
+            return require('fs').readFileSync(`./${packageName}`, { flag: 'r' }).buffer;
+        };
+
+        m.getFileBytes = function getFileBytes(path) {
+            if (!path) return new Uint8Array();
+            return m.FS.readFile(path, { encoding: 'binary' });
+        };
+
+        m.getFileList = function getFileList(path = '/memfs') {
+            const fileList = [];
+            for (const name of m.FS.readdir(path)) {
+                if (name === '.' || name === '..') continue;
+                const fullPath = path === '/' ? `/${name}` : `${path}/${name}`;
+                const stat = m.FS.stat(fullPath);
+                const type = stat.mode & 0o170000;
+                if (type === 0o040000) {
+                    fileList.push(...m.getFileList(fullPath));
+                } else if (type === 0o100000) {
+                    fileList.push({ path: fullPath, size: stat.size });
+                }
+            }
+            return fileList;
+        };
+    },
+};

package/src/assets/js-runtime/adapters/path-fs.js

@@ -0,0 +1,6 @@
+export default function pathFs({ defaultPathPrefix, dataPath }) {
+    return {
+        getDefaultPathPrefix: () => defaultPathPrefix,
+        getDataPath: () => dataPath,
+    };
+}

package/src/assets/js-runtime/adapters/path-url.js

@@ -0,0 +1,8 @@
+export default {
+    finalizePath(output) {
+        if (output.substring(0, 4) !== 'http' && output[0] !== '/') {
+            return `/${output}`;
+        }
+        return output;
+    },
+};

package/src/assets/js-runtime/adapters/vector-coercion.js

@@ -0,0 +1,209 @@
+// === Plain array -> embind vector coercion (shared by the worker and direct runtimes) ===
+// Vectors RETURNED across the worker boundary arrive as plain arrays, so callers naturally
+// try to pass plain arrays back as vector PARAMETERS - which embind rejects with
+// 'Cannot pass "..." as a VectorX'. Coercion catches that error, converts the first
+// remaining plain-array argument with Module.toVector, and retries, so mixed signatures
+// (VectorDataset + VectorString, ...) resolve left to right, matching embind's argument
+// order. embind passes std::vector parameters by value, so the temporaries are deleted
+// after the call instead of leaking wasm memory.
+//
+// This is a REACTIVE strategy: embind does not expose parameter types to JS, so we can
+// only learn that an argument should have been a vector from the failed call. See
+// EXPECTED_VECTOR_RE below - the coercion silently disengages (rethrows) if embind ever
+// changes that message, which the canary test in vectorCoercion.test.js guards against.
+import { decodeCppException } from './exception-decode.js';
+
+let coercionModule = null;
+
+// Matches embind's "Cannot pass <value> as a VectorX" BindingError message.
+const EXPECTED_VECTOR_RE = /as a (Vector\w+)\b/;
+
+export function setCoercionModule(m) {
+    coercionModule = m;
+}
+
+// Proxies created by the coercion wrappers, mapped back to their raw targets. embind
+// rejects a proxied `this` or argument (its class checks compare $$.ptrType.registeredClass
+// by identity), so every invocation unwraps them back to the raw objects first.
+const coercionProxies = new WeakMap();
+
+export function unwrapCoercionProxy(value) {
+    const raw = coercionProxies.get(value);
+    return raw === undefined ? value : raw;
+}
+
+// The retry-on-vector-error loop shared by call and construct. `invoke(args)` performs the
+// actual apply/construct; on a 'Cannot pass ... as a VectorX' error that names a registered
+// Vector class while a plain-array argument remains, the first remaining array is converted
+// with Module.toVector and the invocation retried. Each retry converts exactly one array, so
+// the array count strictly decreases and the loop always terminates.
+function retryWithCoercion(invoke, args) {
+    const temp = [];
+    const cleanup = () => {
+        for (const v of temp) {
+            try {
+                v.delete();
+            } catch (e) { /* already deleted by the callee */ }
+        }
+    };
+    const current = args.slice();
+    for (;;) {
+        let result;
+        try {
+            result = invoke(current);
+        } catch (rawError) {
+            const e = decodeCppException(rawError);
+            const match = EXPECTED_VECTOR_RE.exec(String((e && e.message) || e));
+            const VectorClass = match && coercionModule ? coercionModule[match[1]] : undefined;
+            const index = current.findIndex((a) => Array.isArray(a));
+            if (typeof VectorClass !== 'function' || index < 0) {
+                cleanup();
+                throw e;
+            }
+            let vector;
+            try {
+                vector = coercionModule.toVector(VectorClass, current[index]);
+            } catch (convError) {
+                cleanup();
+                throw e;
+            }
+            temp.push(vector);
+            current[index] = vector;
+            continue;
+        }
+        if (temp.length && result && typeof result.then === 'function') {
+            // Async (JSPI-style) binding: arguments were already converted synchronously,
+            // but hold the temporaries until it settles.
+            return result.then(
+                (value) => {
+                    cleanup();
+                    return value;
+                },
+                (err) => {
+                    cleanup();
+                    throw decodeCppException(err);
+                },
+            );
+        }
+        cleanup();
+        return result;
+    }
+}
+
+export function callWithVectorCoercion(fn, thisArg, args) {
+    return retryWithCoercion((current) => Reflect.apply(fn, thisArg, current), args);
+}
+
+export function constructWithVectorCoercion(Class, args, newTarget) {
+    return retryWithCoercion((current) => Reflect.construct(Class, current, newTarget || Class), args);
+}
+
+// Deep wrapper (WORKER mode): every method reached through the wrapped object - at any depth
+// (Module.Gdal.openEx, dataset.translate, ...) - is invoked through callWithVectorCoercion,
+// and every `new` through the construct trap below. Safe here because the worker world is
+// entirely opaque Comlink proxies - nothing accesses raw memory or object identity through it.
+export function wrapWithVectorCoercion(value, thisArg) {
+    if (value == null || (typeof value !== 'object' && typeof value !== 'function')) {
+        return value;
+    }
+    const proxy = new Proxy(value, {
+        get(target, prop) {
+            const member = Reflect.get(target, prop);
+            // Comlink invokes exposed methods as rawValue.apply(parent, args) with parent
+            // being the WRAPPED object. Handle Function.prototype apply/call here so `this`
+            // and the argument list reach callWithVectorCoercion unwrapped and flat (retries
+            // depend on seeing the real argument positions).
+            if (typeof target === 'function' && member === Function.prototype.apply) {
+                return (applyThis, applyArgs) => callWithVectorCoercion(
+                    target,
+                    applyThis === undefined && thisArg !== undefined
+                        ? thisArg
+                        : unwrapCoercionProxy(applyThis),
+                    applyArgs ? Array.prototype.map.call(applyArgs, unwrapCoercionProxy) : [],
+                );
+            }
+            if (typeof target === 'function' && member === Function.prototype.call) {
+                return (callThis, ...callArgs) => callWithVectorCoercion(
+                    target,
+                    callThis === undefined && thisArg !== undefined
+                        ? thisArg
+                        : unwrapCoercionProxy(callThis),
+                    callArgs.map(unwrapCoercionProxy),
+                );
+            }
+            if (typeof member === 'function' || (member !== null && typeof member === 'object')) {
+                // Proxy invariant: non-configurable, non-writable data properties (a class's
+                // .prototype, notably) must be returned as-is, or the engine throws on access.
+                const desc = Reflect.getOwnPropertyDescriptor(target, prop);
+                if (desc && desc.configurable === false && desc.writable === false) {
+                    return member;
+                }
+                return wrapWithVectorCoercion(member, target);
+            }
+            return member;
+        },
+        set(target, prop, value) {
+            // 3-arg Reflect.set keeps the RAW object as receiver: embind property setters
+            // identity-check `this`, and the default (proxy receiver) fails that check.
+            return Reflect.set(target, prop, unwrapCoercionProxy(value));
+        },
+        apply(target, applyThis, args) {
+            const boundThis = thisArg !== undefined ? thisArg : unwrapCoercionProxy(applyThis);
+            return callWithVectorCoercion(target, boundThis, args.map(unwrapCoercionProxy));
+        },
+        construct(target, args) {
+            // Comlink's CONSTRUCT handler does `new rawValue(...args)` on the wrapped
+            // class. Without this trap the construction falls through with the PROXY as
+            // newTarget, whose get trap hands out a wrapped .prototype (embind classes
+            // are plain functions, so their prototype is writable and the proxy
+            // invariant early-return does not apply) - and embind's prototype-identity
+            // check rejects the instance with "Use 'new' to construct X". Constructing
+            // against the raw class keeps the real prototype and adds the same
+            // plain-array vector coercion that method calls get.
+            return constructWithVectorCoercion(target, args.map(unwrapCoercionProxy));
+        },
+    });
+    coercionProxies.set(proxy, value);
+    return proxy;
+}
+
+// Narrow wrapper (DIRECT / non-worker mode): only the module's own function calls and
+// constructions are coerced. Data members (HEAP*, FS, typed arrays) and returned objects
+// stay raw, because direct-mode code accesses those by index and by identity - a blanket
+// proxy (like the worker wrapper above) would break them. Returned embind objects are
+// already real vectors/objects in direct mode (they are not flattened to plain arrays the
+// way the worker boundary does), so module-level coercion covers the plain-array-literal
+// case without changing any object's identity.
+export function wrapModuleForCoercion(m) {
+    if (m == null || (typeof m !== 'object' && typeof m !== 'function')) {
+        return m;
+    }
+    const wrappedFns = new Map();
+    const moduleProxy = new Proxy(m, {
+        get(target, prop) {
+            const member = Reflect.get(target, prop);
+            if (typeof member !== 'function') {
+                return member; // HEAP*, FS, typed arrays and other data pass through raw
+            }
+            let wrapped = wrappedFns.get(prop);
+            if (!wrapped) {
+                wrapped = new Proxy(member, {
+                    apply(fn, thisArg, args) {
+                        return callWithVectorCoercion(
+                            fn,
+                            unwrapCoercionProxy(thisArg),
+                            args.map(unwrapCoercionProxy),
+                        );
+                    },
+                    construct(Class, args) {
+                        return constructWithVectorCoercion(Class, args.map(unwrapCoercionProxy));
+                    },
+                });
+                wrappedFns.set(prop, wrapped);
+            }
+            return wrapped;
+        },
+    });
+    coercionProxies.set(moduleProxy, m);
+    return moduleProxy;
+}