rivetkit 2.0.2 → 2.0.4-rc.1

package/src/client/actor-handle.ts

@@ -0,0 +1,344 @@
+import * as cbor from "cbor-x";
+import invariant from "invariant";
+import type { AnyActorDefinition } from "@/actor/definition";
+import type { Encoding } from "@/actor/protocol/serde";
+import { assertUnreachable } from "@/actor/utils";
+import { deconstructError } from "@/common/utils";
+import {
+	HEADER_CONN_PARAMS,
+	HEADER_ENCODING,
+	type ManagerDriver,
+} from "@/driver-helpers/mod";
+import type { ActorQuery } from "@/manager/protocol/query";
+import type * as protocol from "@/schemas/client-protocol/mod";
+import {
+	CURRENT_VERSION as CLIENT_PROTOCOL_CURRENT_VERSION,
+	HTTP_ACTION_REQUEST_VERSIONED,
+	HTTP_ACTION_RESPONSE_VERSIONED,
+} from "@/schemas/client-protocol/versioned";
+import {
+	type HttpActionRequest as HttpActionRequestJson,
+	HttpActionRequestSchema,
+	type HttpActionResponse as HttpActionResponseJson,
+	HttpActionResponseSchema,
+} from "@/schemas/client-protocol-zod/mod";
+import { bufferToArrayBuffer } from "@/utils";
+import type { ActorDefinitionActions } from "./actor-common";
+import { type ActorConn, ActorConnRaw } from "./actor-conn";
+import { checkForSchedulingError, queryActor } from "./actor-query";
+import { type ClientRaw, CREATE_ACTOR_CONN_PROXY } from "./client";
+import { ActorError, isSchedulingError } from "./errors";
+import { logger } from "./log";
+import {
+	createQueueSender,
+	type QueueSendNoWaitOptions,
+	type QueueSendOptions,
+	type QueueSendResult,
+	type QueueSendWaitOptions,
+} from "./queue";
+import { rawHttpFetch, rawWebSocket } from "./raw-utils";
+import { sendHttpRequest } from "./utils";
+
+/**
+ * Provides underlying functions for stateless {@link ActorHandle} for action calls.
+ * Similar to ActorConnRaw but doesn't maintain a connection.
+ *
+ * @see {@link ActorHandle}
+ */
+export class ActorHandleRaw {
+	#client: ClientRaw;
+	#driver: ManagerDriver;
+	#encoding: Encoding;
+	#actorQuery: ActorQuery;
+	#params: unknown;
+	#queueSender: ReturnType<typeof createQueueSender>;
+
+	/**
+	 * Do not call this directly.
+	 *
+	 * Creates an instance of ActorHandleRaw.
+	 *
+	 * @protected
+	 */
+	public constructor(
+		client: any,
+		driver: ManagerDriver,
+		params: unknown,
+		encoding: Encoding,
+		actorQuery: ActorQuery,
+	) {
+		this.#client = client;
+		this.#driver = driver;
+		this.#encoding = encoding;
+		this.#actorQuery = actorQuery;
+		this.#params = params;
+		this.#queueSender = createQueueSender({
+			encoding: this.#encoding,
+			params: this.#params,
+			customFetch: async (request: Request) => {
+				const { actorId } = await queryActor(
+					undefined,
+					this.#actorQuery,
+					this.#driver,
+				);
+				return this.#driver.sendRequest(actorId, request);
+			},
+		});
+	}
+
+	send(
+		name: string,
+		body: unknown,
+		options: QueueSendWaitOptions,
+	): Promise<QueueSendResult>;
+	send(
+		name: string,
+		body: unknown,
+		options?: QueueSendNoWaitOptions,
+	): Promise<void>;
+	send(
+		name: string,
+		body: unknown,
+		options?: QueueSendOptions,
+	): Promise<QueueSendResult | void> {
+		return this.#queueSender.send(name, body, options as any);
+	}
+
+	/**
+	 * Call a raw action. This method sends an HTTP request to invoke the named action.
+	 *
+	 * @see {@link ActorHandle}
+	 * @template Args - The type of arguments to pass to the action function.
+	 * @template Response - The type of the response returned by the action function.
+	 */
+	async action<
+		Args extends Array<unknown> = unknown[],
+		Response = unknown,
+	>(opts: {
+		name: string;
+		args: Args;
+		signal?: AbortSignal;
+	}): Promise<Response> {
+		// Track actorId for scheduling error lookups
+		let actorId: string | undefined;
+
+		try {
+			// Get the actor ID
+			const result = await queryActor(
+				undefined,
+				this.#actorQuery,
+				this.#driver,
+			);
+			actorId = result.actorId;
+			logger().debug({ msg: "found actor for action", actorId });
+			invariant(actorId, "Missing actor ID");
+
+			// Invoke the action
+			logger().debug({
+				msg: "handling action",
+				name: opts.name,
+				encoding: this.#encoding,
+			});
+			const responseData = await sendHttpRequest<
+				protocol.HttpActionRequest, // Bare type
+				protocol.HttpActionResponse, // Bare type
+				HttpActionRequestJson, // Json type
+				HttpActionResponseJson, // Json type
+				unknown[], // Request type (the args array)
+				Response // Response type (the output value)
+			>({
+				url: `http://actor/action/${encodeURIComponent(opts.name)}`,
+				method: "POST",
+				headers: {
+					[HEADER_ENCODING]: this.#encoding,
+					...(this.#params !== undefined
+						? { [HEADER_CONN_PARAMS]: JSON.stringify(this.#params) }
+						: {}),
+				},
+				body: opts.args,
+				encoding: this.#encoding,
+				customFetch: this.#driver.sendRequest.bind(
+					this.#driver,
+					actorId,
+				),
+				signal: opts?.signal,
+				requestVersion: CLIENT_PROTOCOL_CURRENT_VERSION,
+				requestVersionedDataHandler: HTTP_ACTION_REQUEST_VERSIONED,
+				responseVersion: CLIENT_PROTOCOL_CURRENT_VERSION,
+				responseVersionedDataHandler: HTTP_ACTION_RESPONSE_VERSIONED,
+				requestZodSchema: HttpActionRequestSchema,
+				responseZodSchema: HttpActionResponseSchema,
+				// JSON Request: args is the raw value
+				requestToJson: (args): HttpActionRequestJson => ({
+					args,
+				}),
+				// BARE Request: args needs to be CBOR-encoded
+				requestToBare: (args): protocol.HttpActionRequest => ({
+					args: bufferToArrayBuffer(cbor.encode(args)),
+				}),
+				// JSON Response: output is the raw value
+				responseFromJson: (json): Response => json.output as Response,
+				// BARE Response: output is ArrayBuffer that needs CBOR-decoding
+				responseFromBare: (bare): Response =>
+					cbor.decode(new Uint8Array(bare.output)) as Response,
+			});
+
+			return responseData;
+		} catch (err) {
+			// Standardize to ClientActorError instead of the native backend error
+			const { group, code, message, metadata } = deconstructError(
+				err,
+				logger(),
+				{},
+				true,
+			);
+
+			// Check if this is a scheduling error and try to get more details
+			if (actorId && isSchedulingError(group, code)) {
+				const schedulingError = await checkForSchedulingError(
+					group,
+					code,
+					actorId,
+					this.#actorQuery,
+					this.#driver,
+				);
+				if (schedulingError) {
+					throw schedulingError;
+				}
+			}
+
+			throw new ActorError(group, code, message, metadata);
+		}
+	}
+
+	/**
+	 * Establishes a persistent connection to the actor.
+	 *
+	 * @template AD The actor class that this connection is for.
+	 * @returns {ActorConn<AD>} A connection to the actor.
+	 */
+	connect(): ActorConn<AnyActorDefinition> {
+		logger().debug({
+			msg: "establishing connection from handle",
+			query: this.#actorQuery,
+		});
+
+		const conn = new ActorConnRaw(
+			this.#client,
+			this.#driver,
+			this.#params,
+			this.#encoding,
+			this.#actorQuery,
+		);
+
+		return this.#client[CREATE_ACTOR_CONN_PROXY](
+			conn,
+		) as ActorConn<AnyActorDefinition>;
+	}
+
+	/**
+	 * Fetches a resource from this actor via the /request endpoint. This is a
+	 * convenience wrapper around the raw HTTP API.
+	 */
+	fetch(input: string | URL | Request, init?: RequestInit) {
+		return rawHttpFetch(
+			this.#driver,
+			this.#actorQuery,
+			this.#params,
+			input,
+			init,
+		);
+	}
+
+	/**
+	 * Opens a raw WebSocket connection to this actor.
+	 */
+	webSocket(path?: string, protocols?: string | string[]) {
+		return rawWebSocket(
+			this.#driver,
+			this.#actorQuery,
+			this.#params,
+			path,
+			protocols,
+		);
+	}
+
+	/**
+	 * Resolves the actor to get its unique actor ID.
+	 */
+	async resolve(): Promise<string> {
+		if ("getForKey" in this.#actorQuery) {
+			const name = this.#actorQuery.getForKey.name;
+
+			// Query the actor to get the id
+			const { actorId } = await queryActor(
+				undefined,
+				this.#actorQuery,
+				this.#driver,
+			);
+
+			this.#actorQuery = { getForId: { actorId, name } };
+
+			return actorId;
+		} else if ("getOrCreateForKey" in this.#actorQuery) {
+			const name = this.#actorQuery.getOrCreateForKey.name;
+
+			// Query the actor to get or create and get the id
+			const { actorId } = await queryActor(
+				undefined,
+				this.#actorQuery,
+				this.#driver,
+			);
+
+			this.#actorQuery = { getForId: { actorId, name } };
+
+			return actorId;
+		} else if ("getForId" in this.#actorQuery) {
+			// Skip since it's already resolved
+			return this.#actorQuery.getForId.actorId;
+		} else if ("create" in this.#actorQuery) {
+			// Cannot create a handle with this query
+			invariant(false, "actorQuery cannot be create");
+		} else {
+			assertUnreachable(this.#actorQuery);
+		}
+	}
+
+	/**
+	 * Returns the raw URL for routing traffic to the actor.
+	 */
+	async getGatewayUrl(): Promise<string> {
+		const { actorId } = await queryActor(
+			undefined,
+			this.#actorQuery,
+			this.#driver,
+		);
+		return await this.#driver.buildGatewayUrl(actorId);
+	}
+}
+
+/**
+ * Stateless handle to a actor. Allows calling actor's remote procedure calls with inferred types
+ * without establishing a persistent connection.
+ *
+ * @example
+ * ```
+ * const room = client.get<ChatRoom>(...etc...);
+ * // This calls the action named `sendMessage` on the `ChatRoom` actor without a connection.
+ * await room.sendMessage('Hello, world!');
+ * ```
+ *
+ * Private methods (e.g. those starting with `_`) are automatically excluded.
+ *
+ * @template AD The actor class that this handle is for.
+ * @see {@link ActorHandleRaw}
+ */
+export type ActorHandle<AD extends AnyActorDefinition> = Omit<
+	ActorHandleRaw,
+	"connect"
+> & {
+	// Add typed version of ActorConn (instead of using AnyActorDefinition)
+	connect(): ActorConn<AD>;
+	// Resolve method returns the actor ID
+	resolve(): Promise<string>;
+} & ActorDefinitionActions<AD>;

