workflow-studio/compute-client

Overview

This document covers the internal architecture of the @workflow-studio/compute-client package, which provides the HTTP client used by Workflow Studio to communicate with remote compute workers.

Package Structure

packages/compute-client/
├── src/
│   ├── index.ts           # Client implementation
│   └── types.ts           # Type definitions
└── package.json

Client Configuration

export type ComputeClientOptions = {
  baseUrl: string;
  apiKey?: string;
  timeoutMs?: number;
  retries?: number;
  fetchImpl?: typeof fetch;
};

Core Methods

Constructor

const client = new ComputeClient({
  baseUrl: 'https://worker.example.com',
  apiKey: process.env.WORKFLOW_COMPUTE_API_KEY,
  timeoutMs: 10_000,
  retries: 2,
});

Trigger Workflow

async trigger(
  request: ComputeTriggerRequest,
  options?: { idempotencyKey?: string }
): Promise<ComputeTriggerResponse>

Sends a POST /v1/runs request to trigger a new workflow run.

Resume Run

async resumeRun(
  request: ComputeResumeRequest
): Promise<ComputeResumeResponse>

Sends a POST /v1/runs/resume request to resume a suspended workflow.

Get Active Deployment

async getActiveDeployment(): Promise<{ deploymentId: string }>

Sends a GET /v1/deployments/active request to retrieve the current active deployment.

Request Flow

URL Construction: Combines baseUrl with endpoint path
Headers: Adds Authorization: Bearer <apiKey> if key provided
Idempotency: Adds Idempotency-Key header if provided in options
Retry Logic: Retries on 429, >=500, and timeout/abort errors up to retries times
Timeout: Aborts request after timeoutMs milliseconds

Error Handling

The client throws structured errors:

class ComputeClientError extends Error {
  status: number;
  code?: string;
  causeBody?: unknown;
  
  constructor(message: string, status: number, code?: string, causeBody?: unknown) {
    super(message);
    this.status = status;
    this.code = code;
    this.causeBody = causeBody;
  }
}

Common error codes:

unauthorized (401): Invalid or missing API key
missing_scope (403): API key lacks required scope
idempotency_required (400): Missing Idempotency-Key header
no_active_deployment (409): No active deployment set on worker
rate_limited (429): Rate limit exceeded

Usage in Workflow Studio

The compute client is used by:

Proxy helpers (proxyTrigger, proxyWebhook): Forward requests from app host to worker
Remote executor adapter (remoteExecutorAdapter): Trigger and resume runs remotely
CLI commands: Deploy, activate, rollback operations

Example from execution-adapters.ts:

const client = new ComputeClient({
  baseUrl: options.baseUrl,
  apiKey: options.apiKey,
  timeoutMs: options.timeoutMs,
  retries: options.retries,
  fetchImpl: options.fetchImpl,
});

return {
  mode: 'remote',
  trigger: async (req) => await client.trigger(req),
  resume: async (req) => await client.resumeRun(req),
  getDeploymentId: async () => (await client.getActiveDeployment()).deploymentId,
};

workflow-studio/compute-client

On this page