Uh oh!
There was an error while loading. Please reload this page.
[world-vercel] Validate ref resolve responses before use - #2035
Merged
Conversation
When workflow-server returns a ref body to the SDK, the bytes are fed into the workflow runtime's event log and deserialized via `decodeFormatPrefix`. The SDK always writes ref payloads with at least a 4-byte format prefix (see `encodeWithFormatPrefix` in `@workflow/core`), so a zero-byte response — or one whose length disagrees with `Content-Length` — is never a valid stored value. Before this change, `resolveRefDescriptor` had no validation: a 200 with an empty body would be passed downstream as a zero-length Uint8Array, which then failed deep inside replay with: Data too short to contain format prefix: expected at least 4 bytes, got 0 By that point the workflow's in-memory event snapshot is already poisoned with the empty payload, so every subsequent replay deterministically reproduces the same failure, downstream `resumeHook()` calls surface as `Hook not found`, and the run only unsticks when stale-run cleanup terminates the sandbox. This catches the failure at the transport boundary instead, where it can be retried as a `WorkflowWorldError`. Both an empty body and a length mismatch (truncated streaming response) are rejected. This is the SDK-side companion to vercel/workflow-server#432, which adds the same validation on the server side.
🦋 Changeset detectedLatest commit: c8f5dce 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
📊 Benchmark Results
workflow with no steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro workflow with 1 step💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) workflow with 10 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) workflow with 25 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) workflow with 50 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) Promise.all with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) Promise.all with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) Promise.all with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) Promise.race with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) Promise.race with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) Promise.race with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro workflow with 10 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro workflow with 25 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) workflow with 50 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) workflow with 10 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro workflow with 25 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) workflow with 50 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) Stream Benchmarks(includes TTFB metrics)workflow with stream💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) stream pipeline with 5 transform steps (1MB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) 10 parallel streams (1MB each)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) fan-out fan-in 10 streams (1MB each)💻 Local Development
▲ Production (Vercel)
🔍 Observability: 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:
❌ Some benchmark jobs failed:
Check the workflow run for details. |
Contributor
🧪 E2E Test Results✅ All tests passed Summary
Details by Category✅ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 🪟 Windows
✅ 📋 Other
|
Contributor
There was a problem hiding this comment.
Pull request overview
Adds defensive validation to @workflow/world-vercel ref resolution so empty/truncated ref payloads don’t propagate into replay/hydration and wedge runs during deterministic replay.
Changes:
- Validate
GET /v2/runs/:runId/refsbodies for zero-length andContent-Lengthmismatches, throwingWorkflowWorldErrorwith specific error codes. - Add a new Vitest suite covering happy paths, zero-byte 200s,
Content-Lengthmismatch, non-2xx passthrough, and inlinedbrfbehavior. - Add a patch changeset for
@workflow/world-vercel.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| packages/world-vercel/src/refs.ts | Adds response body validation (empty body and Content-Length mismatch) before decoding/returning ref payloads. |
| packages/world-vercel/src/refs.test.ts | Introduces unit tests for ref resolution behavior across success/error/edge cases. |
| .changeset/world-vercel-reject-empty-ref-payload.md | Declares a patch release for the new validation behavior. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Three review changes: 1. Reject any body shorter than the 4-byte format-prefix length, not just zero-byte bodies. The SDK guarantees every stored ref payload starts with a 4-byte format prefix (FORMAT_PREFIX_LENGTH in @workflow/core), so a 1-3 byte body would also fail downstream replay with the same 'Data too short to contain format prefix' error this PR exists to prevent. 2. Parse Content-Length safely with parseInt + Number.isFinite + non-negative checks instead of bare Number(). A non-numeric value like 'abc' would otherwise produce NaN and silently surface as a 'truncated' error, masking the real cause. Malformed values are treated as absent; the minimum-length check still defends against actual truncation in that case. 3. Add tests for the truncated-body-without-Content-Length case (chunked transfer where Content-Length validation can't see the truncation), and for a malformed Content-Length header that should be ignored rather than misreported as truncation. The validation logic also moves into a small assertValidRefBody helper to keep the inner trace function under the noExcessiveCognitiveComplexity limit.
karthikscale3
requested changes
Jun 8, 2026
karthikscale3
left a comment
Contributor
There was a problem hiding this comment.
Potential blocker in PR-version packages/world-vercel/src/refs.ts:143: the new Content-Length check compares response.arrayBuffer().byteLength to the header without accounting for Content-Encoding. Node fetch transparently decompresses gzip bodies while preserving the encoded Content-Length, so a valid compressed ref response can now throw ref-body-length-mismatch. I’d skip this check when Content-Encoding is present and not identity, or force/request identity encoding.
fetch/undici transparently decompresses gzip/br bodies but leaves Content-Length describing the encoded (compressed) size, so comparing it against the decompressed byteLength would reject valid compressed refs as a phantom 'ref-body-length-mismatch'. Skip the comparison when a non-identity Content-Encoding is present; an absent or 'identity' encoding is still validated. Adds regression tests for both cases.
TooTallNate
commented
Jun 8, 2026
MemberAuthor
@karthikscale3 great catch — fixed in c8f5dce. You're right: The length comparison is now skipped whenever a non- Added two regression tests:
|
Contributor
Backport PR opened against |
This was referenced Jun 8, 2026
Merged
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
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.
Summary
Adds defense-in-depth validation in
resolveRefDescriptorso a zero-byte or truncated ref response fromGET /v2/runs/:runId/refsno longer corrupts the in-memory event log during workflow replay.The workflow runtime feeds ref payload bytes directly into
decodeFormatPrefix, which requires at least the 4-byte format prefix that the SDK always writes (encodeWithFormatPrefixin@workflow/core). A zero-byte response is therefore never a valid stored value.Before this change,
resolveRefDescriptorcheckedresponse.okand then handed the emptyarrayBuffer()downstream verbatim. Multiple users have reported the resulting failure:That error surfaces deep inside deterministic replay. Because the SDK has already populated its in-memory event snapshot with the empty payload at that point, the run is wedged: every subsequent invocation deterministically replays the same failure, any downstream
resumeHook()then surfaces asHook not found, and the run only clears when stale-run cleanup terminates the sandbox.Changes
packages/world-vercel/src/refs.ts:await response.arrayBuffer(), validatebuffer.byteLength > 0. Empty bodies throw aWorkflowWorldErrorwithcode: 'empty-ref-body'.Content-Lengthis present, validate it matches the actual body length. Truncated responses (proxy abort, upstream stream cut mid-flight) throwWorkflowWorldErrorwithcode: 'ref-body-length-mismatch'.recordExceptionand tagErrorTypefor o11y.packages/world-vercel/src/refs.test.ts(new):application/octet-stream).Content-Lengthmismatch (truncated stream).Content-Length(chunked transfer encoding) — happy path only.HTTP <code>.dbrfrefs decode without making a network request.@workflow/world-vercelpatch.Why both ends validate
This is the SDK-side companion to vercel/workflow-server#432, which rejects zero-byte payloads at the storage boundary. Both layers are necessary because they catch failures at different points in the stack:
undiciquirks, etc.).WorkflowWorldErroris treated as a retryable transport-level error by the runtime, which is the desired behavior here: surface the empty/truncated body up to the retry layer instead of poisoning event-log replay.Validation
pnpm --filter @workflow/world-vercel typecheckpnpm --filter @workflow/world-vercel test(77 tests pass, including 8 new inrefs.test.ts)pnpm --filter @workflow/world-vercel buildpnpm biome check --files-ignore-unknown=true packages/world-vercel/src/refs.ts packages/world-vercel/src/refs.test.tspnpm changeset status --since=main(confirms@workflow/world-vercelpatch bump)