@rivetkit/engine-runner 2.1.9 → 2.1.11-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rivetkit/engine-runner",
-  "version": "2.1.9",
+  "version": "2.1.11-rc.1",
   "type": "module",
   "files": [
     "dist",
@@ -21,8 +21,8 @@
     "uuid": "^12.0.0",
     "pino": "^9.9.5",
     "ws": "^8.18.3",
-    "@rivetkit/engine-runner-protocol": "2.1.9",
-    "@rivetkit/virtual-websocket": "2.0.33"
+    "@rivetkit/virtual-websocket": "2.0.33",
+    "@rivetkit/engine-runner-protocol": "2.1.11-rc.1"
   },
   "devDependencies": {
     "@types/node": "^22.18.1",

package/src/actor.ts

@@ -37,6 +37,13 @@ export class RunnerActor {
 	 **/
 	hibernationRestored: boolean = false;
 
+	/**
+	 * Set when the actor has explicitly requested to stop (e.g. c.destroy()).
+	 * Used to send StopCode.Ok (graceful) vs StopCode.Error (ungraceful) so
+	 * the engine crash policy handles sleepable actors correctly.
+	 **/
+	stopIntentSent: boolean = false;
+
 	constructor(
 		actorId: string,
 		generation: number,

package/src/mod.ts

@@ -217,6 +217,7 @@ export class Runner {
 	runnerId?: string;
 	#started: boolean = false;
 	#shutdown: boolean = false;
+	#draining: boolean = false;
 	#reconnectAttempt: number = 0;
 	#reconnectTimeout?: NodeJS.Timeout;
 
@@ -303,6 +304,24 @@ export class Runner {
 		// The server will send a StopActor command if it wants to fully stop
 	}
 
+	/**
+	 * Like stopActor but marks the actor for graceful destruction.
+	 * This ensures the engine destroys the actor instead of sleeping it.
+	 *
+	 * NOTE: If a drain (GoingAway) occurs after this is called but before the
+	 * stop completes, the engine's going_away flag overrides graceful_exit and
+	 * the actor will sleep instead of being destroyed. The destroy intent is
+	 * lost in this race. This is acceptable since the actor will be rescheduled
+	 * elsewhere and can be destroyed on the next wake.
+	 */
+	destroyActor(actorId: string, generation?: number) {
+		const actor = this.getActor(actorId, generation);
+		if (!actor) return;
+
+		actor.stopIntentSent = true;
+		this.#sendActorIntent(actorId, actor.generation, "stop");
+	}
+
 	async forceStopActor(actorId: string, generation?: number) {
 		this.log?.debug({
 			msg: "force stopping actor",
@@ -502,6 +521,7 @@ export class Runner {
 			return;
 		}
 		this.#shutdown = true;
+		this.#draining = !immediate;
 
 		this.log?.info({
 			msg: "starting shutdown",
@@ -1233,7 +1253,9 @@ export class Runner {
 			actorState = {
 				tag: "ActorStateStopped",
 				val: {
-					code: protocol.StopCode.Ok,
+					code: actor.stopIntentSent || this.#draining
+						? protocol.StopCode.Ok
+						: protocol.StopCode.Error,
 					message: null,
 				},
 			};