Durable Object State

DurableObjectState インターフェイスは、Durable Object class のインスタンスプロパティとして使えます。このインターフェイスは、Durable Object の状態を変更するメソッドをまとめたものです。たとえば、Durable Object にどの WebSocket が接続されているか、ランタイムが同時 Durable Object リクエストをどう扱うか、などです。

DurableObjectState インターフェイスは、Storage API とは異なります。永続的なアプリケーションデータを操作するトップレベルのメソッドはありません。それらのメソッドは DurableObjectStorage インターフェイスにまとめられており、DurableObjectState::storage からアクセスします。

import { DurableObject } from "cloudflare:workers";

// Durable Object
export class MyDurableObject extends DurableObject {
  // DurableObjectState is accessible via the ctx instance property
	constructor(ctx, env) {
		super(ctx, env);
	}
  ...
}

import { DurableObject } from "cloudflare:workers";

export interface Env {
  MY_DURABLE_OBJECT: DurableObjectNamespace<MyDurableObject>;
}

// Durable Object
export class MyDurableObject extends DurableObject {
  // DurableObjectState is accessible via the ctx instance property
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
	}
  ...
}

from workers import DurableObject

# Durable Object
class MyDurableObject(DurableObject):
  # DurableObjectState is accessible via the ctx instance property
  def __init__(self, ctx, env):
    super().__init__(ctx, env)
  # ...

Worker 自身のトップレベル exports へのループバックバインディングを含みます。意味は ExecutionContext の ctx.exports とまったく同じです。

waitUntil は、Workers Runtime APIs との API 互換性のために DurableObjectState で使えます。

• 任意の型の必須の Promise。

• なし。

blockConcurrencyWhile は、非同期コールバックを実行しているあいだ、ほかのイベントが Durable Object に届かないようにします。このメソッドは順序を保証し、同時リクエストを防ぎます。コールバック自身が明示的に開始したイベント以外は、すべてブロックされます。コールバックが完了すると、ほかのイベントが配信されます。

• blockConcurrencyWhile は、Durable Object class のコンストラクター内で、リクエストが届く前に初期化を完了させるために使うことがよくあります。
• ほかの使い方として、Durable Object の現在の状態に基づいて async 操作を実行し、イベントループを譲っているあいだにその状態が変わらないよう blockConcurrencyWhile で保護します。
• コールバックが例外を投げると、オブジェクトは終了してリセットされます。予期しない失敗で、初期化されていない状態のまま残らないようにするためです。
• この動きを避けるには、コールバック本体を try...catch で囲み、例外を投げないようにします。

デッドロックを緩和するため、コールバック実行には 30 秒のタイムアウトがあります。このタイムアウトを超えると、Durable Object はリセットされます。全体のリクエストスループットを上げるため、コールバックではできるだけ少ない処理にとどめるのがおすすめです。

// Durable Object
export class MyDurableObject extends DurableObject {
	initialized = false;

	constructor(ctx, env) {
		super(ctx, env);

		// blockConcurrencyWhile will ensure that initialized will always be true
		this.ctx.blockConcurrencyWhile(async () => {
			this.initialized = true;
		});
	}
  ...
}

# Durable Object
class MyDurableObject(DurableObject):
	def __init__(self, ctx, env):
		super().__init__(ctx, env)
		self.initialized = False

		# blockConcurrencyWhile will ensure that initialized will always be true
		async def set_initialized():
			self.initialized = True
		self.ctx.blockConcurrencyWhile(set_initialized)
	# ...

• Promise<T> を返す必須のコールバック。

• コールバックが返す Promise<T>。

acceptWebSocket は WebSocket Hibernation API の一部です。この API を使うと、WebSocket 接続を維持したまま Durable Object をメモリから外し、コストを抑えられます。

acceptWebSocket は、Durable Object に接続された WebSocket の集合へ WebSocket を追加します。呼び出したあと、着信メッセージは Durable Object の webSocketMessage ハンドラーで配信され、切断時には webSocketClose が呼ばれます。acceptWebSocket を呼ぶと WebSocket は受け入れられ、send と close メソッドを使えます。

WebSocket Hibernation API は、標準の WebSockets API の代わりになります。そのため、ws.accept を別途呼んではいけません。ws.addEventListener もイベントを受け取りません。イベントは Durable Object へ配信されます。

WebSocket Hibernation API では、Durable Object あたり最大 32,768 の WebSocket 接続を許可します。ただし、ワークロードの CPU とメモリ使用量によって、実際に同時接続できる数はさらに制限されることがあります。

• 名前が ws の必須の WebSocket。
• 関連付けるタグの任意の Array<string>。タグは DurableObjectState::getWebSockets で WebSocket を取得するときに使えます。各タグは最大 256 文字で、1 つの WebSocket に関連付けられるタグは最大 10 個です。

• なし。

getWebSockets は WebSocket Hibernation API の一部です。この API を使うと、WebSocket 接続を維持したまま Durable Object をメモリから外し、コストを抑えられます。

getWebSockets は、Durable Object に接続された WebSocket の集合である Array<WebSocket> を返します。任意の tag 引数を使うと、DurableObjectState::acceptWebSocket 呼び出し時に付けたタグで一覧を絞り込めます。

