|
| 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