crossbind 2.0.0-beta.60 → 2.0.0-beta.63

package/src/utils/remoteOutputs.js

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { hostPathOf, isDeclaredOutput, modeOf } from '../runner/files.js';
+
+// Where a file the runner hands back may land: below an output root the step declared, and in a store
+// unit only when this machine does not hold it yet. `present` lists those units per mount.
+export function outputTarget(mounts, present, containerPath) {
+    const target = hostPathOf(mounts, containerPath);
+    if (!isDeclaredOutput(target.rel, target.mount.outputRoots, present[mounts.indexOf(target.mount)])) {
+        throw new Error(`crossbind: the remote runner returned ${containerPath}, which is not an output of this step.`);
+    }
+    return target;
+}
+
+// A link inside the project must not carry a write or a delete out of it.
+function assertStaysInside(target) {
+    fs.mkdirSync(target.mount.host, { recursive: true });
+    const root = fs.realpathSync(target.mount.host);
+    let dir = path.dirname(target.file);
+    while (!fs.existsSync(dir)) dir = path.dirname(dir);
+    const real = fs.realpathSync(dir);
+    if (real !== root && !real.startsWith(`${root}${path.sep}`)) {
+        throw new Error(`crossbind: ${target.file} leads out of ${target.mount.host} through a link, so the remote runner's output stays unwritten.`);
+    }
+}
+
+export function writeOutputFile(target, data, mode) {
+    assertStaysInside(target);
+    fs.mkdirSync(path.dirname(target.file), { recursive: true });
+    // A link at the output's own path is replaced, never written through.
+    if (fs.lstatSync(target.file, { throwIfNoEntry: false })?.isSymbolicLink()) fs.rmSync(target.file);
+    fs.writeFileSync(target.file, data);
+    fs.chmodSync(target.file, modeOf(mode));
+}
+
+export function removeOutputFile(target) {
+    assertStaysInside(target);
+    fs.rmSync(target.file, { force: true });
+}

package/src/utils/remoteRunner.js