• 任意の string 型のタグ。

• Array<WebSocket>。

setWebSocketAutoResponse は WebSocket Hibernation API の一部です。この API を使うと、WebSocket 接続を維持したまま Durable Object をメモリから外し、コストを抑えられます。

setWebSocketAutoResponse は、Durable Object に接続されたすべての WebSocket に対して、指定したリクエストへの自動応答（auto-response）を設定します。指定したリクエストに一致するリクエストを受信すると、ハイバネーション中の WebSocket を起こさず、課金対象の duration を発生させずに auto-response を返します。

setWebSocketAutoResponse は、静的な ping/pong メッセージ用にサーバーを用意する一般的な代替手段です。ハイバネーション中の WebSocket を起こさずに処理できるためです。

• 任意の WebSocketRequestResponsePair(request string, response string)。DurableObjectState::acceptWebSocket 経由で受け入れた WebSocket が、指定したリクエストを受信したときに指定した応答を自動で返すようにします。request と response はそれぞれ最大 2,048 文字です。パラメーターを省略すると、以前設定した auto-response 設定は削除されます。DurableObjectState::getWebSocketAutoResponseTimestamp は、auto-response を最後に送ったタイムスタンプを引き続き反映します。

• なし。

getWebSocketAutoResponse は、DurableObjectState::setWebSocketAutoResponse で最後に設定した WebSocketRequestResponsePair オブジェクトを返します。auto-response が設定されていない場合は null です。

• なし。

• WebSocketRequestResponsePair、または null。

getWebSocketAutoResponseTimestamp は WebSocket Hibernation API の一部です。この API を使うと、WebSocket 接続を維持したまま Durable Object をメモリから外し、コストを抑えられます。

getWebSocketAutoResponseTimestamp は、指定した WebSocket が auto-response を送った直近の Date を取得します。その WebSocket が auto-response を送ったことがない場合は null です。

• 必須の WebSocket。

• Date、または null。

setHibernatableWebSocketEventTimeout は WebSocket Hibernation API の一部です。この API を使うと、WebSocket 接続を維持したまま Durable Object をメモリから外し、コストを抑えられます。

setHibernatableWebSocketEventTimeout は、WebSocket イベントが実行できる最大時間をミリ秒で設定します。

パラメーターを指定しないか、0 を指定し、以前タイムアウトが設定されていた場合は、タイムアウトは解除されます。タイムアウトの最大値は 604,800,000 ms（7 日）です。

• 任意の number。

• なし。

getHibernatableWebSocketEventTimeout は WebSocket Hibernation API の一部です。この API を使うと、WebSocket 接続を維持したまま Durable Object をメモリから外し、コストを抑えられます。

getHibernatableWebSocketEventTimeout は、DurableObjectState::setHibernatableWebSocketEventTimeout で現在設定されている、ハイバネーション可能な WebSocket イベントのタイムアウトを取得します。

• なし。

• number。タイムアウトが設定されていない場合は null。

getTags は WebSocket Hibernation API の一部です。この API を使うと、WebSocket 接続を維持したまま Durable Object をメモリから外し、コストを抑えられます。

getTags は、指定した WebSocket に関連付けられたタグを返します。その WebSocket が DurableObjectState::acceptWebSocket で Durable Object に関連付けられていない場合、このメソッドは例外を投げます。

• 必須の WebSocket。

• タグの Array<string>。

abort を呼ぶと、Durable Object はすぐにリセットされます。ランタイムは、abort に渡したメッセージ付きの JavaScript Error をログに残します。アプリケーションコードはこのエラーを捕捉できません。

既定では、abort で中断されたアラームは、Durable Object のリセット後に再試行されます。Durable Object は、別のリクエストと同時にアラームを実行でき、そのリクエストはアラーム実行中に abort を呼べます。

既定の再試行により、無関係なリクエストがアラームを恒久的にキャンセルすることを防ぎます。中断されたアラームの再試行を防ぎたい abort 呼び出しでは、アラームハンドラーの外も含めて { retryAlarm: false } を渡します。

// Durable Object
export class MyDurableObject extends DurableObject {
	constructor(ctx: DurableObjectState, env: Env) {
		super(ctx, env);
	}

  async sayHello() {
    // Error: Hello, World! will be logged
    this.ctx.abort("Hello, World!");
  }

  async alarm() {
    // Reset this instance without retrying the alarm
    this.ctx.abort("Alarm complete", { retryAlarm: false });
  }
}

# Durable Object
class MyDurableObject(DurableObject):
	def __init__(self, ctx, env):
		super().__init__(ctx, env)

	async def say_hello(self):
		# Error: Hello, World! will be logged
		self.ctx.abort("Hello, World!")

• ログに残すエラーメッセージを含む任意の string。
• 任意の DurableObjectAbortOptions オブジェクト:
  • retryAlarm boolean: この abort で中断されたアラームを再試行するかを制御します。既定値は true です。

• なし。

id は、Durable Object の DurableObjectId に対応する、読み取り専用の DurableObjectId 型プロパティです。

storage は、Storage API をまとめた、読み取り専用の DurableObjectStorage 型プロパティです。

• Durable Objects: Easy, Fast, Correct - Choose Three ↗.