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,消息为传入 abort 的内容。应用程序代码无法捕获此错误。
默认情况下,被 abort 中断的 alarm 会在 Durable Object 重置后重试。Durable Object 可以与另一个请求并发运行 alarm,而该请求可以在 alarm 仍在运行时调用 abort。
默认重试可防止无关请求永久取消 alarm。对于任何应阻止被中断 alarm 重试的 abort 调用(包括 alarm 处理器之外的 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对象:retryAlarmboolean:控制被此次 abort 中断的 alarm 是否重试。默认为true。
- 无。
id 是只读属性,类型为 DurableObjectId,对应于该 Durable Object 的 DurableObjectId。
storage 是只读属性,类型为 DurableObjectStorage,封装了 Storage API。