fix(rivetkit-core): return stopping not starting when sleep/destroy called mid-shutdown

Author: NathanFlurry

rivetkit-rust/packages/rivetkit-core/src/actor/context.rs

@@ -388,9 +388,19 @@ impl ActorContext {
 	}
 
 	pub fn sleep(&self) -> Result<()> {
+		// `started` is cleared when the lifecycle state machine transitions
+		// into SleepGrace / DestroyGrace, so `started=false` covers both
+		// "never started" and "already shutting down". Distinguish with the
+		// request flags for an accurate diagnostic.
 		if !self.0.sleep.started.load(Ordering::SeqCst) {
-			return Err(ActorLifecycleError::Starting.build())
-				.context("cannot request sleep before actor startup completes");
+			let already_stopping = self.0.sleep_requested.load(Ordering::SeqCst)
+				|| self.0.destroy_requested.load(Ordering::SeqCst);
+			return if already_stopping {
+				Err(ActorLifecycleError::Stopping.build()).context("actor is already shutting down")
+			} else {
+				Err(ActorLifecycleError::Starting.build())
+					.context("cannot request sleep before actor startup completes")
+			};
 		}
 		if self.0.sleep_requested.swap(true, Ordering::SeqCst) {
 			return Err(ActorLifecycleError::Stopping.build())
@@ -415,7 +425,13 @@ impl ActorContext {
 	}
 
 	pub fn destroy(&self) -> Result<()> {
-		if !self.0.sleep.started.load(Ordering::SeqCst) {
+		// See `sleep` for why the request flags disambiguate `started=false`.
+		// destroy() is allowed after sleep() has been requested because
+		// destroy is a stronger signal that escalates an in-flight sleep.
+		if !self.0.sleep.started.load(Ordering::SeqCst)
+			&& !self.0.sleep_requested.load(Ordering::SeqCst)
+			&& !self.0.destroy_requested.load(Ordering::SeqCst)
+		{
 			return Err(ActorLifecycleError::Starting.build())
 				.context("cannot request destroy before actor startup completes");
 		}

rivetkit-rust/packages/rivetkit-core/src/actor/sleep.rs

@@ -927,4 +927,27 @@ mod tests {
 		ctx.cancel_shutdown_deadline();
 		assert!(token.is_cancelled());
 	}
+
+	#[tokio::test(start_paused = true)]
+	async fn sleep_after_grace_clears_started_returns_stopping_not_starting() {
+		// Simulate the lifecycle state machine clearing `started` when it
+		// transitions into SleepGrace. Calls into `sleep()` after that point
+		// must surface `Stopping`, not `Starting`.
+		let ctx = ActorContext::new_for_sleep_tests("actor-sleep-after-grace");
+		ctx.set_sleep_started(true);
+
+		ctx.sleep().expect("first sleep call should be accepted");
+
+		// Lifecycle machine clears `started` on transition into SleepGrace.
+		ctx.set_sleep_started(false);
+
+		let err = ctx.sleep().expect_err("second sleep should fail");
+		let rivet_err = rivet_error::RivetError::extract(&err);
+		assert_eq!(rivet_err.group(), "actor");
+		assert_eq!(
+			rivet_err.code(),
+			"stopping",
+			"started=false during shutdown must surface stopping, not starting"
+		);
+	}
 }