Guía Práctica de Cloudflare Workflows: Pipeline Servidor Sin Fallos Basado en Durable Objects

Guía Práctica de Cloudflare Workflows: Pipelines Sin Tiempos de Espera

El principal inconveniente de los entornos serverless tradicionales (AWS Lambda, Cloudflare Workers) ha sido siempre el tiempo máximo de ejecución limitado y la ausencia de estado persistente. Coordinar tareas de larga duración, como procesamientos en lote o integración de APIs de IA, requería conectar múltiples colas y bases de datos.

Cloudflare Workflows resuelve este problema mediante un motor de ejecución duradera (Durable Execution) fundamentado en Durable Objects. Incluso si un paso intermedio falla o un nodo de borde se reinicia, los pasos completados se guardan automáticamente en almacenamiento persistente.

En esta guía analizamos la arquitectura de Cloudflare Workflows, las funciones step.do y step.sleep, y la implementación de un pipeline con reintentos automáticos.

1. Serverless Tradicional vs Cloudflare Workflows

2. Modelo de Programación de Workflows

Cloudflare Workflows se define como una clase TypeScript que extiende de WorkflowEntrypoint.

3 APIs Fundamentales

1. step.do(name, config, callback): Unidad básica de ejecución. El resultado devuelto se guarda automáticamente en almacenamiento persistente.
2. step.sleep(name, duration): Pausa la ejecución durante el tiempo indicado sin consumir tiempo de CPU.
3. step.sleepUntil(name, timestamp): Suspende la ejecución hasta una marca de tiempo UTC concreta.

3. Ejemplo Práctico: Pipeline de IA con Reintentos

Código completo de un flujo de trabajo que genera resúmenes con IA, realiza reintentos con backoff exponencial y envía notificaciones:

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;

    // Paso 1: Generación de Resumen con IA (Checkpointed)
    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: `Resume el siguiente texto en 3 puntos: ${rawText}`,
      });
      return aiResponse.summary;
    });

    // Paso 2: Envío de Webhook con Reintentos Automáticos
    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();
      }
    );

    // Paso 3: Espera pasiva (Coste $0 de CPU)
    await step.sleep('wait-before-email', '10 seconds');

    // Paso 4: Envío Final de Correo
    await step.do('send-email', async () => {
      console.log(`Correo enviado a [${userEmail}]: ${summary}`);
      return { status: 'sent', sentAt: new Date().toISOString() };
    });
  }
}

4. Conclusión

1. Cloudflare Workflows elimina los tiempos de espera serverless almacenando el estado de ejecución en Durable Objects.
2. Los checkpoints por paso garantizan la reanudación exacta tras un fallo imprevisto.
3. Ofrece una experiencia de desarrollo mucho más simple y económica que AWS Step Functions.