rivetkit 2.0.2 → 2.0.3

package/src/inspector/config.ts

@@ -0,0 +1,83 @@
+import type { cors } from "hono/cors";
+import { z } from "zod";
+import { HEADER_ACTOR_QUERY } from "@/driver-helpers/mod";
+import { getEnvUniversal } from "@/utils";
+
+type CorsOptions = NonNullable<Parameters<typeof cors>[0]>;
+
+const defaultTokenFn = () => {
+	const envToken = getEnvUniversal("RIVETKIT_INSPECTOR_TOKEN");
+
+	if (envToken) {
+		return envToken;
+	}
+
+	return "";
+};
+
+const defaultEnabled = () => {
+	return (
+		getEnvUniversal("NODE_ENV") !== "production" ||
+		!getEnvUniversal("RIVETKIT_INSPECTOR_DISABLE")
+	);
+};
+
+const defaultInspectorOrigins = [
+	"http://localhost:43708",
+	"https://studio.rivet.gg",
+];
+
+const defaultCors: CorsOptions = {
+	origin: (origin) => {
+		if (
+			defaultInspectorOrigins.includes(origin) ||
+			(origin.startsWith("https://") && origin.endsWith("rivet-gg.vercel.app"))
+		) {
+			return origin;
+		} else {
+			return null;
+		}
+	},
+	allowMethods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+	allowHeaders: [
+		"Content-Type",
+		"Authorization",
+		HEADER_ACTOR_QUERY,
+		"last-event-id",
+	],
+	maxAge: 3600,
+	credentials: true,
+};
+
+export const InspectorConfigSchema = z
+	.object({
+		enabled: z.boolean().optional().default(defaultEnabled),
+		/** CORS configuration for the router. Uses Hono's CORS middleware options. */
+		cors: z
+			.custom<CorsOptions>()
+			.optional()
+			.default(() => defaultCors),
+
+		/**
+		 * Token used to access the Inspector.
+		 */
+		token: z
+			.function()
+			.returns(z.string())
+			.optional()
+			.default(() => defaultTokenFn),
+
+		/**
+		 * Default RivetKit server endpoint for Rivet Inspector to connect to. This should be the same endpoint as what you use for your Rivet client to connect to RivetKit.
+		 *
+		 * This is a convenience property just for printing out the inspector URL.
+		 */
+		defaultEndpoint: z.string().optional(),
+	})
+	.optional()
+	.default(() => ({
+		enabled: defaultEnabled(),
+		token: defaultTokenFn,
+		cors: defaultCors,
+	}));
+export type InspectorConfig = z.infer<typeof InspectorConfigSchema>;

package/src/inspector/log.ts

@@ -0,0 +1,5 @@
+import { getLogger } from "@/common//log";
+
+export function inspectorLogger() {
+	return getLogger("inspector");
+}

package/src/inspector/manager.ts

@@ -0,0 +1,86 @@
+import { sValidator } from "@hono/standard-validator";
+import { Hono } from "hono";
+import invariant from "invariant";
+import type { CreateInput } from "@/manager/driver";
+import { inspectorLogger } from "./log";
+import { type Actor, type Builds, CreateActorSchema } from "./protocol/common";
+
+export type ManagerInspectorRouterEnv = {
+	Variables: {
+		inspector: ManagerInspector;
+	};
+};
+
+/**
+ * Create a router for the Manager Inspector.
+ * @internal
+ */
+export function createManagerInspectorRouter() {
+	return new Hono<ManagerInspectorRouterEnv>()
+		.get("/ping", (c) => {
+			return c.json({ message: "pong" }, 200);
+		})
+		.get("/actors", async (c) => {
+			const limit = Number.parseInt(c.req.query("limit") ?? "") || undefined;
+			const cursor = c.req.query("cursor") || undefined;
+
+			if (!limit || (limit && limit <= 0)) {
+				return c.json("Invalid limit", 400);
+			}
+
+			try {
+				const actors = await c.var.inspector.accessors.getAllActors({
+					limit,
+					cursor,
+				});
+				return c.json(actors, 200);
+			} catch (error) {
+				inspectorLogger().error("Failed to fetch actors", error);
+				return c.json("Failed to fetch actors", 500);
+			}
+		})
+
+		.post("/actors", sValidator("json", CreateActorSchema), async (c) => {
+			const actor = await c.var.inspector.accessors.createActor(
+				c.req.valid("json"),
+			);
+			return c.json(actor, 201);
+		})
+		.get("/builds", async (c) => {
+			const builds = await c.var.inspector.accessors.getBuilds();
+			return c.json(builds, 200);
+		})
+		.get("/actor/:id", async (c) => {
+			const id = c.req.param("id");
+			const actor = await c.var.inspector.accessors.getActorById(id);
+			if (!actor) {
+				return c.json({ error: "Actor not found" }, 404);
+			}
+			return c.json(actor, 200);
+		})
+		.get("/bootstrap", async (c) => {
+			const actors = await c.var.inspector.accessors.getAllActors({
+				limit: 10,
+			});
+			return c.json({ actors }, 200);
+		});
+}
+
+interface ManagerInspectorAccessors {
+	getAllActors: (param: { cursor?: string; limit: number }) => Promise<Actor[]>;
+	getActorById: (id: string) => Promise<Actor | null>;
+	getBuilds: () => Promise<Builds>;
+	createActor: (input: CreateInput) => Promise<Actor | null>;
+}
+
+/**
+ * Provides a unified interface for inspecting actor external and internal state.
+ */
+export class ManagerInspector {
+	public readonly accessors: ManagerInspectorAccessors;
+
+	constructor(accessors: () => ManagerInspectorAccessors) {
+		this.accessors = accessors();
+		inspectorLogger().debug("Manager Inspector enabled and ready");
+	}
+}