@@ -0,0 +1,97 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DOCKER_BASE } from './replaceBasePathForDocker.js';
+import { remoteVariables } from './selectRunner.js';
+
+const CLIENT = fileURLToPath(new URL('./remoteClient.js', import.meta.url));
+
+// Only native inputs travel to the runner; the application's JavaScript and credential files stay on the
+// machine. A cargo target folder stays on the runner, and only the static libraries crossbind links come back from it.
+export const REMOTE_EXCLUDE_RULES = Object.freeze({
+    dirs: Object.freeze(['node_modules', '.git']),
+    files: Object.freeze(['.env', '.env.*', '.npmrc', '.yarnrc', '.yarnrc.yml', '.netrc']),
+    extensions: Object.freeze(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.jsx', '.tsx']),
+    serverOnly: Object.freeze({ names: Object.freeze(['target', 'target-mt']), marker: 'Cargo.toml', keep: Object.freeze(['*/release/*.a']) }),
+});
+
+const TOKEN_VARIABLE = 'CROSSBIND_TOKEN';
+
+const LOOPBACK = /^(localhost|127(\.\d{1,3}){3}|\[::1\])$/;
+const warnedUrls = new Set();
+
+// Plain http to another machine carries the token and the sources unencrypted.
+function warnIfPlainHttp(url) {
+    const { protocol, hostname } = new URL(url);
+    if (protocol !== 'http:' || LOOPBACK.test(hostname) || warnedUrls.has(url)) return;
+    warnedUrls.add(url);
+    console.warn(`crossbind: ${url} is plain http to another machine - the token and your sources travel unencrypted; put TLS in front of the runner.`);
+}
+
+const isInside = (rel, root) => root === '.' || rel === root || rel.startsWith(`${root}/`);
+
+// Null for a folder outside the base: a local docker run mounts only the base, so it never sees one either.
+function relativeToBase(base, folder) {
+    const rel = path.relative(base, folder);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) return null;
+    return rel.split(path.sep).join('/') || '.';
+}
+
+function foldNested(roots) {
+    const unique = [...new Set(roots)].sort((a, b) => a.length - b.length);
+    return unique.filter((root, i) => !unique.slice(0, i).some((outer) => isInside(root, outer)));
+}
+
+// A file the command line names may include its neighbours (`#include "../include/x.h"`), so unless a
+// configured folder holds it, the package that holds it travels: the nearest folder below the base with a
+// package.json. Its JavaScript stays behind, as everywhere else.
+function packageOf(base, configured, file) {
+    if (configured.some((root) => isInside(relativeToBase(base, file), root))) return file;
+    for (let dir = path.dirname(file); ![null, '.'].includes(relativeToBase(base, dir)); dir = path.dirname(dir)) {
+        if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
+    }
+    return file;
+}
+
+// What a toolchain step may read (inputRoots) and where it writes (outputRoots), relative to paths.base,
+// the folder a local docker run mounts. `extraInputs` are only read (a file the link names);
+// `extraOutputs` are read and written, like a crate's folder and its Cargo.lock.
+export function remoteRoots(config, { extraInputs = [], extraOutputs = [] } = {}) {
+    const { paths, allDependencies = [] } = config;
+    const relOf = (folder) => relativeToBase(paths.base, folder);
+    const isBelowBase = (folder) => Boolean(folder) && relOf(folder) !== null;
+    const dependencyFolders = allDependencies.flatMap((d) => [d.paths.output, ...(d.paths.native ?? []), ...(d.paths.header ?? [])]);
+    const configured = [...paths.native, ...paths.header, paths.cache, paths.output, `${paths.cli}/assets`, ...dependencyFolders].filter(isBelowBase).map(relOf);
+    const outputs = [paths.cache, paths.output, ...extraOutputs].filter(isBelowBase).map(relOf);
+    return {
+        inputRoots: foldNested([...configured, ...extraInputs.filter(isBelowBase).map((file) => relOf(packageOf(paths.base, configured, file))), ...outputs]),
+        outputRoots: foldNested(outputs),
+    };
+}
+
+export function baseMount(config, extra = {}) {
+    return { host: config.paths.base, container: DOCKER_BASE, ...remoteRoots(config, extra) };
+}
+
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+// Paths a command line names below the base (a source the link adds, an include folder, a preload file)
+// travel even when no configured folder holds them. The base itself is never one: it would send everything.
+export function referencedPaths(base, values) {
+    const pattern = new RegExp(`${escapeRegExp(base)}(?:/[^@=;:,'"\\s]*)?`, 'g');
+    const found = values.flatMap((value) => String(value).match(pattern) ?? []);
+    return [...new Set(found)].filter((candidate) => candidate !== base && fs.existsSync(candidate));
+}
+
+// Arguments for execFileSync/spawnSync: the client runs as its own process, so the caller stays
+// synchronous as it is with docker. The token reaches it through its environment, never its command line.
+export function remoteExecParams({ remote, role, image, mounts, cwd, argv, env }, options) {
+    if (!remote) {
+        throw new Error(`crossbind: RUNNER=REMOTE, but the ${role} image has no runner address - set ${remoteVariables(role).key} (or REMOTE_URL), or build with CROSSBIND_RUNNER=DOCKER_RUN. A machine that names no runner address builds on crossbind cloud after crossbind login.`);
+    }
+    const { url, token, tokenVariable } = remote;
+    if (!token) throw new Error(`crossbind: the ${role} runner at ${url} needs a token - set ${tokenVariable}.`);
+    warnIfPlainHttp(url);
+    const payload = { url, role, image, mounts, cwd, argv, env, rules: REMOTE_EXCLUDE_RULES };
+    return [process.execPath, [CLIENT, JSON.stringify(payload)], { ...options, env: { ...process.env, [TOKEN_VARIABLE]: token } }];
+}

package/src/utils/remoteUpload.js

