生命周期 API

本页面列出了 agents/lifecycle 的所有导出项。入门介绍请参阅 Lifecycle 和构建功能。

agents/lifecycle 已稳定。

导出项

导出	类型	说明
`Lifecycle`	类	安装到 Durable Object 上，并运行启动、路由、作业和闹钟
`LifecycleOptions`	类型	`Lifecycle.install()` 和 `new Lifecycle()` 的选项
`LifecycleObject`	接口	带有 `lifecycle` 字段和主机钩子的 Durable Object
`LifecycleCapability`	抽象类	使用 Lifecycle 服务的能力基类
`DurableObjectCapability`	接口	Lifecycle 为能力调用的钩子
`LifecycleServices`	类型	`LifecycleCapability` 可通过 `this.lifecycle` 访问的服务
`LifecycleStatus`	类型	`"zero"`、`"starting"` 或 `"started"`
`LifecycleSockets`	类型	供能力使用的可休眠 WebSocket 访问接口
`LifecycleEvents`	类型	为能力尽力发布事件
`LifecycleEvent`	类型	一个已发布的事件
`LifecycleRoutes`	类型	Lifecycle 之间的消息路由
`LifecycleRouteAddress`	类型	路由到某个 Lifecycle 的地址
`LifecycleRouteContext`	类型	`onRoute()` 的参数
`LifecycleHostContextScope`	类型	传递给 `runInHostContext()` 的连接和请求
`CapabilityStartContext`	类型	能力 `onStart()` 的参数
`CapabilityRequestContext`	类型	`onRequest()` 的参数
`CapabilityWebSocketUpgradeContext`	类型	`onWebSocketUpgrade()` 的参数
`LifecycleJobs`	类型	供宿主或某项能力访问的作业队列
`LifecycleJob`	类型	一个已存储的作业
`LifecycleJobPushOptions`	类型	`jobs.push()` 的选项
`LifecycleJobContext`	类型	`onJob()` 和 `onJobError()` 的参数
`LifecycleJobOutcome`	类型	`onJob()` 和 `onJobError()` 的返回值
`MemoryLimitContext`	类型	`onMemoryLimit()` 和 `onAlarmMemoryLimit()` 的参数
`getCurrentAgent`	函数	读取当前对象、请求和连接
`CurrentAgentContext`	类型	`getCurrentAgent()` 的返回值
`Connection`	类型	由某项能力管理的 WebSocket 连接
`ConnectionContext`	类型	接受连接时传入的上下文
`ConnectionState`	类型	连接上存储的只读状态
`ConnectionSetStateFn`	类型	`connection.setState()` 的更新函数
`WSMessage`	类型	WebSocket 消息：`string`、`ArrayBuffer` 或 `ArrayBufferView`

`Lifecycle`

Lifecycle<Env, Props> 的泛型参数分别是 Worker 环境和启动属性类型。

静态方法和构造函数

成员	说明
`Lifecycle.install(host, options?)`	构造 Lifecycle 并调用 `installHandlers()`。返回 Lifecycle 实例。
`new Lifecycle(host, options?)`	构造 Lifecycle，但不安装处理程序。
`installHandlers()`	除非宿主已自行定义，否则会在宿主上安装 `fetch`、`alarm`、`webSocketMessage`、`webSocketClose` 和 `webSocketError`。重复调用时会抛出异常。

实例成员

成员	返回值	说明
`use(capability)`	`this`	安装一项能力。启动后、ID 重复时，或同一钩子已有兜底能力时，都会抛出异常。
`start(props?)`	`Promise<void>`	启动能力和宿主。会在 fetch、闹钟和 WebSocket 事件中自动调用。请在 RPC 方法中调用它。
`isStarted()`	`boolean`	所有能力和宿主的 `onStart()` 完成后为 `true`。
`name`	`string`	对象在 `ctx.id.name` 中的名称。对象没有名称时会抛出异常。
`jobs`	`LifecycleJobs`	宿主所见的作业队列。
sql`...`	`T[]`	使用绑定参数对对象的 SQLite 数据库执行查询。
`rearmAlarm()`	`Promise<void>`	根据作业队列设置闹钟。队列发生变化时会自动调用。
`trackAlarmWork(promise)`	`boolean`	使作业交接的工作受当前闹钟的内存限制保护。在闹钟处理期间之外返回 `false`。
`dispose()`	`Promise<void>`	按注册顺序的逆序调用每项能力的 `dispose()`。
`disableAlarms()`	`Promise<void>`	删除闹钟并停止 Lifecycle 再次设置闹钟。用于拆除对象时。

