feat(world-vercel): allow a custom dispatcher (vercel#2235)

* feat(world-vercel): allow a custom dispatcher

Add a `dispatcher` option to `APIConfig`/`createVercelWorld` so callers can
supply a custom undici dispatcher. It is threaded through every request path
(HTTP and the queue) and defaults to the shared undici RetryAgent.

* docs(world-vercel): explain why dispatcher is typed unknown

Author: AndrewBarba

.changeset/vercel-world-custom-dispatcher.md

@@ -0,0 +1,5 @@
+---
+'@workflow/world-vercel': minor
+---
+
+Add a `dispatcher` option to `createVercelWorld` for supplying a custom undici dispatcher, used for both HTTP and queue requests. Defaults to the shared undici `RetryAgent`.

packages/world-vercel/README.md

@@ -6,3 +6,15 @@ Integrates with Vercel's infrastructure for storage, queuing, and authentication
 
 Used by default for deployments on Vercel. Authentication and API endpoints are configured automatically in Vercel deployments.
 
+## Custom dispatcher
+
+HTTP requests (including the queue) default to a shared undici `RetryAgent` that handles connection pooling and retries. Pass a custom `dispatcher` to override it — e.g. to tune undici on newer Node runtimes:
+
+```ts
+import { Agent } from 'undici';
+import { createVercelWorld } from '@workflow/world-vercel';
+import { setWorld } from '@workflow/core/runtime';
+
+setWorld(createVercelWorld({ dispatcher: new Agent({ connections: 16 }) }));
+```
+

packages/world-vercel/src/encryption.ts

@@ -97,6 +97,8 @@ export async function fetchRunKey(
     token?: string;
     /** Team ID for team-scoped API requests. */
     teamId?: string;
+    /** Custom HTTP dispatcher. Defaults to the shared undici agent. */
+    dispatcher?: unknown;
   }
 ): Promise<Uint8Array | undefined> {
   // Authenticate via provided token (CLI/config), VERCEL_TOKEN env var
@@ -126,7 +128,7 @@ export async function fetchRunKey(
         Authorization: `Bearer ${token}`,
       },
       // @ts-expect-error -- undici dispatcher is accepted by Node.js fetch but not in @types/node's RequestInit
-      dispatcher: getDispatcher(),
+      dispatcher: getDispatcher({ dispatcher: options?.dispatcher }),
     }
   );
 
@@ -170,7 +172,8 @@ export async function fetchRunKey(
 export function createGetEncryptionKeyForRun(
   projectId: string | undefined,
   teamId?: string,
-  token?: string
+  token?: string,
+  dispatcher?: unknown
 ): World['getEncryptionKeyForRun'] {
   if (!projectId) return undefined;
 
@@ -215,6 +218,10 @@ export function createGetEncryptionKeyForRun(
     // HKDF derivation server-side so the raw deployment key never leaves
     // the API boundary.
     if (!deploymentId) return undefined;
-    return fetchRunKey(deploymentId, projectId, runId, { token, teamId });
+    return fetchRunKey(deploymentId, projectId, runId, {
+      token,
+      teamId,
+      dispatcher,
+    });
   };
 }

packages/world-vercel/src/http-client.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+import { getDispatcher } from './http-client.js';
+
+describe('getDispatcher', () => {
+  it('returns the shared default dispatcher when none is provided', () => {
+    expect(getDispatcher()).toBe(getDispatcher());
+    expect(getDispatcher({})).toBe(getDispatcher());
+  });
+
+  it('returns the caller-supplied dispatcher when provided', () => {
+    const custom = {};
+    expect(getDispatcher({ dispatcher: custom })).toBe(custom);
+  });
+});

packages/world-vercel/src/http-client.ts

@@ -1,15 +1,24 @@
 import { Agent, RetryAgent } from 'undici';
+import type { APIConfig } from './utils.js';
 
 let _dispatcher: RetryAgent | undefined;
 
+/**
+ * Resolves the undici dispatcher for a request: the caller's override, or the
+ * shared default agent.
+ */
+export function getDispatcher(config?: APIConfig): unknown {
+  return config?.dispatcher ?? getDefaultDispatcher();
+}
+
 /**
  * Returns a shared undici RetryAgent wrapping an Agent.
  *
  * - Connection pooling (up to 8 connections per origin)
  * - Retry: Automatic retry on 429/5xx or network errors with exponential backoff
  *   - Observes Retry-After header if received and lower than 30s
  */
-export function getDispatcher(): RetryAgent {
+function getDefaultDispatcher(): RetryAgent {
   if (!_dispatcher) {
     _dispatcher = new RetryAgent(
       new Agent({

packages/world-vercel/src/index.ts

@@ -38,7 +38,8 @@ export function createVercelWorld(config?: APIConfig): World {
     getEncryptionKeyForRun: createGetEncryptionKeyForRun(
       projectId,
       config?.projectConfig?.teamId,
-      config?.token
+      config?.token,
+      config?.dispatcher
     ),
     resolveLatestDeploymentId: createResolveLatestDeploymentId(config),
   };

packages/world-vercel/src/queue.ts

@@ -193,7 +193,7 @@ export function createQueue(config?: APIConfig): Queue {
 
   const clientOptions = {
     region,
-    dispatcher: getDispatcher(),
+    dispatcher: getDispatcher(config),
     transport: dualTransport,
     ...(usingProxy && {
       // final path will be /queues-proxy/api/v3/topic/...

packages/world-vercel/src/refs.ts

@@ -110,7 +110,7 @@ export async function resolveRefDescriptor(
       const response = await fetch(url, {
         method: 'GET',
         headers,
-        dispatcher: getDispatcher(),
+        dispatcher: getDispatcher(config),
       } as any);
 
       span?.setAttributes({

packages/world-vercel/src/resolve-latest-deployment.ts

@@ -58,7 +58,7 @@ export function createResolveLatestDeploymentId(
         Authorization: `Bearer ${token}`,
       },
       // @ts-expect-error -- undici dispatcher is accepted by Node.js fetch but not in @types/node's RequestInit
-      dispatcher: getDispatcher(),
+      dispatcher: getDispatcher(config),
     });
 
     if (!response.ok) {

packages/world-vercel/src/utils.ts

@@ -108,6 +108,17 @@ const getWorkflowServerUrlOverride = (): string =>
 export interface APIConfig {
   token?: string;
   headers?: RequestInit['headers'];
+  /**
+   * Custom HTTP dispatcher passed to every `fetch()` call (e.g. an undici
+   * `Agent`/`RetryAgent`). Defaults to a shared undici `RetryAgent`.
+   *
+   * Typed as `unknown` on purpose: undici's `Dispatcher` type is nominally
+   * version-specific (it differs across v6/v7/v8 and the `undici-types`
+   * bundled with each `@types/node` major), so a concrete type would reject a
+   * dispatcher from a different undici version. Callers may pass any undici
+   * version's dispatcher, or any object implementing the dispatcher contract.
+   */
+  dispatcher?: unknown;
   projectConfig?: {
     /** The real Vercel project ID (e.g., prj_xxx) */
     projectId?: string;
@@ -344,7 +355,7 @@ export async function makeRequest<T>({
         try {
           // eslint-disable-next-line @typescript-eslint/no-explicit-any -- undici v7 dispatcher types don't match @types/node's RequestInit
           response = await fetch(request, {
-            dispatcher: getDispatcher(),
+            dispatcher: getDispatcher(config),
           } as any);
         } catch (error) {
           const elapsed = Date.now() - fetchStart;