rivetkit 2.0.3 → 2.0.5

package/src/client/actor-query.ts

@@ -0,0 +1,65 @@
+import type { Context as HonoContext } from "hono";
+import * as errors from "@/actor/errors";
+import type { ManagerDriver } from "@/driver-helpers/mod";
+import type { ActorQuery } from "@/manager/protocol/query";
+import { logger } from "./log";
+
+/**
+ * Query the manager driver to get or create a actor based on the provided query
+ */
+export async function queryActor(
+	c: HonoContext | undefined,
+	query: ActorQuery,
+	managerDriver: ManagerDriver,
+): Promise<{ actorId: string }> {
+	logger().debug({ msg: "querying actor", query: JSON.stringify(query) });
+	let actorOutput: { actorId: string };
+	if ("getForId" in query) {
+		const output = await managerDriver.getForId({
+			c,
+			name: query.getForId.name,
+			actorId: query.getForId.actorId,
+		});
+		if (!output) throw new errors.ActorNotFound(query.getForId.actorId);
+		actorOutput = output;
+	} else if ("getForKey" in query) {
+		const existingActor = await managerDriver.getWithKey({
+			c,
+			name: query.getForKey.name,
+			key: query.getForKey.key,
+		});
+		if (!existingActor) {
+			throw new errors.ActorNotFound(
+				`${query.getForKey.name}:${JSON.stringify(query.getForKey.key)}`,
+			);
+		}
+		actorOutput = existingActor;
+	} else if ("getOrCreateForKey" in query) {
+		const getOrCreateOutput = await managerDriver.getOrCreateWithKey({
+			c,
+			name: query.getOrCreateForKey.name,
+			key: query.getOrCreateForKey.key,
+			input: query.getOrCreateForKey.input,
+			region: query.getOrCreateForKey.region,
+		});
+		actorOutput = {
+			actorId: getOrCreateOutput.actorId,
+		};
+	} else if ("create" in query) {
+		const createOutput = await managerDriver.createActor({
+			c,
+			name: query.create.name,
+			key: query.create.key,
+			input: query.create.input,
+			region: query.create.region,
+		});
+		actorOutput = {
+			actorId: createOutput.actorId,
+		};
+	} else {
+		throw new errors.InvalidRequest("Invalid query format");
+	}
+
+	logger().debug({ msg: "actor query result", actorId: actorOutput.actorId });
+	return { actorId: actorOutput.actorId };
+}

package/src/client/client.ts

@@ -1,12 +1,9 @@
-import type { Context as HonoContext } from "hono";
-import type { WebSocket } from "ws";
 import type { AnyActorDefinition } from "@/actor/definition";
 import type { Transport } from "@/actor/protocol/old";
 import type { Encoding } from "@/actor/protocol/serde";
-import type { UniversalEventSource } from "@/common/eventsource-interface";
+import type { ManagerDriver } from "@/driver-helpers/mod";
 import type { ActorQuery } from "@/manager/protocol/query";
 import type { Registry } from "@/mod";
-import type { ToServer } from "@/schemas/client-protocol/mod";
 import type { ActorActionFunction } from "./actor-common";
 import {
 	type ActorConn,
@@ -14,8 +11,12 @@ import {
 	CONNECT_SYMBOL,
 } from "./actor-conn";
 import { type ActorHandle, ActorHandleRaw } from "./actor-handle";
+import { queryActor } from "./actor-query";
+import type { ClientConfig } from "./config";
 import { logger } from "./log";
 
+export type { ClientConfig, ClientConfigInput } from "./config";
+
 /** Extract the actor registry from the registry definition. */
 export type ExtractActorsFromRegistry<A extends Registry<any>> =
 	A extends Registry<infer Actors> ? Actors : never;
@@ -78,15 +79,6 @@ export interface ActorAccessor<AD extends AnyActorDefinition> {
 	): Promise<ActorHandle<AD>>;
 }
 
