@crossbind/plugin-metro 2.0.0-beta.62 → 2.0.0-beta.64

package/README.md

@@ -3,7 +3,7 @@
 A tool for seamless C++ integration with the Metro bundler.
 
 <a href="https://www.npmjs.com/package/@crossbind/plugin-metro">
-    <img alt="NPM version" src="https://img.shields.io/npm/v/@crossbind/plugin-metro?style=for-the-badge" />
+    <img alt="NPM version" src="https://img.shields.io/npm/v/@crossbind/plugin-metro/beta?style=for-the-badge" />
 </a>
 <a href="https://github.com/crossbind/crossbind/blob/main/LICENSE">
     <img alt="License" src="https://img.shields.io/github/license/crossbind/crossbind?style=for-the-badge" />
@@ -20,15 +20,15 @@ To integrate crossbind into your project using Metro as a bundler, you can utili
 
 NPM
 ```sh
-npm install @crossbind/plugin-metro --save-dev
+npm install @crossbind/plugin-metro@beta --save-dev
 ```
 or YARN
 ```sh
-yarn add @crossbind/plugin-metro --dev
+yarn add @crossbind/plugin-metro@beta --dev
 ```
 or PNPM
 ```sh
-pnpm add @crossbind/plugin-metro --save-dev
+pnpm add @crossbind/plugin-metro@beta --save-dev
 ```
 or BUN
 ```sh
@@ -73,3 +73,25 @@ const config = getDefaultConfig(__dirname);
 -module.exports = config;
 +module.exports = mergeConfig(config, newConfig);
 ```
+
+## Web
+On Expo's web platform the plugin compiles the C++ to WebAssembly, the build the Vite plugin makes: single-threaded unless `crossbind.config.js` sets `target.runtime: 'mt'`.
+
+Metro resolves imports against the files it found when it started, so the Conan packages and cargo builds the web build needs are staged first:
+```sh
+npx crossbind-metro prepare-web
+npx expo start --web
+```
+
+`expo start --web` builds the wasm when the page first loads and serves it from the dev server. A multithreaded build also gets the `Cross-Origin-Opener-Policy` and `Cross-Origin-Embedder-Policy` headers it needs there. Metro does not watch the C++ sources; reload the page after an edit to rebuild.
+
+`expo export` runs nothing after the bundle, so a web export takes a last command, which links the release wasm into the export:
+```sh
+npx crossbind-metro prepare-web
+npx expo export -p web --clear
+npx crossbind-metro export-web dist
+```
+
+Host `dist` as any static site (with `web.output: 'server'`, pass `dist/client`). A multithreaded build also needs `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` from the host.
+
+If your Metro config sets `server.enhanceMiddleware`, set it before passing the config to `CrossbindMetroPlugin`, which chains it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossbind/plugin-metro",
-  "version": "2.0.0-beta.62",
+  "version": "2.0.0-beta.64",
   "description": "crossbind Metro plugin: A tool for seamless C++ integration with the Metro bundler.",
   "homepage": "https://github.com/crossbind/crossbind/tree/main/plugins/metro#readme",
   "repository": {
@@ -9,12 +9,15 @@
   },
   "license": "MIT",
   "main": "src/metro-plugin.cjs",
