feat(litebox): add pause/resume API for zero-CPU VM freezing

boxlite-cli/src/commands/serve/handlers/boxes.rs

@@ -118,6 +118,42 @@ pub(in crate::commands::serve) async fn stop_box(
     Json(box_info_to_response(&info)).into_response()
 }
 
+pub(in crate::commands::serve) async fn pause_box(
+    State(state): State<Arc<AppState>>,
+    Path(box_id): Path<String>,
+) -> Response {
+    let litebox = match get_or_fetch_box(&state, &box_id).await {
+        Ok(b) => b,
+        Err(resp) => return resp,
+    };
+
+    if let Err(e) = litebox.pause().await {
+        let (status, etype) = classify_boxlite_error(&e);
+        return error_response(status, e.to_string(), etype);
+    }
+
+    let info = litebox.info();
+    Json(box_info_to_response(&info)).into_response()
+}
+
+pub(in crate::commands::serve) async fn resume_box(
+    State(state): State<Arc<AppState>>,
+    Path(box_id): Path<String>,
+) -> Response {
+    let litebox = match get_or_fetch_box(&state, &box_id).await {
+        Ok(b) => b,
+        Err(resp) => return resp,
+    };
+
+    if let Err(e) = litebox.resume().await {
+        let (status, etype) = classify_boxlite_error(&e);
+        return error_response(status, e.to_string(), etype);
+    }
+
+    let info = litebox.info();
+    Json(box_info_to_response(&info)).into_response()
+}
+
 pub(in crate::commands::serve) async fn remove_box(
     State(state): State<Arc<AppState>>,
     Path(box_id): Path<String>,

boxlite-cli/src/commands/serve/mod.rs

@@ -165,15 +165,17 @@ fn error_response(status: StatusCode, message: impl Into<String>, error_type: &s
 }
 
 fn classify_boxlite_error(err: &boxlite::BoxliteError) -> (StatusCode, &'static str) {
-    let msg = err.to_string().to_lowercase();
-    if msg.contains("not found") {
-        (StatusCode::NOT_FOUND, "NotFoundError")
-    } else if msg.contains("already") || msg.contains("conflict") {
-        (StatusCode::CONFLICT, "ConflictError")
-    } else if msg.contains("unsupported") {
-        (StatusCode::BAD_REQUEST, "UnsupportedError")
-    } else {
-        (StatusCode::INTERNAL_SERVER_ERROR, "InternalError")
+    use boxlite::BoxliteError;
+    match err {
+        BoxliteError::NotFound(_) => (StatusCode::NOT_FOUND, "NotFoundError"),
+        BoxliteError::AlreadyExists(_) => (StatusCode::CONFLICT, "ConflictError"),
+        BoxliteError::InvalidState(_) => (StatusCode::CONFLICT, "InvalidStateError"),
+        BoxliteError::InvalidArgument(_) => (StatusCode::BAD_REQUEST, "InvalidArgumentError"),
+        BoxliteError::Unsupported(_) | BoxliteError::UnsupportedEngine => {
+            (StatusCode::BAD_REQUEST, "UnsupportedError")
+        }
+        BoxliteError::Stopped(_) => (StatusCode::CONFLICT, "StoppedError"),
+        _ => (StatusCode::INTERNAL_SERVER_ERROR, "InternalError"),
     }
 }
 
@@ -241,6 +243,14 @@ fn build_router(state: Arc<AppState>) -> Router {
             "/v1/default/boxes/{box_id}/stop",
             post(boxes::stop_box),
         )
+        .route(
+            "/v1/default/boxes/{box_id}/pause",
+            post(boxes::pause_box),
+        )
+        .route(
+            "/v1/default/boxes/{box_id}/resume",
+            post(boxes::resume_box),
+        )
         // Box metrics
         .route(
             "/v1/default/boxes/{box_id}/metrics",

boxlite/src/event_listener/audit_event_listener.rs

@@ -116,6 +116,14 @@ impl EventListener for AuditEventListener {
         ));
     }
 
+    fn on_box_paused(&self, box_id: &BoxID) {
+        self.record(AuditEvent::now(box_id.clone(), AuditEventKind::BoxPaused));
+    }
+
+    fn on_box_resumed(&self, box_id: &BoxID) {
+        self.record(AuditEvent::now(box_id.clone(), AuditEventKind::BoxResumed));
+    }
+
     fn on_box_removed(&self, box_id: &BoxID) {
         self.record(AuditEvent::now(box_id.clone(), AuditEventKind::BoxRemoved));
     }
@@ -229,6 +237,46 @@ mod tests {
         assert_eq!(listener.len(), 1000);
     }
 
+    #[test]
+    fn records_pause_resume_events() {
+        let listener = AuditEventListener::new();
+        let id = test_box_id();
+
+        listener.on_box_started(&id);
+        listener.on_box_paused(&id);
+        listener.on_box_resumed(&id);
+        listener.on_box_stopped(&id, None);
+
+        let events = listener.events();
+        assert_eq!(events.len(), 4);
+        assert!(matches!(events[0].kind, AuditEventKind::BoxStarted));
+        assert!(matches!(events[1].kind, AuditEventKind::BoxPaused));
+        assert!(matches!(events[2].kind, AuditEventKind::BoxResumed));
+        assert!(matches!(events[3].kind, AuditEventKind::BoxStopped { .. }));
+    }
+
+    #[test]
+    fn records_multiple_pause_resume_cycles() {
+        let listener = AuditEventListener::new();
+        let id = test_box_id();
+
+        listener.on_box_started(&id);
+        // Cycle 1
+        listener.on_box_paused(&id);
+        listener.on_box_resumed(&id);
+        // Cycle 2
+        listener.on_box_paused(&id);
+        listener.on_box_resumed(&id);
+        listener.on_box_stopped(&id, Some(0));
+
+        let events = listener.events();
+        assert_eq!(events.len(), 6);
+        // Verify all events have the same box_id
+        for event in &events {
+            assert_eq!(event.box_id, id);
+        }
+    }
+
     #[test]
     fn events_since_filters() {
         let listener = AuditEventListener::new();

boxlite/src/event_listener/event.rs

@@ -42,6 +42,12 @@ pub enum AuditEventKind {
     /// Box VM stopped.
     BoxStopped { exit_code: Option<i32> },
 
+    /// Box VM paused (SIGSTOP).
+    BoxPaused,
+
+    /// Box VM resumed from pause (SIGCONT).
+    BoxResumed,
+
     /// Box removed.
     BoxRemoved,
 

boxlite/src/event_listener/listener.rs

@@ -44,6 +44,12 @@ pub trait EventListener: Send + Sync {
     /// Called after a box VM stops.
     fn on_box_stopped(&self, _box_id: &BoxID, _exit_code: Option<i32>) {}
 
+    /// Called after a box VM is paused (SIGSTOP).
+    fn on_box_paused(&self, _box_id: &BoxID) {}
+
+    /// Called after a box VM is resumed from pause (SIGCONT).
+    fn on_box_resumed(&self, _box_id: &BoxID) {}
+
     /// Called after a box is removed.
     fn on_box_removed(&self, _box_id: &BoxID) {}