-/**
- * Options for configuring the client.
- * @typedef {Object} ClientOptions
- */
-export interface ClientOptions {
-	encoding?: Encoding;
-	transport?: Transport;
-}
-
 /**
  * Options for querying actors.
  * @typedef {Object} QueryOptions
@@ -140,8 +132,8 @@ export interface CreateOptions extends QueryOptions {
  * @typedef {Object} Region
  * @property {string} id - The region ID.
  * @property {string} name - The region name.
- * @see {@link https://rivet.gg/docs/edge|Edge Networking}
- * @see {@link https://rivet.gg/docs/regions|Available Regions}
+ * @see {@link https://rivet.dev/docs/edge|Edge Networking}
+ * @see {@link https://rivet.dev/docs/regions|Available Regions}
  */
 export interface Region {
 	/**
@@ -159,89 +151,29 @@ export const ACTOR_CONNS_SYMBOL = Symbol("actorConns");
 export const CREATE_ACTOR_CONN_PROXY = Symbol("createActorConnProxy");
 export const TRANSPORT_SYMBOL = Symbol("transport");
 
-export interface ClientDriver {
-	action<Args extends Array<unknown> = unknown[], Response = unknown>(
-		c: HonoContext | undefined,
-		actorQuery: ActorQuery,
-		encoding: Encoding,
-		params: unknown,
-		name: string,
-		args: Args,
-		opts: { signal?: AbortSignal } | undefined,
-	): Promise<Response>;
-	resolveActorId(
-		c: HonoContext | undefined,
-		actorQuery: ActorQuery,
-		encodingKind: Encoding,
-		params: unknown,
-		opts: { signal?: AbortSignal } | undefined,
-	): Promise<string>;
-	connectWebSocket(
-		c: HonoContext | undefined,
-		actorQuery: ActorQuery,
-		encodingKind: Encoding,
-		params: unknown,
-		opts: { signal?: AbortSignal } | undefined,
-	): Promise<WebSocket>;
-	connectSse(
-		c: HonoContext | undefined,
-		actorQuery: ActorQuery,
-		encodingKind: Encoding,
-		params: unknown,
-		opts: { signal?: AbortSignal } | undefined,
-	): Promise<UniversalEventSource>;
-	sendHttpMessage(
-		c: HonoContext | undefined,
-		actorId: string,
-		encoding: Encoding,
-		connectionId: string,
-		connectionToken: string,
-		message: ToServer,
-		opts: { signal?: AbortSignal } | undefined,
-	): Promise<void>;
-	rawHttpRequest(
-		c: HonoContext | undefined,
-		actorQuery: ActorQuery,
-		encoding: Encoding,
-		params: unknown,
-		path: string,
-		init: RequestInit,
-		opts: { signal?: AbortSignal } | undefined,
-	): Promise<Response>;
-	rawWebSocket(
-		c: HonoContext | undefined,
-		actorQuery: ActorQuery,
-		encoding: Encoding,
-		params: unknown,
-		path: string,
-		protocols: string | string[] | undefined,
-		opts: { signal?: AbortSignal } | undefined,
-	): Promise<WebSocket>;
-}
-
 /**
  * Client for managing & connecting to actors.
  *
  * @template A The actors map type that defines the available actors.
- * @see {@link https://rivet.gg/docs/manage|Create & Manage Actors}
+ * @see {@link https://rivet.dev/docs/manage|Create & Manage Actors}
  */
 export class ClientRaw {
 	#disposed = false;
 
 	[ACTOR_CONNS_SYMBOL] = new Set<ActorConnRaw>();
 
-	#driver: ClientDriver;
+	#driver: ManagerDriver;
 	#encodingKind: Encoding;
 	[TRANSPORT_SYMBOL]: Transport;
 
 	/**
 	 * Creates an instance of Client.
 	 *
-	 * @param {string} managerEndpoint - The manager endpoint. See {@link https://rivet.gg/docs/setup|Initial Setup} for instructions on getting the manager endpoint.
-	 * @param {ClientOptions} [opts] - Options for configuring the client.
-	 * @see {@link https://rivet.gg/docs/setup|Initial Setup}
+	 * @param {string} managerEndpoint - The manager endpoint. See {@link https://rivet.dev/docs/setup|Initial Setup} for instructions on getting the manager endpoint.
+	 * @param {ClientConfig} [opts] - Options for configuring the client.
+	 * @see {@link https://rivet.dev/docs/setup|Initial Setup}
 	 */
-	public constructor(driver: ClientDriver, opts?: ClientOptions) {
+	public constructor(driver: ManagerDriver, opts?: ClientConfig) {
 		this.#driver = driver;
 
 		this.#encodingKind = opts?.encoding ?? "bare";
@@ -262,7 +194,8 @@ export class ClientRaw {
 		actorId: string,
 		opts?: GetWithIdOptions,
 	): ActorHandle<AD> {
-		logger().debug("get handle to actor with id", {
+		logger().debug({
+			msg: "get handle to actor with id",
 			name,
 			actorId,
 			params: opts?.params,
@@ -296,7 +229,8 @@ export class ClientRaw {
 		// Convert string to array of strings
 		const keyArray: string[] = typeof key === "string" ? [key] : key || [];
 
-		logger().debug("get handle to actor", {
+		logger().debug({
+			msg: "get handle to actor",
 			name,
 			key: keyArray,
 			parameters: opts?.params,
@@ -330,7 +264,8 @@ export class ClientRaw {
 		// Convert string to array of strings
 		const keyArray: string[] = typeof key === "string" ? [key] : key || [];
 
-		logger().debug("get or create handle to actor", {
+		logger().debug({
+			msg: "get or create handle to actor",
 			name,
 			key: keyArray,
 			parameters: opts?.params,
@@ -377,7 +312,8 @@ export class ClientRaw {
 			},
 		} satisfies ActorQuery;
 
-		logger().debug("create actor handle", {
+		logger().debug({
+			msg: "create actor handle",
 			name,
 			key: keyArray,
 			parameters: opts?.params,
@@ -385,14 +321,9 @@ export class ClientRaw {
 		});
 
 		// Create the actor
-		const actorId = await this.#driver.resolveActorId(
-			undefined,
-			createQuery,
-			this.#encodingKind,
-			opts?.params,
-			opts?.signal ? { signal: opts.signal } : undefined,
-		);
-		logger().debug("created actor with ID", {
+		const { actorId } = await queryActor(undefined, createQuery, this.#driver);
+		logger().debug({
+			msg: "created actor with ID",
 			name,
 			key: keyArray,
 			actorId,
@@ -441,12 +372,12 @@ export class ClientRaw {
 	 */
 	async dispose(): Promise<void> {
 		if (this.#disposed) {
-			logger().warn("client already disconnected");
+			logger().warn({ msg: "client already disconnected" });
 			return;
 		}
 		this.#disposed = true;
 
-		logger().debug("disposing client");
+		logger().debug({ msg: "disposing client" });
 
 		const disposePromises = [];
 
@@ -474,10 +405,10 @@ export type Client<A extends Registry<any>> = ClientRaw & {
 export type AnyClient = Client<Registry<any>>;
 
 export function createClientWithDriver<A extends Registry<any>>(
-	driver: ClientDriver,
-	opts?: ClientOptions,
+	driver: ManagerDriver,
+	config?: ClientConfig,
 ): Client<A> {
-	const client = new ClientRaw(driver, opts);
+	const client = new ClientRaw(driver, config);
 
 	// Create proxy for accessing actors by name
 	return new Proxy(client, {

package/src/client/config.ts

@@ -0,0 +1,44 @@
+import z from "zod";
+import { TransportSchema } from "@/actor/protocol/old";
+import { EncodingSchema } from "@/actor/protocol/serde";
+import { getEnvUniversal, type UpgradeWebSocket } from "@/utils";
+
+export type GetUpgradeWebSocket = () => UpgradeWebSocket;
+
+export const ClientConfigSchema = z.object({
+	/** Configure serving the API */
+	api: z
+		.object({
+			host: z.string().default("127.0.0.1"),
+			port: z.number().default(6420),
+		})
+		.default({}),
+
+	/** Endpoint to connect to the Rivet engine. Can be configured via RIVET_ENGINE env var. */
+	endpoint: z
+		.string()
+		.nullable()
+		.default(() => getEnvUniversal("RIVET_ENGINE") ?? null),
+
+	namespace: z
+		.string()
+		.default(() => getEnvUniversal("RIVET_NAMESPACE") ?? "default"),
+
+	runnerName: z
+		.string()
+		.default(() => getEnvUniversal("RIVET_RUNNER") ?? "rivetkit"),
+
+	encoding: EncodingSchema.default("bare"),
+
+	transport: TransportSchema.default("websocket"),
+
+	// This is a function to allow for lazy configuration of upgradeWebSocket on the
+	// fly. This is required since the dependencies that upgradeWebSocket
+	// (specifically Node.js) can sometimes only be specified after the router is
+	// created or must be imported async using `await import(...)`
+	getUpgradeWebSocket: z.custom<GetUpgradeWebSocket>().optional(),
+});
+
+export type ClientConfig = z.infer<typeof ClientConfigSchema>;
+
+export type ClientConfigInput = z.input<typeof ClientConfigSchema>;

package/src/client/errors.ts

@@ -20,6 +20,7 @@ export class ActorError extends ActorClientError {
 	__type = "ActorError";
 
 	constructor(
+		public readonly group: string,
 		public readonly code: string,
 		message: string,
 		public readonly metadata?: unknown,

package/src/client/log.ts

@@ -1,7 +1,5 @@
-import { getLogger } from "@/common//log";
-
-export const LOGGER_NAME = "actor-client";
+import { getLogger } from "@/common/log";
 
 export function logger() {
-	return getLogger(LOGGER_NAME);
+	return getLogger("actor-client");
 }

package/src/client/mod.ts

@@ -1,10 +1,11 @@
 import type { Registry } from "@/registry/mod";
+import { RemoteManagerDriver } from "@/remote-manager-driver/mod";
 import {
 	type Client,
-	type ClientOptions,
+	type ClientConfigInput,
 	createClientWithDriver,
 } from "./client";
-import { createHttpClientDriver } from "./http-client-driver";
+import { ClientConfigSchema } from "./config";
 
 export {
 	ActorDefinition,
@@ -28,7 +29,6 @@ export { ActorHandleRaw } from "./actor-handle";
 export type {
 	ActorAccessor,
 	Client,
-	ClientOptions,
 	ClientRaw,
 	CreateOptions,
 	ExtractActorsFromRegistry,
@@ -41,16 +41,20 @@ export type {
 
 /**
  * Creates a client with the actor accessor proxy.
- *
- * @template A The actor application type.
- * @param {string} managerEndpoint - The manager endpoint.
- * @param {ClientOptions} [opts] - Options for configuring the client.
- * @returns {Client<A>} - A proxied client that supports the `client.myActor.connect()` syntax.
  */
 export function createClient<A extends Registry<any>>(
-	endpoint: string,
-	opts?: ClientOptions,
+	endpointOrConfig?: string | ClientConfigInput,
 ): Client<A> {
-	const driver = createHttpClientDriver(endpoint);
-	return createClientWithDriver<A>(driver, opts);
+	// Parse config
+	const configInput =
+		endpointOrConfig === undefined
+			? {}
+			: typeof endpointOrConfig === "string"
+				? { endpoint: endpointOrConfig }
+				: endpointOrConfig;
+	const config = ClientConfigSchema.parse(configInput);
+
+	// Create client
+	const driver = new RemoteManagerDriver(config);
+	return createClientWithDriver<A>(driver, config);
 }

package/src/client/raw-utils.ts

@@ -1,11 +1,17 @@
+import invariant from "invariant";
+import { PATH_RAW_WEBSOCKET_PREFIX } from "@/actor/router";
+import { deconstructError } from "@/common/utils";
+import { HEADER_CONN_PARAMS, type ManagerDriver } from "@/driver-helpers/mod";
 import type { ActorQuery } from "@/manager/protocol/query";
-import type { ClientDriver } from "./client";
+import { queryActor } from "./actor-query";
+import { ActorError } from "./errors";
+import { logger } from "./log";
 
 /**
  * Shared implementation for raw HTTP fetch requests
  */
 export async function rawHttpFetch(
-	driver: ClientDriver,
+	driver: ManagerDriver,
 	actorQuery: ActorQuery,
 	params: unknown,
 	input: string | URL | Request,
@@ -55,38 +61,89 @@ export async function rawHttpFetch(
 		throw new TypeError("Invalid input type for fetch");
 	}
 
-	// Use the driver's raw HTTP method - just pass the sub-path
-	return await driver.rawHttpRequest(
-		undefined,
-		actorQuery,
-		// Force JSON so it's readable by the user
-		"json",
-		params,
-		path,
-		mergedInit,
-		undefined,
-	);
+	try {
+		// Get the actor ID
+		const { actorId } = await queryActor(undefined, actorQuery, driver);
+		logger().debug({ msg: "found actor for raw http", actorId });
+		invariant(actorId, "Missing actor ID");
+
+		// Build the URL with normalized path
+		const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
+		const url = new URL(`http://actor/raw/http/${normalizedPath}`);
+
+		// Forward conn params if provided
+		const proxyRequestHeaders = new Headers(mergedInit.headers);
+		if (params) {
+			proxyRequestHeaders.set(HEADER_CONN_PARAMS, JSON.stringify(params));
+		}
+
+		// Forward the request to the actor
+		const proxyRequest = new Request(url, {
+			...mergedInit,
+			headers: proxyRequestHeaders,
+		});
+
+		return driver.sendRequest(actorId, proxyRequest);
+	} catch (err) {
+		// Standardize to ClientActorError instead of the native backend error
+		const { group, code, message, metadata } = deconstructError(
+			err,
+			logger(),
+			{},
+			true,
+		);
+		throw new ActorError(group, code, message, metadata);
+	}
 }
 
 /**
  * Shared implementation for raw WebSocket connections
  */
 export async function rawWebSocket(
-	driver: ClientDriver,
+	driver: ManagerDriver,
 	actorQuery: ActorQuery,
 	params: unknown,
 	path?: string,
+	// TODO: Supportp rotocols
 	protocols?: string | string[],
 ): Promise<any> {
-	// Use the driver's raw WebSocket method
-	return await driver.rawWebSocket(
-		undefined,
-		actorQuery,
-		// Force JSON so it's readable by the user
-		"json",
-		params,
-		path || "",
-		protocols,
-		undefined,
-	);
+	// TODO: Do we need encoding in rawWebSocket?
+	const encoding = "bare";
+
+	// Get the actor ID
+	const { actorId } = await queryActor(undefined, actorQuery, driver);
+	logger().debug({ msg: "found actor for action", actorId });
+	invariant(actorId, "Missing actor ID");
+
+	// Parse path and query parameters
+	let pathPortion = "";
+	let queryPortion = "";
+	if (path) {
+		const queryIndex = path.indexOf("?");
+		if (queryIndex !== -1) {
+			pathPortion = path.substring(0, queryIndex);
+			queryPortion = path.substring(queryIndex); // includes the '?'
+		} else {
+			pathPortion = path;
+		}
+		// Remove leading slash if present
+		if (pathPortion.startsWith("/")) {
+			pathPortion = pathPortion.slice(1);
+		}
+	}
+
+	const fullPath = `${PATH_RAW_WEBSOCKET_PREFIX}${pathPortion}${queryPortion}`;
+
+	logger().debug({
+		msg: "opening websocket",
+		actorId,
+		encoding,
+		path: fullPath,
+	});
+
+	// Open WebSocket
+	const ws = await driver.openWebSocket(fullPath, actorId, encoding, params);
+
+	// Node & browser WebSocket types are incompatible
+	return ws as any;
 }

package/src/client/utils.ts

@@ -41,15 +41,16 @@ export interface HttpRequestOpts<RequestBody, ResponseBody> {
 	skipParseResponse?: boolean;
 	signal?: AbortSignal;
 	customFetch?: (req: Request) => Promise<Response>;
-	requestVersionedDataHandler: VersionedDataHandler<RequestBody>;
-	responseVersionedDataHandler: VersionedDataHandler<ResponseBody>;
+	requestVersionedDataHandler: VersionedDataHandler<RequestBody> | undefined;
+	responseVersionedDataHandler: VersionedDataHandler<ResponseBody> | undefined;
 }
 
 export async function sendHttpRequest<
 	RequestBody = unknown,
 	ResponseBody = unknown,
 >(opts: HttpRequestOpts<RequestBody, ResponseBody>): Promise<ResponseBody> {
-	logger().debug("sending http request", {
+	logger().debug({
+		msg: "sending http request",
 		url: opts.url,
 		encoding: opts.encoding,
 	});
@@ -121,6 +122,7 @@ export async function sendHttpRequest<
 
 		// Throw structured error
 		throw new ActorError(
+			responseData.group,
 			responseData.code,
 			responseData.message,
 			responseData.metadata

package/src/common/fake-event-source.ts

@@ -7,10 +7,8 @@ import type {
 	UniversalMessageEvent,
 } from "@/common/eventsource-interface";
 
-export const LOGGER_NAME = "fake-event-source";
-
 export function logger() {
-	return getLogger(LOGGER_NAME);
+	return getLogger("fake-event-source");
 }
 
 /**
@@ -146,12 +144,12 @@ export class FakeEventSource implements UniversalEventSource {
 			return;
 		}
 
-		logger().debug("closing FakeEventSource");
+		logger().debug({ msg: "closing FakeEventSource" });
 		this.readyState = 2; // CLOSED
 
 		// Call the close callback
 		this.#onCloseCallback().catch((err) => {
-			logger().error("error in onClose callback", { error: err });
+			logger().error({ msg: "error in onClose callback", error: err });
 		});
 
 		// Dispatch close event
@@ -223,7 +221,10 @@ export class FakeEventSource implements UniversalEventSource {
 				try {
 					listener.call(this, event);
 				} catch (err) {
-					logger().error(`error in ${type} event listener`, { error: err });
+					logger().error({
+						msg: `error in ${type} event listener`,
+						error: err,
+					});
 				}
 			}
 		}
@@ -235,7 +236,7 @@ export class FakeEventSource implements UniversalEventSource {
 					try {
 						this.onopen.call(this as any, event);
 					} catch (err) {
-						logger().error("error in onopen handler", { error: err });
+						logger().error({ msg: "error in onopen handler", error: err });
 					}
 				}
 				break;
@@ -244,7 +245,7 @@ export class FakeEventSource implements UniversalEventSource {
 					try {
 						this.onmessage.call(this as any, event);
 					} catch (err) {
-						logger().error("error in onmessage handler", { error: err });
+						logger().error({ msg: "error in onmessage handler", error: err });
 					}
 				}
 				break;
@@ -253,7 +254,7 @@ export class FakeEventSource implements UniversalEventSource {
 					try {
 						this.onerror.call(this as any, event);
 					} catch (err) {
-						logger().error("error in onerror handler", { error: err });
+						logger().error({ msg: "error in onerror handler", error: err });
 					}
 				}
 				break;