workflow-studio/compute-worker

Overview

@workflow-studio/compute-worker provides the remote execution server used by Workflow Studio.

It exposes a fetch-style handler and Node HTTP server helpers.

Server creation APIs

createComputeWorker(options)

Returns (req: Request) => Promise<Response>.

Key options:

• world
• compute (optional)
• expectedTargetWorld (optional)
• seedApiKeys (optional)
• requireHttps (optional)
• rateLimitPerMinute (optional)
• sqlitePath (optional)
• artifactDir (optional)
• onWebhook (optional)

createNodeComputeWorkerServer(options)

Returns a Node Server that wraps createComputeWorker.

startNodeComputeWorkerServer(options)

Starts Node Server and resolves when listening.

Public routes

• GET /v1/health
• POST /v1/runs
• GET /v1/runs/:id
• POST /v1/runs/:id/cancel
• POST /v1/runs/resume
• POST /v1/deployments
• POST /v1/deployments/:id/activate
• GET /v1/deployments/:id
• GET /v1/deployments/active
• POST /v1/webhooks/:provider

World-proxy routes

Require world:proxy scope:

• POST /v1/queue/publish
• GET /v1/world/deployment-id
• POST /v1/world/events/create
• POST /v1/world/events/list
• POST /v1/world/events/list-by-correlation
• POST /v1/world/runs/list
• GET /v1/world/steps/:stepId
• POST /v1/world/steps/list
• GET /v1/world/hooks/:hookId
• GET /v1/world/hooks/by-token/:token
• POST /v1/world/hooks/list
• POST /v1/world/streams/write
• POST /v1/world/streams/close
• GET /v1/world/streams/read
• GET /v1/world/streams/list
• POST /v1/world/encryption-key

Authentication and scopes

Auth header:

• Authorization: Bearer <key>

Common scopes:

• public lane: trigger:write, runs:read, runs:write, deploy:read, deploy:write
• internal lane: world:proxy

Correlation headers

Every request passing through the worker is tagged with a correlation ID for end-to-end tracing.

Inbound: the worker reads x-workflow-correlation-id from the incoming request. If the header is absent, the worker generates a UUID and injects it into the request headers before routing.

Outbound: every response includes x-workflow-correlation-id, whether the value was forwarded from the caller or generated by the worker.

Audit: the correlation ID (and x-workflow-run-id when present) is persisted in the metadata_json column of audit log entries. This enables correlation-based forensic queries across request chains.

Idempotency behavior

POST /v1/runs requires Idempotency-Key.

• equivalent payload + same key replays prior accepted response,
• different payload + same key returns 409 idempotency_conflict.

See compute-client HTTP status mapping for how the client surfaces this as IdempotencyComputeClientError.

Deployment selection behavior

If deploymentId is omitted on run trigger paths, worker resolves deployment from active deployment pointer. If no active deployment exists, worker returns 409 { code: 'no_active_deployment' }.

Strict remote guard

In strict mode (NODE_ENV=production), worker startup validates WORKFLOW_TARGET_WORLD against expected target.