Re-design exec interface

[aron-cf]

Reaching a Workspace from a Worker used to go through a reduced stub. It could run a command and wait for the result, but it could not stream output and it did nothing to protect against shell injection. Callers built commands by pasting values into a string, so a name like x; rm -rf / broke out of its argument, and every example grew its own quoting helper to work around it. The durable object that owned the Workspace had the full surface, so the two sides had drifted apart.

This change gives both sides one interface. getWorkspace is a single front door that returns the same client whether you hand it the durable object itself or the object's stub from a Worker.

// From a Worker, against the durable object stub.
using ws = await getWorkspace(env.MyDO.get(id));

// From inside the durable object that owns the Workspace.
using ws = await getWorkspace(this);

The durable object opts in by extending a mixin. It constructs the Workspace and installs the accessor getWorkspace needs, so there is no hand-written method to maintain.

export class MyDO extends withWorkspace(
  class extends DurableObject<Env> {},
  (self) => ({ storage: self.ctx.storage, backends: [/* ... */] }),
) {}

Commands are now escaped by default. shell.exec takes a tagged template that quotes every interpolated value, so a hostile input stays inside its argument.

const file = "my notes.md";
await ws.shell.exec`cat ${file}`;        // runs: cat 'my notes.md'
await ws.shell.exec`echo ${untrusted}`;  // the value can't break out

The plain form still exists for when you need options, and the sh tag is exported so you can escape a command you pass to it.

await ws.shell.exec("npm test", { cwd: "/workspace", encoding: "utf8" });
await ws.shell.exec(sh`cat ${file}`, { cwd: "/workspace" });

The escaping runs on the caller's side on purpose. When a command crosses the boundary to the durable object it travels as a plain value, and a tagged template's raw text is lost in transit, so escaping there would be too late. Building the finished string in the caller is the only place it can happen safely, and the remote stub rejects a raw tagged-template call so the unescaped path can never run by accident.

The same client can now stream a command's output from a Worker, not just wait for its result. Workers RPC carries byte streams but not arbitrary object streams, so the event stream is framed as newline-delimited JSON on the durable-object side and rebuilt into the familiar handle on the Worker side.

for await (const event of await ws.shell.exec`npm test`) {
  if (event.name === "stdout") process.stdout.write(event.value);
}

// Or wait for the whole run.
const { exitCode, stdout } = await (await ws.shell.exec`npm test`).result();

Streaming and waiting for the result are mutually exclusive on a single handle, matching how the in-process handle already behaves. The stream is only started when you actually read from it, so a caller that only wants the result never pays for it.

flowchart LR
  W["Worker: getWorkspace(stub)"] -->|"exec command"| DO["Durable Object"]
  DO -->|"JSON lines over byte stream"| W
  W -->|"rebuilt into events"| C["for await (event of handle)"]

Loading

To verify locally, run the workspace tests, which cover the escaping, the wire codec round trip including binary and multi-byte output, and both the local and remote client paths:

npm test --workspace @cloudflare/workspace

The artifacts example is updated to the new surface: it extends the mixin, reaches the workspace through getWorkspace, and builds its commands with the sh tag instead of a local quoting helper. The shell interface guide and the package README are updated to describe getWorkspace, the tagged template, and why escaping runs caller-side.

The client's passthrough members for the filesystem, git, assets, and artifacts are typed loosely today because the local and remote surfaces are different concrete types. Unifying them behind one declared interface is a good follow-up now that the shape has settled. The new streaming path has unit and integration coverage but has not been run through the long-lived stub-disposal soak harness, which needs a real container; that is worth running before release.

[ndisidore]

Wow I like this a lot more! And very nice to see interface unification efforts.
Happy to give this a review once you're satisfied with to move it out of draft

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/workspace/@cloudflare/workspace@13

commit: 33ffd43