API Referenceworkflow/runtimeWorld SDK

Queue

Queue methods live directly on the world object (not nested). They dispatch internal workflow invocations, including queued step work, to the queue backend.

The Workflow SDK uses these methods internally to dispatch execution. In normal operations, use start() to trigger workflows instead. You only need direct queue access to start the initial execution of a run you programmatically created via world.events.create() with a run_created event, or to debug flow resumption.

Import

import { getWorld } from "workflow/runtime";

const world = await getWorld();
// Call queue methods directly on world, for example, world.queue()

Methods

getDeploymentId()

Get the current deployment ID. The SDK uses it internally to route queue messages to the correct deployment.

const deploymentId = await world.getDeploymentId();

Returns: string. The current deployment ID.

queue()

Dispatch a message to a named queue. The message payload is an internal SDK type (WorkflowInvokePayload or HealthCheckPayload). Queued steps use WorkflowInvokePayload with stepId and stepName.

const { messageId } = await world.queue(queueName, payload, opts);

Parameters:

ParameterTypeDescription
queueNameValidQueueNameThe queue name (branded string)
messageQueuePayloadInternal SDK payload
optsQueueOptionsOptional: deploymentId, idempotencyKey, delaySeconds, headers, region (regional routing hint), specVersion

Returns: { messageId: MessageId | null }

createQueueHandler()

Create an HTTP handler that processes messages from a queue. Use it to set up the queue consumer endpoint.

const handler = world.createQueueHandler(prefix, callback);

Parameters:

ParameterTypeDescription
prefixQueuePrefixQueue name prefix to match
callback(message, meta) => Promise<void | { timeoutSeconds: number }>Handler called for each message. meta contains attempt, queueName, messageId, requestId.

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

meta.messageId should be stable across redeliveries of the same message (one ID per enqueued message, reused on every delivery attempt). The runtime records it on inline step_started events as a liveness lease so that only a redelivery of the owning message re-executes a crashed inline step before the lease expires (see Inline step message ownership). A World whose queue mints a fresh ID per delivery degrades gracefully. Crashed inline steps recover via the delayed backstop instead of immediately on redelivery, but never wedge or duplicate.

PreviousStreamsNextcreateWorld