package/src/inspector/mod.ts

@@ -0,0 +1,2 @@
+export * from "./protocol/common";
+export * from "./protocol/mod";

package/src/inspector/protocol/actor.ts

@@ -0,0 +1,10 @@
+import { hc } from "hono/client";
+import type { createActorInspectorRouter } from "../actor";
+
+type ActorInspectorRouter = ReturnType<typeof createActorInspectorRouter>;
+const client = hc<ActorInspectorRouter>("");
+export type ActorInspectorClient = typeof client;
+
+export const createActorInspectorClient = (
+	...args: Parameters<typeof hc>
+): ActorInspectorClient => hc<ActorInspectorRouter>(...args);

package/src/inspector/protocol/common.ts

@@ -0,0 +1,196 @@
+import z from "zod/v4";
+import { ActorKeySchema, MAX_ACTOR_KEY_SIZE } from "@/manager/protocol/query";
+
+export const ActorId = z.string().brand("ActorId");
+export type ActorId = z.infer<typeof ActorId>;
+
+export enum ActorFeature {
+	Logs = "logs",
+	Config = "config",
+	Connections = "connections",
+	State = "state",
+	Console = "console",
+	Runtime = "runtime",
+	Metrics = "metrics",
+	EventsMonitoring = "events-monitoring",
+	Database = "database",
+}
+
+export const ActorLogEntry = z.object({
+	level: z.string(),
+	message: z.string(),
+	timestamp: z.string(),
+	metadata: z.record(z.string(), z.any()).optional(),
+});
+
+export const ActorSchema = z.object({
+	id: ActorId,
+	name: z.string(),
+	key: z.array(z.string()),
+	tags: z.record(z.string(), z.string()).optional(),
+	region: z.string().optional(),
+	createdAt: z.string().optional(),
+	startedAt: z.string().optional(),
+	destroyedAt: z.string().optional(),
+	features: z.array(z.enum(ActorFeature)).optional(),
+});
+
+export type Actor = z.infer<typeof ActorSchema>;
+export type ActorLogEntry = z.infer<typeof ActorLogEntry>;
+
+// MARK: State
+
+export const OperationSchema = z.discriminatedUnion("op", [
+	z.object({
+		op: z.literal("remove"),
+		path: z.string(),
+	}),
+	z.object({
+		op: z.literal("add"),
+		path: z.string(),
+		value: z.unknown(),
+	}),
+	z.object({
+		op: z.literal("replace"),
+		path: z.string(),
+		value: z.unknown(),
+	}),
+	z.object({
+		op: z.literal("move"),
+		path: z.string(),
+		from: z.string(),
+	}),
+	z.object({
+		op: z.literal("copy"),
+		path: z.string(),
+		from: z.string(),
+	}),
+	z.object({
+		op: z.literal("test"),
+		path: z.string(),
+		value: z.unknown(),
+	}),
+]);
+export type Operation = z.infer<typeof OperationSchema>;
+
+export const PatchSchema = z.array(OperationSchema);
+export type Patch = z.infer<typeof PatchSchema>;
+
+// MARK: Connections
+
+export const ConnectionSchema = z.object({
+	params: z.record(z.string(), z.any()).optional(),
+	id: z.string(),
+	stateEnabled: z.boolean().optional(),
+	state: z.any().optional(),
+	auth: z.record(z.string(), z.any()).optional(),
+});
+export type Connection = z.infer<typeof ConnectionSchema>;
+
+// MARK: Realtime Events
+
+export const RealtimeEventSchema = z.discriminatedUnion("type", [
+	z.object({
+		type: z.literal("action"),
+		name: z.string(),
+		args: z.array(z.any()),
+		connId: z.string(),
+	}),
+	z.object({
+		type: z.literal("broadcast"),
+		eventName: z.string(),
+		args: z.array(z.any()),
+	}),
+	z.object({
+		type: z.literal("subscribe"),
+		eventName: z.string(),
+		connId: z.string(),
+	}),
+	z.object({
+		type: z.literal("unsubscribe"),
+		eventName: z.string(),
+		connId: z.string(),
+	}),
+	z.object({
+		type: z.literal("event"),
+		eventName: z.string(),
+		args: z.array(z.any()),
+		connId: z.string(),
+	}),
+]);
+export type RealtimeEvent = z.infer<typeof RealtimeEventSchema>;
+export const RecordedRealtimeEventSchema = RealtimeEventSchema.and(
+	z.object({
+		id: z.string(),
+		timestamp: z.number(),
+	}),
+);
+export type RecordedRealtimeEvent = z.infer<typeof RecordedRealtimeEventSchema>;
+
+// MARK: Database
+
+export const DatabaseQuerySchema = z.object({
+	sql: z.string(),
+	args: z.array(z.string().or(z.number())),
+});
+export type DatabaseQuery = z.infer<typeof DatabaseQuerySchema>;
+
+export const TableSchema = z.object({
+	schema: z.string(),
+	name: z.string(),
+	type: z.enum(["table", "view"]),
+});
+export type Table = z.infer<typeof TableSchema>;
+
+export const TablesSchema = z.array(TableSchema);
+export type Tables = z.infer<typeof TablesSchema>;
+
+export const ColumnSchema = z.object({
+	cid: z.number(),
+	name: z.string(),
+	type: z
+		.string()
+		.toLowerCase()
+		.transform((val) => {
+			return z
+				.enum(["integer", "text", "real", "blob", "numeric", "serial"])
+				.parse(val);
+		}),
+	notnull: z.coerce.boolean(),
+	dflt_value: z.string().nullable(),
+	pk: z.coerce.boolean().nullable(),
+});
+export type Column = z.infer<typeof ColumnSchema>;
+
+export const ColumnsSchema = z.array(ColumnSchema);
+export type Columns = z.infer<typeof ColumnsSchema>;
+
+export const ForeignKeySchema = z.object({
+	id: z.number(),
+	table: z.string(),
+	from: z.string(),
+	to: z.string(),
+});
+export type ForeignKey = z.infer<typeof ForeignKeySchema>;
+
+export const ForeignKeysSchema = z.array(ForeignKeySchema);
+export type ForeignKeys = z.infer<typeof ForeignKeysSchema>;
+
+// MARK: Builds
+
+export const BuildSchema = z.object({
+	name: z.string(),
+	createdAt: z.string().optional(),
+	tags: z.record(z.string(), z.string()).optional(),
+});
+export type Build = z.infer<typeof BuildSchema>;
+export const BuildsSchema = z.array(BuildSchema);
+export type Builds = z.infer<typeof BuildsSchema>;
+
+export const CreateActorSchema = z.object({
+	name: z.string(),
+	// FIXME: Replace with ActorKeySchema when ready
+	key: z.array(z.string().max(MAX_ACTOR_KEY_SIZE)),
+	input: z.any(),
+});
+export type CreateActor = z.infer<typeof CreateActorSchema>;

