rivetkit 2.0.2 → 2.0.4-rc.1

package/src/client/utils.ts

@@ -0,0 +1,252 @@
+import * as cbor from "cbor-x";
+import invariant from "invariant";
+import type { VersionedDataHandler } from "vbare";
+import type { z } from "zod/v4";
+import type { Encoding } from "@/actor/protocol/serde";
+import { assertUnreachable } from "@/common/utils";
+import type { HttpResponseError } from "@/schemas/client-protocol/mod";
+import { HTTP_RESPONSE_ERROR_VERSIONED } from "@/schemas/client-protocol/versioned";
+import {
+	type HttpResponseError as HttpResponseErrorJson,
+	HttpResponseErrorSchema,
+} from "@/schemas/client-protocol-zod/mod";
+import {
+	contentTypeForEncoding,
+	deserializeWithEncoding,
+	encodingIsBinary,
+	serializeWithEncoding,
+} from "@/serde";
+import { httpUserAgent } from "@/utils";
+import { ActorError, HttpRequestError } from "./errors";
+import { logger } from "./log";
+
+export interface ParsedCloseReason {
+	group: string;
+	code: string;
+	rayId?: string;
+}
+
+/**
+ * Parses WebSocket close reason string into structured data.
+ *
+ * Expected format examples:
+ *   - "guard.actor_runner_failed#t1s80so6h3irenp8ymzltfoittcl00"
+ *   - "ws.client_closed"
+ *
+ * Returns undefined if the format is invalid
+ */
+export function parseWebSocketCloseReason(
+	reason: string,
+): ParsedCloseReason | undefined {
+	const [mainPart, rayId] = reason.split("#");
+	const [group, code] = mainPart.split(".");
+
+	if (!group || !code) {
+		logger().warn({ msg: "failed to parse close reason", reason });
+		return undefined;
+	}
+
+	return {
+		group,
+		code,
+		rayId,
+	};
+}
+
+export type WebSocketMessage = string | Blob | ArrayBuffer | Uint8Array;
+
+export function messageLength(message: WebSocketMessage): number {
+	if (message instanceof Blob) {
+		return message.size;
+	}
+	if (message instanceof ArrayBuffer) {
+		return message.byteLength;
+	}
+	if (message instanceof Uint8Array) {
+		return message.byteLength;
+	}
+	if (typeof message === "string") {
+		return message.length;
+	}
+	assertUnreachable(message);
+}
+
+export interface HttpRequestOpts<
+	RequestBare,
+	ResponseBare,
+	RequestJson = RequestBare,
+	ResponseJson = ResponseBare,
+	Request = RequestBare,
+	Response = ResponseBare,
+> {
+	method: string;
+	url: string;
+	headers: Record<string, string>;
+	body?: Request;
+	encoding: Encoding;
+	skipParseResponse?: boolean;
+	signal?: AbortSignal;
+	customFetch?: (req: globalThis.Request) => Promise<globalThis.Response>;
+	requestVersionedDataHandler: VersionedDataHandler<RequestBare> | undefined;
+	requestVersion: number | undefined;
+	responseVersionedDataHandler:
+		| VersionedDataHandler<ResponseBare>
+		| undefined;
+	responseVersion: number | undefined;
+	requestZodSchema: z.ZodType<RequestJson>;
+	responseZodSchema: z.ZodType<ResponseJson>;
+	requestToJson: (value: Request) => RequestJson;
+	requestToBare: (value: Request) => RequestBare;
+	responseFromJson: (value: ResponseJson) => Response;
+	responseFromBare: (value: ResponseBare) => Response;
+}
+
+export async function sendHttpRequest<
+	RequestBare = unknown,
+	ResponseBare = unknown,
+	RequestJson = RequestBare,
+	ResponseJson = ResponseBare,
+	Request = RequestBare,
+	Response = ResponseBare,
+>(
+	opts: HttpRequestOpts<
+		RequestBare,
+		ResponseBare,
+		RequestJson,
+		ResponseJson,
+		Request,
+		Response
+	>,
+): Promise<Response> {
+	logger().debug({
+		msg: "sending http request",
+		url: opts.url,
+		encoding: opts.encoding,
+	});
+
+	// Serialize body
+	let contentType: string | undefined;
+	let bodyData: string | Uint8Array | undefined;
+	if (opts.method === "POST" || opts.method === "PUT") {
+		invariant(opts.body !== undefined, "missing body");
+		contentType = contentTypeForEncoding(opts.encoding);
+		bodyData = serializeWithEncoding<RequestBare, RequestJson, Request>(
+			opts.encoding,
+			opts.body,
+			opts.requestVersionedDataHandler,
+			opts.requestVersion,
+			opts.requestZodSchema,
+			opts.requestToJson,
+			opts.requestToBare,
+		);
+	}
+
+	// Send request
+	let response: globalThis.Response;
+	try {
+		// Make the HTTP request
+		response = await (opts.customFetch ?? fetch)(
+			new globalThis.Request(opts.url, {
+				method: opts.method,
+				headers: {
+					...opts.headers,
+					...(contentType
+						? {
+								"Content-Type": contentType,
+							}
+						: {}),
+					"User-Agent": httpUserAgent(),
+				},
+				body: bodyData,
+				credentials: "include",
+				signal: opts.signal,
+			}),
+		);
+	} catch (error) {
+		throw new HttpRequestError(`Request failed: ${error}`, {
+			cause: error,
+		});
+	}
+
+	// Parse response error
+	if (!response.ok) {
+		const bufferResponse = await response.arrayBuffer();
+		const contentType = response.headers.get("content-type");
+		const rayId = response.headers.get("x-rivet-ray-id");
+
+		// Determine encoding from Content-Type header, defaulting to provided encoding
+		const encoding: Encoding = contentType?.includes("application/json")
+			? "json"
+			: opts.encoding;
+
+		// Attempt to parse structured error data
+		try {
+			const responseData = deserializeWithEncoding(
+				encoding,
+				new Uint8Array(bufferResponse),
+				HTTP_RESPONSE_ERROR_VERSIONED,
+				HttpResponseErrorSchema,
+				// JSON: metadata is already unknown
+				(json): HttpResponseErrorJson => json as HttpResponseErrorJson,
+				// BARE: decode ArrayBuffer metadata to unknown
+				(bare): any => ({
+					group: bare.group,
+					code: bare.code,
+					message: bare.message,
+					metadata: bare.metadata
+						? cbor.decode(new Uint8Array(bare.metadata))
+						: undefined,
+				}),
+			);
+
+			throw new ActorError(
+				responseData.group,
+				responseData.code,
+				responseData.message,
+				responseData.metadata,
+			);
+		} catch (error) {
+			// If it's already an ActorError, re-throw it
+			if (error instanceof ActorError) {
+				throw error;
+			}
+
+			// Otherwise, fall back to generic error with text response
+			const textResponse = new TextDecoder("utf-8", {
+				fatal: false,
+			}).decode(bufferResponse);
+
+			if (rayId) {
+				throw new HttpRequestError(
+					`${response.statusText} (${response.status}) (Ray ID: ${rayId}):\n${textResponse}`,
+				);
+			} else {
+				throw new HttpRequestError(
+					`${response.statusText} (${response.status}):\n${textResponse}`,
+				);
+			}
+		}
+	}
+
+	// Some requests don't need the success response to be parsed, so this can speed things up
+	if (opts.skipParseResponse) {
+		return undefined as Response;
+	}
+
+	// Parse the response based on encoding
+	try {
+		const buffer = new Uint8Array(await response.arrayBuffer());
+		return deserializeWithEncoding<ResponseBare, ResponseJson, Response>(
+			opts.encoding,
+			buffer,
+			opts.responseVersionedDataHandler,
+			opts.responseZodSchema,
+			opts.responseFromJson,
+			opts.responseFromBare,
+		);
+	} catch (error) {
+		throw new HttpRequestError(`Failed to parse response: ${error}`, {
+			cause: error,
+		});
+	}
+}

