Skip to content

Commit 702861b

Browse files
committed
πŸ“ Record both backend verdicts and the two-question recommendation (#351)
Worker Shell is include-initially-scoped: it runs natively over the Deno-local workspace, reuses Cloudflare's adapter byte-identical, and its containment was measured β€” around fifty escape attempts with zero leaks and no native-execution path. Its one hazard is availability, not capability: a CPU-bound script starves the host event loop, so the boundary recommendation is a Deno Worker. Worker JavaScript is defer: the whole contract works, including an in-memory module graph with no materialization, but isolation holds only in a compiled artifact and CPU-bound user code cannot be preempted. The missing Deno primitive is named precisely. COMPARISON.md answers the two topology questions separately and states that bundled workerd is not necessary for this scope.
1 parent 20174b1 commit 702861b

2 files changed

Lines changed: 274 additions & 0 deletions

File tree

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Comparison and recommendation for #346
2+
3+
#351 completes the evidence set: #347 measured bundled `workerd`, #349 measured
4+
the Deno-local DOFS Workspace, and this spike measures what imperative
5+
execution the Deno-local topology can carry on its own. The topology decision
6+
has two separate questions.
7+
8+
## Question 1 β€” is Deno-local DOFS sufficient for the declarative durable core?
9+
10+
**Yes, on the evidence available.** The core the workflow needs is a durable,
11+
coherent, identity-scoped filesystem, and #349 proved each property directly:
12+
Cloudflare's unmodified DOFS schema over a file-backed `node:sqlite` adapter,
13+
surviving full process restarts (including deletions and replacements),
14+
isolating workspaces by database path, refusing a newer on-disk schema rather
15+
than recreating it, and checkpointing to a single-file artifact on close β€” at
16+
110 MB and 0.08 s per operation, in one process with no supervision surface.
17+
18+
The declarative components map onto primitives that already exist in that
19+
layer: `<Dir>` onto `mkdir`, `<File>` onto `writeFile`/`readFile`, and
20+
`<Branch>`/`<Commit>` onto DOFS's own git support, which Cloudflare drives
21+
through the same filesystem (their `git` shell command is a thin shim over it).
22+
This spike does not implement those components, per its scope; it confirms the
23+
substrate exposes the operations they need, and that a host capability and an
24+
imperative backend observe the same committed state in both directions
25+
**[test]**.
26+
27+
The one caveat carried forward from #349: real FUSE β€” needed only for arbitrary
28+
native subprocesses, which `xmd workflow` does not require β€” is blocked
29+
in-process by a Deno uv-polyfill gap, and the userspace shim is development-only.
30+
Neither bears on the declarative core.
31+
32+
## Question 2 β€” which imperative capabilities can safely layer on top?
33+
34+
**Worker Shell: include initially, scoped.** It runs natively, reuses
35+
Cloudflare's adapter byte-identical, and its containment was measured rather
36+
than assumed β€” ~50 escape attempts, zero leaks, no native-execution path at
37+
all. Two conditions: run it inside a Deno Worker so a CPU-bound script cannot
38+
starve the host (the measured hazard: 6.4 s of wall time with the abort timer
39+
never firing), and describe it accurately as a workspace-scoped interpreter
40+
with 83 built-ins, never as native command execution.
41+
42+
**Worker JavaScript: defer.** The full contract works β€” in-memory module graph
43+
with no materialization, live-streamed output, capability access to DOFS,
44+
returned values, errors, timeouts, cancellation β€” and it is genuinely useful.
45+
But isolation holds only in a compiled artifact (a `deno run` host lets a
46+
"locked" worker import `jsr:`/`npm:`), and CPU-bound user code cannot be
47+
preempted at all. Since it is an optional extension over a declarative core,
48+
the cost of shipping it now exceeds its value; revisit when Deno offers a CPU
49+
or wall budget on `new Worker(...)`, or accept an out-of-process worker and its
50+
startup cost.
51+
52+
## Is bundled `workerd` still necessary?
53+
54+
**Not for this scope.** #347's decisive advantage was that it runs Cloudflare's
55+
real backends; this spike shows both of those execution models also run
56+
natively in Deno over the same workspace, at a fraction of the weight β€” 139.7 MB
57+
carrying *both* backends and DOFS, versus 191 MB for the workerd host, with
58+
operations in tens of milliseconds rather than tenths of a second, and no child
59+
process to supervise.
60+
61+
`workerd` remains the only option for the things this topology deliberately
62+
does not provide: Cloudflare Containers, the hosted Workers surface (KV, R2,
63+
Queues, Durable Object identity), and behavior guaranteed to match deployed
64+
Cloudflare. If those enter scope, #347's evidence stands ready; they are not
65+
required by the declarative workflow core.
66+
67+
## Recommendation
68+
69+
1. **Adopt** the Deno-local DOFS topology for the declarative durable workflow
70+
core.
71+
2. **Include** Worker Shell initially, scoped: inside a Deno Worker, described
72+
as a workspace-scoped interpreter, with unsupported operations refused
73+
explicitly.
74+
3. **Defer** Worker JavaScript until the preemption gap is resolved or an
75+
out-of-process cost is accepted.
76+
4. **Omit** bundled `workerd` from the local topology, keeping #347 as the
77+
documented path if hosted-Cloudflare fidelity or Containers become
78+
requirements.
79+
80+
The final selection is recorded on #346; these spikes supply the evidence, not
81+
the decision.
Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# Evidence: Worker Shell and Worker JavaScript in Deno (#351)
2+
3+
Measured on macOS 15 (Darwin 25.5.0, arm64), Deno 2.9.1, against
4+
cloudflare/computer `v0.1.1` (`63d363632e558f7e077794988d36ed75017c2a62`) and
5+
`[email protected]`, on 2026-08-06. Claims marked **[test]** are asserted by
6+
`tests/`; **[measured]** were observed directly; **[probe]** carry their
7+
command-by-command ledger in `probes/`.
8+
9+
Both backends are **optional imperative extensions** over the declarative
10+
durable core. Neither is a prerequisite for the Deno-local DOFS topology, and
11+
neither backend's limits reject it.
12+
13+
## Verdicts
14+
15+
| Backend | Verdict | Basis |
16+
| --- | --- | --- |
17+
| **Worker Shell** | **include initially, scoped** | Runs natively; containment is architectural and was measured, not inferred; one availability hazard needs a boundary decision |
18+
| **Worker JavaScript** | **defer** | The full contract works, but isolation depends on shipping compiled, and CPU-bound user code cannot be preempted |
19+
20+
## Worker Shell
21+
22+
Cloudflare's shell is the `just-bash` interpreter plus a filesystem adapter.
23+
The adapter is vendored **byte-identical** (sha1
24+
`c9ec5356d60ee7bc9aa3c5677320bf8c9aa4058c`) β€” it has zero `cloudflare:*`
25+
imports, and its filesystem contract is a structural interface rather than an
26+
RPC stub, which is the entire reason the backend ports. Everything Cloudflare
27+
wraps around it β€” `WorkerEntrypoint`, `env.HOST.getWorkspace()`, the Dynamic
28+
Worker loader β€” exists to reach a filesystem across an isolate boundary, and
29+
is unnecessary when the workspace is in-process. The only new code is a
30+
~60-line shim supplying `exists`/`statOrNull`/`lstatOrNull`, which on
31+
Cloudflare come from the RPC stub.
32+
33+
**Works** **[test]**: a host `API.Fs` write is visible to shell execution and a
34+
shell write is visible to the host, each across a full process restart;
35+
pipelines, redirection (`>`, `>>`), exit status (`$?`, explicit `exit N`),
36+
environment variables, cwd, stdout/stderr separation, and unknown-command
37+
errors all behave; separate database paths are separate workspaces.
38+
39+
**Command set** **[probe]**: 83 registered built-ins (`cat`, `grep`, `sed`,
40+
`awk`, `find`, `sort`, `tr`, `cut`, `head`, `tail`, `wc`, `cp`, `mv`, `rm`,
41+
`mkdir`, `chmod`, `test`, …). This is an interpreter, **not** a process
42+
launcher: there is no PATH resolution and no native executable can run
43+
(`/bin/sh`, `id`, `uname` are all `command not found`) **[test]**. Absent:
44+
`trap`, `yes`, `xargs -n`. Worker-backed commands (`js-exec`, `sqlite3`) need a
45+
one-line `process.connected` prelude under Deno; `python3` remains unusable.
46+
47+
**Security β€” measured, not inferred** **[probe]**. With canaries planted on the
48+
host filesystem and in the environment, ~50 escape attempts produced **zero
49+
leaks**:
50+
51+
- Filesystem: `/etc/passwd`, `../../..` traversal, `find /`, `grep -r /` all
52+
resolve inside DOFS only; writes to `/tmp` and `/etc` land in the DOFS
53+
namespace and no host file was created **[test]**.
54+
- Environment: fabricated (`OSTYPE=linux-gnu` on macOS, `uid=1000`, `pid=1`);
55+
the host environment is invisible.
56+
- Native execution: none exists. The QuickJS `child_process.execSync` shim β€”
57+
the one plausible path β€” re-enters just-bash itself.
58+
- QuickJS guest: no `Deno`, `Function` constructor blocked, `import("node:fs")`
59+
blocked, `require("fs")` is a workspace-scoped shim, `Atomics`/`WebAssembly`
60+
undefined.
61+
- Network: off by default; when opted in, a strict prefix allowlist plus
62+
private/loopback rejection plus DNS-rebinding pinning β€” cloud-metadata IPs
63+
and `localhost` are denied even when allowlisted.
64+
65+
**Defense-in-depth**: just-bash ships its own `DefenseInDepthBox`, and
66+
Cloudflare disables it because workerd cannot register ESM loader hooks. Under
67+
Deno it must *also* be disabled: it is on by default and hard-fails
68+
(`critical patches failed: Module._load`), aborting every exec. So the same
69+
one-line opt-out Cloudflare already ships is required here β€” **and the
70+
containment above holds without it**, because it is architectural: an injected
71+
filesystem, a fabricated environment, and an interpreter with no process
72+
launcher.
73+
74+
**The one real hazard is availability, not capability** **[probe]**. just-bash
75+
executes synchronously: a 6.4 s CPU-bound loop starved the host event loop to
76+
0 ticks of an expected 127 β€” the abort timer never fired, so `AbortSignal`
77+
cancellation only works where the interpreter already awaits, and `while true`
78+
spun 56 s at 102 % CPU unrecoverably. The in-isolate brake is
79+
`maxCommandCount` (default 10 000).
80+
81+
**Boundary recommendation**: run the shell in a Deno Worker with the filesystem
82+
as an async RPC proxy. The DOFS handle cannot cross (`structuredClone` β†’
83+
`DataCloneError`), but the adapter's Promise-returning methods tolerate RPC
84+
**unmodified** β€” 10/10 functional parity including symlinks, `chmod`, `sed -i`,
85+
`grep -r`. Cost: 39.6 ms boot, ~0.04 ms per call (`echo` 0.27 ms vs 0.30 ms
86+
in-isolate). Benefit: the host stays responsive and `worker.terminate()`
87+
reclaims a wedged loop that is otherwise unrecoverable. The committed proof
88+
runs in-isolate, which is why the hazard is stated rather than hidden.
89+
90+
## Worker JavaScript
91+
92+
Upstream's `WorkspaceRuntimeLoader` is Cloudflare's Worker Loader binding:
93+
`load({ mainModule, modules })` over an in-memory specifier→source map. The
94+
port replaces it with a Deno Worker.
95+
96+
**Module supply, without materialization** **[probe]**. A relative
97+
`import "./dep.js"` does not resolve from a `blob:` or `data:` base β€” Deno
98+
reports `invalid URL: relative URL with a cannot-be-a-base base`. Rewriting
99+
each specifier to the dependency's absolute blob URL, in topological order,
100+
loads the graph and survives `deno compile`. Static import maps are inherited
101+
by workers but there is no per-Worker `importMap` option, so they cannot carry
102+
a runtime-generated map. **Temp-dir materialization was never needed**, so its
103+
coherence and cleanup costs are avoided rather than measured.
104+
105+
**Works** **[test]**: an entry module with a dependency runs in the isolate,
106+
reaches DOFS through the capability bridge, separates stdout and stderr,
107+
returns a result, and its write is committed β€” readable by a later process.
108+
A thrown error becomes stderr plus exit 1 without failing the host. Output is
109+
live-streamed, not batched (frames at 6/410/812 ms) **[probe]**. Cold
110+
spawn→exit 13 ms; capability round-trip 0.065 ms **[measured]**.
111+
112+
**Isolation is adequate only in the compiled artifact** β€” the decisive caveat.
113+
`permissions: "none"` governs Deno *ops*, not the *module loader*: under
114+
`deno run`, a locked worker still executes `import("jsr:…")`/`import("npm:…")`,
115+
pulling arbitrary third-party code and network egress that `net: false` does
116+
not stop; the `import: false` permission is inert. `deno compile`'s frozen
117+
graph closes this β€” `jsr:`/`npm:`/`https:` all become `Module not found`.
118+
Host files and the environment are denied in both **[test]**. **A `deno run`
119+
host must never be presented as a sandbox.**
120+
121+
**Two gaps** **[probe]**:
122+
123+
1. `Worker.terminate()` cannot preempt CPU-spinning user JavaScript. The
124+
timeout *outcome* is correct (1507 ms for a 1500 ms budget) but
125+
`terminate()` returns in 0 ms while the thread runs on, permanently
126+
blocking process exit. The missing primitive is Deno-side: **a CPU or wall
127+
budget on `new Worker(...)`, or a `terminate()` that interrupts running
128+
JavaScript**. Cloudflare's `limits.cpuMs` has no equivalent. The only
129+
faithful fix is an out-of-process worker that can be SIGKILLed, which
130+
forfeits the 13 ms cold start.
131+
2. `compatibilityDate`/`compatibilityFlags` and retained execution
132+
(`getExec`/`resume`) are not expressible; a Deno Worker's lifetime is bounded
133+
by the host call. Upstream's shell backend has no retention either, so this
134+
only distances the JavaScript backend from hosted Cloudflare.
135+
136+
## Explicit refusal, never fallback
137+
138+
An operation the host does not install fails where it is called, at both
139+
refusal points **[test]**: an operation the runner exposes but the host did not
140+
install reports `unsupported filesystem op: <name>`, and one outside the
141+
capability surface fails as `not a function`. The isolate has no path to host
142+
execution, so there is nothing to fall back to β€” the property workflow mode
143+
requires holds by construction.
144+
145+
## Compatibility matrix
146+
147+
| Dimension | Worker Shell (Deno) | Worker JavaScript (Deno) | Cloudflare (both, #347) |
148+
| --- | --- | --- | --- |
149+
| Execution | 83 interpreter built-ins; no native processes | arbitrary user ES modules | same, in a Dynamic Worker |
150+
| Isolation | architectural (injected fs, fabricated env, no launcher) | Deno Worker; **compiled artifact only** | workerd isolate |
151+
| Filesystem coherence | in-process, immediate, bidirectional **[test]** | async capability RPC, committed **[test]** | RPC to host DO |
152+
| Streaming | buffered β€” upstream synthesizes frames after the run | live-streamed frames | same as each |
153+
| Cancellation | only at interpreter await points; CPU loops unrecoverable in-isolate | terminate() works except on CPU spin | isolate disposal |
154+
| Retention / reattach | none (upstream has none either) | none | JS backend only |
155+
| Platforms | any Deno target | any Deno target | five workerd targets |
156+
| Artifact size | 139.7 MB compiled proof (both backends + DOFS) | β€” | 191 MB (#347) |
157+
| Startup / operation | shell exec 16-22 ms; fs op 2-5 ms **[measured]** | 13 ms cold spawn; 0.065 ms per capability call | 0.27 s warm op cycle (#347) |
158+
159+
## Source reuse and licensing
160+
161+
- `WorkspaceFsAdapter` β€” vendored byte-identical, **MIT** (Cloudflare), with
162+
provenance and upgrade procedure in `vendor/worker-shell/PROVENANCE.md`.
163+
This is the narrow seam the issue asked for: one file, no broad vendoring.
164+
- `[email protected]` β€” an ordinary npm dependency, **Apache-2.0**, from
165+
`github.com/vercel-labs/just-bash` (Vercel Labs, not Cloudflare). ESM entry
166+
256 KB.
167+
- `@cloudflare/dofs` β€” the #349 vendored copy, built once and shared.
168+
- Maintenance delta versus Cloudflare: the shell tracks one vendored file plus
169+
a public npm package; the JavaScript loader is our own ~300 lines against a
170+
12-line upstream interface, so upstream loader changes do not propagate.
171+
172+
**Upstream defects found** (affect Cloudflare equally): relative symlinks are
173+
broken in `@cloudflare/dofs` itself (`ln -s t.txt link` β†’
174+
`Invalid path (must be absolute)`; absolute targets work); a redirect to a
175+
missing parent throws out of `bash.exec()` rather than returning nonzero β€” the
176+
spike wraps exec as upstream's entrypoint does; `ls -l` reports a stale mode
177+
because the adapter's `readdirWithFileTypes` carries none.
178+
179+
## Which `API.Process` semantics a Deno-local provider could claim
180+
181+
Claimable today: run a command string in a workspace-scoped shell; supply cwd
182+
and environment; receive stdout, stderr, and an exit status; run a JavaScript
183+
module graph with a workspace capability and a returned value; refuse anything
184+
unsupported explicitly.
185+
186+
**Not** claimable: arbitrary native command execution (no launcher exists);
187+
preemptive cancellation of CPU-bound work; live incremental streaming from the
188+
shell; retained or reattachable executions; POSIX process semantics such as
189+
signals, pipes to native processes, or a process table. A provider must not
190+
describe the shell backend as native command execution.
191+
192+
See [COMPARISON.md](COMPARISON.md) for the topology comparison with #347 and
193+
#349 and the recommendation for #346.

0 commit comments

Comments
Β (0)