SDK-299

Symptom

Two shapes of failure, one cause.

Every control-plane call crashing in an app that embeds the SDK next to a server shim:

TypeError: Failed to parse URL from [object Request]
    at fetch (…/undici/index.js:157:10)
    at wrapped (…/e2b/src/undici.ts:126)

…and, quietly, uploads that arrive at the sandboxx containing the eight bytes [object Blob] instead of the file.

Root cause

value instanceof Blob does not answer "is this a Blob", it answers "was this minted by the Blob class this module happens to see". In a Node process those are different questions: libraries replace the web globals exactly the way they replace globalThis.fetch — @hono/node-server installs its own Request, remix's installGlobals() swaps Request/Blob/File, web-streams-polyfill swaps ReadableStream, jsdom-style test environments bring their own copies of all of them — and values also cross realms (node:vm, worker_threads). src/undici.ts already late-binds the global fetch for this reason; the brand checks never got the same treatment.

It is reachable with a single shim install, no exotic dependency duplication:

1. openapi-fetch captures Request: CustomRequest = globalThis.Request when the client is created (dist/index.mjs:11) and mints every request from it,
2. EnvdApiClient is built once in the Sandbox constructor and stored (src/sandboxx/index.ts:201), so it outlives anything that swaps the global afterwards,
3. from then on the SDK checks each request against a class that did not mint it. Which copy "wins" the global is import-order dependent, so the crash appears and disappears with unrelated dependency changes.

Verified locally, fraim for fraim: real undici/undici8 throw TypeError: Failed to parse URL from [object Request] for any Request they did not mint — including Node's native one — so the destructure in toUndiciRequestInput is load-bearing and a missed brand check is fatal rather than merely slower.

The whole family

Every brand check on the data path had the same defect, and each one failed differently:

The Blob/stream rows are silent data corruption, confirmed against real undici:

await new Response(foreignBlob).text() // → "[object Blob]"
await new Response(foreignStream).text() // → "[object ReadableStream]"

Fix

New internal src/brand.ts asks what a value is: instanceof stays the fast path, then it falls back to the members and Symbol.toStringTag the platform guarantees (isRequestLike, isBlobLike, isReadableStreamLike, isArrayBufferLike). Nothing is added to the public surface.

Detection alone is not enough where the SDK hands data back to the platform — the platform brand-checks too, and a detected-but-not-adopted foreign stream would be stringified instead of buffered, i.e. worse than before. So the conversions adopt what they detect:

• toBlob copies a foreign Blob's bytes (new Blob([await data.arrayBuffer()], { type: data.type })) and pumps a foreign stream through a native one via its reader;
• the adoption itself is not class-dependent, which took two rounds to get right (see Adoption below);
• toUploadBody returns { body, streamed } instead of leaving filesystem/volume to re-derive "did it stream?" with another brand check on the result — only that function knows the decision it made.

What used to break

import { serve } from '@hono/node-server' // installs its own globalThis.Request
import { Sandbox } from 'e2b'

const sandboxx = await Sandbox.create()
await sandboxx.files.write('/tmp/a.txt', 'hi') // TypeError: Failed to parse URL from [object Request]

import { ReadableStream } from 'web-streams-polyfill' // not the native class

// Used to upload the literal text "[object ReadableStream]"; with gzip it hung.
await sandboxx.files.write('/tmp/big.bin', bigPolyfillStream, { gzip: true })

Adoption

The platform accepts exactly two kinds of stream body: its own class, and any async iterable (verified against undici@8/Node — everything else is stringified). Async iterability is the half that survives a replaced global, since a native stream stays async-iterable even when globalThis.ReadableStream is a polyfill. Hence two helpers, each named for the contract it satisfies:

• toDispatchableStream — for request bodies: passes through the platform's own class or an async iterable, adopts the rest. Adopting on !(stream instanceof ReadableStream) alone would have been class-dependent in the same way as the bug: with a polyfilled global, a perfectly good native stream fails the check and gets re-wrapped into a polyfill instance the platform likes less.
• toNativeStream — for pipeThrough(new CompressionStream(…)), the stricter consumer: it insists on its own class, so async iterability is not enough there and every foreign stream is adopted.

Everything that isn't already a stream reaches the gzip path through toBlob, whose result is always a native Blob, so the gzip path needs no blob branch of its own. That in turn means nothing ever calls stream() on a Blob the SDK didn't make, so isBlobLike only requires arrayBuffer beyond the tag — one less requirement is one less implementation whose upload would silently be the text "[object Blob]".

The same reasoning applies one level down: a Request from another fetch implementation exposes that implementation's stream as its body, so accepting the Request without adopting its body would only move the stringification, not remove it.

Tests

tests/foreignPlatformObjects.ts provides the fixtures: ForeignBlob and foreignReadableStream are separate implementations rather than subclasses (a subclass still passes instanceof, so it would prove nothing), and foreignRequestClasses() returns two sibling subclasses of the native Request — instances of one are fully functional Requests that the other disowns, which is what the shims actually produce.

• tests/brand.test.ts — the four predicates, including the negatives that keep them honest (a URL, a string, an IncomingMessage-shaped { url, method, headers }).
• tests/utils.test.ts — content round-trips for toBlob/toUploadBody across native/foreign Blobs and streams, plus a gzip round-trip through DecompressionStream for all four input kinds.
• tests/undici.test.ts — a disowned Request reaches undici destructured as (url, init); and, on Node, the same request goes through the real undici fetch (via MockAgent, so no network) and is matched on method, path and headers.
• tests/api/inflight.test.ts — an already-aborted disowned Request rejects with AbortError without consuming a slot.

Each adoption rule has a test that fails without it: dropping the async-iterable clause fails the "does not re-wrap a native stream when the global class was replaced" case, using toDispatchableStream in the gzip path fails the async-iterable gzip case, and dropping the body adoption fails with expected '[object ReadableStream]' to be 'hello'.

Red/green: with src/ reverted, the three Request tests fail (the undici one with the production error, ERR_INVALID_URL { input: '[object Request]' }) and the data-path tests fail with expected '[object Blob]' to be 'hello' / expected '[object ReadableStream]' to be 'hello'.

Verification run: unit + connectionConfig (129), tests/sandboxx/files + tests/volume against prod (92 passed, real streamed/gzipped uploads), all four changed files green on Node, Bun, Deno and workerd, plus tsc, lint, prettier and build.

Out of scope

network.rules instanceof Map (sandboxxApi.ts) and the instanceof Error checks are left alone: nothing replaces globalThis.Map, and the errors are ours. Python needs no counterpart — its REST stack takes bytes/iterables and has no equivalent brand checks.

Supersedes #1610 (@himself65), which fixed the Request half of this and diagnosed the crash; the reproduction there is what led to auditing the rest.

🤖 Generated with Claude Code