feat: opt-in HTTP/2 multiplexing transport via undici 7 (Node >= 20.18.1)

[dines-rl]

Summary

Adds an opt-in http2: true client option that sends Node requests over HTTP/2 with real stream multiplexing, backed by undici (Agent({ allowH2: true, connections: 4, pipelining: 64 })). Many concurrent requests share a small bounded pool of TLS sessions instead of opening one connection per request.

undici is the same engine behind Node's built-in fetch: it's require-able from this "type": "commonjs" package and returns a standard WHATWG Response, so core.ts is unchanged. No dynamic-import() hack and no second HTTP stack to keep in sync with node-fetch.

HTTP/2 stays opt-in (@default false); the default transport is still node-fetch, and a user-supplied fetch always wins. On the web and Deno the platform fetch already speaks h2, so the flag is a no-op there.

http2 accepts boolean | undici.Dispatcher: true uses the SDK's default bounded pool, or pass your own configured undici Dispatcher to control the pool yourself — the SDK uses it verbatim and manages nothing, the same contract as a custom httpAgent. This is how you tune the pool (e.g. raise connections/pipelining) for high-concurrency fan-outs without the SDK owning new knobs.

import { Agent } from 'undici';

new RunloopSDK({ http2: true });                          // default 4×64 bounded pool
new RunloopSDK({                                          // bring your own pool
  http2: new Agent({ allowH2: true, connections: 8, pipelining: 100 }),
});

httpAgent (a Node http.Agent) does not apply to the HTTP/2 path — undici has no http.Agent concept. The SDK emits a one-time warning if both are set, instead of silently ignoring httpAgent.

⚠️ Heads-up: Node floor rises 18 → 20.18.1

