Uh oh!
There was an error while loading. Please reload this page.
[world-vercel] Enable HTTP/2 for the events API and stream writes - #2573
Merged
Conversation
Flip allowH2 to true in the shared undici dispatcher so every dispatcher-backed path (v3 makeRequest, v4 events, the queue client, deployment resolution, run-key fetch) negotiates HTTP/2. H2 was previously disabled for a SvelteKit-on-Vercel-prod hang; re-enable it globally and rely on the E2E suite to guard the regression. Streaming paths in streamer.ts intentionally bypass the dispatcher and are unaffected. Adds a regression guard on the agent options plus a local http2 server test proving global fetch honors an allowH2 dispatcher (the mechanism the v4 events path relies on). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
🦋 Changeset detectedLatest commit: b2ec9d7 The changes in this PR will be included in the next version bump. This PR includes changesets to release 17 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Contributor
🧪 E2E Test Results✅ All tests passed Summary
Details by Category✅ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 🪟 Windows
✅ 📋 Other
|
Contributor
📊 Benchmark Results
workflow with no steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro workflow with 1 step💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Express | Nitro workflow with 10 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express workflow with 25 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro workflow with 50 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Express | Nitro Promise.all with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) Promise.all with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) Promise.all with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro | Express Promise.race with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro Promise.race with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) Promise.race with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express workflow with 10 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 25 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 50 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) workflow with 10 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 25 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 50 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) Stream Benchmarks(includes TTFB metrics)workflow with stream💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro stream pipeline with 5 transform steps (1MB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Express | Nitro 10 parallel streams (1MB each)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) fan-out fan-in 10 streams (1MB each)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Express | Nitro SummaryFastest Framework by WorldWinner determined by most benchmark wins
Fastest World by FrameworkWinner determined by most benchmark wins
Column Definitions
Worlds:
|
Enabling H2 on the single shared dispatcher hung the queue's webhook respondWith mechanism (120s E2E timeouts on webhook/hook workflows across frameworks). Instead, give the v4 events API its own H2-enabled dispatcher (getEventsDispatcher) and keep the default dispatcher — queue/webhook, v3 makeRequest, streaming, deployment resolution, run-key fetch — on HTTP/1.1. The events endpoints are the hottest path (an event write per step transition plus log reads) and are plain request/response (or a streamed LIST response), none of which trip the webhook/duplex H2 issues, so they get multiplexing safely. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
VaguelySerious
marked this pull request as draft
June 23, 2026 23:05
SvelteKit bundles the server (including undici via the world adapter) into
ESM output. undici loads node: builtins as ESM imports except node:http2,
which it pulls in lazily via a bare require('node:http2') inside a try/catch.
The bundler leaves that bare require un-wired, so in the ESM bundle it throws
and undici silently falls back to a stub whose http2.connect is undefined —
breaking every HTTP/2 request (the workflow flow-route callback fails with
"fetch failed", so runs never start).
Inject a createRequire-backed global require into the SSR build only (a
node:module import would break the client bundle) so the real node:http2
resolves. Detected via configResolved.build.ssr because SvelteKit does not
set env.isSsrBuild for its server pass.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>Nitro bundles undici (via the world adapter) into the ESM server output.
undici loads node: builtins as ESM imports except node:http2, which it pulls
in lazily via a bare require('node:http2') inside a try/catch. The bundler
leaves that bare require un-wired, so in the ESM bundle it throws and undici
silently falls back to a stub whose http2.connect is undefined — breaking
every HTTP/2 request (the workflow flow-route callback fails with "fetch
failed", so runs never start). This affects all nitro-based builds including
the Vite and TanStack Start framework integrations.
Prepend a createRequire-backed global require to the server chunks (via the
rollup:before hook, production builds only) so the real node:http2 resolves.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>Stream writes (write/writeMulti/close) previously used plain fetch() on HTTP/1.1. Route them through a dedicated H2 stream dispatcher: the PUT requests send a fully-buffered body (or none), so they gain H2 multiplexing without the duplex-streaming issues that keep the long-lived live-read (GET) on plain fetch. The stream dispatcher is a bare undici Agent without the RetryAgent wrapper — stream appends are not idempotent, so undici-level retry is deliberately omitted to avoid duplicating chunks (preserving the streamer's original no-retry behavior). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
| headers: httpConfig.headers, | ||
| }); | ||
| // eslint-disable-next-line @typescript-eslint/no-explicit-any -- undici dispatcher type doesn't match @types/node's RequestInit | ||
| dispatcher: getStreamDispatcher(config), |
Contributor
There was a problem hiding this comment.
[P1] I would block this until the Vercel Nitro v3 benchmark is rerun green or root-caused. The current Benchmark Vercel (nitro-v3) job fails with Stream 1 correctness failure: expected 1048576 bytes, got 983040, exactly one 64 KiB chunk missing from the stream benchmark. Since this PR changes stream PUTs to use the H2 dispatcher here, this looks like a plausible stream-write correctness regression rather than a pure perf failure. Job: https://github.com/vercel/workflow/actions/runs/28066956084/job/83093680965
| * getDefaultStreamDispatcher for why this is a bare Agent (no retry). | ||
| */ | ||
| export function getStreamDispatcher(config?: APIConfig): unknown { | ||
| return config?.dispatcher ?? getDefaultStreamDispatcher(); |
Contributor
There was a problem hiding this comment.
[P2] This keeps the default stream dispatcher retry-free, but config.dispatcher now also controls stream writes. A caller that passes an undici RetryAgent can re-enable retries for stream PUTs; undici retries PUT by default, and stream appends are not idempotent, so that can duplicate chunks. Can we document this in the custom dispatcher section, or split out a stream-specific dispatcher option / guard so retrying dispatchers are not used for stream writes?
MemberAuthor
There was a problem hiding this comment.
(AI) Good catch. Rather than leave stream writes retry-free, I scoped the retry policy so the win (resilience to transient blips) survives without the duplicate-chunk risk:
- The default stream dispatcher is now a
RetryAgentwithSTREAM_RETRY_OPTIONS={ methods: ['PUT'], statusCodes: [429], retryAfter: true }. It retries only on transient connection errors (undici's defaulterrorCodes) and HTTP 429 — both guarantee the chunk was not persisted. 5xx is excluded (a 5xx can mean the chunk was written but the response failed → retry would duplicate), as are other 4xx. - For the caller-override case you flagged: documented in the
dispatcherJSDoc (APIConfiginutils.ts) that a custom dispatcher replaces every default including stream writes, and should not retryPUTon 5xx.
Added a regression test asserting statusCodes is exactly [429] and never contains 500/502/503/504.
| */ | ||
| function addNodeRequireBanner(config: RollupConfig): void { | ||
| const banner = | ||
| "import { createRequire as __wkfCreateRequire } from 'node:module'; if (typeof require === 'undefined') { globalThis.require = __wkfCreateRequire(import.meta.url); }"; |
Contributor
There was a problem hiding this comment.
[P3] This fixes the bundled undici node:http2 issue, but it also globally changes server-bundle feature detection: dependencies that branch on typeof require will now take their CJS/require path in these ESM bundles. The tested Vercel Node lanes passing is reassuring, but can we call this out as a Node-runtime-only server-bundle shim and keep an eye on optional-require behavior in bundled libraries?
MemberAuthor
There was a problem hiding this comment.
(AI) Agreed — that global feature-detection change is the right thing to flag. I kept the global globalThis.require (it's required: undici's bundled bare require(...) resolves against the runtime global scope, so a module-local const require wouldn't reliably be in scope for the inlined undici code), but tightened the JSDoc in both nitro/index.ts and sveltekit/plugin.ts to call it out explicitly as a Node-server-runtime-only shim and document the side effect + why it's safe:
- Server-only — gated to the production server build (
!nitro.options.dev/config.build.ssr); never touches the client/browser bundle. - Guarded — the
typeof require === 'undefined'check makes it a no-op in CJS chunks where a realrequirealready exists; it only fills a genuine ESM gap. - Functional — the
requirewe install is a workingcreateRequire, so a lib that switches to the require path gets a realrequire, not a broken stub (the commontry { require(optional) } catch {}pattern still degrades gracefully).
The comment also records the one residual behavior to watch, per your ask: a bundled lib that, on detecting require, does require() of an ESM-only dependency on a Node version without require(ESM) support. The Vercel Node E2E lanes exercise the real undici path that motivated this. Comment-only change in b2ec9d7.
… 429 Stream writes (PUT) append chunks and are not idempotent. The stream dispatcher was a bare Agent with no retry; switch it to a RetryAgent whose policy is narrowed so PUTs retry only on transient connection errors and HTTP 429 — both of which guarantee the chunk was not persisted — and never on 5xx (where the chunk may already have been written) or other 4xx. Also document that a caller-supplied `config.dispatcher` overrides the stream dispatcher and should not retry PUT on 5xx. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Uh oh!
There was an error while loading. Please reload this page.
…nt (no retry)" / "intentionally retry-free", contradicting the actual `RetryAgent` + `STREAM_RETRY_OPTIONS` implementation in a non-idempotent write path. This commit fixes the issue reported at packages/world-vercel/src/streamer.ts:26 ## The issue `getDefaultStreamDispatcher` in `packages/world-vercel/src/http-client.ts` constructs a `RetryAgent` wrapping `STREAM_RETRY_OPTIONS` (`retryAfter: true`, `methods: ['PUT']`, `statusCodes: [429]`). So the stream-write dispatcher **does** retry — on undici's default transient connection errors and on HTTP 429. Two comments still claimed the opposite: 1. `packages/world-vercel/src/streamer.ts` (~line 26): > "That stream dispatcher is intentionally retry-free — stream appends aren't idempotent, so a retried write would duplicate chunks." 2. `packages/world-vercel/src/http-client.ts` (~line 102, JSDoc on `getStreamDispatcher`): > "See getDefaultStreamDispatcher for why this is a bare Agent (no retry)." Both are factually wrong: the dispatcher is a `RetryAgent`, not a bare `Agent`, and it is not retry-free. The accurate, nuanced description already lives in the `STREAM_RETRY_OPTIONS` and `getDefaultStreamDispatcher` JSDoc — these two comments were simply not updated when the behavior changed. ## Why it matters This is the **non-idempotent write path**. A maintainer reasoning about correctness here relies on these comments to understand exactly what is and isn't retried. "Retry-free" vs. "retries on transient errors + 429 but never 5xx" is a meaningful safety distinction, so the stale wording actively misleads. ## The fix Comment-only changes (no behavior change): - **streamer.ts**: replaced "intentionally retry-free" with wording reflecting the narrowed policy — retries only on transient connection errors + HTTP 429 (both guaranteeing the chunk was never persisted), never 5xx, so a retry can't duplicate an already-applied write. Points to `STREAM_RETRY_OPTIONS`. - **http-client.ts**: replaced "why this is a bare Agent (no retry)" with a reference to the deliberately narrowed retry policy in `getDefaultStreamDispatcher` / `STREAM_RETRY_OPTIONS`. Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com> Co-authored-by: VaguelySerious <mittgfu@gmail.com>
…ide effect Document that the createRequire banner deliberately makes `typeof require` truthy for every bundled dependency in the ESM server output, why that is safe (server-only, guarded, functional require), and the one residual behavior to watch (require() of an ESM-only dep on old Node). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
karthikscale3
approved these changes
Jun 24, 2026
Contributor
Backport PR opened against |
This was referenced Jun 24, 2026
This was referenced Jun 25, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Enable HTTP/2 for two hot
@workflow/world-vercelrequest paths, and fix the framework bundling that previously made H2 impossible on Vite-based adapters.events-v4.ts) — an event write per step transition plus event-log reads on replay. Gets its own H2 undici dispatcher (getEventsDispatcher).streamer.tswrite/writeMulti/close— the PUT path) — routed through a dedicated H2 stream dispatcher (getStreamDispatcher). These send a fully-buffered body (or none), so they get H2 multiplexing without the duplex issues that keep the long-lived live-read (GET) on plainfetch. The stream dispatcher is a bareAgentwithout the RetryAgent wrapper: stream appends aren't idempotent, so undici-level retry is deliberately omitted to avoid duplicating chunks.Everything else stays on HTTP/1.1 (queue client / webhook respondWith, v3
makeRequest, deployment resolution, run-key fetch, live-read GET, list).The bundling fix (why H2 was blocked before)
H2 had been disabled because it "broke SvelteKit on Vercel prod." Root cause: Vite/Rollup-based framework builds (SvelteKit, TanStack Start, plain Vite) bundle undici into the ESM server output. undici imports most
node:builtins as ESM, but loadsnode:http2lazily via a barerequire('node:http2')inside a try/catch. The bundler leaves that barerequireun-wired, so in the ESM bundle it throws and undici silently falls back to a stub whosehttp2.connectisundefined. Any H2 request then fails withfetch failed→ the workflow flow-route callback can't reach the backend → runs never leavepending→ 30-minute E2E timeouts. Frameworks that externalize undici (Express, Astro, Next, Hono, Nitro, …) were unaffected.Fix: inject a
createRequire-backed globalrequireinto the server build (server-only — anode:moduleimport would break the client bundle) so the realnode:http2resolves:@workflow/sveltekit— viaconfigResolved(SvelteKit doesn't setenv.isSsrBuildfor its server pass;build.ssron the resolved config is the reliable signal).@workflow/nitro— via the existingrollup:beforehook, covering Vite, TanStack Start, and Nitro from one place.Verified end-to-end: with the fix, the sveltekit / vite / tanstack-start E2E Vercel Prod lanes pass, and
http2.connect is not a functionerrors drop to zero (previously deterministic on this branch only).Why the default dispatcher stays H1
Enabling H2 on the shared dispatcher deadlocks the queue's webhook respondWith mechanism (120s timeouts on the webhook/hook workflows). So H2 is scoped to the events + stream-write paths, which don't use that mechanism.
Tests
EVENTS_AGENT_OPTIONS.allowH2 === trueandDEFAULT_AGENT_OPTIONS.allowH2 === false.getEventsDispatcherandgetStreamDispatchereach return their own shared singleton — distinct from the default and from each other — and honor a caller-supplied dispatcher.node:http2TLS server test: a request through the globalfetchwith anallowH2dispatcher negotiatesh2(the mechanism these paths rely on).@workflow/world-vercelunit suite passes (172 tests).Notes
events-v4.tsand the stream writes stay on the Vercel-patched globalfetch(preserves observability instrumentation); only the dispatcher they pass changes.sleepingWorkflowanddistributedAbortControllerfailures seen on some lanes are pre-existing flakes (zero-tolerance server-side sleep timing / abort timeout) that also fail onmain— unrelated to this change.🤖 Generated with Claude Code