package/src/client/actor-query.ts

@@ -0,0 +1,112 @@
+import type { Context as HonoContext } from "hono";
+import * as errors from "@/actor/errors";
+import { stringifyError } from "@/common/utils";
+import type { ManagerDriver } from "@/driver-helpers/mod";
+import type { ActorQuery } from "@/manager/protocol/query";
+import { ActorSchedulingError } from "./errors";
+import { logger } from "./log";
+
+/**
+ * Query the manager driver to get or create a actor based on the provided query
+ */
+export async function queryActor(
+	c: HonoContext | undefined,
+	query: ActorQuery,
+	managerDriver: ManagerDriver,
+): Promise<{ actorId: string }> {
+	logger().debug({ msg: "querying actor", query: JSON.stringify(query) });
+	let actorOutput: { actorId: string };
+	if ("getForId" in query) {
+		const output = await managerDriver.getForId({
+			c,
+			name: query.getForId.name,
+			actorId: query.getForId.actorId,
+		});
+		if (!output) throw new errors.ActorNotFound(query.getForId.actorId);
+		actorOutput = output;
+	} else if ("getForKey" in query) {
+		const existingActor = await managerDriver.getWithKey({
+			c,
+			name: query.getForKey.name,
+			key: query.getForKey.key,
+		});
+		if (!existingActor) {
+			throw new errors.ActorNotFound(
+				`${query.getForKey.name}:${JSON.stringify(query.getForKey.key)}`,
+			);
+		}
+		actorOutput = existingActor;
+	} else if ("getOrCreateForKey" in query) {
+		const getOrCreateOutput = await managerDriver.getOrCreateWithKey({
+			c,
+			name: query.getOrCreateForKey.name,
+			key: query.getOrCreateForKey.key,
+			input: query.getOrCreateForKey.input,
+			region: query.getOrCreateForKey.region,
+		});
+		actorOutput = {
+			actorId: getOrCreateOutput.actorId,
+		};
+	} else if ("create" in query) {
+		const createOutput = await managerDriver.createActor({
+			c,
+			name: query.create.name,
+			key: query.create.key,
+			input: query.create.input,
+			region: query.create.region,
+		});
+		actorOutput = {
+			actorId: createOutput.actorId,
+		};
+	} else {
+		throw new errors.InvalidRequest("Invalid query format");
+	}
+
+	logger().debug({ msg: "actor query result", actorId: actorOutput.actorId });
+	return { actorId: actorOutput.actorId };
+}
+
+/**
+ * Extract the actor name from a query.
+ */
+export function getActorNameFromQuery(query: ActorQuery): string {
+	if ("getForId" in query) return query.getForId.name;
+	if ("getForKey" in query) return query.getForKey.name;
+	if ("getOrCreateForKey" in query) return query.getOrCreateForKey.name;
+	if ("create" in query) return query.create.name;
+	throw new errors.InvalidRequest("Invalid query format");
+}
+
+/**
+ * Fetch actor details and check for scheduling errors.
+ */
+export async function checkForSchedulingError(
+	group: string,
+	code: string,
+	actorId: string,
+	query: ActorQuery,
+	driver: ManagerDriver,
+): Promise<ActorSchedulingError | null> {
+	const name = getActorNameFromQuery(query);
+
+	try {
+		const actor = await driver.getForId({ name, actorId });
+
+		if (actor?.error) {
+			logger().info({
+				msg: "found actor scheduling error",
+				actorId,
+				error: actor.error,
+			});
+			return new ActorSchedulingError(group, code, actorId, actor.error);
+		}
+	} catch (err) {
+		logger().warn({
+			msg: "failed to fetch actor details for scheduling error check",
+			actorId,
+			error: stringifyError(err),
+		});
+	}
+
+	return null;
+}