rivetkit 2.0.2 → 2.0.4-rc.1

package/src/common/log.ts

@@ -0,0 +1,229 @@
+import {
+	type LevelWithSilent,
+	type Logger,
+	pino,
+	stdTimeFunctions,
+} from "pino";
+import { z } from "zod/v4";
+import { getLogLevel, getLogTarget, getLogTimestamp } from "@/utils/env-vars";
+import {
+	castToLogValue,
+	formatTimestamp,
+	LOGGER_CONFIG,
+	stringify,
+} from "./logfmt";
+
+export type { Logger } from "pino";
+
+let baseLogger: Logger | undefined;
+let configuredLogLevel: LogLevel | undefined;
+
+/** Cache of child loggers by logger name. */
+const loggerCache = new Map<string, Logger>();
+
+export const LogLevelSchema = z.enum([
+	"trace",
+	"debug",
+	"info",
+	"warn",
+	"error",
+	"fatal",
+	"silent",
+]);
+
+export type LogLevel = z.infer<typeof LogLevelSchema>;
+
+export function getPinoLevel(logLevel?: LogLevel): LevelWithSilent {
+	// Priority: provided > configured > env > default
+	if (logLevel) {
+		return logLevel;
+	}
+
+	if (configuredLogLevel) {
+		return configuredLogLevel;
+	}
+
+	const raw = (getLogLevel() || "warn").toString().toLowerCase();
+
+	const parsed = LogLevelSchema.safeParse(raw);
+	if (parsed.success) {
+		return parsed.data;
+	}
+
+	// Default to info if invalid
+	return "info";
+}
+
+export function getIncludeTarget(): boolean {
+	return getLogTarget();
+}
+
+/**
+ * Configure a custom base logger.
+ */
+export function configureBaseLogger(logger: Logger): void {
+	baseLogger = logger;
+	loggerCache.clear();
+}
+
+// TODO: This can be simplified in logfmt.ts
+function customWrite(level: string, o: any) {
+	const entries: any = {};
+
+	// Add timestamp if enabled
+	if (getLogTimestamp() && o.time) {
+		const date = typeof o.time === "number" ? new Date(o.time) : new Date();
+		entries.ts = formatTimestamp(date);
+	}
+
+	// Add level
+	entries.level = level.toUpperCase();
+
+	// Add target if present
+	if (o.target) {
+		entries.target = o.target;
+	}
+
+	// Add message
+	if (o.msg) {
+		entries.msg = o.msg;
+	}
+
+	// Add other properties
+	for (const [key, value] of Object.entries(o)) {
+		if (
+			key !== "time" &&
+			key !== "level" &&
+			key !== "target" &&
+			key !== "msg" &&
+			key !== "pid" &&
+			key !== "hostname"
+		) {
+			entries[key] = castToLogValue(value);
+		}
+	}
+
+	const output = stringify(entries);
+	console.log(output);
+}
+
+/**
+ * Configure the default logger with optional log level.
+ */
+export function configureDefaultLogger(logLevel?: LogLevel) {
+	// Store the configured log level
+	if (logLevel) {
+		configuredLogLevel = logLevel;
+	}
+
+	baseLogger = pino({
+		level: getPinoLevel(logLevel),
+		messageKey: "msg",
+		// Do not include pid/hostname in output
+		base: {},
+		// Keep a string level in the output
+		formatters: {
+			level(_label: string, number: number) {
+				return { level: number };
+			},
+		},
+		timestamp: getLogTimestamp() ? stdTimeFunctions.epochTime : false,
+		browser: {
+			write: {
+				fatal: customWrite.bind(null, "fatal"),
+				error: customWrite.bind(null, "error"),
+				warn: customWrite.bind(null, "warn"),
+				info: customWrite.bind(null, "info"),
+				debug: customWrite.bind(null, "debug"),
+				trace: customWrite.bind(null, "trace"),
+			},
+		},
+		hooks: {
+			logMethod(inputArgs, method, level) {
+				// TODO: This is a hack to not implement our own Pino transport target. We can get better perf if we have our own transport target.
+
+				const levelMap: Record<number, string> = {
+					10: "trace",
+					20: "debug",
+					30: "info",
+					40: "warn",
+					50: "error",
+					60: "fatal",
+				};
+				const levelName = levelMap[level] || "info";
+				const time = getLogTimestamp() ? Date.now() : undefined;
+
+				// Get bindings from the logger instance (child logger fields)
+				const bindings = (this as any).bindings?.() || {};
+
+				// TODO: This can be simplified in logfmt.ts
+				if (inputArgs.length >= 2) {
+					const [objOrMsg, msg] = inputArgs;
+					if (typeof objOrMsg === "object" && objOrMsg !== null) {
+						customWrite(levelName, {
+							...bindings,
+							...objOrMsg,
+							msg,
+							time,
+						});
+					} else {
+						customWrite(levelName, {
+							...bindings,
+							msg: String(objOrMsg),
+							time,
+						});
+					}
+				} else if (inputArgs.length === 1) {
+					const [objOrMsg] = inputArgs;
+					if (typeof objOrMsg === "object" && objOrMsg !== null) {
+						customWrite(levelName, {
+							...bindings,
+							...objOrMsg,
+							time,
+						});
+					} else {
+						customWrite(levelName, {
+							...bindings,
+							msg: String(objOrMsg),
+							time,
+						});
+					}
+				}
+			},
+		},
+	});
+
+	loggerCache.clear();
+}
+
+/**
+ * Get or initialize the base logger.
+ */
+export function getBaseLogger(): Logger {
+	if (!baseLogger) {
+		configureDefaultLogger();
+	}
+	return baseLogger!;
+}
+
+/**
+ * Returns a child logger with `target` bound for the given name.
+ */
+export function getLogger(name = "default"): Logger {
+	// Check cache first
+	const cached = loggerCache.get(name);
+	if (cached) {
+		return cached;
+	}
+
+	// Create
+	const base = getBaseLogger();
+
+	// Add target to log if enabled
+	const child = getIncludeTarget() ? base.child({ target: name }) : base;
+
+	// Cache the logger
+	loggerCache.set(name, child);
+
+	return child;
+}

