rivetkit 2.3.0-rc.5 → 2.3.0-rc.6

package/src/actor/errors.ts

@@ -14,6 +14,15 @@ export interface RivetErrorOptions extends ErrorOptions {
 	metadata?: unknown;
 	/** Explicit HTTP status override for router responses. */
 	statusCode?: number;
+	/** Actor context associated with this error. */
+	actor?: ActorSpecifier;
+}
+
+/** Identifies the actor that was handling work when an error was produced. */
+export interface ActorSpecifier {
+	actorId: string;
+	generation: number;
+	key?: string;
 }
 
 export interface RivetErrorLike {
@@ -24,8 +33,11 @@ export interface RivetErrorLike {
 	metadata?: unknown;
 	public?: boolean;
 	statusCode?: number;
+	actor?: ActorSpecifier;
 }
 
+export interface BridgeRivetErrorPayload extends RivetErrorLike {}
+
 export interface UserErrorOptions extends ErrorOptions {
 	/**
 	 * Machine readable code for this error. Useful for catching different types of
@@ -48,6 +60,7 @@ function looksLikeRivetErrorOptions(
 		("public" in value ||
 			"metadata" in value ||
 			"statusCode" in value ||
+			"actor" in value ||
 			"cause" in value)
 	);
 }
@@ -85,12 +98,25 @@ export function isRivetErrorLike(
 	);
 }
 
+function isActorSpecifier(value: unknown): value is ActorSpecifier {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"actorId" in value &&
+		typeof value.actorId === "string" &&
+		"generation" in value &&
+		typeof value.generation === "number" &&
+		(!("key" in value) || value.key === undefined || typeof value.key === "string")
+	);
+}
+
 export class RivetError extends Error {
 	__type = "RivetError" as const;
 
 	public public: boolean;
 	public metadata?: unknown;
 	public statusCode: number;
+	public actor?: ActorSpecifier;
 	public readonly group: string;
 	public readonly code: string;
 
@@ -123,6 +149,7 @@ export class RivetError extends Error {
 		this.public = normalized.public ?? false;
 		this.metadata = normalized.metadata;
 		this.statusCode = normalized.statusCode ?? (this.public ? 400 : 500);
+		this.actor = normalized.actor;
 	}
 
 	toString() {
@@ -165,6 +192,7 @@ export function toRivetError(
 			public: error.public,
 			statusCode: error.statusCode,
 			metadata: error.metadata,
+			actor: error.actor,
 			cause: error instanceof Error ? error.cause : undefined,
 		});
 	}
@@ -177,6 +205,7 @@ export function toRivetError(
 			public: fallback?.public,
 			statusCode: fallback?.statusCode,
 			metadata: fallback?.metadata,
+			actor: fallback?.actor,
 			cause: error instanceof Error ? error : undefined,
 		},
 	);
@@ -190,10 +219,13 @@ export function encodeBridgeRivetError(error: RivetErrorLike): string {
 		metadata: error.metadata,
 		public: error.public,
 		statusCode: error.statusCode,
+		actor: error.actor,
 	})}`;
 }
 
-export function decodeBridgeRivetError(value: string): RivetError | undefined {
+export function decodeBridgeRivetErrorPayload(
+	value: string,
+): BridgeRivetErrorPayload | undefined {
 	if (!value.startsWith(BRIDGE_RIVET_ERROR_PREFIX)) {
 		return undefined;
 	}
@@ -201,21 +233,34 @@ export function decodeBridgeRivetError(value: string): RivetError | undefined {
 	try {
 		const payload = JSON.parse(
 			value.slice(BRIDGE_RIVET_ERROR_PREFIX.length),
-		) as RivetErrorLike;
+		) as BridgeRivetErrorPayload;
 		if (!isRivetErrorLike(payload)) {
 			return undefined;
 		}
+		if (payload.actor !== undefined && !isActorSpecifier(payload.actor)) {
+			return undefined;
+		}
 
-		return new RivetError(payload.group, payload.code, payload.message, {
-			metadata: payload.metadata,
-			public: payload.public,
-			statusCode: payload.statusCode,
-		});
+		return payload;
 	} catch {
 		return undefined;
 	}
 }
 
+export function decodeBridgeRivetError(value: string): RivetError | undefined {
+	const payload = decodeBridgeRivetErrorPayload(value);
+	if (!payload) {
+		return undefined;
+	}
+
+	return new RivetError(payload.group, payload.code, payload.message, {
+		metadata: payload.metadata,
+		public: payload.public,
+		statusCode: payload.statusCode,
+		actor: payload.actor,
+	});
+}
+
 export function isRivetErrorCode(
 	error: unknown,
 	group: string,
@@ -241,6 +286,7 @@ export function internalError(
 			public: options?.public,
 			statusCode: options?.statusCode,
 			metadata: options?.metadata,
+			actor: options?.actor,
 			cause: options?.cause,
 		},
 	);

package/src/client/actor-conn.ts

@@ -56,7 +56,6 @@ import {
 	type QueueSendResult,
 	type QueueSendWaitOptions,
 } from "./queue";
-import { resolveGatewayTarget } from "./resolve-gateway-target";
 import {
 	type WebSocketMessage as ConnMessage,
 	messageLength,
@@ -217,6 +216,9 @@ export class ActorConnRaw {
 		this.#encoding = encoding;
 		this.#actorResolutionState = actorResolutionState;
 		this.#gatewayOptions = resolveActorGatewayOptions(gatewayOptions);
+		if ("getForId" in actorResolutionState) {
+			this.#actorId = actorResolutionState.getForId.actorId;
+		}
 		this.#readyPromise = promiseWithResolvers((reason) =>
 			logger().warn({
 				msg: "unhandled ready promise rejection",
@@ -578,9 +580,7 @@ export class ActorConnRaw {
 
 	async #connectWebSocket() {
 		const params = await this.#resolveConnectionParams();
-		const target = this.#gatewayOptions.skipReadyWait
-			? await this.#resolveGatewayTargetForSkipReadyWait()
-			: getGatewayTarget(this.#actorResolutionState);
+		const target = getGatewayTarget(this.#actorResolutionState);
 		const ws = await this.#driver.openWebSocket(
 			PATH_CONNECT,
 			target,
@@ -634,25 +634,6 @@ export class ActorConnRaw {
 		});
 	}
 
-	async #resolveGatewayTargetForSkipReadyWait() {
-		if ("getForId" in this.#actorResolutionState) {
-			return {
-				directId: this.#actorResolutionState.getForId.actorId,
-			} as const;
-		}
-
-		if (this.#actorId) {
-			return { directId: this.#actorId } as const;
-		}
-
-		return {
-			directId: await resolveGatewayTarget(
-				this.#driver,
-				this.#actorResolutionState,
-			),
-		} as const;
-	}
-
 	/** Called by the onopen event from drivers. */
 	#handleOnOpen() {
 		// Connection was disposed before Init message arrived - close the websocket to avoid leak
@@ -754,7 +735,7 @@ export class ActorConnRaw {
 			this.#handleOnOpen();
 		} else if (response.body.tag === "Error") {
 			// Connection error
-			const { group, code, message, metadata, actionId } =
+			const { group, code, message, metadata, actionId, actor } =
 				response.body.val;
 
 			if (actionId !== null) {
@@ -769,10 +750,16 @@ export class ActorConnRaw {
 					code,
 					message,
 					metadata,
+					actorId: actor?.actorId,
+					generation: actor?.generation,
+					actorKey: actor?.key,
 				});
 
 				inFlight.reject(
-					new errors.ActorError(group, code, message, metadata),
+					new errors.ActorError(group, code, message, {
+						metadata,
+						actor,
+					}),
 				);
 			} else {
 				logger().warn({
@@ -781,12 +768,18 @@ export class ActorConnRaw {
 					code,
 					message,
 					metadata,
+					actorId: actor?.actorId,
+					generation: actor?.generation,
+					actorKey: actor?.key,
 				});
 
 				if (this.#shouldReconnectForStaleActor(group, code)) {
 					this.#clearResolvedActorIdentity();
 					this.#onOpenPromise?.reject(
-						new errors.ActorError(group, code, message, metadata),
+						new errors.ActorError(group, code, message, {
+							metadata,
+							actor,
+						}),
 					);
 					return;
 				}
@@ -796,7 +789,7 @@ export class ActorConnRaw {
 					group,
 					code,
 					message,
-					metadata,
+					{ metadata, actor },
 				);
 				if (errors.isSchedulingError(group, code) && this.#actorId) {
 					const schedulingError = await checkForSchedulingError(
@@ -1368,6 +1361,7 @@ export class ActorConnRaw {
 						message: string;
 						metadata: unknown;
 						actionId: bigint | null;
+						actor?: errors.ActorSpecifier;
 					};
 			  }
 			| { tag: "ActionResponse"; val: { id: bigint; output: unknown } }
@@ -1382,8 +1376,26 @@ export class ActorConnRaw {
 			buffer,
 			CLIENT_PROTOCOL_TO_CLIENT,
 			ToClientSchema,
-			// JSON: values are already the correct type
-			(msg): ToClientJson => msg as ToClientJson,
+			// JSON/CBOR: normalize actor generation to the public number shape.
+			(msg): any => {
+				if (msg.body.tag !== "Error" || !msg.body.val.actor) {
+					return msg as ToClientJson;
+				}
+				return {
+					body: {
+						tag: "Error",
+						val: {
+							...msg.body.val,
+							actor: {
+								...msg.body.val.actor,
+								generation: Number(
+									msg.body.val.actor.generation,
+								),
+							},
+						},
+					},
+				};
+			},
 			// BARE: need to decode ArrayBuffer fields back to unknown
 			(msg): any => {
 				if (msg.body.tag === "Error") {
@@ -1402,6 +1414,17 @@ export class ActorConnRaw {
 										)
 									: null,
 								actionId: msg.body.val.actionId,
+								actor: msg.body.val.actor
+									? {
+											actorId: msg.body.val.actor.actorId,
+											generation: Number(
+												msg.body.val.actor.generation,
+											),
+											key:
+												msg.body.val.actor.key ??
+												undefined,
+										}
+									: undefined,
 							},
 						},
 					};

package/src/client/actor-handle.ts

@@ -1,4 +1,5 @@
 import type { AnyActorDefinition } from "@/actor/definition";
+import type { ActorSpecifier } from "@/actor/errors";
 import type { Encoding } from "@/common/encoding";
 import {
 	HEADER_CONN_PARAMS,
@@ -139,7 +140,13 @@ export class ActorHandleRaw {
 			for (let attempt = 0; attempt < maxAttempts; attempt++) {
 				let actorId: string | undefined;
 				try {
-					const target = await this.#resolveActionTarget(useQueryTarget);
+					const gatewayOptions = resolveActorGatewayOptions(
+						this.#gatewayOptions,
+					);
+					const target = await this.#resolveGatewayRequestTarget(
+						useQueryTarget,
+						gatewayOptions,
+					);
 					actorId = "directId" in target ? target.directId : undefined;
 
 					return await createQueueSender({
@@ -149,17 +156,13 @@ export class ActorHandleRaw {
 							return await this.#driver.sendRequest(
 								target,
 								request,
-								resolveActorGatewayOptions(
-									this.#gatewayOptions,
-								),
+								gatewayOptions,
 							);
 						},
 					}).send(name, body, options as any);
 				} catch (err) {
-					const { group, code, message, metadata } = deconstructError(
+					const { group, code, message, metadata, actor } = deconstructError(
 						err,
-						logger(),
-						{},
 						true,
 					);
 
@@ -216,7 +219,7 @@ export class ActorHandleRaw {
 						continue;
 					}
 
-					throw new ActorError(group, code, message, metadata);
+					throw new ActorError(group, code, message, { metadata, actor });
 				}
 			}
 
@@ -270,7 +273,10 @@ export class ActorHandleRaw {
 		for (let attempt = 0; attempt < maxAttempts; attempt++) {
 			let actorId: string | undefined;
 			try {
-				const target = await this.#resolveActionTarget(useQueryTarget);
+				const target = await this.#resolveGatewayRequestTarget(
+					useQueryTarget,
+					gatewayOptions,
+				);
 				actorId = "directId" in target ? target.directId : undefined;
 
 				logger().debug(
@@ -337,10 +343,8 @@ export class ActorHandleRaw {
 				}
 				return output;
 			} catch (err) {
-				const { group, code, message, metadata } = deconstructError(
+				const { group, code, message, metadata, actor } = deconstructError(
 					err,
-					logger(),
-					{},
 					true,
 				);
 
@@ -382,7 +386,7 @@ export class ActorHandleRaw {
 						"actor",
 						"not_found",
 						"The actor does not exist or was destroyed.",
-						metadata,
+						{ metadata, actor },
 					);
 				}
 
@@ -398,7 +402,7 @@ export class ActorHandleRaw {
 					continue;
 				}
 
-				throw new ActorError(group, code, message, metadata);
+				throw new ActorError(group, code, message, { metadata, actor });
 			}
 		}
 
@@ -561,6 +565,17 @@ export class ActorHandleRaw {
 		}
 	}
 
+	async #resolveGatewayRequestTarget(
+		useQueryTarget: boolean,
+		gatewayOptions: ActorGatewayOptions,
+	) {
+		if (gatewayOptions.skipReadyWait) {
+			return getGatewayTarget(this.#actorResolutionState);
+		}
+
+		return await this.#resolveActionTarget(useQueryTarget);
+	}
+
 	/**
 	 * Establishes a persistent connection to the actor.
 	 *
@@ -619,7 +634,10 @@ export class ActorHandleRaw {
 		for (let attempt = 0; attempt < maxAttempts; attempt++) {
 			let actorId: string | undefined;
 			try {
-				const target = await this.#resolveActionTarget(useQueryTarget);
+				const target = await this.#resolveGatewayRequestTarget(
+					useQueryTarget,
+					gatewayOptions,
+				);
 				actorId = "directId" in target ? target.directId : undefined;
 				const response = await rawHttpFetch(
 					this.#driver,
@@ -644,10 +662,8 @@ export class ActorHandleRaw {
 				}
 				return response;
 			} catch (err) {
-				const { group, code, message, metadata } = deconstructError(
+				const { group, code, message, metadata, actor } = deconstructError(
 					err,
-					logger(),
-					{},
 					true,
 				);
 
@@ -691,7 +707,7 @@ export class ActorHandleRaw {
 					continue;
 				}
 
-				throw new ActorError(group, code, message, metadata);
+				throw new ActorError(group, code, message, { metadata, actor });
 			}
 		}
 
@@ -771,6 +787,7 @@ export class ActorHandleRaw {
 		code: string;
 		message: string;
 		metadata?: unknown;
+		actor?: ActorSpecifier;
 	} | null> {
 		if (response.ok) {
 			return null;
@@ -790,13 +807,22 @@ export class ActorHandleRaw {
 					code: string;
 					message: string;
 					metadata?: unknown;
+					actor?: ActorSpecifier;
 				}
 			>(
 				encoding,
 				new Uint8Array(await response.clone().arrayBuffer()),
 				HTTP_RESPONSE_ERROR_VERSIONED,
 				HttpResponseErrorSchema,
-				(json) => json as HttpResponseErrorJson,
+				(json) => ({
+					...json,
+					actor: json.actor
+						? {
+								...json.actor,
+								generation: Number(json.actor.generation),
+							}
+						: undefined,
+				}),
 				(bare) => ({
 					group: bare.group,
 					code: bare.code,
@@ -804,6 +830,13 @@ export class ActorHandleRaw {
 					metadata: bare.metadata
 						? decodeCborCompat(new Uint8Array(bare.metadata))
 						: undefined,
+					actor: bare.actor
+						? {
+								actorId: bare.actor.actorId,
+								generation: Number(bare.actor.generation),
+								key: bare.actor.key ?? undefined,
+							}
+						: undefined,
 				}),
 			);
 		} catch {
@@ -824,9 +857,10 @@ export class ActorHandleRaw {
 			this.#gatewayOptions,
 			options,
 		);
-		const target = gatewayOptions.skipReadyWait
-			? await this.#resolveActionTarget(false)
-			: getGatewayTarget(this.#actorResolutionState);
+		const target = await this.#resolveGatewayRequestTarget(
+			false,
+			gatewayOptions,
+		);
 		return await rawWebSocket(
 			this.#driver,
 			target,

package/src/client/errors.ts

@@ -1,6 +1,7 @@
 import {
 	INTERNAL_ERROR_CODE,
 	RivetError,
+	type ActorSpecifier,
 	type RivetErrorLike,
 	UserError,
 } from "@/actor/errors";
@@ -21,7 +22,7 @@ export class MalformedResponseMessage extends ActorClientError {
 
 export { RivetError, RivetError as ActorError, UserError };
 export type ActorSchedulingError = RivetError;
-export type { RivetErrorLike };
+export type { ActorSpecifier, RivetErrorLike };
 
 export class HttpRequestError extends ActorClientError {
 	constructor(message: string, opts?: { cause?: unknown }) {

package/src/client/raw-utils.ts

@@ -96,13 +96,11 @@ export async function rawHttpFetch(
 		return driver.sendRequest(target, proxyRequest, options);
 	} catch (err) {
 		// Standardize to ClientActorError instead of the native backend error
-		const { group, code, message, metadata } = deconstructError(
+		const { group, code, message, metadata, actor } = deconstructError(
 			err,
-			logger(),
-			{},
 			true,
 		);
-		throw new ActorError(group, code, message, metadata);
+		throw new ActorError(group, code, message, { metadata, actor });
 	}
 }
 

package/src/client/utils.ts

@@ -186,8 +186,16 @@ export async function sendHttpRequest<
 				new Uint8Array(bufferResponse),
 				HTTP_RESPONSE_ERROR_VERSIONED,
 				HttpResponseErrorSchema,
-				// JSON: metadata is already unknown
-				(json): HttpResponseErrorJson => json as HttpResponseErrorJson,
+				// JSON/CBOR: normalize actor generation to the public number shape.
+				(json): any => ({
+					...json,
+					actor: json.actor
+						? {
+								...json.actor,
+								generation: Number(json.actor.generation),
+							}
+						: undefined,
+				}),
 				// BARE: decode ArrayBuffer metadata to unknown
 				(bare): any => ({
 					group: bare.group,
@@ -196,14 +204,35 @@ export async function sendHttpRequest<
 					metadata: bare.metadata
 						? decodeCborCompat(new Uint8Array(bare.metadata))
 						: undefined,
+					actor: bare.actor
+						? {
+								actorId: bare.actor.actorId,
+								generation: Number(bare.actor.generation),
+								key: bare.actor.key ?? undefined,
+							}
+						: undefined,
 				}),
 			);
 
+			logger().warn({
+				msg: "http error response",
+				group: responseData.group,
+				code: responseData.code,
+				message: responseData.message,
+				metadata: responseData.metadata,
+				actorId: responseData.actor?.actorId,
+				generation: responseData.actor?.generation,
+				actorKey: responseData.actor?.key,
+			});
+
 			throw new ActorError(
 				responseData.group,
 				responseData.code,
 				responseData.message,
-				responseData.metadata,
+				{
+					metadata: responseData.metadata,
+					actor: responseData.actor,
+				},
 			);
 		} catch (error) {
 			// If it's already an ActorError, re-throw it

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

@@ -14,6 +14,8 @@ export const HEADER_ENCODING = "x-rivet-encoding";
 export const HEADER_CONN_PARAMS = "x-rivet-conn-params";
 
 export const HEADER_ACTOR_ID = "x-rivet-actor";
+export const HEADER_ACTOR_GENERATION = "x-rivet-actor-generation";
+export const HEADER_ACTOR_KEY = "x-rivet-actor-key";
 
 export const HEADER_RIVET_TOKEN = "x-rivet-token";
 
@@ -49,6 +51,8 @@ export const ALLOWED_PUBLIC_HEADERS = [
 	HEADER_ENCODING,
 	HEADER_CONN_PARAMS,
 	HEADER_ACTOR_ID,
+	HEADER_ACTOR_GENERATION,
+	HEADER_ACTOR_KEY,
 	HEADER_RIVET_TARGET,
 	HEADER_RIVET_ACTOR,
 	HEADER_RIVET_NAMESPACE,