rivetkit 2.0.2 → 2.0.4

package/src/registry/mod.ts

@@ -0,0 +1,157 @@
+import type { Hono } from "hono";
+import { type Client, createClientWithDriver } from "@/client/client";
+import { configureBaseLogger, configureDefaultLogger } from "@/common/log";
+import { chooseDefaultDriver } from "@/drivers/default";
+import { getInspectorUrl } from "@/inspector/utils";
+import { createManagerRouter } from "@/manager/router";
+import pkg from "../../package.json" with { type: "json" };
+import {
+	type RegistryActors,
+	type RegistryConfig,
+	type RegistryConfigInput,
+	RegistryConfigSchema,
+} from "./config";
+import { logger } from "./log";
+import {
+	type DriverConfig,
+	type RunConfig,
+	type RunConfigInput,
+	RunConfigSchema,
+} from "./run-config";
+import { crossPlatformServe } from "./serve";
+
+interface ServerOutput<A extends Registry<any>> {
+	config: RunConfig;
+	driver: DriverConfig;
+	client: Client<A>;
+	hono: Hono;
+	handler: (req: Request) => Promise<Response>;
+	serve: (hono?: Hono) => void;
+}
+
+export class Registry<A extends RegistryActors> {
+	#config: RegistryConfig;
+
+	public get config(): RegistryConfig {
+		return this.#config;
+	}
+
+	constructor(config: RegistryConfig) {
+		this.#config = config;
+	}
+
+	/**
+	 * Runs the registry for a server.
+	 */
+	public createServer(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;
+		}
+
+		// Configure getUpgradeWebSocket lazily so we can assign it in crossPlatformServe
+		let upgradeWebSocket: any;
+		if (!config.getUpgradeWebSocket) {
+			config.getUpgradeWebSocket = () => upgradeWebSocket!;
+		}
+
+		// Create router
+		const managerDriver = driver.manager(this.#config, config);
+		const { router: hono } = createManagerRouter(
+			this.#config,
+			config,
+			managerDriver,
+			false,
+		);
+
+		// Create client
+		const client = createClientWithDriver<this>(managerDriver, config);
+
+		const driverLog = managerDriver.extraStartupLog?.() ?? {};
+		logger().info({
+			msg: "rivetkit ready",
+			driver: driver.name,
+			definitions: Object.keys(this.#config.use).length,
+			...driverLog,
+		});
+		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();
+		}
+
+		// Create runner
+		//
+		// Even though we do not use the return value, this is required to start the code that will handle incoming actors
+		const _actorDriver = driver.actor(
+			this.#config,
+			config,
+			managerDriver,
+			client,
+		);
+
+		return {
+			config,
+			driver,
+			client,
+			hono,
+			handler: async (req: Request) => await hono.fetch(req),
+			serve: async (app) => {
+				const out = await crossPlatformServe(hono, app);
+				upgradeWebSocket = out.upgradeWebSocket;
+			},
+		};
+	}
+
+	/**
+	 * Runs the registry as a standalone server.
+	 */
+	public async runServer(inputConfig?: RunConfigInput) {
+		const { driver, serve } = this.createServer(inputConfig);
+
+		// TODO: FInd better way of doing this
+		// Don't run server by default
+		if (driver.name !== "engine") {
+			serve();
+		}
+	}
+}
+
+export function setup<A extends RegistryActors>(
+	input: RegistryConfigInput<A>,
+): Registry<A> {
+	const config = RegistryConfigSchema.parse(input);
+	return new Registry(config);
+}
+
+export type { RegistryConfig, RegistryActors, RunConfig, DriverConfig };
+export { RegistryConfigSchema };

package/src/registry/run-config.ts

@@ -0,0 +1,52 @@
+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";
+
+type CorsOptions = NonNullable<Parameters<typeof cors>[0]>;
+
+export const DriverConfigSchema = z.object({
+	/** Machine-readable name to identify this driver by. */
+	name: z.string(),
+	manager: z.custom<ManagerDriverBuilder>(),
+	actor: z.custom<ActorDriverBuilder>(),
+});
+
+export type DriverConfig = z.infer<typeof DriverConfigSchema>;
+
+/** Base config used for the actor config across all platforms. */
+export const RunConfigSchema = ClientConfigSchema.extend({
+	driver: DriverConfigSchema.optional(),
+
+	/** CORS configuration for the router. Uses Hono's CORS middleware options. */
+	cors: z.custom<CorsOptions>().optional(),
+
+	maxIncomingMessageSize: z.number().optional().default(65_536),
+
+	inspector: InspectorConfigSchema,
+
+	/**
+	 * 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("/"),
+
+	/** Disable welcome message. */
+	noWelcome: z.boolean().optional().default(false),
+
+	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

@@ -0,0 +1,52 @@
+import { Hono } from "hono";
+import { getEnvUniversal } from "@/utils";
+import { logger } from "./log";
+
+export async function crossPlatformServe(
+	rivetKitRouter: Hono<any>,
+	userRouter: Hono | undefined,
+) {
+	const app = userRouter ?? new Hono();
+
+	// Import @hono/node-server
+	let serve: any;
+	try {
+		const dep = await import("@hono/node-server");
+		serve = dep.serve;
+	} catch (err) {
+		logger().error(
+			"failed to import @hono/node-server. please run 'npm install @hono/node-server @hono/node-ws'",
+		);
+		process.exit(1);
+	}
+
+	// Mount registry
+	// app.route("/registry", rivetKitRouter);
+	app.route("/", rivetKitRouter);
+
+	// Import @hono/node-ws
+	let createNodeWebSocket: any;
+	try {
+		const dep = await import("@hono/node-ws");
+		createNodeWebSocket = dep.createNodeWebSocket;
+	} catch (err) {
+		logger().error(
+			"failed to import @hono/node-ws. please run 'npm install @hono/node-server @hono/node-ws'",
+		);
+		process.exit(1);
+	}
+
+	// Inject WS
+	const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({
+		app,
+	});
+
+	// Start server
+	const port = 6420;
+	const server = serve({ fetch: app.fetch, port }, () =>
+		logger().info({ msg: "server listening", port }),
+	);
+	injectWebSocket(server);
+
+	return { upgradeWebSocket };
+}

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

@@ -0,0 +1,72 @@
+import type { ClientConfig } from "@/client/config";
+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 = `${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,
+	});
+
+	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,63 @@
+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 { 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 = `${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,43 @@
+import type { ClientConfig } from "@/client/config";
+import { sendHttpRequest } from "@/client/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 = `${endpoint}${path}${path.includes("?") ? "&" : "?"}namespace=${encodeURIComponent(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");
+}