Repository navigation
Add WebSocket transport for step-execution event writes (opt-in) #3084
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| --- | ||
| '@workflow/world-vercel': minor | ||
| '@workflow/builders': patch | ||
| '@workflow/rollup': patch | ||
| '@workflow/next': patch | ||
| --- | ||
|
|
||
| Add an opt-in WebSocket transport for event writes during step execution, enabled with `WORKFLOW_EVENTS_TRANSPORT=ws`. Defaults to HTTP; no behavior change unless explicitly enabled. |
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
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -273,3 +273,11 @@ Platform-provided values such as `VERCEL_DEPLOYMENT_ID`, `VERCEL_PROJECT_ID`, an | |
| - CLI flag: none | ||
| - Default: `1000` | ||
| - Maximum stream chunks written in one Vercel World request. Larger batches are split. | ||
|
|
||
| ### `WORKFLOW_EVENTS_TRANSPORT` | ||
|
|
||
| - Factory option: none | ||
| - CLI flag: none | ||
| - Default: `http` | ||
| - Experimental. Set to `ws` to ship workflow run events to the Vercel World over a WebSocket instead of one HTTP request each. | ||
| - Ignored when the World is configured with `projectConfig` and routes through the `api-workflow` proxy — that endpoint is an HTTP-only REST gateway and does not forward a WebSocket upgrade, so events stay on HTTP. | ||
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -196,6 +196,12 @@ Per-request timeout, in milliseconds, for Vercel World HTTP calls to workflow-se | |
|
|
||
| Maximum stream chunks written in one Vercel World request. Larger batches are split across multiple requests. Default: `1000`. Minimum: `1`. | ||
|
|
||
| ### `WORKFLOW_EVENTS_TRANSPORT` | ||
|
|
||
| Experimental. Set `WORKFLOW_EVENTS_TRANSPORT=ws` to ship workflow run events to the Vercel World over a WebSocket instead of one HTTP request each. Default: `http`. | ||
|
|
||
| The setting is ignored when the World is configured with `projectConfig` and therefore routes through the `api-workflow` proxy: that endpoint is an HTTP-only REST gateway and does not forward a WebSocket upgrade, so events stay on HTTP and a warning is logged once per process. | ||
|
|
||
| ### Programmatic configuration | ||
|
|
||
| `createWorld()` accepts explicit API configuration. It does not read `WORKFLOW_VERCEL_*` automatically, so pass the environment values yourself when you want a configured World module: | ||
|
|
||
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -32,6 +32,7 @@ export { | |
| export { createNodeModuleErrorPlugin } from './node-module-esbuild-plugin.js'; | ||
| export { WORKFLOW_OPTIONAL_OTEL_API_MODULE } from './optional-otel-api.js'; | ||
| export { WORKFLOW_OPTIONAL_TYPESCRIPT_ALIAS } from './optional-typescript-alias.js'; | ||
| export { WORKFLOW_OPTIONAL_WS_NATIVE_MODULES } from './optional-ws-native.js'; | ||
| export { | ||
| createPseudoPackagePlugin, | ||
| PSEUDO_PACKAGES, | ||
|
|
||
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,32 @@ | ||
| /** | ||
| * `bufferutil` and `utf-8-validate` are optional native accelerators for the | ||
| * `ws` package, which `@workflow/world-vercel` uses for its WebSocket events | ||
| * transport. Neither is installed by default: `ws` requires each one inside a | ||
| * try/catch and falls back to a pure-JS implementation when the require throws. | ||
| * | ||
| * Marking them external keeps that fallback reachable. Two bundlers take it away | ||
| * without changing the build's outcome, so the damage only shows up at runtime, | ||
| * on the first frame big enough to reach the native masker (`ws` uses pure JS | ||
| * below 48 bytes — small-payload smoke tests pass; CBOR event frames don't): | ||
| * | ||
| * - **webpack** bundles the JS wrapper without its native `.node` binding. | ||
| * - **Vite** resolves the absent peer to its own `optional-peer-dep` stub, so | ||
| * `ws`'s require *succeeds* and the try/catch never fires. | ||
| * | ||
| * Both end at `bufferUtil.mask is not a function`. Rollup-family setups are not | ||
| * known to break: nothing substitutes a stub, and nitro traces and externalizes | ||
| * `ws` in a production build, so the require stays a real one that fails and the | ||
| * fallback engages. Externalizing there buys determinism against a change in | ||
| * externals policy, not a fix for a known break. (Turbopack already externalizes | ||
| * Node packages.) | ||
| * | ||
| * Externalized unconditionally, unlike `WORKFLOW_OPTIONAL_OTEL_API_MODULE`, | ||
| * which is only externalized when it can't be resolved. The OTEL API has to | ||
| * load for tracing to work, so a self-contained output must bundle it when | ||
| * present; these accelerators must specifically *not* load, so a failed runtime | ||
| * require is the designed path and a half-bundled native module is not. | ||
| */ | ||
| export const WORKFLOW_OPTIONAL_WS_NATIVE_MODULES = [ | ||
| 'bufferutil', | ||
| 'utf-8-validate', | ||
| ] as const; |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -4,6 +4,7 @@ import { dirname, isAbsolute, join } from 'node:path'; | |
| import { | ||
| resolveConfiguredProjectRoot, | ||
| resolveProjectRoot, | ||
| WORKFLOW_OPTIONAL_WS_NATIVE_MODULES, | ||
| } from '@workflow/builders'; | ||
| import type { NextConfig } from 'next'; | ||
| import semver from 'semver'; | ||
|
|
@@ -321,6 +322,26 @@ function registerWorkflowDiagnosticsManifestCopy(metadata: { | |
| globalWithMarker[marker].push(metadata); | ||
| } | ||
|
|
||
| /** | ||
| * Mark `ws`'s optional native accelerators external on the webpack server | ||
| * build, which otherwise bundles their JS wrapper without the native `.node` | ||
| * binding and throws "bufferUtil.mask is not a function" at runtime. See | ||
| * `WORKFLOW_OPTIONAL_WS_NATIVE_MODULES`; `@workflow/rollup` handles the | ||
| * Rollup/Vite/Nitro side. | ||
| */ | ||
| function externalizeWsNativeAccelerators(webpackConfig: { | ||
| externals?: unknown; | ||
| }): void { | ||
| const names = [...WORKFLOW_OPTIONAL_WS_NATIVE_MODULES]; | ||
| if (Array.isArray(webpackConfig.externals)) { | ||
| webpackConfig.externals.push(...names); | ||
| } else if (webpackConfig.externals) { | ||
| webpackConfig.externals = [webpackConfig.externals, ...names]; | ||
| } else { | ||
| webpackConfig.externals = names; | ||
| } | ||
| } | ||
|
|
||
| export function withWorkflow( | ||
| nextConfigOrFn: | ||
| | NextConfig | ||
|
|
@@ -571,6 +592,10 @@ export function withWorkflow( | |
| loader: loaderPath, | ||
| }); | ||
|
|
||
| if (args[1]?.isServer) { | ||
| externalizeWsNativeAccelerators(webpackConfig); | ||
| } | ||
|
|
||
| return existingWebpackModify | ||
| ? (existingWebpackModify(...args) ?? webpackConfig) | ||
| : webpackConfig; | ||
|
|
||
Oops, something went wrong.
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
AI Review: Note
There is no latency measurement for the WS path anywhere in the PR, even though latency is the motivation.
benchmarks.ymlnever setsWORKFLOW_EVENTS_TRANSPORTand waits on the passive deployment, so the benchmark referenced in the Testing section is measuring HTTP. Since this job already stands up its own deployment with the flag set, it is the cheapest place to capture a before/after number worth deciding the default on.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Dropping a durabench screenshot here for reference. This force enabled websockets so there is promise. Shows consistent STSO p75 drop.