[aron-cf]

Replaces #293. Closes the main part of #297. Based on #293's branch, so it includes Ben's stack until that lands.

Today a host module can only return JSON. To give code an object, like a job or a page, you write two modules: flat host functions over IDs, and source in the isolate that builds the objects back up. createCodemodeModule() makes that one module. Its objects keep working after a pause or a deploy.

Returning objects

import { createCodemodeModule } from "@cloudflare/computer";

const jobs = createCodemodeModule({ description: "Build jobs: `createJob(name)` returns a job." });

const Run = jobs.define("Run", ({ id }) => ({
  wait: async (_args, ctx) => api.wait(id, { signal: ctx.signal }),
}));

const Job = jobs.define("Job", ({ id }) => ({
  start: async ([ref], ctx) => Run({ id: await api.start(id, ref, { key: ctx.callId }) }),
}));

modules: {
  "codemode:jobs": jobs.module({
    createJob: async ([name], ctx) => Job({ id: await api.create(name, { key: ctx.callId }) }),
  }),
}

import { createJob } from "codemode:jobs";

const job = await createJob("build");
const run = await job.start("main");
await approval();                    // the run can pause here, across a deploy
const { status } = await run.wait(); // still works, and nothing ran twice

Run({ id }) builds the object and remembers { id }. After a restart, the backend calls the same builder with { id } to get it back. The one rule: an object is whatever its state rebuilds.

Shared context

context(name, create) adds ctx[name] to every function and method in the module. It's made once, when the backend connects.

jobs.context("api", (host) => createJobsClient(host));

const Job = jobs.define("Job", ({ id }) => ({
  start: async ([ref], { api, callId }) => Run({ id: await api.start(id, ref, { key: callId }) }),
}));

State for one run

Add { scoped: true } to get a fresh value for each scope of a run. It starts the first time a method reads it, so ctx.session is a promise. It's disposed when the run pauses or ends.

const browser = createCodemodeModule();

browser.context(
  "session",
  (scope) => browsers.connect({ conversation: scope.metadata.conversation }),
  {
    scoped: true,
    async dispose(session, end) {
      await session.close();
      if (end.reason !== "paused") end.log("Closed the browser.\n");
    },
  },
);

const Page = browser.define("Page", ({ pageId }) => ({
  text: async (_args, ctx) => (await ctx.session).page(pageId).text(),
}));

modules: {
  "codemode:browser": browser.module({
    open: async ([url], ctx) => Page({ pageId: await (await ctx.session).open(String(url)) }),
  }),
}

Objects read context when they're called, not when they're built. So after a resume, Page just works against the new session.

Richer values and errors

A codemode module can use Date, bigint, byte arrays, Headers and errors in any run, including replayable ones. Errors keep their name and their own properties.

schedule: async ([when]) => {
  if (when < new Date()) {
    throw Object.assign(new RangeError("That's in the past"), { code: "EPAST", earliest: new Date() });
  }
  return { at: when, id: 2n ** 64n };
},

try {
  await schedule(new Date(0));
} catch (error) {
  error instanceof RangeError; // true, live and on replay
  error.earliest;              // a Date
}

Callbacks, streams and live stubs

In runs that don't replay, Workers RPC carries these as they are:

watch: async ([onEvent], ctx) => {
  for await (const event of deploys.events({ signal: ctx.signal })) await onEvent(event);
},
logs: async ([id]) => deploys.logStream(id),          // a ReadableStream
room: async ([name]) => env.ROOMS.get(env.ROOMS.idFromName(String(name))), // a live stub

A replayable run refuses them, since the journal can't keep them yet.

Releasing early

const run = await job.start("main");
await run.wait();
await run[Symbol.asyncDispose](); // the host object's disposer runs with reason "disposed"

Rules

Methods	The object's own functions, called as (args, ctx).
Kinds	Named with a string, stored as codemode:jobs#Run. Don't use variable names, since minifiers change them.
State	Anything a replayable run can carry. Must rebuild the object.
Replayable runs	JSON plus Date, bigint, byte arrays, typed arrays, Headers and errors. No URL, Map, Set or RegExp.
Runs that don't replay	Anything Workers RPC carries, including callbacks, streams and live stubs.
One module per builder	Calling module() twice throws, unless the builder has a name.

Plain host modules and factories don't change. Codemode modules are experimental.

---

Implementation

No new transport. A method on an object is just a host call named host/<ref>.<method>, like host/codemode:jobs#3:0.start. It goes through the existing bridge.call(), with the same limits, journal and replay ordering as any other call.

Refs and proxies. When a result holds a defined object, the bridge swaps it for a marker and lists it as { ref, kind, state }. A ref is the module, the journal seq of the call that made it, and its place in the result. The journal keeps the state. The isolate only gets the ref, and turns it into a Proxy whose methods are host calls. A scope that only replayed an object rebuilds it from its state the first time it's called live. Refs the bridge didn't issue or replay are refused, and so are objects from another module.

Journal values. Plain JSON keeps the journal's old format and call keys, so existing journals read and match as before. Anything richer is stored with Cap'n Web's serialize(), behind a NUL-prefixed marker. We only use its encoding, not a session. Cap'n Web refuses functions, stubs and streams, which is the rule a replayable run needs. Workers RPC also has to carry the value to the isolate, which rules out URL.

Lifecycle. This takes #293's scope lifecycle and drops its API. Started scoped contexts and live objects with a disposer go into the record's instances, and close together when the scope ends, with #293's reasons, deadline and log(). createScopedModule() never shipped, so it's removed, along with its export list and its "functions don't match exports" check.

Also in this PR

• Bumps capnweb to ^0.12.0 in packages/computer and packages/rpc.
• Fixes a byte array in a codemode result being copied as a plain object.
• Updates the replay digest test. REPLAY_VERSION stays, since the new isolate code only acts on responses that list objects or carry error names and properties, which no older journal has.

---

[changeset-bot]

🦋 Changeset detected

Latest commit: 79ed36e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@cloudflare/computer	Minor
@cloudflare/computer-rpc	Minor
@cloudflare/dofs	Minor
@cloudflare/computerd	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@cloudflare/computer@301

commit: 79ed36e