world-http Adapter

go-workflow/world-http exposes a Go World served by HTTP(world) as a Workflow SDK World in JavaScript. It sends its operations to the handler's CBOR RPC endpoint and uses bounded polling for stream chunks.

Most projects never import it: the web UI loads it for you through WORKFLOW_TARGET_WORLD. Use it directly when JavaScript or TypeScript code needs to read or control Go runs with the Workflow SDK's World API, such as an admin script or a Node service.

Install

npm install go-workflow

Usage

Create the World with the URL of the Go handler, including /v1/workflow:

import { createWorld } from "go-workflow/world-http";

const world = await createWorld({
  baseURL: "http://localhost:8080/v1/workflow",
});

List the most recent failed runs, without their payloads:

const failed = await world.runs.list({ status: "failed", resolveData: "none" });

Read one run with its input and output:

const run = await world.runs.get(failed.data[0].runId);

Wait up to 30 seconds for a run to finish:

const finished = await world.runs.waitForTerminalStatus(run.runId, { timeoutMs: 30_000 });

Options

Option	Default	Description
baseURL	WORKFLOW_HTTP_BASE_URL	The handler's URL, including /v1/workflow.
token	WORKFLOW_HTTP_TOKEN	Sent as Authorization: Bearer <token>. An Authorization header in headers wins.
headers	none	Headers sent with every RPC request, such as Authorization.
fetch	globalThis.fetch	A custom fetch implementation.

createWorld calls the client.spec RPC once before it returns, to read the World's protocol version and capabilities, so it fails fast when the handler is unreachable. world.getDeploymentId() asks the Go World for its deployment on every call, so it stays correct across redeploys.

If you protect the RPC path with worlds.WithRPCToken, set WORKFLOW_HTTP_TOKEN or pass the token:

const world = await createWorld({
  baseURL: "https://workflows.example.com/v1/workflow",
  token: process.env.WORKFLOW_HTTP_TOKEN,
});

Loading through the Workflow SDK runtime

The Workflow SDK CLI and runtime load a World by module name. Set:

export WORKFLOW_TARGET_WORLD=go-workflow/world-http
export WORKFLOW_HTTP_BASE_URL=http://localhost:8080/v1/workflow
export WORKFLOW_HTTP_TOKEN=... # when the RPC path is protected

Loaded this way, the adapter is created without options and reads WORKFLOW_HTTP_BASE_URL and WORKFLOW_HTTP_TOKEN, so it cannot send other custom headers.

Limits

The adapter is a client only. Deliveries are executed by your Go process, so it cannot create queue handlers. Its deployment ID is the Go World's.

WARNING

The RPC endpoint is unauthenticated unless you protect it. Point the adapter only at Worlds on a trusted network, or protect the RPC path and set WORKFLOW_HTTP_TOKEN.