Workflow SDK

Run durable workflows built with the Workflow SDK on Gigadrive Network queues, using the queue adapter in @gigadrive/sdk.

The Workflow SDK runs durable, resumable functions on top of a queue, and its pluggable "World" decides which queue that is. createWorkflowQueue() from @gigadrive/sdk is the queue half of a World, so workflow steps, sleeps and retries run on Gigadrive Network queues.

Plug in the queue

A World also needs storage and streaming, which come from your World implementation. Spread the queue into it:

// lib/world.ts
import { createWorkflowQueue } from '@gigadrive/sdk';
import type { MessageId, World } from '@workflow/world';

import { storage, streamer } from './world-storage';

export const world: World = {
  ...storage,
  ...streamer,
  ...createWorkflowQueue<MessageId>(),
};

The MessageId type argument makes the returned message ids match the World's branded type. Inside a deployed Function the adapter needs no other configuration: its zero-config client authenticates with the Function's own credential, described in OIDC federation.

What the adapter does

Workflow SDK expects	On Gigadrive Network
Messages delivered to `/.well-known/workflow/v1/flow`	A push queue per Workflow queue prefix, such as `__wkf_workflow_`, with that consumer path
`delaySeconds` on a send	A delayed message
`idempotencyKey` on a send	A deduplication key, so a repeated send returns the first message id
`deploymentId` on a send	The message is pinned to that deployment; without one, to the deployment sending it
A handler that returns `{ timeoutSeconds }`	The message is delivered again after that long, without spending an attempt
A stable message id across redeliveries	The same id on every delivery
`Uint8Array` values in a message	Preserved through a tagged JSON encoding

Without queueSettings, the adapter creates the push queue on its first send, with 100 attempts and a 900 second delivery timeout, and leaves an existing queue's settings alone, so changes you make in the console stick. With queueSettings, it applies those settings instead, on every start, so set them in code or in the console, not both. The Workflow runtime stops retrying a message on its own before the attempts run out. All workflows of one prefix share that queue, which keeps them inside your plan's queues per environment.

Options

Option	Default	Purpose
`consumerPath`	`/.well-known/workflow/v1/flow`	Where your app serves the Workflow handler
`queueSettings`	None	Queue settings applied on every start, such as `concurrency` or a longer `visibilityTimeoutSeconds` for long steps
`deploymentId`	`GIGADRIVE_DEPLOYMENT_ID`	The deployment the Workflow runtime stamps on new runs
`client`	A zero-config client	A `GigadriveClient` to use outside a deployment
`applicationId`	The client's application	Application UUID; a deployment's client uses `GIGADRIVE_APPLICATION_ID`
`environment`	The deployment's environment	Environment slug or UUID, for clients outside a deployment
`signingSecret`	`GIGADRIVE_QUEUE_SIGNING_SECRET`	The secret that verifies push deliveries
`allowUnsigned`	`false`	Accept deliveries without a valid signature; for local development only

Watch workflow traffic

The backing queue appears in the console like any other, so its depth, dead letters and delivery errors show how your workflows are doing. Lower concurrency in queueSettings to protect a downstream service from a burst of workflow steps.