Durable Object Patterns on Cloudflare Workers

Stateful compute primitives for the edge — four production patterns, design principles, and practical examples.

Cloudflare Durable Objects (DOs) are one of the most underappreciated primitives in cloud computing. They give you something no other serverless platform offers: a single-threaded, globally addressable, stateful compute unit that lives as long as you need it to.

This is not a getting-started tutorial. This is a pattern catalog for engineers building production systems on Durable Objects. Every pattern here comes from real deployed code.

Table of Contents

Why Durable Objects Matter

Every serverless platform gives you stateless compute. Most bolt on state through external databases — DynamoDB, Redis, Postgres. This works, but it creates a fundamental tension: your compute is ephemeral but your state is not, and the glue between them (connection pooling, caching, consistency) becomes the hardest part of your system.

Durable Objects resolve this tension by fusing state and compute into a single primitive:

• Persistent state: Each DO has its own transactional storage (key-value or SQLite). State survives restarts, deployments, and migrations.
• Single-threaded execution: Only one request executes at a time within a DO. No locks, no races, no distributed consensus. If your code is running, you have exclusive access to your state.
• Global addressing: Every DO has a unique ID. Any Worker, anywhere in the world, can send a request to any DO by its ID. Cloudflare routes to the right machine automatically.
• Location intelligence: DOs migrate to be near their callers. A DO serving mostly European users will run in Europe.
• Alarm scheduling: A DO can set an alarm to wake itself up in the future — even if no external requests arrive.

These properties combine to make DOs the natural home for control logic: the code that decides what to do, when to do it, and how to adapt when things go wrong.

+------------------------------------------------------+
|                    The Key Insight                    |
|                                                      |
|  A Durable Object is not a database row.             |
|  It's not a cache entry.                             |
|  It's not a microservice.                            |
|                                                      |
|  It's a tiny, autonomous agent with perfect memory   |
|  and a guaranteed single thread of execution.        |
|                                                      |
|  Think of it as an actor that never forgets.         |
+------------------------------------------------------+

What DOs Are Good At

What DOs Are Not Good At

DOs are not general-purpose databases. They are not designed for fan-out queries across thousands of entities. Each DO is independent — there is no cross-DO transaction or query. If you need to search across all your DOs, you need a separate index (D1, KV, or a dedicated indexing DO).

The Meta-Pattern: Control Plane / Data Plane

Before diving into specific patterns, understand the architectural meta-pattern that all four share:

+----------------------------------------------------------+
|                    CONTROL PLANE (DO)                     |
|                                                          |
|  * Scheduling: when should work happen?                  |
|  * Routing: which worker/model/service handles it?       |
|  * Budget: how much resource to allocate?                |
|  * Decisions: what to do based on observed state?        |
|  * Adaptation: how to adjust based on results?           |
|                                                          |
|  State: metrics, config, decision history, budgets       |
|  Execution: single-threaded, alarm-driven                |
+--------------------+---------------------+---------------+
                     |  commands/config     |  results/telemetry
                     v                      ^
+----------------------------------------------------------+
|                   DATA PLANE (Workers)                    |
|                                                          |
|  * Processing: do the actual work                        |
|  * I/O: call APIs, read databases, transform data        |
|  * Parallelism: fan out across many Workers              |
|  * Stateless: get config from DO, return results         |
|                                                          |
|  Also: Workflows, Queues, R2, D1, external APIs          |
+----------------------------------------------------------+

Why this separation matters:

1. Reasoning: All decision logic is in one place with one thread. You can read a DO’s code and understand every possible state transition. No distributed state to reason about.

2. Scaling: The data plane scales horizontally (more Workers, more Workflow instances). The control plane does not need to scale — it just coordinates.

3. Resilience: If the data plane fails (API timeout, bad response), the control plane observes the failure, adapts, and retries. The controller never crashes because a downstream call failed.

4. Observability: Every decision is made in the DO, so every decision can be logged with full context. You do not need distributed tracing to understand why something happened — the DO knows.

Every pattern in this article is a variation of this meta-pattern. The Adaptive Controller adapts batch sizes. The Budget Governor allocates resources. The Event Reactor makes decisions based on domain events. The Storage Sidecar provides state to a Workflow control plane. They all separate “deciding what to do” from “doing it.”

Pattern 1: Adaptive Controller

A self-driving batch processor that learns from its own performance.

This is the most common DO pattern in production. You have a recurring task — enriching records, syncing data, processing a queue — and you need it to run reliably without manual tuning. The DO manages the batch loop: it processes a batch, measures success, and adjusts its own parameters.

The Problem

Fixed batch processing breaks in predictable ways:

• Batch too large -> downstream rate limits -> cascade failure
• Batch too small -> underutilized capacity -> slow throughput
• Fixed schedule -> no adaptation to load or API health
• External cron -> no state between runs -> can’t learn

The Solution

A Durable Object that:

1. Wakes itself on a schedule (alarm)
2. Processes a batch of work
3. Measures success rate and latency
4. Adjusts batch size based on observed performance
5. Repeats

// enrichment-controller.ts — Adaptive batch processor DO

interface ControllerState {
  // Adaptive parameters
  batchSize: number;
  intervalMs: number;

  // Rolling metrics (last 100 results)
  metrics: {
    successRate: number;
    avgLatencyMs: number;
    consecutiveErrors: number;
    results: Array<{ success: boolean; latencyMs: number; timestamp: number }>;
  };

  // Operational state
  status: "running" | "paused" | "backoff";
  lastRunAt: number;
  totalProcessed: number;
  totalErrors: number;
}

