Durable Object State

DurableObjectState 接口可作为 Durable Object 类 上的实例属性访问。此接口封装修改 Durable Object 状态的方法，例如哪些 WebSocket 附加到 Durable Object，或运行时如何处理并发 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 自身顶层导出的回环绑定（loopback bindings）。其含义与 ExecutionContext 的 ctx.exports 完全相同。

waitUntil 在 DurableObjectState 上可用，用于与 Workers Runtime API 保持 API 兼容性。

• 任意类型的必需 promise。

• 无。

blockConcurrencyWhile 在执行异步回调期间，会阻止向 Durable Object 投递任何其他事件，直到回调完成。此方法保证顺序并防止并发请求。所有并非作为回调本身一部分显式发起的事件都将被阻止。回调完成后，所有其他事件将被投递。

• blockConcurrencyWhile 通常在 Durable Object 类的构造函数中使用，以强制在投递任何请求之前完成初始化。
• 另一个用例是基于 Durable Object 的当前状态执行 async 操作，并使用 blockConcurrencyWhile 在让出事件循环时防止该状态发生变化。
• 如果回调抛出异常，对象将被终止并重置。这可确保在发生意外失败时，对象不会卡在未初始化状态。
• 为避免此行为，请将回调主体放在 try...catch 块中，确保其不会抛出异常。

为帮助缓解死锁，执行回调时会应用 30 秒超时。如果超过此超时，Durable Object 将被重置。最佳实践是让回调尽可能少地工作，以提高 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 允许将 Durable Object 从内存中移除以节省成本，同时保持其 WebSocket 连接。

acceptWebSocket 将 WebSocket 添加到附加到 Durable Object 的 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 个字符，每个 WebSocket 最多可关联 10 个标签。

• 无。

getWebSockets 是 WebSocket Hibernation API 的一部分，该 API 允许将 Durable Object 从内存中移除以节省成本，同时保持其 WebSocket 连接。

getWebSockets 返回 Array<WebSocket>，即附加到 Durable Object 的 WebSocket 集合。可选的 tag 参数可用于根据调用 DurableObjectState::acceptWebSocket 时提供的标签筛选列表。

• 可选的 string 类型标签。

• Array<WebSocket>。

setWebSocketAutoResponse 是 WebSocket Hibernation API 的一部分，该 API 允许将 Durable Object 从内存中移除以节省成本，同时保持其 WebSocket 连接。

setWebSocketAutoResponse 为附加到 Durable Object 的所有 WebSocket 设置针对所提供请求的自动响应（auto-response）。如果收到与所提供请求匹配的请求，则将返回自动响应，而无需唤醒休眠中的 WebSocket，也不会产生可计费时长费用。

setWebSocketAutoResponse 是为静态 ping/pong 消息设置服务器的常见替代方案，因为这可以在不唤醒休眠 WebSocket 的情况下处理。

• 可选的 WebSocketRequestResponsePair(request string, response string)，使通过 DurableObjectState::acceptWebSocket 接受的任何 WebSocket 在收到所提供请求时自动回复所提供的响应。request 和 response 均限制为各 2,048 个字符。如果省略该参数，将移除任何先前设置的自动响应配置。DurableObjectState::getWebSocketAutoResponseTimestamp 仍会反映上次发送自动响应的时间戳。

• 无。

getWebSocketAutoResponse 返回由 DurableObjectState::setWebSocketAutoResponse 最后设置的 WebSocketRequestResponsePair 对象；如果尚未设置自动响应，则返回 null。

• 无。

• WebSocketRequestResponsePair 或 null。

getWebSocketAutoResponseTimestamp 是 WebSocket Hibernation API 的一部分，该 API 允许将 Durable Object 从内存中移除以节省成本，同时保持其 WebSocket 连接。

getWebSocketAutoResponseTimestamp 获取给定 WebSocket 最近一次发送自动响应的 Date；如果给定 WebSocket 从未发送过自动响应，则返回 null。

• 必需的 WebSocket。

• Date 或 null。

setHibernatableWebSocketEventTimeout 是 WebSocket Hibernation API 的一部分，该 API 允许将 Durable Object 从内存中移除以节省成本，同时保持其 WebSocket 连接。

setHibernatableWebSocketEventTimeout 设置 WebSocket 事件可运行的最大时间（毫秒）。

如果未提供参数或提供参数 0，且先前已设置超时，则将取消该超时。超时的最大值为 604,800,000 毫秒（7 天）。

• 可选的 number。

• 无。

getHibernatableWebSocketEventTimeout 是 WebSocket Hibernation API 的一部分，该 API 允许将 Durable Object 从内存中移除以节省成本，同时保持其 WebSocket 连接。

getHibernatableWebSocketEventTimeout 获取当前设置的 hibernatable WebSocket 事件超时（如果已通过 DurableObjectState::setHibernatableWebSocketEventTimeout 设置）。

• 无。

• 一个数字；如果尚未设置超时，则为 null。

getTags 是 WebSocket Hibernation API 的一部分，该 API 允许将 Durable Object 从内存中移除以节省成本，同时保持其 WebSocket 连接。

getTags 返回与给定 WebSocket 关联的标签。如果该 WebSocket 尚未通过 DurableObjectState::acceptWebSocket 与 Durable Object 关联，此方法会抛出异常。

• 必需的 WebSocket。

• 标签的 Array<string>。

abort 用于强制重置 Durable Object。将记录一条 JavaScript Error，其消息为作为参数传入的消息。此错误无法在应用程序代码中捕获。

// 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!");
  }
}

# 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。

• 无。

id 是只读属性，类型为 DurableObjectId，对应于该 Durable Object 的 DurableObjectId。

storage 是只读属性，类型为 DurableObjectStorage，封装了 Storage API。

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