@@ -0,0 +1,134 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Raw bytes per upload request, a batch of small files or a part of a large one. With base64 a batch stays below the
+// 32 MiB a Cloud Run request may carry, and a part below Cloudflare's 100 MB as well.
+const UPLOAD_BATCH_BYTES = 16 * 1024 * 1024;
+// The first runner protocol that joins a file sent in parts.
+const PARTS_PROTOCOL = 2;
+const MB = 1024 * 1024;
+// A long upload to a hosted runner now and then loses its connection: a request goes again this many times, waiting a
+// second longer each time.
+const UPLOAD_RETRIES = 4;
+const RETRY_DELAY_MS = 1000;
+// Failures before a connection opened, such as a name lookup that failed for a moment: the request never reached the
+// runner, so it goes again this many times. After a connection opened it never does, since a step may have started.
+const UNSENT_CODES = new Set(['ENOTFOUND', 'EAI_AGAIN', 'ECONNREFUSED', 'ENETUNREACH', 'EHOSTUNREACH', 'UND_ERR_CONNECT_TIMEOUT']);
+const UNSENT_RETRIES = 2;
+
+const wait = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); });
+
+export async function request(url, route, init = {}) {
+    const token = process.env.CROSSBIND_TOKEN;
+    const headers = { ...(token ? { authorization: `Bearer ${token}` } : {}), ...init.headers };
+    for (let attempt = 1; ; attempt += 1) {
+        try {
+            // A redirect would send the request, sources included, to an address nobody configured.
+            return await fetch(`${url}${route}`, { ...init, headers, redirect: 'error' });
+        } catch (error) {
+            if (!UNSENT_CODES.has(error.cause?.code) || attempt > UNSENT_RETRIES) {
+                throw new Error(`crossbind: the remote runner at ${url} is unreachable (${error.cause?.code ?? error.message}).`, { cause: error });
+            }
+            await wait(RETRY_DELAY_MS * attempt);
+        }
+    }
+}
+
+export async function expectOk(response, what) {
+    if (response.ok) return response.json();
+    const body = await response.json().catch(() => ({}));
+    throw new Error(`crossbind: the remote runner failed ${what}: ${body.error ?? response.status}.`);
+}
+
+async function requestWithRetries(url, route, init) {
+    for (let attempt = 1; ; attempt += 1) {
+        const response = await request(url, route, init).catch((error) => error);
+        const failed = response instanceof Error || response.status >= 500;
+        if (!failed || attempt > UPLOAD_RETRIES) {
+            if (response instanceof Error) throw response;
+            return response;
+        }
+        await wait(RETRY_DELAY_MS * attempt);
+    }
+}
+
+async function runnerProtocol(url) {
+    const health = await expectOk(await request(url, '/v1/health'), 'to answer its health check');
+    return health.protocol ?? 1;
+}
+
+// One request per part, in order; the runner checks the joined file against its hash. After a part whose connection
+// dropped, the upload goes on from where the runner says it stands. The upload is named after the file, so a later
+// attempt, or another client sending the same file, goes on with what the runner holds.
+async function uploadInParts(url, hash, file, total, partBytes) {
+    const upload = hash.slice(0, 32);
+    const fd = fs.openSync(file, 'r');
+    let resumes = 0;
+    try {
+        for (let start = 0; start < total;) {
+            const part = Buffer.alloc(Math.min(partBytes, total - start));
+            fs.readSync(fd, part, 0, part.length, start);
+            const response = await requestWithRetries(url, `/v1/blobs/${hash}`, {
+                method: 'PUT',
+                body: part,
+                headers: { 'content-range': `bytes ${start}-${start + part.length - 1}/${total}`, 'x-crossbind-upload': upload },
+            });
+            if (response.status === 413) {
+                throw new Error(`crossbind: the remote runner at ${url} took no part of ${path.basename(file)}: it refused a part of ${part.length} bytes, so the proxy in front of it takes less in one request.`);
+            }
+            if (response.status === 409 && resumes < UPLOAD_RETRIES) {
+                const { received } = await response.json();
+                if (!Number.isSafeInteger(received) || received < 0 || received >= total) throw new Error(`crossbind: the remote runner holds ${received} bytes of ${path.basename(file)}, which has ${total}.`);
+                resumes += 1;
+                start = received;
+                continue;
+            }
+            const answer = await expectOk(response, `to receive ${path.basename(file)}`);
+            if (response.status === 201) return;
+            start = answer.received;
+        }
+    } finally {
+        fs.closeSync(fd);
+    }
+}
+
+// A runner deployed before uploads in parts takes a large file in one request, which a body limit in front of it refuses.
+async function uploadWhole(url, hash, file, total) {
+    const response = await request(url, `/v1/blobs/${hash}`, { method: 'PUT', body: fs.readFileSync(file) });
+    if (response.status === 413) {
+        throw new Error(`crossbind: the remote runner at ${url} refused ${path.basename(file)} (${Math.ceil(total / MB)} MB) as too large for one request; deploy the runner again with this crossbind version, which sends large files in parts.`);
+    }
+    await expectOk(response, `to receive ${path.basename(file)}`);
+}
+
+// `sources` maps each hash to a file holding it; only what the runner lacks travels, small files in a few batches and a
+// large one on its own.
+export async function uploadMissing(url, sources, partBytes = UPLOAD_BATCH_BYTES) {
+    const listing = await request(url, '/v1/missing', { method: 'POST', body: JSON.stringify({ hashes: [...sources.keys()] }) });
+    const { missing } = await expectOk(listing, 'to list the files it lacks');
+    let protocol;
+    let batch = [];
+    let size = 0;
+    const flush = async () => {
+        if (batch.length === 0) return;
+        const body = batch.map(({ hash, data }) => JSON.stringify({ sha256: hash, data: data.toString('base64') })).join('\n');
+        await expectOk(await requestWithRetries(url, '/v1/blobs', { method: 'POST', body }), `to receive ${batch.length} files`);
+        batch = [];
+        size = 0;
+    };
+    for (const hash of missing) {
+        const file = sources.get(hash);
+        const fileSize = fs.statSync(file).size;
+        if (fileSize > partBytes) {
+            protocol ??= await runnerProtocol(url);
+            if (protocol >= PARTS_PROTOCOL) await uploadInParts(url, hash, file, fileSize, partBytes);
+            else await uploadWhole(url, hash, file, fileSize);
+            continue;
+        }
+        const data = fs.readFileSync(file);
+        if (size > 0 && size + data.length > partBytes) await flush();
+        batch.push({ hash, data });
+        size += data.length;
+    }
+    await flush();
+}

