[AZ-651] [AZ-668] lost-link failsafe ladder + mapobjects persistence (batch 7)

AZ-651 (mission_executor lost-link ladder): - LostLinkLadder pure-logic state machine (LinkOk -> Degraded -> Lost -> LinkLostInFollow + MavlinkLost branch). Configurable thresholds via LostLinkConfig. - LostLinkCommandIssuer trait + MavlinkCommandIssuer production impl emitting MAV_CMD_NAV_RETURN_TO_LAUNCH via MavlinkHandle::send_command. - LostLinkDriver task wires the ladder to operator-link watch, MAVLink LinkEvent broadcast, and optional target-follow signal. On RTL, driver calls the issuer THEN MissionExecutorHandle::failsafe_trigger. - failsafe_trigger(LinkLost | LinkLostInFollow) short-circuits FlyMission -> Land via direct FSM state mutation + TransitionEvent emission; Paused state is intentionally NOT overridden. - Tests: 4/4 ACs locally green (degraded-no-rtl; lost-fires-once; follow-grace; mavlink-loss-no-rtl) plus driver + FSM integration. AZ-668 (mapobjects_store persistence): - Snapshot serializable shape + Store::{to_snapshot,from_snapshot} round trip. - MapObjectsPersistence async trait + JsonSnapshotEngine default impl (write to .tmp, sync_all, atomic rename, best-effort parent fsync). - PersistenceError::{Corrupt, SchemaMismatch} surfaces explicit errors on bad blob; PersistenceMetrics tracks last_snapshot_ts, snapshot_size_bytes, snapshot_errors_total. - MapObjectsStore::from_snapshot factory for crash recovery from the composition root. - Tests: 4/4 ACs locally green (round-trip; atomic rename ignores partial .tmp; crash recovery preserves pending; corruption returns explicit error) plus schema-mismatch + metrics smoke checks. Quality gates: - cargo fmt: clean. - cargo clippy -p mission_executor -p mapobjects_store --tests: 0 warns. - cargo test --workspace: all green. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-21 23:51:09 +00:00 · 2026-05-19 18:59:28 +03:00
parent 23366a5c6d
commit 2bcd4a8059
16 changed files with 1940 additions and 8 deletions
@@ -0,0 +1,221 @@
+//! AZ-668 — persistence trait + default JSON snapshot engine.
+//!
+//! Default engine per Q3: in-memory + atomic JSON snapshot. The trait
+//! is kept narrow on purpose so a future SQLite+H3 / RocksDB engine
+//! can swap in without touching call sites.
+//!
+//! Crash-safety: writes go to `${state_dir}/mapobjects/<mission_id>.json.tmp`,
+//! are fsync'd, then atomically renamed onto the final path. The parent
+//! directory is fsync'd after the rename so the rename itself survives
+//! a power loss. Interrupted writes leave the `.tmp` file behind; the
+//! next `load_snapshot` ignores it.
+//!
+//! Corruption surfaces as [`PersistenceError::Corrupt`]: the caller MUST
+//! refuse to start with stale state and propagate the error to the
+//! operator (AZ-668 AC-4). The engine does NOT silently fall back to
+//! an empty store.
+
+use std::path::{Path, PathBuf};
+
+use async_trait::async_trait;
+use thiserror::Error;
+use tokio::sync::Mutex as AsyncMutex;
+use tokio::{fs, io::AsyncWriteExt};
+
+use super::snapshot::Snapshot;
+
+/// Errors surfaced by [`MapObjectsPersistence`].
+#[derive(Debug, Error)]
+pub enum PersistenceError {
+    #[error("persistence I/O error: {0}")]
+    Io(#[from] std::io::Error),
+    /// The snapshot file was present but unreadable. The caller MUST
+    /// refuse to start with stale state and surface the error to the
+    /// operator — never silently start empty (AZ-668 AC-4).
+    #[error("snapshot corrupt at {path}: {reason}")]
+    Corrupt { path: PathBuf, reason: String },
+    /// Schema version mismatch — the on-disk blob predates the running
+    /// binary. Treated as corruption (operator must reconcile).
+    #[error("snapshot schema mismatch at {path}: expected {expected}, found {found}")]
+    SchemaMismatch {
+        path: PathBuf,
+        expected: u32,
+        found: u32,
+    },
+}
+
+/// Engine-level metrics surfaced to the health aggregator.
+/// Per AZ-668 §Outcome: `last_snapshot_ts`, `snapshot_size_bytes`,
+/// `snapshot_errors_total`.
+#[derive(Debug, Clone, Default)]
+pub struct PersistenceMetrics {
+    pub last_snapshot_ts: Option<chrono::DateTime<chrono::Utc>>,
+    pub snapshot_size_bytes: Option<u64>,
+    pub snapshot_errors_total: u64,
+}
+
+/// Pluggable persistence backend. The default impl is the JSON
+/// snapshot engine (below); future Q3 engines (SQLite+H3, RocksDB, …)
+/// implement this trait without breaking call sites.
+///
+/// Methods are `async` because file I/O on the Jetson can stall while
+/// the SD card is busy with detection-evidence writes; blocking the
+/// runtime worker thread would starve `mavlink_layer`'s heartbeat
+/// task. Implementations that do nothing async can delegate to
+/// `tokio::task::spawn_blocking`.
+#[async_trait]
+pub trait MapObjectsPersistence: Send + Sync {
+    /// Atomically persist `snapshot` keyed by its `mission_id`.
+    /// Implementations MUST guarantee no partial writes are visible to
+    /// `load_snapshot` — typically by writing to a `.tmp` sibling then
+    /// renaming.
+    async fn save_snapshot(&self, snapshot: &Snapshot) -> Result<(), PersistenceError>;
+
+    /// Load the most recent snapshot for `mission_id`. Returns
+    /// `Ok(None)` if no snapshot exists; `Err(Corrupt)` on a present
+    /// but unreadable blob (the caller MUST refuse to start).
+    async fn load_snapshot(&self, mission_id: &str) -> Result<Option<Snapshot>, PersistenceError>;
+
+    /// Engine metrics for the health surface.
+    fn metrics(&self) -> PersistenceMetrics;
+}
+
+/// Default Q3 engine: one JSON file per mission, atomic-renamed on
+/// each write.
+///
+/// Path layout: `${state_dir}/mapobjects/<mission_id>.json`. The
+/// `mapobjects` subdirectory is created on first write.
+pub struct JsonSnapshotEngine {
+    state_dir: PathBuf,
+    metrics: AsyncMutex<PersistenceMetrics>,
+}
+
+impl std::fmt::Debug for JsonSnapshotEngine {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("JsonSnapshotEngine")
+            .field("state_dir", &self.state_dir)
+            .finish_non_exhaustive()
+    }
+}
+
+impl JsonSnapshotEngine {
+    /// Construct an engine rooted at `state_dir`. The directory does
+    /// not have to exist yet — it is created lazily on the first
+    /// successful `save_snapshot`.
+    pub fn new(state_dir: impl Into<PathBuf>) -> Self {
+        Self {
+            state_dir: state_dir.into(),
+            metrics: AsyncMutex::new(PersistenceMetrics::default()),
+        }
+    }
+
+    /// Resolve the canonical snapshot path for `mission_id`.
+    ///
+    /// `mission_id` is treated as an opaque filename component. Callers
+    /// supply trusted ids from the central API; no path traversal
+    /// sanitisation is performed (the AZ-668 spec does not require it).
+    /// If untrusted ids ever flow in, add validation here.
+    pub fn snapshot_path(&self, mission_id: &str) -> PathBuf {
+        self.state_dir
+            .join("mapobjects")
+            .join(format!("{mission_id}.json"))
+    }
+
+    fn tmp_path(&self, mission_id: &str) -> PathBuf {
+        self.state_dir
+            .join("mapobjects")
+            .join(format!("{mission_id}.json.tmp"))
+    }
+}
+
+#[async_trait]
+impl MapObjectsPersistence for JsonSnapshotEngine {
+    async fn save_snapshot(&self, snapshot: &Snapshot) -> Result<(), PersistenceError> {
+        let outcome = self.save_snapshot_inner(snapshot).await;
+        if outcome.is_err() {
+            let mut m = self.metrics.lock().await;
+            m.snapshot_errors_total = m.snapshot_errors_total.saturating_add(1);
+        }
+        outcome
+    }
+
+    async fn load_snapshot(&self, mission_id: &str) -> Result<Option<Snapshot>, PersistenceError> {
+        let path = self.snapshot_path(mission_id);
+        let outcome = self.load_snapshot_inner(&path).await;
+        if matches!(
+            outcome,
+            Err(PersistenceError::Corrupt { .. } | PersistenceError::SchemaMismatch { .. })
+        ) {
+            let mut m = self.metrics.lock().await;
+            m.snapshot_errors_total = m.snapshot_errors_total.saturating_add(1);
+        }
+        outcome
+    }
+
+    fn metrics(&self) -> PersistenceMetrics {
+        // Cheap snapshot under a non-async borrow — `try_lock` keeps the
+        // health surface non-blocking; if the lock is contended we
+        // return zeros rather than parking the health caller.
+        self.metrics
+            .try_lock()
+            .map(|m| m.clone())
+            .unwrap_or_default()
+    }
+}
+
+impl JsonSnapshotEngine {
+    async fn save_snapshot_inner(&self, snapshot: &Snapshot) -> Result<(), PersistenceError> {
+        let path = self.snapshot_path(&snapshot.mission_id);
+        let tmp = self.tmp_path(&snapshot.mission_id);
+        let dir = path.parent().expect("snapshot path always has parent");
+
+        fs::create_dir_all(dir).await?;
+        let bytes = serde_json::to_vec(snapshot).map_err(|e| PersistenceError::Corrupt {
+            path: path.clone(),
+            reason: format!("serialize: {e}"),
+        })?;
+        let size = bytes.len() as u64;
+
+        {
+            let mut f = fs::File::create(&tmp).await?;
+            f.write_all(&bytes).await?;
+            f.sync_all().await?;
+        }
+        fs::rename(&tmp, &path).await?;
+        // Best-effort parent fsync so the rename survives a power
+        // loss. POSIX guarantees this is the durability anchor for
+        // directory operations; non-POSIX platforms ignore.
+        if let Ok(dir_handle) = std::fs::File::open(dir) {
+            let _ = dir_handle.sync_all();
+        }
+
+        let mut m = self.metrics.lock().await;
+        m.last_snapshot_ts = Some(chrono::Utc::now());
+        m.snapshot_size_bytes = Some(size);
+        Ok(())
+    }
+
+    async fn load_snapshot_inner(
+        &self,
+        path: &Path,
+    ) -> Result<Option<Snapshot>, PersistenceError> {
+        let bytes = match fs::read(path).await {
+            Ok(b) => b,
+            Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
+            Err(e) => return Err(e.into()),
+        };
+        let snapshot: Snapshot =
+            serde_json::from_slice(&bytes).map_err(|e| PersistenceError::Corrupt {
+                path: path.to_path_buf(),
+                reason: format!("deserialize: {e}"),
+            })?;
+        if snapshot.schema_version != Snapshot::CURRENT_SCHEMA_VERSION {
+            return Err(PersistenceError::SchemaMismatch {
+                path: path.to_path_buf(),
+                expected: Snapshot::CURRENT_SCHEMA_VERSION,
+                found: snapshot.schema_version,
+            });
+        }
+        Ok(Some(snapshot))
+    }
+}