`LifecycleOptions`

选项	类型	默认值	说明
`maxAlarmMemoryLimitStrikes`	`number`	`3`	熔断器删除恢复作业之前，连续发生内存限制重置的次数。更多信息，请参阅内存限制保护。

`LifecycleObject`

LifecycleObject<Env, Props> 扩展 DurableObject<Env>，并包含 lifecycle: Lifecycle<Env, Props> 字段及以下可选宿主钩子。每个钩子都在宿主上下文中运行：

Hook	返回值	触发时机
`onStart(props?)`	`void \| Promise<void>`	每个内存生命周期运行一次，在所有能力启动后运行。
`onRequest(request)`	`Response \| Promise<Response>`	对于每个未被任何能力处理的 HTTP 请求运行。
`onAlarm()`	`void \| Promise<void>`	每次闹钟运行一次，在到期作业之后运行。
`onJob(context)`	`LifecycleJobOutcome \| void` 或一个 Promise。	宿主作业到期时运行。
`onAlarmMemoryLimit(context)`	`void \| Promise<void>`	闹钟因内存限制重置而结束后、能力钩子运行后执行。

LifecycleObject 是 getCurrentAgent() 的默认类型参数。

`DurableObjectCapability`

DurableObjectCapability<Props> 是 Lifecycle 调用的接口。所有钩子均为可选。钩子在宿主上下文之外运行。

成员	返回值	说明
`claims`	`"selective" \| "catch-all"`	能力如何声明对流量的处理权。默认为 `"selective"`。更多信息，请参阅能力顺序。
`onStart(context)`	`void`	创建表或恢复状态。按注册顺序运行，并先于宿主的 `onStart()`。`context.props` 中包含启动属性。
`onRequest(context)`	`Response \| undefined`	通过返回 `Response` 处理 HTTP 请求，或返回 `undefined` 继续传递请求。
`onWebSocketUpgrade(context)`	`Response \| undefined`	通过返回 `Response` 接受 WebSocket 升级。此后，该能力会在套接字的整个生命周期内拥有它。
`onWebSocketMessage(ws, message)`	`boolean \| void`	处理休眠套接字上的消息。返回 `true` 表示已处理该消息。
`onWebSocketClose(ws, code, reason, wasClean)`	`boolean \| void`	处理休眠套接字的关闭事件。返回 `true` 表示已处理该事件。
`onWebSocketError(ws, error)`	`boolean \| void`	处理休眠套接字的错误事件。返回 `true` 表示已处理该事件。
`onJob(context)`	`LifecycleJobOutcome \| void`	运行该能力推送的一个到期作业。请保持处理时间简短。
`onJobError(context, error)`	`LifecycleJobOutcome \| void`	作业最后一次重试失败后运行。返回值决定如何处理该作业。不返回值表示作业已完成。
`onMemoryLimit(context)`	`void`	在闹钟因内存限制重置而结束后应用策略。先于宿主的 `onAlarmMemoryLimit()` 运行。写入操作应尽量少。
`onRoute(context)`	`unknown`	处理路由到此能力 ID 的消息。返回值会发送回发送方。
`dispose()`	`void`	在显式拆除期间释放活动资源。对象被逐出时不会运行。

任何钩子都可以返回表示其结果的 Promise。

Lifecycle 会按以下方式分发每个钩子：

onStart() 会按注册顺序在每项能力上运行。
onRequest() 和 onWebSocketUpgrade() 会按注册顺序依次交给各项能力处理，兜底能力最后运行。第一个返回 Response 的能力会处理请求。
onWebSocketMessage()、onWebSocketClose() 和 onWebSocketError() 会按注册顺序依次调用，直到某项能力返回 true。未被任何能力处理的事件会被忽略。
onJob() 和 onJobError() 只会交给推送该作业的能力。
onRoute() 只会交给消息中指定 ID 的能力。
onMemoryLimit() 会在每项能力上运行。一项能力失败不会阻止后续能力运行。
dispose() 会按注册顺序的逆序在每项能力上运行。一项能力失败不会阻止后续能力运行。

上下文类型

类型	字段
`CapabilityStartContext<Props>`	`props: Props \| undefined`
`CapabilityRequestContext`	`request: Request`
`CapabilityWebSocketUpgradeContext`	`request: Request`
`LifecycleJobContext`	`job: LifecycleJob`, `attempt: number`
`LifecycleRouteContext`	`source: LifecycleRouteAddress \| undefined`, `payload: unknown`
`MemoryLimitContext`	`sealed`、`nextTime?`、`executing?`、`purgedRecoveryLoopJobs?`。更多信息，请参阅内存限制保护。