+  "bin": {
+    "crossbind-metro": "src/cli.cjs"
+  },
   "peerDependencies": {
     "metro": "*",
     "@babel/core": "^7.0.0"
   },
   "dependencies": {
-    "crossbind": "^2.0.0-beta.62",
+    "crossbind": "^2.0.0-beta.64",
     "@babel/runtime": "^7.29.7",
     "@react-native/metro-babel-transformer": "^0.87.1",
     "upath": "^3.0.8"

package/src/cli.cjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+const fs = require('node:fs');
+const path = require('node:path');
+const { WEB_FILES, requireWebTargets, buildWebGlue } = require('./web.cjs');
+
+const USAGE = 'usage: crossbind-metro prepare-web\n       crossbind-metro export-web [output-dir]';
+
+// Metro resolves imports against the files it found when it started, so the Conan packages and cargo
+// builds a web bundle needs are staged before `expo start --web` or `expo export`, as build_js.js
+// stages them before the native bundles.
+async function prepareWeb() {
+    const crossbind = await import('crossbind');
+    const { targetParams, release: target } = requireWebTargets(crossbind);
+    await crossbind.buildDependencies({ targetParams: { ...targetParams, buildType: [target.buildType] } });
+}
+
+// Expo's export copies public/ before Metro bundles and runs nothing after it, so the wasm the web
+// bundle boots is linked here, from the bridges that bundling wrote, and put next to the bundle.
+async function exportWeb(outputDir) {
+    const crossbind = await import('crossbind');
+    const { targetParams, release: target } = requireWebTargets(crossbind);
+    await buildWebGlue(crossbind, targetParams, target);
+    fs.mkdirSync(outputDir, { recursive: true });
+    WEB_FILES.forEach(({ name, output, isOptional }) => {
+        const filePath = `${crossbind.state.config.paths.build}/${target[output]}`;
+        if (isOptional && !fs.existsSync(filePath)) return;
+        fs.copyFileSync(filePath, path.join(outputDir, name));
+    });
+    console.log(`crossbind: linked ${target.path} into ${outputDir}`);
+    if (target.runtime === 'mt') {
+        console.log(`crossbind: ${outputDir} holds a multithreaded build; serve it with Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp.`);
+    }
+}
+
+const [command, outputDir = 'dist'] = process.argv.slice(2);
+const COMMANDS = {
+    'prepare-web': () => prepareWeb(),
+    'export-web': () => exportWeb(outputDir),
+};
+if (command === '--help' || command === '-h') {
+    console.log(USAGE);
+} else if (!Object.hasOwn(COMMANDS, command ?? '')) {
+    console.error(USAGE);
+    process.exitCode = 1;
+} else {
+    // Reported as the crossbind CLI reports a failure: one line, the whole stack with DEBUG=1.
+    COMMANDS[command]().catch((error) => {
+        const cause = error?.cause?.message ? `\n  caused by: ${error.cause.message.split('\n')[0]}` : '';
+        console.error(process.env.DEBUG ? error : `${error?.message ?? error}${cause}`);
+        process.exitCode = 1;
+    });
+}

package/src/metro-plugin.cjs

@@ -1,12 +1,63 @@
+const fs = require('node:fs');
 const path = require('node:path');
+const { pipeline } = require('node:stream/promises');
+const { WEB_FILES, getWebTargets, buildWebGlue } = require('./web.cjs');
 
-let getDependFilePathFunc;
-let crossbindState;
-import('crossbind').then(({ getDependFilePath, state }) => {
-    getDependFilePathFunc = getDependFilePath;
-    crossbindState = state;
+let crossbind;
+const crossbindPromise = import('crossbind').then((module) => {
+    crossbind = module;
 });
 
+// A web page load asks for the glue first, so serving it is where a changed source or a newly
+// imported header gets linked in. Requests that arrive meanwhile (a pthread pool's) share the build,
+// and the wasm and data wait for it instead of reading what it is still writing.
+let inFlightBuild = null;
+
+async function serveWebFile({ targetParams, debug: target }, file, res) {
+    if (file.name === 'crossbind.js') {
+        inFlightBuild = inFlightBuild || buildWebGlue(crossbind, targetParams, target).finally(() => { inFlightBuild = null; });
+    }
+    await inFlightBuild;
+    // A page reloaded during the build has gone; piping a file to its response would leak the handle.
+    if (res.destroyed) return;
+    const filePath = `${crossbind.state.config.paths.build}/${target[file.output]}`;
+    if (!fs.existsSync(filePath)) {
+        res.statusCode = 404;
+        res.end();
+        return;
+    }
+    res.setHeader('Content-Type', file.contentType);
+    await pipeline(fs.createReadStream(filePath), res);
+}
+
+function createWebMiddleware(middleware) {
+    return (req, res, next) => {
+        crossbindPromise.then(() => {
+            const webTargets = getWebTargets(crossbind);
+            if (webTargets?.debug.runtime === 'mt') {
+                // A multithreaded wasm needs SharedArrayBuffer, which only a cross-origin isolated page has.
+                res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
+                res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
+            }
+            // The boot code asks under Expo's experiments.baseUrl, which need not be the root.
+            const pathname = req.url.split('?')[0];
+            const file = webTargets && req.method === 'GET' && WEB_FILES.find(({ name }) => pathname.endsWith(`/${name}`));
+            if (!file) {
+                return middleware(req, res, next);
+            }
+            return serveWebFile(webTargets, file, res).catch((error) => {
+                // A page that reloads mid-download closes the response; nothing failed.
+                if (error.code === 'ERR_STREAM_PREMATURE_CLOSE') return;
+                console.error(error);
+                if (res.headersSent || res.destroyed) return;
+                res.statusCode = 500;
+                res.setHeader('Content-Type', 'text/plain');
+                res.end(error.message);
+            });
+        }).catch(next);
+    };
+}
+
 module.exports = function CrossbindMetroPlugin(defaultConfig) {
     // Generated proxy modules (e.g. a cargo package's lib.rs) originate in package workspaces
     // outside the app's node_modules chain, so their bare imports (react-native, @babel/runtime,
@@ -32,9 +83,11 @@ module.exports = function CrossbindMetroPlugin(defaultConfig) {
                 // The `crossbind` import above resolves asynchronously; until it lands (and for
                 // platforms with no matching target) fall back to Metro's default resolution
                 // instead of dereferencing undefined state.
-                if (crossbindState && getDependFilePathFunc) {
-                    const target = crossbindState.targets.find((t) => t.platform === platform);
-                    const dependFilePath = target && getDependFilePathFunc(moduleName, target);
+                if (crossbind) {
+                    const target = platform === 'web'
+                        ? getWebTargets(crossbind)?.release
+                        : crossbind.state.targets.find((t) => t.platform === platform);
+                    const dependFilePath = target && crossbind.getDependFilePath(moduleName, target);
                     if (dependFilePath) {
                         return context.resolveRequest(context, dependFilePath, platform);
                     }
@@ -47,5 +100,13 @@ module.exports = function CrossbindMetroPlugin(defaultConfig) {
             ...defaultConfig.transformer,
             babelTransformerPath: require.resolve('./metro-transformer.cjs'),
         },
+        server: {
+            ...defaultConfig.server,
+            // Expo's dev server serves the web app, and the wasm its bundle boots is served from here.
+            // Metro deprecates enhanceMiddleware, but Expo still builds its middleware stack from it.
+            enhanceMiddleware: (metroMiddleware, metroServer) => createWebMiddleware(
+                defaultConfig.server?.enhanceMiddleware?.(metroMiddleware, metroServer) ?? metroMiddleware,
+            ),
+        },
     };
 };

package/src/metro-transformer.cjs

@@ -1,4 +1,7 @@
  
+const path = require('node:path');
+const { getWebTargets, requireWebTargets } = require('./web.cjs');
+
 const upstreamTransformer = (() => {
     try {
         return require('@expo/metro-config/babel-transformer');
@@ -15,33 +18,48 @@ let compilerClassPromise;
 const getCompilerClass = () => {
     if (compilerClassPromise) return compilerClassPromise;
     compilerClassPromise = new Promise((resolve, reject) => {
-        import('crossbind').then(({ state, getCrossbindScript, getRustJsScript, createBridgeFile }) => {
-            resolve({ state, getCrossbindScript, getRustJsScript, createBridgeFile });
+        import('crossbind').then(({
+            state, getCrossbindScript, getRustJsScript, createBridgeFile, getTargetParams, getFilteredBuildTargets, bindHeaderImports,
+        }) => {
+            resolve({
+                state, getCrossbindScript, getRustJsScript, createBridgeFile, getTargetParams, getFilteredBuildTargets, bindHeaderImports,
+            });
         }).catch((e) => reject(e));
     });
     return compilerClassPromise;
 };
 
 module.exports.transform = async ({ src, filename, ...rest }) => {
-    const { state, getCrossbindScript, getRustJsScript, createBridgeFile } = await getCompilerClass();
+    const crossbind = await getCompilerClass();
+    const { state, getCrossbindScript, getRustJsScript, createBridgeFile } = crossbind;
+    const file = path.resolve(rest.options.projectRoot ?? '', filename);
     const headerRegex = new RegExp(`\\.(${state.config.ext.header.join('|')})$`);
     const moduleRegex = new RegExp(`\\.(${state.config.ext.module.join('|')})$`);
     if (headerRegex.test(filename) || moduleRegex.test(filename) || filename.endsWith('.rs')) {
         let target;
         if (rest.options.platform === 'ios') target = state.targets.find((t) => t.platform === 'ios');
         else if (rest.options.platform === 'android') target = state.targets.find((t) => t.platform === 'android');
-        else target = state.targets.find((t) => t.platform === 'wasm');
+        else target = requireWebTargets(crossbind).release;
+        // Expo serves a web app under experiments.baseUrl, and the boot code asks for its wasm there.
+        const base = `${rest.options.customTransformOptions?.baseUrl ?? ''}/`;
 
         // Rust surfaces need no bridge file here: the native bridge is the package's generated
         // companion crate; this only emits the JS proxy module (same shape as the .h flow).
         if (filename.endsWith('.rs')) {
-            return upstreamTransformer.transform({ src: getRustJsScript(target, filename), filename, ...rest });
+            return upstreamTransformer.transform({ src: getRustJsScript(target, filename, { base }), filename, ...rest });
         }
 
-        const bridgeFile = createBridgeFile(filename, target);
+        const bridgeFile = createBridgeFile(file, target);
 
-        return upstreamTransformer.transform({ src: getCrossbindScript(target, bridgeFile), filename, ...rest });
+        // Only a dev server keeps a header's module while the app's imports change: Xcode and Gradle bundle a release
+        // from a cleared cache.
+        return upstreamTransformer.transform({ src: getCrossbindScript(target, bridgeFile, { base, liveExports: rest.options.dev }), filename, ...rest });
     }
 
+    const appTarget = ['ios', 'android'].includes(rest.options.platform)
+        ? state.targets.find((t) => t.platform === rest.options.platform)
+        : getWebTargets(crossbind)?.release;
+    if (appTarget) crossbind.bindHeaderImports(src, file, appTarget);
+
     return upstreamTransformer.transform({ src, filename, ...rest });
 };

package/src/web.cjs

@@ -0,0 +1,48 @@
+// The files the web bundle's boot code asks for, each one a build output of the web target.
+const WEB_FILES = [
+    { name: 'crossbind.js', output: 'jsName', contentType: 'text/javascript' },
+    { name: 'crossbind.wasm', output: 'wasmName', contentType: 'application/wasm' },
+    { name: 'crossbind.data.txt', output: 'dataTxtName', contentType: 'text/plain', isOptional: true },
+];
+
+// The build the Vite, webpack and Rollup plugins make for a browser: single-threaded unless
+// crossbind.config.js sets target.runtime to 'mt'. Null when the config leaves no such target.
+function getWebTargets({ getTargetParams, getFilteredBuildTargets }) {
+    const targetParams = getTargetParams({
+        platform: ['wasm'], arch: ['wasm32'], runtime: ['st'], runtimeEnv: ['browser'],
+    }, true);
+    const release = getFilteredBuildTargets(targetParams, { buildType: 'release' })[0];
+    const debug = getFilteredBuildTargets(targetParams, { buildType: 'debug' })[0];
+    if (!release && !debug) return null;
+    return { targetParams, release: release ?? debug, debug: debug ?? release };
+}
+
+function requireWebTargets(crossbind) {
+    const webTargets = getWebTargets(crossbind);
+    if (!webTargets) {
+        throw new Error('crossbind: crossbind.config.js leaves no wasm32 browser target to build the web app with.');
+    }
+    return webTargets;
+}
+
+// Metro transforms the .h imports in worker processes, so their bridges are read from the build
+// directory, as the native builds read them.
+async function buildWebGlue(crossbind, targetParams, target) {
+    const {
+        state, buildDependencies, isSourceNewer, createLib, getAllBridges, buildWasm,
+    } = crossbind;
+    await buildDependencies({ targetParams: { ...targetParams, buildType: [target.buildType] } });
+    const force = isSourceNewer(target);
+    const sourceBuilt = createLib(target, 'Source', { force, buildSource: true });
+    const bridgeBuilt = createLib(target, 'Bridge', {
+        force,
+        buildSource: false,
+        nativeGlob: [`${state.config.paths.cli}/assets/cpp-runtime/commonBridges.cpp`, ...getAllBridges()],
+    });
+    // A rebuilt lib must force the final link, or the wasm keeps the stale registrations.
+    await buildWasm(target, { force: force || Boolean(sourceBuilt) || Boolean(bridgeBuilt) });
+}
+
+module.exports = {
+    WEB_FILES, getWebTargets, requireWebTargets, buildWebGlue,
+};