const DEFAULT_STATE: ControllerState = {
  batchSize: 10,
  intervalMs: 60_000, // 1 minute
  metrics: {
    successRate: 1.0,
    avgLatencyMs: 0,
    consecutiveErrors: 0,
    results: [],
  },
  status: "running",
  lastRunAt: 0,
  totalProcessed: 0,
  totalErrors: 0,
};

export class EnrichmentController implements DurableObject {
  private state: DurableObjectState;
  private env: Env;
  private controller: ControllerState = DEFAULT_STATE;

  constructor(state: DurableObjectState, env: Env) {
    this.state = state;
    this.env = env;

    // Restore state from storage on construction
    this.state.blockConcurrencyWhile(async () => {
      const stored = await this.state.storage.get<ControllerState>("controller");
      if (stored) {
        this.controller = stored;
      }
    });
  }

  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);

    switch (url.pathname) {
      case "/start":
        return this.start();
      case "/pause":
        return this.pause();
      case "/status":
        return Response.json(this.controller);
      case "/reset":
        return this.reset();
      default:
        return new Response("Not found", { status: 404 });
    }
  }

  // -- Lifecycle -----------------------------------------------

  private async start(): Promise<Response> {
    this.controller.status = "running";
    await this.scheduleNext();
    await this.save();
    return Response.json({ status: "started", batchSize: this.controller.batchSize });
  }

  private async pause(): Promise<Response> {
    this.controller.status = "paused";
    await this.state.storage.deleteAlarm();
    await this.save();
    return Response.json({ status: "paused" });
  }

  private async reset(): Promise<Response> {
    this.controller = { ...DEFAULT_STATE };
    await this.state.storage.deleteAlarm();
    await this.save();
    return Response.json({ status: "reset" });
  }

  // -- The Heartbeat -------------------------------------------

  async alarm(): Promise<void> {
    if (this.controller.status !== "running") return;

    try {
      // 1. Fetch a batch of work
      const items = await this.fetchPendingItems(this.controller.batchSize);

      if (items.length === 0) {
        // Nothing to do — schedule next check and return
        await this.scheduleNext();
        return;
      }

      // 2. Process the batch
      const results = await this.enrichBatch(items);

      // 3. Record metrics
      this.recordResults(results);

      // 4. Adapt based on performance
      this.adapt();

      // 5. Update operational counters
      this.controller.lastRunAt = Date.now();
      this.controller.totalProcessed += results.filter((r) => r.success).length;
      this.controller.totalErrors += results.filter((r) => !r.success).length;
    } catch (err) {
      // Entire batch failed — record as consecutive error
      this.controller.metrics.consecutiveErrors++;
      this.adapt();
      console.error("Controller alarm error:", err);
    }

    // Always schedule next run (even after errors)
    await this.scheduleNext();
    await this.save();
  }

  // -- Batch Processing ----------------------------------------

  private async fetchPendingItems(limit: number): Promise<WorkItem[]> {
    // Fetch from your data source — D1, KV, external API, etc.
    const response = await fetch(
      `${this.env.API_BASE}/items/pending?limit=${limit}`,
      { headers: { Authorization: `Bearer ${this.env.API_KEY}` } }
    );
    if (!response.ok) throw new Error(`Fetch failed: ${response.status}`);
    return response.json();
  }

  private async enrichBatch(
    items: WorkItem[]
  ): Promise<Array<{ success: boolean; latencyMs: number }>> {
    // Process items in parallel with individual error handling
    return Promise.all(
      items.map(async (item) => {
        const start = Date.now();
        try {
          await this.enrichItem(item);
          return { success: true, latencyMs: Date.now() - start };
        } catch {
          return { success: false, latencyMs: Date.now() - start };
        }
      })
    );
  }

  private async enrichItem(item: WorkItem): Promise<void> {
    // Your enrichment logic here — call an API, transform data, etc.
    const response = await fetch(`${this.env.ENRICHMENT_API}/enrich`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(item),
    });
    if (!response.ok) throw new Error(`Enrichment failed: ${response.status}`);

    // Write result back
    await fetch(`${this.env.API_BASE}/items/${item.id}`, {
      method: "PATCH",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${this.env.API_KEY}`,
      },
      body: JSON.stringify({ enriched: true, data: await response.json() }),
    });
  }

  // -- Metrics -------------------------------------------------

  private recordResults(
    results: Array<{ success: boolean; latencyMs: number }>
  ): void {
    const now = Date.now();

    // Add to rolling window
    for (const result of results) {
      this.controller.metrics.results.push({
        ...result,
        timestamp: now,
      });
    }

    // Keep only last 100 results
    if (this.controller.metrics.results.length > 100) {
      this.controller.metrics.results =
        this.controller.metrics.results.slice(-100);
    }

    // Recalculate aggregates
    const recent = this.controller.metrics.results;
    const successes = recent.filter((r) => r.success).length;
    this.controller.metrics.successRate = successes / recent.length;
    this.controller.metrics.avgLatencyMs =
      recent.reduce((sum, r) => sum + r.latencyMs, 0) / recent.length;

    // Track consecutive errors
    const allFailed = results.every((r) => !r.success);
    if (allFailed) {
      this.controller.metrics.consecutiveErrors++;
    } else {
      this.controller.metrics.consecutiveErrors = 0;
    }
  }

  // -- Adaptation ----------------------------------------------

  private adapt(): void {
    const { successRate, consecutiveErrors } = this.controller.metrics;

    if (consecutiveErrors >= 5) {
      // Circuit breaker: back off hard
      this.controller.batchSize = 5;
      this.controller.intervalMs = Math.min(
        this.controller.intervalMs * 2,
        300_000 // cap at 5 minutes
      );
      this.controller.status = "backoff";
      console.log(
        `[adapt] Circuit break: ${consecutiveErrors} consecutive errors. ` +
        `Batch=5, interval=${this.controller.intervalMs}ms`
      );
      return;
    }

    // Resume from backoff if things are improving
    if (this.controller.status === "backoff" && successRate > 0.8) {
      this.controller.status = "running";
      this.controller.intervalMs = 60_000;
      console.log("[adapt] Recovered from backoff");
    }

    if (successRate > 0.95) {
      // Excellent — increase batch size
      this.controller.batchSize = Math.min(
        Math.ceil(this.controller.batchSize * 1.5),
        50 // cap
      );
      console.log(
        `[adapt] Success rate ${(successRate * 100).toFixed(1)}% ` +
        `-> batch size ${this.controller.batchSize}`
      );
    } else if (successRate >= 0.8) {
      // Good — maintain current settings
      console.log(
        `[adapt] Success rate ${(successRate * 100).toFixed(1)}% ` +
        `-> maintaining batch size ${this.controller.batchSize}`
      );
    } else if (successRate >= 0.5) {
      // Degraded — reduce batch size
      this.controller.batchSize = Math.max(
        Math.floor(this.controller.batchSize * 0.5),
        5 // floor
      );
      console.log(
        `[adapt] Success rate ${(successRate * 100).toFixed(1)}% ` +
        `-> reduced batch to ${this.controller.batchSize}`
      );
    } else {
      // Critical — minimum batch + backoff
      this.controller.batchSize = 5;
      this.controller.intervalMs = Math.min(
        this.controller.intervalMs * 1.5,
        300_000
      );
      console.log(
        `[adapt] Success rate ${(successRate * 100).toFixed(1)}% ` +
        `-> minimum batch, interval ${this.controller.intervalMs}ms`
      );
    }
  }

  // -- Scheduling ----------------------------------------------

  private async scheduleNext(): Promise<void> {
    const next = Date.now() + this.controller.intervalMs;
    await this.state.storage.setAlarm(next);
  }

  // -- Persistence ---------------------------------------------

  private async save(): Promise<void> {
    await this.state.storage.put("controller", this.controller);
  }
}

interface WorkItem {
  id: string;
  [key: string]: unknown;
}

interface Env {
  API_BASE: string;
  API_KEY: string;
  ENRICHMENT_API: string;
}

How It Works

                    +---------------+
                    |   alarm()     | <-- DO wakes itself
                    +-------+-------+
                            |
                    +-------v-------+
                    | fetchPending  | -- get batch of work
                    +-------+-------+
                            |
                    +-------v-------+
                    | enrichBatch   | -- parallel processing
                    +-------+-------+
                            |
                    +-------v-------+
                    | recordResults | -- rolling window metrics
                    +-------+-------+
                            |
                    +-------v-------+
                    |   adapt()     | -- adjust batch size
                    +-------+-------+
                            |
                    +-------v-------+
                    | scheduleNext  | -- set next alarm
                    +---------------+

Key Insight

The DO learns from its own performance. After every batch, it observes the success rate and adjusts. If the downstream API is healthy, batches grow. If it is struggling, batches shrink. If it is failing, the controller backs off. No external monitoring needed — the controller is self-healing.

This is fundamentally different from a cron job with fixed parameters. A cron job does the same thing regardless of conditions. An Adaptive Controller responds to reality.

Adaptation Thresholds

Pattern 2: Storage Sidecar

Stateful storage companion for Cloudflare Workflows.

The Problem

Cloudflare Workflows are excellent for durable execution — steps retry, state persists, and the runtime handles failures. But they have a hard constraint: 1 MiB total state limit. If your Workflow accumulates data across steps (API responses, intermediate results, large payloads), you hit this wall fast.

You also cannot share state between Workflow instances without an external store. Two Workflows processing the same entity have no way to coordinate through Workflow state alone.

The Solution

Pair each Workflow (or each entity) with a Durable Object that acts as a storage sidecar. The Workflow orchestrates steps. The DO holds state. The Workflow reads and writes to the DO instead of accumulating step state.

// storage-sidecar.ts — Stateful companion for Workflows

export class StorageSidecar implements DurableObject {
  private state: DurableObjectState;

  constructor(state: DurableObjectState, env: Env) {
    this.state = state;
  }

  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);
    const key = url.searchParams.get("key");

    switch (request.method) {
      case "GET": {
        if (key) {
          // Get single key
          const value = await this.state.storage.get(key);
          if (value === undefined) {
            return new Response(null, { status: 404 });
          }
          return Response.json({ key, value });
        }
        // Get all state
        const all = await this.state.storage.list();
        const entries = Object.fromEntries(all);
        return Response.json(entries);
      }

      case "PUT": {
        if (!key) {
          return new Response("Missing key parameter", { status: 400 });
        }
        const value = await request.json();
        await this.state.storage.put(key, value);
        return Response.json({ key, written: true });
      }

      case "POST": {
        // Append to an array stored at `key`
        if (!key) {
          return new Response("Missing key parameter", { status: 400 });
        }
        const item = await request.json();
        const existing =
          (await this.state.storage.get<unknown[]>(key)) || [];
        existing.push(item);
        await this.state.storage.put(key, existing);
        return Response.json({ key, length: existing.length });
      }

      case "DELETE": {
        if (key) {
          await this.state.storage.delete(key);
          return Response.json({ key, deleted: true });
        }
        // Delete all
        await this.state.storage.deleteAll();
        return Response.json({ cleared: true });
      }

      default:
        return new Response("Method not allowed", { status: 405 });
    }
  }
}

// -- Using the sidecar from a Workflow -----------------------

interface WorkflowParams {
  entityId: string;
  sources: Array<{ id: string; url: string }>;
}

interface Env {
  STORAGE_SIDECAR: DurableObjectNamespace;
  PUBLISH_API: string;
}

export class ProcessingWorkflow extends WorkflowEntrypoint<Env, WorkflowParams> {
  async run(event: WorkflowEvent<WorkflowParams>, step: WorkflowStep) {
    const { entityId, sources } = event.payload;

    // Get a handle to this entity's sidecar DO
    const sidecarId = this.env.STORAGE_SIDECAR.idFromName(entityId);
    const sidecar = this.env.STORAGE_SIDECAR.get(sidecarId);

    // Step 1: Initialize sidecar state
    await step.do("init-sidecar", async () => {
      await sidecar.fetch(
        new Request("https://sidecar/?key=status", {
          method: "PUT",
          body: JSON.stringify({
            phase: "started",
            startedAt: Date.now(),
          }),
        })
      );
    });

    // Step 2: Fetch data from multiple sources
    for (const source of sources) {
      await step.do(`fetch-${source.id}`, async () => {
        const response = await fetch(source.url);
        const data = await response.json();

        // Append to sidecar instead of accumulating in step state
        await sidecar.fetch(
          new Request("https://sidecar/?key=rawData", {
            method: "POST",
            body: JSON.stringify({
              source: source.id,
              data,
              fetchedAt: Date.now(),
            }),
          })
        );

        // Return minimal data to Workflow state (stays under 1 MiB)
        return {
          source: source.id,
          status: "fetched",
          records: (data as unknown[]).length,
        };
      });
    }

    // Step 3: Process — read all data from sidecar
    const result = await step.do("process", async () => {
      const response = await sidecar.fetch(
        new Request("https://sidecar/?key=rawData")
      );
      const { value: allData } = (await response.json()) as {
        value: unknown[];
      };

      // Process the full dataset (which could be many MiB)
      const processed = transform(allData);

      // Store result in sidecar
      await sidecar.fetch(
        new Request("https://sidecar/?key=result", {
          method: "PUT",
          body: JSON.stringify(processed),
        })
      );

      return { recordsProcessed: processed.length };
    });

    // Step 4: Publish result
    await step.do("publish", async () => {
      const response = await sidecar.fetch(
        new Request("https://sidecar/?key=result")
      );
      const { value: finalResult } = (await response.json()) as {
        value: unknown;
      };

      await fetch(`${this.env.PUBLISH_API}/publish`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(finalResult),
      });

      // Clean up sidecar
      await sidecar.fetch(
        new Request("https://sidecar/", { method: "DELETE" })
      );
    });

    return { entityId, status: "completed" };
  }
}

function transform(data: unknown[]): unknown[] {
  // Your processing logic here
  return data;
}

Why Not Just Use D1 or KV?

You could — but the sidecar pattern has specific advantages:

The sidecar is ideal when state is temporary (lives for the duration of a workflow), entity-scoped (belongs to one thing), and consistency-sensitive (multiple steps must see the same state).

Key Insight

The Workflow handles orchestration (what steps to run, in what order, with what retry policy). The DO handles state (accumulating data across steps, providing a consistent view). This separation lets each primitive do what it is best at.

Typed RPC Variant

If you prefer type safety over HTTP, use Durable Object RPC (available since 2024):

export class StorageSidecarRPC extends DurableObject {
  async get(key: string): Promise<unknown> {
    return this.ctx.storage.get(key);
  }

  async set(key: string, value: unknown): Promise<void> {
    await this.ctx.storage.put(key, value);
  }

  async append(key: string, item: unknown): Promise<number> {
    const existing =
      (await this.ctx.storage.get<unknown[]>(key)) || [];
    existing.push(item);
    await this.ctx.storage.put(key, existing);
    return existing.length;
  }

  async clear(): Promise<void> {
    await this.ctx.storage.deleteAll();
  }
}

// Usage from a Worker or Workflow — fully typed, no HTTP serialization:
//
// const sidecar = env.STORAGE_SIDECAR.get(id);
// await sidecar.set("key", { foo: "bar" });
// const value = await sidecar.get("key");

Pattern 3: Budget Governor

A resource allocation controller that distributes budget across competing processors.

The Problem

You have multiple processing tasks that share a limited budget — API calls with rate limits, dollars allocated to LLM inference, time windows for batch operations. Each processor type has different costs, different priorities, and different performance characteristics. You need something to allocate resources intelligently.

The Solution

A Durable Object that acts as a budget governor: it receives a total budget per cycle, allocates it across processor types by weight, routes to appropriate model tiers, and tracks spend per processor.

// budget-governor.ts — Resource allocation controller

interface ProcessorConfig {
  id: string;
  name: string;
  weight: number;        // Budget weight (0-1, all weights sum to 1)
  phase: number;         // Execution order (lower = earlier)
  modelTier: "premium" | "standard" | "economy";
  enabled: boolean;
}

interface BudgetAllocation {
  allocated: number;
  spent: number;
  items: number;
  errors: number;
  avgLatencyMs: number;
}

interface BudgetCycle {
  cycleId: string;
  totalBudget: number;   // Total budget units for this cycle
  startedAt: number;
  allocations: Record<string, BudgetAllocation>;
}

interface GovernorState {
  processors: ProcessorConfig[];
  currentCycle: BudgetCycle | null;
  cycleHistory: Array<{
    cycleId: string;
    totalBudget: number;
    totalSpent: number;
    completedAt: number;
  }>;
  modelRouting: Record<
    string,
    {
      model: string;
      costPerCall: number;
      maxConcurrency: number;
    }
  >;
}

export class BudgetGovernor implements DurableObject {
  private state: DurableObjectState;
  private env: Env;
  private governor: GovernorState;

  constructor(state: DurableObjectState, env: Env) {
    this.state = state;
    this.env = env;
    this.governor = {
      processors: [],
      currentCycle: null,
      cycleHistory: [],
      modelRouting: {
        premium: {
          model: "gpt-4o",
          costPerCall: 0.03,
          maxConcurrency: 5,
        },
        standard: {
          model: "gpt-4o-mini",
          costPerCall: 0.005,
          maxConcurrency: 20,
        },
        economy: {
          model: "gemini-2.0-flash",
          costPerCall: 0.001,
          maxConcurrency: 50,
        },
      },
    };

    this.state.blockConcurrencyWhile(async () => {
      const stored =
        await this.state.storage.get<GovernorState>("governor");
      if (stored) this.governor = stored;
    });
  }

  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);

    switch (url.pathname) {
      case "/configure":
        return this.configure(await request.json());
      case "/start-cycle":
        return this.startCycle(await request.json());
      case "/execute":
        return this.executeCycle();
      case "/report-usage":
        return this.reportUsage(await request.json());
      case "/status":
        return Response.json(this.governor);
      default:
        return new Response("Not found", { status: 404 });
    }
  }

  // -- Configuration -------------------------------------------

  private async configure(
    config: { processors: ProcessorConfig[] }
  ): Promise<Response> {
    // Validate weights sum to 1
    const totalWeight = config.processors
      .filter((p) => p.enabled)
      .reduce((sum, p) => sum + p.weight, 0);

    if (Math.abs(totalWeight - 1.0) > 0.01) {
      return Response.json(
        {
          error: `Weights sum to ${totalWeight}, must equal 1.0`,
        },
        { status: 400 }
      );
    }

    this.governor.processors = config.processors;
    await this.save();
    return Response.json({
      configured: true,
      processors: config.processors.length,
    });
  }

  // -- Cycle Management ----------------------------------------

  private async startCycle(
    params: { totalBudget: number }
  ): Promise<Response> {
    const cycleId = `cycle_${Date.now()}`;

    // Allocate budget by weight
    const allocations: BudgetCycle["allocations"] = {};
    for (const proc of this.governor.processors.filter(
      (p) => p.enabled
    )) {
      allocations[proc.id] = {
        allocated: params.totalBudget * proc.weight,
        spent: 0,
        items: 0,
        errors: 0,
        avgLatencyMs: 0,
      };
    }

    this.governor.currentCycle = {
      cycleId,
      totalBudget: params.totalBudget,
      startedAt: Date.now(),
      allocations,
    };

    await this.save();

    return Response.json({
      cycleId,
      allocations: Object.entries(allocations).map(
        ([id, a]) => ({
          processor: id,
          allocated: a.allocated,
        })
      ),
    });
  }

  // -- Phase-Ordered Execution ---------------------------------

  private async executeCycle(): Promise<Response> {
    const cycle = this.governor.currentCycle;
    if (!cycle) {
      return Response.json(
        { error: "No active cycle" },
        { status: 400 }
      );
    }

    // Group processors by phase, execute in order
    const phases = new Map<number, ProcessorConfig[]>();
    for (const proc of this.governor.processors.filter(
      (p) => p.enabled
    )) {
      const group = phases.get(proc.phase) || [];
      group.push(proc);
      phases.set(proc.phase, group);
    }

    const results: Record<string, unknown> = {};

    // Execute phases in order (processors within a phase run in parallel)
    const sortedPhases = [...phases.entries()].sort(
      ([a], [b]) => a - b
    );

    for (const [phase, processors] of sortedPhases) {
      const phaseResults = await Promise.all(
        processors.map(async (proc) => {
          const allocation = cycle.allocations[proc.id];
          if (
            !allocation ||
            allocation.spent >= allocation.allocated
          ) {
            return {
              processor: proc.id,
              skipped: true,
              reason: "budget exhausted",
            };
          }

          const routing =
            this.governor.modelRouting[proc.modelTier];
          const remainingBudget =
            allocation.allocated - allocation.spent;
          const maxItems = Math.floor(
            remainingBudget / routing.costPerCall
          );

          // Dispatch to data plane Worker
          const response = await fetch(
            `${this.env.PROCESSOR_API}/process`,
            {
              method: "POST",
              headers: {
                "Content-Type": "application/json",
              },
              body: JSON.stringify({
                processorId: proc.id,
                model: routing.model,
                maxItems: Math.min(
                  maxItems,
                  routing.maxConcurrency
                ),
                cycleId: cycle.cycleId,
              }),
            }
          );

          return {
            processor: proc.id,
            phase,
            ...((await response.json()) as object),
          };
        })
      );

      for (const result of phaseResults) {
        results[result.processor] = result;
      }
    }

    // Archive cycle
    this.governor.cycleHistory.push({
      cycleId: cycle.cycleId,
      totalBudget: cycle.totalBudget,
      totalSpent: Object.values(cycle.allocations).reduce(
        (sum, a) => sum + a.spent,
        0
      ),
      completedAt: Date.now(),
    });

    // Keep last 50 cycles
    if (this.governor.cycleHistory.length > 50) {
      this.governor.cycleHistory =
        this.governor.cycleHistory.slice(-50);
    }

    this.governor.currentCycle = null;
    await this.save();

    return Response.json({ cycleId: cycle.cycleId, results });
  }

  // -- Usage Reporting -----------------------------------------

  private async reportUsage(report: {
    processorId: string;
    cost: number;
    items: number;
    errors: number;
    avgLatencyMs: number;
  }): Promise<Response> {
    const cycle = this.governor.currentCycle;
    if (!cycle) {
      return Response.json(
        { error: "No active cycle" },
        { status: 400 }
      );
    }

    const allocation = cycle.allocations[report.processorId];
    if (!allocation) {
      return Response.json(
        { error: "Unknown processor" },
        { status: 400 }
      );
    }

    allocation.spent += report.cost;
    allocation.items += report.items;
    allocation.errors += report.errors;
    // Running average
    const prevItems = allocation.items - report.items;
    allocation.avgLatencyMs =
      (allocation.avgLatencyMs * prevItems +
        report.avgLatencyMs * report.items) /
      allocation.items;

    const overBudget = allocation.spent > allocation.allocated;

    await this.save();

    return Response.json({
      processorId: report.processorId,
      remaining: allocation.allocated - allocation.spent,
      overBudget,
    });
  }

  private async save(): Promise<void> {
    await this.state.storage.put("governor", this.governor);
  }
}

interface Env {
  PROCESSOR_API: string;
}

Budget Allocation Flow

+------------------------------------------------------------------+
|                     Budget Governor DO                            |
|                                                                  |
|  Total Budget: $1.00/cycle                                       |
|                                                                  |
|  +---------------+  +---------------+  +---------------+         |
|  | Keyword       |  | Competitor    |  | Backlink      |         |
|  | Enrichment    |  | Analysis      |  | Discovery     |         |
|  |               |  |               |  |               |         |
|  | Weight: 0.5   |  | Weight: 0.3   |  | Weight: 0.2   |         |
|  | Phase: 1      |  | Phase: 1      |  | Phase: 2      |         |
|  | Tier: std     |  | Tier: prem    |  | Tier: econ    |         |
|  | Budget: $0.50 |  | Budget: $0.30 |  | Budget: $0.20 |         |
|  +-------+-------+  +-------+-------+  +-------+-------+         |
|          |                  |                   |                 |
+----------+------------------+-------------------+-----------------+
           |                  |                   |
           v                  v                   v
    +-----------+      +-----------+       +-----------+
    |gpt-4o-mini|      |   gpt-4o  |       | gemini    |
    | 100 items |      |  10 items |       | 200 items |
    |$0.005/call|      |$0.03/call |       |$0.001/call|
    +-----------+      +-----------+       +-----------+

Key Insight

The DO is a resource allocator, not a task executor. It never calls an LLM or processes a record directly. It decides how much each processor gets, which model tier to use, and in what order to run them. The actual work happens in stateless Workers that report back their usage.

This means you can change allocation strategies (more budget to keyword enrichment, less to backlinks) without touching any processing code. The governor’s configuration is the single source of truth for resource distribution.

Pattern 4: Event Reactor

An autonomous agent that responds to domain events and emits commands.

This pattern uses the Cloudflare Agents SDK to build a DO that acts as a domain-level decision maker. It receives events (research completed, content published, metric threshold crossed), maintains decision context, and emits commands to other services.

The Problem

Distributed systems generate events. Something has to watch those events and decide what to do next. Traditional approaches:

• Event-driven microservice: Stateless, so it re-fetches context on every event. Expensive and slow.
• State machine in a database: Works, but the logic is spread across application code and database queries. Hard to reason about.
• Workflow engine: Good for linear flows, but awkward for reactive, event-driven logic.

The Solution

A Durable Object (via the Agents SDK) that maintains a persistent view of the world and reacts to events by emitting commands.

// brand-agent.ts — Event-driven decision maker using Agents SDK

import { Agent } from "agents";

interface BrandState {
  // Identity
  brandId: string;
  brandName: string;

  // Decision context — what we know about the world
  observations: {
    lastResearchAt: number | null;
    lastPublishAt: number | null;
    contentCount: number;
    avgEngagement: number;
    topKeywords: string[];
    competitorMoves: Array<{
      competitor: string;
      action: string;
      observedAt: number;
    }>;
  };

  // Pending decisions
  pending: Array<{
    id: string;
    type: string;
    payload: unknown;
    createdAt: number;
  }>;

  // Decision log — why we did what we did
  decisions: Array<{
    id: string;
    type: string;
    reason: string;
    result: "pending" | "success" | "failed";
    timestamp: number;
  }>;

  // Cycle tracking
  lastCycleAt: number;
  cycleIntervalMs: number;
}

const DEFAULT_BRAND_STATE: BrandState = {
  brandId: "",
  brandName: "",
  observations: {
    lastResearchAt: null,
    lastPublishAt: null,
    contentCount: 0,
    avgEngagement: 0,
    topKeywords: [],
    competitorMoves: [],
  },
  pending: [],
  decisions: [],
  lastCycleAt: 0,
  cycleIntervalMs: 3600_000, // 1 hour
};

interface DomainEvent {
  type: string;
  payload: unknown;
  timestamp: number;
}

interface Command {
  type: string;
  payload: unknown;
}

interface Env {
  COMMAND_QUEUE: Queue;
}

export class BrandAgent extends Agent<Env, BrandState> {
  // -- Initialization ------------------------------------------

  initialState: BrandState = DEFAULT_BRAND_STATE;

  async onStart(): Promise<void> {
    // Schedule periodic decision cycle
    this.schedule("decision-cycle", "*/60 * * * *"); // every hour
  }

  // -- Event Handlers ------------------------------------------

  async onRequest(request: Request): Promise<Response> {
    const url = new URL(request.url);

    switch (url.pathname) {
      case "/event":
        return this.handleEvent(await request.json());
      case "/state":
        return Response.json(this.state);
      case "/decisions":
        return Response.json(this.state.decisions.slice(-20));
      default:
        return new Response("Not found", { status: 404 });
    }
  }

  private async handleEvent(
    event: DomainEvent
  ): Promise<Response> {
    console.log(`[${this.state.brandId}] Event: ${event.type}`);

    switch (event.type) {
      case "research.completed":
        return this.onResearchCompleted(event);
      case "content.published":
        return this.onContentPublished(event);
      case "engagement.report":
        return this.onEngagementReport(event);
      case "competitor.detected":
        return this.onCompetitorDetected(event);
      default:
        return Response.json({
          accepted: true,
          action: "ignored",
        });
    }
  }

  // -- Event: Research Completed -------------------------------

  private async onResearchCompleted(
    event: DomainEvent
  ): Promise<Response> {
    const { keywords, opportunities } = event.payload as {
      keywords: string[];
      gaps: string[];
      opportunities: string[];
    };

    // Update observations
    this.setState({
      ...this.state,
      observations: {
        ...this.state.observations,
        lastResearchAt: Date.now(),
        topKeywords: keywords.slice(0, 20),
      },
    });

    // Decision: should we create content for these opportunities?
    const commands: Command[] = [];

    for (const opportunity of opportunities) {
      if (this.shouldCreateContent(opportunity)) {
        const command: Command = {
          type: "content.create",
          payload: {
            brandId: this.state.brandId,
            keyword: opportunity,
            priority: this.calculatePriority(opportunity),
          },
        };
        commands.push(command);

        this.logDecision(
          "create-content",
          `Research found opportunity "${opportunity}" — creating content`,
          "pending"
        );
      }
    }

    // Emit commands to queue
    if (commands.length > 0) {
      await this.emitCommands(commands);
    }

    return Response.json({
      accepted: true,
      commands: commands.length,
    });
  }

  // -- Event: Content Published --------------------------------

  private async onContentPublished(
    event: DomainEvent
  ): Promise<Response> {
    const { contentId, keyword } = event.payload as {
      contentId: string;
      keyword: string;
    };

    this.setState({
      ...this.state,
      observations: {
        ...this.state.observations,
        lastPublishAt: Date.now(),
        contentCount: this.state.observations.contentCount + 1,
      },
    });

    // Decision: should we promote this content on social?
    if (this.shouldPromote(keyword)) {
      await this.emitCommands([
        {
          type: "social.schedule",
          payload: {
            brandId: this.state.brandId,
            contentId,
            platforms: ["twitter", "linkedin"],
            timing: "optimal",
          },
        },
      ]);

      this.logDecision(
        "promote-content",
        `Content "${keyword}" published — scheduling social promotion`,
        "pending"
      );
    }

    return Response.json({ accepted: true });
  }

  // -- Event: Engagement Report --------------------------------

  private async onEngagementReport(
    event: DomainEvent
  ): Promise<Response> {
    const { avgEngagement, underPerforming } = event.payload as {
      avgEngagement: number;
      topPerforming: string[];
      underPerforming: string[];
    };

    this.setState({
      ...this.state,
      observations: {
        ...this.state.observations,
        avgEngagement,
      },
    });

    // Decision: adjust strategy based on engagement
    if (avgEngagement < 0.02) {
      // Low engagement — trigger research to find better topics
      await this.emitCommands([
        {
          type: "research.request",
          payload: {
            brandId: this.state.brandId,
            focus: "engagement-optimization",
            context: { underPerforming },
          },
        },
      ]);

      this.logDecision(
        "engagement-pivot",
        `Engagement at ${(avgEngagement * 100).toFixed(1)}% — triggering research pivot`,
        "pending"
      );
    }

    return Response.json({ accepted: true });
  }

  // -- Event: Competitor Detected ------------------------------

  private async onCompetitorDetected(
    event: DomainEvent
  ): Promise<Response> {
    const { competitor, action, details } = event.payload as {
      competitor: string;
      action: string;
      details: unknown;
    };

    // Record observation
    const moves = [
      ...this.state.observations.competitorMoves,
      { competitor, action, observedAt: Date.now() },
    ].slice(-50); // Keep last 50

    this.setState({
      ...this.state,
      observations: {
        ...this.state.observations,
        competitorMoves: moves,
      },
    });

    // Decision: react to competitor move?
    if (
      action === "new-content" &&
      this.isHighPriorityCompetitor(competitor)
    ) {
      await this.emitCommands([
        {
          type: "research.request",
          payload: {
            brandId: this.state.brandId,
            focus: "competitive-response",
            context: { competitor, action, details },
          },
        },
      ]);

      this.logDecision(
        "competitive-response",
        `Competitor "${competitor}" published new content — investigating`,
        "pending"
      );
    }

    return Response.json({ accepted: true });
  }

  // -- Scheduled: Decision Cycle -------------------------------

  async onSchedule(scheduleName: string): Promise<void> {
    if (scheduleName !== "decision-cycle") return;

    const now = Date.now();
    const hoursSinceResearch =
      this.state.observations.lastResearchAt
        ? (now - this.state.observations.lastResearchAt) / 3600_000
        : Infinity;
    const hoursSincePublish =
      this.state.observations.lastPublishAt
        ? (now - this.state.observations.lastPublishAt) / 3600_000
        : Infinity;

    // If no research in 24 hours, request it
    if (hoursSinceResearch > 24) {
      await this.emitCommands([
        {
          type: "research.request",
          payload: {
            brandId: this.state.brandId,
            focus: "routine-discovery",
          },
        },
      ]);
      this.logDecision(
        "routine-research",
        `No research in ${hoursSinceResearch.toFixed(0)}h — requesting routine discovery`,
        "pending"
      );
    }

    // If no publishing in 48 hours, something is stuck
    if (hoursSincePublish > 48) {
      this.logDecision(
        "pipeline-stall",
        `No publishing in ${hoursSincePublish.toFixed(0)}h — pipeline may be stalled`,
        "pending"
      );
    }

    this.setState({
      ...this.state,
      lastCycleAt: now,
    });
  }

  // -- Decision Helpers ----------------------------------------

  private shouldCreateContent(_opportunity: string): boolean {
    // Simple heuristic — in production, this could consult
    // historical performance, budget, content calendar, etc.
    const recentContent = this.state.decisions
      .filter((d) => d.type === "create-content")
      .filter((d) => Date.now() - d.timestamp < 86400_000);
    return recentContent.length < 5; // Max 5 pieces per day
  }

  private shouldPromote(keyword: string): boolean {
    return this.state.observations.topKeywords.includes(keyword);
  }

  private calculatePriority(opportunity: string): number {
    const isTopKeyword =
      this.state.observations.topKeywords.includes(opportunity);
    return isTopKeyword ? 1 : 2;
  }

  private isHighPriorityCompetitor(competitor: string): boolean {
    const recentMoves = this.state.observations.competitorMoves
      .filter((m) => m.competitor === competitor)
      .filter(
        (m) => Date.now() - m.observedAt < 7 * 86400_000
      );
    return recentMoves.length >= 3; // Active if 3+ moves in a week
  }

  // -- Command Emission ----------------------------------------

  private async emitCommands(commands: Command[]): Promise<void> {
    for (const command of commands) {
      await this.env.COMMAND_QUEUE.send({
        ...command,
        brandId: this.state.brandId,
        emittedAt: Date.now(),
      });
    }
  }

  private logDecision(
    type: string,
    reason: string,
    result: "pending" | "success" | "failed"
  ): void {
    const decisions = [
      ...this.state.decisions,
      {
        id: `dec_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
        type,
        reason,
        result,
        timestamp: Date.now(),
      },
    ].slice(-100); // Keep last 100

    this.setState({
      ...this.state,
      decisions,
    });
  }
}

