Uh oh!
There was an error while loading. Please reload this page.
[core] Add wire-level framing for byte streams - #1853
Merged
Conversation
🦋 Changeset detectedLatest commit: 2dbcbb7 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: Express | Next.js (Turbopack) | Nitro workflow with 1 step💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | 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 | Express | Next.js (Turbopack) 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: Next.js (Turbopack) | Nitro | Express Promise.all with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Express | Next.js (Turbopack) 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: Next.js (Turbopack) | Express | Nitro Promise.race with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) workflow with 10 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express 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: Nitro | Express | Next.js (Turbopack) workflow with 10 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | 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: 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: Express | Next.js (Turbopack) | 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: Nitro | Next.js (Turbopack) | Express 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
There was a problem hiding this comment.
Pull request overview
Adds opt-in wire-level length-prefix framing for type: 'bytes'ReadableStreams, gated by target run capabilities, to preserve chunk boundaries on the wire and enable future transparent auto-reconnect.
Changes:
- Introduces byte-stream framing/unframing transforms and carries a per-stream
framingfield through serialization refs and VM symbols. - Adds
framedByteStreamscapability detection (viaworkflowCoreVersion) and uses a cross-deploymenthealthCheckprobe instart()to decide framing. - Updates producer/consumer sites (step return values,
getWritable,resumeHook, workflow argument dehydration) and adds dedicated tests + changeset.
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/core/src/symbols.ts | Adds STREAM_FRAMING_SYMBOL to persist framing choice through the VM boundary. |
| packages/core/src/step/writable-stream.ts | Forces framed byte-stream support when serializing values written from steps (same-deployment assumption). |
| packages/core/src/serialization.ts | Implements byte framing/unframing, adds framing to serialized stream refs, and threads framedByteStreams through reducers/revivers. |
| packages/core/src/runtime/step-handler.ts | Always enables framed byte streams for step return value dehydration (same-deployment assumption). |
| packages/core/src/runtime/start.ts | Adds capability probing for cross-deployment start() to decide whether to frame byte streams. |
| packages/core/src/runtime/resume-hook.ts | Uses run capabilities to decide whether to emit framed byte streams in hook resume payloads. |
| packages/core/src/runtime/helpers.ts | Parses and surfaces workflowCoreVersion from health check responses. |
| packages/core/src/capabilities.ts | Adds framedByteStreams capability with semver cutoff logic. |
| packages/core/src/capabilities.test.ts | Adds coverage for framedByteStreams cutoff/invalid-version behavior. |
| packages/core/src/byte-stream-framing.test.ts | Adds unit + e2e tests for framing/unframing and ref behavior. |
| .changeset/byte-stream-wire-framing.md | Declares a minor release for the new wire framing capability and 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.
Uh oh!
There was an error while loading. Please reload this page.
The responding deployment already advertises its `@workflow/core` version
on the wire via `handleHealthCheckMessage` (`helpers.ts:109`), but it was
dropped at the parsing step. Surface it on `HealthCheckResult` so
callers can derive capability metadata about a target deployment before
sending it work — for example, version-gated decisions via
`getRunCapabilities()`.
Backwards compatible:
- Older deployments with plain-text health responses (specVersion < 3)
yield `{ healthy: true }` with no version metadata, as before.
- Older deployments with JSON responses but no `workflowCoreVersion`
field continue to return `{ healthy, specVersion? }`; the field is
simply omitted from the result.
- Defensive type check rejects non-string values rather than passing
them through as garbage.
Tests cover all four cases (workflowCoreVersion present, missing,
wrong type, plain-text legacy response) via a small in-memory mock
world plus a new e2e assertion.TooTallNateforce-pushed
the
nate/byte-stream-framing
branch
from
April 25, 2026 07:31
cc06349 to
90d9e65Compare
VaguelySerious
left a comment
Member
There was a problem hiding this comment.
AI review: no blocking issues
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.
VaguelySerious
commented
Jun 10, 2026
Member
(AI) Cross-PR context & merge order Together these make How the pieces fit:
Behavioural note: the reconnecting reader only reopens on a connection error — a clean close means "complete". So the client change is inert on its own and only takes effect once paired with the coordinated server-side change that ends a timed-out connection with an error rather than a silent close (handled separately). Shipping the client first is therefore safe and must precede that server change. Suggested order:
#1853 is independent and can land on its own schedule; it unblocks byte-stream reconnect as a future follow-up. |
The placeholder cutoff (5.0.0-beta.3) predates several published betas that do not contain the unframing reader. A producer probing a beta.3..beta.13 target would wrongly write framed bytes that the consumer cannot decode. Pin the capability to the next unpublished beta and leave a TODO(release) marker to re-verify at release time.
5.0.0-beta.14 was published (Version Packages #2326) without this PR, so beta.14 consumers have no unframing reader. Move the cutoff to the next unpublished beta per the TODO(release) marker.
…test rename - getByteFramingStream now rejects chunks over MAX_FRAME_SIZE at write time (shared constant with the unframer), so an oversized chunk fails where the error is actionable instead of producing a frame the consumer refuses to decode - Document the one-frame-per-stored-chunk invariant that future byte-stream reconnect resume arithmetic depends on - Rename the wire-level round-trip test to describe what it exercises (the ref-dispatch claim it previously made is covered by the dehydrateStepReturnValue round-trip tests above it)
VaguelySerious
approved these changes
Jun 12, 2026
VaguelySerious
left a comment
Member
There was a problem hiding this comment.
(AI) AI review: no blocking issues
Re-reviewed on the current tip (merge of main is resolved and the branch merges into main cleanly). Conflicts that existed earlier — from the #2318 reconnect work touching the same type: 'bytes' reviver branch — are resolved, and the earlier review nits are addressed (write-time MAX_FRAME_SIZE cap, one-frame-per-stored-chunk invariant doc, test rename, version cutoff bumped).
Validated:
- Core suites pass locally — byte-stream-framing (17), capabilities (28), reconnecting-framed-stream (11), serialization (406); CI shows no failing checks.
- Framer/unframer round-trip is correct under adversarial transport re-chunking, including the 4-byte length header split across reads and reads straddling a frame boundary (checked with an extra one-off). Symmetric size caps on both sides;
flusherrors on truncated trailing data; empty-chunk drop is intentional and avoids the[0,0,0,0]sniff collision. - Capability gating is backward-compatible: same-deployment → framed; cross-deployment probes
healthCheckwith a tight timeout and falls back to raw on miss/old version, so a run started against an older deployment emits raw bytes it can read. The ref carriesframingonly when capable; absent/rawrefs read unchanged. - Post-merge reviver coexists correctly with reconnect: byte streams stay on the raw path (no reconnect), object streams use the reconnecting wrapper.
AI Review: Note (non-blocking, fine as follow-ups)
appendToBufferin the unframer reallocates the pending buffer on every transport read (O(n²) with many tiny chunks). Only matters for pathological chunking on the opt-in framed path.- The cross-deployment probe adds a synchronous (≤2s on a cached miss) round-trip to
start(); acceptable given the raw fallback, but worth caching per-deployment if cross-deploymentstart()becomes hot.
This was referenced Jun 12, 2026
Contributor
Backport PR opened against |
This was referenced Jun 12, 2026
Merged
This was referenced Jun 17, 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
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
Wraps each chunk of
type: 'bytes'ReadableStreams in a 4-byte big-endian length prefix on the wire, so consumers can identify chunk boundaries. The user-facing API is unchanged —getReader()still yields rawUint8Arraychunks; only the wire envelope is new.This enables byte-stream auto-reconnect to be added in a follow-up: with frames on the wire, a reconnecting reader can count completed frames and resume from
startIndex + consumedafter a transient error — the same trick the object-stream reconnecting reader uses.Mechanism
The framing decision is made per-stream at serialization time and recorded in the stream ref:
Readers dispatch on the field. Absent or
'raw'→ existing legacy behavior (no unframing).'framed-v1'→ pipe throughgetByteUnframingStream()to strip the length prefix before handing chunks to the user.Capability gating
Producers consult a new
framedByteStreamscapability ingetRunCapabilities(), keyed on the target run'sworkflowCoreVersion, and bake the choice into the ref so consumers don't re-do the lookup. Same-deployment/same-run producers always frame; cross-deploymentstart()probes the target viahealthCheck()(2s timeout) and falls back to raw on miss/timeout. Older runs whose refs lackframingare read as raw bytes.Relationship to the reconnect work
Independent of, and not blocking, the object-stream reconnect PRs (#1847 on
stableand itsmainforward-port), which deliberately opt byte streams out. This PR lays the groundwork so a later follow-up can extend the same frame-counting reconnect toframing: 'framed-v1'byte streams without touching the legacy raw path. See the cross-PR comment for ordering.Tests
byte-stream-framing.test.ts(new): framing/unframing prefix shape, empty-chunk drop, large chunks, split/coalesced frames across reads, mid-frame truncation + oversized-frame guards, and end-to-end round-trips for bothframedByteStreamson/off.capabilities.test.ts(extended):framedByteStreamsfalse for invalid/old versions, true from the cutoff onward.Notes
The
minVersionforframedByteStreamsis set based on the next beta release — update if the actual ship version differs. The'framed-v1'identifier is opaque so future framing variants can be added without breaking existing consumers.