package/src/common/actor-router-consts.ts

@@ -0,0 +1,59 @@
+// NOTE: This is in a separate file from the router since it needs to be shared between the client & the server. If this was in the router file, the client would end up importing the *entire* actor router and tree shaking would not work.
+
+// MARK: Paths
+export const PATH_CONNECT = "/connect";
+export const PATH_WEBSOCKET_BASE = "/websocket";
+export const PATH_WEBSOCKET_PREFIX = "/websocket/";
+export const PATH_INSPECTOR_CONNECT = "/inspector/connect";
+
+// MARK: Headers
+export const HEADER_ACTOR_QUERY = "x-rivet-query";
+
+export const HEADER_ENCODING = "x-rivet-encoding";
+
+// IMPORTANT: Params must be in headers or in an E2EE part of the request (i.e. NOT the URL or query string) in order to ensure that tokens can be securely passed in params.
+export const HEADER_CONN_PARAMS = "x-rivet-conn-params";
+
+export const HEADER_ACTOR_ID = "x-rivet-actor";
+
+export const HEADER_RIVET_TOKEN = "x-rivet-token";
+
+// MARK: Manager Gateway Headers
+export const HEADER_RIVET_TARGET = "x-rivet-target";
+export const HEADER_RIVET_ACTOR = "x-rivet-actor";
+export const HEADER_RIVET_NAMESPACE = "x-rivet-namespace";
+
+// MARK: WebSocket Protocol Prefixes
+/** Some servers (such as node-ws & Cloudflare) require explicitly match a certain WebSocket protocol. This gives us a static protocol to match against. */
+export const WS_PROTOCOL_STANDARD = "rivet";
+export const WS_PROTOCOL_TARGET = "rivet_target.";
+export const WS_PROTOCOL_ACTOR = "rivet_actor.";
+export const WS_PROTOCOL_ENCODING = "rivet_encoding.";
+export const WS_PROTOCOL_CONN_PARAMS = "rivet_conn_params.";
+export const WS_PROTOCOL_TOKEN = "rivet_token.";
+/**
+ * Used to pass an inspector token for connecting to the inspector.
+ * Only used internally by Rivet.
+ */
+export const WS_PROTOCOL_INSPECTOR_TOKEN = "rivet_inspector_token.";
+
+// MARK: WebSocket Inline Test Protocol Prefixes
+export const WS_TEST_PROTOCOL_PATH = "test_path.";
+
+/**
+ * Headers that publics can send from public clients.
+ *
+ * Used for CORS.
+ **/
+export const ALLOWED_PUBLIC_HEADERS = [
+	"Content-Type",
+	"User-Agent",
+	HEADER_ACTOR_QUERY,
+	HEADER_ENCODING,
+	HEADER_CONN_PARAMS,
+	HEADER_ACTOR_ID,
+	HEADER_RIVET_TARGET,
+	HEADER_RIVET_ACTOR,
+	HEADER_RIVET_NAMESPACE,
+	HEADER_RIVET_TOKEN,
+];