The SDK now depends on undici 7 (^7.26.0), whose own engines requires Node >= 20.18.1, and the Node shim loads undici eagerly — so the supported Node floor rises from 18 to 20.18.1 for all Node users, not only those who opt into http2. This is enforced at install (undici's engine constraint fails yarn install below 20.18.1) and documented in the README; the CI lint job moved off Node 18 accordingly. Other runtimes (browser/Deno/Bun/Workers) use platform fetch and are unaffected.

This ships as a minor (not a major): Node 18 reached EOL on 2025-04-30 and the README already scopes support to non-EOL Node, so the floor bump is consistent with stated policy. Node 18 users should pin the prior SDK minor or upgrade Node.

Why multiplexing (and why undici 7)

Two findings from benchmarking the initial single-Agent approach and tracing undici:

1. A default Agent({ allowH2: true }) doesn't multiplex. undici only multiplexes H2 streams when pipelining > 1 (default is 1; the dispatch loop gates on kRunning >= getPipelining()). With the default config it opens one TLS connection per concurrent request — a connection storm, not multiplexing.
2. The multiplexing config assert-crashes on undici 6.x. Agent({ allowH2, connections, pipelining > 1 }) multiplexes correctly but crashes with assert(!this.completed) under concurrent multiplexed H2. Fixed upstream in undici v7.23.0 (nodejs/undici#4845). Hence the ^7.26.0 floor.

So the fix is two Agent options + a dependency bump — undici owns the pool, stream lifecycle, and abort handling, so there's no hand-rolled concurrency to maintain.

Evidence

Local self-signed h2 server, 2000 concurrent requests, 20ms server delay, server maxConcurrentStreams=100, on the pinned undici 7.26.0:

config	TLS conns	h2 sessions	crashes	failures	wall
default Agent({allowH2}) (pipelining=1, unbounded)	1145	1145	0	855	8142ms
this PR (connections=4, pipelining=64)	4	4	0	0	257ms

4 × 64 = 256 in-flight requests/origin before undici queues the rest (bounded, no storm).

What changed

• src/lib/undici-fetch.ts (new) — the adapter, exposed as a createUndiciFetch(dispatcher?) factory: with no argument it binds the shared default bounded Agent (the http2: true case); pass a Dispatcher to bind it verbatim (the passthrough case). Normalizes the body shapes core.ts produces (string / Buffer / typed array / ArrayBuffer / multipart Node Readable → web stream via Readable.toWeb() + duplex: 'half'); strips the node-fetch-style agent; returns the undici Response directly.
• src/index.ts — http2?: boolean | import('undici').Dispatcher. The constructor resolves the dispatcher (makeHttp2Fetch(typeof http2 === 'object' ? http2 : undefined)) and emits a one-time console.warn when http2 + httpAgent are combined (guarded by !fetch). JSDoc documents the passthrough, the h1-fallback pipelining caveat, and the httpAgent note.
• src/_shims/* — replaces the internal http2Fetch value with a makeHttp2Fetch(dispatcher?) factory across Node/web/Deno/registry (web and Deno reuse the platform fetch and ignore the dispatcher).
• package.json / yarn.lock — undici ^7.26.0. (No engines field: yarn classic hard-errors on the root package's own engines during install, which broke the Node-18 lint job; the floor is enforced transitively by undici and documented in the README.)
• .github/workflows/ci.yml — lint job Node 18 → 20 (undici 7 can't yarn install on Node 18; every other job was already ≥ 20).
• .github/workflows/smoke-tests.yml — smoke suite runs over both transports ([http1, http2] matrix) via SMOKE_HTTP2, plus a verify-http2.mjs step on the http2 leg.
• README.md — Node requirement raised to ≥20.18.1; new HTTP/2 transport section.
• Tests — tests/lib/undici-fetch.test.ts (units for normalizeBody, the adapter's only non-trivial logic); tests/index.test.ts locks the precedence ("custom fetch wins over http2"), the passthrough (a MockAgent — a real undici Dispatcher — with net-connect disabled serves the request, proving the dispatcher is threaded end-to-end), and the warn-once behavior; verify-http2.mjs adds a "Pass D" assertion that 25 concurrent requests multiplex over ≤ 4 connections against the real API.

Testing is deliberately proportionate: normalizeBody units + the precedence / passthrough / warn-once tests (all PR-gated, hermetic — the passthrough test uses undici's own MockAgent rather than a TLS server), leaning on the existing smoke matrix for the live multiplexing assertion. Trade-off: smoke / verify-http2 run on release/manual dispatch, not on PRs, so the live multiplexing-regression check is not PR-gated.

Risk / known limitation

pipelining: 64 also enables HTTP/1.1 request pipelining on the fallback path (undici gates both protocols on getPipelining), so http2: true (opt-in) is intended for h2-capable origins like the Runloop API. The JSDoc and README warn against enabling it for traffic routed through non-h2 intermediaries. With the passthrough, strict-h1-safety or any other policy is now a one-liner — pass http2: new Agent({ allowH2: true, pipelining: 1 }) (or an ALPN-routed dispatcher) — so no hardening is baked into the default.

On the HTTP/2 path the httpAgent option is not used — undici manages connections through its own dispatcher rather than a Node http.Agent. The SDK warns once if both are set; to tune connections on the h2 path, pass a Dispatcher as http2.

Verification

• Bench on pinned undici 7.26.0: 0 crashes, 4 sessions / 2000 concurrent (table above).
• verify-http2.mjs against api.runloop.pro: ALPN negotiates h2 (not a silent h1 fallback), success body parses, a 401 rejects cleanly without crashing the process, the h1 control path works, and 25 concurrent requests multiplex over ≤ 4 connections.
• yarn build compiles CJS + ESM (both require() and import() of the package load on undici 7); yarn lint (eslint + tsc --noEmit) clean. The public dist/index.d.ts carries import('undici').Dispatcher (autocomplete) while the _shims .d.ts stay any, so web/deno declarations don't reference undici.
• yarn test: the MockAgent passthrough test and the warn-once test pass alongside the existing suite.
• CI green: build, lint, test, build-package-test.

🤖 Generated with Claude Code

[codeant-ai]

CodeAnt AI is reviewing your PR.

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[codeant-ai]

Suggestion: Converting the module URL with .pathname can produce an invalid filesystem path (/C:/... on Windows and %20-encoded segments for spaces), which makes require fail with module-not-found in valid environments. Convert the URL with fileURLToPath(...) (or require the URL directly) before requiring the built file. [logic error]

Severity Level: Major ⚠️

- ❌ HTTP2 verification harness fails on paths with spaces.
- ⚠️ Windows developers cannot run HTTP2 verifier without path tweaks.

Steps of Reproduction ✅

1. Build the SDK so `dist/index.js` exists, as used by the harness at
`tests/smoketests/scripts/verify-http2.mjs:21`.

2. On a machine where the repo path contains spaces or other characters that are
percent-encoded in URLs (for example `C:\Users\John Doe\api-client-ts` on Windows), run
`RUNLOOP_API_KEY=... node tests/smoketests/scripts/verify-http2.mjs` as described in the
usage comment at `tests/smoketests/scripts/verify-http2.mjs:14-15`.

3. The script computes `distPath` using `new URL('../../../dist/index.js',
import.meta.url).pathname` at `tests/smoketests/scripts/verify-http2.mjs:21`, which yields
a pathname with a leading slash and percent-encoded segments (e.g.
`/C:/Users/John%20Doe/api-client-ts/dist/index.js`).

4. `createRequire(import.meta.url)` at `tests/smoketests/scripts/verify-http2.mjs:20` then
calls `require(distPath)` at line 22 with this non-normalized, encoded path, causing
Node's module loader to fail to resolve the file (MODULE_NOT_FOUND / ENOENT) and terminate
the HTTP/2 verification harness before any checks run.

Fix in Cursor | Fix in VSCode Claude

(Use Cmd/Ctrl + Click for best experience)

Prompt for AI Agent 🤖

This is a comment left during a code review.

**Path:** tests/smoketests/scripts/verify-http2.mjs
**Line:** 21:22
**Comment:**
	*Logic Error: Converting the module URL with `.pathname` can produce an invalid filesystem path (`/C:/...` on Windows and `%20`-encoded segments for spaces), which makes `require` fail with module-not-found in valid environments. Convert the URL with `fileURLToPath(...)` (or require the URL directly) before requiring the built file.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix

👍 | 👎

[codeant-ai]

Suggestion: This drops the incoming agent unconditionally, so when a client is configured with httpAgent (proxy agent, custom CA, mTLS, corporate egress controls, etc.) and http2: true, those connection settings are silently ignored. That breaks the existing client contract and can cause requests to fail or bypass required network policy. Preserve equivalent transport configuration for undici (or explicitly reject incompatible agent usage with a clear error instead of silently discarding it). [api mismatch]

Severity Level: Critical 🚨

- ❌ HTTP/2 requests ignore configured proxy or custom TLS agents.
- ⚠️ Corporate egress controls relying on httpAgent are bypassed.
- ⚠️ Users enabling http2 see unexpected connection failures behind proxies.

Steps of Reproduction ✅

1. Configure a client instance with both a custom agent and HTTP/2:

   `new Runloop({ httpAgent: myAgent, http2: true })` using the `ClientOptions` type
   defined in `src/index.ts:254-331` (`httpAgent?: Agent` at `src/index.ts:277-283`,
   `http2?: boolean` at `src/index.ts:293-306`). The `Runloop` constructor passes these
   into `Core.APIClient` at `src/index.ts:361-385`, setting `httpAgent: options.httpAgent`
   and `fetch: options.fetch ?? (options.http2 ? http2Fetch : undefined)`.

2. Invoke any API operation, for example `runloop.devboxes.create()` implemented in
`src/resources/devboxes/devboxes.ts:9-31`. That method calls
`this._client.post('/v1/devboxes', { body, ...options })`
(`src/resources/devboxes/devboxes.ts:27-30`), which resolves to `APIClient.post()` in
`src/core.ts:279-281`, then `APIClient.request()` (`src/core.ts:295-311`), and finally
`APIClient.makeRequest()` / `buildRequest()` (`src/core.ts:478-493`,
`src/core.ts:339-388`).

3. In `APIClient.buildRequest()` (`src/core.ts:339-388`), the client computes `const
httpAgent = options.httpAgent ?? this.httpAgent ?? getDefaultAgent(url);` at
`src/core.ts:357`, so the `httpAgent` passed to `Runloop` is stored on the instance and
selected here. The resulting `RequestInit` includes `...(httpAgent && { agent: httpAgent
})` at `src/core.ts:377-382`, so the Node `http.Agent` is attached as `req.agent`.
`makeRequest()` then calls `fetchWithTimeout(url, req, timeout, controller)` at
`src/core.ts:490-503`.

4. In `fetchWithTimeout()` (`src/core.ts:573-600`), the method constructs `fetchOptions`
by spreading `init` minus the original `signal` (`const { signal, ...options } = init ||
{};` at `src/core.ts:579`) and then calling `this.fetch.call(undefined, url,
fetchOptions)` at `src/core.ts:594-597`. Because the `Runloop` constructor chose `fetch:
options.http2 ? http2Fetch : undefined` (`src/index.ts:378-385`), `this.fetch` is the
HTTP/2-capable `http2Fetch` shim. The shims registry wires `http2Fetch` to the Node
runtime's `http2Fetch` (`src/_shims/registry.ts:34-38`, set from `setShims()` at
`src/_shims/registry.ts:50-75`), and the Node runtime provides `http2Fetch: undiciFetch`
in `getRuntime()` at `src/_shims/node-runtime.ts:61-72`.

5. The HTTP/2 adapter `undiciFetch` in `src/lib/undici-fetch.ts:56-79` receives
`fetchOptions` with the `agent` field set, but immediately strips it with `const { agent:
_ignoredAgent, body: rawBody, signal, ...rest } = (init ?? {}) as any;` at
`src/lib/undici-fetch.ts:60`. It then constructs an undici-specific init object with a
hard-coded dispatcher `dispatcher: h2Dispatcher` at `src/lib/undici-fetch.ts:64-71`, where
`h2Dispatcher` is a module-scoped `new Agent({ allowH2: true, ... })` created at
`src/lib/undici-fetch.ts:25-32`. The original Node `http.Agent` (proxy agent, custom CA,
mTLS, etc.) from `ClientOptions.httpAgent` is never consulted in this HTTP/2 code path. As
a result, any connection-level configuration expressed via `httpAgent` is ignored when
`http2: true` is set, even though `httpAgent` is still accepted and stored by `APIClient`.
(The comment at `src/index.ts:293-303` notes that `httpAgent` "is not used" on the HTTP/2
path, but there is no runtime guard; the agent is simply dropped.)

Fix in Cursor | Fix in VSCode Claude

(Use Cmd/Ctrl + Click for best experience)

Prompt for AI Agent 🤖

This is a comment left during a code review.

**Path:** src/lib/undici-fetch.ts
**Line:** 60:60
**Comment:**
	*Api Mismatch: This drops the incoming `agent` unconditionally, so when a client is configured with `httpAgent` (proxy agent, custom CA, mTLS, corporate egress controls, etc.) and `http2: true`, those connection settings are silently ignored. That breaks the existing client contract and can cause requests to fail or bypass required network policy. Preserve equivalent transport configuration for undici (or explicitly reject incompatible agent usage with a clear error instead of silently discarding it).

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix

👍 | 👎

[codeant-ai]

CodeAnt AI finished reviewing your PR.

[codeant-ai]

CodeAnt AI is running Incremental review

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[codeant-ai]

CodeAnt AI Incremental review completed.