rivetkit 2.0.1 → 2.0.3

package/src/client/http-client-driver.ts

@@ -0,0 +1,326 @@
+import * as cbor from "cbor-x";
+import type { Context as HonoContext } from "hono";
+import type { WebSocket } from "ws";
+import type { Encoding } from "@/actor/protocol/serde";
+import {
+	HEADER_ACTOR_ID,
+	HEADER_ACTOR_QUERY,
+	HEADER_CONN_ID,
+	HEADER_CONN_PARAMS,
+	HEADER_CONN_TOKEN,
+	HEADER_ENCODING,
+} from "@/actor/router-endpoints";
+import { importEventSource } from "@/common/eventsource";
+import type { UniversalEventSource } from "@/common/eventsource-interface";
+import { importWebSocket } from "@/common/websocket";
+import type { ActorQuery } from "@/manager/protocol/query";
+import type * as protocol from "@/schemas/client-protocol/mod";
+import {
+	HTTP_ACTION_REQUEST_VERSIONED,
+	HTTP_ACTION_RESPONSE_VERSIONED,
+	HTTP_RESOLVE_REQUEST_VERSIONED,
+	HTTP_RESOLVE_RESPONSE_VERSIONED,
+	TO_SERVER_VERSIONED,
+} from "@/schemas/client-protocol/versioned";
+import { serializeWithEncoding, wsBinaryTypeForEncoding } from "@/serde";
+import { assertUnreachable, bufferToArrayBuffer, httpUserAgent } from "@/utils";
+import type { ClientDriver } from "./client";
+import * as errors from "./errors";
+import { logger } from "./log";
+import { sendHttpRequest } from "./utils";
+
+/**
+ * Client driver that communicates with the manager via HTTP.
+ */
+export function createHttpClientDriver(managerEndpoint: string): ClientDriver {
+	// Lazily import the dynamic imports so we don't have to turn `createClient` in to an async fn
+	const dynamicImports = (async () => {
+		// Import dynamic dependencies
+		const [WebSocket, EventSource] = await Promise.all([
+			importWebSocket(),
+			importEventSource(),
+		]);
+		return {
+			WebSocket,
+			EventSource,
+		};
+	})();
+
+	const driver: ClientDriver = {
+		action: async <Args extends Array<unknown> = unknown[], Response = unknown>(
+			_c: HonoContext | undefined,
+			actorQuery: ActorQuery,
+			encoding: Encoding,
+			params: unknown,
+			name: string,
+			args: Args,
+			opts: { signal?: AbortSignal } | undefined,
+		): Promise<Response> => {
+			logger().debug("actor handle action", {
+				name,
+				args,
+				query: actorQuery,
+			});
+
+			const responseData = await sendHttpRequest<
+				protocol.HttpActionRequest,
+				protocol.HttpActionResponse
+			>({
+				url: `${managerEndpoint}/registry/actors/actions/${encodeURIComponent(name)}`,
+				method: "POST",
+				headers: {
+					[HEADER_ENCODING]: encoding,
+					[HEADER_ACTOR_QUERY]: JSON.stringify(actorQuery),
+					...(params !== undefined
+						? { [HEADER_CONN_PARAMS]: JSON.stringify(params) }
+						: {}),
+				},
+				body: {
+					args: bufferToArrayBuffer(cbor.encode(args)),
+				} satisfies protocol.HttpActionRequest,
+				encoding: encoding,
+				signal: opts?.signal,
+				requestVersionedDataHandler: HTTP_ACTION_REQUEST_VERSIONED,
+				responseVersionedDataHandler: HTTP_ACTION_RESPONSE_VERSIONED,
+			});
+
+			return cbor.decode(new Uint8Array(responseData.output));
+		},
+
+		resolveActorId: async (
+			_c: HonoContext | undefined,
+			actorQuery: ActorQuery,
+			encodingKind: Encoding,
+			params: unknown,
+		): Promise<string> => {
+			logger().debug("resolving actor ID", { query: actorQuery });
+
+			try {
+				const result = await sendHttpRequest<
+					null,
+					protocol.HttpResolveResponse
+				>({
+					url: `${managerEndpoint}/registry/actors/resolve`,
+					method: "POST",
+					headers: {
+						[HEADER_ENCODING]: encodingKind,
+						[HEADER_ACTOR_QUERY]: JSON.stringify(actorQuery),
+						...(params !== undefined
+							? { [HEADER_CONN_PARAMS]: JSON.stringify(params) }
+							: {}),
+					},
+					body: null,
+					encoding: encodingKind,
+					requestVersionedDataHandler: HTTP_RESOLVE_REQUEST_VERSIONED,
+					responseVersionedDataHandler: HTTP_RESOLVE_RESPONSE_VERSIONED,
+				});
+
+				logger().debug("resolved actor ID", { actorId: result.actorId });
+				return result.actorId;
+			} catch (error) {
+				logger().error("failed to resolve actor ID", { error });
+				if (error instanceof errors.ActorError) {
+					throw error;
+				} else {
+					throw new errors.InternalError(
+						`Failed to resolve actor ID: ${String(error)}`,
+					);
+				}
+			}
+		},
+
+		connectWebSocket: async (
+			_c: HonoContext | undefined,
+			actorQuery: ActorQuery,
+			encodingKind: Encoding,
+			params: unknown,
+		): Promise<WebSocket> => {
+			const { WebSocket } = await dynamicImports;
+
+			const endpoint = managerEndpoint
+				.replace(/^http:/, "ws:")
+				.replace(/^https:/, "wss:");
+			const url = `${endpoint}/registry/actors/connect/websocket`;
+
+			// Pass sensitive data via protocol
+			const protocol = [
+				`query.${encodeURIComponent(JSON.stringify(actorQuery))}`,
+				`encoding.${encodingKind}`,
+			];
+			if (params)
+				protocol.push(
+					`conn_params.${encodeURIComponent(JSON.stringify(params))}`,
+				);
+
+			// HACK: See packages/drivers/cloudflare-workers/src/websocket.ts
+			protocol.push("rivetkit");
+
+			logger().debug("connecting to websocket", { url });
+			const ws = new WebSocket(url, protocol);
+			// HACK: Bun bug prevents changing binary type, so we ignore the error https://github.com/oven-sh/bun/issues/17005
+			try {
+				ws.binaryType = wsBinaryTypeForEncoding(encodingKind);
+			} catch (error) {}
+
+			// Node & web WebSocket types not compatible
+			return ws as any;
+		},
+
+		connectSse: async (
+			_c: HonoContext | undefined,
+			actorQuery: ActorQuery,
+			encodingKind: Encoding,
+			params: unknown,
+		): Promise<UniversalEventSource> => {
+			const { EventSource } = await dynamicImports;
+
+			const url = `${managerEndpoint}/registry/actors/connect/sse`;
+
+			logger().debug("connecting to sse", { url });
+			const eventSource = new EventSource(url, {
+				fetch: (input, init) => {
+					return fetch(input, {
+						...init,
+						headers: {
+							...init?.headers,
+							"User-Agent": httpUserAgent(),
+							[HEADER_ENCODING]: encodingKind,
+							[HEADER_ACTOR_QUERY]: JSON.stringify(actorQuery),
+							...(params !== undefined
+								? { [HEADER_CONN_PARAMS]: JSON.stringify(params) }
+								: {}),
+						},
+						credentials: "include",
+					});
+				},
+			});
+
+			return eventSource as UniversalEventSource;
+		},
+
+		sendHttpMessage: async (
+			_c: HonoContext | undefined,
+			actorId: string,
+			encoding: Encoding,
+			connectionId: string,
+			connectionToken: string,
+			message: protocol.ToServer,
+		): Promise<void> => {
+			// TODO: Implement ordered messages, this is not guaranteed order. Needs to use an index in order to ensure we can pipeline requests efficiently.
+			// TODO: Validate that we're using HTTP/3 whenever possible for pipelining requests
+			const messageSerialized = serializeWithEncoding(
+				encoding,
+				message,
+				TO_SERVER_VERSIONED,
+			);
+			const res = await fetch(`${managerEndpoint}/registry/actors/message`, {
+				method: "POST",
+				headers: {
+					"User-Agent": httpUserAgent(),
+					[HEADER_ENCODING]: encoding,
+					[HEADER_ACTOR_ID]: actorId,
+					[HEADER_CONN_ID]: connectionId,
+					[HEADER_CONN_TOKEN]: connectionToken,
+				},
+				body: messageSerialized,
+				credentials: "include",
+			});
+			if (!res.ok) {
+				throw new errors.InternalError(
+					`Publish message over HTTP error (${res.statusText}):\n${await res.text()}`,
+				);
+			}
+
+			// Discard response
+			await res.body?.cancel();
+		},
+
+		rawHttpRequest: async (
+			_c: HonoContext | undefined,
+			actorQuery: ActorQuery,
+			encoding: Encoding,
+			params: unknown,
+			path: string,
+			init: RequestInit,
+		): Promise<Response> => {
+			// Build the full URL
+			// Remove leading slash from path to avoid double slashes
+			const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
+			const url = `${managerEndpoint}/registry/actors/raw/http/${normalizedPath}`;
+
+			logger().debug("rewriting http url", {
+				from: path,
+				to: url,
+			});
+
+			// Merge headers properly
+			const headers = new Headers(init.headers);
+			headers.set("User-Agent", httpUserAgent());
+			headers.set(HEADER_ACTOR_QUERY, JSON.stringify(actorQuery));
+			headers.set(HEADER_ENCODING, encoding);
+			if (params !== undefined) {
+				headers.set(HEADER_CONN_PARAMS, JSON.stringify(params));
+			}
+
+			// Forward the request with query in headers
+			return await fetch(url, {
+				...init,
+				headers,
+			});
+		},
+
+		rawWebSocket: async (
+			_c: HonoContext | undefined,
+			actorQuery: ActorQuery,
+			encoding: Encoding,
+			params: unknown,
+			path: string,
+			protocols: string | string[] | undefined,
+		): Promise<WebSocket> => {
+			const { WebSocket } = await dynamicImports;
+
+			// Build the WebSocket URL with normalized path
+			const wsEndpoint = managerEndpoint
+				.replace(/^http:/, "ws:")
+				.replace(/^https:/, "wss:");
+			// Normalize path to match raw HTTP behavior
+			const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
+			const url = `${wsEndpoint}/registry/actors/raw/websocket/${normalizedPath}`;
+
+			logger().debug("rewriting websocket url", {
+				from: path,
+				to: url,
+			});
+
+			// Pass data via WebSocket protocol subprotocols
+			const protocolList: string[] = [];
+			protocolList.push(
+				`query.${encodeURIComponent(JSON.stringify(actorQuery))}`,
+			);
+			protocolList.push(`encoding.${encoding}`);
+			if (params) {
+				protocolList.push(
+					`conn_params.${encodeURIComponent(JSON.stringify(params))}`,
+				);
+			}
+
+			// HACK: See packages/drivers/cloudflare-workers/src/websocket.ts
+			protocolList.push("rivetkit");
+
+			// Add user protocols
+			if (protocols) {
+				if (Array.isArray(protocols)) {
+					protocolList.push(...protocols);
+				} else {
+					protocolList.push(protocols);
+				}
+			}
+
+			// Create WebSocket connection
+			logger().debug("opening raw websocket", { url });
+			return new WebSocket(url, protocolList) as any;
+		},
+	};
+
+	return driver;
+}

