586 lines
15 KiB
Markdown
586 lines
15 KiB
Markdown
# Cloudflare Workflows - Production Patterns
|
|
|
|
**Last Updated**: 2025-10-22
|
|
|
|
This document provides battle-tested patterns for building production-ready Cloudflare Workflows.
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
1. [Idempotency Patterns](#idempotency-patterns)
|
|
2. [Error Handling Patterns](#error-handling-patterns)
|
|
3. [Long-Running Process Patterns](#long-running-process-patterns)
|
|
4. [Human-in-the-Loop Patterns](#human-in-the-loop-patterns)
|
|
5. [Workflow Chaining Patterns](#workflow-chaining-patterns)
|
|
6. [Testing Patterns](#testing-patterns)
|
|
7. [Monitoring Patterns](#monitoring-patterns)
|
|
|
|
---
|
|
|
|
## Idempotency Patterns
|
|
|
|
### Pattern 1: Idempotency Keys
|
|
|
|
**Problem:** Workflow steps may execute multiple times due to retries.
|
|
|
|
**Solution:** Use idempotency keys to ensure operations execute only once.
|
|
|
|
```typescript
|
|
export class PaymentWorkflow extends WorkflowEntrypoint<Env, PaymentParams> {
|
|
async run(event: WorkflowEvent<PaymentParams>, step: WorkflowStep) {
|
|
const { orderId, amount } = event.payload;
|
|
|
|
// Generate idempotency key from workflow instance ID + step name
|
|
const idempotencyKey = `${event.instanceId}-charge-payment`;
|
|
|
|
const paymentResult = await step.do('charge payment', async () => {
|
|
// Check if already processed
|
|
const existing = await this.env.KV.get(`payment:${idempotencyKey}`);
|
|
if (existing) {
|
|
console.log('Payment already processed, returning cached result');
|
|
return JSON.parse(existing);
|
|
}
|
|
|
|
// Process payment
|
|
const response = await fetch('https://payment-gateway.example.com/charge', {
|
|
method: 'POST',
|
|
headers: {
|
|
'Idempotency-Key': idempotencyKey // Payment gateway checks this
|
|
},
|
|
body: JSON.stringify({ orderId, amount })
|
|
});
|
|
|
|
const result = await response.json();
|
|
|
|
// Cache result
|
|
await this.env.KV.put(
|
|
`payment:${idempotencyKey}`,
|
|
JSON.stringify(result),
|
|
{ expirationTtl: 86400 } // 24 hours
|
|
});
|
|
|
|
return result;
|
|
});
|
|
|
|
return { orderId, transactionId: paymentResult.transactionId };
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Pattern 2: Database Upsert for Idempotency
|
|
|
|
```typescript
|
|
await step.do('create order', async () => {
|
|
// Use INSERT OR REPLACE to make idempotent
|
|
await this.env.DB.prepare(`
|
|
INSERT INTO orders (id, user_id, amount, status, created_at)
|
|
VALUES (?, ?, ?, ?, ?)
|
|
ON CONFLICT(id) DO UPDATE SET
|
|
user_id = excluded.user_id,
|
|
amount = excluded.amount,
|
|
updated_at = CURRENT_TIMESTAMP
|
|
`).bind(
|
|
orderId,
|
|
userId,
|
|
amount,
|
|
'pending',
|
|
new Date().toISOString()
|
|
).run();
|
|
|
|
return { orderId };
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## Error Handling Patterns
|
|
|
|
### Pattern 1: Categorize Errors for Retry Logic
|
|
|
|
```typescript
|
|
async function shouldRetry(error: Error): Promise<boolean> {
|
|
// Don't retry on client errors (4xx)
|
|
if (error.message.includes('400') ||
|
|
error.message.includes('401') ||
|
|
error.message.includes('403') ||
|
|
error.message.includes('404')) {
|
|
return false;
|
|
}
|
|
|
|
// Retry on server errors (5xx) and network errors
|
|
return true;
|
|
}
|
|
|
|
await step.do('call API', async () => {
|
|
try {
|
|
const response = await fetch('https://api.example.com/data');
|
|
|
|
if (!response.ok) {
|
|
const error = new Error(`API error: ${response.status}`);
|
|
|
|
if (!await shouldRetry(error)) {
|
|
throw new NonRetryableError(error.message);
|
|
}
|
|
|
|
throw error; // Will retry
|
|
}
|
|
|
|
return await response.json();
|
|
} catch (error) {
|
|
if (error instanceof NonRetryableError) {
|
|
throw error;
|
|
}
|
|
|
|
// Network error - retry
|
|
throw error;
|
|
}
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
### Pattern 2: Circuit Breaker
|
|
|
|
```typescript
|
|
export class CircuitBreaker {
|
|
constructor(
|
|
private kv: KVNamespace,
|
|
private serviceName: string,
|
|
private threshold: number = 5,
|
|
private resetTime: number = 60000 // 1 minute
|
|
) {}
|
|
|
|
async call<T>(fn: () => Promise<T>): Promise<T> {
|
|
const key = `circuit:${this.serviceName}`;
|
|
const state = await this.kv.get(key, 'json') as {
|
|
failures: number;
|
|
lastFailure: number;
|
|
} | null;
|
|
|
|
// Check if circuit is open
|
|
if (state && state.failures >= this.threshold) {
|
|
const elapsed = Date.now() - state.lastFailure;
|
|
|
|
if (elapsed < this.resetTime) {
|
|
throw new NonRetryableError(
|
|
`Circuit breaker open for ${this.serviceName}`
|
|
);
|
|
}
|
|
}
|
|
|
|
try {
|
|
const result = await fn();
|
|
|
|
// Reset on success
|
|
await this.kv.delete(key);
|
|
|
|
return result;
|
|
} catch (error) {
|
|
// Increment failure count
|
|
const newState = {
|
|
failures: (state?.failures || 0) + 1,
|
|
lastFailure: Date.now()
|
|
};
|
|
|
|
await this.kv.put(key, JSON.stringify(newState), {
|
|
expirationTtl: this.resetTime / 1000
|
|
});
|
|
|
|
throw error;
|
|
}
|
|
}
|
|
}
|
|
|
|
// Usage
|
|
export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
|
|
async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
|
|
const circuitBreaker = new CircuitBreaker(this.env.KV, 'external-api');
|
|
|
|
await step.do('call external API', async () => {
|
|
return await circuitBreaker.call(async () => {
|
|
const response = await fetch('https://external-api.example.com/data');
|
|
return await response.json();
|
|
});
|
|
});
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Pattern 3: Graceful Degradation
|
|
|
|
```typescript
|
|
await step.do('fetch user preferences', async () => {
|
|
try {
|
|
const response = await fetch(`https://api.example.com/users/${userId}/preferences`);
|
|
if (!response.ok) throw new Error('Failed to fetch preferences');
|
|
return await response.json();
|
|
} catch (error) {
|
|
console.warn('Failed to fetch preferences, using defaults:', error);
|
|
|
|
// Fallback to defaults
|
|
return {
|
|
theme: 'light',
|
|
language: 'en',
|
|
notifications: true
|
|
};
|
|
}
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## Long-Running Process Patterns
|
|
|
|
### Pattern 1: Polling with Exponential Backoff
|
|
|
|
```typescript
|
|
export class VideoProcessingWorkflow extends WorkflowEntrypoint<Env, VideoParams> {
|
|
async run(event: WorkflowEvent<VideoParams>, step: WorkflowStep) {
|
|
const { videoId } = event.payload;
|
|
|
|
// Submit video for processing
|
|
const jobId = await step.do('submit video', async () => {
|
|
const response = await fetch('https://processor.example.com/jobs', {
|
|
method: 'POST',
|
|
body: JSON.stringify({ videoId })
|
|
});
|
|
const data = await response.json();
|
|
return data.jobId;
|
|
});
|
|
|
|
// Poll for completion with exponential backoff
|
|
let complete = false;
|
|
let attempt = 0;
|
|
const maxAttempts = 20;
|
|
|
|
while (!complete && attempt < maxAttempts) {
|
|
// Wait with exponential backoff: 10s, 20s, 40s, ...
|
|
const delay = Math.min(10 * Math.pow(2, attempt), 300); // Max 5 minutes
|
|
await step.sleep(`wait attempt ${attempt}`, `${delay} seconds`);
|
|
|
|
const status = await step.do(`check status attempt ${attempt}`, async () => {
|
|
const response = await fetch(
|
|
`https://processor.example.com/jobs/${jobId}/status`
|
|
);
|
|
return await response.json();
|
|
});
|
|
|
|
if (status.state === 'complete') {
|
|
complete = true;
|
|
} else if (status.state === 'failed') {
|
|
throw new NonRetryableError(`Processing failed: ${status.error}`);
|
|
}
|
|
|
|
attempt++;
|
|
}
|
|
|
|
if (!complete) {
|
|
throw new Error('Processing timeout after maximum attempts');
|
|
}
|
|
|
|
return { videoId, jobId, status: 'complete' };
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Pattern 2: Progress Tracking
|
|
|
|
```typescript
|
|
export class DataMigrationWorkflow extends WorkflowEntrypoint<Env, MigrationParams> {
|
|
async run(event: WorkflowEvent<MigrationParams>, step: WorkflowStep) {
|
|
const { totalRecords, batchSize } = event.payload;
|
|
const batches = Math.ceil(totalRecords / batchSize);
|
|
|
|
for (let i = 0; i < batches; i++) {
|
|
const progress = await step.do(`migrate batch ${i}`, async () => {
|
|
const offset = i * batchSize;
|
|
|
|
// Migrate batch
|
|
await this.migrateBatch(offset, batchSize);
|
|
|
|
// Update progress in DB
|
|
const percentage = Math.round(((i + 1) / batches) * 100);
|
|
await this.env.DB.prepare(`
|
|
UPDATE migration_jobs
|
|
SET progress = ?, updated_at = ?
|
|
WHERE id = ?
|
|
`).bind(percentage, new Date().toISOString(), event.payload.jobId).run();
|
|
|
|
return { batch: i + 1, total: batches, percentage };
|
|
});
|
|
|
|
console.log(`Progress: ${progress.percentage}%`);
|
|
|
|
// Small delay between batches to avoid overwhelming database
|
|
if (i < batches - 1) {
|
|
await step.sleep(`pause before batch ${i + 1}`, '1 second');
|
|
}
|
|
}
|
|
|
|
return { status: 'complete', batches };
|
|
}
|
|
|
|
private async migrateBatch(offset: number, limit: number) {
|
|
// Migration logic
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Human-in-the-Loop Patterns
|
|
|
|
### Pattern 1: Approval with Timeout and Escalation
|
|
|
|
```typescript
|
|
export class ApprovalWorkflow extends WorkflowEntrypoint<Env, ApprovalParams> {
|
|
async run(event: WorkflowEvent<ApprovalParams>, step: WorkflowStep) {
|
|
const { requestId, amount } = event.payload;
|
|
|
|
// Send to primary approver
|
|
await step.do('notify primary approver', async () => {
|
|
await this.sendApprovalRequest('manager@example.com', requestId);
|
|
});
|
|
|
|
// Wait 48 hours for approval
|
|
let approved: boolean;
|
|
let approver: string;
|
|
|
|
try {
|
|
const decision = await step.waitForEvent<ApprovalEvent>(
|
|
'wait for primary approval',
|
|
{ type: 'approval-decision', timeout: '48 hours' }
|
|
);
|
|
|
|
approved = decision.approved;
|
|
approver = decision.approverId;
|
|
} catch (error) {
|
|
// Timeout - escalate to senior manager
|
|
console.log('Primary approval timeout, escalating');
|
|
|
|
await step.do('notify senior approver', async () => {
|
|
await this.sendApprovalRequest('senior-manager@example.com', requestId);
|
|
});
|
|
|
|
// Wait another 24 hours
|
|
const escalatedDecision = await step.waitForEvent<ApprovalEvent>(
|
|
'wait for escalated approval',
|
|
{ type: 'approval-decision', timeout: '24 hours' }
|
|
);
|
|
|
|
approved = escalatedDecision.approved;
|
|
approver = escalatedDecision.approverId;
|
|
}
|
|
|
|
if (approved) {
|
|
await step.do('execute approved action', async () => {
|
|
// Execute the action
|
|
});
|
|
}
|
|
|
|
return { requestId, approved, approver };
|
|
}
|
|
|
|
private async sendApprovalRequest(to: string, requestId: string) {
|
|
// Send notification
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Workflow Chaining Patterns
|
|
|
|
### Pattern 1: Parent-Child Workflows
|
|
|
|
```typescript
|
|
export class OrderWorkflow extends WorkflowEntrypoint<Env, OrderParams> {
|
|
async run(event: WorkflowEvent<OrderParams>, step: WorkflowStep) {
|
|
const { orderId } = event.payload;
|
|
|
|
// Step 1: Process payment (separate workflow)
|
|
const paymentWorkflow = await step.do('start payment workflow', async () => {
|
|
const instance = await this.env.PAYMENT_WORKFLOW.create({
|
|
params: { orderId, amount: event.payload.amount }
|
|
});
|
|
return { instanceId: instance.id };
|
|
});
|
|
|
|
// Step 2: Wait for payment to complete
|
|
let paymentComplete = false;
|
|
|
|
while (!paymentComplete) {
|
|
await step.sleep('wait for payment', '30 seconds');
|
|
|
|
const paymentStatus = await step.do('check payment status', async () => {
|
|
const instance = await this.env.PAYMENT_WORKFLOW.get(
|
|
paymentWorkflow.instanceId
|
|
);
|
|
return await instance.status();
|
|
});
|
|
|
|
if (paymentStatus.status === 'complete') {
|
|
paymentComplete = true;
|
|
} else if (paymentStatus.status === 'errored') {
|
|
throw new Error(`Payment failed: ${paymentStatus.error}`);
|
|
}
|
|
}
|
|
|
|
// Step 3: Start fulfillment workflow
|
|
await step.do('start fulfillment workflow', async () => {
|
|
await this.env.FULFILLMENT_WORKFLOW.create({
|
|
params: { orderId }
|
|
});
|
|
});
|
|
|
|
return { orderId, status: 'processing' };
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Testing Patterns
|
|
|
|
### Pattern 1: Mock External APIs
|
|
|
|
```typescript
|
|
import { describe, it, expect, beforeEach } from 'vitest';
|
|
import { unstable_dev } from 'wrangler';
|
|
|
|
describe('PaymentWorkflow', () => {
|
|
let worker;
|
|
|
|
beforeEach(async () => {
|
|
worker = await unstable_dev('src/index.ts', {
|
|
experimental: { disableExperimentalWarning: true }
|
|
});
|
|
});
|
|
|
|
it('should process payment successfully', async () => {
|
|
// Mock fetch to return success
|
|
globalThis.fetch = async (url: string) => {
|
|
if (url.includes('payment-gateway')) {
|
|
return new Response(JSON.stringify({
|
|
transactionId: 'TXN-123',
|
|
status: 'success'
|
|
}));
|
|
}
|
|
return new Response('Not found', { status: 404 });
|
|
};
|
|
|
|
const response = await worker.fetch('/workflows/create', {
|
|
method: 'POST',
|
|
body: JSON.stringify({
|
|
orderId: 'ORD-123',
|
|
amount: 99.99
|
|
})
|
|
});
|
|
|
|
const data = await response.json();
|
|
expect(data.id).toBeDefined();
|
|
});
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## Monitoring Patterns
|
|
|
|
### Pattern 1: Structured Logging
|
|
|
|
```typescript
|
|
export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
|
|
async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
|
|
this.log('info', 'Workflow started', {
|
|
instanceId: event.instanceId,
|
|
params: event.payload
|
|
});
|
|
|
|
try {
|
|
await step.do('process data', async () => {
|
|
this.log('info', 'Processing data', { userId: event.payload.userId });
|
|
// Process
|
|
return { processed: true };
|
|
});
|
|
|
|
this.log('info', 'Workflow completed successfully', {
|
|
instanceId: event.instanceId
|
|
});
|
|
} catch (error) {
|
|
this.log('error', 'Workflow failed', {
|
|
instanceId: event.instanceId,
|
|
error: error instanceof Error ? error.message : 'Unknown error'
|
|
});
|
|
throw error;
|
|
}
|
|
}
|
|
|
|
private log(level: string, message: string, data: any) {
|
|
console.log(JSON.stringify({
|
|
level,
|
|
message,
|
|
timestamp: new Date().toISOString(),
|
|
...data
|
|
}));
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Pattern 2: Metrics Tracking
|
|
|
|
```typescript
|
|
await step.do('track metrics', async () => {
|
|
const metrics = {
|
|
workflowId: event.instanceId,
|
|
stepName: 'payment-processing',
|
|
duration: performance.now() - startTime,
|
|
status: 'success',
|
|
timestamp: new Date().toISOString()
|
|
};
|
|
|
|
// Store in Analytics Engine
|
|
await this.env.ANALYTICS.writeDataPoint(metrics);
|
|
|
|
return metrics;
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## Best Practices Summary
|
|
|
|
### Always Do
|
|
|
|
1. **Use idempotency keys** for external API calls
|
|
2. **Categorize errors** - retry on transient failures, fail fast on terminal errors
|
|
3. **Log structured data** - JSON logs for easy querying
|
|
4. **Track progress** - update database for long-running processes
|
|
5. **Use exponential backoff** - for polling and retries
|
|
6. **Test workflows** - unit tests with mocked dependencies
|
|
7. **Monitor metrics** - track success rates, durations, errors
|
|
|
|
### Never Do
|
|
|
|
1. **Don't retry non-idempotent operations infinitely** - use retry limits
|
|
2. **Don't ignore timeout errors** - handle gracefully with fallbacks
|
|
3. **Don't block on external events without timeout** - always set timeout
|
|
4. **Don't assume steps execute in order** - each step is independent
|
|
5. **Don't return non-serializable values** - only JSON-compatible types
|
|
6. **Don't store sensitive data in workflow state** - use KV/D1 instead
|
|
7. **Don't forget to clean up resources** - terminate unused workflow instances
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-10-22
|
|
**Maintainer**: Jeremy Dawes | jeremy@jezweb.net
|