Uh oh!
There was an error while loading. Please reload this page.
[codex] Migrate workflow execution routes to v2 - #2154
Conversation
🦋 Changeset detectedLatest commit: e20540c The changes in this PR will be included in the next version bump. This PR includes changesets to release 21 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 |
📊 Benchmark Results
workflow with no steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express workflow with 1 step💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express workflow with 10 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express workflow with 25 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express workflow with 50 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express Promise.all with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express Promise.all with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express Promise.all with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express Promise.race with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express Promise.race with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express Promise.race with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express workflow with 10 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express workflow with 25 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express workflow with 50 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express workflow with 10 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express workflow with 25 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express workflow with 50 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express Stream Benchmarks(includes TTFB metrics)workflow with stream💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express stream pipeline with 5 transform steps (1MB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express 10 parallel streams (1MB each)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express fan-out fan-in 10 streams (1MB each)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express 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. |
🧪 E2E Test Results✅ All tests passed Summary
Details by Category✅ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 📋 Other
❌ Some E2E test jobs failed:
Check the workflow run for details. |
There was a problem hiding this comment.
Pull request overview
This PR migrates the canonical workflow execution and webhook endpoints from /.well-known/workflow/v1/ to /.well-known/workflow/v2/. The combined flow handler at v2 now serves both workflow and step queue messages (the separate v1/step route is no longer emitted). The webhook endpoint is also moved to v2, while /.well-known/workflow/v1/webhook/:token remains supported as a compatibility alias across all integrations. The v1 directory continues to host manifest.json and webhook compatibility resources, and builders proactively clean up stale v1 execution artifacts from prior builds.
Changes:
- Update all queue clients, builders, framework integrations, and tests to use
/.well-known/workflow/v2/flowand/.well-known/workflow/v2/webhook/:token. - Preserve
/.well-known/workflow/v1/webhook/:tokenas a compatibility route in Next, Nitro, Nest, Sveltekit, Astro, BOA, and standalone builds. - Clean stale v1
flow/step/config.json/manifest.jsonartifacts on each build/boot to avoid cached v1 outputs leaking into v5 deployments.
Reviewed changes
Copilot reviewed 46 out of 46 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
.changeset/workflow-v2-routes.md | New changeset noting the v2 route migration for all affected packages. |
.github/workflows/tests.yml, .github/workflows/e2e-community-world.yml | Update CI dev-test config paths to v2 generated routes. |
AGENTS.md | Document that execution routes are now v2; v1 retains manifest/webhook compatibility. |
docs/content/docs/v5/** | Documentation updated for v2 paths and v1 webhook compatibility (getting-started, how-it-works, hooks, webhooks, api-reference, changelog). |
packages/astro/src/builder.ts | Generate to v2 dir, remove stale v1 flow.js/step.js, route v1 webhook to v2 handler, keep manifest in v1. |
packages/builders/src/base-builder.ts | Comment updated to v2 webhook path. |
packages/builders/src/standalone.ts | Remove stale v1 flow.mjs/step.mjs; build both v2 and v1 webhook bundles; manifest stays in v1. |
packages/builders/src/vercel-build-output-api.ts | Clean v1 flow.func/step.func/webhook; emit v2 flow/webhook funcs; add Build Output route rewrite from v1 webhook to v2. |
packages/cli/src/commands/health.ts, packages/cli/src/lib/config/workflow-config.ts | Use v2 paths; rename steps bundle to __step_registrations.mjs. |
packages/core/e2e/{e2e,local-build}.test.ts | Tests target v2 endpoints; one webhook test retained on v1 to validate compatibility. |
packages/core/src/{create-hook,workflow/create-hook,runtime/world-init}.ts | Webhook URL/doc strings updated to v2. |
packages/nest/src/workflow.controller.ts, packages/nest/README.md | Controller exposes v2 flow + v2 webhook + v1 legacy webhook (delegating to v2). |
packages/next/src/builder-deferred.ts, builder-eager.ts, builder.ts, index.test.ts | Generate to v2; write/copy webhook stubs for both v1 and v2; cleanup stale v1 routes/config; update deferred entries; tighten watch-mode invariant. |
packages/nitro/src/{index,vite}.ts, index.test.ts | Register both v1 and v2 webhook virtual handlers; v2 flow handler; functionRules updated; middleware matcher widened. |
packages/sveltekit/src/{builder,index}.ts | Generate to v2; build both v1 and v2 webhook routes; cleanup stale v1 flow/step; manifest stays in v1; .vc-config path updated to v2. |
packages/utils/src/get-port.ts, get-port.test.ts | Probe endpoint updated to v2. |
packages/world-local/src/queue.ts, packages/world-postgres/src/queue.ts, queue.test.ts, README.md, HOW_IT_WORKS.md | Route all step and workflow queue messages to the v2 flow endpoint. |
packages/world-testing/{package.json,src/server.mts,scripts/generate-well-known-dts.mjs} | Import v2 flow handler; generate v2 flow/webhook + v1 webhook dts stubs; copy both v1 and v2 mjs into dist. |
scripts/create-test-matrix.mjs | DEV test config paths updated to v2. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Signed-off-by: Pranay Prakash <pranay.gp@gmail.com>
TooTallNate
left a comment
There was a problem hiding this comment.
Request Changes — branch is too stale; merging as-is reverts at least three landed PRs
The architectural direction is sound: moving the combined execution endpoint to /v2/flow while keeping the webhook + manifest on /v1 is the right call for v5 (the v4-stable URL contract stays intact, the v5-only behavioral change gets its own path). The PR description's reasoning matches the v5 spec. Approving that direction.
However, the branch is dated May 26 (base b0d0561af) and was last touched June 5 without a rebase. Several PRs landed on main after the base, and the codex diff against current main shows those changes being deleted. Until the branch is rebased and the regressions are vetted, this is unsafe to merge.
Regressions caused by stale base
1. V8 regex stack overflow fix (#930886fe3, Peter, May 27) — reverted
packages/next/src/builder-deferred.tsextractBundleSourceFiles would crash with RangeError: Maximum call stack size exceeded at RegExpStringIterator.next on bundles with multi-MB inline base64 sourcemaps. Peter replaced the matchAll(/...[A-Za-z0-9+/=]+.../g) with a literal-prefix scan + manual base64 alphabet loop. This PR's diff puts the broken regex back:
- // Extract inline base64 sourcemaps via string scanning. A previous- // implementation used `bundleContents.matchAll(/...[A-Za-z0-9+/=]+.../g)`- // which overflows V8's regex stack ...- // [60-line scan loop]+ const sourceMapMatches = bundleContents.matchAll(+ /\/\/# sourceMappingURL=data:application\/json[^,]*;base64,([A-Za-z0-9+/=]+)/g+ );This was added specifically because inline sourcemaps (#1799) became universal across workspace packages and the bundles got large enough to trip V8's irregexp recursion. The crash was tied to a separate branch where it surfaced first, but the underlying hazard is general — every Next builder run is now vulnerable to it.
2. Nitro dashboard handler (#2110, June 2) — reverted
packages/nitro/src/index.ts loses ~75 lines: the entire addDashboardHandler() function, the addDashboardHandler(nitro) call in dev mode, and the createRequire/pathToFileURL imports it needs. /_workflow dev UI dashboard goes away.
Verified: git show origin/main:packages/nitro/src/index.ts | grep -c addDashboardHandler = 2; git show pr-2154:packages/nitro/src/index.ts | grep -c addDashboardHandler = 0.
3. Lazy step route imports (#2263, JJ, June 5) — reverted
packages/next/src/builder-deferred.ts loses 263 lines that JJ added: createDeferredFlowRoute, createDeferredStepSideEffectImports, getDeferredRouteImportSpecifier, resolveDeferredRouteImportFilePath, resolvePackageSourceDistFilePathForRouteImport, findPackageRootForRouteImportSource, createDeferredStepManifest, resolveBuiltInStepFilesForManifest, mergeWorkflowManifest. The replacement is a single createCombinedBundle() call.
It's plausible that createCombinedBundle actually subsumes what those helpers were doing (the base builder already implements the combined-bundle pattern used by sveltekit/nitro/nest/eager-next), and JJ's PR may have been an interim approach. But the codex diff doesn't make that case — it just deletes the helpers. The accompanying packages/next/src/builder-deferred.test.ts (137 lines added by #2263) isn't touched, so any tests that referenced the deleted helpers will break. And whatever bug #2263 was fixing ("lazy step route imports") may resurface depending on how createCombinedBundle differs.
4. Lockfile / version churn
packages/world-testing/package.json reverts:
@hono/node-server1.19.13 → 1.19.9 (downgrade)hono4.12.21 → 4.12.3 (downgrade)- own version 5.0.0-beta.12 → 5.0.0-beta.7
- 5 CHANGELOG.md entries removed (beta.8 through beta.12)
These are all stale-branch artifacts from being forked before recent version bumps and dependency updates landed. They'll resolve on rebase, but they're a useful signal for how far behind this branch is.
Status check evidence
The PR's commit e20540c6e ("Keep webhook route on v1", June 5) was never run through CI — only Vercel Agent Review, DCO, Socket, and preview deploys ran on it. The earlier commit d4ef02406 (May 29) ran the full suite with E2E Required Check: failure and Unit Tests (windows-latest): failure. Even if those are flaky, no CI evidence currently exists that the branch in its current state builds, lints, and tests on Linux. mergeStateStatus: DIRTY / mergeable: CONFLICTING confirms there's at least one merge conflict (docs/content/docs/v5/changelog/eager-processing.mdx).
Architectural concerns (separate from staleness)
Workflow-server coordination
The Vercel workflow-server (out of this repo) is what calls into the user app at /v1/flow / /v1/step today. If this PR ships and the user app stops exposing /v1/flow and /v1/step, dispatches from workflow-server will 404 unless workflow-server already knows to:
- Dispatch to
/v2/flowfor new-spec deployments, AND - Fall back to
/v1/flow+/v1/stepfor older deployments that haven't redeployed with the v2 SDK.
The PR doesn't say which workflow-server version is required, and there's no smoke test exercising a mixed-version scenario. Please confirm:
- Workflow-server already dispatches to
/v2/flowfor v5-spec deployments - Either workflow-server retains
/v1/flow+/v1/stepfallback during rollout, OR all v5 deployments get re-built before this lands - The Vercel beta-channel rollout sequencing is documented somewhere
If the dispatch logic is already version-aware (e.g. driven by manifest contents the workflow-server reads), saying so in the PR description would be enough.
Patch bump?
12 packages all get patch bumps for what is effectively a public-route relocation. On the beta channel patch doesn't matter (changesets always rolls beta.N), but if this ever has to be backported (the PR description says it won't be), patch would be the wrong semver. Since the PR explicitly says no backport, this is fine, but worth a sentence: "Patch is acceptable on the v5/beta channel; this route change is a v5 spec implementation detail, not a public API change."
Things to verify after rebase
Once rebased onto current main:
- Re-confirm
createCombinedBundleproduces equivalent output tocreateDeferredFlowRoutefor the deferred-builder path. The key thing JJ's PR #2263 was solving (per the title — "Fix Next lazy step route imports") needs to either be preserved bycreateCombinedBundleor explicitly handled separately. - Re-verify
extractBundleSourceFileskeeps the string-scan implementation (not the regex). - Re-verify
addDashboardHandlerstays inpackages/nitro/src/index.ts. - Run
pnpm turbo run build --filter='!./workbench/*'from a clean state. - Re-run E2E (especially
nextjs-webpackdev, which was the canary for the V8 crash).
What I verified locally
- Checked out PR head onto current
mainmerge base; confirmed the three regressions above viagit showagainstorigin/main - Confirmed the changeset is appropriately scoped to packages with real changes (modulo the docs file which is in changeset
ignore) - The route-prefix migration itself (paths in builders, tests, docs, CLI, get-port probe) is consistent across the 38 files —
/v2/floweverywhere,/v1/webhookeverywhere,/v1/manifest.jsoneverywhere
Bottom line
The direction is right and most of the route-rename mechanics look correct. The blocker is the staleness — this PR was generated by a codex agent from a May 26 branch and the agent didn't notice that meaningful code on main got deleted in the process. Rebase, re-run CI, and re-verify the three reverts are restored.
Holding the approve until the rebase shows green and confirms the three referenced PRs survive.
Summary
/.well-known/workflow/v1/flowto/.well-known/workflow/v2/flowand stop emitting the separate v1 step route./.well-known/workflow/v1/webhookand the public manifest under/.well-known/workflow/v1across supported integrations and build targets.Why
Workflow v5 uses the combined flow handler, so the execution route has a materially different contract from the v4 split flow/step model and moves to v2. The webhook route did not materially change, so it remains on v1 rather than introducing an unnecessary webhook URL migration.
Backporting
Do not backport this PR to
stable: this changes the v5/main execution route contract and does not apply to the v4 stable surface.Validation
pnpm buildpnpm vitest run packages/next/src/index.test.ts packages/nitro/src/index.test.ts packages/world-postgres/src/queue.test.ts packages/world-local/src/queue.test.tspnpm vitest run packages/utils/src/get-port.test.ts -t \"identify workflow server|respect custom timeout|handle concurrent getWorkflowPort|return single port without probing\"WORKFLOW_PUBLIC_MANIFEST=1 pnpm buildinworkbench/exampleWORKFLOW_PUBLIC_MANIFEST=1 pnpm buildinworkbench/nextjs-turbopackpnpm buildinworkbench/sveltekitandworkbench/astrov2/flow,v1/webhook, and nov2/webhookroute