Uh oh!
There was an error while loading. Please reload this page.
[world-vercel] Unify HTTP request handling into a shared core - #2631
Merged
Conversation
Collapse the duplicated cross-cutting request logic across world-vercel's request paths into one shared module (http-core.ts): - errorForResponse: single status -> typed-error map (409/410/425/429/else), shared by the v3 makeRequest and v4 throwForErrorResponse paths. - getVercelDiagnostics / parseRetryAfter / httpLog / logCurlRepro: one copy each (were duplicated across utils.ts and streamer.ts). - resolveVercelApiToken: shared token precedence for the direct Vercel-API calls (was byte-identical in encryption.ts and resolve-latest-deployment.ts). - instrumentedFetch: the shared OTEL-span + trace-injection + cache-bust + timeout + DEBUG-logging + error envelope. Route the v4 events, stream write/read, and Vercel-API (run-key / resolve-latest-deployment) paths through instrumentedFetch so they gain the OTEL client spans and DEBUG logging the v3 path already had. Stream writes now also inject W3C trace context (previously missing). Collapse the three dispatcher singletons in http-client.ts behind a single makeRetryDispatcher factory. No behavior change beyond the added observability: per-path error-message formats, the non-idempotent stream retry policy, and the no-timeout semantics of the v4/stream/Vercel-API paths are preserved. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
🦋 Changeset detectedLatest commit: 9263886 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
📊 Benchmark Results
workflow with no steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) workflow with 1 step💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 10 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 25 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) workflow with 50 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express Promise.all with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | 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: Express | Nitro | Next.js (Turbopack) Promise.race with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) 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: Express | Next.js (Turbopack) | Nitro workflow with 10 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) workflow with 25 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | 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: Express | Nitro | Next.js (Turbopack) workflow with 50 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) Stream Benchmarks(includes TTFB metrics)workflow with stream💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) stream pipeline with 5 transform steps (1MB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) 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: Express | Nitro | Next.js (Turbopack) SummaryFastest Framework by WorldWinner determined by most benchmark wins
Fastest World by FrameworkWinner determined by most benchmark wins
Column Definitions
Worlds:
|
Contributor
🧪 E2E Test Results✅ All tests passed Summary
Details by Category✅ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 🪟 Windows
✅ 📋 Other
|
Contributor
karthikscale3
approved these changes
Jun 28, 2026
karthikscale3
left a comment
Contributor
There was a problem hiding this comment.
Approving — reviewed against the merged OTEL trace-correlation work (linked-mode #2363, route/execution cohesion #2527, v4 injection #2533). No regressions; this is a net improvement.
What I verified:
- Injection is centralized + default-on:
injectTraceContext = trueininstrumentedFetch, inject runs inside thehttp <method>CLIENT span, and no caller passesfalse— so every path injects. - No bypass remains: the only raw
fetch(is insideinstrumentedFetch; all call sites (v4 events, makeRequest, streamer, both Vercel-API callers) route through it. Stronger guarantee than before. - v4 is fixed, not broken: #2533's inline injection moves into the core and v4 now gets a real client span (it had none), so workflow-server parents to it like v3. Stream + Vercel-API paths gain propagation.
- Span name + parenting preserved: still
http <method>/ CLIENT withPeerService/RpcService→ service-map edges and name-based queries intact; workflow-server still parents into the invocation trace (parent/child, not links). - Cohesion/linked mode untouched (only
world-vercel/*changed;runtime.ts/step-handler.ts/telemetry.tsare not in the diff). - Tests strengthened:
trace-propagation.test.tsasserts the v4 request's traceparent matches its client span and adds a stream-write propagation test.
One thing to confirm (see inline comment) + a doc follow-up.
| // Explicitly propagate trace context so the receiving server can parent | ||
| // its spans to this client span — the custom undici dispatcher bypasses | ||
| // ambient auto-instrumentation. No-ops when no OTEL SDK is registered. | ||
| if (injectTraceContext) await injectTraceContextIntoHeaders(headers); |
Contributor
There was a problem hiding this comment.
Since instrumentedFetch is now the single trace-context injection chokepoint, please update the AGENTS.md guardrail (Architecture Notes → "Trace context propagation (world-vercel HTTP requests)") before merge: it currently tells contributors to call injectTraceContextIntoHeaders directly, but the rule should now be "route new request paths through instrumentedFetch (injects W3C context by default)". That keeps the guidance pointing at this chokepoint so future paths inherit propagation automatically.
Also worth a conscious decision: the peerService: 'vercel-api' callers default to injectTraceContext: true, so they now send traceparentand baggage (incl. workflow.run_id/name) to vercel.com. Likely fine since it's first-party, but if that propagation isn't intended, pass injectTraceContext: false for those callers.
Contributor
No backport to This PR is an explicit follow-up to #2573 and the unified To override, re-run the Backport to stable workflow manually via |
VaguelySerious added a commit
that referenced
this pull request
Jul 31, 2026
Backport of #2631, adapted to stable. The v3 makeRequest path, the v4 events client, the stream write/close path and the direct Vercel API calls each had their own request envelope; the 412 -> PreconditionFailed and firewall-challenge-429 -> retryable TRANSPORT mappings were duplicated between utils.ts and events-v4.ts. http-core.ts now owns that envelope: the OTEL CLIENT span and its attributes, W3C trace-context injection, the X-Request-Time cache bust, the per-request deadline (mapped to a typed retryable WorkflowWorldError instead of an opaque AbortError), DEBUG logging with a curl repro, and the status -> typed-error mapping. utils.ts, events-v4.ts, streamer.ts, encryption.ts and resolve-latest-deployment.ts delegate to it. Behavioral gains on stable: the v4 events path and stream writes now emit client spans and propagate traceparent, so the backend can parent its spans to the caller without relying on the app having undici auto-instrumentation. Adapted rather than cherry-picked: stable keeps #3169's bounded headers/body timeouts (documented as firing ahead of the outer REQUEST_TIMEOUT_MS backstop), its body-parse retry loop, and #3038's write-vs-close stream dispatcher split. Only injectTraceContextIntoHeaders is taken from #2363, not its WORKFLOW_TRACE_MODE machinery. Routing v4 through the global fetch makes the H2 interceptor's re-buffering gate live on this path (fetch streamifies request bodies), so the new http-client test drives createWorkflowRunEventV4 concurrently against a local H2 server: 16 writes on one session with the interceptor, 8 without it.
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
Follow-up to #2573. world-vercel had five separate HTTP request paths, each re-implementing the same cross-cutting concerns inconsistently. This collapses the duplication into one shared core (
http-core.ts) and routes every path through it, so the v4 / stream / Vercel-API paths gain the OTEL client spans +DEBUGlogging the v3 path already had.Before
makeRequestThe v4 events path — now the hottest path — had no client span and no debug logging.
How
New
http-core.tsis the single source of truth for the request envelope:errorForResponse— the status → typed-error map (409→EntityConflictError, 410→RunExpiredError, 425→TooEarlyError, 429→ThrottleError, else→WorkflowWorldError). Was implemented twice (v3makeRequest+ v4throwForErrorResponse).getVercelDiagnostics/parseRetryAfter/httpLog/logCurlRepro— one copy each (were duplicated acrossutils.tsandstreamer.ts).resolveVercelApiToken— sharedtoken → VERCEL_TOKEN → OIDCprecedence (was byte-identical inencryption.tsandresolve-latest-deployment.ts).instrumentedFetch— shared OTEL span + trace-context injection + cache-bust header + timeout +DEBUGlogging + error envelope. The v4 events, stream, and Vercel-API paths now route through it.Also: stream writes now inject W3C trace context (previously missing, contrary to the documented requirement that every world→server request must), and the three dispatcher singletons in
http-client.tscollapse behind onemakeRetryDispatcherfactory.Behavior preserved
No behavior change beyond the added observability:
timeoutMs: null); only the v3 path keeps its 60s timeout.Tests
http-core.test.ts(error mapping per status,parseRetryAfter, diagnostics, token precedence).trace-propagation.test.ts: v4 now parents to its ownhttp GETclient span (matching v3), and a new case asserts stream writes injecttraceparent.Changeset
@workflow/world-vercelpatch — internal transport refactor + added observability, no API surface change.