rivetkit 2.0.2 → 2.0.4-rc.1

package/src/client/errors.ts

@@ -0,0 +1,76 @@
+export class ActorClientError extends Error {}
+
+export class InternalError extends ActorClientError {}
+
+export class ManagerError extends ActorClientError {
+	constructor(error: string, opts?: ErrorOptions) {
+		super(`Manager error: ${error}`, opts);
+	}
+}
+
+export class MalformedResponseMessage extends ActorClientError {
+	constructor(cause?: unknown) {
+		super(`Malformed response message: ${cause}`, { cause });
+	}
+}
+
+export class ActorError extends ActorClientError {
+	__type = "ActorError";
+
+	constructor(
+		public readonly group: string,
+		public readonly code: string,
+		message: string,
+		public readonly metadata?: unknown,
+	) {
+		super(message);
+	}
+}
+
+export class HttpRequestError extends ActorClientError {
+	constructor(message: string, opts?: { cause?: unknown }) {
+		super(`HTTP request error: ${message}`, { cause: opts?.cause });
+	}
+}
+
+export class ActorConnDisposed extends ActorClientError {
+	constructor() {
+		super("Attempting to interact with a disposed actor connection.");
+	}
+}
+
+/**
+ * Checks if an error code indicates a scheduling error that may have more details.
+ */
+export function isSchedulingError(group: string, code: string): boolean {
+	return (
+		group === "guard" &&
+		(code === "actor_ready_timeout" || code === "actor_runner_failed")
+	);
+}
+
+/**
+ * Error thrown when actor scheduling fails.
+ * Provides detailed information about why the actor failed to start.
+ */
+export class ActorSchedulingError extends ActorError {
+	public readonly actorId: string;
+	public readonly details: unknown;
+
+	constructor(
+		group: string,
+		code: string,
+		actorId: string,
+		details: unknown,
+	) {
+		super(
+			group,
+			code,
+			`Actor failed to start (${actorId}): ${JSON.stringify(details)}`,
+			{ actorId, details },
+		);
+		this.name = "ActorSchedulingError";
+		this.actorId = actorId;
+		this.details = details;
+	}
+}

package/src/client/log.ts

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

package/src/client/mod.browser.ts

@@ -0,0 +1,2 @@
+// Browser-safe client exports (all client functionality is browser-compatible)
+export * from "./mod";

package/src/client/mod.ts

@@ -0,0 +1,70 @@
+import { injectDevtools } from "@/devtools-loader";
+import type { Registry } from "@/registry";
+import { RemoteManagerDriver } from "@/remote-manager-driver/mod";
+import {
+	type Client,
+	type ClientConfigInput,
+	createClientWithDriver,
+} from "./client";
+import { ClientConfigSchema } from "./config";
+
+export type { ActorDefinition, AnyActorDefinition } from "@/actor/definition";
+export type { Encoding } from "@/actor/protocol/serde";
+export {
+	ActorClientError,
+	ActorConnDisposed,
+	ActorError,
+	InternalError,
+	MalformedResponseMessage,
+	ManagerError,
+} from "@/client/errors";
+export type { CreateRequest } from "@/manager/protocol/query";
+export { KEYS as KV_KEYS } from "../actor/instance/keys";
+export type { ActorActionFunction } from "./actor-common";
+export type {
+	ActorConn,
+	ActorConnStatus,
+	ConnectionStateCallback,
+	EventUnsubscribe,
+	StatusChangeCallback,
+} from "./actor-conn";
+export { ActorConnRaw } from "./actor-conn";
+export type { ActorHandle } from "./actor-handle";
+export { ActorHandleRaw } from "./actor-handle";
+export type {
+	ActorAccessor,
+	Client,
+	ClientRaw,
+	CreateOptions,
+	ExtractActorsFromRegistry,
+	ExtractRegistryFromClient,
+	GetOptions,
+	GetWithIdOptions,
+	QueryOptions,
+	Region,
+} from "./client";
+
+/**
+ * Creates a client with the actor accessor proxy.
+ */
+export function createClient<A extends Registry<any>>(
+	endpointOrConfig?: string | ClientConfigInput,
+): Client<A> {
+	// Parse config
+	const configInput =
+		endpointOrConfig === undefined
+			? {}
+			: typeof endpointOrConfig === "string"
+				? { endpoint: endpointOrConfig }
+				: endpointOrConfig;
+	const config = ClientConfigSchema.parse(configInput);
+
+	// Create client
+	const driver = new RemoteManagerDriver(config);
+
+	if (config.devtools) {
+		injectDevtools(config);
+	}
+
+	return createClientWithDriver<A>(driver, config);
+}

