rivetkit 2.0.30 → 2.0.32

package/src/client/actor-conn.ts

@@ -54,6 +54,16 @@ import {
 	sendHttpRequest,
 } from "./utils";
 
+/**
+ * Connection status for an actor connection.
+ *
+ * - `"idle"`: Not connected, no auto-reconnect (initial state, after dispose, or disabled)
+ * - `"connecting"`: Attempting to establish connection
+ * - `"connected"`: Connection is active
+ * - `"disconnected"`: Connection was lost, will auto-reconnect
+ */
+export type ActorConnStatus = "idle" | "connecting" | "connected" | "disconnected";
+
 interface ActionInFlight {
 	name: string;
 	resolve: (response: { id: bigint; output: unknown }) => void;
@@ -86,6 +96,13 @@ export type ActorErrorCallback = (error: errors.ActorError) => void;
  */
 export type ConnectionStateCallback = () => void;
 
+/**
+ * A callback for connection status changes.
+ *
+ * @typedef {Function} StatusChangeCallback
+ */
+export type StatusChangeCallback = (status: ActorConnStatus) => void;
+
 export interface SendHttpMessageOpts {
 	ephemeral: boolean;
 	signal?: AbortSignal;
@@ -104,10 +121,10 @@ export class ActorConnRaw {
 	/* Will be aborted on dispose. */
 	#abortController = new AbortController();
 
-	#connecting = false;
+	#connStatus: ActorConnStatus = "idle";
 
 	#actorId?: string;
-	#connectionId?: string;
+	#connId?: string;
 
 	#messageQueue: Array<{
 		body:
@@ -128,8 +145,7 @@ export class ActorConnRaw {
 	#errorHandlers = new Set<ActorErrorCallback>();
 	#openHandlers = new Set<ConnectionStateCallback>();
 	#closeHandlers = new Set<ConnectionStateCallback>();
-
-	#isConnected = false;
+	#statusChangeHandlers = new Set<StatusChangeCallback>();
 
 	#actionIdCounter = 0;
 
@@ -249,39 +265,86 @@ enc
 		this.#connectWithRetry();
 	}
 
-	async #connectWithRetry() {
-		this.#connecting = true;
+	#setConnStatus(status: ActorConnStatus) {
+		const prevStatus = this.#connStatus;
+		if (prevStatus === status) return;
+		this.#connStatus = status;
 
-		// Attempt to reconnect indefinitely
-		try {
-			await pRetry(this.#connectAndWait.bind(this), {
-				forever: true,
-				minTimeout: 250,
-				maxTimeout: 30_000,
+		// Notify status change handlers
+		for (const handler of [...this.#statusChangeHandlers]) {
+			try {
+				handler(status);
+			} catch (err) {
+				logger().error({
+					msg: "error in status change handler",
+					error: stringifyError(err),
+				});
+			}
+		}
 
-				onFailedAttempt: (error) => {
-					logger().warn({
-						msg: "failed to reconnect",
-						attempt: error.attemptNumber,
-						error: stringifyError(error),
+		// Notify open handlers
+		if (status === "connected") {
+			for (const handler of [...this.#openHandlers]) {
+				try {
+					handler();
+				} catch (err) {
+					logger().error({
+						msg: "error in open handler",
+						error: stringifyError(err),
 					});
-				},
+				}
+			}
+		}
 
-				// Cancel retry if aborted
-				signal: this.#abortController.signal,
-			});
-		} catch (err) {
+		// Notify close handlers (only if transitioning from Connected to Disconnected or Idle)
+		if (
+			(status === "disconnected" ||
+				status === "idle") &&
+			prevStatus === "connected"
+		) {
+			for (const handler of [...this.#closeHandlers]) {
+				try {
+					handler();
+				} catch (err) {
+					logger().error({
+						msg: "error in close handler",
+						error: stringifyError(err),
+					});
+				}
+			}
+		}
+	}
+
+	#connectWithRetry() {
+		this.#setConnStatus("connecting");
+
+		// Attempt to reconnect indefinitely
+		// This is intentionally not awaited - connection happens in background
+		pRetry(this.#connectAndWait.bind(this), {
+			forever: true,
+			minTimeout: 250,
+			maxTimeout: 30_000,
+
+			onFailedAttempt: (error) => {
+				logger().warn({
+					msg: "failed to reconnect",
+					attempt: error.attemptNumber,
+					error: stringifyError(error),
+				});
+			},
+
+			// Cancel retry if aborted
+			signal: this.#abortController.signal,
+		}).catch((err) => {
 			if ((err as Error).name === "AbortError") {
-				// Ignore abortions
 				logger().info({ msg: "connection retry aborted" });
-				return;
 			} else {
-				// Unknown error
-				throw err;
+				logger().error({
+					msg: "unexpected error in connection retry",
+					error: stringifyError(err),
+				});
 			}
-		}
-
-		this.#connecting = false;
+		});
 	}
 
 	async #connectAndWait() {
@@ -315,7 +378,7 @@ enc
 		);
 		logger().debug({
 			msg: "opened websocket",
-			connectionId: this.#connectionId,
+			connId: this.#connId,
 			readyState: ws.readyState,
 			messageQueueLength: this.#messageQueue.length,
 		});
@@ -323,7 +386,7 @@ enc
 		ws.addEventListener("open", () => {
 			logger().debug({
 				msg: "client websocket open",
-				connectionId: this.#connectionId,
+				connId: this.#connId,
 			});
 		});
 		ws.addEventListener("message", async (ev) => {
@@ -360,14 +423,24 @@ enc
 
 	/** Called by the onopen event from drivers. */
 	#handleOnOpen() {
+		// Connection was disposed before Init message arrived - close the websocket to avoid leak
+		if (this.#disposed) {
+			logger().debug({ msg: "handleOnOpen called after dispose, closing websocket" });
+			if (this.#websocket) {
+				this.#websocket.close(1000, "Disposed");
+				this.#websocket = undefined;
+			}
+			return;
+		}
+
 		logger().debug({
 			msg: "socket open",
 			messageQueueLength: this.#messageQueue.length,
-			connectionId: this.#connectionId,
+			connId: this.#connId,
 		});
 
-		// Update connection state
-		this.#isConnected = true;
+		// Update connection state (this also notifies handlers)
+		this.#setConnStatus("connected");
 
 		// Resolve open promise
 		if (this.#onOpenPromise) {
@@ -376,18 +449,6 @@ enc
 			logger().warn({ msg: "#onOpenPromise is undefined" });
 		}
 
-		// Notify open handlers
-		for (const handler of [...this.#openHandlers]) {
-			try {
-				handler();
-			} catch (err) {
-				logger().error({
-					msg: "error in open handler",
-					error: stringifyError(err),
-				});
-			}
-		}
-
 		// Resubscribe to all active events
 		for (const eventName of this.#eventSubscriptions.keys()) {
 			this.#sendSubscription(eventName, true);
@@ -431,11 +492,11 @@ enc
 		if (response.body.tag === "Init") {
 			// Store connection info
 			this.#actorId = response.body.val.actorId;
-			this.#connectionId = response.body.val.connectionId;
+			this.#connId = response.body.val.connectionId;
 			logger().trace({
 				msg: "received init message",
 				actorId: this.#actorId,
-				connectionId: this.#connectionId,
+				connId: this.#connId,
 			});
 			this.#handleOnOpen();
 		} else if (response.body.tag === "Error") {
@@ -520,86 +581,54 @@ enc
 
 	/** Called by the onclose event from drivers. */
 	#handleOnClose(event: Event | CloseEvent) {
-		// TODO: Handle queue
-		// TODO: Reconnect with backoff
-
 		// We can't use `event instanceof CloseEvent` because it's not defined in NodeJS
-		//
-		// These properties will be undefined
 		const closeEvent = event as CloseEvent;
 		const wasClean = closeEvent.wasClean;
-
-		// Update connection state and notify handlers
-		const wasConnected = this.#isConnected;
-		this.#isConnected = false;
-
-		if (wasConnected) {
-			for (const handler of [...this.#closeHandlers]) {
-				try {
-					handler();
-				} catch (err) {
-					logger().error({
-						msg: "error in close handler",
-						error: stringifyError(err),
-					});
-				}
-			}
-		}
-
-		// Reject open promise
-		if (this.#onOpenPromise) {
-			this.#onOpenPromise.reject(
-				new Error(
-					`websocket closed with code ${closeEvent.code}: ${closeEvent.reason}`,
-				),
-			);
-		}
+		const wasConnected = this.#connStatus === "connected";
 
 		logger().info({
 			msg: "socket closed",
 			code: closeEvent.code,
 			reason: closeEvent.reason,
-			wasClean: wasClean,
-			connectionId: this.#connectionId,
-			messageQueueLength: this.#messageQueue.length,
-			actionsInFlight: this.#actionsInFlight.size,
+			wasClean,
+			disposed: this.#disposed,
+			connId: this.#connId,
 		});
 
-		// Reject all in-flight actions
-		if (this.#actionsInFlight.size > 0) {
-			logger().debug({
-				msg: "rejecting in-flight actions after disconnect",
-				count: this.#actionsInFlight.size,
-				connectionId: this.#connectionId,
-				wasClean,
-			});
+		this.#websocket = undefined;
 
-			const disconnectError = new Error(
-				`${wasClean ? "Connection closed" : "Connection lost"} (code: ${closeEvent.code}, reason: ${closeEvent.reason})`,
+		if (this.#disposed) {
+			// Use ActorConnDisposed error and prevent unhandled rejection
+			this.#rejectPendingPromises(new errors.ActorConnDisposed(), true);
+		} else {
+			this.#setConnStatus("disconnected");
+			this.#rejectPendingPromises(
+				new Error(
+					`${wasClean ? "Connection closed" : "Connection lost"} (code: ${closeEvent.code}, reason: ${closeEvent.reason})`,
+				),
+				false,
 			);
 
-			for (const actionInfo of this.#actionsInFlight.values()) {
-				actionInfo.reject(disconnectError);
+			// Automatically reconnect if we were connected
+			if (wasConnected) {
+				logger().debug({ msg: "triggering reconnect", connId: this.#connId });
+				this.#connectWithRetry();
 			}
-			this.#actionsInFlight.clear();
 		}
+	}
 
-		this.#websocket = undefined;
-
-		// Automatically reconnect. Skip if already attempting to connect.
-		if (!this.#disposed && !this.#connecting) {
-			logger().debug({
-				msg: "triggering reconnect",
-				connectionId: this.#connectionId,
-				messageQueueLength: this.#messageQueue.length,
-			});
-			// TODO: Fetch actor to check if it's destroyed
-			// TODO: Add backoff for reconnect
-			// TODO: Add a way of preserving connection ID for connection state
+	#rejectPendingPromises(error: Error, suppressUnhandled: boolean) {
+		if (this.#onOpenPromise) {
+			if (suppressUnhandled) {
+				this.#onOpenPromise.promise.catch(() => {});
+			}
+			this.#onOpenPromise.reject(error);
+		}
 
-			// Attempt to connect again
-			this.#connectWithRetry();
+		for (const actionInfo of this.#actionsInFlight.values()) {
+			actionInfo.reject(error);
 		}
+		this.#actionsInFlight.clear();
 	}
 
 	/** Called by the onerror event from drivers. */
@@ -751,13 +780,23 @@ enc
 		};
 	}
 
+	/**
+	 * Returns the current connection status.
+	 *
+	 * @returns {ActorConnStatus} - The current connection status.
+	 */
+	get connStatus(): ActorConnStatus {
+		return this.#connStatus;
+	}
+
 	/**
 	 * Returns whether the connection is currently open.
 	 *
+	 * @deprecated Use `connStatus` instead.
 	 * @returns {boolean} - True if the connection is open, false otherwise.
 	 */
 	get isConnected(): boolean {
-		return this.#isConnected;
+		return this.#connStatus === "connected";
 	}
 
 	/**
@@ -795,6 +834,23 @@ enc
 		};
 	}
 
+	/**
+	 * Subscribes to connection status changes.
+	 *
+	 * This is called whenever the connection status changes between Disconnected, Connecting, and Connected.
+	 *
+	 * @param {StatusChangeCallback} callback - The callback function to execute when the status changes.
+	 * @returns {() => void} - A function to unsubscribe from the status change handler.
+	 */
+	onStatusChange(callback: StatusChangeCallback): () => void {
+		this.#statusChangeHandlers.add(callback);
+
+		// Return unsubscribe function
+		return () => {
+			this.#statusChangeHandlers.delete(callback);
+		};
+	}
+
 	#sendMessage(
 		message: {
 			body:
@@ -810,7 +866,11 @@ enc
 		opts?: SendHttpMessageOpts,
 	) {
 		if (this.#disposed) {
-			throw new errors.ActorConnDisposed();
+			if (opts?.ephemeral) {
+				return;
+			} else {
+				throw new errors.ActorConnDisposed();
+			}
 		}
 
 		let queueMessage = false;
@@ -827,7 +887,7 @@ enc
 							: readyState === 2
 								? "CLOSING"
 								: "CLOSED",
-				connectionId: this.#connectionId,
+				connId: this.#connId,
 				messageType: (message.body as any).tag,
 				actionName: (message.body as any).val?.name,
 			});
@@ -837,7 +897,7 @@ enc
 						this.#encoding,
 						message,
 						TO_SERVER_VERSIONED,
-					CLIENT_PROTOCOL_CURRENT_VERSION,
+						CLIENT_PROTOCOL_CURRENT_VERSION,
 						ToServerSchema,
 						// JSON: args is the raw value
 						(msg): ToServerJson => msg as ToServerJson,
@@ -870,7 +930,7 @@ enc
 					logger().warn({
 						msg: "failed to send message, added to queue",
 						error,
-						connectionId: this.#connectionId,
+						connId: this.#connId,
 					});
 
 					// Assuming the socket is disconnected and will be reconnected soon
@@ -894,7 +954,7 @@ enc
 			logger().debug({
 				msg: "queued connection message",
 				queueLength: this.#messageQueue.length,
-				connectionId: this.#connectionId,
+				connId: this.#connId,
 				messageType: (message.body as any).tag,
 				actionName: (message.body as any).val?.name,
 			});
@@ -993,8 +1053,17 @@ enc
 	 * Get the connection ID (for testing purposes).
 	 * @internal
 	 */
+	get connId(): string | undefined {
+		return this.#connId;
+	}
+
+	/**
+	 * Get the connection ID (for testing purposes).
+	 * @internal
+	 * @deprecated Use `connId` instead.
+	 */
 	get connectionId(): string | undefined {
-		return this.#connectionId;
+		return this.#connId;
 	}
 
 	/**
@@ -1013,35 +1082,29 @@ enc
 
 		logger().debug({ msg: "disposing actor conn" });
 
+		// Set status to Idle (intentionally closed, no auto-reconnect)
+		this.#setConnStatus("idle");
+
 		// Clear interval so NodeJS process can exit
 		clearInterval(this.#keepNodeAliveInterval);
 
-		// Abort
+		// Abort retry loop
 		this.#abortController.abort();
 
 		// Remove from registry
 		this.#client[ACTOR_CONNS_SYMBOL].delete(this);
 
-		// Disconnect websocket cleanly
+		// Close websocket (#handleOnClose will reject pending promises)
 		if (this.#websocket) {
-			logger().debug("closing ws");
-
 			const ws = this.#websocket;
-			// Check if WebSocket is already closed or closing
-			if (
-				ws.readyState === 2 /* CLOSING */ ||
-				ws.readyState === 3 /* CLOSED */
-			) {
-				logger().debug({ msg: "ws already closed or closing" });
-			} else {
+			if (ws.readyState !== 2 /* CLOSING */ && ws.readyState !== 3 /* CLOSED */) {
 				const { promise, resolve } = promiseWithResolvers();
-				ws.addEventListener("close", () => {
-					logger().debug({ msg: "ws closed" });
-					resolve(undefined);
-				});
-				ws.close(1000, "Normal closure");
+				ws.addEventListener("close", () => resolve(undefined));
+				ws.close(1000, "Disposed");
 				await promise;
 			}
+		} else {
+			this.#rejectPendingPromises(new errors.ActorConnDisposed(), true);
 		}
 		this.#websocket = undefined;
 	}

package/src/client/config.ts

@@ -32,7 +32,10 @@ export const ClientConfigSchema = z.object({
 
 	encoding: EncodingSchema.default("bare"),
 
-	headers: z.record(z.string(), z.string()).optional().default(() => ({})),
+	headers: z
+		.record(z.string(), z.string())
+		.optional()
+		.default(() => ({})),
 
 	// See RunConfig.getUpgradeWebSocket
 	getUpgradeWebSocket: z.custom<GetUpgradeWebSocket>().optional(),

package/src/client/mod.ts

@@ -14,6 +14,7 @@ export {
 export type { Encoding } from "@/actor/protocol/serde";
 export {
 	ActorClientError,
+	ActorConnDisposed,
 	ActorError,
 	InternalError,
 	MalformedResponseMessage,
@@ -25,8 +26,9 @@ export type {
 	ActorConn,
 	ConnectionStateCallback,
 	EventUnsubscribe,
+	StatusChangeCallback,
 } from "./actor-conn";
-export { ActorConnRaw } from "./actor-conn";
+export { ActorConnRaw, ActorConnStatus } from "./actor-conn";
 export type { ActorHandle } from "./actor-handle";
 export { ActorHandleRaw } from "./actor-handle";
 export type {

package/src/client/utils.ts

@@ -1,9 +1,9 @@
 import * as cbor from "cbor-x";
 import invariant from "invariant";
+import type { VersionedDataHandler } from "vbare";
 import type { z } from "zod";
 import type { Encoding } from "@/actor/protocol/serde";
 import { assertUnreachable } from "@/common/utils";
-import type { VersionedDataHandler } from "vbare";
 import type { HttpResponseError } from "@/schemas/client-protocol/mod";
 import { HTTP_RESPONSE_ERROR_VERSIONED } from "@/schemas/client-protocol/versioned";
 import {

package/src/driver-test-suite/tests/action-features.ts

@@ -136,5 +136,68 @@ export function runActionFeaturesTests(driverTestConfig: DriverTestConfig) {
 				expect(results).toContain("delayed");
 			});
 		});
+
+		describe("Large Payloads", () => {
+			test("should handle large request within size limit", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				const instance = client.largePayloadActor.getOrCreate();
+
+				// Create a large payload that's under the default 64KB limit
+				// Each item is roughly 60 bytes, so 800 items ≈ 48KB
+				const items: string[] = [];
+				for (let i = 0; i < 800; i++) {
+					items.push(`Item ${i} with some additional text to increase size`);
+				}
+
+				const result = await instance.processLargeRequest({ items });
+
+				expect(result.itemCount).toBe(800);
+				expect(result.firstItem).toBe("Item 0 with some additional text to increase size");
+				expect(result.lastItem).toBe("Item 799 with some additional text to increase size");
+			});
+
+			test("should reject request exceeding maxIncomingMessageSize", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				const instance = client.largePayloadActor.getOrCreate();
+
+				// Create a payload that exceeds the default 64KB limit
+				// Each item is roughly 60 bytes, so 1500 items ≈ 90KB
+				const items: string[] = [];
+				for (let i = 0; i < 1500; i++) {
+					items.push(`Item ${i} with some additional text to increase size`);
+				}
+
+				await expect(
+					instance.processLargeRequest({ items })
+				).rejects.toThrow();
+			});
+
+			test("should handle large response", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				const instance = client.largePayloadActor.getOrCreate();
+
+				// Request a large response (800 items ≈ 48KB)
+				const result = await instance.getLargeResponse(800);
+
+				expect(result.items).toHaveLength(800);
+				expect(result.items[0]).toBe("Item 0 with some additional text to increase size");
+				expect(result.items[799]).toBe("Item 799 with some additional text to increase size");
+			});
+
+			test("should reject response exceeding maxOutgoingMessageSize", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				const instance = client.largePayloadActor.getOrCreate();
+
+				// Request a response that exceeds the default 1MB limit
+				// Each item is roughly 60 bytes, so 20000 items ≈ 1.2MB
+				await expect(
+					instance.getLargeResponse(20000)
+				).rejects.toThrow();
+			});
+		});
 	});
 }