DO Alarms 定時器:讓每個物件自己醒來做事 | Cloudflare 完整教學

setAlarm(T)  ──►  [ DO 記下:下次喚醒 = T ]  ──►  (時間到 T)
                                                     │
                                                     ▼
                                            平台喚醒 DO,呼叫 alarm()
                                                     │
                              ┌──────────────────────┴───────────────────────┐
                              ▼                                               ▼
                     alarm() 正常結束                                alarm() 中途 throw
                              │                                               │
                    Alarm 被消耗(清空)                          平台指數退避,稍後重試 alarm()
                              │                                               │
              (若要週期性,需在此再 setAlarm)              (直到成功;handler 需冪等)

// src/index.ts
import { DurableObject } from "cloudflare:workers";

export interface Env {
  ORDER: DurableObjectNamespace<Order>;
}

export class Order extends DurableObject<Env> {
  private sql = this.ctx.storage.sql;

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    ctx.blockConcurrencyWhile(async () => {
      // 用一張單列表保存這張訂單的狀態(paid / expired)
      this.sql.exec(`
        CREATE TABLE IF NOT EXISTS state (
          k TEXT PRIMARY KEY,
          v TEXT NOT NULL
        );
      `);
    });
  }

  // 下單:排定 15 分鐘後檢查是否逾期(RPC 方法)
  async create(): Promise<void> {
    this.sql.exec(
      `INSERT INTO state (k, v) VALUES ('status', 'pending')
       ON CONFLICT(k) DO UPDATE SET v = 'pending';`
    );
    // 關鍵:setAlarm 接受「絕對時間戳」,所以是 now + 間隔
    await this.ctx.storage.setAlarm(Date.now() + 15 * 60_000);
  }

  // 使用者付款:清掉那個還沒觸發的 Alarm(RPC 方法)
  async pay(): Promise<void> {
    this.sql.exec(
      `UPDATE state SET v = 'paid' WHERE k = 'status';`
    );
    // 已付款就不需要逾期檢查了,取消 Alarm
    await this.ctx.storage.deleteAlarm();
  }

  // Alarm 觸發時,平台自動呼叫這個方法
  async alarm(): Promise<void> {
    const { v } = this.sql
      .exec<{ v: string }>(`SELECT v FROM state WHERE k = 'status';`)
      .one();
    // 冪等:只有仍是 pending 才標記逾期;重複觸發也安全
    if (v === "pending") {
      this.sql.exec(`UPDATE state SET v = 'expired' WHERE k = 'status';`);
      // 這裡可以再做:通知使用者、釋放庫存……
    }
  }
}

// 一個定期把記憶體中累積的指標寫入 SQLite 的 DO
export class Aggregator extends DurableObject<Env> {
  private sql = this.ctx.storage.sql;

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    ctx.blockConcurrencyWhile(async () => {
      this.sql.exec(`
        CREATE TABLE IF NOT EXISTS ticks (
          at    INTEGER PRIMARY KEY,
          note  TEXT NOT NULL
        );
      `);
    });
  }

  // 啟動週期性任務:只需排第一次,之後由 alarm() 自我延續(RPC 方法)
  async start(): Promise<void> {
    // 用 getAlarm 檢查,避免重複啟動又疊加(其實 setAlarm 會替換,但語意更清楚)
    const existing = await this.ctx.storage.getAlarm();
    if (existing === null) {
      await this.ctx.storage.setAlarm(Date.now() + 60_000);
    }
  }

  async alarm(): Promise<void> {
    // ── 做這一輪該做的事 ──
    this.sql.exec(
      `INSERT INTO ticks (at, note) VALUES (?, ?);`,
      Date.now(),
      "heartbeat"
    );

    // ── 關鍵:在尾端重排下一次,形成週期循環 ──
    // 漏掉這行 => Alarm 只會跑第一次就停
    await this.ctx.storage.setAlarm(Date.now() + 60_000);
  }

  // 停止週期性任務:清掉 Alarm,循環就中斷(RPC 方法)
  async stop(): Promise<void> {
    await this.ctx.storage.deleteAlarm();
  }
}

// 高頻計數器:用 Alarm 把大量增量「去抖動」成每秒一次批次寫入
export class HotCounter extends DurableObject<Env> {
  private sql = this.ctx.storage.sql;
  private pending = 0; // 記憶體中累積、尚未落地的增量

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    ctx.blockConcurrencyWhile(async () => {
      this.sql.exec(`
        CREATE TABLE IF NOT EXISTS counter (
          id    INTEGER PRIMARY KEY CHECK (id = 1),
          total INTEGER NOT NULL
        );
      `);
      this.sql.exec(
        `INSERT INTO counter (id, total) VALUES (1, 0)
         ON CONFLICT(id) DO NOTHING;`
      );
    });
  }

  // 高頻呼叫:只累加記憶體,並「確保有一個」1 秒後的 Alarm(RPC 方法)
  async bump(n = 1): Promise<void> {
    this.pending += n;
    // 去抖動關鍵:只有在「還沒排 Alarm」時才排,
    // 已排定的話就沿用同一個到期時間,不往後延
    if ((await this.ctx.storage.getAlarm()) === null) {
      await this.ctx.storage.setAlarm(Date.now() + 1_000);
    }
  }

  async alarm(): Promise<void> {
    const flush = this.pending;
    if (flush === 0) return;
    // 先把待寫量歸零,再落地(即使重試,pending 已清空也不會重複寫兩份)
    this.pending = 0;
    this.sql.exec(
      `UPDATE counter SET total = total + ? WHERE id = 1;`,
      flush
    );
    // 不重排:沒有新的 bump 就不需要下一次 Alarm(下次 bump 會自己排)
  }

  async total(): Promise<number> {
    // 讀取時把尚未落地的 pending 也算進去,回傳即時值
    const { total } = this.sql
      .exec<{ total: number }>(`SELECT total FROM counter WHERE id = 1;`)
      .one();
    return total + this.pending;
  }
}

export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    const stub = env.HOT_COUNTER.getByName("page-views:home");
    await stub.bump(1); // 觸發去抖動累加,Alarm 由 DO 內部自理
    return new Response("ok");
  },
} satisfies ExportedHandler<Env>;

// ❌ 錯誤:期待它每分鐘跑,但只會跑第一次
async alarm() {
  await this.doWork();
  // 少了重排,循環就斷了
}

// ✅ 正確:在尾端重排下一次,形成自我延續的週期
async alarm() {
  await this.doWork();
  await this.ctx.storage.setAlarm(Date.now() + 60_000);
}

// ❌ 錯誤:重試會重複發信
async alarm() {
  await sendEmail(this.userEmail); // 若後面 throw 被重試,信會發第二次
  this.sql.exec(`UPDATE sub SET reminded = 1;`);
}

// ✅ 正確:先檢查旗標,冪等
async alarm() {
  const { reminded } = this.sql
    .exec<{ reminded: number }>(`SELECT reminded FROM sub WHERE id = 1;`)
    .one();
  if (reminded) return;            // 已處理過,直接返回
  await sendEmail(this.userEmail);
  this.sql.exec(`UPDATE sub SET reminded = 1;`);
}

// ❌ 錯誤:被當成 1970 年的絕對時間 => 立刻觸發
await this.ctx.storage.setAlarm(60_000);

// ✅ 正確:現在時間 + 間隔
await this.ctx.storage.setAlarm(Date.now() + 60_000);