@rivetkit/cloudflare-workers 0.9.0

package/src/actor-driver.ts

@@ -0,0 +1,66 @@
+import type { ActorDriver, AnyActorInstance } from "@rivetkit/core/driver-helpers";
+import invariant from "invariant";
+import { KEYS } from  "./actor-handler-do";
+
+interface DurableObjectGlobalState {
+	ctx: DurableObjectState;
+	env: unknown;
+}
+
+/**
+ * Cloudflare DO can have multiple DO running within the same global scope.
+ *
+ * This allows for storing the actor context globally and looking it up by ID in `CloudflareActorsActorDriver`.
+ */
+export class CloudflareDurableObjectGlobalState {
+	// Single map for all actor state
+	#dos: Map<string, DurableObjectGlobalState> = new Map();
+
+	getDOState(actorId: string): DurableObjectGlobalState {
+		const state = this.#dos.get(actorId);
+		invariant(state !== undefined, "durable object state not in global state");
+		return state;
+	}
+
+	setDOState(actorId: string, state: DurableObjectGlobalState) {
+		this.#dos.set(actorId, state);
+	}
+}
+
+export interface ActorDriverContext {
+	ctx: DurableObjectState;
+	env: unknown;
+}
+
+export class CloudflareActorsActorDriver implements ActorDriver {
+	#globalState: CloudflareDurableObjectGlobalState;
+
+	constructor(globalState: CloudflareDurableObjectGlobalState) {
+		this.#globalState = globalState;
+	}
+
+	#getDOCtx(actorId: string) {
+		return this.#globalState.getDOState(actorId).ctx;
+	}
+
+	getContext(actorId: string): ActorDriverContext {
+		const state = this.#globalState.getDOState(actorId);
+		return { ctx: state.ctx, env: state.env };
+	}
+
+	async readPersistedData(actorId: string): Promise<Uint8Array | undefined> {
+		return await this.#getDOCtx(actorId).storage.get(KEYS.PERSIST_DATA);
+	}
+
+	async writePersistedData(actorId: string, data: Uint8Array): Promise<void> {
+		await this.#getDOCtx(actorId).storage.put(KEYS.PERSIST_DATA, data);
+	}
+
+	async setAlarm(actor: AnyActorInstance, timestamp: number): Promise<void> {
+		await this.#getDOCtx(actor.id).storage.setAlarm(timestamp);
+	}
+
+	async getDatabase(actorId: string): Promise<unknown | undefined> {
+		return this.#getDOCtx(actorId).storage.sql;
+	}
+}

package/src/actor-handler-do.ts

