feat: default to HTTP/2 transport on Node

[jrvb-rl]

Why HTTP/2 (performance motivation)

On Node.js the previous default transport (node-fetch over HTTP/1.1) opens a new TCP + TLS connection per concurrent request — HTTP/1.1 can't multiplex, so a burst of N in-flight requests means up to N handshakes and, once the socket pool is saturated, requests queue waiting for a free connection. That connection setup and queueing lands squarely in the tail latency.

The SDK's node:http2 transport multiplexes many concurrent requests as streams over a small shared pool of connections: one handshake amortized across many requests, no per-request connection setup, and no pool-exhaustion queueing. Runloop SDK traffic is bursty and highly concurrent (agents firing many devbox operations in parallel), which is exactly the workload HTTP/2 multiplexing is built for. Bulk transfers stay at parity because the H2 session's flow-control window is sized so large streams aren't RTT-bound.

End-to-end benchmark (dev)

Measured against dev from this branch (Node v24), same client config with only the http2 flag flipped. Indicative single-run results from a shared environment — compare like-for-like, not as absolute targets.

Request handling under high concurrency (primary)

The SDK's own load harness — loadtest/loadtest.ts (from #798) — fires many devboxes.create calls concurrently at a deliberately nonexistent blueprint (bp_nonexistent_loadtest_00000). Every request fails fast server-side (all HTTP 400, zero devboxes created), which isolates client + server request handling from actual provisioning — i.e. purely "can the stack absorb a burst of requests at once." Run here at 2,000 concurrent requests (reduced from the harness default; the sandbox FD limit is 4096), http2 set explicitly per pass:

Metric	HTTP/1.1	HTTP/2	Improvement
Wall clock (2,000 reqs)	16.13 s	0.98 s	~16× faster
Throughput	124 req/s	2,037 req/s	~16×
p50 latency	6,447 ms	744 ms	~8.7×
p95 latency	11,952 ms	908 ms	~13×
p99 latency	16,087 ms	969 ms	~16.6×
Result	2000× 400	2000× 400	—

Under a 2,000-request burst, HTTP/1.1 (node-fetch) opens a socket per request and serializes behind connection setup + pool limits, so latency balloons into multi-second territory; HTTP/2 multiplexes the whole burst over a small connection pool and clears it in under a second. This is the workload the default flip is aimed at.

Concurrent lightweight reads (secondary)

A smaller micro-benchmark firing N concurrent devboxes.list({ limit: 1 }) reads (warmup excluded, 0 failures) — a lighter endpoint where server processing dominates the median, so the win shows in the tail:

Concurrency	Transport	req/s	p50	p95	p99
40 (×5)	HTTP/1.1	149.5	203	441	460
40 (×5)	HTTP/2	179.4	202	220	228
100 (×3)	HTTP/1.1	192.2	457	630	638
100 (×3)	HTTP/2	209.8	429	478	480

Concurrent large downloads (throughput parity)

8 × 10 MB via downloadFile, md5-verified (exercises the H2 flow-control window):

Transport	Effective throughput
HTTP/1.1	55.7 MB/s
HTTP/2	62.0 MB/s

Bulk throughput is at parity (slightly ahead here), with all payloads byte-identical — HTTP/2 is not a regression for large transfers.

Summary

Makes HTTP/2 the default transport on Node.js. The SDK's native node:http2 transport multiplexes many concurrent requests over a small shared pool of TLS connections instead of opening one connection per request. Previously HTTP/2 was opt-in (http2: true); this flips the default from false → true.

• Web / Deno / Bun: unaffected — the platform fetch already speaks HTTP/2, and the H2 shim is a no-op there.
• Custom fetch: always wins over http2.
• Opt out: http2: false selects the HTTP/1.1 node-fetch transport.

Transport resolution

httpAgent only applies to the HTTP/1.1 path — the H2 pool manages its own connections. To avoid silently changing behavior for existing users who pass an httpAgent, resolution is:

http2	httpAgent	Result
unset	unset	HTTP/2 (new default, shared pool)
unset	set	HTTP/1.1, one-time warning (honors the agent)
false	any	HTTP/1.1, silent
true	any	HTTP/2 (shared pool); warns once if httpAgent also set
H2FetchOptions	any	HTTP/2 with a dedicated, tuned pool
any	+ custom fetch	custom fetch

No existing httpAgent user is silently moved off HTTP/1.1: they get a one-time notice and can drop httpAgent to adopt H2 or pass http2: false to silence it.

Shared connection pool

All clients using the default transport share a single HTTP/2 pool, so short-lived clients (e.g. one per request) don't each open — and leak — their own H2 sessions. Explicit H2FetchOptions still get a dedicated pool, since that's deliberate tuning.

Transport correctness

Making H2 the default surfaced two behaviors of the transport that only mattered once non-opt-in clients used it, both fixed here:

• Response contract — the H2 fetch now returns a standard node-fetch Response, so .asResponse() satisfies instanceof Response like the HTTP/1.1 transport does. Streaming is preserved (the H2 body is consumed as a Node Readable).
• Process lifetime — idle pooled H2 sessions are unref'd (and ref'd only while a request is in flight), so a short Node script or test process exits normally instead of hanging on open sockets.

Code organization

The transport-selection logic and its one-time warnings live in a handwritten helper, src/lib/http2-transport.ts. The generated src/index.ts keeps only a one-line call-site hook, so regeneration stays clean.

Docs

Rewrote the README HTTP/2 transport section for H2-as-default and the http2: false opt-out, and corrected stale copy that still described the previous undici-based transport (it's native node:http2).

Release

Ships as a minor version bump; http2: false is the documented opt-out.

Test plan

• tsc --noEmit clean.
• Unit coverage for transport resolution: default→H2 with a shared pool, http2: false opt-out, dedicated pool for H2FetchOptions, and both one-time warnings.
• Full jest suite against the mock server: 880 passed, 6 skipped, including all tests/api-resources/** and the h2-transport suite; the process exits promptly.

🤖 Generated with Claude Code

[codeant-ai]

CodeAnt AI is reviewing your PR.

[codeant-ai]

---

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 finished reviewing your PR.

[codeant-ai]

CodeAnt AI is running Incremental review

[codeant-ai]

---

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.

[codeant-ai]

CodeAnt AI is running Incremental review

[codeant-ai]

---

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.

[james-rl]

This looks good to me.

Some trivial nits:

• in tests/index.test.ts:105 references a variable that doesn't exist any more
• src/lib/h2-transport/index.ts:69 has status 101 in NULL_BODY_STATUSES but it's unreachable on HTTP/2
• src/lib/h2-transport/index.ts:89 uses Object.defineProperty for url but omits writable: true

[jrvb-rl]

Thanks @james-rl! All three nits fixed in 31661f3:

• tests/index.test.ts stale comment — updated to reference the current fetch: options.fetch ?? resolveHttp2Fetch(options) (was still describing the pre-refactor useHttp2 / makeHttp2Fetch(...) shape).
• 101 in NULL_BODY_STATUSES — removed; Switching Protocols is an HTTP/1.1 upgrade status and can't occur over HTTP/2, so it was unreachable. Now {204, 205, 304}.
• Response.url descriptor — added writable: true.

tsc + lint clean; h2-transport (80) and http2 unit tests still green.