package/src/common/cors.ts

@@ -0,0 +1,57 @@
+import type { MiddlewareHandler } from "hono";
+
+/**
+ * Simple CORS middleware that matches the gateway behavior.
+ *
+ * - Echoes back the Origin header from the request
+ * - Echoes back the Access-Control-Request-Headers from preflight
+ * - Supports credentials
+ * - Allows common HTTP methods
+ * - Caches preflight for 24 hours
+ * - Adds Vary header to prevent cache poisoning
+ */
+export const cors = (): MiddlewareHandler => {
+	return async (c, next) => {
+		// Extract origin from request
+		const origin = c.req.header("origin") || "*";
+
+		// Handle preflight OPTIONS request
+		if (c.req.method === "OPTIONS") {
+			const requestHeaders =
+				c.req.header("access-control-request-headers") || "*";
+
+			c.header("access-control-allow-origin", origin);
+			c.header("access-control-allow-credentials", "true");
+			c.header(
+				"access-control-allow-methods",
+				"GET, POST, PUT, DELETE, OPTIONS, PATCH",
+			);
+			c.header("access-control-allow-headers", requestHeaders);
+			c.header("access-control-expose-headers", "*");
+			c.header("access-control-max-age", "86400");
+
+			// Add Vary header to prevent cache poisoning when echoing origin
+			if (origin !== "*") {
+				c.header("vary", "Origin");
+			}
+
+			// Remove content headers from preflight response
+			c.res.headers.delete("content-length");
+			c.res.headers.delete("content-type");
+
+			return c.body(null, 204);
+		}
+
+		await next();
+
+		// Add CORS headers to actual request
+		c.header("access-control-allow-origin", origin);
+		c.header("access-control-allow-credentials", "true");
+		c.header("access-control-expose-headers", "*");
+
+		// Add Vary header to prevent cache poisoning when echoing origin
+		if (origin !== "*") {
+			c.header("vary", "Origin");
+		}
+	};
+};

package/src/common/eventsource-interface.ts

