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

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Tony Deng <tony@runloop.ai>
Co-authored-by: sid-rl <siddarth@runloop.ai>
Co-authored-by: Reflex <agent@reflex.dev>

Author: 5 people

.github/workflows/ci.yml

@@ -26,7 +26,9 @@ jobs:
       - name: Set up Node
         uses: runloopai/setup-node@main
         with:
-          node-version: '18'
+          # undici 7 (the http2 transport dep) requires Node >= 20.18.1, so the
+          # lint job can no longer bootstrap on Node 18. See README Requirements.
+          node-version: '20'
 
       - name: Bootstrap
         run: ./scripts/bootstrap

.github/workflows/smoke-tests.yml

@@ -28,8 +28,17 @@ concurrency:
 
 jobs:
   smoke-tests:
+    name: smoke-tests (${{ matrix.transport }})
     runs-on: ubuntu-latest
     timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        # Run the full suite over both transports: default node-fetch (HTTP/1.1)
+        # and the undici adapter (HTTP/2). SMOKE_HTTP2 is read in tests/smoketests/utils.ts.
+        transport: [http1, http2]
+    env:
+      SMOKE_HTTP2: ${{ matrix.transport == 'http2' && '1' || '0' }}
     steps:
       - name: Checkout
         uses: runloopai/checkout@main
@@ -66,5 +75,9 @@ jobs:
       - name: Verify generated example artifacts
         run: yarn check:examples-md
 
+      - name: Verify HTTP/2 negotiation
+        if: matrix.transport == 'http2'
+        run: node tests/smoketests/scripts/verify-http2.mjs
+
       - name: Run smoke tests
         run: yarn test:smoke --maxWorkers=800% --color

README.md

