rivetkit 2.0.3 → 2.0.5

package/src/manager-api/routes/actors-create.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { ActorSchema } from "./common";
+
+export const ActorsCreateRequestSchema = z.object({
+	name: z.string(),
+	runner_name_selector: z.string(),
+	crash_policy: z.string(),
+	key: z.string().nullable().optional(),
+	input: z.string().nullable().optional(),
+});
+export type ActorsCreateRequest = z.infer<typeof ActorsCreateRequestSchema>;
+
+export const ActorsCreateResponseSchema = z.object({
+	actor: ActorSchema,
+});
+export type ActorsCreateResponse = z.infer<typeof ActorsCreateResponseSchema>;

package/src/manager-api/routes/actors-delete.ts

@@ -0,0 +1,4 @@
+import { z } from "zod";
+
+export const ActorsDeleteResponseSchema = z.object({});
+export type ActorsDeleteResponse = z.infer<typeof ActorsDeleteResponseSchema>;

package/src/manager-api/routes/actors-get-by-id.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+import { RivetIdSchema } from "./common";
+
+export const ActorsGetByIdResponseSchema = z.object({
+	actor_id: RivetIdSchema.nullable().optional(),
+});
+export type ActorsGetByIdResponse = z.infer<typeof ActorsGetByIdResponseSchema>;

package/src/manager-api/routes/actors-get-or-create-by-id.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import { ActorSchema, RivetIdSchema } from "./common";
+
+export const ActorsGetOrCreateResponseSchema = z.object({
+	actor: ActorSchema,
+	created: z.boolean(),
+});
+export type ActorsGetOrCreateResponse = z.infer<
+	typeof ActorsGetOrCreateResponseSchema
+>;
+
+export const ActorsGetOrCreateByIdResponseSchema = z.object({
+	actor_id: RivetIdSchema,
+	created: z.boolean(),
+});
+export type ActorsGetOrCreateByIdResponse = z.infer<
+	typeof ActorsGetOrCreateByIdResponseSchema
+>;
+
+export const ActorsGetOrCreateByIdRequestSchema = z.object({
+	name: z.string(),
+	key: z.string(),
+	runner_name_selector: z.string(),
+	crash_policy: z.string(),
+	input: z.string().nullable().optional(),
+});
+export type ActorsGetOrCreateByIdRequest = z.infer<
+	typeof ActorsGetOrCreateByIdRequestSchema
+>;

package/src/manager-api/routes/actors-get.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+import { ActorSchema } from "./common";
+
+export const ActorsGetResponseSchema = z.object({
+	actor: ActorSchema,
+});
+export type ActorsGetResponse = z.infer<typeof ActorsGetResponseSchema>;

package/src/manager-api/routes/common.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+
+export const RivetIdSchema = z.string();
+export type RivetId = z.infer<typeof RivetIdSchema>;
+
+export const ActorSchema = z.object({
+	actor_id: RivetIdSchema,
+	name: z.string(),
+	key: z.string(),
+	namespace_id: RivetIdSchema,
+	runner_name_selector: z.string(),
+	create_ts: z.number(),
+	connectable_ts: z.number().nullable().optional(),
+	destroy_ts: z.number().nullable().optional(),
+	sleep_ts: z.number().nullable().optional(),
+	start_ts: z.number().nullable().optional(),
+});
+export type Actor = z.infer<typeof ActorSchema>;

package/src/mod.ts

@@ -3,7 +3,6 @@ export * from "@/actor/mod";
 export {
 	type AnyClient,
 	type Client,
-	type ClientDriver,
 	createClientWithDriver,
 } from "@/client/client";
 export { InlineWebSocketAdapter2 } from "@/common/inline-websocket-adapter2";
@@ -13,7 +12,6 @@ export {
 	createFileSystemDriver,
 	createMemoryDriver,
 } from "@/drivers/file-system/mod";
-export { createInlineClientDriver } from "@/inline-client-driver/mod";
 // Re-export important protocol types and utilities needed by drivers
 export type { ActorQuery } from "@/manager/protocol/query";
 export * from "@/registry/mod";