Event Flow

External Events              Brand Agent DO             Command Queue
                             +-----------------+
research.completed ------->  | Update state    |
                             | Evaluate opps   |-------> content.create
                             | Log decision    |-------> content.create
                             +-----------------+

content.published  ------->  +-----------------+
                             | Update counters |
                             | Check promotion |-------> social.schedule
                             | Log decision    |
                             +-----------------+

engagement.report  ------->  +-----------------+
                             | Update metrics  |
                             | Check thresholds|-------> research.request
                             | Log decision    |
                             +-----------------+

          alarm()  ------->  +-----------------+
   (decision-cycle)          | Check staleness |
                             | Detect stalls   |-------> research.request
                             | Log decisions   |
                             +-----------------+

Key Insight

The DO makes decisions; queues do the work. The BrandAgent never calls an API, never generates content, never posts to social media. It observes events, updates its internal model of the world, and emits commands. This makes the decision logic easy to test (feed events, check commands) and easy to reason about (all decisions are in one file with full state context).

The decision log is particularly powerful. Every command the agent emits has a recorded reason. When you debug why something happened, you read the decision log — not distributed traces across five services.

Layer Guide: Raw DO to Server to Agent

Durable Objects can be used at three levels of abstraction. Each layer adds capabilities and opinions.

Layer 0: Raw Durable Object