@@ -355,6 +355,32 @@ await runloop.devboxes.create({...}, {
 });
 ```
 
+### HTTP/2 transport
+
+On Node.js, the SDK can send requests over HTTP/2, which multiplexes many concurrent requests over a small number of TLS connections instead of opening a connection per request. Enable it with the `http2` option:
+
+<!-- prettier-ignore -->
+```ts
+const runloop = new RunloopSDK({
+  http2: true,
+});
+```
+
+Requests are routed through an [undici](https://github.com/nodejs/undici) connection pool with HTTP/2 enabled, falling back to HTTP/1.1 for origins that don't negotiate h2 via ALPN. It is intended for HTTP/2-capable origins such as the Runloop API. This transport uses undici and therefore **requires Node.js >= 20.18.1** (see Requirements).
+
+`http2: true` uses a default bounded pool. To control the pool yourself — for example to raise the number of connections or multiplexed streams for a high-concurrency workload — pass a configured undici `Dispatcher` (such as an `Agent`) instead. The SDK uses it verbatim and does not manage its lifecycle, the same way it treats a custom `httpAgent`:
+
+<!-- prettier-ignore -->
+```ts
+import { Agent } from 'undici';
+
+const runloop = new RunloopSDK({
+  http2: new Agent({ allowH2: true, connections: 8, pipelining: 100 }),
+});
+```
+
+The `httpAgent` option does not apply to the HTTP/2 transport (undici has no Node `http.Agent` concept); set `http2` to a `Dispatcher` to tune connections. A one-time warning is emitted if both `http2` and `httpAgent` are provided.
+
 ## Semantic versioning
 
 This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions:
@@ -374,7 +400,7 @@ TypeScript >= 4.5 is supported.
 The following runtimes are supported:
 
 - Web browsers (Up-to-date Chrome, Firefox, Safari, Edge, and more)
-- Node.js 18 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions.
+- Node.js 20.18.1 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions. (Raised from 18 because the SDK now depends on undici 7 on Node; the HTTP/2 transport needs the undici >= 7.23.0 crash fix, and the package pins `^7.26.0`.)
 - Deno v1.28.0 or higher.
 - Bun 1.0 or later.
 - Cloudflare Workers.

package.json

@@ -48,6 +48,7 @@
     "formdata-node": "^4.3.2",
     "node-fetch": "^2.6.7",
     "tar": "^7.5.2",
+    "undici": "^7.26.0",
     "uuidv7": "^1.0.2",
     "zod": "^3.24.1"
   },

src/_shims/index-deno.ts

@@ -9,6 +9,11 @@ const _fetch = fetch;
 type _fetch = typeof fetch;
 export { _fetch as fetch };
 
+// The platform `fetch` already negotiates HTTP/2 at the transport layer, so
+// `{ http2: ... }` is a no-op on Deno — reuse the global fetch and ignore any passed
+// dispatcher (undici dispatchers are a Node-only concept).
+export const makeHttp2Fetch = () => _fetch;
+
 const _Request = Request;
 type _Request = Request;
 export { _Request as Request };

src/_shims/index.d.ts

@@ -15,6 +15,15 @@ export type Agent = SelectType<manual.Agent, auto.Agent>;
 // @ts-ignore
 export const fetch: SelectType<typeof manual.fetch, typeof auto.fetch>;
 
+/**
+ * Build an HTTP/2-capable `fetch`, used when the client is constructed with
+ * `{ http2: ... }`. In Node this is the undici adapter (`Agent({ allowH2: true })`);
+ * the optional `dispatcher` lets the caller pass a configured undici `Dispatcher`
+ * (the `http2: <Dispatcher>` passthrough), defaulting to the SDK's bounded pool. On
+ * the web it returns the platform `fetch`, which already negotiates HTTP/2.
+ */
+export function makeHttp2Fetch(dispatcher?: any): typeof fetch;
+
 // @ts-ignore
 export type Request = SelectType<manual.Request, auto.Request>;
 // @ts-ignore

src/_shims/node-runtime.ts

@@ -14,6 +14,7 @@ import { type RequestOptions } from '../core';
 import { MultipartBody } from './MultipartBody';
 import { type Shims } from './registry';
 import { ReadableStream } from 'node:stream/web';
+import { createUndiciFetch } from '../lib/undici-fetch';
 
 type FileFromPathOptions = Omit<FilePropertyBag, 'lastModified'>;
 
@@ -66,6 +67,7 @@ export function getRuntime(): Shims {
   return {
     kind: 'node',
     fetch: nf.default,
+    makeHttp2Fetch: createUndiciFetch,
     Request: nf.Request,
     Response: nf.Response,
     Headers: nf.Headers,

src/_shims/registry.ts

@@ -6,6 +6,14 @@ import { type RequestOptions } from '../core';
 export interface Shims {
   kind: string;
   fetch: any;
+  /**
+   * Build an HTTP/2-capable `fetch`, used when the client is constructed with
+   * `{ http2: ... }`. In Node this is the undici adapter (`Agent({ allowH2: true })`);
+   * the optional `dispatcher` lets the caller pass a configured undici `Dispatcher`
+   * (the `http2: <Dispatcher>` passthrough), defaulting to the SDK's bounded pool. On
+   * the web the platform `fetch` already negotiates HTTP/2, so the argument is ignored.
+   */
+  makeHttp2Fetch: (dispatcher?: any) => any;
   Request: any;
   Response: any;
   Headers: any;
@@ -27,6 +35,7 @@ export interface Shims {
 export let auto = false;
 export let kind: Shims['kind'] | undefined = undefined;
 export let fetch: Shims['fetch'] | undefined = undefined;
+export let makeHttp2Fetch: Shims['makeHttp2Fetch'] | undefined = undefined;
 export let Request: Shims['Request'] | undefined = undefined;
 export let Response: Shims['Response'] | undefined = undefined;
 export let Headers: Shims['Headers'] | undefined = undefined;
@@ -53,6 +62,7 @@ export function setShims(shims: Shims, options: { auto: boolean } = { auto: fals
   auto = options.auto;
   kind = shims.kind;
   fetch = shims.fetch;
+  makeHttp2Fetch = shims.makeHttp2Fetch;
   Request = shims.Request;
   Response = shims.Response;
   Headers = shims.Headers;

src/_shims/web-runtime.ts

@@ -35,6 +35,10 @@ export function getRuntime({ manuallyImported }: { manuallyImported?: boolean }
   return {
     kind: 'web',
     fetch: _fetch,
+    // The platform `fetch` already negotiates HTTP/2 at the transport layer, so
+    // `{ http2: ... }` is a no-op on the web — reuse the global fetch and ignore any
+    // passed dispatcher (undici dispatchers are a Node-only concept).
+    makeHttp2Fetch: () => _fetch,
     Request: _Request,
     Response: _Response,
     Headers: _Headers,

src/index.ts

@@ -1,6 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { type Agent } from './_shims/index';
+import { type Agent, makeHttp2Fetch } from './_shims/index';
 import * as Core from './core';
 import * as Errors from './error';
 import * as Pagination from './pagination';
@@ -291,6 +291,38 @@ export interface ClientOptions {
    */
   fetch?: Core.Fetch | undefined;
 
+  /**
+   * Send requests over HTTP/2 (with automatic fallback to HTTP/1.1).
+   *
+   * In Node.js this swaps the default `node-fetch` transport for an undici-backed
+   * adapter (`Agent({ allowH2: true })`) that negotiates HTTP/2 via ALPN. On the
+   * web the platform `fetch` already speaks HTTP/2, so this is a no-op there.
+   * Ignored when a custom `fetch` is provided.
+   *
+   * - `true` uses the SDK's default bounded HTTP/2 pool (a few TLS sessions, many
+   *   multiplexed streams each).
+   * - Pass a configured undici `Dispatcher` (e.g. `new Agent({ allowH2: true,
+   *   connections, pipelining })`) to control the pool yourself — the SDK uses it
+   *   verbatim and does not manage its lifecycle, exactly like `httpAgent`.
+   *
+   * **Intended for HTTP/2-capable origins (such as the Runloop API).** When the
+   * origin does not negotiate h2, undici falls back to HTTP/1.1 with request
+   * pipelining enabled on the shared dispatcher; pipelining is unsafe against
+   * many HTTP/1.1 servers and proxies. Do not enable this flag if your traffic
+   * may be routed through a non-h2 intermediary.
+   *
+   * On the HTTP/2 path the `httpAgent` option is not used, since undici manages
+   * connections through its own dispatcher rather than a Node `http.Agent` — to
+   * tune connections here, pass a `Dispatcher` as shown above. A one-time warning
+   * is emitted if both `http2` and `httpAgent` are set.
+   *
+   * @default false
+   */
+  // The `import('undici').Dispatcher` type is inlined (rather than a top-of-file
+  // import) to keep this manual addition to a generated file regen-friendly and to
+  // avoid pulling undici types onto the web/deno code paths; it is type-only/erased.
+  http2?: boolean | import('undici').Dispatcher | undefined;
+
   /**
    * The maximum number of times that the client will retry a request in case of a
    * temporary failure, like a network error or a 5XX error from the server.
@@ -327,6 +359,11 @@ export interface ClientOptions {
  * console.log(result.exitCode);
  * ```
  */
