rivetkit 2.0.2 → 2.0.3

package/src/common/logfmt.ts

@@ -0,0 +1,228 @@
+import { type LogLevel, LogLevels } from "./log-levels";
+
+export type LogEntry = [string, LogValue];
+export type LogValue = string | number | bigint | boolean | null | undefined;
+
+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 using orderer parameters.
+ *
+ * We use varargs because it's ordered & it has less overhead than 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: LogEntry[]) {
+	let line = "";
+
+	for (let i = 0; i < data.length; i++) {
+		const [key, valueRaw] = data[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 !== data.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): LogValue {
+	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,
+): LogEntry[] {
+	if (
+		LOGGER_CONFIG.enableSpreadObject &&
+		typeof data === "object" &&
+		!Array.isArray(data) &&
+		data !== null &&
+		Object.keys(data).length !== 0 &&
+		Object.keys(data).length < 16
+	) {
+		const logData: LogEntry[] = [];
+		for (const key in data) {
+			// logData.push([`${base}.${key}`, JSON.stringify((data as any)[key])]);
+
+			logData.push(
+				...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): LogEntry[] {
+	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) : []),
+		];
+	}
+	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,87 @@
+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 { HttpResponseError } from "@/schemas/client-protocol/mod";
+import { HTTP_RESPONSE_ERROR_VERSIONED } from "@/schemas/client-protocol/versioned";
+import { serializeWithEncoding } from "@/serde";
+import { bufferToArrayBuffer } from "@/utils";
+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("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"),
+		});
+	};
+}
+
+export function handleRouteNotFound(c: HonoContext) {
+	return c.text("Not Found (RivetKit)", 404);
+}
+
+export interface HandleRouterErrorOpts {
+	enableExposeInternalError?: boolean;
+}
+
+export function handleRouteError(
+	opts: HandleRouterErrorOpts,
+	error: unknown,
+	c: HonoContext,
+) {
+	const exposeInternalError =
+		opts.enableExposeInternalError && getRequestExposeInternalError(c.req.raw);
+
+	const { statusCode, code, message, metadata } = deconstructError(
+		error,
+		logger(),
+		{
+			method: c.req.method,
+			path: c.req.path,
+		},
+		exposeInternalError,
+	);
+
+	let encoding: Encoding;
+	try {
+		encoding = getRequestEncoding(c.req);
+	} catch (err) {
+		logger().debug("failed to extract encoding", {
+			error: stringifyError(err),
+		});
+		encoding = "json";
+	}
+
+	const output = serializeWithEncoding(
+		encoding,
+		{
+			code,
+			message,
+			metadata: bufferToArrayBuffer(cbor.encode(metadata)),
+		},
+		HTTP_RESPONSE_ERROR_VERSIONED,
+	);
+
+	return c.body(output, { status: statusCode });
+}

package/src/common/utils.ts