package/src/client/log.ts

@@ -0,0 +1,7 @@
+import { getLogger } from "@/common//log";
+
+export const LOGGER_NAME = "actor-client";
+
+export function logger() {
+	return getLogger(LOGGER_NAME);
+}

package/src/client/mod.ts

@@ -0,0 +1,56 @@
+import type { Registry } from "@/registry/mod";
+import {
+	type Client,
+	type ClientOptions,
+	createClientWithDriver,
+} from "./client";
+import { createHttpClientDriver } from "./http-client-driver";
+
+export {
+	ActorDefinition,
+	AnyActorDefinition,
+} from "@/actor/definition";
+export type { Transport } from "@/actor/protocol/old";
+export type { Encoding } from "@/actor/protocol/serde";
+export {
+	ActorClientError,
+	ActorError,
+	InternalError,
+	MalformedResponseMessage,
+	ManagerError,
+} from "@/client/errors";
+export type { CreateRequest } from "@/manager/protocol/query";
+export type { ActorActionFunction } from "./actor-common";
+export type { ActorConn, EventUnsubscribe } from "./actor-conn";
+export { ActorConnRaw } from "./actor-conn";
+export type { ActorHandle } from "./actor-handle";
+export { ActorHandleRaw } from "./actor-handle";
+export type {
+	ActorAccessor,
+	Client,
+	ClientOptions,
+	ClientRaw,
+	CreateOptions,
+	ExtractActorsFromRegistry,
+	ExtractRegistryFromClient,
+	GetOptions,
+	GetWithIdOptions,
+	QueryOptions,
+	Region,
+} from "./client";
+
+/**
+ * Creates a client with the actor accessor proxy.
+ *
+ * @template A The actor application type.
+ * @param {string} managerEndpoint - The manager endpoint.
+ * @param {ClientOptions} [opts] - Options for configuring the client.
+ * @returns {Client<A>} - A proxied client that supports the `client.myActor.connect()` syntax.
+ */
+export function createClient<A extends Registry<any>>(
+	endpoint: string,
+	opts?: ClientOptions,
+): Client<A> {
+	const driver = createHttpClientDriver(endpoint);
+	return createClientWithDriver<A>(driver, opts);
+}

