@rivetkit/engine-runner 2.1.8 → 2.1.10

package/dist/mod.d.cts

@@ -97,6 +97,12 @@ declare class RunnerActor {
      * that the caller is implemented correctly.
      **/
     hibernationRestored: boolean;
+    /**
+     * 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;
     constructor(actorId: string, generation: number, config: ActorConfig, 
     /**
      * List of hibernating requests provided by the gateway on actor start.
@@ -253,6 +259,17 @@ declare class Runner {
     constructor(config: RunnerConfig);
     sleepActor(actorId: string, generation?: number): void;
     stopActor(actorId: string, generation?: number): Promise<void>;
+    /**
+     * 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): void;
     forceStopActor(actorId: string, generation?: number): Promise<void>;
     getActor(actorId: string, generation?: number): RunnerActor | undefined;
     getAndWaitForActor(actorId: string, generation?: number): Promise<RunnerActor | undefined>;

package/dist/mod.d.ts

@@ -97,6 +97,12 @@ declare class RunnerActor {
      * that the caller is implemented correctly.
      **/
     hibernationRestored: boolean;
+    /**
+     * 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;
     constructor(actorId: string, generation: number, config: ActorConfig, 
     /**
      * List of hibernating requests provided by the gateway on actor start.
@@ -253,6 +259,17 @@ declare class Runner {
     constructor(config: RunnerConfig);
     sleepActor(actorId: string, generation?: number): void;
     stopActor(actorId: string, generation?: number): Promise<void>;
+    /**
+     * 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): void;
     forceStopActor(actorId: string, generation?: number): Promise<void>;
     getActor(actorId: string, generation?: number): RunnerActor | undefined;
     getAndWaitForActor(actorId: string, generation?: number): Promise<RunnerActor | undefined>;

package/dist/mod.js

@@ -125,6 +125,12 @@ var RunnerActor = class {
    * that the caller is implemented correctly.
    **/
   hibernationRestored = 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 = false;
   // Pending request methods
   getPendingRequest(gatewayId, requestId) {
     var _a;
@@ -1534,6 +1540,7 @@ var Runner = class {
   runnerId;
   #started = false;
   #shutdown = false;
+  #draining = false;
   #reconnectAttempt = 0;
   #reconnectTimeout;
   // Protocol metadata
@@ -1593,6 +1600,22 @@ var Runner = class {
     if (!actor) return;
     this.#sendActorIntent(actorId, actor.generation, "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, generation) {
+    const actor = this.getActor(actorId, generation);
+    if (!actor) return;
+    actor.stopIntentSent = true;
+    this.#sendActorIntent(actorId, actor.generation, "stop");
+  }
   async forceStopActor(actorId, generation) {
     var _a, _b;
     (_a = this.log) == null ? void 0 : _a.debug({
@@ -1745,6 +1768,7 @@ var Runner = class {
       return;
     }
     this.#shutdown = true;
+    this.#draining = !immediate;
     (_b = this.log) == null ? void 0 : _b.info({
       msg: "starting shutdown",
       immediate,
@@ -2319,7 +2343,7 @@ var Runner = class {
       actorState = {
         tag: "ActorStateStopped",
         val: {
-          code: protocol.StopCode.Ok,
+          code: actor.stopIntentSent || this.#draining ? protocol.StopCode.Ok : protocol.StopCode.Error,
           message: null
         }
       };