アラーム

背景

Durable Objectsのアラームを使用すると、Durable Objectを将来の特定の時間に起動するようにスケジュールできます。アラームのスケジュールされた時間が来ると、alarm()ハンドラーメソッドが呼び出されます。アラームはTransactional Storage APIを使用して変更され、アラーム操作は他のストレージ操作と同じルールに従います。

特に：

各Durable Objectインスタンスは、setAlarm()を呼び出すことで、一度に1つのアラームをスケジュールできます。
アラームは少なくとも1回の実行が保証されており、alarm()ハンドラーが例外をスローした場合は自動的に再試行されます。
再試行は、最初の失敗から2秒の遅延で始まる指数バックオフを使用して行われ、最大6回の再試行が許可されます。

アラームは、Durable Objectsの上にキューやバッチ処理などの分散プリミティブを構築するために使用できます。また、アラームは、Durable Objectを生かすために受信リクエストに依存せずに、Durable Object内の操作が完了することを保証するメカニズムを提供します。完全な例については、アラームAPIの使用を参照してください。

トランザクショナルストレージメソッド

getAlarm

getAlarm() : number | null
- アラームが設定されている場合、UNIXエポックから経過したミリ秒数で現在設定されているアラームの時間を返します。そうでない場合はnullを返します。

setAlarm

setAlarm(scheduledTimeMsnumber) : void
- アラームが実行される時間をUNIXエポックから経過したミリ秒数で設定します。

deleteAlarm

deleteAlarm() : void
- 現在設定されているアラームがある場合、アラームを解除します。
- alarm()ハンドラー内でdeleteAlarm()を呼び出すと、最善の努力に基づいて再試行を防ぐ可能性がありますが、保証はされません。

ハンドラーメソッド

alarm

alarm() : void
- スケジュールされたアラームの時間に達したときにシステムによって呼び出されます。
- alarm()ハンドラーは少なくとも1回の実行が保証されており、失敗した場合は指数バックオフを使用して再試行されます。再試行は、最大6回の遅延で2秒から始まります。メソッドが未捕捉の例外で失敗した場合、再試行が行われます。
- このメソッドはasyncにすることができます。

例

この例では、setAlarm(timestamp)メソッドを使用してアラームを設定し、Durable Object内でalarm()ハンドラーを使用してアラームを処理する方法を示します。

アラームが発火するたびにalarm()ハンドラーが呼び出されます。
予期しないエラーでDurable Objectが終了した場合、alarm()ハンドラーは別のマシンで再インスタンス化されます。
短い遅延の後、alarm()ハンドラーは別のマシンで最初から実行されます。

export default {
  async fetch(request, env) {
    let id = env.ALARM_EXAMPLE.idFromName("foo");
    return await env.ALARM_EXAMPLE.get(id).fetch(request);
  },
};

const SECONDS = 1000;

export class AlarmExample {
  constructor(ctx, env) {
    this.ctx = ctx;
    this.storage = ctx.storage;
  }
  async fetch(request) {
    // 現在アラームが設定されていない場合、10秒後にアラームを設定します
    let currentAlarm = await this.storage.getAlarm();
    if (currentAlarm == null) {
      this.storage.setAlarm(Date.now() + 10 * SECONDS);
    }
  }
  async alarm() {
    // アラームが発火するたびにアラームハンドラーが呼び出されます。
    // これを使用して作業を行ったり、トランザクショナルストレージAPIから読み取ったり、HTTP呼び出しを行ったり、
    // このハンドラー内から`this.storage.setAlarm()`を使用して将来のアラームを設定できます。
  }
}