package/src/inspector/protocol/manager.ts

@@ -0,0 +1,10 @@
+import { hc } from "hono/client";
+import type { createManagerInspectorRouter } from "../manager";
+
+type ManagerInspectorRouter = ReturnType<typeof createManagerInspectorRouter>;
+const client = hc<ManagerInspectorRouter>("");
+export type ManagerInspectorClient = typeof client;
+
+export const createManagerInspectorClient = (
+	...args: Parameters<typeof hc>
+): ManagerInspectorClient => hc<ManagerInspectorRouter>(...args);

package/src/inspector/protocol/mod.ts

@@ -0,0 +1,2 @@
+export * from "./actor";
+export * from "./manager";

package/src/inspector/utils.ts

@@ -0,0 +1,76 @@
+import crypto from "node:crypto";
+import { createMiddleware } from "hono/factory";
+import type { RunConfig } from "@/mod";
+import type { RunConfigInput } from "@/registry/run-config";
+import { inspectorLogger } from "./log";
+
+export function compareSecrets(providedSecret: string, validSecret: string) {
+	// Early length check to avoid unnecessary processing
+	if (providedSecret.length !== validSecret.length) {
+		return false;
+	}
+
+	const encoder = new TextEncoder();
+
+	const a = encoder.encode(providedSecret);
+	const b = encoder.encode(validSecret);
+
+	if (a.byteLength !== b.byteLength) {
+		return false;
+	}
+
+	// Perform timing-safe comparison
+	if (!crypto.timingSafeEqual(a, b)) {
+		return false;
+	}
+	return true;
+}
+
+export const secureInspector = (runConfig: RunConfig) =>
+	createMiddleware(async (c, next) => {
+		if (!runConfig.inspector.enabled) {
+			return c.text("Inspector is not enabled", 503);
+		}
+
+		const userToken = c.req.header("Authorization")?.replace("Bearer ", "");
+		if (!userToken) {
+			return c.text("Unauthorized", 401);
+		}
+
+		const inspectorToken = runConfig.inspector.token?.();
+		if (!inspectorToken) {
+			return c.text("Unauthorized", 401);
+		}
+
+		const isValid = compareSecrets(userToken, inspectorToken);
+
+		if (!isValid) {
+			return c.text("Unauthorized", 401);
+		}
+		await next();
+	});
+
+export function getInspectorUrl(runConfig: RunConfigInput | undefined) {
+	if (!runConfig?.inspector?.enabled) {
+		return "disabled";
+	}
+
+	const accessToken = runConfig?.inspector?.token?.();
+
+	if (!accessToken) {
+		inspectorLogger().warn(
+			"Inspector Token is not set, but Inspector is enabled. Please set it in the run configuration `inspector.token` or via `RIVETKIT_INSPECTOR_TOKEN` environment variable. Inspector will not be accessible.",
+		);
+		return "disabled";
+	}
+
+	const url = new URL("https://studio.rivet.gg");
+
+	url.searchParams.set("t", accessToken);
+
+	if (runConfig?.inspector?.defaultEndpoint) {
+		url.searchParams.set("u", runConfig.inspector.defaultEndpoint);
+	}
+
+	return url.href;
+}

