[codex] Migrate workflow execution routes to v2#2154
Open
pranaygp wants to merge 1 commit into
Open
Conversation
Contributor
🦋 Changeset detectedLatest commit: d4ef024 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 |
Contributor
📊 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. |
Contributor
🧪 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. |
Contributor
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.
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 free
to 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
/.well-known/workflow/v1/flowto/.well-known/workflow/v2/flow./.well-known/workflow/v2/webhookwhile preserving/.well-known/workflow/v1/webhookcompatibility across supported integrations and build targets.Why
Workflow v5 uses the combined flow handler; the separate
v1/stependpoint belongs to the v4 route model and should not be emitted or advertised by v5 builds. At the same time, existing external webhook URLs must continue working, so the v1 webhook path remains supported as a compatibility alias.Backporting
Do not backport this PR to
stable: this changes the v5/main route contract and does not apply to the v4 stable surface.Validation
pnpm buildpnpm exec biome checkfor changed TypeScript/JavaScript files andgit diff --checkpnpm 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/astroNotes
pnpm lintrun currently reports pre-existing diagnostics outside this change.