capsite/toybox: OCapN vats; createVat takes remote objects

The admin socket now also speaks OCapN over Cap'n Web: a WebSocket there
reaches the VatAdmin DO, an OCapN peer whose bootstrap (swissnum
vatAdmin) offers createVat(src, params). params may hold remote objects;
the vat's root comes back as one.

Each OCapN vat is its own peer: SES and @endo/ocapn run in its facet
(vat-runtime.js, bundled with esbuild), around the vat's own module,
which exports buildRootObject(vatPowers, params). Passing a client's
object to a vat, or a vat's root to the client, is an OCapN handoff, so
the receiver dials the exporter. Nothing here can dial out, so the
VatAdmin is also the router: a client registers its gateway under a
designator, a vat's designator is its id, and every peer reaches every
other through it. The netlayer is ertp-clerk's, made to work over Workers
RPC stubs and plain promises as well as Cap'n Web.

Not yet: sturdyrefs that survive a restart, an adminNode, and grants
(egress, mount) for OCapN vats. App vats (export class App) still work
beside them.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

toybox/test/lockdown.js

@@ -0,0 +1,10 @@
+// @endo/init/debug.js, but with `overrideTaming: 'moderate'`: Node 24's
+// undici assigns `message` to its errors (ClientDestroyedError when a
+// WebSocket closes), which 'min' makes a TypeError.
+import '@endo/init/pre-remoting.js';
+
+lockdown({
+  errorTaming: 'unsafe',
+  overrideTaming: 'moderate',
+  domainTaming: 'unsafe',
+});

toybox/test/ocapn.test.js