+// Emitted at most once per process when `http2` and `httpAgent` are combined (see
+// the constructor). Module-scoped flag mirrors the `fileFromPathWarned` pattern in
+// _shims/node-runtime.ts.
+let http2HttpAgentWarned = false;
+
 export class Runloop extends Core.APIClient {
   bearerToken: string;
 
@@ -340,6 +377,7 @@ export class Runloop extends Core.APIClient {
    * @param {number} [opts.timeout=30 seconds] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out.
    * @param {number} [opts.httpAgent] - An HTTP agent used to manage HTTP(s) connections.
    * @param {Core.Fetch} [opts.fetch] - Specify a custom `fetch` function implementation.
+   * @param {boolean | import('undici').Dispatcher} [opts.http2=false] - Send requests over HTTP/2 (Node only; ignored when `fetch` is provided). `true` uses the default bounded pool; pass an undici `Dispatcher` to control the pool yourself.
    * @param {number} [opts.maxRetries=5] - The maximum number of times the client will retry a request.
    * @param {Core.Headers} opts.defaultHeaders - Default headers to include with every request to the API.
    * @param {Core.DefaultQuery} opts.defaultQuery - Default query parameters to include with every request to the API.
@@ -361,13 +399,30 @@ export class Runloop extends Core.APIClient {
       baseURL: baseURL || `https://api.runloop.ai`,
     };
 
+    // `httpAgent` (a Node `http.Agent`) does not apply to the HTTP/2 transport —
+    // undici manages its own dispatcher and has no `http.Agent` concept. Warn once
+    // instead of silently ignoring it. (Skipped when a custom `fetch` supersedes
+    // `http2` entirely.)
+    if (!options.fetch && options.http2 && options.httpAgent && !http2HttpAgentWarned) {
+      http2HttpAgentWarned = true;
+      console.warn(
+        '[runloop] `httpAgent` is ignored when `http2` is set: undici manages its own ' +
+          'dispatcher and has no Node http.Agent concept. To configure the HTTP/2 transport, ' +
+          'pass a configured undici Dispatcher as `http2` (e.g. `http2: new Agent({ connections, pipelining })`).',
+      );
+    }
+
     super({
       baseURL: options.baseURL!,
       baseURLOverridden: baseURL ? baseURL !== 'https://api.runloop.ai' : false,
       timeout: options.timeout ?? 30000 /* 30 seconds */,
       httpAgent: options.httpAgent,
       maxRetries: options.maxRetries,
-      fetch: options.fetch,
+      fetch:
+        options.fetch ??
+        (options.http2 ?
+          makeHttp2Fetch(typeof options.http2 === 'object' ? options.http2 : undefined)
+        : undefined),
     });
 
     const customHeadersEnv = Core.readEnv('RUNLOOP_CUSTOM_HEADERS');