@@ -0,0 +1,184 @@
+import { DurableObject } from "cloudflare:workers";
+import type { Registry, RunConfig, ActorKey } from "@rivetkit/core";
+import { serializeEmptyPersistData } from "@rivetkit/core/driver-helpers";
+import { logger } from "./log";
+import { PartitionTopologyActor } from "@rivetkit/core/topologies/partition";
+import {
+	CloudflareDurableObjectGlobalState,
+	CloudflareActorsActorDriver,
+} from "./actor-driver";
+import { Bindings, CF_AMBIENT_ENV } from "./handler";
+import { ExecutionContext } from "hono";
+
+export const KEYS = {
+	NAME: "rivetkit:name",
+	KEY: "rivetkit:key",
+	PERSIST_DATA: "rivetkit:data",
+};
+
+export interface ActorHandlerInterface extends DurableObject {
+	initialize(req: ActorInitRequest): Promise<void>;
+}
+
+export interface ActorInitRequest {
+	name: string;
+	key: ActorKey;
+	input?: unknown;
+}
+
+interface InitializedData {
+	name: string;
+	key: ActorKey;
+}
+
+export type DurableObjectConstructor = new (
+	...args: ConstructorParameters<typeof DurableObject<Bindings>>
+) => DurableObject<Bindings>;
+
+interface LoadedActor {
+	actorTopology: PartitionTopologyActor;
+}
+
+export function createActorDurableObject(
+	registry: Registry<any>,
+	runConfig: RunConfig,
+): DurableObjectConstructor {
+	const globalState = new CloudflareDurableObjectGlobalState();
+
+	/**
+	 * Startup steps:
+	 * 1. If not already created call `initialize`, otherwise check KV to ensure it's initialized
+	 * 2. Load actor
+	 * 3. Start service requests
+	 */
+	return class ActorHandler
+		extends DurableObject<Bindings>
+		implements ActorHandlerInterface
+	{
+		#initialized?: InitializedData;
+		#initializedPromise?: PromiseWithResolvers<void>;
+
+		#actor?: LoadedActor;
+
+		async #loadActor(): Promise<LoadedActor> {
+			// This is always called from another context using CF_AMBIENT_ENV
+
+			// Wait for init
+			if (!this.#initialized) {
+				// Wait for init
+				if (this.#initializedPromise) {
+					await this.#initializedPromise.promise;
+				} else {
+					this.#initializedPromise = Promise.withResolvers();
+					const res = await this.ctx.storage.get([
+						KEYS.NAME,
+						KEYS.KEY,
+						KEYS.PERSIST_DATA,
+					]);
+					if (res.get(KEYS.PERSIST_DATA)) {
+						const name = res.get(KEYS.NAME) as string;
+						if (!name) throw new Error("missing actor name");
+						const key = res.get(KEYS.KEY) as ActorKey;
+						if (!key) throw new Error("missing actor key");
+
+						logger().debug("already initialized", { name, key });
+
+						this.#initialized = { name, key };
+						this.#initializedPromise.resolve();
+					} else {
+						logger().debug("waiting to initialize");
+					}
+				}
+			}
+
+			// Check if already loaded
+			if (this.#actor) {
+				return this.#actor;
+			}
+
+			if (!this.#initialized) throw new Error("Not initialized");
+
+			// Configure actor driver
+			runConfig.driver.actor = new CloudflareActorsActorDriver(globalState);
+
+			const actorTopology = new PartitionTopologyActor(
+				registry.config,
+				runConfig,
+			);
+
+			// Register DO with global state
+			// HACK: This leaks the DO context, but DO does not provide a native way
+			// of knowing when the DO shuts down. We're making a broad assumption
+			// that DO will boot a new isolate frequenlty enough that this is not an issue.
+			const actorId = this.ctx.id.toString();
+			globalState.setDOState(actorId, { ctx: this.ctx, env: this.env });
+
+			// Save actor
+			this.#actor = {
+				actorTopology,
+			};
+
+			// Start actor
+			await actorTopology.start(
+				actorId,
+				this.#initialized.name,
+				this.#initialized.key,
+				// TODO:
+				"unknown",
+			);
+
+			return this.#actor;
+		}
+
+		/** RPC called by the service that creates the DO to initialize it. */
+		async initialize(req: ActorInitRequest) {
+			// TODO: Need to add this to a core promise that needs to be resolved before start
+
+			return await CF_AMBIENT_ENV.run(this.env, async () => {
+				await this.ctx.storage.put({
+					[KEYS.NAME]: req.name,
+					[KEYS.KEY]: req.key,
+					[KEYS.PERSIST_DATA]: serializeEmptyPersistData(req.input),
+				});
+				this.#initialized = {
+					name: req.name,
+					key: req.key,
+				};
+
+				logger().debug("initialized actor", { key: req.key });
+
+				// Preemptively actor so the lifecycle hooks are called
+				await this.#loadActor();
+			});
+		}
+
+		async fetch(request: Request): Promise<Response> {
+			return await CF_AMBIENT_ENV.run(this.env, async () => {
+				const { actorTopology } = await this.#loadActor();
+
+				const ctx = this.ctx;
+				return await actorTopology.router.fetch(
+					request,
+					this.env,
+					// Implement execution context so we can wait on requests
+					{
+						waitUntil(promise: Promise<unknown>) {
+							ctx.waitUntil(promise);
+						},
+						passThroughOnException() {
+							// Do nothing
+						},
+						props: {},
+					} satisfies ExecutionContext,
+				);
+			});
+		}
+
+		async alarm(): Promise<void> {
+			return await CF_AMBIENT_ENV.run(this.env, async () => {
+				const { actorTopology } = await this.#loadActor();
+				await actorTopology.actor.onAlarm();
+			});
+		}
+	};
+}

package/src/config.ts

@@ -0,0 +1,12 @@
+import { RunConfigSchema } from "@rivetkit/core/driver-helpers";
+import { Hono } from "hono";
+import { z } from "zod";
+
+export const ConfigSchema = RunConfigSchema.removeDefault()
+	.omit({ driver: true, getUpgradeWebSocket: true })
+	.extend({
+		app: z.custom<Hono>().optional(),
+	})
+	.default({});
+export type InputConfig = z.input<typeof ConfigSchema>;
+export type Config = z.infer<typeof ConfigSchema>;

package/src/handler.ts

