feat(js-sdk): run the full unit test suite in Cloudflare workerd (#1593)

## What

Promotes `test:cf` from a single dist smoke test to the **full unit +
connectionConfig suite running inside Cloudflare's workerd**
(`@cloudflare/vitest-pool-workers`) — the same coverage `test:bun` and
`test:deno` get. Locally: **74 files / 393 tests green** against prod
sandboxes. The real-deploy suite (`test:cf:deploy`) is unchanged and
keeps covering the built bundle on actual Cloudflare infrastructure (the
pool can't reproduce bundling bugs like #1579).

## SDK fixes the suite surfaced

1. **Dropped-connection mapping for Workers** (`src/envd/rpc.ts`):
workerd surfaces a sandbox connection drop as `Network connection lost`,
which fell through to a cryptic `SandboxError`. It's now matched like
the Node/Bun/Deno variants, so killing a sandbox mid-request surfaces as
the health-checked `TimeoutError`:

   ```ts
const cmd = await sandbox.commands.run('sleep 60', { background: true })
   await sandbox.kill()
await cmd.wait() // now rejects with TimeoutError('…sandbox was killed
or reached its end of life…') on Workers too
   ```

2. **Double connection release on stream cancel**
(`src/connectionConfig.ts`): `wrapStreamWithConnectionCleanup` claimed
its `release` was idempotent but had no guard — cancelling a streamed
download while a read was in flight ran `cleanup()` twice (both the
`cancel` callback and the pending `pull` resolving `done` fire).
workerd's stream scheduling hits this deterministically; the pooled
connection was double-released.

Both are runtime-behavior fixes specific to the JS fetch/streams stack —
no Python SDK equivalent applies.

## Test adjustments

- **boot_id reads** in the two "filesystem-only pause" tests now use
`commands.run('cat …')` instead of `files.read`: envd's non-gzip
download path serves procfs files as an empty 200 (filed as
e2b-dev/infra#3363 — Go `ServeContent` sizes them by stat, which is 0).
Only clients that don't negotiate gzip (workerd's fetch) observe it; the
command path sidesteps the bug while keeping the reboot assertion on all
runtimes.
- **runtime.test.ts** Node-host detection scenarios skip under workerd
via the existing host guard (same treatment as Bun/Deno).
- **Pool config filters expected unhandled-rejection shapes** via
vitest's `onUnhandledError` (not the blanket
`dangerouslyIgnoreUnhandledErrors`): workerd reports a rejection as
unhandled unless a handler attaches within the same microtask drain —
even inline `await expect(op()).rejects` trips it — and vitest never
processes the `rejectionhandled` retraction on any runtime, so the
suite's deliberate rejections false-positive ~60× per run. A diagnostic
pairing `unhandledrejection` with `rejectionhandled` confirmed all of
them are handled-late false positives (zero genuine leaks). The filter
drops only the shapes the tests provoke (SDK error classes,
`ConnectError`, `AbortError`, workerd's `Network connection lost.`, one
test stub); unknown rejection shapes and uncaught exceptions still fail
the run — verified with a planted never-handled `TypeError` (exit 1).

## CI

Rebased onto #1588's per-runtime matrix: the `cloudflare` leg (already
ubuntu-only there) now runs the full suite; no extra jobs added. The
stale `tests/integration` exclude was dropped after #1591 removed that
suite.

## Notes

- Suite config needs `nodejs_compat_populate_process_env` +
`E2B_API_KEY`/`E2B_DOMAIN` miniflare bindings so the SDK and tests read
env like on Node.
- The deleted `tests/runtimes/cloudflare/run.test.ts` (dist smoke) is
fully subsumed: lifecycle coverage by the suite, bundle coverage by
`test:cf:deploy` + `tests/bundle/edgeCompat.test.ts`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: mishushakov

.changeset/cf-workers-connection-fixes.md

@@ -0,0 +1,5 @@
+---
+'e2b': patch
+---
+
+Recognize Cloudflare Workers' `Network connection lost` as a dropped sandbox connection so a sandbox killed mid-request surfaces as the health-checked `TimeoutError` (matching Node/Bun/Deno), and fix streaming downloads releasing their pooled connection twice when cancelled while a read was in flight

.github/workflows/js_sdk_tests.yml

@@ -86,8 +86,8 @@ jobs:
           path: ${{ matrix.os == 'windows-latest' && '~/AppData/Local/ms-playwright' || '~/.cache/ms-playwright' }}
           key: playwright-${{ runner.os }}-${{ steps.playwright-version.outputs.version }}
 
-      # Every suite needs dist/: the unit bundle test and both Cloudflare
-      # configs fail in CI when the build output is missing.
+      # The unit bundle test and the Cloudflare deploy config fail in CI when
+      # the build output is missing.
       - name: Test build
         run: pnpm build
 
@@ -122,7 +122,8 @@ jobs:
           E2B_API_KEY: ${{ secrets.E2B_API_KEY }}
           E2B_DOMAIN: ${{ inputs.E2B_DOMAIN }}
 
