secondsky/claude-skills / plugins/cloudflare-workflows/skills/cloudflare-workflows
cloudflare-workflows
VerifiedCloudflare Workflows for durable long-running execution. Use for multi-step workflows, retries, state persistence, or encountering NonRetryableError, execution failed errors.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.5 KB |
| references/2025-features.md | markdown | 7.9 KB |
| references/common-issues.md | markdown | 9.9 KB |
| references/limits-quotas.md | markdown | 8.7 KB |
| references/metrics-analytics.md | markdown | 11.7 KB |
| references/production-checklist.md | markdown | 11.8 KB |
| references/troubleshooting.md | markdown | 15.1 KB |
| references/workflow-patterns.md | markdown | 15.2 KB |
| references/wrangler-commands.md | markdown | 6.6 KB |
| templates/basic-workflow.ts | script | 3.4 KB |
| templates/circuit-breaker-workflow.ts | script | 12.6 KB |
| templates/parallel-execution-workflow.ts | script | 8.6 KB |
| templates/scheduled-workflow.ts | script | 7.2 KB |
| templates/worker-trigger.ts | script | 6.6 KB |
| templates/workflow-with-events.ts | script | 9.2 KB |
| templates/workflow-with-retries.ts | script | 6.2 KB |
| templates/wrangler-workflows-config.jsonc | other | 3.8 KB |
templates/circuit-breaker-workflow.ts
View on GitHub/**
* Circuit Breaker Workflow
*
* Implements the Circuit Breaker pattern for resilient external service calls.
* Prevents cascade failures by detecting unhealthy services and failing fast.
*
* Key Concepts:
* - Circuit states: CLOSED (normal), OPEN (failing fast), HALF_OPEN (testing)
* - Failure threshold before opening circuit
* - Automatic recovery after timeout
* - Fallback behavior when circuit is open
*
* Usage:
* 1. Copy this file to src/workflows/
* 2. Update Env and Params types for your use case
* 3. Configure circuit breaker settings
* 4. Export from src/index.ts
* 5. Add to wrangler.jsonc workflows array
*/
import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from 'cloudflare:workers';
import { NonRetryableError } from 'cloudflare:workflows';
// Environment bindings
interface Env {
CIRCUIT_WORKFLOW: Workflow;
KV: KVNamespace; // For storing circuit state across instances
}
// Workflow input parameters
interface Params {
serviceId: string; // ID of the service to call
endpoint: string; // API endpoint
payload?: unknown; // Request payload
fallbackValue?: unknown; // Value to return when circuit is open
}
// Circuit breaker configuration
interface CircuitConfig {
failureThreshold: number; // Failures before opening (default: 5)
resetTimeoutMs: number; // Time before trying again (default: 60000)
halfOpenSuccesses: number; // Successes to close circuit (default: 3)
monitorWindowMs: number; // Time window for failure counting (default: 60000)
}
// Circuit state stored in KV
interface CircuitState {
status: 'CLOSED' | 'OPEN' | 'HALF_OPEN';
failures: number;
successes: number;
lastFailure: number;
lastSuccess: number;
openedAt?: number;
}
// Default configuration
const DEFAULT_CONFIG: CircuitConfig = {
failureThreshold: 5,
resetTimeoutMs: 60000, // 1 minute
halfOpenSuccesses: 3,
monitorWindowMs: 60000 // 1 minute window for counting failures
};
/**
* Circuit Breaker implementation using KV for distributed state
*/
class CircuitBreaker {
private env: Env;
private serviceId: string;
private config: CircuitConfig;
constructor(env: Env, serviceId: string, config: Partial<CircuitConfig> = {}) {
this.env = env;
this.serviceId = serviceId;
this.config = { ...DEFAULT_CONFIG, ...config };
}
private getKey(): string {
return `circuit:${this.serviceId}`;
}
async getState(): Promise<CircuitState> {
const stored = await this.env.KV.get(this.getKey(), 'json');
if (!stored) {
return {
status: 'CLOSED',
failures: 0,
successes: 0,
lastFailure: 0,
lastSuccess: 0
};
}
return stored as CircuitState;
}
async setState(state: CircuitState): Promise<void> {
await this.env.KV.put(
this.getKey(),
JSON.stringify(state),
{ expirationTtl: 86400 } // 24 hour TTL
);
}
async canExecute(): Promise<{ allowed: boolean; state: CircuitState }> {
const state = await this.getState();
const now = Date.now();
switch (state.status) {
case 'CLOSED':
// Normal operation - allow execution
return { allowed: true, state };
case 'OPEN':
// Check if reset timeout has elapsed
if (state.openedAt && now - state.openedAt >= this.config.resetTimeoutMs) {
// Transition to HALF_OPEN
const newState: CircuitState = {
...state,
status: 'HALF_OPEN',
successes: 0
};
await this.setState(newState);
return { allowed: true, state: newState };
}
// Still open - fail fast
return { allowed: false, state };
case 'HALF_OPEN':
// Allow limited traffic to test recovery
return { allowed: true, state };
default:
return { allowed: true, state };
}
}
async recordSuccess(): Promise<CircuitState> {
const state = await this.getState();
const now = Date.now();
const newState: CircuitState = {
...state,
lastSuccess: now,
successes: state.successes + 1
};
if (state.status === 'HALF_OPEN') {
// Check if we've had enough successes to close
if (newState.successes >= this.config.halfOpenSuccesses) {
newState.status = 'CLOSED';
newState.failures = 0;
newState.openedAt = undefined;
console.log(`Circuit ${this.serviceId}: HALF_OPEN -> CLOSED (recovered)`);
}
} else if (state.status === 'CLOSED') {
// Reset failure count on success
newState.failures = 0;
}
await this.setState(newState);
return newState;
}
async recordFailure(): Promise<CircuitState> {
const state = await this.getState();
const now = Date.now();
// Only count failures within the monitoring window
const recentFailures = state.lastFailure > now - this.config.monitorWindowMs
? state.failures + 1
: 1;
const newState: CircuitState = {
...state,
failures: recentFailures,
lastFailure: now,
successes: 0
};
if (state.status === 'HALF_OPEN') {
// Any failure in HALF_OPEN reopens the circuit
newState.status = 'OPEN';
newState.openedAt = now;
console.log(`Circuit ${this.serviceId}: HALF_OPEN -> OPEN (still failing)`);
} else if (state.status === 'CLOSED') {
// Check if we've exceeded failure threshold
if (newState.failures >= this.config.failureThreshold) {
newState.status = 'OPEN';
newState.openedAt = now;
console.log(`Circuit ${this.serviceId}: CLOSED -> OPEN (threshold exceeded)`);
}
}
await this.setState(newState);
return newState;
}
}
/**
* Call external service with timeout
*/
async function callService(
endpoint: string,
payload?: unknown,
timeoutMs = 10000
): Promise<{ success: boolean; data?: unknown; error?: string }> {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), timeoutMs);
try {
const response = await fetch(endpoint, {
method: payload ? 'POST' : 'GET',
headers: { 'Content-Type': 'application/json' },
body: payload ? JSON.stringify(payload) : undefined,
signal: controller.signal
});
if (!response.ok) {
return {
success: false,
error: `HTTP ${response.status}: ${response.statusText}`
};
}
const data = await response.json();
return { success: true, data };
} catch (error) {
if (error instanceof Error && error.name === 'AbortError') {
return { success: false, error: 'Request timeout' };
}
return {
success: false,
error: error instanceof Error ? error.message : 'Unknown error'
};
} finally {
clearTimeout(timeout);
}
}
export class CircuitBreakerWorkflow extends WorkflowEntrypoint<Env, Params> {
async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
const { serviceId, endpoint, payload, fallbackValue } = event.payload;
console.log('Starting circuit breaker workflow', {
instanceId: event.instanceId,
serviceId,
endpoint
});
// Initialize circuit breaker
const circuitBreaker = new CircuitBreaker(this.env, serviceId, {
failureThreshold: 5,
resetTimeoutMs: 60000,
halfOpenSuccesses: 3
});
// Check circuit state
const circuitCheck = await step.do('check circuit', async () => {
const { allowed, state } = await circuitBreaker.canExecute();
console.log(`Circuit ${serviceId} state:`, {
status: state.status,
failures: state.failures,
allowed
});
return { allowed, state };
});
// If circuit is open, return fallback immediately
if (!circuitCheck.allowed) {
console.log(`Circuit ${serviceId} is OPEN - using fallback`);
if (fallbackValue !== undefined) {
return {
status: 'fallback',
circuitState: circuitCheck.state.status,
data: fallbackValue
};
}
throw new NonRetryableError(
`Circuit breaker for ${serviceId} is OPEN. Service unavailable.`
);
}
// Attempt to call the service
const result = await step.do(
'call service',
{
retries: {
limit: 2,
delay: '1 second',
backoff: 'constant'
}
},
async () => {
const response = await callService(endpoint, payload);
if (!response.success) {
// Record failure and throw to trigger retry
await circuitBreaker.recordFailure();
throw new Error(response.error);
}
// Record success
await circuitBreaker.recordSuccess();
return response.data;
}
);
return {
status: 'success',
circuitState: 'CLOSED',
data: result
};
}
}
/**
* Multi-Service Circuit Breaker Workflow
*
* Demonstrates calling multiple services with independent circuit breakers.
*/
interface MultiServiceParams {
services: Array<{
id: string;
endpoint: string;
required: boolean; // If true, workflow fails when circuit is open
}>;
}
export class MultiServiceWorkflow extends WorkflowEntrypoint<Env, MultiServiceParams> {
async run(event: WorkflowEvent<MultiServiceParams>, step: WorkflowStep) {
const { services } = event.payload;
const results: Record<string, { success: boolean; data?: unknown; error?: string }> = {};
for (const service of services) {
const circuitBreaker = new CircuitBreaker(this.env, service.id);
const result = await step.do(`call ${service.id}`, async () => {
const { allowed, state } = await circuitBreaker.canExecute();
if (!allowed) {
if (service.required) {
throw new NonRetryableError(
`Required service ${service.id} unavailable (circuit OPEN)`
);
}
return { success: false, error: 'Circuit open', skipped: true };
}
const response = await callService(service.endpoint);
if (response.success) {
await circuitBreaker.recordSuccess();
} else {
await circuitBreaker.recordFailure();
}
return response;
});
results[service.id] = result;
}
const allRequired = services
.filter(s => s.required)
.every(s => results[s.id]?.success);
return {
allRequiredSucceeded: allRequired,
results
};
}
}
/**
* Retry with Backoff and Circuit Breaker
*
* Combines Cloudflare's built-in retry with circuit breaker pattern.
*/
export class RetryWithCircuitWorkflow extends WorkflowEntrypoint<Env, Params> {
async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
const { serviceId, endpoint, payload } = event.payload;
const circuitBreaker = new CircuitBreaker(this.env, serviceId, {
failureThreshold: 3,
resetTimeoutMs: 30000 // 30 seconds
});
// First check: is circuit already open?
const preCheck = await step.do('pre-check circuit', async () => {
const { allowed, state } = await circuitBreaker.canExecute();
return { allowed, status: state.status };
});
if (!preCheck.allowed) {
// Wait for circuit reset timeout
await step.sleep('wait for circuit reset', '30 seconds');
// Re-check after waiting
const reCheck = await step.do('re-check circuit', async () => {
const { allowed, state } = await circuitBreaker.canExecute();
return { allowed, status: state.status };
});
if (!reCheck.allowed) {
throw new NonRetryableError(
`Service ${serviceId} still unavailable after waiting`
);
}
}
// Attempt with Cloudflare's retry + manual circuit breaker updates
const result = await step.do(
'call with retry',
{
retries: {
limit: 5,
delay: '2 seconds',
backoff: 'exponential' // 2s, 4s, 8s, 16s, 32s
}
},
async () => {
const response = await callService(endpoint, payload);
if (!response.success) {
// Record failure for circuit breaker
const state = await circuitBreaker.recordFailure();
// If circuit just opened, throw NonRetryableError to stop retries
if (state.status === 'OPEN') {
throw new NonRetryableError(
`Circuit opened after ${state.failures} failures: ${response.error}`
);
}
// Otherwise throw regular error to continue retrying
throw new Error(response.error);
}
// Success - record it
await circuitBreaker.recordSuccess();
return response.data;
}
);
return {
status: 'success',
data: result
};
}
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |