Durable Object 基底クラス

DurableObject 基底クラスは、すべての Durable Objects が継承する抽象クラスです。この基底クラスは、オプションのメソッド一式（ハンドラーメソッドと呼ばれることが多い）を提供します。ハンドラーはイベントに応答できます。例として、WebSocket Hibernation API を使うときの webSocketMessage があります。具体例として、DurableObject を拡張し、呼び出し元の Worker に "Hello, World!" を返す fetch ハンドラーを実装した Durable Object MyDurableObject を示します。

export class MyDurableObject extends DurableObject {
	constructor(ctx, env) {
		super(ctx, env);
	}

	async fetch(request) {
		return new Response("Hello, World!");
	}
}

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

    async fetch(request: Request) {
    	return new Response("Hello, World!");
    }

}

from workers import DurableObject, Response

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

	async def fetch(self, request):
		return Response("Hello, World!")

メソッド

`fetch`

fetch(request Request) : Response | Promise<Response>
- HTTP Request ↗ を受け取り、HTTP Response ↗ を返します。このメソッドにより、Durable Object は HTTP サーバーのように振る舞います。そのオブジェクトへのバインディングを持つ Worker がクライアントになります。
- このメソッドは async にできます。
- Durable Objects は、互換性日付 2024-04-03 以降、RPC 呼び出しに対応しています。アプリケーションが HTTP のリクエスト / レスポンスの流れに従わない場合は、fetch() より RPC メソッドを推奨します。

パラメーター

request Request - 受信した HTTP リクエストオブジェクト。

戻り値

Response または Promise<Response>。

例

export class MyDurableObject extends DurableObject {
	async fetch(request) {
		const url = new URL(request.url);
		if (url.pathname === "/hello") {
			return new Response("Hello, World!");
		}
		return new Response("Not found", { status: 404 });
	}
}

export class MyDurableObject extends DurableObject<Env> {
	async fetch(request: Request): Promise<Response> {
		const url = new URL(request.url);
		if (url.pathname === "/hello") {
			return new Response("Hello, World!");
		}
		return new Response("Not found", { status: 404 });
	}
}

from workers import DurableObject, Response
from urllib.parse import urlparse

class MyDurableObject(DurableObject):
    async def fetch(self, request):
        path = urlparse(request.url).path
        if path == "/hello":
            return Response("Hello, World!")
        return Response("Not found", status=404)

`alarm`

alarm(alarmInfo? AlarmInvocationInfo) : void | Promise<void>
- 予約したアラーム時刻になると、システムが呼び出します。
- alarm() ハンドラーは、少なくとも 1 回の実行が保証されます。失敗時は指数バックオフで再試行され、最初は 2 秒間隔、最大 6 回までです。メソッドが捕捉されない例外で失敗した場合に再試行されます。
- このメソッドは async にできます。
- 詳細は Alarms を参照してください。

パラメーター

alarmInfo AlarmInvocationInfo（オプション） - 再試行情報を含むオブジェクトです。
- retryCount number - このアラームイベントが再試行された回数。
- isRetry boolean - このアラームイベントが再試行なら true、それ以外は false。

戻り値

なし。

例

export class MyDurableObject extends DurableObject {
	async alarm(alarmInfo) {
		if (alarmInfo?.isRetry) {
			console.log(`Alarm retry attempt ${alarmInfo.retryCount}`);
		}
		await this.processScheduledTask();
	}
}

export class MyDurableObject extends DurableObject<Env> {
	async alarm(alarmInfo?: AlarmInvocationInfo): Promise<void> {
		if (alarmInfo?.isRetry) {
			console.log(`Alarm retry attempt ${alarmInfo.retryCount}`);
		}
		await this.processScheduledTask();
	}
}

from workers import DurableObject

class MyDurableObject(DurableObject):
    async def alarm(self, alarm_info=None):
        if alarm_info and alarm_info.isRetry:
            print(f"Alarm retry attempt {alarm_info.retryCount}")
        await self.process_scheduled_task()

`webSocketMessage`

webSocketMessage(ws WebSocket, message string | ArrayBuffer) : void | Promise<void>
- 受け入れ済みの WebSocket がメッセージを受信すると、システムが呼び出します。
- WebSocket の制御フレームでは、このメソッドは呼ばれません。受信した WebSocket protocol ping ↗ には、システムがハイバネーションを中断せずに自動応答します。
- このメソッドは async にできます。

パラメーター

ws WebSocket - メッセージを受信した WebSocket ↗。応答の送信や、シリアル化した添付データへのアクセスにこの参照を使います。
message string | ArrayBuffer - メッセージデータ。テキストメッセージは string、バイナリメッセージは ArrayBuffer として届きます。

戻り値

なし。

例