package/src/utils/replaceFile.js

@@ -0,0 +1,8 @@
+import fs from 'node:fs';
+
+// macOS keeps the code signature of a loaded binary per inode: a rebuilt addon or command copied over
+// one that already ran gets the next process that loads it killed. A new file gets a new inode.
+export default function replaceFile(source, destination) {
+    fs.rmSync(destination, { force: true });
+    fs.copyFileSync(source, destination);
+}

package/src/utils/resolveCompanionPackage.js

@@ -0,0 +1,51 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import state from '../state/index.js';
+
+// The binding runtimes ship as their own packages and the ENGINE never depends on them: the
+// consumer declares one - directly, or transitively through a platform plugin - and the engine
+// only resolves it. pnpm keeps transitive deps unhoisted, so resolution may need to hop through
+// the declaring plugin; inside this monorepo the package sits next to the engine under core/.
+export default function createCompanionResolver({
+    pkg, anchors = [], siblingDir, siblingMarker, missingMessage,
+}) {
+    let cached = null;
+
+    const resolveFrom = (baseDir) => {
+        try {
+            const req = createRequire(path.join(baseDir, 'package.json'));
+            return path.dirname(fs.realpathSync(req.resolve(`${pkg}/package.json`)));
+        } catch (e) {
+            return null;
+        }
+    };
+
+    return function resolveCompanionRoot() {
+        if (cached) return cached;
+
+        const project = state.config?.paths?.project;
+        let root = project ? resolveFrom(project) : null;
+        if (!root && project) {
+            for (const anchor of anchors) {
+                try {
+                    const req = createRequire(path.join(project, 'package.json'));
+                    const anchorDir = path.dirname(fs.realpathSync(req.resolve(`${anchor}/package.json`)));
+                    root = resolveFrom(anchorDir);
+                    if (root) break;
+                } catch (e) { /* this plugin is not installed - try the next anchor */ }
+            }
+        }
+        if (!root) {
+            const here = path.dirname(fileURLToPath(import.meta.url));
+            const sibling = path.resolve(here, '../../..', siblingDir);
+            if (fs.existsSync(`${sibling}/${siblingMarker}`)) root = sibling;
+        }
+        if (!root) {
+            throw new Error(missingMessage);
+        }
+        cached = root;
+        return root;
+    };
+}