@@ -0,0 +1,47 @@
+// Define minimal event interfaces to avoid conflicts between different EventSource implementations
+export interface UniversalEvent {
+	type: string;
+	target?: any;
+	currentTarget?: any;
+}
+
+export interface UniversalMessageEvent extends UniversalEvent {
+	data: string;
+	lastEventId: string;
+	origin: string;
+}
+
+export interface UniversalErrorEvent extends UniversalEvent {
+	message: string;
+	filename?: string;
+	lineno?: number;
+	colno?: number;
+	error?: any;
+}
+
+/**
+ * Common EventSource interface that can be implemented by different EventSource-like classes
+ * This is compatible with the standard EventSource API but allows for custom implementations
+ */
+export interface UniversalEventSource {
+	// EventSource readyState values
+	readonly CONNECTING: 0;
+	readonly OPEN: 1;
+	readonly CLOSED: 2;
+
+	// Properties
+	readonly readyState: 0 | 1 | 2;
+	readonly url: string;
+	readonly withCredentials: boolean;
+
+	// Methods
+	close(): void;
+	addEventListener(type: string, listener: (event: any) => void): void;
+	removeEventListener(type: string, listener: (event: any) => void): void;
+	dispatchEvent(event: UniversalEvent): boolean;
+
+	// Event handlers (optional)
+	onopen?: ((event: UniversalEvent) => void) | null;
+	onmessage?: ((event: UniversalMessageEvent) => void) | null;
+	onerror?: ((event: UniversalErrorEvent) => void) | null;
+}

package/src/common/eventsource.ts

@@ -0,0 +1,44 @@
+import type { EventSource } from "eventsource";
+import { logger } from "@/client/log";
+
+// Global singleton promise that will be reused for subsequent calls
+let eventSourcePromise: Promise<typeof EventSource> | null = null;
+
+export async function importEventSource(): Promise<typeof EventSource> {
+	// IMPORTANT: Import `eventsource` from the custom `eventsource` library. We need a custom implementation
+	// since we need to attach our own custom headers to the request.
+	//
+	// We can't use the browser-provided EventSource since it does not allow providing custom headers.
+
+	// Return existing promise if we already started loading
+	if (eventSourcePromise !== null) {
+		return eventSourcePromise;
+	}
+
+	// Create and store the promise
+	eventSourcePromise = (async () => {
+		let _EventSource: typeof EventSource;
+
+		// Node.js environment
+		try {
+			const moduleName = "eventsource";
+			const es = await import(/* webpackIgnore: true */ moduleName);
+			_EventSource = es.EventSource;
+			logger().debug("using eventsource from npm");
+		} catch (err) {
+			// EventSource not available
+			_EventSource = class MockEventSource {
+				constructor() {
+					throw new Error(
+						'EventSource support requires installing the "eventsource" peer dependency.',
+					);
+				}
+			} as unknown as typeof EventSource;
+			logger().debug("using mock eventsource");
+		}
+
+		return _EventSource;
+	})();
+
+	return eventSourcePromise;
+}

package/src/common/inline-websocket-adapter.ts