`LifecycleCapability`

LifecycleCapability<Props> 是实现 DurableObjectCapability 的抽象类。继承它即可访问 Lifecycle 服务。

成员	说明
`constructor(id)`	受保护成员。接受该能力的稳定 ID。ID 为空时会抛出异常。
`capabilityId`	传给构造函数的 ID。作业、事件和路由消息都会使用它。
`claims`	默认值为 `"selective"`。若该能力会处理其钩子的所有流量，可将其覆盖为 `"catch-all"`。
`onStart(context)`	默认不执行任何操作。可覆盖此方法以创建表或恢复状态。
`lifecycle`	受保护成员。该能力的 `LifecycleServices`。未安装该能力时会抛出异常。
`lifecycleServices`	受保护成员。相同的服务；安装前为 `undefined`。

`LifecycleServices`

LifecycleCapability 可通过 this.lifecycle 读取以下服务：

成员	类型	说明
`name`	`string`	对象名称。与 `Lifecycle.name` 相同。
`className`	`string`	宿主类名称，即 Worker 导出的类名称。
`storage`	`DurableObjectStorage`	对象的存储，包括 `storage.sql`。
`sockets`	`LifecycleSockets`	接受并列出可休眠 WebSocket。
`ready()`	`() => Promise<void>`	在启动完成时解析；如有需要会先启动对象。启动失败时会拒绝。启动过程中会立即解析。
`status()`	`() => LifecycleStatus`	启动前为 `"zero"`，启动期间为 `"starting"`，启动后为 `"started"`。
`jobs`	`LifecycleJobs`	该能力所见的作业队列。
`trackAlarmWork(promise)`	`(work: Promise<unknown>) => boolean`	使 `onJob()` 交接的工作受当前闹钟的内存限制保护。在闹钟处理期间之外返回 `false`。
`runInHostContext(fn, scope?)`	`Promise<unknown>`	在宿主上下文中运行用户代码，因此 `getCurrentAgent()` 可用。`scope` 的类型为 `LifecycleHostContextScope`。
`events`	`LifecycleEvents`	尽力发布事件。
`routes`	`LifecycleRoutes`	向另一个 Lifecycle 上 ID 相同的能力发送消息。

`LifecycleSockets`

成员	说明
`accept(ws, tags)`	接受服务器端 WebSocket，并使用给定标签进行休眠。
`get(tag?)`	返回对象上所有休眠的 WebSocket，可选择按标签筛选。

这些服务对应 Durable Object 的 ctx.acceptWebSocket() 和 ctx.getWebSockets()。get() 也会返回由其他能力持有的套接字，因此请使用自己的标签进行筛选。

`LifecycleHostContextScope`

字段	类型	说明
`connection`	`Connection \| undefined`	用户代码代表其运行的连接
`request`	`Request \| undefined`	用户代码代表其运行的请求

`LifecycleEvents` 和 `LifecycleEvent`

events.emit(type, payload) 会发布一个包含以下字段的 LifecycleEvent：

字段	类型	说明
`source`	`string`	能力 ID；队列事件使用 `"lifecycle"`。
`type`	`string`	事件名称，例如 `uptime:check`。
`payload`	`unknown`	事件数据

source 和 type 都不能为空。启动完成前发出的事件会暂存，直到启动完成。在普通 Durable Object 上，Lifecycle 会根据 type 的前缀，将每个事件发布到相应的 agents:*诊断通道。未知前缀的事件会发送到 agents:lifecycle。发布的消息还会添加宿主类名称作为 agent、对象 name 和 timestamp。

`LifecycleRoutes`

成员	说明
`source`	此 Lifecycle 的 `LifecycleRouteAddress`；如果是根对象，则为 `undefined`。
`toRoot(payload)`	将 `payload` 发送给根 Lifecycle 上 ID 相同的能力，并解析为其 `onRoute()` 的返回值。
`to(target, payload)`	将 `payload` 发送给 `target` 处 Lifecycle 上 ID 相同的能力。

LifecycleRouteAddress 包含用于比较和存储的 key，以及序列化后的 data 字符串。

Lifecycle 之间的路由需要由宿主提供传输机制。Agent 类会为其子 Agent 提供传输机制。普通 Durable Object 没有传输机制：source 为 undefined，toRoot() 会在同一对象上调用该能力自己的 onRoute()，而 to() 会抛出异常。

管理自己的 WebSocket 连接