package/src/client/queue.ts

@@ -0,0 +1,146 @@
+import * as cbor from "cbor-x";
+import type { Encoding } from "@/actor/protocol/serde";
+import { HEADER_CONN_PARAMS, HEADER_ENCODING } from "@/driver-helpers/mod";
+import type * as protocol from "@/schemas/client-protocol/mod";
+import {
+	CURRENT_VERSION as CLIENT_PROTOCOL_CURRENT_VERSION,
+	HTTP_QUEUE_SEND_REQUEST_VERSIONED,
+	HTTP_QUEUE_SEND_RESPONSE_VERSIONED,
+} from "@/schemas/client-protocol/versioned";
+import {
+	type HttpQueueSendRequest as HttpQueueSendRequestJson,
+	HttpQueueSendRequestSchema,
+	type HttpQueueSendResponse as HttpQueueSendResponseJson,
+	HttpQueueSendResponseSchema,
+} from "@/schemas/client-protocol-zod/mod";
+import { bufferToArrayBuffer } from "@/utils";
+import { sendHttpRequest } from "./utils";
+
+export interface QueueSender {
+	send(
+		name: string,
+		body: unknown,
+		options: QueueSendWaitOptions,
+	): Promise<QueueSendResult>;
+	send(
+		name: string,
+		body: unknown,
+		options?: QueueSendNoWaitOptions,
+	): Promise<void>;
+}
+
+export interface QueueSendWaitOptions {
+	wait: true;
+	timeout?: number;
+	signal?: AbortSignal;
+}
+
+export interface QueueSendNoWaitOptions {
+	wait?: false;
+	timeout?: never;
+	signal?: AbortSignal;
+}
+
+export type QueueSendOptions = QueueSendWaitOptions | QueueSendNoWaitOptions;
+
+export interface QueueSendResult {
+	status: "completed" | "timedOut";
+	response?: unknown;
+}
+
+interface QueueSenderOptions {
+	encoding: Encoding;
+	params: unknown;
+	customFetch: (request: Request) => Promise<Response>;
+}
+
+export function createQueueSender(senderOptions: QueueSenderOptions): QueueSender {
+	async function send(
+		name: string,
+		body: unknown,
+		options: QueueSendWaitOptions,
+	): Promise<QueueSendResult>;
+	async function send(
+		name: string,
+		body: unknown,
+		options?: QueueSendNoWaitOptions,
+	): Promise<void>;
+	async function send(
+		name: string,
+		body: unknown,
+		options?: QueueSendOptions,
+	): Promise<QueueSendResult | void> {
+		const wait = options?.wait ?? false;
+		const timeout = options?.timeout;
+
+		const result = await sendHttpRequest<
+			protocol.HttpQueueSendRequest,
+			protocol.HttpQueueSendResponse,
+			HttpQueueSendRequestJson,
+			HttpQueueSendResponseJson,
+			{ body: unknown; wait?: boolean; timeout?: number; name?: string },
+			QueueSendResult
+		>({
+			url: `http://actor/queue/${encodeURIComponent(name)}`,
+			method: "POST",
+			headers: {
+				[HEADER_ENCODING]: senderOptions.encoding,
+				...(senderOptions.params !== undefined
+					? {
+							[HEADER_CONN_PARAMS]: JSON.stringify(
+								senderOptions.params,
+							),
+						}
+					: {}),
+			},
+			body: { body, wait, timeout },
+			encoding: senderOptions.encoding,
+			customFetch: senderOptions.customFetch,
+			signal: options?.signal,
+			requestVersion: CLIENT_PROTOCOL_CURRENT_VERSION,
+			requestVersionedDataHandler: HTTP_QUEUE_SEND_REQUEST_VERSIONED,
+			responseVersion: CLIENT_PROTOCOL_CURRENT_VERSION,
+			responseVersionedDataHandler:
+				HTTP_QUEUE_SEND_RESPONSE_VERSIONED,
+			requestZodSchema: HttpQueueSendRequestSchema,
+			responseZodSchema: HttpQueueSendResponseSchema,
+			requestToJson: (value): HttpQueueSendRequestJson => ({
+				...value,
+				name,
+			}),
+			requestToBare: (value): protocol.HttpQueueSendRequest => ({
+				name: value.name ?? name,
+				body: bufferToArrayBuffer(cbor.encode(value.body)),
+				wait: value.wait ?? false,
+				timeout: value.timeout !== undefined ? BigInt(value.timeout) : null,
+			}),
+			responseFromJson: (json): QueueSendResult => {
+				if (json.response === undefined) {
+					return { status: json.status as "completed" | "timedOut" };
+				}
+				return {
+					status: json.status as "completed" | "timedOut",
+					response: json.response,
+				};
+			},
+			responseFromBare: (bare): QueueSendResult => {
+				if (bare.response === null || bare.response === undefined) {
+					return { status: bare.status as "completed" | "timedOut" };
+				}
+				return {
+					status: bare.status as "completed" | "timedOut",
+					response: cbor.decode(new Uint8Array(bare.response)),
+				};
+			},
+		});
+
+		if (wait) {
+			return result;
+		}
+		return;
+	}
+
+	return {
+		send,
+	};
+}