package/src/manager/auth.ts

@@ -0,0 +1,121 @@
+import type { Context as HonoContext } from "hono";
+import type { AuthIntent } from "@/actor/config";
+import type { AnyActorDefinition } from "@/actor/definition";
+import * as errors from "@/actor/errors";
+import type { RegistryConfig } from "@/registry/config";
+import { stringifyError } from "@/utils";
+import type { ManagerDriver } from "./driver";
+import { logger } from "./log";
+import type { ActorQuery } from "./protocol/query";
+
+/**
+ * Get authentication intents from a actor query
+ */
+export function getIntentsFromQuery(query: ActorQuery): Set<AuthIntent> {
+	const intents = new Set<AuthIntent>();
+
+	if ("getForId" in query) {
+		intents.add("get");
+	} else if ("getForKey" in query) {
+		intents.add("get");
+	} else if ("getOrCreateForKey" in query) {
+		intents.add("get");
+		intents.add("create");
+	} else if ("create" in query) {
+		intents.add("create");
+	}
+
+	return intents;
+}
+
+/**
+ * Get actor name from a actor query
+ */
+export async function getActorNameFromQuery(
+	c: HonoContext,
+	driver: ManagerDriver,
+	query: ActorQuery,
+): Promise<string> {
+	if ("getForId" in query) {
+		// TODO: This will have a duplicate call to getForId between this and queryActor
+		const output = await driver.getForId({
+			c,
+			name: query.getForId.name,
+			actorId: query.getForId.actorId,
+		});
+		if (!output) throw new errors.ActorNotFound(query.getForId.actorId);
+		return output.name;
+	} else if ("getForKey" in query) {
+		return query.getForKey.name;
+	} else if ("getOrCreateForKey" in query) {
+		return query.getOrCreateForKey.name;
+	} else if ("create" in query) {
+		return query.create.name;
+	} else {
+		throw new errors.InvalidRequest("Invalid query format");
+	}
+}
+
+/**
+ * Authenticate a request using the actor's onAuth function
+ */
+export async function authenticateRequest(
+	c: HonoContext,
+	actorDefinition: AnyActorDefinition,
+	intents: Set<AuthIntent>,
+	params: unknown,
+): Promise<unknown> {
+	if (!("onAuth" in actorDefinition.config)) {
+		throw new errors.Forbidden(
+			"Actor requires authentication but no onAuth handler is defined (https://rivet.gg/docs/actors/authentication/). Provide an empty handler to disable auth: `onAuth: () => {}`",
+		);
+	}
+
+	try {
+		const dataOrPromise = actorDefinition.config.onAuth(
+			{
+				request: c.req.raw,
+				intents,
+			},
+			params,
+		);
+		if (dataOrPromise instanceof Promise) {
+			return await dataOrPromise;
+		} else {
+			return dataOrPromise;
+		}
+	} catch (error) {
+		logger().info("authentication error", { error: stringifyError(error) });
+		throw error;
+	}
+}
+
+/**
+ * Simplified authentication for endpoints that combines all auth steps
+ */
+export async function authenticateEndpoint(
+	c: HonoContext,
+	driver: ManagerDriver,
+	registryConfig: RegistryConfig,
+	query: ActorQuery,
+	additionalIntents: AuthIntent[],
+	params: unknown,
+): Promise<unknown> {
+	// Get base intents from query
+	const intents = getIntentsFromQuery(query);
+
+	// Add endpoint-specific intents
+	for (const intent of additionalIntents) {
+		intents.add(intent);
+	}
+
+	// Get actor definition
+	const actorName = await getActorNameFromQuery(c, driver, query);
+	const actorDefinition = registryConfig.use[actorName];
+	if (!actorDefinition) {
+		throw new errors.ActorNotFound(actorName);
+	}
+
+	// Authenticate
+	return await authenticateRequest(c, actorDefinition, intents, params);
+}