package/src/client/raw-utils.ts

@@ -0,0 +1,92 @@
+import type { ActorQuery } from "@/manager/protocol/query";
+import type { ClientDriver } from "./client";
+
+/**
+ * Shared implementation for raw HTTP fetch requests
+ */
+export async function rawHttpFetch(
+	driver: ClientDriver,
+	actorQuery: ActorQuery,
+	params: unknown,
+	input: string | URL | Request,
+	init?: RequestInit,
+): Promise<Response> {
+	// Extract path and merge init options
+	let path: string;
+	let mergedInit: RequestInit = init || {};
+
+	if (typeof input === "string") {
+		path = input;
+	} else if (input instanceof URL) {
+		path = input.pathname + input.search;
+	} else if (input instanceof Request) {
+		// Extract path from Request URL
+		const url = new URL(input.url);
+		path = url.pathname + url.search;
+		// Merge Request properties with init
+		const requestHeaders = new Headers(input.headers);
+		const initHeaders = new Headers(init?.headers || {});
+
+		// Merge headers - init headers override request headers
+		const mergedHeaders = new Headers(requestHeaders);
+		for (const [key, value] of initHeaders) {
+			mergedHeaders.set(key, value);
+		}
+
+		mergedInit = {
+			method: input.method,
+			body: input.body,
+			mode: input.mode,
+			credentials: input.credentials,
+			redirect: input.redirect,
+			referrer: input.referrer,
+			referrerPolicy: input.referrerPolicy,
+			integrity: input.integrity,
+			keepalive: input.keepalive,
+			signal: input.signal,
+			...mergedInit, // init overrides Request properties
+			headers: mergedHeaders, // headers must be set after spread to ensure proper merge
+		};
+		// Add duplex if body is present
+		if (mergedInit.body) {
+			(mergedInit as any).duplex = "half";
+		}
+	} else {
+		throw new TypeError("Invalid input type for fetch");
+	}
+
+	// Use the driver's raw HTTP method - just pass the sub-path
+	return await driver.rawHttpRequest(
+		undefined,
+		actorQuery,
+		// Force JSON so it's readable by the user
+		"json",
+		params,
+		path,
+		mergedInit,
+		undefined,
+	);
+}
+
+/**
+ * Shared implementation for raw WebSocket connections
+ */
+export async function rawWebSocket(
+	driver: ClientDriver,
+	actorQuery: ActorQuery,
+	params: unknown,
+	path?: string,
+	protocols?: string | string[],
+): Promise<any> {
+	// Use the driver's raw WebSocket method
+	return await driver.rawWebSocket(
+		undefined,
+		actorQuery,
+		// Force JSON so it's readable by the user
+		"json",
+		params,
+		path || "",
+		protocols,
+		undefined,
+	);
+}