package/src/client/raw-utils.ts

@@ -0,0 +1,149 @@
+import invariant from "invariant";
+import { PATH_WEBSOCKET_PREFIX } from "@/common/actor-router-consts";
+import { deconstructError } from "@/common/utils";
+import { HEADER_CONN_PARAMS, type ManagerDriver } from "@/driver-helpers/mod";
+import type { ActorQuery } from "@/manager/protocol/query";
+import { queryActor } from "./actor-query";
+import { ActorError } from "./errors";
+import { logger } from "./log";
+
+/**
+ * Shared implementation for raw HTTP fetch requests
+ */
+export async function rawHttpFetch(
+	driver: ManagerDriver,
+	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);
+		initHeaders.forEach((value, key) => {
+			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");
+	}
+
+	try {
+		// Get the actor ID
+		const { actorId } = await queryActor(undefined, actorQuery, driver);
+		logger().debug({ msg: "found actor for raw http", actorId });
+		invariant(actorId, "Missing actor ID");
+
+		// Build the URL with normalized path
+		const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
+		const url = new URL(`http://actor/request/${normalizedPath}`);
+
+		// Forward conn params if provided
+		const proxyRequestHeaders = new Headers(mergedInit.headers);
+		if (params) {
+			proxyRequestHeaders.set(HEADER_CONN_PARAMS, JSON.stringify(params));
+		}
+
+		// Forward the request to the actor
+		const proxyRequest = new Request(url, {
+			...mergedInit,
+			headers: proxyRequestHeaders,
+		});
+
+		return driver.sendRequest(actorId, proxyRequest);
+	} catch (err) {
+		// Standardize to ClientActorError instead of the native backend error
+		const { group, code, message, metadata } = deconstructError(
+			err,
+			logger(),
+			{},
+			true,
+		);
+		throw new ActorError(group, code, message, metadata);
+	}
+}
+
+/**
+ * Shared implementation for raw WebSocket connections
+ */
+export async function rawWebSocket(
+	driver: ManagerDriver,
+	actorQuery: ActorQuery,
+	params: unknown,
+	path?: string,
+	// TODO: Supportp rotocols
+	protocols?: string | string[],
+): Promise<any> {
+	// TODO: Do we need encoding in rawWebSocket?
+	const encoding = "bare";
+
+	// Get the actor ID
+	const { actorId } = await queryActor(undefined, actorQuery, driver);
+	logger().debug({ msg: "found actor for action", actorId });
+	invariant(actorId, "Missing actor ID");
+
+	// Parse path and query parameters
+	let pathPortion = "";
+	let queryPortion = "";
+	if (path) {
+		const queryIndex = path.indexOf("?");
+		if (queryIndex !== -1) {
+			pathPortion = path.substring(0, queryIndex);
+			queryPortion = path.substring(queryIndex); // includes the '?'
+		} else {
+			pathPortion = path;
+		}
+		// Remove leading slash if present
+		if (pathPortion.startsWith("/")) {
+			pathPortion = pathPortion.slice(1);
+		}
+	}
+
+	const fullPath = `${PATH_WEBSOCKET_PREFIX}${pathPortion}${queryPortion}`;
+
+	logger().debug({
+		msg: "opening websocket",
+		actorId,
+		encoding,
+		path: fullPath,
+	});
+
+	// Open WebSocket
+	const ws = await driver.openWebSocket(fullPath, actorId, encoding, params);
+
+	// Node & browser WebSocket types are incompatible
+	return ws as any;
+}

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);
+//	}
+//}