chore(rivetkit): add listing actors by only name to manager api

Author: NathanFlurry

rivetkit-typescript/packages/cloudflare-workers/src/manager-driver.ts

@@ -7,6 +7,7 @@ import {
 	type GetOrCreateWithKeyInput,
 	type GetWithKeyInput,
 	generateRandomString,
+	type ListActorsInput,
 	type ManagerDisplayInformation,
 	type ManagerDriver,
 	WS_PROTOCOL_ACTOR,
@@ -348,6 +349,14 @@ export class CloudflareActorsManagerDriver implements ManagerDriver {
 		};
 	}
 
+	async listActors({ c, name }: ListActorsInput): Promise<ActorOutput[]> {
+		logger().warn({
+			msg: "listActors not fully implemented for Cloudflare Workers",
+			name,
+		});
+		return [];
+	}
+
 	// Helper method to build actor output from an ID
 	async #buildActorOutput(
 		c: any,

rivetkit-typescript/packages/rivetkit/scripts/dump-openapi.ts

@@ -32,6 +32,7 @@ function main() {
 		getWithKey: unimplemented,
 		getOrCreateWithKey: unimplemented,
 		createActor: unimplemented,
+		listActors: unimplemented,
 		sendRequest: unimplemented,
 		openWebSocket: unimplemented,
 		proxyRequest: unimplemented,

rivetkit-typescript/packages/rivetkit/src/driver-helpers/mod.ts

@@ -24,6 +24,7 @@ export type {
 	GetForIdInput,
 	GetOrCreateWithKeyInput,
 	GetWithKeyInput,
+	ListActorsInput,
 	ManagerDisplayInformation,
 	ManagerDriver,
 } from "@/manager/driver";

rivetkit-typescript/packages/rivetkit/src/driver-test-suite/test-inline-client-driver.ts

@@ -25,6 +25,7 @@ import {
 	type GetOrCreateWithKeyInput,
 	type GetWithKeyInput,
 	HEADER_ACTOR_ID,
+	type ListActorsInput,
 	type ManagerDisplayInformation,
 	type ManagerDriver,
 } from "@/driver-helpers/mod";
@@ -73,6 +74,9 @@ export function createTestInlineClientDriver(
 				input,
 			]);
 		},
+		listActors(input: ListActorsInput): Promise<ActorOutput[]> {
+			return makeInlineRequest(endpoint, encoding, "listActors", [input]);
+		},
 		async sendRequest(
 			actorId: string,
 			actorRequest: Request,

rivetkit-typescript/packages/rivetkit/src/drivers/file-system/manager.ts

@@ -17,6 +17,7 @@ import type {
 	GetForIdInput,
 	GetOrCreateWithKeyInput,
 	GetWithKeyInput,
+	ListActorsInput,
 	ManagerDriver,
 } from "@/driver-helpers/mod";
 import { ManagerInspector } from "@/inspector/manager";
@@ -333,6 +334,31 @@ export class FileSystemManagerDriver implements ManagerDriver {
 		};
 	}
 