package/src/client/test.ts

@@ -0,0 +1,44 @@
+//import { exec as execCallback } from "node:child_process";
+//import { setupLogging } from "@/common//log";
+//import type { ClientOptions } from "./client";
+//import { InternalError } from "./errors";
+//import { Client } from "./mod.ts";
+//
+///**
+// * Uses the Rivet CLI to read the manager endpoint to connect to. This allows
+// * for writing tests that run locally without hardcoding the manager endpoint.
+// */
+//export async function readEndpointFromCli(): Promise<string> {
+//	// Read endpoint
+//	const cliPath = process.env.RIVET_CLI_PATH ?? "rivet";
+//
+//	try {
+//		const { stdout, stderr } = await new Promise<{
+//			stdout: string;
+//			stderr: string;
+//		}>((resolve, reject) => {
+//			execCallback(`${cliPath} manager endpoint`, (error, stdout, stderr) => {
+//				if (error) reject(error);
+//				else resolve({ stdout, stderr });
+//			});
+//		});
+//
+//		if (stderr) {
+//			throw new Error(stderr);
+//		}
+//
+//		// Decode output
+//		return stdout.trim();
+//	} catch (error) {
+//		throw new InternalError(`Read endpoint failed: ${error}`);
+//	}
+//}
+//
+//export class TestClient extends Client {
+//	public constructor(opts?: ClientOptions) {
+//		// Setup logging automatically
+//		setupLogging();
+//
+//		super(readEndpointFromCli(), opts);
+//	}
+//}