The fundamental primitive. You implement fetch() and optionally alarm(). You manage storage directly.

export class RawCounter implements DurableObject {
  private state: DurableObjectState;

  constructor(state: DurableObjectState, env: Env) {
    this.state = state;
  }

  async fetch(request: Request): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === "/increment") {
      const current =
        (await this.state.storage.get<number>("count")) || 0;
      const next = current + 1;
      await this.state.storage.put("count", next);
      return Response.json({ count: next });
    }

    if (url.pathname === "/get") {
      const count =
        (await this.state.storage.get<number>("count")) || 0;
      return Response.json({ count });
    }

    return new Response("Not found", { status: 404 });
  }
}

Use when:

• Simple state + simple logic
• You need maximum control
• No framework dependencies desired
• Learning DOs for the first time

Layer 1: Server Framework (Hono on DO)

Add a router framework for cleaner HTTP handling. Hono works well because it is lightweight and designed for edge runtimes.

import { Hono } from "hono";

export class ServerCounter implements DurableObject {
  private state: DurableObjectState;
  private app: Hono;

  constructor(state: DurableObjectState, env: Env) {
    this.state = state;

    this.app = new Hono();

    this.app.post("/increment", async (c) => {
      const current =
        (await this.state.storage.get<number>("count")) || 0;
      const next = current + 1;
      await this.state.storage.put("count", next);
      return c.json({ count: next });
    });

    this.app.get("/count", async (c) => {
      const count =
        (await this.state.storage.get<number>("count")) || 0;
      return c.json({ count });
    });

    this.app.post("/reset", async (c) => {
      await this.state.storage.put("count", 0);
      return c.json({ count: 0 });
    });
  }

  fetch(request: Request): Promise<Response> {
    return this.app.fetch(request);
  }
}