refactor: rename all uses of "rpc" to "action" internally (#965)

Author: NathanFlurry

packages/actor-core/README.md

@@ -12,77 +12,6 @@ Supports Rivet, Cloudflare Workers, Bun, and Node.js.
 - [Documentation](https://actorcore.org/)
 - [Examples](https://github.com/rivet-gg/actor-core/tree/main/examples)
 
-## Getting Started
-
-### Step 1: Installation
-
-```bash
-# npm
-npm add actor-core
-
-# pnpm
-pnpm add actor-core
-
-# Yarn
-yarn add actor-core
-
-# Bun
-bun add actor-core
-```
-
-### Step 2: Create an Actor
-
-```typescript
-import { Actor, type Rpc } from "actor-core";
-
-export interface State {
-    messages: { username: string; message: string }[];
-}
-
-export default class ChatRoom extends Actor<State> {
-    // initialize this._state
-    _onInitialize() {
-        return { messages: [] };
-    }
-
-    // receive an remote procedure call from the client
-    sendMessage(rpc: Rpc<ChatRoom>, username: string, message: string) {
-        // save message to persistent storage
-        this._state.messages.push({ username, message });
-
-        // broadcast message to all clients
-        this._broadcast("newMessage", username, message);
-    }
-}
-```
-
-### Step 3: Connect to Actor
-
-```typescript
-import { Client } from "actor-core/client";
-import type ChatRoom from "../src/chat-room.ts";
-
-const client = new Client(/* manager endpoint */);
-
-// connect to chat room
-const chatRoom = await client.get<ChatRoom>({ name: "chat" });
-
-// listen for new messages
-chatRoom.on("newMessage", (username: string, message: string) =>
-    console.log(`Message from ${username}: ${message}`),
-);
-
-// send message to room
-await chatRoom.sendMessage("william", "All the world's a stage.");
-```
-
-### Step 4: Deploy
-
-Deploy to your platform of choice:
-
-- [Cloudflare Workers](https://actorcore.org/platforms/cloudflare-workers)
-- [Rivet](https://actorcore.org/platforms/rivet)
-
 ## Community & Support
 
 - Join our [Discord](https://rivet.gg/discord)

packages/actor-core/package.json

@@ -106,16 +106,6 @@
         "default": "./dist/cli/mod.cjs"
       }
     },
-    "./protocol/http": {
-      "import": {
-        "types": "./dist/actor/protocol/http/rpc.d.ts",
-        "default": "./dist/actor/protocol/http/rpc.js"
-      },
-      "require": {
-        "types": "./dist/actor/protocol/http/rpc.d.cts",
-        "default": "./dist/actor/protocol/http/rpc.cjs"
-      }
-    },
     "./test": {
       "import": {
         "types": "./dist/test/mod.d.ts",
@@ -163,7 +153,7 @@
   "sideEffects": false,
   "scripts": {
     "dev": "yarn build --watch",
-    "build": "tsup src/mod.ts src/client/mod.ts src/common/log.ts src/actor/errors.ts src/topologies/coordinate/mod.ts src/topologies/partition/mod.ts src/utils.ts src/driver-helpers/mod.ts src/driver-test-suite/mod.ts src/cli/mod.ts src/actor/protocol/inspector/mod.ts src/actor/protocol/http/rpc.ts src/test/mod.ts src/inspector/protocol/actor/mod.ts src/inspector/protocol/manager/mod.ts src/inspector/mod.ts",
+    "build": "tsup src/mod.ts src/client/mod.ts src/common/log.ts src/actor/errors.ts src/topologies/coordinate/mod.ts src/topologies/partition/mod.ts src/utils.ts src/driver-helpers/mod.ts src/driver-test-suite/mod.ts src/cli/mod.ts src/actor/protocol/inspector/mod.ts src/test/mod.ts src/inspector/protocol/actor/mod.ts src/inspector/protocol/manager/mod.ts src/inspector/mod.ts",
     "check-types": "tsc --noEmit",
     "boop": "tsc --outDir dist/test -d",
     "test": "vitest run",

packages/actor-core/src/actor/errors.ts

@@ -272,9 +272,9 @@ export class ProxyError extends ActorError {
 	}
 }
 
-export class InvalidRpcRequest extends ActorError {
+export class InvalidActionRequest extends ActorError {
 	constructor(message: string) {
-		super("invalid_rpc_request", message, { public: true });
+		super("invalid_action_request", message, { public: true });
 	}
 }
 

packages/actor-core/src/actor/instance.ts

@@ -458,7 +458,7 @@ export class ActorInstance<S, CP, CS, V> {
 					}
 				}
 
-				// State will be flushed at the end of the RPC
+				// State will be flushed at the end of the action
 			},
 			{ ignoreDetached: true },
 		);
@@ -734,8 +734,8 @@ export class ActorInstance<S, CP, CS, V> {
 	// MARK: Messages
 	async processMessage(message: wsToServer.ToServer, conn: Conn<S, CP, CS, V>) {
 		await processMessage(message, this, conn, {
-			onExecuteRpc: async (ctx, name, args) => {
-				return await this.executeRpc(ctx, name, args);
+			onExecuteAction: async (ctx, name, args) => {
+				return await this.executeAction(ctx, name, args);
 			},
 			onSubscribe: async (eventName, conn) => {
 				this.#addSubscription(eventName, conn, false);
@@ -820,98 +820,98 @@ export class ActorInstance<S, CP, CS, V> {
 	}
 
 	/**
-	 * Execute an RPC call from a client.
+	 * Execute an action call from a client.
 	 *
 	 * This method handles:
-	 * 1. Validating the RPC name
-	 * 2. Executing the RPC function
-	 * 3. Processing the result through onBeforeRpcResponse (if configured)
+	 * 1. Validating the action name
+	 * 2. Executing the action function
+	 * 3. Processing the result through onBeforeActionResponse (if configured)
 	 * 4. Handling timeouts and errors
 	 * 5. Saving state changes
 	 *
-	 * @param ctx The RPC context
-	 * @param rpcName The name of the RPC being called
-	 * @param args The arguments passed to the RPC
-	 * @returns The result of the RPC call
-	 * @throws {RpcNotFound} If the RPC doesn't exist
-	 * @throws {RpcTimedOut} If the RPC times out
+	 * @param ctx The action context
+	 * @param actionName The name of the action being called
+	 * @param args The arguments passed to the action
+	 * @returns The result of the action call
+	 * @throws {ActionNotFound} If the action doesn't exist
+	 * @throws {ActionTimedOut} If the action times out
 	 * @internal
 	 */
-	async executeRpc(
+	async executeAction(
 		ctx: ActionContext<S, CP, CS, V>,
-		rpcName: string,
+		actionName: string,
 		args: unknown[],
 	): Promise<unknown> {
-		invariant(this.#ready, "exucuting rpc before ready");
+		invariant(this.#ready, "exucuting action before ready");
 
 		// Prevent calling private or reserved methods
-		if (!(rpcName in this.#config.actions)) {
-			logger().warn("rpc does not exist", { rpcName });
+		if (!(actionName in this.#config.actions)) {
+			logger().warn("action does not exist", {  actionName });
 			throw new errors.ActionNotFound();
 		}
 
 		// Check if the method exists on this object
-		// biome-ignore lint/suspicious/noExplicitAny: RPC name is dynamic from client
-		const rpcFunction = this.#config.actions[rpcName];
-		if (typeof rpcFunction !== "function") {
-			logger().warn("action not found", { actionName: rpcName });
+		// biome-ignore lint/suspicious/noExplicitAny: action name is dynamic from client
+		const actionFunction = this.#config.actions[actionName];
+		if (typeof actionFunction !== "function") {
+			logger().warn("action not found", { actionName: actionName });
 			throw new errors.ActionNotFound();
 		}
 
-		// TODO: pass abortable to the rpc to decide when to abort
+		// TODO: pass abortable to the action to decide when to abort
 		// TODO: Manually call abortable for better error handling
 		// Call the function on this object with those arguments
 		try {
 			// Log when we start executing the action
-			logger().debug("executing action", { actionName: rpcName, args });
+			logger().debug("executing action", { actionName: actionName, args });
 
-			const outputOrPromise = rpcFunction.call(undefined, ctx, ...args);
+			const outputOrPromise = actionFunction.call(undefined, ctx, ...args);
 			let output: unknown;
 			if (outputOrPromise instanceof Promise) {
 				// Log that we're waiting for an async action
-				logger().debug("awaiting async action", { actionName: rpcName });
+				logger().debug("awaiting async action", { actionName: actionName });
 
 				output = await deadline(
 					outputOrPromise,
 					this.#config.options.action.timeout,
 				);
 
 				// Log that async action completed
-				logger().debug("async action completed", { actionName: rpcName });
+				logger().debug("async action completed", { actionName: actionName });
 			} else {
 				output = outputOrPromise;
 			}
 
-			// Process the output through onBeforeRpcResponse if configured
+			// Process the output through onBeforeActionResponse if configured
 			if (this.#config.onBeforeActionResponse) {
 				try {
 					const processedOutput = this.#config.onBeforeActionResponse(
 						this.actorContext,
-						rpcName,
+						actionName,
 						args,
 						output,
 					);
 					if (processedOutput instanceof Promise) {
 						logger().debug("awaiting onBeforeActionResponse", {
-							actionName: rpcName,
+							actionName: actionName,
 						});
 						output = await processedOutput;
 						logger().debug("onBeforeActionResponse completed", {
-							actionName: rpcName,
+							actionName: actionName,
 						});
 					} else {
 						output = processedOutput;
 					}
 				} catch (error) {
-					logger().error("error in `onBeforeRpcResponse`", {
+					logger().error("error in `onBeforeActionResponse`", {
 						error: stringifyError(error),
 					});
 				}
 			}
 
 			// Log the output before returning
 			logger().debug("action completed", {
-				actionName: rpcName,
+				actionName: actionName,
 				outputType: typeof output,
 				isPromise: output instanceof Promise,
 			});
@@ -922,7 +922,7 @@ export class ActorInstance<S, CP, CS, V> {
 				throw new errors.ActionTimedOut();
 			}
 			logger().error("action error", {
-				actionName: rpcName,
+				actionName: actionName,
 				error: stringifyError(error),
 			});
 			throw error;
@@ -932,9 +932,9 @@ export class ActorInstance<S, CP, CS, V> {
 	}
 
 	/**
-	 * Returns a list of RPC methods available on this actor.
+	 * Returns a list of action methods available on this actor.
 	 */
-	get rpcs(): string[] {
+	get actions(): string[] {
 		return Object.keys(this.#config.actions);
 	}
 
@@ -1040,7 +1040,7 @@ export class ActorInstance<S, CP, CS, V> {
 	 * Runs a promise in the background.
 	 *
 	 * This allows the actor runtime to ensure that a promise completes while
-	 * returning from an RPC request early.
+	 * returning from an action request early.
 	 *
 	 * @param promise - The promise to run in the background.
 	 */

packages/actor-core/src/actor/protocol/http/action.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+
+export const ActionRequestSchema = z.object({
+	// Args
+	a: z.array(z.unknown()),
+});
+
+export const ActionResponseSchema = z.object({
+	// Output
+	o: z.unknown(),
+});
+
+
+export type ActionRequest = z.infer<typeof ActionRequestSchema>;
+export type ActionResponse = z.infer<typeof ActionResponseSchema>;