接受自有 WebSocket 的能力会声明处理升级请求，通过 sockets.accept() 接受套接字，并为其添加休眠附件。对象唤醒后，Lifecycle 会按顺序将每个套接字事件交给所有能力，因此每项能力都必须识别自己的套接字，并且仅对自己的套接字返回 true：

import { LifecycleCapability } from "agents/lifecycle";

const TAG = "echo";

export class EchoSockets extends LifecycleCapability {
	constructor() {
		super("echo-sockets");
	}

	onWebSocketUpgrade({ request }) {
		if (!new URL(request.url).pathname.endsWith("/echo")) return;
		const { 0: client, 1: server } = new WebSocketPair();
		server.serializeAttachment({ owner: TAG });
		this.lifecycle.sockets.accept(server, [TAG]);
		return new Response(null, { status: 101, webSocket: client });
	}

	onWebSocketMessage(ws, message) {
		if (!this.#owns(ws)) return false;
		ws.send(message);
		return true;
	}

	onWebSocketClose(ws, code, reason) {
		if (!this.#owns(ws)) return false;
		ws.close(code, reason);
		return true;
	}

	get connectionCount() {
		return this.lifecycle.sockets.get(TAG).length;
	}

	#owns(ws) {
		const attachment = ws.deserializeAttachment();
		return attachment?.owner === TAG;
	}
}

import {
	LifecycleCapability,
	type CapabilityWebSocketUpgradeContext,
	type WSMessage,
} from "agents/lifecycle";

const TAG = "echo";

export class EchoSockets extends LifecycleCapability {
	constructor() {
		super("echo-sockets");
	}

	onWebSocketUpgrade({
		request,
	}: CapabilityWebSocketUpgradeContext): Response | undefined {
		if (!new URL(request.url).pathname.endsWith("/echo")) return;
		const { 0: client, 1: server } = new WebSocketPair();
		server.serializeAttachment({ owner: TAG });
		this.lifecycle.sockets.accept(server, [TAG]);
		return new Response(null, { status: 101, webSocket: client });
	}

	onWebSocketMessage(ws: WebSocket, message: WSMessage): boolean {
		if (!this.#owns(ws)) return false;
		ws.send(message);
		return true;
	}

	onWebSocketClose(ws: WebSocket, code: number, reason: string): boolean {
		if (!this.#owns(ws)) return false;
		ws.close(code, reason);
		return true;
	}

	get connectionCount(): number {
		return this.lifecycle.sockets.get(TAG).length;
	}

	#owns(ws: WebSocket): boolean {
		const attachment = ws.deserializeAttachment() as { owner?: string } | null;
		return attachment?.owner === TAG;
	}
}

EchoSockets 可以与 WebSockets 能力并存。WebSockets 会兜底处理升级请求，因此无论安装顺序如何，Lifecycle 都会先将每次升级请求交给 EchoSockets。对于大多数实时客户端，请改用 WebSockets 能力。

作业类型

作业类型详见作业和闹钟：

LifecycleJobs：请参阅管理作业。
LifecycleJobPushOptions：请参阅推送选项。
LifecycleJob：请参阅LifecycleJob 的结构。
LifecycleJobOutcome：请参阅控制作业运行后的处理方式。
MemoryLimitContext：请参阅内存限制保护。

连接类型

agents/lifecycle 定义了连接类型，因此 WebSockets 能力和 getCurrentAgent() 都可以使用这些类型：

类型	说明
`Connection<TState>`	一个包含 `id`、`uri`（升级 URL）、只读 `state`、`setState()` 和 `tags` 的 `WebSocket`。第一个标签始终是连接 ID。
`ConnectionContext`	`{ request: Request }`，即原始升级请求。
`ConnectionState<T>`	不可变的连接状态，或 `null`。此状态存储在套接字的休眠附件中。
`ConnectionSetStateFn<T>`	`(prevState: ConnectionState<T>) => T`，即 `connection.setState()` 的更新函数。
`WSMessage`	`string \| ArrayBuffer \| ArrayBufferView`.

有关连接的工作方式，请参阅 WebSockets。

`getCurrentAgent()` 的类型

getCurrentAgent<Host>() 会返回包含 agent、connection、request 和 email 的 CurrentAgentContext<Host>。更多信息，请参阅 getCurrentAgent()。

生命周期 API

导出项

Lifecycle

静态方法和构造函数

实例成员

LifecycleOptions

LifecycleObject

DurableObjectCapability

上下文类型

LifecycleCapability

LifecycleServices

LifecycleSockets

LifecycleHostContextScope

LifecycleEvents 和 LifecycleEvent

LifecycleRoutes