@@ -0,0 +1,154 @@
+import { WSContext } from "hono/ws";
+import type { UpgradeWebSocketArgs } from "@/actor/router-websocket-endpoints";
+import type { UniversalWebSocket } from "@/common/websocket-interface";
+import { VirtualWebSocket } from "@rivetkit/virtual-websocket";
+import { getLogger } from "./log";
+
+function logger() {
+	return getLogger("inline-websocket-adapter");
+}
+
+/**
+ * InlineWebSocketAdapter creates two linked WebSocket objects:
+ * - clientWs: for the client/proxy side (returned from openWebSocket)
+ * - actorWs: for the actor side (passed via wsContext.raw)
+ *
+ * Each side's send() triggers the OTHER side's message event.
+ */
+export class InlineWebSocketAdapter {
+	#handler: UpgradeWebSocketArgs;
+	#wsContext: WSContext;
+	#readyState: 0 | 1 | 2 | 3 = 0;
+
+	#clientWs: VirtualWebSocket;
+	#actorWs: VirtualWebSocket;
+
+	constructor(handler: UpgradeWebSocketArgs) {
+		this.#handler = handler;
+
+		// Create linked WebSocket pair
+		// Client's send() -> handler.onMessage (for RPC) + Actor's message event (for raw WS)
+		// Actor's send() -> Client's message event
+		this.#clientWs = new VirtualWebSocket({
+			getReadyState: () => this.#readyState,
+			onSend: (data) => {
+				try {
+					// Call handler.onMessage for protocol-based connections (RPC)
+					this.#handler.onMessage({ data }, this.#wsContext);
+					// Also trigger message event on actor's websocket for raw websocket handlers
+					this.#actorWs.triggerMessage(data);
+				} catch (err) {
+					this.#handleError(err);
+					this.#close(1011, "Internal error processing message");
+				}
+			},
+			onClose: (code, reason) => this.#close(code, reason),
+		});
+
+		this.#actorWs = new VirtualWebSocket({
+			getReadyState: () => this.#readyState,
+			onSend: (data) => this.#clientWs.triggerMessage(data),
+			onClose: (code, reason) => this.#close(code, reason),
+		});
+
+		// Create WSContext with actorWs as raw
+		this.#wsContext = new WSContext({
+			raw: this.#actorWs,
+			send: (data: string | ArrayBuffer | Uint8Array) => {
+				logger().debug({ msg: "WSContext.send called" });
+				this.#clientWs.triggerMessage(data);
+			},
+			close: (code?: number, reason?: string) => {
+				logger().debug({ msg: "WSContext.close called", code, reason });
+				this.#close(code || 1000, reason || "");
+			},
+			readyState: 1,
+		});
+
+		// Defer initialization to allow event listeners to be attached first
+		setTimeout(() => {
+			this.#initialize();
+		}, 0);
+	}
+
+	/** Get the client-side WebSocket (for proxy/client code) */
+	get clientWebSocket(): UniversalWebSocket {
+		return this.#clientWs;
+	}
+
+	/** Get the actor-side WebSocket (passed to actor via wsContext.raw) */
+	get actorWebSocket(): UniversalWebSocket {
+		return this.#actorWs;
+	}
+
+	async #initialize(): Promise<void> {
+		try {
+			logger().debug({ msg: "websocket initializing" });
+
+			this.#readyState = 1; // OPEN
+
+			logger().debug({ msg: "calling handler.onOpen with WSContext" });
+			this.#handler.onOpen(undefined, this.#wsContext);
+
+			// Fire open event to both sides
+			this.#clientWs.triggerOpen();
+			this.#actorWs.triggerOpen();
+		} catch (err) {
+			this.#handleError(err);
+			this.#close(1011, "Internal error during initialization");
+		}
+	}
+
+	#handleError(err: unknown): void {
+		logger().error({
+			msg: "error in websocket",
+			error: err,
+			errorMessage: err instanceof Error ? err.message : String(err),
+			stack: err instanceof Error ? err.stack : undefined,
+		});
+
+		// Call handler.onError
+		try {
+			this.#handler.onError(err, this.#wsContext);
+		} catch (handlerErr) {
+			logger().error({ msg: "error in onError handler", error: handlerErr });
+		}
+
+		// Fire error event to both sides
+		this.#clientWs.triggerError(err);
+		this.#actorWs.triggerError(err);
+	}
+
+	#close(code: number, reason: string): void {
+		if (this.#readyState === 3 || this.#readyState === 2) {
+			return;
+		}
+
+		logger().debug({ msg: "closing websocket", code, reason });
+
+		this.#readyState = 2; // CLOSING
+
+		try {
+			this.#handler.onClose({ code, reason, wasClean: true }, this.#wsContext);
+		} catch (err) {
+			logger().error({ msg: "error closing websocket", error: err });
+		} finally {
+			this.#readyState = 3; // CLOSED
+
+			// Fire close event to both sides
+			this.#clientWs.triggerClose(code, reason);
+			this.#actorWs.triggerClose(code, reason);
+		}
+	}
+}
+
+/**
+ * Creates an InlineWebSocketAdapter and returns the client-side WebSocket.
+ * This is the main entry point for creating inline WebSocket connections.
+ */
+export function createInlineWebSocket(
+	handler: UpgradeWebSocketArgs,
+): UniversalWebSocket {
+	const adapter = new InlineWebSocketAdapter(handler);
+	return adapter.clientWebSocket;
+}

package/src/common/log-levels.ts

@@ -0,0 +1,27 @@
+export type LogLevel =
+	| "TRACE"
+	| "DEBUG"
+	| "INFO"
+	| "WARN"
+	| "ERROR"
+	| "CRITICAL";
+
+export const LogLevels: Record<LogLevel, LevelIndex> = {
+	TRACE: 0,
+	DEBUG: 1,
+	INFO: 2,
+	WARN: 3,
+	ERROR: 4,
+	CRITICAL: 5,
+} as const;
+
+export const LevelNameMap: Record<number, LogLevel> = {
+	0: "TRACE",
+	1: "DEBUG",
+	2: "INFO",
+	3: "WARN",
+	4: "ERROR",
+	5: "CRITICAL",
+};
+
+export type LevelIndex = number;