package/src/registry/config.ts

@@ -5,7 +5,7 @@ import type { ActorDefinition, AnyActorDefinition } from "@/actor/definition";
 
 export const ActorsSchema = z.record(
 	z.string(),
-	z.custom<ActorDefinition<any, any, any, any, any, any, any, any>>(),
+	z.custom<ActorDefinition<any, any, any, any, any, any, any>>(),
 );
 export type RegistryActors = z.infer<typeof ActorsSchema>;
 

package/src/registry/log.ts

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

package/src/registry/mod.ts

@@ -1,10 +1,10 @@
 import type { Hono } from "hono";
-import { createActorRouter } from "@/actor/router";
 import { type Client, createClientWithDriver } from "@/client/client";
+import { configureBaseLogger, configureDefaultLogger } from "@/common/log";
 import { chooseDefaultDriver } from "@/drivers/default";
-import { createInlineClientDriver } from "@/inline-client-driver/mod";
 import { getInspectorUrl } from "@/inspector/utils";
 import { createManagerRouter } from "@/manager/router";
+import pkg from "../../package.json" with { type: "json" };
 import {
 	type RegistryActors,
 	type RegistryConfig,
@@ -21,10 +21,10 @@ import {
 import { crossPlatformServe } from "./serve";
 
 interface ServerOutput<A extends Registry<any>> {
+	/** Client to communicate with the actors. */
 	client: Client<A>;
-	hono: Hono;
-	handler: (req: Request) => Promise<Response>;
-	serve: (hono?: Hono) => void;
+	/** Fetch handler to manually route requests to the Rivet manager API. */
+	fetch: (request: Request, ...args: any) => Response | Promise<Response>;
 }
 
 export class Registry<A extends RegistryActors> {
@@ -41,12 +41,34 @@ export class Registry<A extends RegistryActors> {
 	/**
 	 * Runs the registry for a server.
 	 */
-	public createServer(inputConfig?: RunConfigInput): ServerOutput<this> {
+	public start(inputConfig?: RunConfigInput): ServerOutput<this> {
 		const config = RunConfigSchema.parse(inputConfig);
 
+		// Configure logger
+		if (config.logging?.baseLogger) {
+			// Use provided base logger
+			configureBaseLogger(config.logging.baseLogger);
+		} else {
+			// Configure default logger with log level from config
+			// getPinoLevel will handle env variable priority
+			configureDefaultLogger(config.logging?.level);
+		}
+
 		// Choose the driver based on configuration
 		const driver = chooseDefaultDriver(config);
 
+		// TODO: Find cleaner way of disabling by default
+		if (driver.name === "engine") {
+			config.inspector.enabled = false;
+			config.disableServer = true;
+		}
+		if (driver.name === "cloudflare-workers") {
+			config.inspector.enabled = false;
+			config.disableServer = true;
+			config.disableActorDriver = true;
+			config.noWelcome = true;
+		}
+
 		// Configure getUpgradeWebSocket lazily so we can assign it in crossPlatformServe
 		let upgradeWebSocket: any;
 		if (!config.getUpgradeWebSocket) {
@@ -55,62 +77,69 @@ export class Registry<A extends RegistryActors> {
 
 		// Create router
 		const managerDriver = driver.manager(this.#config, config);
-		const clientDriver = createInlineClientDriver(managerDriver);
 		const { router: hono } = createManagerRouter(
 			this.#config,
 			config,
-			clientDriver,
 			managerDriver,
 			false,
 		);
 
 		// Create client
-		const client = createClientWithDriver<this>(clientDriver);
+		const client = createClientWithDriver<this>(managerDriver, config);
 
 		const driverLog = managerDriver.extraStartupLog?.() ?? {};
-		logger().info("rivetkit ready", {
+		logger().info({
+			msg: "rivetkit ready",
 			driver: driver.name,
 			definitions: Object.keys(this.#config.use).length,
 			...driverLog,
 		});
-		if (config.inspector?.enabled) {
-			logger().info("inspector ready", {
-				url: getInspectorUrl(config),
-			});
+		if (config.inspector?.enabled && managerDriver.inspector) {
+			logger().info({ msg: "inspector ready", url: getInspectorUrl(config) });
+		}
+
+		// Print welcome information
+		if (!config.noWelcome) {
+			const displayInfo = managerDriver.displayInformation();
+			console.log();
+			console.log(`  RivetKit ${pkg.version} (${displayInfo.name})`);
+			console.log(`  - Endpoint:     http://127.0.0.1:6420`);
+			for (const [k, v] of Object.entries(displayInfo.properties)) {
+				const padding = " ".repeat(Math.max(0, 13 - k.length));
+				console.log(`  - ${k}:${padding}${v}`);
+			}
+			if (config.inspector?.enabled && managerDriver.inspector) {
+				console.log(`  - Inspector:    ${getInspectorUrl(config)}`);
+			}
+			console.log();
 		}
 
+		// HACK: We need to find a better way to let the driver itself decide when to start the actor driver
 		// Create runner
-		if (config.role === "all" || config.role === "runner") {
-			const inlineClient = createClientWithDriver(
-				createInlineClientDriver(managerDriver),
-			);
+		//
+		// Even though we do not use the return value, this is required to start the code that will handle incoming actors
+		if (!config.disableActorDriver) {
 			const _actorDriver = driver.actor(
 				this.#config,
 				config,
 				managerDriver,
-				inlineClient,
+				client,
 			);
-			// TODO: What do we do with the actor driver here?
+		}
+
+		// Start server
+		if (!config.disableServer) {
+			(async () => {
+				const out = await crossPlatformServe(hono, undefined);
+				upgradeWebSocket = out.upgradeWebSocket;
+			})();
 		}
 
 		return {
 			client,
-			hono,
-			handler: async (req: Request) => await hono.fetch(req),
-			serve: async (app) => {
-				const out = await crossPlatformServe(hono, app);
-				upgradeWebSocket = out.upgradeWebSocket;
-			},
+			fetch: hono.fetch.bind(hono),
 		};
 	}
-
-	/**
-	 * Runs the registry as a standalone server.
-	 */
-	public async runServer(inputConfig?: RunConfigInput) {
-		const { serve } = this.createServer(inputConfig);
-		serve();
-	}
 }
 
 export function setup<A extends RegistryActors>(

package/src/registry/run-config.ts

@@ -1,14 +1,14 @@
 import type { cors } from "hono/cors";
+import type { Logger } from "pino";
 import { z } from "zod";
 import type { ActorDriverBuilder } from "@/actor/driver";
+import { ClientConfigSchema } from "@/client/config";
+import { LogLevelSchema } from "@/common/log";
 import { InspectorConfigSchema } from "@/inspector/config";
 import type { ManagerDriverBuilder } from "@/manager/driver";
-import type { UpgradeWebSocket } from "@/utils";
 
 type CorsOptions = NonNullable<Parameters<typeof cors>[0]>;
 
-export type GetUpgradeWebSocket = () => UpgradeWebSocket;
-
 export const DriverConfigSchema = z.object({
 	/** Machine-readable name to identify this driver by. */
 	name: z.string(),
@@ -19,36 +19,49 @@ export const DriverConfigSchema = z.object({
 export type DriverConfig = z.infer<typeof DriverConfigSchema>;
 
 /** Base config used for the actor config across all platforms. */
-export const RunConfigSchema = z
-	.object({
-		driver: DriverConfigSchema.optional(),
+export const RunConfigSchema = ClientConfigSchema.extend({
+	driver: DriverConfigSchema.optional(),
+
+	/** CORS configuration for the router. Uses Hono's CORS middleware options. */
+	cors: z.custom<CorsOptions>().optional(),
 
-		/** Endpoint to connect to the Rivet engine. Can be configured via RIVET_ENGINE env var. */
-		engine: z.string().optional(),
+	maxIncomingMessageSize: z.number().optional().default(65_536),
 
-		// This is a function to allow for lazy configuration of upgradeWebSocket on the
-		// fly. This is required since the dependencies that profie 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(),
+	inspector: InspectorConfigSchema,
 
-		role: z.enum(["all", "server", "runner"]).optional().default("all"),
+	/** @experimental */
+	disableServer: z.boolean().optional().default(false),
 
-		/** CORS configuration for the router. Uses Hono's CORS middleware options. */
-		cors: z.custom<CorsOptions>().optional(),
+	/** @experimental */
+	disableActorDriver: z.boolean().optional().default(false),
 
-		maxIncomingMessageSize: z.number().optional().default(65_536),
+	/**
+	 * @experimental
+	 *
+	 * Base path for the router. This is used to prefix all routes.
+	 * For example, if the base path is `/api`, then the route `/actors` will be
+	 * available at `/api/actors`.
+	 */
+	basePath: z.string().optional().default("/"),
 
-		inspector: InspectorConfigSchema,
+	/**
+	 * @experimental
+	 *
+	 * Disable welcome message.
+	 * */
+	noWelcome: z.boolean().optional().default(false),
 
-		/**
-		 * Base path for the router. This is used to prefix all routes.
-		 * For example, if the base path is `/api`, then the route `/actors` will be
-		 * available at `/api/actors`.
-		 */
-		basePath: z.string().optional().default("/"),
-	})
-	.default({});
+	/**
+	 * @experimental
+	 * */
+	logging: z
+		.object({
+			baseLogger: z.custom<Logger>().optional(),
+			level: LogLevelSchema.optional(),
+		})
+		.optional()
+		.default({}),
+}).default({});
 
 export type RunConfig = z.infer<typeof RunConfigSchema>;
 export type RunConfigInput = z.input<typeof RunConfigSchema>;

package/src/registry/serve.ts

@@ -21,7 +21,8 @@ export async function crossPlatformServe(
 	}
 
 	// Mount registry
-	app.route("/registry", rivetKitRouter);
+	// app.route("/registry", rivetKitRouter);
+	app.route("/", rivetKitRouter);
 
 	// Import @hono/node-ws
 	let createNodeWebSocket: any;
@@ -41,11 +42,9 @@ export async function crossPlatformServe(
 	});
 
 	// Start server
-	const port = Number.parseInt(
-		getEnvUniversal("PORT") ?? getEnvUniversal("PORT_HTTP") ?? "8080",
-	);
+	const port = 6420;
 	const server = serve({ fetch: app.fetch, port }, () =>
-		logger().info("server listening", { port }),
+		logger().info({ msg: "server listening", port }),
 	);
 	injectWebSocket(server);
 

package/src/remote-manager-driver/actor-http-client.ts

@@ -0,0 +1,74 @@
+import type { ClientConfig } from "@/client/config";
+import { combineUrlPath } from "@/utils";
+import { getEndpoint } from "./api-utils";
+
+export async function sendHttpRequestToActor(
+	runConfig: ClientConfig,
+	actorId: string,
+	actorRequest: Request,
+): Promise<Response> {
+	// Route through guard port
+	const url = new URL(actorRequest.url);
+	const endpoint = getEndpoint(runConfig);
+	const guardUrl = combineUrlPath(endpoint, url.pathname + url.search);
+
+	// Handle body properly based on method and presence
+	let bodyToSend: ArrayBuffer | null = null;
+	const guardHeaders = buildGuardHeadersForHttp(actorRequest, actorId);
+
+	if (
+		actorRequest.body &&
+		actorRequest.method !== "GET" &&
+		actorRequest.method !== "HEAD"
+	) {
+		if (actorRequest.bodyUsed) {
+			throw new Error("Request body has already been consumed");
+		}
+
+		// TODO: This buffers the entire request in memory every time. We
+		// need to properly implement streaming bodies.
+		// Clone and read the body to ensure it can be sent
+		const clonedRequest = actorRequest.clone();
+		bodyToSend = await clonedRequest.arrayBuffer();
+
+		// If this is a streaming request, we need to convert the headers
+		// for the basic array buffer
+		guardHeaders.delete("transfer-encoding");
+		guardHeaders.set(
+			"content-length",
+			String((bodyToSend as ArrayBuffer).byteLength),
+		);
+	}
+
+	const guardRequest = new Request(guardUrl, {
+		method: actorRequest.method,
+		headers: guardHeaders,
+		body: bodyToSend,
+		signal: actorRequest.signal,
+	});
+
+	return mutableResponse(await fetch(guardRequest));
+}
+
+function mutableResponse(fetchRes: Response): Response {
+	// We cannot return the raw response from `fetch` since the response type is not mutable.
+	//
+	// In order for middleware to be able to mutate the response, we need to build a new Response object that is mutable.
+	return new Response(fetchRes.body, fetchRes);
+}
+
+function buildGuardHeadersForHttp(
+	actorRequest: Request,
+	actorId: string,
+): Headers {
+	const headers = new Headers();
+	// Copy all headers from the original request
+	for (const [key, value] of actorRequest.headers.entries()) {
+		headers.set(key, value);
+	}
+	// Add guard-specific headers
+	headers.set("x-rivet-target", "actor");
+	headers.set("x-rivet-actor", actorId);
+	headers.set("x-rivet-port", "main");
+	return headers;
+}

package/src/remote-manager-driver/actor-websocket-client.ts

@@ -0,0 +1,64 @@
+import {
+	HEADER_AUTH_DATA,
+	HEADER_CONN_PARAMS,
+	HEADER_ENCODING,
+} from "@/actor/router-endpoints";
+import type { ClientConfig } from "@/client/config";
+import { importWebSocket } from "@/common/websocket";
+import type { Encoding, UniversalWebSocket } from "@/mod";
+import { combineUrlPath } from "@/utils";
+import { getEndpoint } from "./api-utils";
+import { logger } from "./log";
+
+export async function openWebSocketToActor(
+	runConfig: ClientConfig,
+	path: string,
+	actorId: string,
+	encoding: Encoding,
+	params: unknown,
+): Promise<UniversalWebSocket> {
+	const WebSocket = await importWebSocket();
+
+	// WebSocket connections go through guard
+	const endpoint = getEndpoint(runConfig);
+	const guardUrl = combineUrlPath(endpoint, path);
+
+	logger().debug({
+		msg: "opening websocket to actor via guard",
+		actorId,
+		path,
+		guardUrl,
+	});
+
+	// Create WebSocket connection
+	const ws = new WebSocket(guardUrl, {
+		headers: buildGuardHeadersForWebSocket(actorId, encoding, params),
+	});
+
+	// Set binary type to arraybuffer for proper encoding support
+	ws.binaryType = "arraybuffer";
+
+	logger().debug({ msg: "websocket connection opened", actorId });
+
+	return ws as UniversalWebSocket;
+}
+
+export function buildGuardHeadersForWebSocket(
+	actorId: string,
+	encoding: Encoding,
+	params?: unknown,
+	authData?: unknown,
+): Record<string, string> {
+	const headers: Record<string, string> = {};
+	headers["x-rivet-target"] = "actor";
+	headers["x-rivet-actor"] = actorId;
+	headers["x-rivet-port"] = "main";
+	headers[HEADER_ENCODING] = encoding;
+	if (params) {
+		headers[HEADER_CONN_PARAMS] = JSON.stringify(params);
+	}
+	if (authData) {
+		headers[HEADER_AUTH_DATA] = JSON.stringify(authData);
+	}
+	return headers;
+}

package/src/remote-manager-driver/api-endpoints.ts

@@ -0,0 +1,79 @@
+import { serializeActorKey } from "@/actor/keys";
+import type { ClientConfig } from "@/client/client";
+import type {
+	ActorsCreateRequest,
+	ActorsCreateResponse,
+} from "@/manager-api/routes/actors-create";
+import type { ActorsDeleteResponse } from "@/manager-api/routes/actors-delete";
+import type { ActorsGetResponse } from "@/manager-api/routes/actors-get";
+import type { ActorsGetByIdResponse } from "@/manager-api/routes/actors-get-by-id";
+import type {
+	ActorsGetOrCreateByIdRequest,
+	ActorsGetOrCreateByIdResponse,
+} from "@/manager-api/routes/actors-get-or-create-by-id";
+import type { RivetId } from "@/manager-api/routes/common";
+import { apiCall } from "./api-utils";
+
+// MARK: Get actor
+export async function getActor(
+	config: ClientConfig,
+	actorId: RivetId,
+): Promise<ActorsGetResponse> {
+	return apiCall<never, ActorsGetResponse>(
+		config,
+		"GET",
+		`/actors/${encodeURIComponent(actorId)}`,
+	);
+}
+
+// MARK: Get actor by id
+export async function getActorById(
+	config: ClientConfig,
+	name: string,
+	key: string[],
+): Promise<ActorsGetByIdResponse> {
+	const serializedKey = serializeActorKey(key);
+	return apiCall<never, ActorsGetByIdResponse>(
+		config,
+		"GET",
+		`/actors/by-id?name=${encodeURIComponent(name)}&key=${encodeURIComponent(serializedKey)}`,
+	);
+}
+
+// MARK: Get or create actor by id
+export async function getOrCreateActorById(
+	config: ClientConfig,
+	request: ActorsGetOrCreateByIdRequest,
+): Promise<ActorsGetOrCreateByIdResponse> {
+	return apiCall<ActorsGetOrCreateByIdRequest, ActorsGetOrCreateByIdResponse>(
+		config,
+		"PUT",
+		`/actors/by-id`,
+		request,
+	);
+}
+
+// MARK: Create actor
+export async function createActor(
+	config: ClientConfig,
+	request: ActorsCreateRequest,
+): Promise<ActorsCreateResponse> {
+	return apiCall<ActorsCreateRequest, ActorsCreateResponse>(
+		config,
+		"POST",
+		`/actors`,
+		request,
+	);
+}
+
+// MARK: Destroy actor
+export async function destroyActor(
+	config: ClientConfig,
+	actorId: RivetId,
+): Promise<ActorsDeleteResponse> {
+	return apiCall<never, ActorsDeleteResponse>(
+		config,
+		"DELETE",
+		`/actors/${encodeURIComponent(actorId)}`,
+	);
+}

package/src/remote-manager-driver/api-utils.ts

@@ -0,0 +1,46 @@
+import type { ClientConfig } from "@/client/config";
+import { sendHttpRequest } from "@/client/utils";
+import { combineUrlPath } from "@/utils";
+import { logger } from "./log";
+
+// Error class for Engine API errors
+export class EngineApiError extends Error {
+	constructor(
+		public readonly group: string,
+		public readonly code: string,
+		message?: string,
+	) {
+		super(message || `Engine API error: ${group}/${code}`);
+		this.name = "EngineApiError";
+	}
+}
+
+export function getEndpoint(config: ClientConfig) {
+	return config.endpoint ?? "http://127.0.0.1:6420";
+}
+
+// Helper function for making API calls
+export async function apiCall<TInput = unknown, TOutput = unknown>(
+	config: ClientConfig,
+	method: "GET" | "POST" | "PUT" | "DELETE",
+	path: string,
+	body?: TInput,
+): Promise<TOutput> {
+	const endpoint = getEndpoint(config);
+	const url = combineUrlPath(endpoint, path, {
+		namespace: config.namespace,
+	});
+
+	logger().debug({ msg: "making api call", method, url });
+
+	return await sendHttpRequest<TInput, TOutput>({
+		method,
+		url,
+		headers: {},
+		body,
+		encoding: "json",
+		skipParseResponse: false,
+		requestVersionedDataHandler: undefined,
+		responseVersionedDataHandler: undefined,
+	});
+}

package/src/remote-manager-driver/log.ts

@@ -0,0 +1,5 @@
+import { getLogger } from "@/common//log";
+
+export function logger() {
+	return getLogger("remote-manager-driver");
+}