Lifecycle API

This page lists every export of agents/lifecycle. For a guided introduction, refer to Lifecycle and Build a capability.

agents/lifecycle is stable.

Lifecycle<Env, Props> is generic over the Worker environment and the type of startup props.

LifecycleObject<Env, Props> extends DurableObject<Env> with a lifecycle: Lifecycle<Env, Props> field and these optional host hooks. Each one runs inside the host context:

LifecycleObject is the default type parameter of getCurrentAgent().

DurableObjectCapability<Props> is the interface the Lifecycle calls. Every hook is optional. Hooks run outside the host context.

Any hook can also return a promise of its result.

The Lifecycle dispatches each hook as follows:

• onStart() runs on every capability, in registration order.
• onRequest() and onWebSocketUpgrade() are offered in registration order, with the catch-all last. The first Response wins.
• onWebSocketMessage(), onWebSocketClose(), and onWebSocketError() are offered in registration order until one returns true. Events that no capability consumes are ignored.
• onJob() and onJobError() go only to the capability that pushed the job.
• onRoute() goes only to the capability whose ID the message names.
• onMemoryLimit() runs on every capability. A failure in one does not stop the next.
• dispose() runs on every capability, in reverse registration order. A failure in one does not stop the next.

LifecycleCapability<Props> is an abstract class that implements DurableObjectCapability. Extend it to receive Lifecycle services.

A LifecycleCapability reads these services from this.lifecycle:

These are the Durable Object's ctx.acceptWebSocket() and ctx.getWebSockets(). get() returns sockets that other capabilities own too, so filter by your own tag.

events.emit(type, payload) publishes a LifecycleEvent with these fields:

Both source and type must be non-empty. Events emitted before startup finishes are held until it does. On a plain Durable Object, the Lifecycle publishes each event to an agents:* diagnostics channel chosen by the prefix of type. Unknown prefixes go to agents:lifecycle. The published message adds the host class name as agent, the object name, and a timestamp.

A LifecycleRouteAddress has a key, used for equality and storage, and a serialized data string.

Routing between Lifecycles needs a transport that the host provides. The Agent class provides one for its sub-agents. On a plain Durable Object there is no transport: source is undefined, toRoot() delivers to the capability's own onRoute() on the same object, and to() throws.

A capability that accepts its own WebSockets claims the upgrade, accepts the socket through sockets.accept(), and marks it with a hibernation attachment. After a wake, the Lifecycle offers each socket event to every capability in order, so each capability must recognize its own sockets and return true only for those:

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 can sit beside the WebSockets capability. WebSockets is a catch-all for upgrades, so the Lifecycle offers each upgrade to EchoSockets first, whatever the install order. For most real-time clients, use the WebSockets capability instead.

The job types are described on Jobs and alarms:

• LifecycleJobs: refer to Manage jobs.
• LifecycleJobPushOptions: refer to Push options.
• LifecycleJob: refer to The LifecycleJob shape.
• LifecycleJobOutcome: refer to Control what happens after a job runs.
• MemoryLimitContext: refer to Memory-limit protection.

agents/lifecycle defines the connection types, so that both the WebSockets capability and getCurrentAgent() can use them:

For how connections work, refer to WebSockets.

getCurrentAgent<Host>() returns a CurrentAgentContext<Host> with agent, connection, request, and email. For more information, refer to getCurrentAgent().