Uh oh!
There was an error while loading. Please reload this page.
[world-vercel] Runtime HTTP/2 → HTTP/1.1 fallback for bundled ESM servers - #2633
Open
VaguelySerious wants to merge 4 commits into
Open
[world-vercel] Runtime HTTP/2 → HTTP/1.1 fallback for bundled ESM servers#2633VaguelySerious wants to merge 4 commits into
VaguelySerious wants to merge 4 commits into
Conversation
… fallback)
undici loads node:http2 lazily via a bare require('node:http2'). When
world-vercel is bundled into an ESM server (a custom Vite/Rollup/esbuild build,
or any consumer that doesn't externalize undici), there is no require in scope:
the call throws, undici falls back to a stub with no http2.connect, and every
HTTP/2 request (the events API + stream writes) hangs on a dead connection
through RetryAgent's backoff (~16s) then fails. Framework integrations have been
patching this one bundler at a time with a build banner; a custom or third-party
bundled consumer gets no protection.
Move the defense into the package itself, two layers:
A. Install a working `globalThis.require` (createRequire-backed) at module load
so undici's bare require resolves the real node:http2 regardless of how a
consumer bundles us. Guarded to a no-op wherever a real require already
exists.
B. Detect whether node:http2 is actually usable and, if not, build the H2
dispatchers with allowH2:false and warn once — so requests degrade to working
HTTP/1.1 instead of silently failing.
Exports isHttp2Available() and shouldFallBackToH1() with unit coverage,
including a simulated bundled-undici stub (http2 without connect).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>🦋 Changeset detectedLatest commit: 6988e7f 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
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
workflow with 1 step💻 Local Development
workflow with 10 sequential steps💻 Local Development
workflow with 25 sequential steps💻 Local Development
workflow with 50 sequential steps💻 Local Development
Promise.all with 10 concurrent steps💻 Local Development
Promise.all with 25 concurrent steps💻 Local Development
Promise.all with 50 concurrent steps💻 Local Development
Promise.race with 10 concurrent steps💻 Local Development
Promise.race with 25 concurrent steps💻 Local Development
Promise.race with 50 concurrent steps💻 Local Development
workflow with 10 sequential data payload steps (10KB)💻 Local Development
workflow with 25 sequential data payload steps (10KB)💻 Local Development
workflow with 50 sequential data payload steps (10KB)💻 Local Development
workflow with 10 concurrent data payload steps (10KB)💻 Local Development
workflow with 25 concurrent data payload steps (10KB)💻 Local Development
workflow with 50 concurrent data payload steps (10KB)💻 Local Development
Stream Benchmarks(includes TTFB metrics)workflow with stream💻 Local Development
stream pipeline with 5 transform steps (1MB)💻 Local Development
10 parallel streams (1MB each)💻 Local Development
fan-out fan-in 10 streams (1MB each)💻 Local Development
SummaryFastest Framework by WorldWinner determined by most benchmark wins
Fastest World by FrameworkWinner determined by most benchmark wins
Column Definitions
Worlds:
❌ Some benchmark jobs failed:
Check the workflow run for details. |
…-vercel) world-vercel installs the global `require` shim itself (and falls back to H1 when node:http2 is unreachable), so the per-bundler banners in the nitro and sveltekit integrations are redundant. Remove them; their e2e-vercel-prod lanes (nitro, vite, tanstack-start via nitro; sveltekit) now validate that world-vercel's built-in shim carries those bundles on its own. The @workflow/web banner is intentionally kept for now — workflow-web has no e2e coverage, so it stays as belt-and-suspenders until a deployed-web smoke test exists. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
VaguelySerious
marked this pull request as ready for review
June 25, 2026 22:55
Replace the load-time `node:http2` capability probe (which checked `globalThis.require`, the wrong binding — it false-positives in bundlers like nitro/rollup where undici's `require` is a tool-injected per-chunk binding the global never reaches, so it kept H2 on and still hung) with a runtime fallback. `fetchWithH2Fallback(path, ...)` issues the request over the H2 dispatcher and, on the bundling failure signature (`http2.connect is not a function` — detected via `isHttp2ConnectUnavailableError`), retries the same request on an HTTP/1.1 dispatcher and latches the downgrade process-wide so later requests skip the dead H2 attempt and its ~16s connect-retry backoff. The connect failure is pre-send, so the replay is safe even for the non-idempotent stream writes; the stream fallback preserves STREAM_RETRY_OPTIONS (never retries 5xx). This recovers regardless of how the bundler bound undici's `require`, unlike the probe. Layer A (the global `require` self-install) stays as a best-effort H2 preserver; the framework banners remain for full H2 perf where we ship a builder. Routes v4 events and stream write/close through the new helper. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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
1 participant
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.
Problem
When
@workflow/world-vercelis bundled into an ESM server output (a custom Vite/Rollup/esbuild build, or a framework integration that doesn't externalize undici), undici's lazyrequire('node:http2')can be left un-wired. undici swallows the failure and falls back to a stub whosehttp2.connectisundefined, so the first HTTP/2 connect throwshttp2.connect is not a function— surfacing (after undici's ~16s connect-retry backoff) as a failed request. On the events/stream H2 paths this silently breaks observability reads (and stream writes) for any such consumer.What this does
A runtime HTTP/2 → HTTP/1.1 fallback, plus a best-effort H2 preserver:
fetchWithH2Fallback(path, …)issues the request over the H2 dispatcher and, on the bundling failure signature (isHttp2ConnectUnavailableError), retries the same request on an HTTP/1.1 dispatcher and latches the downgrade process-wide so later requests skip the dead H2 attempt and its ~16s backoff. The connect failure is pre-send, so replaying is safe even for the non-idempotent stream writes — and the stream fallback preservesSTREAM_RETRY_OPTIONS(never retries 5xx). v4 events and stream write/close now route through this helper.requireself-install) stays as a best-effort H2 preserver: where undici's bundledrequireis a free identifier it restores real H2; where it isn't (notably nitro/rollup per-chunk bindings) the runtime fallback covers correctness.Why the previous load-time probe was replaced
The earlier approach probed
globalThis.require('node:http2')at load time to decide whether to keep H2. That checks the wrong binding: in bundlers like nitro/rollup undici'srequireresolves to a tool-injected per-chunk binding the global never reaches, so the probe false-positived (saw H2 "available", keptallowH2: true) and the request still hung. The runtime fallback triggers on the actual connect failure, so it recovers regardless of how the bundler bound undici'srequire.The framework build banners (
@workflow/sveltekit,@workflow/nitro,@workflow/web) remain the way to keep full H2 performance in the bundlers we ship a builder for; this is the correctness catch-all for consumers we don't.Verification
@workflow/world-vercelsuite green (182 tests), typecheck + lint clean.isHttp2ConnectUnavailableErrorsignature matching (incl. minified.connect, non-match on ECONNREFUSED/unrelated/nullish);fetchWithH2Fallbackretry-on-distinct-H1-dispatcher, downgrade latching, stream-policy preservation, non-H2 rethrow, override-verbatim.http2.connect = undefined) against a dual h1/h2 server —fetchWithH2Fallback('events', …)returns 200 over HTTP/1.1 after the H2 backoff (call update docs sidebar to auto expand #1 ~15.6s), and call Home tweaks #2 is ~9ms (latched to H1).🤖 Generated with Claude Code