package/src/common/logfmt.ts

@@ -0,0 +1,221 @@
+import { type LogLevel, LogLevels } from "./log-levels";
+
+const LOG_LEVEL_COLORS: Record<number, string> = {
+	[LogLevels.CRITICAL]: "\x1b[31m", // Red
+	[LogLevels.ERROR]: "\x1b[31m", // Red
+	[LogLevels.WARN]: "\x1b[33m", // Yellow
+	[LogLevels.INFO]: "\x1b[32m", // Green
+	[LogLevels.DEBUG]: "\x1b[36m", // Cyan
+	[LogLevels.TRACE]: "\x1b[36m", // Cyan
+};
+
+const RESET_COLOR = "\x1b[0m";
+
+/**
+ * Serializes logfmt line from an object.
+ *
+ * ## Styling Methodology
+ *
+ * The three things you need to know for every log line is the level, the
+ * message, and who called it. These properties are highlighted in different colros
+ * and sorted in th eorder that you usually read them.
+ *
+ * Once you've found a log line you care about, then you want to find the
+ * property you need to see. The property names are bolded and the default color
+ * while the rest of the data is dim. This lets you scan to find the property
+ * name quickly then look closer to read the data associated with the
+ * property.
+ */
+export function stringify(data: any) {
+	let line = "";
+	const entries = Object.entries(data);
+
+	for (let i = 0; i < entries.length; i++) {
+		const [key, valueRaw] = entries[i];
+
+		let isNull = false;
+		let valueString: string;
+		if (valueRaw == null) {
+			isNull = true;
+			valueString = "";
+		} else {
+			valueString = valueRaw.toString();
+		}
+
+		// Clip value unless specifically the error message
+		if (valueString.length > 512 && key !== "msg" && key !== "error")
+			valueString = `${valueString.slice(0, 512)}...`;
+
+		const needsQuoting =
+			valueString.indexOf(" ") > -1 || valueString.indexOf("=") > -1;
+		const needsEscaping =
+			valueString.indexOf('"') > -1 || valueString.indexOf("\\") > -1;
+
+		valueString = valueString.replace(/\n/g, "\\n");
+		if (needsEscaping) valueString = valueString.replace(/["\\]/g, "\\$&");
+		if (needsQuoting || needsEscaping) valueString = `"${valueString}"`;
+		if (valueString === "" && !isNull) valueString = '""';
+
+		if (LOGGER_CONFIG.enableColor) {
+			// With color
+
+			// Special message colors
+			let color = "\x1b[2m";
+			if (key === "level") {
+				const level = LogLevels[valueString as LogLevel];
+				const levelColor = LOG_LEVEL_COLORS[level];
+				if (levelColor) {
+					color = levelColor;
+				}
+			} else if (key === "msg") {
+				color = "\x1b[32m";
+			} else if (key === "trace") {
+				color = "\x1b[34m";
+			}
+
+			// Format line
+			line += `\x1b[0m\x1b[1m${key}\x1b[0m\x1b[2m=\x1b[0m${color}${valueString}${RESET_COLOR}`;
+		} else {
+			// No color
+			line += `${key}=${valueString}`;
+		}
+
+		if (i !== entries.length - 1) {
+			line += " ";
+		}
+	}
+
+	return line;
+}
+
+export function formatTimestamp(date: Date): string {
+	const year = date.getUTCFullYear();
+	const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+	const day = String(date.getUTCDate()).padStart(2, "0");
+	const hours = String(date.getUTCHours()).padStart(2, "0");
+	const minutes = String(date.getUTCMinutes()).padStart(2, "0");
+	const seconds = String(date.getUTCSeconds()).padStart(2, "0");
+	const milliseconds = String(date.getUTCMilliseconds()).padStart(3, "0");
+
+	return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}.${milliseconds}Z`;
+}
+
+export function castToLogValue(v: unknown): any {
+	if (
+		typeof v === "string" ||
+		typeof v === "number" ||
+		typeof v === "bigint" ||
+		typeof v === "boolean" ||
+		v === null ||
+		v === undefined
+	) {
+		return v;
+	}
+	if (v instanceof Error) {
+		//args.push(...errorToLogEntries(k, v));
+		return String(v);
+	}
+	try {
+		return JSON.stringify(v);
+	} catch {
+		return "[cannot stringify]";
+	}
+}
+
+// MARK: Config
+interface GlobalLoggerConfig {
+	enableColor: boolean;
+	enableSpreadObject: boolean;
+	enableErrorStack: boolean;
+}
+
+export const LOGGER_CONFIG: GlobalLoggerConfig = {
+	enableColor: false,
+	enableSpreadObject: false,
+	enableErrorStack: false,
+};
+
+// MARK: Utils
+/**
+ * Converts an object in to an easier to read KV of entries.
+ */
+export function spreadObjectToLogEntries(base: string, data: unknown): any {
+	if (
+		LOGGER_CONFIG.enableSpreadObject &&
+		typeof data === "object" &&
+		!Array.isArray(data) &&
+		data !== null &&
+		Object.keys(data).length !== 0 &&
+		Object.keys(data).length < 16
+	) {
+		const logData: any = {};
+		for (const key in data) {
+			Object.assign(
+				logData,
+				spreadObjectToLogEntries(
+					`${base}.${key}`,
+					// biome-ignore lint/suspicious/noExplicitAny: FIXME
+					(data as any)[key],
+				),
+			);
+		}
+		return logData;
+	}
+
+	return { [base]: JSON.stringify(data) };
+}
+
+export function errorToLogEntries(base: string, error: unknown): any {
+	if (error instanceof Error) {
+		return {
+			[`${base}.message`]: error.message,
+			...(LOGGER_CONFIG.enableErrorStack && error.stack
+				? { [`${base}.stack`]: formatStackTrace(error.stack) }
+				: {}),
+			...(error.cause
+				? errorToLogEntries(`${base}.cause`, error.cause)
+				: {}),
+		};
+	}
+	return { [base]: `${error}` };
+}
+
+// export function errorToLogEntries(base: string, error: unknown): LogEntry[] {
+// 	if (error instanceof RuntimeError) {
+// 		return [
+// 			[`${base}.code`, error.code],
+// 			[`${base}.description`, error.errorConfig?.description],
+// 			[`${base}.module`, error.moduleName],
+// 			...(error.trace ? [[`${base}.trace`, stringifyTrace(error.trace)] as LogEntry] : []),
+// 			...(LOGGER_CONFIG.enableErrorStack && error.stack
+// 				? [[`${base}.stack`, formatStackTrace(error.stack)] as LogEntry]
+// 				: []),
+// 			...(error.meta ? [[`${base}.meta`, JSON.stringify(error.meta)] as LogEntry] : []),
+// 			...(error.cause ? errorToLogEntries(`${base}.cause`, error.cause) : []),
+// 		];
+// 	} else if (error instanceof Error) {
+// 		return [
+// 			[`${base}.name`, error.name],
+// 			[`${base}.message`, error.message],
+// 			...(LOGGER_CONFIG.enableErrorStack && error.stack
+// 				? [[`${base}.stack`, formatStackTrace(error.stack)] as LogEntry]
+// 				: []),
+// 			...(error.cause ? errorToLogEntries(`${base}.cause`, error.cause) : []),
+// 		];
+// 	} else {
+// 		return [
+// 			[base, `${error}`],
+// 		];
+// 	}
+// }
+
+/**
+ * Formats a JS stack trace in to a legible one-liner.
+ */
+function formatStackTrace(stackTrace: string): string {
+	const regex = /at (.+?)$/gm;
+	const matches = [...stackTrace.matchAll(regex)];
+	// Reverse array since the stack goes from top level -> bottom level
+	matches.reverse();
+	return matches.map((match) => match[1].trim()).join(" > ");
+}

package/src/common/network.ts

@@ -0,0 +1,2 @@
+/** Only enforced client-side in order to prevent building malformed URLs. */
+export const MAX_CONN_PARAMS_SIZE = 4096;

package/src/common/router.ts

@@ -0,0 +1,174 @@
+import * as cbor from "cbor-x";
+import type { Context as HonoContext, Next } from "hono";
+import type { Encoding } from "@/actor/protocol/serde";
+import {
+	getRequestEncoding,
+	getRequestExposeInternalError,
+} from "@/actor/router-endpoints";
+import {
+	buildActorNames,
+	type RegistryConfig,
+} from "@/registry/config";
+import type * as protocol from "@/schemas/client-protocol/mod";
+import {
+	CURRENT_VERSION as CLIENT_PROTOCOL_CURRENT_VERSION,
+	HTTP_RESPONSE_ERROR_VERSIONED,
+} from "@/schemas/client-protocol/versioned";
+import {
+	type HttpResponseError as HttpResponseErrorJson,
+	HttpResponseErrorSchema,
+} from "@/schemas/client-protocol-zod/mod";
+import { encodingIsBinary, serializeWithEncoding } from "@/serde";
+import { bufferToArrayBuffer, VERSION } from "@/utils";
+import { getLogHeaders } from "@/utils/env-vars";
+import { getLogger, type Logger } from "./log";
+import { deconstructError, stringifyError } from "./utils";
+
+export function logger() {
+	return getLogger("router");
+}
+
+export function loggerMiddleware(logger: Logger) {
+	return async (c: HonoContext, next: Next) => {
+		const method = c.req.method;
+		const path = c.req.path;
+		const startTime = Date.now();
+
+		await next();
+
+		const duration = Date.now() - startTime;
+		logger.debug({
+			msg: "http request",
+			method,
+			path,
+			status: c.res.status,
+			dt: `${duration}ms`,
+			reqSize: c.req.header("content-length"),
+			resSize: c.res.headers.get("content-length"),
+			userAgent: c.req.header("user-agent"),
+			...(getLogHeaders()
+				? { allHeaders: JSON.stringify(c.req.header()) }
+				: {}),
+		});
+	};
+}
+
+export function handleRouteNotFound(c: HonoContext) {
+	return c.text("Not Found (RivetKit)", 404);
+}
+
+export function handleRouteError(error: unknown, c: HonoContext) {
+	const exposeInternalError = getRequestExposeInternalError(c.req.raw);
+
+	const { statusCode, group, code, message, metadata } = deconstructError(
+		error,
+		logger(),
+		{
+			method: c.req.method,
+			path: c.req.path,
+		},
+		exposeInternalError,
+	);
+
+	let encoding: Encoding;
+	try {
+		encoding = getRequestEncoding(c.req);
+	} catch (_) {
+		encoding = "json";
+	}
+
+	const errorData = { group, code, message, metadata };
+	const output = serializeWithEncoding(
+		encoding,
+		errorData,
+		HTTP_RESPONSE_ERROR_VERSIONED,
+		CLIENT_PROTOCOL_CURRENT_VERSION,
+		HttpResponseErrorSchema,
+		// JSON: metadata is the raw value (will be serialized by jsonStringifyCompat)
+		(value): HttpResponseErrorJson => ({
+			group: value.group,
+			code: value.code,
+			message: value.message,
+			metadata: value.metadata,
+		}),
+		// BARE/CBOR: metadata needs to be CBOR-encoded to ArrayBuffer
+		(value): protocol.HttpResponseError => ({
+			group: value.group,
+			code: value.code,
+			message: value.message,
+			metadata: value.metadata
+				? bufferToArrayBuffer(cbor.encode(value.metadata))
+				: null,
+		}),
+	);
+
+	// TODO: Remove any
+	return c.body(output as any, { status: statusCode });
+}
+
+export type MetadataRunnerKind =
+	| { serverless: Record<never, never> }
+	| { normal: Record<never, never> };
+
+/**
+ * Metadata response interface for the /metadata endpoint
+ */
+export interface MetadataResponse {
+	runtime: string;
+	version: string;
+	runner?: {
+		kind: MetadataRunnerKind;
+		version?: number;
+	};
+	actorNames: ReturnType<typeof buildActorNames>;
+	/**
+	 * Endpoint that the client should connect to to access this runner.
+	 *
+	 * If defined, will override the endpoint the user has configured on startup.
+	 *
+	 * This is helpful if attempting to connect to a serverless runner, so the serverless runner can define where the main endpoint lives.
+	 *
+	 * This is also helpful for setting up clean redirects as needed.
+	 **/
+	clientEndpoint?: string;
+	/**
+	 * Namespace that the client should use when connecting.
+	 **/
+	clientNamespace?: string;
+	/**
+	 * Token that the client should use when connecting.
+	 **/
+	clientToken?: string;
+}
+
+export function handleMetadataRequest(
+	c: HonoContext,
+	config: RegistryConfig,
+	runnerKind: MetadataRunnerKind,
+	clientEndpoint: string | undefined,
+	clientNamespace: string | undefined,
+	clientToken: string | undefined,
+) {
+	const response: MetadataResponse = {
+		runtime: "rivetkit",
+		version: VERSION,
+		runner: {
+			kind: runnerKind,
+			version: config.runner.version,
+		},
+		actorNames: buildActorNames(config),
+		clientEndpoint,
+		clientNamespace,
+		clientToken,
+	};
+
+	return c.json(response);
+}
+
+export function handleHealthRequest(c: HonoContext) {
+	return c.json({
+		status: "ok",
+		runtime: "rivetkit",
+		version: VERSION,
+	});
+}