package/src/client/utils.ts

@@ -0,0 +1,150 @@
+import * as cbor from "cbor-x";
+import invariant from "invariant";
+import { assertUnreachable } from "@/common/utils";
+import type { VersionedDataHandler } from "@/common/versioned-data";
+import type { Encoding } from "@/mod";
+import type { HttpResponseError } from "@/schemas/client-protocol/mod";
+import { HTTP_RESPONSE_ERROR_VERSIONED } from "@/schemas/client-protocol/versioned";
+import {
+	contentTypeForEncoding,
+	deserializeWithEncoding,
+	serializeWithEncoding,
+} from "@/serde";
+import { httpUserAgent } from "@/utils";
+import { ActorError, HttpRequestError } from "./errors";
+import { logger } from "./log";
+
+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<RequestBody, ResponseBody> {
+	method: string;
+	url: string;
+	headers: Record<string, string>;
+	body?: RequestBody;
+	encoding: Encoding;
+	skipParseResponse?: boolean;
+	signal?: AbortSignal;
+	customFetch?: (req: Request) => Promise<Response>;
+	requestVersionedDataHandler: VersionedDataHandler<RequestBody>;
+	responseVersionedDataHandler: VersionedDataHandler<ResponseBody>;
+}
+
+export async function sendHttpRequest<
+	RequestBody = unknown,
+	ResponseBody = unknown,
+>(opts: HttpRequestOpts<RequestBody, ResponseBody>): Promise<ResponseBody> {
+	logger().debug("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<RequestBody>(
+			opts.encoding,
+			opts.body,
+			opts.requestVersionedDataHandler,
+		);
+	}
+
+	// Send request
+	let response: Response;
+	try {
+		// Make the HTTP request
+		response = await (opts.customFetch ?? fetch)(
+			new 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) {
+		// Attempt to parse structured data
+		const bufferResponse = await response.arrayBuffer();
+		let responseData: HttpResponseError;
+		try {
+			responseData = deserializeWithEncoding(
+				opts.encoding,
+				new Uint8Array(bufferResponse),
+				HTTP_RESPONSE_ERROR_VERSIONED,
+			);
+		} catch (error) {
+			//logger().warn("failed to cleanly parse error, this is likely because a non-structured response is being served", {
+			//	error: stringifyError(error),
+			//});
+
+			// Error is not structured
+			const textResponse = new TextDecoder("utf-8", { fatal: false }).decode(
+				bufferResponse,
+			);
+			throw new HttpRequestError(
+				`${response.statusText} (${response.status}):\n${textResponse}`,
+			);
+		}
+
+		// Throw structured error
+		throw new ActorError(
+			responseData.code,
+			responseData.message,
+			responseData.metadata
+				? cbor.decode(new Uint8Array(responseData.metadata))
+				: undefined,
+		);
+	}
+
+	// Some requests don't need the success response to be parsed, so this can speed things up
+	if (opts.skipParseResponse) {
+		return undefined as ResponseBody;
+	}
+
+	// Parse the response based on encoding
+	try {
+		const buffer = new Uint8Array(await response.arrayBuffer());
+		return deserializeWithEncoding(
+			opts.encoding,
+			buffer,
+			opts.responseVersionedDataHandler,
+		);
+	} catch (error) {
+		throw new HttpRequestError(`Failed to parse response: ${error}`, {
+			cause: error,
+		});
+	}
+}