@@ -0,0 +1,98 @@
+import {
+	type DurableObjectConstructor,
+	type ActorHandlerInterface,
+	createActorDurableObject,
+} from "./actor-handler-do";
+import { ConfigSchema, type Config, type InputConfig } from "./config";
+import { Hono } from "hono";
+import { PartitionTopologyManager } from "@rivetkit/core/topologies/partition";
+import type { Client } from "@rivetkit/core/client";
+import { CloudflareActorsManagerDriver } from "./manager-driver";
+import { DriverConfig, Registry, RunConfig } from "@rivetkit/core";
+import { upgradeWebSocket } from "./websocket";
+import invariant from "invariant";
+import { AsyncLocalStorage } from "node:async_hooks";
+
+/** Cloudflare Workers env */
+export interface Bindings {
+	ACTOR_KV: KVNamespace;
+	ACTOR_DO: DurableObjectNamespace<ActorHandlerInterface>;
+}
+
+/**
+ * Stores the env for the current request. Required since some contexts like the inline client driver does not have access to the Hono context.
+ *
+ * Use getCloudflareAmbientEnv unless using CF_AMBIENT_ENV.run.
+ */
+export const CF_AMBIENT_ENV = new AsyncLocalStorage<Bindings>();
+
+export function getCloudflareAmbientEnv(): Bindings {
+	const env = CF_AMBIENT_ENV.getStore();
+	invariant(env, "missing CF_AMBIENT_ENV");
+	return env;
+}
+
+interface Handler {
+	handler: ExportedHandler<Bindings>;
+	ActorHandler: DurableObjectConstructor;
+}
+
+interface SetupOutput<A extends Registry<any>> {
+	client: Client<A>;
+	createHandler: (hono?: Hono) => Handler;
+}
+
+export function createServerHandler<R extends Registry<any>>(
+	registry: R,
+	inputConfig?: InputConfig,
+): Handler {
+	const { createHandler } = createServer(registry, inputConfig);
+	return createHandler();
+}
+
+export function createServer<R extends Registry<any>>(
+	registry: R,
+	inputConfig?: InputConfig,
+): SetupOutput<R> {
+	const config = ConfigSchema.parse(inputConfig);
+
+	// Create config
+	const runConfig = {
+		driver: {
+			topology: "partition",
+			manager: new CloudflareActorsManagerDriver(),
+			// HACK: We can't build the actor driver until we're inside the Druable Object
+			actor: undefined as any,
+		},
+		getUpgradeWebSocket: () => upgradeWebSocket,
+		...config,
+	} satisfies RunConfig;
+
+	// Create Durable Object
+	const ActorHandler = createActorDurableObject(registry, runConfig);
+
+	const managerTopology = new PartitionTopologyManager(
+		registry.config,
+		runConfig,
+	);
+
+	return {
+		client: managerTopology.inlineClient as Client<R>,
+		createHandler: (hono) => {
+			// Build base router
+			const app = hono ?? new Hono();
+
+			// Mount registry
+			app.route("/registry", managerTopology.router);
+
+			// Create Cloudflare handler
+			const handler = {
+				fetch: (request, env, ctx) => {
+					return CF_AMBIENT_ENV.run(env, () => app.fetch(request, env, ctx));
+				},
+			} satisfies ExportedHandler<Bindings>;
+
+			return { handler, ActorHandler };
+		},
+	};
+}

package/src/log.ts

@@ -0,0 +1,7 @@
+import { getLogger } from "@rivetkit/core/log";
+
+export const LOGGER_NAME = "driver-cloudflare-workers";
+
+export function logger() {
+	return getLogger(LOGGER_NAME);
+}

package/src/manager-driver.ts

