fix(rivetkit): add lifecycle error retry and gateway HTTP routing

Author: NathanFlurry

rivetkit-typescript/packages/rivetkit/src/actor/errors.ts

@@ -367,6 +367,30 @@ export function actorStopping(identifier?: string): RivetError {
 	);
 }
 
+export interface ActorRestartingOptions {
+	phase?: "stopping" | "sleeping" | "waking" | "runner_shutdown";
+	retryAfterMs?: number;
+}
+
+export function actorRestarting(opts?: ActorRestartingOptions): RivetError {
+	return new RivetError(
+		"actor",
+		"restarting",
+		"Actor is restarting. Retry the request.",
+		{
+			public: true,
+			statusCode: 503,
+			metadata: {
+				retryable: true,
+				...(opts?.phase ? { phase: opts.phase } : {}),
+				...(opts?.retryAfterMs !== undefined
+					? { retryAfterMs: opts.retryAfterMs }
+					: {}),
+			},
+		},
+	);
+}
+
 export function forbiddenError(): RivetError {
 	return new RivetError("auth", "forbidden", "Forbidden", {
 		public: true,

rivetkit-typescript/packages/rivetkit/src/actor/instance/mod.ts

@@ -919,7 +919,7 @@ export class ActorInstance<
 	async restartRunHandler(): Promise<void> {
 		this.assertReady();
 		if (this.#stopCalled)
-			throw new errors.InternalError("Actor is stopping");
+			throw errors.actorRestarting({ phase: "stopping" });
 		if (this.#runHandlerActive && this.#runPromise) {
 			await this.#runPromise;
 		}

rivetkit-typescript/packages/rivetkit/src/client/actor-conn.ts

@@ -1,5 +1,5 @@
 import invariant from "invariant";
-import pRetry from "p-retry";
+import pRetry, { AbortError } from "p-retry";
 import type { AnyActorDefinition } from "@/actor/definition";
 import { PATH_CONNECT } from "@/common/actor-router-consts";
 import type * as protocol from "@/common/client-protocol";
@@ -44,6 +44,7 @@ import {
 } from "./actor-query";
 import { ACTOR_CONNS_SYMBOL, type ClientRaw } from "./client";
 import * as errors from "./errors";
+import { isRetryableLifecycleReconnectSignal } from "./lifecycle-errors";
 import { logger } from "./log";
 import {
 	createQueueSender,
@@ -441,7 +442,11 @@ export class ActorConnRaw {
 			// Cancel retry if aborted
 			signal: this.#abortController.signal,
 		}).catch((err) => {
-			if ((err as Error).name === "AbortError") {
+			if (
+				err instanceof AbortError ||
+				(err as Error).name === "AbortError" ||
+				!this.#shouldRetryConnectionOpenError(err)
+			) {
 				logger().info({ msg: "connection retry aborted" });
 			} else {
 				logger().error({
@@ -468,11 +473,51 @@ export class ActorConnRaw {
 
 			// Wait for result
 			await this.#onOpenPromise.promise;
+		} catch (error) {
+			if (this.#shouldRetryConnectionOpenError(error)) {
+				throw error;
+			}
+
+			const actorError =
+				error instanceof errors.ActorError
+					? error
+					: new errors.ActorError(
+							"client",
+							"connection_open_failed",
+							`Failed to open connection: ${stringifyError(error)}`,
+							{ error: stringifyError(error) },
+						);
+
+			this.#clearQueuedMessages();
+			this.#rejectPendingPromises(actorError, false);
+			this.#dispatchActorError(actorError);
+			this.#setConnStatus("idle");
+
+			throw new AbortError(
+				error instanceof Error
+					? error
+					: new Error(stringifyError(error)),
+			);
 		} finally {
 			this.#onOpenPromise = undefined;
 		}
 	}
 
+	#shouldRetryConnectionOpenError(error: unknown): boolean {
+		if (error instanceof errors.ActorConnDisposed) {
+			return false;
+		}
+
+		if (
+			error instanceof errors.ActorError &&
+			this.#shouldReconnectForStaleActor(error.group, error.code)
+		) {
+			return true;
+		}
+
+		return isRetryableLifecycleReconnectSignal(error);
+	}
+
 	#clearQueuedMessages() {
 		if (this.#messageQueue.length === 0) return;
 

rivetkit-typescript/packages/rivetkit/src/client/actor-handle.ts

@@ -39,6 +39,7 @@ import {
 } from "./actor-query";
 import { type ClientRaw, CREATE_ACTOR_CONN_PROXY } from "./client";
 import { ActorError, isSchedulingError } from "./errors";
+import { retryOnLifecycleBoundary } from "./lifecycle-errors";
 import { logger } from "./log";
 import {
 	createQueueSender,
@@ -233,7 +234,12 @@ export class ActorHandleRaw {
 				`Invalid action call: expected an options object { name, args }, got ${typeof opts}. Use handle.actionName(...args) for the shorthand API.`,
 			);
 		}
-		return (await this.#sendActionNow(opts)) as Response;
+		const run = async () => (await this.#sendActionNow(opts)) as Response;
+		if (opts.name === "destroy") {
+			return await run();
+		}
+
+		return await retryOnLifecycleBoundary(run, { signal: opts.signal });
 	}
 
 	async #sendActionNow(opts: {