workflow 5.0.0-beta.5 → 5.0.0-beta.51

package/docs/configuration/worlds.mdx

@@ -0,0 +1,313 @@
+---
+title: Worlds
+description: Configure the Workflow backend that stores runs and delivers queue messages.
+type: reference
+summary: Select and configure Local, Postgres, Vercel, or custom Worlds.
+related:
+  - /worlds/local
+  - /worlds/postgres
+  - /worlds/vercel
+---
+
+A [World](/docs/deploying) stores workflow state and delivers queue messages.
+
+## Selecting a World
+
+### `WORKFLOW_TARGET_WORLD`
+
+- Surface: environment variable
+- Default: `local` outside Vercel; automatic Vercel World inside Vercel deployments
+- Selects a non-default World module.
+
+Outside Vercel, Workflow defaults to the Local World. On Vercel, leave `WORKFLOW_TARGET_WORLD` unset for the normal case; Workflow detects the Vercel deployment and selects the Vercel World automatically.
+
+The World is selected when your app **runs**, from the environment of the process serving it, so changing `WORKFLOW_TARGET_WORLD` takes effect on the next start without a rebuild. Detection keys off `VERCEL_DEPLOYMENT_ID`, which Vercel sets in every deployed function and nothing else sets: with it, the Vercel World; without it, the Local World.
+
+Broader signals are deliberately ignored. `vercel env pull` writes `VERCEL=1` into `.env.local`, so a dev server or a production server started on your own machine sees it while running against a writable filesystem, where the Local World is the right choice. Set `WORKFLOW_TARGET_WORLD=vercel` explicitly if you want such a process to talk to the Vercel World; starting a run then fails with an error naming the missing `VERCEL_DEPLOYMENT_ID`.
+
+A deployment that pins `WORKFLOW_TARGET_WORLD=local` warns at startup and fails on its first write, because a Vercel deployment's filesystem is read-only.
+
+Set `WORKFLOW_TARGET_WORLD` only when you want to use a custom or self-hosted World:
+
+- `local`: Alias for `@workflow/world-local`.
+- `@workflow/world-postgres`: Postgres World package.
+- `./my-world.ts`: Local module exporting a World, `createWorld()`, or a default factory.
+- Any package specifier: Custom World package.
+
+The `vercel` alias exists for manual selection and tooling, but deployed Vercel apps do not need to set it.
+
+Export a configured World from a module when you need factory options instead of pure environment configuration:
+
+```typescript title="my-world.ts" lineNumbers
+import { createWorld } from "@workflow/world-postgres";
+
+export default createWorld({
+  connectionString: process.env.DATABASE_URL!,
+  jobPrefix: "myapp_",
+});
+```
+
+```bash title=".env"
+WORKFLOW_TARGET_WORLD="./my-world.ts"
+```
+
+## Local World
+
+The Local World is the default outside Vercel and is intended for development.
+
+### `dataDir`
+
+- Environment variable: `WORKFLOW_LOCAL_DATA_DIR`
+- Default: `.workflow-data`
+- Directory where runs, steps, events, hooks, streams, and the local manifest are written.
+
+### `baseUrl`
+
+- Environment variable: `WORKFLOW_LOCAL_BASE_URL`
+- Default: inferred from the app port
+- Full base URL used when queue messages call back into the app.
+- Overrides `port` and `PORT`.
+
+### `port`
+
+- Environment variable: `PORT`
+- Default: auto-detected
+- Local app port used to build the callback URL when `baseUrl` is unset.
+
+### `WORKFLOW_LOCAL_QUEUE_CONCURRENCY`
+
+- Factory option: none
+- Default: `1000`
+- Maximum number of concurrent local queue message handlers.
+
+### `WORKFLOW_LOCAL_QUEUE_MAX_VISIBILITY`
+
+- Factory option: none
+- Default: unlimited
+- Maximum seconds a local queue message stays hidden before the handler rechecks the run.
+
+### `WORKFLOW_LOCAL_HEADERS_TIMEOUT_MS`
+
+- Factory option: none
+- Default: `30000`
+- Maximum milliseconds to wait for a local queue handler to begin responding before the durable message is redelivered. Set to `0` to disable.
+
+### `WORKFLOW_LOCAL_BODY_TIMEOUT_MS`
+
+- Factory option: none
+- Default: `30000`
+- Maximum gap in milliseconds between response body chunks from a local queue handler before the durable message is redelivered. Set to `0` to disable.
+
+### `recoverActiveRuns`
+
+- Environment variable: `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS`
+- Default: `true`
+- Re-enqueues pending and running local runs when the World starts. Set the environment variable to `0` or `false` to skip recovery; the factory option wins when both are set.
+
+### `WORKFLOW_LOCAL_HOOK_RETENTION_LIMIT_DAYS`
+
+- Factory option: none
+- Default: `30`
+- Maximum [`experimental_minRetention`](/docs/api-reference/workflow/create-hook#keep-a-token-unavailable-after-the-run-ends) accepted by the Local World, in days.
+- Set this to the same limit as your production World so oversized values fail during local development.
+
+### `tag`
+
+- Environment variable: none
+- Default: unset
+- Scopes local storage files to a tag, mainly for test isolation.
+
+### `streamFlushIntervalMs`
+
+- Environment variable fallback: `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
+- Default: `0` (dispatch the leading chunk of an idle stream immediately)
+- Group-commit window for the leading chunk of an idle stream; a positive value trades first-chunk latency for larger groups. The `WORKFLOW_STREAM_FLUSH_INTERVAL_MS` environment variable, when set, overrides this option; otherwise the World option governs, including the first chunk.
+
+### `WORKFLOW_MAX_EVENTS`
+
+- Default: `25000`
+- Per-run event ceiling reported to the runtime. A run whose event log reaches it fails with `MAX_EVENTS_EXCEEDED`, bounding a runaway loop. See [`WORKFLOW_MAX_EVENTS_OVERRIDE`](/docs/configuration/runtime-tuning#workflow_max_events_override) for the runtime-side clamp.
+
+## Postgres World
+
+The Postgres World is a self-hosted durable backend for long-running server processes.
+
+### `connectionString`
+
+- Environment variable: `WORKFLOW_POSTGRES_URL`, then `DATABASE_URL`
+- Default: `postgres://world:world@localhost:5432/world`
+- PostgreSQL connection string used by the runtime World.
+- The `bootstrap` migration command uses the same precedence.
+
+### `pool`
+
+- Environment variable: none
+- Default: new `pg.Pool`
+- Existing `pg.Pool` to use instead of constructing one from `connectionString`.
+
+### `jobPrefix`
+
+- Environment variable: `WORKFLOW_POSTGRES_JOB_PREFIX`
+- Default: `workflow_`
+- Prefix for Graphile Worker job names.
+
+### `queueConcurrency`
+
+- Environment variable: `WORKFLOW_POSTGRES_WORKER_CONCURRENCY`
+- Default: `50`
+- Number of concurrent workers polling for jobs.
+- Also bounds concurrent parent-to-child workflow return-value polls.
+
+### `applicationManagedShutdown`
+
+- Environment variable: `WORKFLOW_POSTGRES_APPLICATION_MANAGED_SHUTDOWN` (`1` enables)
+- Default: `false`
+- Whether the application coordinates shutdown instead of Graphile Worker responding automatically.
+- Set to `true` only when the application awaits `world.close()` before closing its workflow HTTP server and caller-owned pool.
+- Prevents Graphile Worker's default handler from terminating the process before the application's remaining cleanup finishes.
+
+### `maxPoolSize`
+
+- Environment variable: `WORKFLOW_POSTGRES_MAX_POOL_SIZE`
+- Default: `pg` default
+- Maximum size of the internal `pg.Pool` when the World creates the pool.
+
+### `WORKFLOW_POSTGRES_HOOK_RETENTION_LIMIT_DAYS`
+
+- Factory option: none
+- Default: `30`
+- Maximum [`experimental_minRetention`](/docs/api-reference/workflow/create-hook#keep-a-token-unavailable-after-the-run-ends) accepted by the Postgres World, in days.
+- Set this to the same limit as your production World so oversized values fail during development.
+
+### `namespace`
+
+- Environment variable fallback: `WORKFLOW_QUEUE_NAMESPACE`
+- Default: none
+- Queue topic namespace. For example, `custom` changes `__wkf_*` topics to `__custom_wkf_*`.
+
+### `streamFlushIntervalMs`
+
+- Environment variable fallback: `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
+- Default: `0` (dispatch the leading chunk of an idle stream immediately)
+- Group-commit window for the leading chunk of an idle stream; a positive value trades first-chunk latency for larger groups. The `WORKFLOW_STREAM_FLUSH_INTERVAL_MS` environment variable, when set, overrides this option; otherwise the World option governs, including the first chunk.
+
+## Vercel World
+
+The Vercel World is configured automatically inside Vercel deployments. The platform provides the deployment ID, project ID, request authentication, queue integration, storage, and encryption material.
+
+Most applications should not set `WORKFLOW_VERCEL_*` variables on Vercel. They configure tooling that talks to a Vercel Workflow project from outside a deployment, such as the Workflow CLI, the web user interface (UI), continuous integration (CI), or tests. The runtime warns if these variables are set in a deployed Vercel Function because they do not control runtime configuration there.
+
+Platform-provided values such as `VERCEL_DEPLOYMENT_ID`, `VERCEL_PROJECT_ID`, and `VERCEL_DEPLOYMENT_KEY` are read by the runtime inside Vercel deployments. Do not set them yourself.
+
+### `token`
+
+- Environment variable: `WORKFLOW_VERCEL_AUTH_TOKEN`, then `VERCEL_TOKEN`, then Vercel CLI login
+- CLI flag: `--authToken`
+- Default: inferred when possible
+- Vercel API token for external tooling. Keep it secret.
+
+### `projectConfig.environment`
+
+- Environment variable: `WORKFLOW_VERCEL_ENV`
+- CLI flag: `--env` or `-e`
+- Default: `production`
+- Vercel environment targeted by tooling. Accepts `production` or `preview`.
+
+### `projectConfig.projectId`
+
+- Environment variable: `WORKFLOW_VERCEL_PROJECT`
+- CLI flag: `--project`
+- Default: inferred from `.vercel/project.json` when possible
+- Vercel project ID.
+
+### `projectConfig.teamId`
+
+- Environment variable: `WORKFLOW_VERCEL_TEAM`
+- CLI flag: `--team`
+- Default: inferred from `.vercel/project.json` when possible
+- Vercel team ID.
+
+### `WORKFLOW_VERCEL_PROJECT_NAME`
+
+- Factory option: none
+- CLI flag: none
+- Default: inferred when possible
+- Project slug used for dashboard links.
+
+### `WORKFLOW_VERCEL_BACKEND_URL`
+
+- Factory option: none
+- CLI flag: none
+- Default: `https://api.vercel.com/v1/workflow`
+- Workflow API proxy URL for external tooling.
+
+### `WORKFLOW_SEQUENTIAL_REPLAYS`
+
+- Default: disabled
+- Set `1` to serialize orchestrator (flow) invocations per run: each run's replays get their own queue topic and the flow trigger is generated with `maxConcurrency: 1`. Inline step executions get per-step topics and keep full parallelism.
+- Read at **both build time and runtime**: set it as a project-level environment variable so the generated trigger and the runtime queue routing agree.
+- Routing each run through a dedicated `maxConcurrency: 1` topic might lead to higher queue performance overhead. See [Vercel World](/worlds/vercel#workflow_sequential_replays) for details.
+
+### `VERCEL_WORKFLOW_SERVER_URL`
+
+- Factory option: none
+- CLI flag: none
+- Default: unset
+- Direct workflow-server URL override for testing or custom infrastructure. Normal deployments do not need it.
+
+### `VERCEL_QUEUE_MAX_DELAY_SECONDS`
+
+- Factory option: none
+- CLI flag: none
+- Default: `82800` (23 hours)
+- Maximum delay for one Vercel Queues continuation message when implementing `sleep()`.
+- Longer sleeps schedule another continuation when the first one fires.
+
+`VERCEL_QUEUE_MAX_DELAY_SECONDS` defaults to 23 hours because Vercel Queues message delays are capped by the message TTL, and the default TTL is 24 hours. Workflow stays inside that default and chains continuation messages for longer sleeps.
+
+### `WORKFLOW_REQUEST_TIMEOUT_MS`
+
+- Factory option: none
+- CLI flag: none
+- Default: `60000`
+- Clamp: `10000` to `120000` (values outside are clamped, with a warning)
+- Per-request timeout for Vercel World HTTP calls to workflow-server.
+- At the `10000` floor the run-status long poll disables itself, because its budget is this value minus 10s of headroom.
+
+### `WORKFLOW_MAX_CHUNKS_PER_REQUEST`
+
+- Factory option: none
+- CLI flag: none
+- Default: `1000`
+- Maximum stream chunks written in one Vercel World request. Larger batches are split.
+
+### `WORKFLOW_STREAMS_TRANSPORT`
+
+- Factory option: none
+- CLI flag: none
+- Default: `http`
+- Experimental stream-write transport capability. Set to exactly `ws` to attempt `workflow-stream-ws/v1`. The server authoritatively accepts or declines each upgrade; a decline uses HTTP directly for that writer lifetime. Stream reads remain HTTP and demand-driven.
+- This is not tenant rollout policy or a package-version check. HTTP remains the compatibility path. `/websockets/v1` is independent of REST v2/v4 and persisted workflow `specVersion` values.
+
+### `WORKFLOW_DISABLE_ANALYTICS_READS`
+
+- Factory option: none
+- CLI flag: none
+- Default: disabled
+- Set `1` to turn off the World's metadata-only `analytics` read namespace, forcing `workflow inspect` and web UI list views onto strongly consistent primary storage. Intended for tests and tooling that read entities immediately after writing them.
+
+### `WORKFLOW_BATCH_TRANSITIONS`
+
+- Surface: environment variable
+- Default: on
+- Set to `0` (or `false`) to **disable** batched event writes, the escape hatch that restores the exact prior one-write-per-event path.
+
+When enabled (the default), a suspension's eager `step_created` and `wait_created` writes fold into batched `events.createBatch` calls (one durable write with per-event outcomes) on Worlds that implement the optional batch API. The fold only engages when the World implements `events.createBatch` (the Vercel World does; Local and Postgres do not), the run's spec version supports slot identity (≥ 6), and the suspension carries no attribute writes, hook writes, or resilient step dispatch. Everything else keeps the single-event path unchanged, so disabling is only needed as an operational escape hatch. Batches are capped at 32 events; larger fan-outs commit in successive batches. See the [batched event writes changelog](/docs/changelog/batched-event-writes) for the World API contract.
+
+### `WORKFLOW_EVENTS_TRANSPORT`
+
+- Factory option: none
+- CLI flag: none
+- Default: `ws`
+- Ships workflow run events to the Vercel World over a WebSocket instead of one HTTP request each. Set to exactly `http` to opt out; any other value, including unset or empty, uses the WebSocket.
+- 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.