diff --git a/docs/content/docs/v4/deploying/index.mdx b/docs/content/docs/v4/deploying/index.mdx index e30e1a527f..6af72e5573 100644 --- a/docs/content/docs/v4/deploying/index.mdx +++ b/docs/content/docs/v4/deploying/index.mdx @@ -56,6 +56,13 @@ vercel deploy Learn more about the [Vercel World](/worlds/vercel) and its capabilities. + + Starting with `workflow` version 5.0.0-beta.33, the Vercel World supports + **multi-region**: runs are pinned to the region that creates them, keeping + workflow data, queuing, and streaming close to your users. See + [Multi-region in the v5 docs](/v5/docs/deploying/world/vercel-world#multi-region). + + ## Self-Hosting & Other Providers For self-hosting or deploying to other cloud providers, you can use community-maintained Worlds or build your own. diff --git a/docs/content/docs/v4/deploying/meta.json b/docs/content/docs/v4/deploying/meta.json index d9d363f308..6180091352 100644 --- a/docs/content/docs/v4/deploying/meta.json +++ b/docs/content/docs/v4/deploying/meta.json @@ -1,4 +1,4 @@ { "title": "Deploying", - "pages": ["...deploying", "building-a-world"] + "pages": ["...deploying", "world", "building-a-world"] } diff --git a/docs/content/docs/v4/deploying/world/meta.json b/docs/content/docs/v4/deploying/world/meta.json index 0cb3e7c432..696aa6507e 100644 --- a/docs/content/docs/v4/deploying/world/meta.json +++ b/docs/content/docs/v4/deploying/world/meta.json @@ -1,4 +1,4 @@ { - "title": "World", + "title": "Worlds", "pages": ["local-world", "vercel-world", "postgres-world"] } diff --git a/docs/content/docs/v4/deploying/world/vercel-world.mdx b/docs/content/docs/v4/deploying/world/vercel-world.mdx index 56b6395954..b2bdba79e5 100644 --- a/docs/content/docs/v4/deploying/world/vercel-world.mdx +++ b/docs/content/docs/v4/deploying/world/vercel-world.mdx @@ -44,9 +44,18 @@ For self-hosted deployments, use the [Postgres World](/worlds/postgres). For loc ## Limitations -- **Single-region deployment** - The backend infrastructure is currently deployed only in `iad1`. Applications in other regions will route workflow requests to `iad1`, which may result in higher latency. For best performance, deploy your Vercel apps using Workflow to `iad1`. Global deployment is planned to colocate the backend closer to your applications. + + **Multi-region support is available starting with `workflow` version + 5.0.0-beta.33.** On 5.x, workflow runs are pinned to the region that creates them — + storage, queuing, and streams are served region-locally instead of routing + through `iad1`. See [Multi-region in the v5 + docs](/v5/docs/deploying/world/vercel-world#multi-region). The limitations + below apply to the 4.x release line, which will not support multi-region. + + +- **Single-region deployment** - On the 4.x release line, the backend infrastructure is used only in `iad1`. Applications in other regions will route workflow requests to `iad1`, which may result in higher latency. For best performance, deploy your Vercel apps using Workflow to `iad1` — or upgrade to `workflow` 5.0.0-beta.33+ for multi-region support. -- **Data residency** - The Vercel World is currently deployed in the `iad1` region. This means independently of the deployment location of your application, the data for your workflows will be stored in the `iad1` region. +- **Data residency** - On the 4.x release line, independently of the deployment location of your application, the data for your workflows will be stored in the `iad1` region. ## Observability diff --git a/docs/content/docs/v5/deploying/index.mdx b/docs/content/docs/v5/deploying/index.mdx index e30e1a527f..02ae36d340 100644 --- a/docs/content/docs/v5/deploying/index.mdx +++ b/docs/content/docs/v5/deploying/index.mdx @@ -43,6 +43,7 @@ The Vercel World provides: - **Managed queuing** - Steps are processed reliably with automatic retries - **Automatic scaling** - Workflows scale with your application - **Built-in observability** - View workflow runs in the Vercel dashboard +- **Multi-region** - Runs are pinned to the region that creates them, keeping workflow data, queuing, and streaming close to your users (requires `workflow` 5.0.0-beta.33 or later) Simply deploy your application: @@ -53,7 +54,7 @@ vercel deploy - Learn more about the [Vercel World](/worlds/vercel) and its capabilities. + Learn more about the [Vercel World](/docs/deploying/world/vercel-world) and its capabilities, including [multi-region](/docs/deploying/world/vercel-world#multi-region). ## Self-Hosting & Other Providers diff --git a/docs/content/docs/v5/deploying/meta.json b/docs/content/docs/v5/deploying/meta.json index d9d363f308..6180091352 100644 --- a/docs/content/docs/v5/deploying/meta.json +++ b/docs/content/docs/v5/deploying/meta.json @@ -1,4 +1,4 @@ { "title": "Deploying", - "pages": ["...deploying", "building-a-world"] + "pages": ["...deploying", "world", "building-a-world"] } diff --git a/docs/content/docs/v5/deploying/world/meta.json b/docs/content/docs/v5/deploying/world/meta.json index 0cb3e7c432..696aa6507e 100644 --- a/docs/content/docs/v5/deploying/world/meta.json +++ b/docs/content/docs/v5/deploying/world/meta.json @@ -1,4 +1,4 @@ { - "title": "World", + "title": "Worlds", "pages": ["local-world", "vercel-world", "postgres-world"] } diff --git a/docs/content/docs/v5/deploying/world/vercel-world.mdx b/docs/content/docs/v5/deploying/world/vercel-world.mdx index 84da4e7777..b68e67e236 100644 --- a/docs/content/docs/v5/deploying/world/vercel-world.mdx +++ b/docs/content/docs/v5/deploying/world/vercel-world.mdx @@ -42,11 +42,55 @@ For complete details on pricing, usage limits, and included allotments on Vercel For self-hosted deployments, use the [Postgres World](/worlds/postgres). For local development, use the [Local World](/worlds/local). -## Limitations +## Multi-region + +The Vercel World runs in every [Vercel Function region](https://vercel.com/docs/regions). Each workflow run is pinned to a single region at creation time: its stored state, queue dispatch, and streams are all served from that region — no cross-region round trips on the hot path. When your application is deployed in the run's region (the automatic case below), step execution is region-local too. + + + Multi-region requires `workflow` version **5.0.0-beta.33** or later. + The 4.x release line does not support region pinning — runs created by + 4.x always live in `iad1`. + + +### Automatic region pinning + +No configuration is needed. A run is pinned to the region of the function that creates it: + +- Deploy your app to a single region (via [`regions`](https://vercel.com/docs/project-configuration#regions) in `vercel.json` or the project settings), and every run lives there. +- Deploy to multiple regions for a globally distributed audience, and each run is pinned to the region that served the user who triggered it — workflow data and streaming stay close to that user. + +### Explicit region selection + +To pin a specific run somewhere else, pass the `region` option to [`start()`](/docs/api-reference/workflow-api/start): -- **Single-region deployment** - The backend infrastructure is currently deployed only in `iad1`. Applications in other regions will route workflow requests to `iad1`, which may result in higher latency. For best performance, deploy your Vercel apps using Workflow to `iad1`. Global deployment is planned to colocate the backend closer to your applications. +```typescript +import { start } from "workflow/api"; +import { myWorkflow } from "@/workflows/my-workflow"; + +const run = await start(myWorkflow, [input], { region: "sfo1" }); +``` + + + The `region` option controls where the run's **data is stored** and where + its **queue messages are dispatched from** — it does not deploy your code + there. Your workflow and step functions execute in the regions your + application is deployed to. For execution to actually happen in the + specified region, your app must be deployed there — via + [`regions`](https://vercel.com/docs/project-configuration#regions) in + `vercel.json` or the Function Regions setting in your project settings. + If it isn't, the run's data lives in the requested region but its steps + execute in the nearest region your app is deployed to. + + +### Good to know + +- Reads, hook resumes, and stream consumers can come from anywhere — the platform routes them to the run's region automatically. +- Runs created by 4.x SDKs (and any runs that existed before you upgraded) live in `iad1` and are unaffected by an upgrade; there is no migration. +- **Hook tokens are currently stored in `iad1`** for every run, regardless of the run's region: the token-to-run mapping that powers [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) and [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) lives there so tokens — which carry no region information — can always be resolved. Hook *payloads* are not affected: a received payload is recorded on the run's event log, which lives in the run's region like all other run data. This token placement may become a project-level setting in the future. + +## Limitations -- **Data residency** - The Vercel World is currently deployed in the `iad1` region. This means independently of the deployment location of your application, the data for your workflows will be stored in the `iad1` region. +- **No run migration** - A run's region is fixed at creation. Existing runs cannot be moved to a different region. ## Observability