package/src/utils/resolveEmbindNapi.js

@@ -0,0 +1,22 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import createCompanionResolver from './resolveCompanionPackage.js';
+
+const PKG = '@crossbind/core-embind-napi';
+
+const resolveEmbindNapiRoot = createCompanionResolver({
+    pkg: PKG,
+    siblingDir: 'embind-napi',
+    siblingMarker: 'cpp/src/node_api_module.cpp',
+    missingMessage: `crossbind: native Node.js builds need ${PKG} - add it to your devDependencies.`,
+});
+
+export default resolveEmbindNapiRoot;
+
+// The embind runtime itself ships in @crossbind/core-embind-jsi, a dependency of the Node-API
+// package, so it resolves from there.
+export function resolveEmbindJsiRoot() {
+    const req = createRequire(path.join(resolveEmbindNapiRoot(), 'package.json'));
+    return path.dirname(fs.realpathSync(req.resolve('@crossbind/core-embind-jsi/package.json')));
+}

package/src/utils/resolveEmbindRust.js

@@ -1,60 +1,25 @@
 import fs from 'node:fs';
-import path from 'node:path';
-import { createRequire } from 'node:module';
-import { fileURLToPath } from 'node:url';
-import state from '../state/index.js';
+import createCompanionResolver from './resolveCompanionPackage.js';
 
-// The Rust producer crate + adapters ship in @crossbind/core-embind-rust. The ENGINE never
-// depends on it (same direction rule as core-embind-jsi): the consumer declares it - directly,
-// or transitively through a platform plugin - and the engine only resolves it. pnpm keeps
-// transitive deps unhoisted, so resolution may need to hop through the declaring plugin.
+// The Rust producer crate + adapters ship in @crossbind/core-embind-rust (same direction rule as
+// core-embind-jsi: the consumer declares it, the engine only resolves it).
 const PKG = '@crossbind/core-embind-rust';
-const PLUGIN_ANCHORS = [
-    '@crossbind/plugin-react-native',
-    '@crossbind/plugin-vite',
-    '@crossbind/plugin-rollup',
-    '@crossbind/plugin-metro',
-    '@crossbind/plugin-webpack',
-];
 
-let cached = null;
+const resolveEmbindRustRoot = createCompanionResolver({
+    pkg: PKG,
+    anchors: [
+        '@crossbind/plugin-react-native',
+        '@crossbind/plugin-vite',
+        '@crossbind/plugin-rollup',
+        '@crossbind/plugin-metro',
+        '@crossbind/plugin-webpack',
+    ],
+    siblingDir: 'embind-rust',
+    siblingMarker: 'crate/Cargo.toml',
+    missingMessage: `crossbind: Rust bindings need ${PKG} - add it to your (dev)dependencies.`,
+});
 
