Remote Procedure Calls

Remote procedure calls (RPC) are how clients communicate with actors. RPCs are as simple as writing a method on the actor class and then calling it from the client.

Writing RPCs

RPCs can be written as native JavaScript methods on the actor class.

For example, the multiplyByTwo method is written as:

export class Example extends Actor {
	// This is an RPC
	multiplyByTwo(rpc: Rpc<Example>, x: number) {
		return x * 2;
	}
}

Private Methods

Methods starting with _ or # (e.g. _myMethod and #myMethod) are private and cannot be called by clients.

All Rivet-provided methods start with _ (e.g. _broadcast) so clients cannot call them.

For example:

export default class Example extends Actor {
	// This is private and cannot be called by clients
	#calcFibonacci(n: number): number {
		if (n <= 1) return n;
		return this.#calcFibonacci(n - 1) + this.#calcFibonacci(n - 2);
	}

	// This is public and can be called by clients
	fetchFibonacci(rpc: Rpc<Example>, n: number): number {
		return this.#calcFibonacci(n);
	}
}

Streaming Return Data

RPCs have a single return value. In order to stream realtime data in response to an RPC, use events.

Calling RPCs

Calling RPCs is as simple as calling any other JavaScript function.

import type { Counter } from "./counter.ts";

const actor = await client.get<Counter>({ name: "counter" });
await actor.increment(42);

Type Safety

The Rivet client includes type safety out of the box. The first generic parameter in get<Actor>(...) defines the actor class. You can safely import the actor's type with import type in to the client, like this:

import type { Counter } from "./counter.ts";
// ...setup...
const actor = await client.get<Counter>(/* ... */);
await actor.increment(123); // passes
await actor.increment("non-number type"); // compile error
await actor.nonexistentMethod(123); // compile error

Error Handling

Rivet provides robust error handling out of the box for RPCs.

User Errors

UserError error can be used to return rich error data to the client. You can provide:

• A human-readable message
• A machine-readable code that's useful for matching errors in a try-catch (optional)
• A metadata object for providing richer error context (optional)

For example:

// Throw a simple error with a message
throw new UserError("Invalid username");

// Throw an error with a code
throw new UserError("Invalid username", {
	code: "invalid_username",
});

// Throw an error with custom metadata
throw new UserError("Invalid username", {
	code: "invalid_username",
	meta: {
		maxLength: 32,
	},
});

Read the documentation for UserError here.

Internal Errors

All other errors will return an error with the code internal_error to the client. This helps keep your application secure, as errors can sometimes expose sensitive information.

Schema Validation

Data schemas are not validated by default. For production applications, use a library like zod to validate input types.

In the previous example, providing a non-number value to count could corrupt the actor's state (e.g. by passing a string instead of a number). For example, to validate the increment request schema:

import { z } from "zod";

// Define schemas for user requests
const IncrementOptionsSchema = z.object({
	count: z.number().int(),
});

type IncrementOptions = z.infer<typeof IncrementOptionsSchema>;

export class Counter extends Actor {
	increment(rpc: Rpc<Counter>, opts: IncrementOptions) {
		// Will throw error if input is invalid
		const validatedOpts = IncrementOptionsSchema.parse(opts);

		// ...etc...
	}
}

Authentication

By default, clients can call all RPCs on an actor without restriction. Make sure to implement authentication if needed. Documentation on authentication is available here.