package/src/manager/driver.ts

@@ -0,0 +1,80 @@
+import type { Env, Hono, Context as HonoContext } from "hono";
+import type { ActorKey, Encoding } from "@/actor/mod";
+import type { ManagerInspector } from "@/inspector/manager";
+import type { RunConfig } from "@/mod";
+import type { RegistryConfig } from "@/registry/config";
+
+export type ManagerDriverBuilder = (
+	registryConfig: RegistryConfig,
+	runConfig: RunConfig,
+) => ManagerDriver;
+
+export interface ManagerDriver {
+	getForId(input: GetForIdInput): Promise<ActorOutput | undefined>;
+	getWithKey(input: GetWithKeyInput): Promise<ActorOutput | undefined>;
+	getOrCreateWithKey(input: GetOrCreateWithKeyInput): Promise<ActorOutput>;
+	createActor(input: CreateInput): Promise<ActorOutput>;
+
+	sendRequest(actorId: string, actorRequest: Request): Promise<Response>;
+	openWebSocket(
+		path: string,
+		actorId: string,
+		encoding: Encoding,
+		params: unknown,
+	): Promise<WebSocket>;
+	proxyRequest(
+		c: HonoContext,
+		actorRequest: Request,
+		actorId: string,
+	): Promise<Response>;
+	proxyWebSocket(
+		c: HonoContext,
+		path: string,
+		actorId: string,
+		encoding: Encoding,
+		params: unknown,
+		authData: unknown,
+	): Promise<Response>;
+
+	extraStartupLog?: () => Record<string, unknown>;
+
+	modifyManagerRouter?: (registryConfig: RegistryConfig, router: Hono) => void;
+
+	/**
+	 * @internal
+	 */
+	readonly inspector?: ManagerInspector;
+}
+export interface GetForIdInput<E extends Env = any> {
+	c?: HonoContext | undefined;
+	name: string;
+	actorId: string;
+}
+
+export interface GetWithKeyInput<E extends Env = any> {
+	c?: HonoContext | undefined;
+	name: string;
+	key: ActorKey;
+}
+
+export interface GetOrCreateWithKeyInput<E extends Env = any> {
+	c?: HonoContext | undefined;
+	name: string;
+	key: ActorKey;
+	input?: unknown;
+	region?: string;
+}
+
+export interface CreateInput<E extends Env = any> {
+	c?: HonoContext | undefined;
+	name: string;
+	key: ActorKey;
+	input?: unknown;
+	region?: string;
+}
+
+export interface ActorOutput {
+	actorId: string;
+	name: string;
+	key: ActorKey;
+}