feat(daemon): add protocol version compatibility checks (#141)

jordond · web-flow · commit b076b91d49ff · 2026-01-30T19:36:29.000-05:00
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -89,6 +89,22 @@ jobs:
           workspaces: cli
       - run: cargo check --all-targets --all-features
 
+  rust-test:
+    name: Rust Test
+    needs: changes
+    if: needs.changes.outputs.rust == 'true'
+    runs-on: macos-latest
+    defaults:
+      run:
+        working-directory: ./cli
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: cli
+      - run: cargo test --workspace
+
   rust-build:
     name: Build ${{ matrix.target }}
     needs: changes
diff --git a/cli/src/app/daemon.rs b/cli/src/app/daemon.rs
@@ -9,7 +9,7 @@ use color_eyre::eyre::Result;
 use tracing::{debug, info};
 
 use super::App;
-use crate::daemon::{DaemonClient, DataSnapshot};
+use crate::daemon::{ClientError, DaemonClient, DataSnapshot};
 
 impl App {
     /// Attempts to connect to the daemon and subscribe for real-time updates.
@@ -37,43 +37,48 @@ impl App {
     /// Attempts to subscribe to the daemon for real-time updates.
     /// Returns true if subscription was successful.
     fn try_subscribe_to_daemon(&mut self) -> bool {
-        if let Ok(mut client) = DaemonClient::connect() {
-            if client.subscribe().is_ok() && client.set_nonblocking(true).is_ok() {
-                info!("Subscribed to daemon for real-time data");
-
-                // Create channel for background thread to send snapshots
-                let (tx, rx) = std::sync::mpsc::channel();
-                self.snapshot_rx = Some(rx);
-
-                // Spawn background thread to continuously read from socket
-                std::thread::spawn(move || {
-                    debug!("Background daemon reader thread started");
-                    let mut client = client;
-                    loop {
-                        match client.read_update() {
-                            Ok(Some(snapshot)) => {
-                                if tx.send(snapshot).is_err() {
-                                    debug!("Channel closed, reader thread exiting");
-                                    break;
-                                }
-                            }
-                            Ok(None) => {
-                                // No data available, sleep briefly to avoid busy loop
-                                std::thread::sleep(std::time::Duration::from_millis(10));
-                            }
-                            Err(e) => {
-                                debug!(error = %e, "Background reader connection lost");
+        let client = match DaemonClient::connect_with_version_check() {
+            Ok(c) => c,
+            Err(ClientError::VersionMismatch(e)) => {
+                tracing::warn!("{}", e);
+                return false;
+            }
+            Err(_) => return false,
+        };
+
+        let mut client = client;
+        if client.subscribe().is_ok() && client.set_nonblocking(true).is_ok() {
+            info!("Subscribed to daemon for real-time data");
+
+            let (tx, rx) = std::sync::mpsc::channel();
+            self.snapshot_rx = Some(rx);
+
+            std::thread::spawn(move || {
+                debug!("Background daemon reader thread started");
+                let mut client = client;
+                loop {
+                    match client.read_update() {
+                        Ok(Some(snapshot)) => {
+                            if tx.send(snapshot).is_err() {
+                                debug!("Channel closed, reader thread exiting");
                                 break;
                             }
                         }
+                        Ok(None) => {
+                            std::thread::sleep(std::time::Duration::from_millis(10));
+                        }
+                        Err(e) => {
+                            debug!(error = %e, "Background reader connection lost");
+                            break;
+                        }
                     }
-                });
+                }
+            });
 
-                self.using_daemon_data = true;
-                self.daemon_connected = true;
-                self.sync_daemon_broadcast_interval();
-                return true;
-            }
+            self.using_daemon_data = true;
+            self.daemon_connected = true;
+            self.sync_daemon_broadcast_interval();
+            return true;
         }
         false
     }
diff --git a/cli/src/daemon/client.rs b/cli/src/daemon/client.rs
@@ -5,9 +5,56 @@ use std::time::Duration;
 use crate::daemon::protocol::{
     ChargeSession, CycleSummary, DaemonRequest, DaemonResponse, DaemonStatus, DailyCycle,
     DailyStat, DailyTopProcess, DataSnapshot, HourlyStat, KillProcessResult, KillSignal, Sample,
+    MIN_SUPPORTED_VERSION, PROTOCOL_VERSION,
 };
 use crate::daemon::socket_path;
 
+#[derive(Debug, Clone)]
+pub struct VersionMismatchError {
+    pub tui_protocol_version: u32,
+    pub tui_min_supported: u32,
+    pub daemon_protocol_version: u32,
+    pub daemon_min_supported: u32,
+    pub daemon_binary_version: String,
+    pub kind: VersionMismatchKind,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum VersionMismatchKind {
+    TuiTooOld,
+    DaemonTooOld,
+}
+
+impl std::fmt::Display for VersionMismatchError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self.kind {
+            VersionMismatchKind::TuiTooOld => {
+                write!(
+                    f,
+                    "Protocol version mismatch: TUI uses protocol v{}, but daemon (v{}) requires v{}+.\n\n\
+                    Please update jolt:\n  \
+                    brew upgrade jolt\n  \
+                    # or: cargo install jolt-tui",
+                    self.tui_protocol_version,
+                    self.daemon_binary_version,
+                    self.daemon_min_supported
+                )
+            }
+            VersionMismatchKind::DaemonTooOld => {
+                write!(
+                    f,
+                    "Protocol version mismatch: daemon (v{}) uses protocol v{}, but this TUI requires v{}+.\n\n\
+                    Please restart the daemon:\n  \
+                    jolt daemon restart",
+                    self.daemon_binary_version,
+                    self.daemon_protocol_version,
+                    self.tui_min_supported
+                )
+            }
+        }
+    }
+}
+
 #[derive(Debug, thiserror::Error)]
 pub enum ClientError {
     #[error("Connection failed: {0}")]
@@ -21,10 +68,43 @@ pub enum ClientError {
 
     #[error("Subscription rejected: {0}")]
     SubscriptionRejected(String),
+
+    #[error("{0}")]
+    VersionMismatch(VersionMismatchError),
 }
 
 pub type Result<T> = std::result::Result<T, ClientError>;
 
+/// Checks if the TUI and daemon protocol versions are compatible.
+/// Returns Ok(()) if compatible, or Err with detailed mismatch info.
+pub fn check_version_compatibility(status: &DaemonStatus) -> Result<()> {
+    // Check 1: Can daemon understand TUI's messages?
+    if PROTOCOL_VERSION < status.min_supported_version {
+        return Err(ClientError::VersionMismatch(VersionMismatchError {
+            tui_protocol_version: PROTOCOL_VERSION,
+            tui_min_supported: MIN_SUPPORTED_VERSION,
+            daemon_protocol_version: status.protocol_version,
+            daemon_min_supported: status.min_supported_version,
+            daemon_binary_version: status.version.clone(),
+            kind: VersionMismatchKind::TuiTooOld,
+        }));
+    }
+
+    // Check 2: Can TUI understand daemon's messages?
+    if status.protocol_version < MIN_SUPPORTED_VERSION {
+        return Err(ClientError::VersionMismatch(VersionMismatchError {
+            tui_protocol_version: PROTOCOL_VERSION,
+            tui_min_supported: MIN_SUPPORTED_VERSION,
+            daemon_protocol_version: status.protocol_version,
+            daemon_min_supported: status.min_supported_version,
+            daemon_binary_version: status.version.clone(),
+            kind: VersionMismatchKind::DaemonTooOld,
+        }));
+    }
+
+    Ok(())
+}
+
 pub struct DaemonClient {
     stream: UnixStream,
     read_buffer: Vec<u8>,
@@ -42,6 +122,15 @@ impl DaemonClient {
         })
     }
 
+    /// Connects to the daemon and validates protocol version compatibility.
+    /// This is the preferred connection method for the TUI.
+    pub fn connect_with_version_check() -> Result<Self> {
+        let mut client = Self::connect()?;
+        let status = client.get_status()?;
+        check_version_compatibility(&status)?;
+        Ok(client)
+    }
+
     fn read_line_blocking(&mut self) -> Result<String> {
         let mut temp_buf = [0u8; 8192];
         loop {
@@ -293,3 +382,107 @@ impl DaemonClient {
         Ok(())
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn make_status(
+        protocol_version: u32,
+        min_supported_version: u32,
+        version: &str,
+    ) -> DaemonStatus {
+        DaemonStatus {
+            running: true,
+            uptime_secs: 0,
+            sample_count: 0,
+            last_sample_time: None,
+            database_size_bytes: 0,
+            version: version.to_string(),
+            subscriber_count: 0,
+            history_enabled: false,
+            protocol_version,
+            min_supported_version,
+        }
+    }
+
+    #[test]
+    fn test_version_compatible_same_version() {
+        let status = make_status(PROTOCOL_VERSION, MIN_SUPPORTED_VERSION, "1.0.0");
+        assert!(check_version_compatibility(&status).is_ok());
+    }
+
+    #[test]
+    fn test_version_compatible_daemon_newer() {
+        let status = make_status(PROTOCOL_VERSION + 1, MIN_SUPPORTED_VERSION, "2.0.0");
+        assert!(check_version_compatibility(&status).is_ok());
+    }
+
+    #[test]
+    fn test_version_compatible_at_min_boundary() {
+        let status = make_status(MIN_SUPPORTED_VERSION, MIN_SUPPORTED_VERSION, "0.5.0");
+        assert!(check_version_compatibility(&status).is_ok());
+    }
+
+    #[test]
+    fn test_version_tui_too_old() {
+        let status = make_status(10, PROTOCOL_VERSION + 1, "3.0.0");
+        let result = check_version_compatibility(&status);
+        assert!(result.is_err());
+        if let Err(ClientError::VersionMismatch(e)) = result {
+            assert_eq!(e.kind, VersionMismatchKind::TuiTooOld);
+            assert_eq!(e.tui_protocol_version, PROTOCOL_VERSION);
+            assert_eq!(e.daemon_min_supported, PROTOCOL_VERSION + 1);
+            assert!(e.to_string().contains("update jolt"));
+        } else {
+            panic!("Expected VersionMismatch error");
+        }
+    }
+
+    #[test]
+    fn test_version_daemon_too_old() {
+        let status = make_status(0, 0, "0.1.0");
+        let result = check_version_compatibility(&status);
+        assert!(result.is_err());
+        if let Err(ClientError::VersionMismatch(e)) = result {
+            assert_eq!(e.kind, VersionMismatchKind::DaemonTooOld);
+            assert_eq!(e.daemon_protocol_version, 0);
+            assert_eq!(e.tui_min_supported, MIN_SUPPORTED_VERSION);
+            assert!(e.to_string().contains("restart the daemon"));
+        } else {
+            panic!("Expected VersionMismatch error");
+        }
+    }
+
+    #[test]
+    fn test_version_mismatch_error_display_tui_too_old() {
+        let error = VersionMismatchError {
+            tui_protocol_version: 1,
+            tui_min_supported: 1,
+            daemon_protocol_version: 3,
+            daemon_min_supported: 2,
+            daemon_binary_version: "2.0.0".to_string(),
+            kind: VersionMismatchKind::TuiTooOld,
+        };
+        let msg = error.to_string();
+        assert!(msg.contains("TUI uses protocol v1"));
+        assert!(msg.contains("daemon (v2.0.0) requires v2+"));
+        assert!(msg.contains("brew upgrade jolt"));
+    }
+
+    #[test]
+    fn test_version_mismatch_error_display_daemon_too_old() {
+        let error = VersionMismatchError {
+            tui_protocol_version: 3,
+            tui_min_supported: 2,
+            daemon_protocol_version: 1,
+            daemon_min_supported: 1,
+            daemon_binary_version: "0.5.0".to_string(),
+            kind: VersionMismatchKind::DaemonTooOld,
+        };
+        let msg = error.to_string();
+        assert!(msg.contains("daemon (v0.5.0) uses protocol v1"));
+        assert!(msg.contains("TUI requires v2+"));
+        assert!(msg.contains("jolt daemon restart"));
+    }
+}
diff --git a/cli/src/daemon/mod.rs b/cli/src/daemon/mod.rs
@@ -3,7 +3,7 @@ mod protocol;
 mod server;
 pub mod service;
 
-pub use client::DaemonClient;
+pub use client::{ClientError, DaemonClient};
 #[allow(unused_imports)]
 pub use jolt_protocol::{
     BatterySnapshot, BatteryState, ChargeSession, ChargingState, CycleSummary, DaemonRequest,
diff --git a/crates/protocol/src/version.rs b/crates/protocol/src/version.rs
@@ -1,2 +1,37 @@
+//! Protocol versioning for daemon IPC communication.
+//!
+//! # Version History
+//!
+//! | Version | Changes |
+//! |---------|---------|
+//! | 1 | Initial protocol version |
+//! | 2 | Added `os_name` to SystemSnapshot, forecast fields |
+//!
+//! # Breaking Changes (require PROTOCOL_VERSION bump)
+//!
+//! - Removing fields from request/response types
+//! - Changing field types
+//! - Renaming fields without `#[serde(alias)]`
+//! - Removing enum variants
+//!
+//! # Non-Breaking Changes (safe without version bump)
+//!
+//! - Adding new optional fields with `#[serde(default)]`
+//! - Adding new request/response variants
+//! - Adding new enum variants
+//!
+//! # Support Policy
+//!
+//! We maintain N-1 backwards compatibility, meaning the current version
+//! supports communication with the previous version. When updating:
+//!
+//! 1. Bump `PROTOCOL_VERSION` for breaking changes
+//! 2. Keep `MIN_SUPPORTED_VERSION` one behind to allow gradual upgrades
+//! 3. Only bump `MIN_SUPPORTED_VERSION` when dropping support for old versions
+
+/// Current protocol version. Bump when making breaking changes.
 pub const PROTOCOL_VERSION: u32 = 2;
+
+/// Minimum protocol version this build can communicate with.
+/// Kept at N-1 to allow one version of backwards compatibility.
 pub const MIN_SUPPORTED_VERSION: u32 = 1;
