agents/lifecycle 中的 Lifecycle 可协调 Durable Object 的启动和传入事件。它还会将待处理作业存储在 SQLite 中,并管理对象唯一的闹钟。多项功能可以安排工作,而不会覆盖彼此的唤醒时间。
agents/lifecycle 已稳定。
安装后,Lifecycle 会为 Durable Object 提供:
- 启动。 每个内存生命周期中,首次处理请求、闹钟或 WebSocket 事件之前会运行一次
onStart()。 - 请求分发。 每个请求都会交给你安装的能力。若没有能力处理,则会交给你的
onRequest()。 - 持久化作业。 SQLite 中的作业队列拥有对象唯一的闹钟,因此不同能力安排的工作不会互相覆盖。更多信息,请参阅作业和闹钟。
- 名称。
lifecycle.name是对象被寻址时使用的名称。 - 宿主上下文。 在钩子及其调用的代码中,
getCurrentAgent()会返回当前对象、请求和连接。 - 拆除。 提供用于释放活动资源并在删除对象前停止闹钟的方法。
Lifecycle 安装的处理程序会在需要时启动流程,然后分发事件:
flowchart TB
accTitle: Lifecycle 启动与事件分发
accDescr: Lifecycle 在每个内存生命周期中启动一次 capabilities 和宿主,然后将 HTTP 请求、WebSocket 事件和 alarm 分发给相应的处理程序。
E["请求、WebSocket 事件或 alarm"] --> S{"启动完成?"}
S -->|"否"| ST["启动 capabilities,<br/>然后运行 onStart()"]
S -->|"是"| D{"分发事件"}
ST --> D
D -->|"HTTP 请求"| R["由第一个 capability 处理;<br/>否则运行 onRequest()"]
D -->|"WebSocket 事件"| W["由拥有该连接的<br/>capability 处理"]
D -->|"Alarm"| J["在所属对象上运行到期作业;<br/>然后运行 onAlarm()"]
J --> A["为下一项作业设置 alarm"]
对象被逐出、部署或崩溃后,Lifecycle 会重新启动各项能力。待处理作业仍保存在 SQLite 中,闹钟可以唤醒对象来运行这些作业。每项能力或 harness 会读取已保存的状态,以决定如何继续工作。
Lifecycle 不会自动检查点保存任意 JavaScript,也不会从函数中断处继续执行。有关重试行为和恢复模式,请参阅作业和闹钟。
npm i agentsyarn add agentspnpm add agentsbun add agents在继承 DurableObject 的类中,将 Lifecycle 构造为字段:
import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
export class MyAgent extends DurableObject {
lifecycle = Lifecycle.install(this);
onStart() {
// Runs once for each in-memory lifetime, before any other work.
}
onRequest(request) {
return new Response(`Hello from ${this.lifecycle.name}`);
}
onAlarm() {
// Runs once for each alarm, after due jobs.
}
}import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
export class MyAgent extends DurableObject<Env> {
readonly lifecycle = Lifecycle.install(this);
onStart(): void {
// Runs once for each in-memory lifetime, before any other work.
}
onRequest(request: Request): Response {
return new Response(`Hello from ${this.lifecycle.name}`);
}
onAlarm(): void {
// Runs once for each alarm, after due jobs.
}
}Lifecycle.install(this) 会构造 Lifecycle,并在对象上安装 fetch、alarm、webSocketMessage、webSocketClose 和 webSocketError 处理程序。请勿自行定义这些方法。如果类已定义其中某个方法,Lifecycle 会保留该方法,而该处理程序也不会经过 Lifecycle。
展开写法会将构造与处理程序安装分开:
import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
export class MyAgent extends DurableObject {
lifecycle = new Lifecycle(this);
constructor(ctx, env) {
super(ctx, env);
this.lifecycle.installHandlers();
}
}import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
export class MyAgent extends DurableObject<Env> {
readonly lifecycle = new Lifecycle(this);
constructor(ctx: DurableObjectState, env: Env) {
super(ctx, env);
this.lifecycle.installHandlers();
}
}多次调用 installHandlers() 会抛出错误。两种写法都接受作为第二个参数的 LifecycleOptions。其中唯一的选项 maxAlarmMemoryLimitStrikes 详见内存限制保护。
如需从 Worker 访问对象,请参阅路由。
在类上实现以下可选方法。Lifecycle 会在宿主上下文中调用它们,因此其中可以使用 getCurrentAgent()。
| 钩子 | 触发时机 |
|---|---|
onStart(props?) |
每个内存生命周期运行一次,在所有能力启动后运行。 |
onRequest(request) |
对于每个未被任何能力处理的 HTTP 请求运行。 |
onAlarm() |
每次闹钟运行一次,在 Lifecycle 运行到期作业后执行。 |
onJob(context) |
宿主通过 lifecycle.jobs 推送的作业到期时运行。 |
onAlarmMemoryLimit(context) |
闹钟因内存限制重置而结束后,在每项能力运行完策略后执行。 |
如果未实现 onRequest(),未被任何能力处理的 HTTP 请求会返回 404。LifecycleObject 类型描述了包含这些钩子和 lifecycle 字段的 Durable Object。
宿主不会收到 WebSocket 事件。如需接受 WebSocket 客户端,请安装 WebSockets 能力。
每个内存生命周期首次收到请求、闹钟或 WebSocket 事件时,Lifecycle 都会启动:
- 解析对象名称。
- 各项能力按注册顺序运行其
onStart()钩子,兜底能力最后运行。 - 宿主运行
onStart(props)。 - Lifecycle 处理唤醒对象的事件。
启动过程在 blockConcurrencyWhile() 中运行,因此完成前不会有其他事件到达对象。处于热状态的对象会跳过启动。如果启动抛出异常,该事件会失败,下一个事件会重试启动。只要作业队列中仍有作业,备用闹钟也会重试启动,因此排队的工作不必等待新请求。
props 来自 props 路由选项,或来自 lifecycle.start(props)。
Durable Object 上的公共方法是 RPC 方法。
RPC 调用不会经过 fetch(),因此不会启动生命周期。在每个使用 capability 或使用 onStart() 所设置内容的 RPC 方法开头,调用 await this.lifecycle.start()。
import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
export class MyAgent extends DurableObject {
lifecycle = Lifecycle.install(this);
#userId;
onStart(props) {
this.#userId = props?.userId;
}
async whoAmI(props) {
await this.lifecycle.start(props);
return this.#userId;
}
}import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
type Props = { userId: string };
export class MyAgent extends DurableObject<Env> {
readonly lifecycle = Lifecycle.install<Env, Props>(this);
#userId: string | undefined;
onStart(props?: Props): void {
this.#userId = props?.userId;
}
async whoAmI(props?: Props): Promise<string | undefined> {
await this.lifecycle.start(props);
return this.#userId;
}
}start(props) 会将 props 传给每项能力的 onStart() 和宿主的 onStart()。如果启动已在运行或已完成,则会忽略这些属性。并发调用 start() 时会共享同一次启动。在启动期间发起的调用会立即返回,不会等待自身完成。
所有能力和宿主的 onStart() 完成后,lifecycle.isStarted() 会返回 true。许多能力方法(例如 scheduler.set())会自行等待启动完成。
在对象内部,Lifecycle 会将每个 HTTP 请求交给实现了 onRequest() 的能力,并将每个 WebSocket 升级请求交给实现了 onWebSocketUpgrade() 的能力。第一个返回 Response 的能力会处理请求。返回 undefined 的能力会继续传递请求。此处没有 next() 回调,因此能力无法包装或观察后续响应。
启动后,非升级 HTTP 请求会按以下路径处理:
flowchart TB
accTitle: Lifecycle 启动后分发非升级 HTTP 请求
accDescr: 选择性 HTTP capabilities 按注册顺序运行,直到其中一个返回 Response。若没有 capability 处理请求,则尝试 HTTP 兜底处理程序。如果兜底处理程序不存在或返回 undefined,则运行宿主的 onRequest 钩子。若宿主未定义该钩子,则返回 404。
S["按注册顺序尝试选择性<br/>HTTP capabilities"] -->|"第一个 Response"| R["返回响应"]
S -->|"全部返回 undefined"| C["尝试已安装的 HTTP 兜底处理程序"]
C -->|"Response"| R
C -->|"不存在或返回 undefined"| H["运行宿主的 onRequest()(若已定义)"]
H -->|"Response"| R
H -->|"无钩子"| N["404"]
能力通过 claims 声明如何处理流量:
| 值 | 行为 |
|---|---|
"selective"(默认) |
仅处理它能识别的路由,其余路由返回 undefined。按注册顺序运行。 |
"catch-all" |
处理提供给其所实现钩子的所有内容。只要已安装,就始终在所有 selective 能力之后运行。 |
每个钩子只能有一个全捕获处理程序。为 onRequest() 或 onWebSocketUpgrade() 安装第二个全捕获处理程序时,use() 会抛出错误,因为它永远无法被执行。HTTP 的全捕获处理程序和升级请求的全捕获处理程序可以共存。
| 事件 | 处理方 |
|---|---|
| HTTP 请求 | 第一个返回 Response 的能力;否则由宿主的 onRequest() 处理;再否则返回 404 |
| WebSocket 升级 | 第一个返回 Response 的能力;否则返回 404 |
| WebSocket 消息、关闭或错误 | 拥有该连接的能力;否则忽略 |
| Alarm | 先处理到期作业,再调用宿主的 onAlarm() |
能力是 Durable Object 中可复用的一部分,例如 WebSocket 连接或调度器。将每个能力构造为字段,然后使用 use() 注册:
import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
import { Scheduler } from "agents/schedules";
import { WebSockets } from "agents/websockets";
export class MyAgent extends DurableObject {
scheduler = new Scheduler({ callbacks: {} });
webSockets = new WebSockets();
lifecycle = Lifecycle.install(this).use(this.scheduler).use(this.webSockets);
}import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
import { Scheduler } from "agents/schedules";
import { WebSockets } from "agents/websockets";
export class MyAgent extends DurableObject<Env> {
readonly scheduler = new Scheduler({ callbacks: {} });
readonly webSockets = new WebSockets();
readonly lifecycle = Lifecycle.install(this)
.use(this.scheduler)
.use(this.webSockets);
}use() 返回 Lifecycle,因此可以链式调用。它遵循以下规则:
- 在
lifecycle字段之前声明能力字段。 类字段按顺序初始化,因此在lifecycle之后声明的能力,在use()运行时仍为undefined。 - 在启动前注册所有能力。 启动开始后,
use()会抛出错误。 - 每个能力 ID 只能安装一次。 如果具有相同 ID 的能力已安装,
use()会抛出错误。
有关 SDK 随附的能力,请参阅能力。
Lifecycle 从 ctx.id.name 读取对象名称,并将其公开为 lifecycle.name。使用 getByName() 或 idFromName() 按名称寻址对象,或使用 routeAgentRequest() 将请求路由到对象。
没有名称的对象会启动失败。这种情况会出现在来自 newUniqueId() 或 idFromString() 的 ID,以及长度超过 1,024 字节的名称中。对于由旧版 PartyServer 创建的对象,Lifecycle 还会从存储中读取旧版名称记录,但绝不会写入该记录。
lifecycle.sql 是一个带标签的模板,用于对对象的 SQLite 数据库运行查询。插值会成为绑定参数,结果是一个行数组:
import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
export class NotesAgent extends DurableObject {
lifecycle = Lifecycle.install(this);
onStart() {
this.lifecycle
.sql`CREATE TABLE IF NOT EXISTS notes (id TEXT PRIMARY KEY, body TEXT NOT NULL)`;
}
onRequest(request) {
const id = new URL(request.url).searchParams.get("id") ?? "";
const rows = this.lifecycle.sql`
SELECT id, body FROM notes WHERE id = ${id}
`;
return Response.json(rows);
}
}import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
export class NotesAgent extends DurableObject<Env> {
readonly lifecycle = Lifecycle.install(this);
onStart(): void {
this.lifecycle
.sql`CREATE TABLE IF NOT EXISTS notes (id TEXT PRIMARY KEY, body TEXT NOT NULL)`;
}
onRequest(request: Request): Response {
const id = new URL(request.url).searchParams.get("id") ?? "";
const rows = this.lifecycle.sql<{ id: string; body: string }>`
SELECT id, body FROM notes WHERE id = ${id}
`;
return Response.json(rows);
}
}值必须是字符串、数字、布尔值或 null。对于其他查询,请直接使用 ctx.storage.sql。
一个 Durable Object 只有一个 alarm。Lifecycle 拥有该 alarm,并根据持久作业队列设置它,因此 Scheduler 等能力绝不会互相覆盖 alarm。你的类可以通过 lifecycle.jobs 推送自己的作业,并在 onJob() 中处理它们。
不要对使用 Lifecycle 的对象调用 ctx.storage.setAlarm()。有关详细信息,请参阅作业和 alarm。
Lifecycle 有两种拆除方法:
lifecycle.disableAlarms()会阻止 Lifecycle 再次设置 alarm,并删除当前 alarm。此实例无法撤销该操作。lifecycle.dispose()按与注册相反的顺序调用每个能力的dispose()钩子。它会释放活动资源,例如 MCP 传输和打开的 WebSocket 连接,但不会删除已存储的数据。
驱逐不会调用这两个方法。要删除对象,请同时调用这两个方法,然后删除其存储:
import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
export class MyAgent extends DurableObject {
lifecycle = Lifecycle.install(this);
async destroy() {
await this.lifecycle.disableAlarms();
await this.lifecycle.dispose();
await this.ctx.storage.deleteAll();
}
}import { DurableObject } from "cloudflare:workers";
import { Lifecycle } from "agents/lifecycle";
export class MyAgent extends DurableObject<Env> {
readonly lifecycle = Lifecycle.install(this);
async destroy(): Promise<void> {
await this.lifecycle.disableAlarms();
await this.lifecycle.dispose();
await this.ctx.storage.deleteAll();
}
}Agent 类将此 Lifecycle 安装为其 lifecycle 字段,并已附加多个能力。它还会在公共 async RPC 方法运行前启动 Lifecycle。
- 路由介绍请求如何从 Worker 到达你的对象。
- 作业和闹钟介绍持久化作业队列。
getCurrentAgent()可从共享代码中读取当前对象、请求和连接。- Lifecycle API列出了
agents/lifecycle的所有导出。 - 构建能力介绍如何编写自己的能力。