@@ -0,0 +1,335 @@
+import {
+	type ManagerDriver,
+	type GetForIdInput,
+	type GetWithKeyInput,
+	type ActorOutput,
+	type CreateInput,
+	type GetOrCreateWithKeyInput,
+	type ConnRoutingHandler,
+	HEADER_EXPOSE_INTERNAL_ERROR,
+	HEADER_ENCODING,
+	HEADER_CONN_PARAMS,
+	HEADER_AUTH_DATA,
+} from "@rivetkit/core/driver-helpers";
+import { ActorAlreadyExists, InternalError } from "@rivetkit/core/errors";
+import { Bindings } from "./mod";
+import { logger } from "./log";
+import { serializeNameAndKey, serializeKey } from "./util";
+import { getCloudflareAmbientEnv } from "./handler";
+import { Encoding } from "@rivetkit/core";
+
+// Actor metadata structure
+interface ActorData {
+	name: string;
+	key: string[];
+}
+
+// Key constants similar to Redis implementation
+const KEYS = {
+	ACTOR: {
+		// Combined key for actor metadata (name and key)
+		metadata: (actorId: string) => `actor:${actorId}:metadata`,
+
+		// Key index function for actor lookup
+		keyIndex: (name: string, key: string[] = []) => {
+			// Use serializeKey for consistent handling of all keys
+			return `actor_key:${serializeKey(key)}`;
+		},
+	},
+};
+
+const STANDARD_WEBSOCKET_HEADERS = [
+	"connection",
+	"upgrade",
+	"sec-websocket-key",
+	"sec-websocket-version",
+	"sec-websocket-protocol",
+	"sec-websocket-extensions",
+];
+
+export class CloudflareActorsManagerDriver implements ManagerDriver {
+	connRoutingHandler: ConnRoutingHandler;
+
+	constructor() {
+		this.connRoutingHandler = {
+			custom: {
+				sendRequest: async (actorId, actorRequest): Promise<Response> => {
+					const env = getCloudflareAmbientEnv();
+
+					logger().debug("sending request to durable object", {
+						actorId,
+						method: actorRequest.method,
+						url: actorRequest.url,
+					});
+
+					const id = env.ACTOR_DO.idFromString(actorId);
+					const stub = env.ACTOR_DO.get(id);
+
+					return await stub.fetch(actorRequest);
+				},
+
+				openWebSocket: async (
+					actorId,
+					encodingKind: Encoding,
+					params: unknown,
+				): Promise<WebSocket> => {
+					const env = getCloudflareAmbientEnv();
+
+					logger().debug("opening websocket to durable object", { actorId });
+
+					// Make a fetch request to the Durable Object with WebSocket upgrade
+					const id = env.ACTOR_DO.idFromString(actorId);
+					const stub = env.ACTOR_DO.get(id);
+
+					const headers: Record<string, string> = {
+						Upgrade: "websocket",
+						Connection: "Upgrade",
+						[HEADER_EXPOSE_INTERNAL_ERROR]: "true",
+						[HEADER_ENCODING]: encodingKind,
+					};
+					if (params) {
+						headers[HEADER_CONN_PARAMS] = JSON.stringify(params);
+					}
+					// HACK: See packages/platforms/cloudflare-workers/src/websocket.ts
+					headers["sec-websocket-protocol"] = "rivetkit";
+
+					const response = await stub.fetch("http://actor/connect/websocket", {
+						headers,
+					});
+					const webSocket = response.webSocket;
+
+					if (!webSocket) {
+						throw new InternalError(
+							"missing websocket connection in response from DO",
+						);
+					}
+
+					logger().debug("durable object websocket connection open", {
+						actorId,
+					});
+
+					webSocket.accept();
+
+					// TODO: Is this still needed?
+					// HACK: Cloudflare does not call onopen automatically, so we need
+					// to call this on the next tick
+					setTimeout(() => {
+						(webSocket as any).onopen?.(new Event("open"));
+					}, 0);
+
+					return webSocket as unknown as WebSocket;
+				},
+
+				proxyRequest: async (c, actorRequest, actorId): Promise<Response> => {
+					logger().debug("forwarding request to durable object", {
+						actorId,
+						method: actorRequest.method,
+						url: actorRequest.url,
+					});
+
+					const id = c.env.ACTOR_DO.idFromString(actorId);
+					const stub = c.env.ACTOR_DO.get(id);
+
+					return await stub.fetch(actorRequest);
+				},
+				proxyWebSocket: async (
+					c,
+					path,
+					actorId,
+					encoding,
+					params,
+					authData,
+				) => {
+					logger().debug("forwarding websocket to durable object", {
+						actorId,
+						path,
+					});
+
+					// Validate upgrade
+					const upgradeHeader = c.req.header("Upgrade");
+					if (!upgradeHeader || upgradeHeader !== "websocket") {
+						return new Response("Expected Upgrade: websocket", {
+							status: 426,
+						});
+					}
+
+					// TODO: strip headers
+					const newUrl = new URL(`http://actor${path}`);
+					const actorRequest = new Request(newUrl, c.req.raw);
+
+					// Always build fresh request to prevent forwarding unwanted headers
+					// HACK: Since we can't build a new request, we need to remove
+					// non-standard headers manually
+					const headerKeys: string[] = [];
+					actorRequest.headers.forEach((v, k) => headerKeys.push(k));
+					for (const k of headerKeys) {
+						if (!STANDARD_WEBSOCKET_HEADERS.includes(k)) {
+							actorRequest.headers.delete(k);
+						}
+					}
+
+					// Add RivetKit headers
+					actorRequest.headers.set(HEADER_EXPOSE_INTERNAL_ERROR, "true");
+					actorRequest.headers.set(HEADER_ENCODING, encoding);
+					if (params) {
+						actorRequest.headers.set(
+							HEADER_CONN_PARAMS,
+							JSON.stringify(params),
+						);
+					}
+					if (authData) {
+						actorRequest.headers.set(
+							HEADER_AUTH_DATA,
+							JSON.stringify(authData),
+						);
+					}
+
+					const id = c.env.ACTOR_DO.idFromString(actorId);
+					const stub = c.env.ACTOR_DO.get(id);
+
+					return await stub.fetch(actorRequest);
+				},
+			},
+		};
+	}
+
+	async getForId({
+		c,
+		actorId,
+	}: GetForIdInput<{ Bindings: Bindings }>): Promise<ActorOutput | undefined> {
+		const env = getCloudflareAmbientEnv();
+
+		// Get actor metadata from KV (combined name and key)
+		const actorData = (await env.ACTOR_KV.get(KEYS.ACTOR.metadata(actorId), {
+			type: "json",
+		})) as ActorData | null;
+
+		// If the actor doesn't exist, return undefined
+		if (!actorData) {
+			return undefined;
+		}
+
+		return {
+			actorId,
+			name: actorData.name,
+			key: actorData.key,
+		};
+	}
+
+	async getWithKey({
+		c,
+		name,
+		key,
+	}: GetWithKeyInput<{ Bindings: Bindings }>): Promise<
+		ActorOutput | undefined
+	> {
+		const env = getCloudflareAmbientEnv();
+
+		logger().debug("getWithKey: searching for actor", { name, key });
+
+		// Generate deterministic ID from the name and key
+		// This is aligned with how createActor generates IDs
+		const nameKeyString = serializeNameAndKey(name, key);
+		const actorId = env.ACTOR_DO.idFromName(nameKeyString).toString();
+
+		// Check if the actor metadata exists
+		const actorData = await env.ACTOR_KV.get(KEYS.ACTOR.metadata(actorId), {
+			type: "json",
+		});
+
+		if (!actorData) {
+			logger().debug("getWithKey: no actor found with matching name and key", {
+				name,
+				key,
+				actorId,
+			});
+			return undefined;
+		}
+
+		logger().debug("getWithKey: found actor with matching name and key", {
+			actorId,
+			name,
+			key,
+		});
+		return this.#buildActorOutput(c, actorId);
+	}
+
+	async getOrCreateWithKey(
+		input: GetOrCreateWithKeyInput,
+	): Promise<ActorOutput> {
+		// TODO: Prevent race condition here
+		const getOutput = await this.getWithKey(input);
+		if (getOutput) {
+			return getOutput;
+		} else {
+			return await this.createActor(input);
+		}
+	}
+
+	async createActor({
+		c,
+		name,
+		key,
+		input,
+	}: CreateInput<{ Bindings: Bindings }>): Promise<ActorOutput> {
+		const env = getCloudflareAmbientEnv();
+
+		// Check if actor with the same name and key already exists
+		const existingActor = await this.getWithKey({ c, name, key });
+		if (existingActor) {
+			throw new ActorAlreadyExists(name, key);
+		}
+
+		// Create a deterministic ID from the actor name and key
+		// This ensures that actors with the same name and key will have the same ID
+		const nameKeyString = serializeNameAndKey(name, key);
+		const doId = env.ACTOR_DO.idFromName(nameKeyString);
+		const actorId = doId.toString();
+
+		// Init actor
+		const actor = env.ACTOR_DO.get(doId);
+		await actor.initialize({
+			name,
+			key,
+			input,
+		});
+
+		// Store combined actor metadata (name and key)
+		const actorData: ActorData = { name, key };
+		await env.ACTOR_KV.put(
+			KEYS.ACTOR.metadata(actorId),
+			JSON.stringify(actorData),
+		);
+
+		// Add to key index for lookups by name and key
+		await env.ACTOR_KV.put(KEYS.ACTOR.keyIndex(name, key), actorId);
+
+		return {
+			actorId,
+			name,
+			key,
+		};
+	}
+
+	// Helper method to build actor output from an ID
+	async #buildActorOutput(
+		c: any,
+		actorId: string,
+	): Promise<ActorOutput | undefined> {
+		const env = getCloudflareAmbientEnv();
+
+		const actorData = (await env.ACTOR_KV.get(KEYS.ACTOR.metadata(actorId), {
+			type: "json",
+		})) as ActorData | null;
+
+		if (!actorData) {
+			return undefined;
+		}
+
+		return {
+			actorId,
+			name: actorData.name,
+			key: actorData.key,
+		};
+	}
+}

package/src/mod.ts

@@ -0,0 +1,2 @@
+export { type Bindings, createServer, createServerHandler } from "./handler";
+export type { InputConfig as Config } from "./config";