Cloudflare Workflows 실전 가이드: Durable Objects 기반의 서버리스 내결함성 재시도 파이프라인

Cloudflare Workflows 실전 가이드: 타임아웃 없는 서버리스 내결함성 파이프라인

기존 서버리스 환경(AWS Lambda, Cloudflare Workers)의 가장 큰 약점은 **단기 실행 타임아웃(Short Execution Timeouts)**과 상태 보존(State Persistence)의 미비였습니다. 외부 API 호출 지연, 대용량 파일 변환, AI 이미지/텍스트 생성 파이프라인 등 몇 분 이상 소요되는 작업을 처리하려면 큐(Queue)와 DB, 람다 함수를 복잡하게 엮어야 했습니다.

Cloudflare가 출시한 **Cloudflare Workflows**는 Durable Objects의 영속적 상태 저장 아키텍처를 기반으로 한 **내결함성 워크플로우 엔진(Durable Execution Engine)**입니다. 코드 중간에 에러가 발생하거나 서버가 재시작되어도, 완료된 스텝의 상태가 자동 보존되어 미완료 스텝부터 정확히 재실행(Retry)됩니다.

본 가이드에서는 Cloudflare Workflows의 작동 원리, step.do / step.sleep 활용법, 그리고 AI 배치 처리 파이프라인 구축 실전 코드를 소개합니다.

1. Traditional Serverless vs Cloudflare Workflows 비교

2. Workflows 핵심 프로그래밍 모델

Cloudflare Workflows는 TypeScript 클래스로 정의하며 WorkflowEntrypoint를 상속받습니다.

3대 핵심 API

1. step.do(name, config, callback): 독립적으로 상태가 체크포인팅되는 최소 작업 단위입니다. 해당 블록이 성공하면 결과가 Durable Storage에 자동 저장됩니다.
2. step.sleep(name, duration): 비동기 프로세스를 지정한 시간(초, 분, 일) 동안 정지시킵니다. 대기 기간 동안 CPU 코어를 소모하지 않습니다.
3. step.sleepUntil(name, timestamp): 특정 시각까지 작업을 안전하게 대기시킵니다.

3. 실전 예제: AI 콘텐츠 생성 및 이메일 발송 파이프라인

다음은 AI 요약 생성 후 외부 API 재시도 처리, 10초 대기, 최종 발송까지 보장하는 내결함성 워크플로우 코드입니다.

import { WorkflowEntrypoint, WorkflowEvent, WorkflowStep } from 'cloudflare:workers';

type Env = {
  AI: any;
  MY_WORKFLOW: Workflow;
};

type Params = {
  articleId: string;
  userEmail: string;
  rawText: string;
};

export class ArticleSummaryWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    const { articleId, userEmail, rawText } = event.payload;

    // Step 1: AI 요약 생성 (자동 체크포인팅)
    const summary = await step.do('generate-summary', async () => {
      const aiResponse = await this.env.AI.run('@cf/meta/llama-3.3-70b-instruct-fp8-fast', {
        prompt: `다음 글을 3줄 요약해줘: ${rawText}`,
      });
      return aiResponse.summary;
    });

    // Step 2: 외부 웹훅 전송 (실패 시 최대 3회 재시도 설정)
    const webhookResult = await step.do(
      'send-webhook',
      {
        retries: {
          limit: 3,
          delay: '5 seconds',
          backoff: 'exponential',
        },
        timeout: '10 seconds',
      },
      async () => {
        const res = await fetch('https://api.example.com/webhooks/summary', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ articleId, summary }),
        });
        if (!res.ok) throw new Error(`HTTP Error: ${res.status}`);
        return await res.json();
      }
    );

    // Step 3: 사용자 확인을 위한 10초 대기 (CPU 타임 과금 $0)
    await step.sleep('wait-before-email', '10 seconds');

    // Step 4: 최종 이메일 발송 완료
    await step.do('send-email', async () => {
      console.log(`이메일 발송 완료 [${userEmail}]: ${summary}`);
      return { status: 'sent', sentAt: new Date().toISOString() };
    });
  }
}

Wrangler 설정 (wrangler.jsonc)

{
  "name": "my-durable-pipeline",
  "main": "src/index.ts",
  "compatibility_date": "2026-07-30",
  "workflows": [
    {
      "name": "article-summary-workflow",
      "binding": "MY_WORKFLOW",
      "class_name": "ArticleSummaryWorkflow"
    }
  ]
}

4. 요약 및 핵심 이점

1. **Cloudflare Workflows**는 Durable Objects 기반으로 작동하므로 백엔드 타임아웃 걱정 없이 긴 배치 작업을 처리할 수 있습니다.
2. 각 **step.do**의 결과가 자동 저장되어 중간 장애 시에도 이전 스텝을 재실행하지 않고 실패 스텝부터 즉시 재개합니다.
3. AWS Step Functions 대비 훨씬 단순한 TypeScript 코드 정의와 뛰어난 비용 효율성을 제공합니다.