-      - name: Run Cloudflare Workers tests
+      # Full unit + connectionConfig suite inside workerd (vitest-pool-workers).
+      - name: Run test suite under Cloudflare workerd
         if: matrix.runtime == 'cloudflare'
         run: pnpm test:cf
         env:

packages/js-sdk/src/connectionConfig.ts

@@ -295,8 +295,15 @@ export function wrapStreamWithConnectionCleanup(
   const reader = body.getReader()
   const idle = createIdleAbort(controller, idleTimeoutMs, 'Stream')
 
-  // Idempotent: safe to call from multiple stream callbacks.
+  // Idempotent: safe to call from multiple stream callbacks — cancelling
+  // while a pull is in flight settles both paths (the pending read resolves
+  // `done` after `reader.cancel()`), which must not release twice.
+  let released = false
   const release = () => {
+    if (released) {
+      return
+    }
+    released = true
     idle.clear()
     cleanup()
   }

packages/js-sdk/src/envd/rpc.ts

@@ -25,14 +25,16 @@ export type SandboxHealthCheck = () => Promise<boolean | undefined>
  * is dropped mid-request. The transport surfaces a dropped connection (e.g. an
  * HTTP/2 stream reset) with runtime- and version-specific wording, so we match
  * every known variant:
- *   - Node (undici): `terminated`
- *   - Bun:           `The socket connection was closed unexpectedly`
- *   - Deno:          `error reading a body from connection`
+ *   - Node (undici):       `terminated`
+ *   - Bun:                 `The socket connection was closed unexpectedly`
+ *   - Deno:                `error reading a body from connection`
+ *   - Cloudflare Workers:  `Network connection lost`
  */
 const CONNECTION_TERMINATED_MESSAGES = [
   'terminated',
   'The socket connection was closed unexpectedly',
   'error reading a body from connection',
+  'Network connection lost',
 ]
 
 /**

packages/js-sdk/tests/envd/handleEnvdApiError.test.ts

@@ -125,6 +125,7 @@ describe('handleEnvdApiFetchError', () => {
     Node: new TypeError('terminated'),
     Bun: new Error('The socket connection was closed unexpectedly'),
     Deno: new TypeError('error reading a body from connection'),
+    'Cloudflare Workers': new Error('Network connection lost.'),
   }
 
   for (const [runtime, error] of Object.entries(runtimeTerminatedErrors)) {

packages/js-sdk/tests/envd/handleRpcError.test.ts

@@ -69,6 +69,7 @@ describe('handleRpcErrorWithHealthCheck', () => {
     Node: 'terminated',
     Bun: 'The socket connection was closed unexpectedly',
     Deno: 'error reading a body from connection',
+    'Cloudflare Workers': 'Network connection lost.',
   }
 
   test('returns a TimeoutError when the health check says the sandbox is not running', async () => {

packages/js-sdk/tests/runtime.test.ts

@@ -1,11 +1,13 @@
 import { afterEach, expect, test, vi } from 'vitest'
 
-// The unit project also runs under Bun (and prospectively Deno), where the
-// host runtime's own unstubbable marker (globalThis.Bun / globalThis.Deno)
-// correctly wins detection — these scenarios only exist on a Node host.
+// The unit project also runs under Bun, Deno, and Cloudflare's workerd, where
+// the host runtime's own unstubbable marker (globalThis.Bun / globalThis.Deno /
+// the Cloudflare-Workers user agent) correctly wins detection — these
+// scenarios only exist on a Node host.
 const isNodeHost =
   typeof (globalThis as any).Bun === 'undefined' &&
-  typeof (globalThis as any).Deno === 'undefined'
+  typeof (globalThis as any).Deno === 'undefined' &&
+  (globalThis as any).navigator?.userAgent !== 'Cloudflare-Workers'
 
 afterEach(() => {
   vi.unstubAllGlobals()

packages/js-sdk/tests/runtimes/cloudflare/run.test.ts

@@ -1,36 +1,43 @@
-import { existsSync } from 'node:fs'
-import path from 'node:path'
-import { fileURLToPath } from 'node:url'
-
 import { cloudflareTest } from '@cloudflare/vitest-pool-workers'
 import { config } from 'dotenv'
 import { defineConfig } from 'vitest/config'
 
 const env = config()
 
-// The suite smoke-tests the built ESM bundle (what Workers users consume),
-// so dist must exist. Skip locally to keep plain `vitest` runs green, but
-// fail loudly in CI where the build step is expected to have run.
-const distEntry = path.resolve(
-  path.dirname(fileURLToPath(import.meta.url)),
-  '../../../dist/index.mjs'
-)
-const hasDist = existsSync(distEntry)
-
-if (!hasDist) {
-  const message =
-    'dist/index.mjs not found — run `pnpm build` in packages/js-sdk before running the Cloudflare Workers tests'
-  if (process.env.CI) {
-    throw new Error(message)
-  }
-  console.warn(`Skipping Cloudflare Workers tests: ${message}`)
-}
+// Error names thrown by src/errors.ts (plus CommandExitError) — the shapes
+// this suite's rejection tests expect. Kept as a literal list so an unknown
+// error class still fails the run instead of being silently ignored.
+const SDK_ERROR_NAMES = new Set([
+  'SandboxError',
+  'TimeoutError',
+  'InvalidArgumentError',
+  'NotEnoughSpaceError',
+  'NotFoundError',
+  'FileNotFoundError',
+  'SandboxNotFoundError',
+  'AuthenticationError',
+  'GitAuthError',
+  'GitUpstreamError',
+  'TemplateError',
+  'RateLimitError',
+  'BuildError',
+  'FileUploadError',
+  'VolumeError',
+  'CommandExitError',
+])
 
+// Runs the unit + connectionConfig projects (same coverage as test:bun /
+// test:deno) inside Cloudflare's workerd via vitest-pool-workers, against src.
+// The real-deploy suite (tests/runtimes/cloudflare-deploy) keeps covering the
+// built bundle on actual Cloudflare infrastructure.
 export default defineConfig({
   plugins: [
     cloudflareTest({
       miniflare: {
         compatibilityDate: '2026-03-01',
+        // nodejs_compat is a hard requirement for the SDK on Workers. It also
+        // mirrors the bindings below into process.env (default since compat
+        // date 2025-04-01), which is how tests and the SDK read E2B_*.
         compatibilityFlags: ['nodejs_compat'],
         bindings: {
           E2B_API_KEY: process.env.E2B_API_KEY ?? env.parsed?.E2B_API_KEY ?? '',
@@ -41,8 +48,43 @@ export default defineConfig({
   ],
   test: {
     name: 'cloudflare',
-    include: hasDist ? ['tests/runtimes/cloudflare/**/*.test.ts'] : [],
-    passWithNoTests: !hasDist,
+    include: ['tests/**/*.test.ts'],
+    exclude: [
+      'tests/runtimes/**',
+      'tests/template/**',
+      // Inspects the host-built dist/index.mjs via node:fs, which workerd's
+      // virtual filesystem can never see (and throws in CI when the file is
+      // "missing"); the Node unit project keeps running it.
+      'tests/bundle/**',
+    ],
+    globals: false,
     testTimeout: 30_000,
+    bail: 0,
+    // workerd reports a rejection as unhandled unless a handler is attached
+    // within the same microtask drain, and vitest never processes the
+    // rejectionhandled retraction, so rejections the tests DO handle (the
+    // `await expect(p).rejects` pattern, including inline ones — workerd also
+    // flags intermediate promises of the async-function chain) false-positive
+    // ~60 times per run. Instead of dangerouslyIgnoreUnhandledErrors, drop
+    // only the rejection shapes these tests deliberately provoke; uncaught
+    // exceptions and any unknown rejection shape still fail the run.
+    onUnhandledError(error) {
+      const message = String(error.message ?? '')
+      const expectedRejection =
+        error.type === 'Unhandled Rejection' &&
+        // SDK public errors — what `expect(p).rejects` asserts on.
+        (SDK_ERROR_NAMES.has(error.name) ||
+          // The transport errors the SDK wraps: connect-rpc failures and
+          // aborted requests surface on intermediate promises too.
+          error.name === 'ConnectError' ||
+          message.startsWith('ConnectError:') ||
+          error.name === 'AbortError' ||
+          // workerd's teardown error for in-flight streams when a test kills
+          // the sandbox mid-request.
+          message === 'Network connection lost.' ||
+          // Stub rejection from tests/sandbox/git/validation.test.ts.
+          message === 'commands.run should not be called')
+      if (expectedRejection) return false
+    },
   },
 })

packages/js-sdk/tests/runtimes/cloudflare/vitest.config.mts

@@ -79,9 +79,13 @@ test.skipIf(isDebug)(
     try {
       const marker = 'auto-pause-fs-only'
       await sandbox.files.write('/home/user/auto-pause-marker.txt', marker)
+      // Read via a command, not files.read: envd's non-gzip download path
+      // serves procfs files as an empty 200 (it sizes them by stat, which is
+      // 0), so clients that don't negotiate gzip — like workerd's fetch —
+      // silently get '' (infra#3363).
       const bootBefore = (
-        await sandbox.files.read('/proc/sys/kernel/random/boot_id')
-      ).trim()
+        await sandbox.commands.run('cat /proc/sys/kernel/random/boot_id')
+      ).stdout.trim()
 
       await wait(5_000)
 
@@ -97,8 +101,8 @@ test.skipIf(isDebug)(
       assert.equal(persisted, marker)
 
       const bootAfter = (
-        await sandbox.files.read('/proc/sys/kernel/random/boot_id')
-      ).trim()
+        await sandbox.commands.run('cat /proc/sys/kernel/random/boot_id')
+      ).stdout.trim()
       assert.notEqual(bootAfter, bootBefore)
     } finally {
       await sandbox.kill().catch(() => {})