-export default function resolveEmbindRustRoot() {
-    if (cached) return cached;
-
-    const resolveFrom = (baseDir) => {
-        try {
-            const req = createRequire(path.join(baseDir, 'package.json'));
-            return path.dirname(fs.realpathSync(req.resolve(`${PKG}/package.json`)));
-        } catch (e) {
-            return null;
-        }
-    };
-
-    const project = state.config?.paths?.project;
-    let root = project ? resolveFrom(project) : null;
-    if (!root && project) {
-        for (const anchor of PLUGIN_ANCHORS) {
-            try {
-                const req = createRequire(path.join(project, 'package.json'));
-                const anchorDir = path.dirname(fs.realpathSync(req.resolve(`${anchor}/package.json`)));
-                root = resolveFrom(anchorDir);
-                if (root) break;
-            } catch (e) { /* this plugin is not installed - try the next anchor */ }
-        }
-    }
-    if (!root) {
-        // Monorepo layout: the package ships next to the engine.
-        const here = path.dirname(fileURLToPath(import.meta.url));
-        const sibling = path.resolve(here, '../../../embind-rust');
-        if (fs.existsSync(`${sibling}/crate/Cargo.toml`)) root = sibling;
-    }
-    if (!root) {
-        throw new Error(`crossbind: Rust bindings need ${PKG} - add it to your (dev)dependencies.`);
-    }
-    cached = root;
-    return root;
-}
+export default resolveEmbindRustRoot;
 
 // The package version, stamped into generated bridge manifests for debuggability.
 export function embindRustVersion() {

package/src/utils/runCargo.js

@@ -1,4 +1,4 @@
-import { spawnSync, execFileSync } from 'node:child_process';
+import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -7,6 +7,10 @@ import getOsUserAndGroupId from './getOsUserAndGroupId.js';
 import replaceBasePathForDockerUtil, { DOCKER_BASE } from './replaceBasePathForDocker.js';
 import pullDockerImage, { getDockerImage, getDockerContainerName, imageRoleFor } from './pullDockerImage.js';
 import { DOCKER_RUN_SECURITY_ARGS } from './dockerSecurity.js';
+import { HOST_BUILT_PLATFORMS } from './targets.js';
+import assertExecContainer from './execContainer.js';
+import { remoteExecParams, baseMount } from './remoteRunner.js';
+import { runnerFor } from './selectRunner.js';
 
 // Every cargo invocation crossbind makes goes through here.
 //
@@ -59,6 +63,26 @@ const CONFIG_NAMES = ['config.toml', 'config'];
 // cargo's upward config search finds nothing.
 const CONTAINER_CARGO_HOME = '/var/cache/crossbind/cargo';
 const CONTAINER_CWD = '/tmp/crossbind-cargo';
+// What the host reads out of the registry a remote runner keeps: crate sources, for bridge generation, one
+// folder per crate version or git revision.
+const REMOTE_CARGO_HOME_OUTPUTS = ['registry/src/*/*', 'git/checkouts/*/*'];
+
+// The crate a cargo call names travels whole, with every crate its `path =` dependencies reach (embind-rs,
+// the generated bridges); their target folders stay on a remote runner. A `path` naming a file ([lib]
+// path) holds no Cargo.toml and is skipped.
+function crateFolders(args) {
+    const at = args.indexOf('--manifest-path');
+    if (at === -1) return [];
+    const folders = new Set();
+    const visit = (dir) => {
+        const manifest = path.join(dir, 'Cargo.toml');
+        if (folders.has(dir) || !fs.existsSync(manifest)) return;
+        folders.add(dir);
+        for (const [, rel] of fs.readFileSync(manifest, 'utf8').matchAll(/\bpath\s*=\s*"([^"]+)"/g)) visit(path.resolve(dir, rel));
+    };
+    visit(path.dirname(path.resolve(args[at + 1])));
+    return [...folders];
+}
 
 // Crossbind-owned and machine-wide: $CARGO_HOME/config.toml is one of the discovery legs, so the
 // registry cache lives somewhere we can assert is clean instead of in the user's ~/.cargo. It is
@@ -107,12 +131,11 @@ export function assertCleanConfigChain(home, cwd) {
     }
 }
 
-// iOS links with Xcode, which is in no image, so its Rust stays on the host - as does every build
-// under RUNNER=LOCAL.
+// Apple targets link with Xcode, which is in no image, so their Rust stays on the host - as does
+// every build under RUNNER=LOCAL.
 export function cargoRunner(target) {
-    if (target?.platform === 'ios') return 'LOCAL';
-    const runner = state.config?.system?.RUNNER;
-    return runner === 'DOCKER_RUN' || runner === 'DOCKER_EXEC' ? runner : 'LOCAL';
+    const { runner } = runnerFor(imageRoleFor(target), state.config?.system);
+    return HOST_BUILT_PLATFORMS.includes(target?.platform) ? 'LOCAL' : runner;
 }
 
 function allowedEnv() {
@@ -153,52 +176,6 @@ function createHint(name, base, home, image) {
     ].join('\n');
 }
 
