rivetkit 2.3.0-rc.5 → 2.3.0-rc.7

package/src/client/actor-conn.ts

@@ -22,6 +22,7 @@ import {
 import { assertUnreachable, stringifyError } from "@/common/utils";
 import type { UniversalWebSocket } from "@/common/websocket-interface";
 import type { EngineControlClient } from "@/engine-client/driver";
+import type { JsonCompatValue } from "@/common/encoding";
 import {
 	decodeCborCompat,
 	deserializeWithEncoding,
@@ -56,7 +57,6 @@ import {
 	type QueueSendResult,
 	type QueueSendWaitOptions,
 } from "./queue";
-import { resolveGatewayTarget } from "./resolve-gateway-target";
 import {
 	type WebSocketMessage as ConnMessage,
 	messageLength,
@@ -94,8 +94,6 @@ interface EventSubscriptions<Args extends Array<unknown>> {
 	once: boolean;
 }
 
-const DEFAULT_MAX_INCOMING_MESSAGE_SIZE = 65_536;
-
 /**
  * A function that unsubscribes from an event.
  *
@@ -237,7 +235,9 @@ export class ActorConnRaw {
 			},
 		});
 
-		this.#keepNodeAliveInterval = setInterval(() => 60_000);
+		// Keep the Node event loop alive while this connection is active without blocking exit.
+		this.#keepNodeAliveInterval = setInterval(() => {}, 60_000);
+		this.#keepNodeAliveInterval.unref?.();
 	}
 
 	#clearResolvedActorIdentity() {
@@ -578,9 +578,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 +632,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 +733,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 +748,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 +766,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 +787,7 @@ export class ActorConnRaw {
 					group,
 					code,
 					message,
-					metadata,
+					{ metadata, actor },
 				);
 				if (errors.isSchedulingError(group, code) && this.#actorId) {
 					const schedulingError = await checkForSchedulingError(
@@ -1279,7 +1270,7 @@ export class ActorConnRaw {
 											name: msg.body.val.name,
 											args: bufferToArrayBuffer(
 												encodeCborCompat(
-													msg.body.val.args,
+													msg.body.val.args as JsonCompatValue,
 												),
 											),
 										},
@@ -1290,34 +1281,8 @@ export class ActorConnRaw {
 							}
 						},
 					);
-					const serializedLength = messageLength(messageSerialized);
-					if (
-						serializedLength > DEFAULT_MAX_INCOMING_MESSAGE_SIZE &&
-						message.body.tag === "ActionRequest"
-					) {
-						const actionId = Number(message.body.val.id);
-						const inFlight = this.#takeActionInFlight(actionId);
-						const error = new errors.ActorError(
-							"message",
-							"incoming_too_long",
-							"Incoming message too long",
-							{
-								maxSize: DEFAULT_MAX_INCOMING_MESSAGE_SIZE,
-								actualSize: serializedLength,
-							},
-						);
-						logger().warn({
-							msg: "rejecting oversized connection action request",
-							actionId,
-							actionName: inFlight.name,
-							actualSize: serializedLength,
-							maxSize: DEFAULT_MAX_INCOMING_MESSAGE_SIZE,
-						});
-						inFlight.reject(error);
-						this.#dispatchActorError(error);
-						return;
-					}
 					this.#websocket.send(messageSerialized);
+					const serializedLength = messageLength(messageSerialized);
 					logger().trace({
 						msg: "sent websocket message",
 						len: serializedLength,
@@ -1368,6 +1333,7 @@ export class ActorConnRaw {
 						message: string;
 						metadata: unknown;
 						actionId: bigint | null;
+						actor?: errors.ActorSpecifier;
 					};
 			  }
 			| { tag: "ActionResponse"; val: { id: bigint; output: unknown } }
@@ -1382,8 +1348,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 +1386,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,
@@ -22,6 +23,7 @@ import {
 } from "@/common/client-protocol-zod";
 import { deconstructError } from "@/common/utils";
 import type { EngineControlClient } from "@/engine-client/driver";
+import type { JsonCompatValue } from "@/common/encoding";
 import { decodeCborCompat, deserializeWithEncoding, encodeCborCompat } from "@/serde";
 import { bufferToArrayBuffer } from "@/utils";
 import type {
@@ -139,7 +141,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 +157,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 +220,7 @@ export class ActorHandleRaw {
 						continue;
 					}
 
-					throw new ActorError(group, code, message, metadata);
+					throw new ActorError(group, code, message, { metadata, actor });
 				}
 			}
 
@@ -270,7 +274,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(
@@ -326,7 +333,7 @@ export class ActorHandleRaw {
 						args,
 					}),
 					requestToBare: (args): protocol.HttpActionRequest => ({
-						args: bufferToArrayBuffer(encodeCborCompat(args)),
+						args: bufferToArrayBuffer(encodeCborCompat(args as JsonCompatValue)),
 					}),
 					responseFromJson: (json): Response => json.output as Response,
 					responseFromBare: (bare): Response =>
@@ -337,10 +344,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 +387,7 @@ export class ActorHandleRaw {
 						"actor",
 						"not_found",
 						"The actor does not exist or was destroyed.",
-						metadata,
+						{ metadata, actor },
 					);
 				}
 
@@ -398,7 +403,7 @@ export class ActorHandleRaw {
 					continue;
 				}
 
-				throw new ActorError(group, code, message, metadata);
+				throw new ActorError(group, code, message, { metadata, actor });
 			}
 		}
 
@@ -561,6 +566,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 +635,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 +663,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 +708,7 @@ export class ActorHandleRaw {
 					continue;
 				}
 
-				throw new ActorError(group, code, message, metadata);
+				throw new ActorError(group, code, message, { metadata, actor });
 			}
 		}
 
@@ -771,6 +788,7 @@ export class ActorHandleRaw {
 		code: string;
 		message: string;
 		metadata?: unknown;
+		actor?: ActorSpecifier;
 	} | null> {
 		if (response.ok) {
 			return null;
@@ -790,13 +808,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 +831,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 +858,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/queue.ts

@@ -12,6 +12,7 @@ import {
 	type HttpQueueSendResponse as HttpQueueSendResponseJson,
 	HttpQueueSendResponseSchema,
 } from "@/common/client-protocol-zod";
+import type { JsonCompatValue } from "@/common/encoding";
 import { decodeCborCompat, encodeCborCompat } from "@/serde";
 import { bufferToArrayBuffer } from "@/utils";
 import { sendHttpRequest } from "./utils";
@@ -111,7 +112,7 @@ export function createQueueSender(
 			}),
 			requestToBare: (value): protocol.HttpQueueSendRequest => ({
 				name: value.name ?? name,
-				body: bufferToArrayBuffer(encodeCborCompat(value.body)),
+				body: bufferToArrayBuffer(encodeCborCompat(value.body as JsonCompatValue)),
 				wait: value.wait ?? false,
 				timeout:
 					value.timeout !== undefined ? BigInt(value.timeout) : null,

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

@@ -3,7 +3,6 @@ import type { VersionedDataHandler } from "vbare";
 import type { z } from "zod/v4";
 import type { Encoding } from "@/common/encoding";
 import { assertUnreachable } from "@/common/utils";
-import type { HttpResponseError } from "@/common/client-protocol";
 import { HTTP_RESPONSE_ERROR_VERSIONED } from "@/common/client-protocol-versioned";
 import {
 	type HttpResponseError as HttpResponseErrorJson,
@@ -186,8 +185,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 +203,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,