export class MyDurableObject extends DurableObject {
	async webSocketMessage(ws, message) {
		if (typeof message === "string") {
			ws.send(`Received: ${message}`);
		} else {
			ws.send(`Received ${message.byteLength} bytes`);
		}
	}
}

export class MyDurableObject extends DurableObject<Env> {
	async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer) {
		if (typeof message === "string") {
			ws.send(`Received: ${message}`);
		} else {
			ws.send(`Received ${message.byteLength} bytes`);
		}
	}
}

from workers import DurableObject

class MyDurableObject(DurableObject):
    async def webSocketMessage(self, ws, message):
        if isinstance(message, str):
            ws.send(f"Received: {message}")
        else:
            ws.send(f"Received {len(message)} bytes")

`webSocketClose`

webSocketClose(ws WebSocket, code number, reason string, wasClean boolean) : void | Promise<void>
- WebSocket 接続が閉じられると、システムが呼び出します。
- web_socket_auto_reply_to_close 互換性フラグ（互換性日付が 2026-04-07 以降ではデフォルトで有効）がある場合、ランタイムは対応する Close フレームを自動送信し、このハンドラーが呼ばれる前に readyState を CLOSED へ遷移します。ws.close() を呼ぶ必要はありません。呼んでも安全です（呼び出しは無視されます）。
- 古い互換性日付（2026-04-07 より前）では、WebSocket のクローズハンドシェイクを完了するために、このハンドラー内で必ず ws.close(code, reason) を呼び出してください。閉じに応答しないと、クライアント側で 1006 エラーになります。これは WebSocket 仕様上の異常クローズです。
- このメソッドは async にできます。

パラメーター

ws WebSocket - 閉じられた WebSocket ↗。
code number - ピアが送った WebSocket close code ↗（例: 通常クローズは 1000、離脱は 1001）。
reason string - 接続が閉じられた理由を示す文字列。空の場合があります。
wasClean boolean - 適切なクローズハンドシェイクで正常に閉じた場合は true、それ以外は false。

戻り値

なし。

例

export class MyDurableObject extends DurableObject {
	async webSocketClose(ws, code, reason, wasClean) {
		// With web_socket_auto_reply_to_close (compat date >= 2026-04-07),
		// the runtime has already completed the close handshake.
		// On older compat dates, call ws.close(code, reason) here.
		ws.close(code, reason);
		console.log(`WebSocket closed: code=${code}, reason=${reason}`);
	}
}

export class MyDurableObject extends DurableObject<Env> {
	async webSocketClose(ws: WebSocket, code: number, reason: string, wasClean: boolean) {
		// With web_socket_auto_reply_to_close (compat date >= 2026-04-07),
		// the runtime has already completed the close handshake.
		// On older compat dates, call ws.close(code, reason) here.
		ws.close(code, reason);
		console.log(`WebSocket closed: code=${code}, reason=${reason}`);
	}
}

from workers import DurableObject

class MyDurableObject(DurableObject):
    async def webSocketClose(self, ws, code, reason, was_clean):
        ws.close(code, reason)
        print(f"WebSocket closed: code={code}, reason={reason}")

`webSocketError`

webSocketError(ws WebSocket, error unknown) : void | Promise<void>
- WebSocket 接続で切断以外のエラーが起きると、システムが呼び出します。
- このメソッドは async にできます。

パラメーター

ws WebSocket - エラーが起きた WebSocket ↗。
error unknown - 発生したエラー。発生源によっては Error オブジェクト、または別の型になる場合があります。

戻り値

なし。

例

export class MyDurableObject extends DurableObject {
	async webSocketError(ws, error) {
		const message = error instanceof Error ? error.message : String(error);
		console.error(`WebSocket error: ${message}`);
	}
}

export class MyDurableObject extends DurableObject<Env> {
	async webSocketError(ws: WebSocket, error: unknown) {
		const message = error instanceof Error ? error.message : String(error);
		console.error(`WebSocket error: ${message}`);
	}
}

from workers import DurableObject

class MyDurableObject(DurableObject):
    async def webSocketError(self, ws, error):
        print(f"WebSocket error: {error}")

プロパティ

`ctx`

ctx は DurableObjectState 型の読み取り専用プロパティです。ストレージ、WebSocket 管理、その他のインスタンス固有の機能にアクセスできます。

`env`

env には、この Durable Object で使える環境バインディングが含まれます。内容は Wrangler の設定で定義します。

Durable Object 基底クラス

メソッド

fetch

パラメーター

戻り値

例

alarm

パラメーター

戻り値

例

webSocketMessage

パラメーター

戻り値

例

webSocketClose

パラメーター

戻り値

例

webSocketError

パラメーター

戻り値

例

プロパティ

ctx

env

関連リソース

`fetch`

`alarm`

`webSocketMessage`

`webSocketClose`

`webSocketError`

`ctx`

`env`