@@ -0,0 +1,68 @@
+/** @file OCapN vats: a client on the admin socket creates a vat and passes it a remote object. */
+import { mkdir, mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { after, before, test } from "node:test";
+import assert from "node:assert/strict";
+import { E, Far } from "@endo/far";
+import { makeClient, swissnumFromBytes } from "@endo/ocapn";
+import { newWebSocketRpcSession } from "capnweb";
+import WebSocket from "ws";
+import { locationOf, makeRpcNetLayer } from "../netlayer.js";
+import { freePort, here, startWorkerd } from "./workerd.js";
+
+const vatSrc = (name) => readFile(join(here, "vats", name), "utf8");
+
+/**
+ * An OCapN client on the admin socket: registers its own gateway with the
+ * router there, and reaches every other peer through it.
+ *
+ * @param {string} adminSock
+ * @param {string} designator
+ */
+const connectClient = async (adminSock, designator) => {
+	const ws = new WebSocket(`ws+unix:${adminSock}:/`);
+	await new Promise((resolve, reject) => (ws.once("open", resolve), ws.once("error", reject)));
+	const session = newWebSocketRpcSession(ws);
+	const ocapn = makeClient({ debugLabel: designator, verbose: !!process.env.OCAPN_LOG });
+	const netlayer = await ocapn.registerNetlayer(
+		makeRpcNetLayer({ designator, openGateway: (d) => session.gateway(d) }),
+	);
+	await session.register(designator, netlayer.gateway);
+	const vatAdmin = await ocapn.enlivenSturdyRef(
+		ocapn.makeSturdyRef(locationOf("vatAdmin"), swissnumFromBytes(new TextEncoder().encode("vatAdmin"))),
+	);
+	return { vatAdmin, close: () => (ocapn.shutdown(), ws.close()) };
+};
+
+let dir, server, client;
+
+before(async () => {
+	dir = await mkdtemp(join(tmpdir(), "toybox-ocapn-"));
+	await mkdir(join(dir, "state"));
+	const port = await freePort();
+	server = await startWorkerd(
+		"config.capnp",
+		[
+			"-s", `http=127.0.0.1:${port}`, "-s", `admin=unix:${join(dir, "admin.sock")}`,
+			"-d", `state=${join(dir, "state")}`, "-e", `switchboard=unix:${join(dir, "no-switchboard.sock")}`,
+		],
+		{ port, host: "127.0.0.1" },
+		[join(dir, "admin.sock")],
+	);
+	client = await connectClient(join(dir, "admin.sock"), "client-1");
+});
+
+after(async () => {
+	client?.close();
+	await server?.stop();
+	await rm(dir, { recursive: true, force: true });
+});
+
+test("createVat passes a remote object in; the vat's root comes back", async () => {
+	const carol = Far("carol", { greet: (name) => `hi ${name}, from carol` });
+	const { id, root } = await E(client.vatAdmin).createVat(await vatSrc("greeter.js"), { carol });
+	assert.match(id, /^[0-9a-f]{64}$/);
+	assert.equal(await E(root).hello(), "hello from the vat");
+	assert.equal(await E(root).greetVia("vat"), "hi vat, from carol");
+});

toybox/test/vat.test.js

@@ -1,34 +1,14 @@
 /** @file toybox end to end: a real workerd, an admin socket, a public port, a switchboard with two handles. */
-import { spawn } from "node:child_process";
 import { mkdir, mkdtemp, readFile, rm } from "node:fs/promises";
 import { createServer as createHttpServer, request } from "node:http";
-import { connect, createServer } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { after, before, test } from "node:test";
 import assert from "node:assert/strict";
 import { WebSocketServer } from "ws";
-
-const here = new URL("..", import.meta.url).pathname;
-// the package binary, not the .bin shim: the shim forks it, so a kill would orphan workerd
-const workerd = join(here, "node_modules/workerd/bin/workerd");
+import { freePort, here, startWorkerd } from "./workerd.js";
 const app = (name) => readFile(join(here, "apps", name), "utf8");
 
-const freePort = () =>
-	new Promise((resolve) => {
-		const s = createServer().listen(0, "127.0.0.1", () => {
-			const { port } = s.address();
-			s.close(() => resolve(port));
-		});
-	});
-
-/** Resolves once something accepts connections at `opts` (a port or a socket path). */
-const accepting = (opts) =>
-	new Promise((resolve) => {
-		const s = connect(opts, () => (s.end(), resolve(true)));
-		s.on("error", () => resolve(false));
-	});
-
 /**
  * The admin socket: holding it is the authority to create and upgrade vats.
  *
@@ -67,31 +47,6 @@ const makePublic = (base) => ({
 	put: async (pathAndQuery, src) => (await fetch(`${base}${pathAndQuery}`, { method: "PUT", body: src })).status,
 });
 
-/**
- * Run workerd on `config` until `stop()`; resolves once `listening` accepts.
- *
- * @param {string} config
- * @param {string[]} args socket, directory, and external overrides
- * @param {{ port: number } | { path: string }} listening
- * @param {string[]} stale socket files a crash leaves behind; bind() would fail on them
- */
-const startWorkerd = async (config, args, listening, stale = []) => {
-	for (const f of stale) await rm(f, { force: true });
-	const child = spawn(workerd, ["serve", "--experimental", join(here, config), ...args], {
-		stdio: ["ignore", "ignore", "pipe"],
-	});
-	let log = "";
-	child.stderr.on("data", (c) => (log += c));
-	const exited = new Promise((resolve) => child.on("exit", resolve));
-	for (let i = 0; i < 100; i++) {
-		// SIGKILL: a crash is the harder durability test
-		if (await accepting(listening)) return { stop: () => (child.kill("SIGKILL"), exited) };
-		await new Promise((r) => setTimeout(r, 50));
-	}
-	child.kill("SIGKILL");
-	throw new Error(`workerd did not start: ${log}`);
-};
-
 /** An HTTP server that answers GET with "plain ok", echoes WebSocket messages, and counts requests. */
 const startEcho = async () => {
 	let hits = 0;

toybox/test/workerd.js

@@ -0,0 +1,51 @@
+/** @file Run real workerd processes for tests. */
+import { spawn } from "node:child_process";
+import { rm } from "node:fs/promises";
+import { connect, createServer } from "node:net";
+import { join } from "node:path";
+
+export const here = new URL("..", import.meta.url).pathname;
+// the package binary, not the .bin shim: the shim forks it, so a kill would orphan workerd
+const workerd = join(here, "node_modules/workerd/bin/workerd");
+
+export const freePort = () =>
+	new Promise((resolve) => {
+		const s = createServer().listen(0, "127.0.0.1", () => {
+			const { port } = s.address();
+			s.close(() => resolve(port));
+		});
+	});
+
+/** Resolves once something accepts connections at `opts` (a port or a socket path). */
+export const accepting = (opts) =>
+	new Promise((resolve) => {
+		const s = connect(opts, () => (s.end(), resolve(true)));
+		s.on("error", () => resolve(false));
+	});
+
+/**
+ * Run workerd on `config` until `stop()`; resolves once `listening` accepts.
+ *
+ * @param {string} config
+ * @param {string[]} args socket, directory, and external overrides
+ * @param {{ port: number } | { path: string }} listening
+ * @param {string[]} stale socket files a crash leaves behind; bind() would fail on them
+ */
+export const startWorkerd = async (config, args, listening, stale = []) => {
+	for (const f of stale) await rm(f, { force: true });
+	const child = spawn(workerd, ["serve", "--experimental", join(here, config), ...args], {
+		stdio: ["ignore", process.env.WORKERD_LOG ? "inherit" : "ignore", "pipe"],
+	});
+	let log = "";
+	// WORKERD_LOG=1 echoes workerd's stderr, for debugging
+	child.stderr.on("data", (c) => (process.env.WORKERD_LOG ? process.stderr.write(c) : (log += c)));
+	const exited = new Promise((resolve) => child.on("exit", resolve));
+	for (let i = 0; i < 100; i++) {
+		// SIGKILL: a crash is the harder durability test
+		if (await accepting(listening)) return { stop: () => (child.kill("SIGKILL"), exited) };
+		await new Promise((r) => setTimeout(r, 50));
+	}
+	child.kill("SIGKILL");
+	throw new Error(`workerd did not start: ${log}`);
+};
+