+	async listActors({ name }: ListActorsInput): Promise<ActorOutput[]> {
+		const actors: ActorOutput[] = [];
+		const itr = this.#state.getActorsIterator({});
+
+		for await (const actor of itr) {
+			if (actor.name === name) {
+				actors.push({
+					actorId: actor.actorId,
+					name: actor.name,
+					key: actor.key as string[],
+					createTs: Number(actor.createdAt),
+				});
+			}
+		}
+
+		// Sort by create ts desc (most recent first)
+		actors.sort((a, b) => {
+			const aTs = a.createTs ?? 0;
+			const bTs = b.createTs ?? 0;
+			return bTs - aTs;
+		});
+
+		return actors;
+	}
+
 	displayInformation(): ManagerDisplayInformation {
 		return {
 			name: this.#state.persist ? "File System" : "Memory",

rivetkit-typescript/packages/rivetkit/src/manager/driver.ts

@@ -14,6 +14,7 @@ export interface ManagerDriver {
 	getWithKey(input: GetWithKeyInput): Promise<ActorOutput | undefined>;
 	getOrCreateWithKey(input: GetOrCreateWithKeyInput): Promise<ActorOutput>;
 	createActor(input: CreateInput): Promise<ActorOutput>;
+	listActors(input: ListActorsInput): Promise<ActorOutput[]>;
 
 	sendRequest(actorId: string, actorRequest: Request): Promise<Response>;
 	openWebSocket(
@@ -92,8 +93,16 @@ export interface CreateInput<E extends Env = any> {
 	region?: string;
 }
 
+export interface ListActorsInput<E extends Env = any> {
+	c?: HonoContext | undefined;
+	name: string;
+	key?: string;
+	includeDestroyed?: boolean;
+}
+
 export interface ActorOutput {
 	actorId: string;
 	name: string;
 	key: ActorKey;
+	createTs?: number;
 }

rivetkit-typescript/packages/rivetkit/src/manager/router.ts

@@ -289,17 +289,7 @@ function addManagerRoutes(
 			if (key && !name) {
 				return c.json(
 					{
-						error: "When providing 'key', 'name' must also be provided.",
-					},
-					400,
-				);
-			}
-
-			// Validate: must provide either actor_ids or (name + key)
-			if (!actorIdsParsed && !key) {
-				return c.json(
-					{
-						error: "Must provide either 'actor_ids' or both 'name' and 'key'.",
+						error: "Name is required when key is provided.",
 					},
 					400,
 				);
@@ -351,16 +341,33 @@ function addManagerRoutes(
 						}
 					}
 				}
-			} else if (key) {
-				// At this point, name is guaranteed to be defined due to validation above
+			} else if (key && name) {
 				const actorOutput = await managerDriver.getWithKey({
 					c,
-					name: name!,
+					name,
 					key: [key], // Convert string to ActorKey array
 				});
 				if (actorOutput) {
 					actors.push(actorOutput);
 				}
+			} else {
+				if (!name) {
+					return c.json(
+						{
+							error: "Name is required when not using actor_ids.",
+						},
+						400,
+					);
+				}
+
+				// List all actors with the given name
+				const actorOutputs = await managerDriver.listActors({
+					c,
+					name,
+					key,
+					includeDestroyed: false,
+				});
+				actors.push(...actorOutputs);
 			}
 
 			return c.json<ActorsListResponse>({
@@ -722,7 +729,7 @@ function createApiActor(
 		key: serializeActorKey(actor.key),
 		namespace_id: "default", // Assert default namespace
 		runner_name_selector: runnerName,
-		create_ts: Date.now(),
+		create_ts: actor.createTs ?? Date.now(),
 		connectable_ts: null,
 		destroy_ts: null,
 		sleep_ts: null,

rivetkit-typescript/packages/rivetkit/src/remote-manager-driver/api-endpoints.ts

@@ -25,7 +25,7 @@ export async function getActor(
 	);
 }
 
-// MARK: Get actor by id
+// MARK: Get actor by key
 export async function getActorByKey(
 	config: ClientConfig,
 	name: string,
@@ -39,6 +39,18 @@ export async function getActorByKey(
 	);
 }
 
+// MARK: List actors by name
+export async function listActorsByName(
+	config: ClientConfig,
+	name: string,
+): Promise<ActorsListResponse> {
+	return apiCall<never, ActorsListResponse>(
+		config,
+		"GET",
+		`/actors?name=${encodeURIComponent(name)}`,
+	);
+}
+
 // MARK: Get or create actor by id
 export async function getOrCreateActor(
 	config: ClientConfig,

rivetkit-typescript/packages/rivetkit/src/remote-manager-driver/mod.ts

@@ -12,6 +12,7 @@ import type {
 	GetForIdInput,
 	GetOrCreateWithKeyInput,
 	GetWithKeyInput,
+	ListActorsInput,
 	ManagerDisplayInformation,
 	ManagerDriver,
 } from "@/driver-helpers/mod";
@@ -30,6 +31,7 @@ import {
 	getActorByKey,
 	getMetadata,
 	getOrCreateActor,
+	listActorsByName,
 } from "./api-endpoints";
 import { EngineApiError, getEndpoint } from "./api-utils";
 import { logger } from "./log";
@@ -255,6 +257,24 @@ export class RemoteManagerDriver implements ManagerDriver {
 		};
 	}
 
+	async listActors({ c, name }: ListActorsInput): Promise<ActorOutput[]> {
+		// Wait for metadata check to complete if in progress
+		if (this.#metadataPromise) {
+			await this.#metadataPromise;
+		}
+
+		logger().debug({ msg: "listing actors via engine api", name });
+
+		const response = await listActorsByName(this.#config, name);
+
+		return response.actors.map((actor) => ({
+			actorId: actor.actor_id,
+			name: actor.name,
+			key: deserializeActorKey(actor.key),
+			createTs: actor.create_ts,
+		}));
+	}
+
 	async destroyActor(actorId: string): Promise<void> {
 		// Wait for metadata check to complete if in progress
 		if (this.#metadataPromise) {