Merge pull request #113 from NatLabRockies/fix/split-api-version

daniel-thom · web-flow · commit 1893dda247dc · 2026-02-11T20:37:59.000-07:00
Create new API version for server
diff --git a/src/bin/torc-dash.rs b/src/bin/torc-dash.rs
@@ -2301,7 +2301,9 @@ async fn server_status_handler(State(state): State<Arc<AppState>>) -> impl IntoR
 #[derive(Serialize)]
 struct VersionResponse {
     version: String,
+    api_version: String,
     server_version: Option<String>,
+    server_api_version: Option<String>,
     version_mismatch: Option<String>,
     mismatch_severity: Option<String>,
 }
@@ -2324,7 +2326,7 @@ async fn version_handler(State(state): State<Arc<AppState>>) -> impl IntoRespons
     .await
     .ok();
 
-    let (server_version, version_mismatch, mismatch_severity) = match result {
+    let (server_version, server_api_version, version_mismatch, mismatch_severity) = match result {
         Some(result) => match &result.server_version {
             Some(server_ver) => {
                 let severity_str = match result.severity {
@@ -2338,11 +2340,16 @@ async fn version_handler(State(state): State<Arc<AppState>>) -> impl IntoRespons
                 } else {
                     None
                 };
-                (Some(server_ver.clone()), mismatch_msg, severity_str)
+                (
+                    Some(server_ver.clone()),
+                    result.server_api_version.clone(),
+                    mismatch_msg,
+                    severity_str,
+                )
             }
-            None => (None, None, None),
+            None => (None, None, None, None),
         },
-        None => (None, None, None),
+        None => (None, None, None, None),
     };
 
     // Extract just the semver from server version (strip git hash suffix for display)
@@ -2352,7 +2359,9 @@ async fn version_handler(State(state): State<Arc<AppState>>) -> impl IntoRespons
 
     Json(VersionResponse {
         version: env!("CARGO_PKG_VERSION").to_string(),
+        api_version: version_check::CLIENT_API_VERSION.to_string(),
         server_version: server_version_display,
+        server_api_version,
         version_mismatch,
         mismatch_severity,
     })
diff --git a/src/client.rs b/src/client.rs
@@ -56,5 +56,5 @@ pub use report_models::{
 
 // Version checking utilities
 pub use version_check::{
-    VersionCheckResult, VersionMismatchSeverity, check_and_warn, check_version,
+    ServerInfo, VersionCheckResult, VersionMismatchSeverity, check_and_warn, check_version,
 };
diff --git a/src/client/job_runner.rs b/src/client/job_runner.rs
@@ -374,12 +374,19 @@ impl JobRunner {
             .server_version
             .clone()
             .unwrap_or_else(|| "unknown".to_string());
+        let server_api_version = version_result
+            .server_api_version
+            .clone()
+            .unwrap_or_else(|| "unknown".to_string());
 
         info!(
-            "Starting torc job runner version={} server_version={} workflow_id={} hostname={} output_dir={} resources={:?} rules={:?} \
+            "Starting torc job runner version={} client_api_version={} server_version={} server_api_version={} \
+            workflow_id={} hostname={} output_dir={} resources={:?} rules={:?} \
             job_completion_poll_interval={}s max_parallel_jobs={:?} end_time={:?} strict_scheduler_match={}",
             version,
+            version_check::CLIENT_API_VERSION,
             server_version,
+            server_api_version,
             self.workflow_id,
             hostname,
             self.output_dir.display(),
diff --git a/src/client/version_check.rs b/src/client/version_check.rs
@@ -1,14 +1,27 @@
-//! Version checking utilities for comparing client and server versions.
+//! Version checking utilities for comparing client and server API versions.
 //!
-//! This module provides functions to check version compatibility between
+//! This module provides functions to check API version compatibility between
 //! client applications and the torc-server, with appropriate warning levels.
+//!
+//! The HTTP API has its own semver version (e.g., "0.8.0") that is independent
+//! of the crate/binary version. This allows the client to change frequently
+//! without implying server incompatibility. The API version only bumps when the
+//! HTTP contract changes.
 
 use crate::client::apis::configuration::Configuration;
 use crate::client::apis::default_api;
 
 /// The current version of this binary, set at compile time.
 pub const CLIENT_VERSION: &str = env!("CARGO_PKG_VERSION");
 
+/// The API version that this client expects from the server.
+///
+/// Bump this only when the HTTP API contract changes:
+/// - Patch: bug fix in an existing endpoint (response field fix, etc.)
+/// - Minor: new endpoint, new optional field, new query parameter
+/// - Major: removed endpoint, renamed field, changed semantics
+pub const CLIENT_API_VERSION: &str = "0.8.0";
+
 /// The git commit hash of this binary, set at compile time via build.rs.
 pub const GIT_HASH: &str = env!("GIT_HASH");
 
@@ -25,16 +38,16 @@ pub fn version_with_hash() -> String {
     format!("{}-{}{}", CLIENT_VERSION, GIT_HASH, GIT_DIRTY)
 }
 
-/// Severity level for version mismatches.
+/// Severity level for API version mismatches.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum VersionMismatchSeverity {
-    /// Versions match exactly - no warning needed.
+    /// API versions match exactly - no warning needed.
     None,
     /// Only patch version differs - minor warning.
     Patch,
-    /// Minor version of client is higher than server - strong warning.
+    /// Client API minor version is higher than server - some features may not work.
     Minor,
-    /// Major version differs - error condition.
+    /// API major version differs - incompatible.
     Major,
 }
 
@@ -50,14 +63,27 @@ impl VersionMismatchSeverity {
     }
 }
 
-/// Result of a version check operation.
+/// Information retrieved from the server's /version endpoint.
+#[derive(Debug, Clone)]
+pub struct ServerInfo {
+    /// The server's binary version (e.g., "0.14.0 (abc1234)").
+    pub version: String,
+    /// The server's API version (e.g., "0.8.0").
+    pub api_version: Option<String>,
+}
+
+/// Result of an API version check operation.
 #[derive(Debug, Clone)]
 pub struct VersionCheckResult {
-    /// The client (local) version.
+    /// The client binary version.
     pub client_version: String,
-    /// The server version (if successfully retrieved).
+    /// The server binary version (if successfully retrieved).
     pub server_version: Option<String>,
-    /// The severity of any version mismatch.
+    /// The client API version.
+    pub client_api_version: String,
+    /// The server API version (if successfully retrieved).
+    pub server_api_version: Option<String>,
+    /// The severity of any API version mismatch.
     pub severity: VersionMismatchSeverity,
     /// A human-readable message describing the result.
     pub message: String,
@@ -69,19 +95,41 @@ impl VersionCheckResult {
         Self {
             client_version: CLIENT_VERSION.to_string(),
             server_version: None,
+            client_api_version: CLIENT_API_VERSION.to_string(),
+            server_api_version: None,
             severity: VersionMismatchSeverity::None,
             message: "Could not check server version".to_string(),
         }
     }
 
     /// Creates a new result for a successful version check.
-    pub fn new(client_version: &str, server_version: &str) -> Self {
-        let severity = compare_versions(client_version, server_version);
-        let message = format_version_message(client_version, server_version, severity);
+    pub fn from_server_info(server_info: &ServerInfo) -> Self {
+        let (severity, message) = match &server_info.api_version {
+            Some(server_api) => {
+                let severity = compare_versions(CLIENT_API_VERSION, server_api);
+                let message = format_api_version_message(
+                    CLIENT_API_VERSION,
+                    server_api,
+                    &server_info.version,
+                    severity,
+                );
+                (severity, message)
+            }
+            None => {
+                // Old server that doesn't report api_version — fall back to
+                // comparing binary versions (pre-API-versioning behavior).
+                let severity = compare_versions(CLIENT_VERSION, &server_info.version);
+                let message =
+                    format_legacy_version_message(CLIENT_VERSION, &server_info.version, severity);
+                (severity, message)
+            }
+        };
 
         Self {
-            client_version: client_version.to_string(),
-            server_version: Some(server_version.to_string()),
+            client_version: CLIENT_VERSION.to_string(),
+            server_version: Some(server_info.version.clone()),
+            client_api_version: CLIENT_API_VERSION.to_string(),
+            server_api_version: server_info.api_version.clone(),
             severity,
             message,
         }
@@ -154,8 +202,47 @@ pub fn compare_versions(client_version: &str, server_version: &str) -> VersionMi
     VersionMismatchSeverity::None
 }
 
-/// Formats a human-readable message for the version check result.
-fn format_version_message(
+/// Formats a human-readable message for an API version mismatch.
+fn format_api_version_message(
+    client_api: &str,
+    server_api: &str,
+    server_version: &str,
+    severity: VersionMismatchSeverity,
+) -> String {
+    match severity {
+        VersionMismatchSeverity::None => {
+            format!(
+                "API version {} matches server (server {})",
+                client_api, server_version
+            )
+        }
+        VersionMismatchSeverity::Patch => {
+            format!(
+                "API version mismatch: client API {} vs server API {} \
+                 (server {}) - patch difference, should be compatible",
+                client_api, server_api, server_version
+            )
+        }
+        VersionMismatchSeverity::Minor => {
+            format!(
+                "API version mismatch: client API {} is newer than server API {} \
+                 (server {}) - some client features may not be supported by this server",
+                client_api, server_api, server_version
+            )
+        }
+        VersionMismatchSeverity::Major => {
+            format!(
+                "API version incompatible: client API {} vs server API {} \
+                 (server {}) - major version mismatch, client and server are not compatible",
+                client_api, server_api, server_version
+            )
+        }
+    }
+}
+
+/// Formats a human-readable message when the server doesn't report an API version
+/// (pre-API-versioning server). Falls back to comparing binary versions.
+fn format_legacy_version_message(
     client_version: &str,
     server_version: &str,
     severity: VersionMismatchSeverity,
@@ -172,42 +259,61 @@ fn format_version_message(
         }
         VersionMismatchSeverity::Minor => {
             format!(
-                "Warning: Client version {} is newer than server {} - some features may not work",
+                "Client version {} is newer than server {} \
+                 - server does not report API version, some features may not work",
                 client_version, server_version
             )
         }
         VersionMismatchSeverity::Major => {
             format!(
-                "Error: Major version mismatch - client {} vs server {} - incompatible versions",
+                "Major version mismatch: client {} vs server {} \
+                 - server does not report API version, client and server are likely incompatible",
                 client_version, server_version
             )
         }
     }
 }
 
-/// Fetches the server version from the API.
-pub fn get_server_version(config: &Configuration) -> Option<String> {
+/// Fetches server information from the /version endpoint.
+pub fn get_server_info(config: &Configuration) -> Option<ServerInfo> {
     match default_api::get_version(config) {
         Ok(value) => {
-            // The server returns the version as a JSON string
-            if let Some(version) = value.as_str() {
-                Some(version.to_string())
-            } else {
-                // Try to extract from object if wrapped
-                value
+            if value.is_object() {
+                // New structured response: { "version": "...", "api_version": "...", ... }
+                let version = value
                     .get("version")
                     .and_then(|v| v.as_str())
-                    .map(|s| s.to_string())
+                    .map(|s| s.to_string())?;
+                let api_version = value
+                    .get("api_version")
+                    .and_then(|v| v.as_str())
+                    .map(|s| s.to_string());
+                Some(ServerInfo {
+                    version,
+                    api_version,
+                })
+            } else {
+                // Legacy response: plain string (pre-API-versioning server)
+                value.as_str().map(|version| ServerInfo {
+                    version: version.to_string(),
+                    api_version: None,
+                })
             }
         }
         Err(_) => None,
     }
 }
 
-/// Performs a version check between the client and server.
+/// Fetches the server version string from the API.
+/// Returns the binary version for display purposes (e.g., in log messages).
+pub fn get_server_version(config: &Configuration) -> Option<String> {
+    get_server_info(config).map(|info| info.version)
+}
+
+/// Performs an API version check between the client and server.
 pub fn check_version(config: &Configuration) -> VersionCheckResult {
-    match get_server_version(config) {
-        Some(server_version) => VersionCheckResult::new(CLIENT_VERSION, &server_version),
+    match get_server_info(config) {
+        Some(server_info) => VersionCheckResult::from_server_info(&server_info),
         None => VersionCheckResult::server_unreachable(),
     }
 }
diff --git a/src/server/api_types.rs b/src/server/api_types.rs
@@ -31,7 +31,7 @@ use tokio::sync::broadcast;
 pub type ServiceError = Box<dyn Error + Send + Sync + 'static>;
 
 pub const BASE_PATH: &str = "/torc-service/v1";
-pub const API_VERSION: &str = "v0.7.0";
+pub const API_VERSION: &str = "0.8.0";
 
 #[derive(Debug, PartialEq, Serialize, Deserialize)]
 #[must_use]
diff --git a/src/server/http_server.rs b/src/server/http_server.rs
@@ -2685,9 +2685,11 @@ where
             "get_version() - X-Span-ID: {:?}",
             Has::<XSpanIdString>::get(context).0.clone()
         );
-        Ok(GetVersionResponse::SuccessfulResponse(serde_json::json!(
-            full_version()
-        )))
+        Ok(GetVersionResponse::SuccessfulResponse(serde_json::json!({
+            "version": full_version(),
+            "api_version": API_VERSION,
+            "git_hash": GIT_HASH
+        })))
     }
 
     /// Retrieve all workflows.
diff --git a/src/tui/ui.rs b/src/tui/ui.rs
@@ -274,10 +274,12 @@ fn draw_server_url(f: &mut Frame, area: Rect, app: &App) {
             version_check::VersionMismatchSeverity::Patch => Color::Yellow,
             version_check::VersionMismatchSeverity::None => Color::Green,
         };
-        spans.push(Span::styled(
-            format!(" (server v{})", server_version),
-            Style::default().fg(version_color),
-        ));
+        let display = if let Some(ref api_ver) = version_result.server_api_version {
+            format!(" (server {} API {})", server_version, api_ver)
+        } else {
+            format!(" (server {})", server_version)
+        };
+        spans.push(Span::styled(display, Style::default().fg(version_color)));
     }
 
     spans.extend(vec![
diff --git a/tests/test_version_check.rs b/tests/test_version_check.rs