@@ -0,0 +1,322 @@
+import type { Next } from "hono";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import * as errors from "@/actor/errors";
+import { getEnvUniversal } from "@/utils";
+import type { Logger } from "./log";
+
+export function assertUnreachable(x: never): never {
+	throw new Error(`Unreachable case: ${x}`);
+}
+
+/**
+ * Safely stringifies an object, ensuring that the stringified object is under a certain size.
+ * @param obj any object to stringify
+ * @param maxSize maximum size of the stringified object in bytes
+ * @returns stringified object
+ */
+export function safeStringify(obj: unknown, maxSize: number) {
+	let size = 0;
+
+	function replacer(key: string, value: unknown) {
+		if (value === null || value === undefined) return value;
+		const valueSize =
+			typeof value === "string" ? value.length : JSON.stringify(value).length;
+		size += key.length + valueSize;
+
+		if (size > maxSize) {
+			throw new Error(`JSON object exceeds size limit of ${maxSize} bytes.`);
+		}
+
+		return value;
+	}
+
+	return JSON.stringify(obj, replacer);
+}
+
+// TODO: Instead of doing this, use a temp var for state and attempt to write
+// it. Roll back state if fails to serialize.
+
+/**
+ * Check if a value is CBOR serializable.
+ * Optionally pass an onInvalid callback to receive the path to invalid values.
+ *
+ * For a complete list of supported CBOR tags, see:
+ * https://github.com/kriszyp/cbor-x/blob/cc1cf9df8ba72288c7842af1dd374d73e34cdbc1/README.md#list-of-supported-tags-for-decoding
+ */
+export function isCborSerializable(
+	value: unknown,
+	onInvalid?: (path: string) => void,
+	currentPath = "",
+): boolean {
+	// Handle primitive types directly
+	if (value === null || value === undefined) {
+		return true;
+	}
+
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) {
+			onInvalid?.(currentPath);
+			return false;
+		}
+		return true;
+	}
+
+	if (typeof value === "boolean" || typeof value === "string") {
+		return true;
+	}
+
+	// Handle BigInt (CBOR tags 2 and 3)
+	if (typeof value === "bigint") {
+		return true;
+	}
+
+	// Handle Date objects (CBOR tags 0 and 1)
+	if (value instanceof Date) {
+		return true;
+	}
+
+	// Handle typed arrays (CBOR tags 64-82)
+	if (
+		value instanceof Uint8Array ||
+		value instanceof Uint8ClampedArray ||
+		value instanceof Uint16Array ||
+		value instanceof Uint32Array ||
+		value instanceof BigUint64Array ||
+		value instanceof Int8Array ||
+		value instanceof Int16Array ||
+		value instanceof Int32Array ||
+		value instanceof BigInt64Array ||
+		value instanceof Float32Array ||
+		value instanceof Float64Array
+	) {
+		return true;
+	}
+
+	// Handle Map (CBOR tag 259)
+	if (value instanceof Map) {
+		for (const [key, val] of value.entries()) {
+			const keyPath = currentPath
+				? `${currentPath}.key(${String(key)})`
+				: `key(${String(key)})`;
+			const valPath = currentPath
+				? `${currentPath}.value(${String(key)})`
+				: `value(${String(key)})`;
+			if (
+				!isCborSerializable(key, onInvalid, keyPath) ||
+				!isCborSerializable(val, onInvalid, valPath)
+			) {
+				return false;
+			}
+		}
+		return true;
+	}
+
+	// Handle Set (CBOR tag 258)
+	if (value instanceof Set) {
+		let index = 0;
+		for (const item of value.values()) {
+			const itemPath = currentPath
+				? `${currentPath}.set[${index}]`
+				: `set[${index}]`;
+			if (!isCborSerializable(item, onInvalid, itemPath)) {
+				return false;
+			}
+			index++;
+		}
+		return true;
+	}
+
+	// Handle RegExp (CBOR tag 27)
+	if (value instanceof RegExp) {
+		return true;
+	}
+
+	// Handle Error objects (CBOR tag 27)
+	if (value instanceof Error) {
+		return true;
+	}
+
+	// Handle arrays
+	if (Array.isArray(value)) {
+		for (let i = 0; i < value.length; i++) {
+			const itemPath = currentPath ? `${currentPath}[${i}]` : `[${i}]`;
+			if (!isCborSerializable(value[i], onInvalid, itemPath)) {
+				return false;
+			}
+		}
+		return true;
+	}
+
+	// Handle plain objects and records (CBOR tags 105, 51, 57344-57599)
+	if (typeof value === "object") {
+		// Allow plain objects and objects with prototypes (for records and named objects)
+		const proto = Object.getPrototypeOf(value);
+		if (proto !== null && proto !== Object.prototype) {
+			// Check if it's a known serializable object type
+			const protoConstructor = value.constructor;
+			if (protoConstructor && typeof protoConstructor.name === "string") {
+				// Allow objects with named constructors (records, named objects)
+				// This includes user-defined classes and built-in objects
+				// that CBOR can serialize with tag 27 or record tags
+			}
+		}
+
+		// Check all properties recursively
+		for (const key in value) {
+			const propPath = currentPath ? `${currentPath}.${key}` : key;
+			if (
+				!isCborSerializable(
+					value[key as keyof typeof value],
+					onInvalid,
+					propPath,
+				)
+			) {
+				return false;
+			}
+		}
+		return true;
+	}
+
+	// Not serializable
+	onInvalid?.(currentPath);
+	return false;
+}
+
+export interface DeconstructedError {
+	__type: "ActorError";
+	statusCode: ContentfulStatusCode;
+	public: boolean;
+	code: string;
+	message: string;
+	metadata?: unknown;
+}
+
+/** Deconstructs error in to components that are used to build responses. */
+export function deconstructError(
+	error: unknown,
+	logger: Logger,
+	extraLog: Record<string, unknown>,
+	exposeInternalError = false,
+): DeconstructedError {
+	// Build response error information. Only return errors if flagged as public in order to prevent leaking internal behavior.
+	//
+	// We log the error here instead of after generating the code & message because we need to log the original error, not the masked internal error.
+	let statusCode: ContentfulStatusCode;
+	let public_: boolean;
+	let code: string;
+	let message: string;
+	let metadata: unknown;
+	if (errors.ActorError.isActorError(error) && error.public) {
+		// Check if error has statusCode (could be ActorError instance or DeconstructedError)
+		statusCode = (
+			"statusCode" in error && error.statusCode ? error.statusCode : 400
+		) as ContentfulStatusCode;
+		public_ = true;
+		code = error.code;
+		message = getErrorMessage(error);
+		metadata = error.metadata;
+
+		logger.info("public error", {
+			code,
+			message,
+			issues: "https://github.com/rivet-gg/rivetkit/issues",
+			support: "https://rivet.gg/discord",
+			...extraLog,
+		});
+	} else if (exposeInternalError) {
+		if (errors.ActorError.isActorError(error)) {
+			statusCode = 500;
+			public_ = false;
+			code = error.code;
+			message = getErrorMessage(error);
+			metadata = error.metadata;
+
+			logger.info("internal error", {
+				code,
+				message,
+				issues: "https://github.com/rivet-gg/rivetkit/issues",
+				support: "https://rivet.gg/discord",
+				...extraLog,
+			});
+		} else {
+			statusCode = 500;
+			public_ = false;
+			code = errors.INTERNAL_ERROR_CODE;
+			message = getErrorMessage(error);
+
+			logger.info("internal error", {
+				code,
+				message,
+				issues: "https://github.com/rivet-gg/rivetkit/issues",
+				support: "https://rivet.gg/discord",
+				...extraLog,
+			});
+		}
+	} else {
+		statusCode = 500;
+		public_ = false;
+		code = errors.INTERNAL_ERROR_CODE;
+		message = errors.INTERNAL_ERROR_DESCRIPTION;
+		metadata = {
+			//url: `https://hub.rivet.gg/projects/${actorMetadata.project.slug}/environments/${actorMetadata.environment.slug}/actors?actorId=${actorMetadata.actor.id}`,
+		} satisfies errors.InternalErrorMetadata;
+
+		logger.warn("internal error", {
+			error: getErrorMessage(error),
+			stack: (error as Error)?.stack,
+			issues: "https://github.com/rivet-gg/rivetkit/issues",
+			support: "https://rivet.gg/discord",
+			...extraLog,
+		});
+	}
+
+	return {
+		__type: "ActorError",
+		statusCode,
+		public: public_,
+		code,
+		message,
+		metadata,
+	};
+}
+
+export function stringifyError(error: unknown): string {
+	if (error instanceof Error) {
+		if (
+			typeof process !== "undefined" &&
+			getEnvUniversal("_RIVETKIT_ERROR_STACK") === "1"
+		) {
+			return `${error.name}: ${error.message}${error.stack ? `\n${error.stack}` : ""}`;
+		} else {
+			return `${error.name}: ${error.message}`;
+		}
+	} else if (typeof error === "string") {
+		return error;
+	} else if (typeof error === "object" && error !== null) {
+		try {
+			return `${JSON.stringify(error)}`;
+		} catch {
+			return "[cannot stringify error]";
+		}
+	} else {
+		return `Unknown error: ${getErrorMessage(error)}`;
+	}
+}
+
+function getErrorMessage(err: unknown): string {
+	if (
+		err &&
+		typeof err === "object" &&
+		"message" in err &&
+		typeof err.message === "string"
+	) {
+		return err.message;
+	} else {
+		return String(err);
+	}
+}
+
+/** Generates a `Next` handler to pass to middleware in order to be able to call arbitrary middleware. */
+export function noopNext(): Next {
+	return async () => {};
+}