-function samePath(a, b) {
-    const real = (p) => {
-        try {
-            return fs.realpathSync(p);
-        } catch {
-            return path.resolve(p);
-        }
-    };
-    return real(a) === real(b);
-}
-
-function assertExecContainer(name, base, home, image) {
-    const hint = createHint(name, base, home, image);
-    let info;
-    try {
-        // stderr is dropped: docker's own "No such container" would land before the message below.
-        info = JSON.parse(execFileSync('docker', ['container', 'inspect', name], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }))[0];
-    } catch {
-        throw new Error(`crossbind: RUNNER=DOCKER_EXEC needs a container named '${name}', which does not exist.\n${hint}`);
-    }
-    if (!info?.State?.Running) {
-        throw new Error(
-            `crossbind: the container '${name}' exists but is not running. Start it with \`docker start ${name}\`, or recreate it.\n${hint}`,
-        );
-    }
-    for (const [destination, source] of [
-        [DOCKER_BASE, base],
-        [CONTAINER_CARGO_HOME, home],
-    ]) {
-        const mount = (info.Mounts ?? []).find((m) => m.Destination === destination);
-        if (!mount || !samePath(mount.Source, source)) {
-            const found = mount ? ` - it mounts ${mount.Source} there` : '';
-            throw new Error(
-                `crossbind: the container '${name}' does not mount ${source} at ${destination}${found}. It predates the cargo mount, so recreate it.\n${hint}`,
-            );
-        }
-    }
-    // `docker run --workdir` creates the directory; `docker exec --workdir` does not, and cargo
-    // dies with an OCI "chdir to cwd" error that names nothing the user can act on.
-    try {
-        execFileSync('docker', ['exec', '--user', getOsUserAndGroupId(), name, 'mkdir', '-p', CONTAINER_CWD], { stdio: 'ignore' });
-    } catch (e) {
-        throw new Error(`crossbind: could not create the working directory ${CONTAINER_CWD} inside '${name}'.\n${hint}`, { cause: e });
-    }
-}
-
 export default function runCargo(args, { cwd, rustflags = [], panic, capture = false, maxBuffer, allowUnstable = false, target } = {}) {
     const home = cargoHome();
     const workdir = cwd ?? neutralCwd();
@@ -232,12 +209,33 @@ export default function runCargo(args, { cwd, rustflags = [], panic, capture = f
         panic,
         allowUnstable,
     });
+    if (runner === 'REMOTE') {
+        return spawnSync(...remoteExecParams({
+            remote: runnerFor(role, state.config.system).remote,
+            role,
+            image: getDockerImage(role, platform),
+            mounts: [
+                baseMount(state.config, { extraOutputs: crateFolders(args) }),
+                { host: home, container: CONTAINER_CARGO_HOME, inputRoots: [], outputRoots: REMOTE_CARGO_HOME_OUTPUTS },
+            ],
+            cwd: CONTAINER_CWD,
+            argv: ['cargo', ...replaceBasePathForDockerUtil(args, base)],
+            env,
+        }, options));
+    }
+
     const envArgs = Object.entries(env).flatMap(([key, value]) => ['-e', `${key}=${value}`]);
 
     let runnerArgs;
     if (runner === 'DOCKER_EXEC') {
         const name = getDockerContainerName(base, role);
-        assertExecContainer(name, base, home, getDockerImage(role, platform));
+        assertExecContainer({
+            name,
+            mounts: [[DOCKER_BASE, base], [CONTAINER_CARGO_HOME, home]],
+            workdir: CONTAINER_CWD,
+            hint: createHint(name, base, home, getDockerImage(role, platform)),
+            mountNote: 'It predates the cargo mount, so recreate it.',
+        });
         runnerArgs = ['exec', ...envArgs, '--user', getOsUserAndGroupId(), '--workdir', CONTAINER_CWD, name];
     } else {
         pullDockerImage(role, platform);