feat(container-runner): keep instance warm instead of self-exiting

Author: abcxff

container-runner/README.md

@@ -8,7 +8,8 @@ This README covers development, the example projects, and the local test harness
 spawning a child game-server process per actor and proxying Rivet's tunneled
 HTTP/WebSocket traffic to it. Each child gets its own port; the pool's request
 concurrency decides how many actors share a container (one, in the recommended
-game-server setup), and the process exits when the last actor stops. Wrap any dedicated server (Unity, Godot, a plain Node process) in a
+game-server setup). The instance stays warm after its last actor stops; the engine
+reaps it by draining the `/start` connection after the request lifespan. Wrap any dedicated server (Unity, Godot, a plain Node process) in a
 container with this binary as the entrypoint and Rivet Compute can cold-start and route
 to it.
 

container-runner/src/actor.rs

@@ -4,7 +4,8 @@
 //! readiness (so the actor is never reported ready before the child listens),
 //! `run` is a watchdog that reports unexpected child exits,
 //! `on_fetch`/`on_websocket` proxy tunneled traffic to the child's port, and
-//! `on_destroy` stops the child, exiting the process once no actors remain.
+//! `on_destroy` stops the child while the instance stays warm for the next
+//! placement.
 
 use std::sync::Arc;
 
@@ -16,7 +17,7 @@ use tokio::sync::Mutex as TokioMutex;
 use crate::child::{ChildProcess, SpawnSpec, log_prefix};
 use crate::input::ActorInput;
 use crate::{
-	children, effective_stop_grace, release_child_port, request_exit, reserve_child_port,
+	children, effective_stop_grace, release_child_port, reserve_child_port,
 	runner_config,
 };
 
@@ -40,11 +41,12 @@ impl GameServer {
 			release_child_port(child.child_port).await;
 		}
 
-		// Once the last actor is gone the instance drains rather than
-		// lingering for the next placement.
-		if children().is_empty() {
-			request_exit(actor_id, reason);
-		}
+		// The instance stays alive and warm after its last actor stops, ready to
+		// host the next placement. It is reaped by the platform's own shutdown
+		// signal, not by self-exit. This keeps the serverless container long
+		// lived enough for the log agent to drain its stderr, which a fast
+		// self-exit could otherwise lose.
+		tracing::info!(actor_id = %actor_id, reason, "actor stopped, keeping instance warm");
 	}
 }
 
@@ -129,12 +131,10 @@ impl Actor for GameServer {
 			Ok(child) => Arc::new(child),
 			Err(err) => {
 				release_child_port(child_port).await;
-				// A failed start on an otherwise idle instance poisons it;
-				// don't let it serve the next placement. With other actors
-				// running, the failure is this actor's alone.
-				if children().is_empty() {
-					request_exit(&actor_id, "child failed to start");
-				}
+				// A failed start is this actor's alone and does not take the
+				// instance down. The container stays warm and ready for the next
+				// placement, and stays alive long enough for the log agent to
+				// drain the failure logs before the platform reaps it.
 				return Err(err);
 			}
 		};

container-runner/src/main.rs

@@ -12,8 +12,9 @@
 //! The runner hosts as many concurrent actors as the engine places on it,
 //! each with its own child process on its own port; the pool's request
 //! concurrency decides how many that is (1 in the recommended game-server
-//! setup). When the last actor stops the process exits so the platform reaps
-//! the instance.
+//! setup). The instance stays warm after its last actor stops and never
+//! self-exits; the engine reaps it by draining the `/start` connection once
+//! the request lifespan elapses, or the platform sends a SIGTERM.
 
 mod actor;
 mod child;
@@ -167,12 +168,12 @@ pub fn effective_stop_grace() -> Duration {
 	}
 }
 
-/// End the process. Called when the LAST actor on this instance is gone (or a
-/// failed start poisoned an otherwise idle instance): the instance drains
-/// instead of lingering for the next placement. The runner is PID 1 in the
+/// End the process. Only the platform shutdown signal drives this now: actors
+/// stopping or failing to start no longer exit the instance, so it stays warm
+/// and reusable and its logs have time to drain. The runner is PID 1 in the
 /// image, so exiting stops the container and the platform reaps the instance.
 pub fn request_exit(actor_id: &str, reason: &str) {
-	tracing::info!(actor_id = %actor_id, reason, "actor finished, exiting container");
+	tracing::info!(actor_id = %actor_id, reason, "shutting down container");
 	EXIT.cancel();
 }
 
@@ -346,18 +347,21 @@ async fn async_main() -> Result<()> {
 	));
 	tracing::info!(port, "container-runner serverless front door listening");
 
-	// Wait for an exit request, then tear down. Two orders depending on why:
+	// Wait for an exit request, then tear down. Only the signal path is live
+	// today: nothing calls `request_exit` except `spawn_signal_handler`, which
+	// sets `SIGNAL_SHUTDOWN` before cancelling `EXIT`, so the `else` branch is
+	// currently unreachable and kept only as a fallback for a future
+	// actor-driven exit.
 	//
 	// Signal (platform is reclaiming the instance): tell the engine FIRST so
 	// it can start re-placing actors immediately. Its per-actor stops run our
 	// on_destroy hooks, which SIGTERM children with the capped signal grace.
 	// The drain is bounded so an unreachable engine cannot eat the whole
 	// platform budget; the sweep then catches any child whose hooks never ran.
 	//
-	// Actor-driven exit (last actor stopped or a failed start poisoned an
-	// idle instance): no platform deadline. Children are already reaped by
-	// the hooks (the sweep is a no-op backstop), and the runtime drains
-	// unbounded so the /start SSE flushes its stopping frame cleanly.
+	// Fallback actor-driven exit (unreachable today): no platform deadline.
+	// Children are already reaped by the hooks (the sweep is a no-op backstop),
+	// and the runtime drains unbounded so the /start SSE flushes cleanly.
 	EXIT.cancelled().await;
 	if SIGNAL_SHUTDOWN.load(Ordering::Acquire) {
 		if tokio::time::timeout(signal_drain_timeout(), runtime.shutdown())

website/src/content/docs/deploy/container-runner.mdx

@@ -65,7 +65,7 @@ Create actors against the pool's runner (`default`) and connect clients through
 2. The runner spawns your server as a child process with `PORT` set to the child port, waits for the port to open, and reports the actor as running.
 3. Gateway traffic for the actor arrives over Rivet's tunnel and is proxied to `127.0.0.1:<child port>`. WebSocket clients connect at the bare gateway URL with the `rivet` WebSocket subprotocol. Raw HTTP reaches the child under the `/request/*` prefix on the actor surface (the prefix is stripped before proxying); other paths are reserved for the runtime's own endpoints.
 4. Child stdout and stderr are re-emitted with an `[actorId=... key=...]` prefix so actor logs are attributed in the dashboard.
-5. When an actor stops, the runner sends its child `SIGTERM`, escalates to `SIGKILL` after a grace period, and exits the process once no actors remain.
+5. When an actor stops, the runner sends its child `SIGTERM` and escalates to `SIGKILL` after a grace period. The instance stays warm for the next placement rather than exiting; the engine reaps it by draining the `/start` connection after the request lifespan.
 
 ## Configuration