v0.3.2-pre.007

crates/ksp-store-lib/src/store.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-store-lib/src/store.rs
-// version: 3
+// version: 4
 
 /// Opaque common Store runtime facade.
 ///
@@ -37,6 +37,44 @@ impl Store {
         };
     }
 
+    /// Returns a safe synchronous runtime snapshot without performing backend I/O.
+    #[must_use]
+    pub fn runtime_snapshot(&self) -> crate::StoreRuntimeSnapshot {
+        #[cfg(feature = "postgres")]
+        {
+            return match &self.runtime {
+                StoreRuntime::Postgres(backend) => map_postgres_runtime_snapshot(backend.runtime_snapshot(), self.backend_kind, self.network.clone()),
+            };
+        }
+        #[cfg(not(feature = "postgres"))]
+        {
+            return crate::StoreRuntimeSnapshot::new(self.backend_kind, self.network.clone(), 0, 0, 0, 0);
+        }
+    }
+
+    /// Runs the selected backend's lightweight bounded readiness probe and returns only portable redacted diagnostics.
+    pub async fn health(&self) -> crate::StoreHealthSnapshot {
+        #[cfg(feature = "postgres")]
+        {
+            return match &self.runtime {
+                StoreRuntime::Postgres(backend) => {
+                    let snapshot = backend.health().await;
+                    map_postgres_health_snapshot(snapshot, self.backend_kind, self.network.clone())
+                },
+            };
+        }
+        #[cfg(not(feature = "postgres"))]
+        {
+            return crate::StoreHealthSnapshot::new(
+                crate::StoreHealthState::NotReady,
+                self.runtime_snapshot(),
+                std::option::Option::None,
+                0,
+                std::option::Option::Some(crate::ERROR_CODE_BACKEND_NOT_COMPILED),
+            );
+        }
+    }
+
     /// Explicitly closes the Store runtime, consumes its facade handle and applies the configured bounded shutdown deadline.
     pub async fn close(self) -> ksp_store_api::Result<()> {
         let backend_kind = self.backend_kind;
@@ -136,9 +174,47 @@ async fn open_postgres(
 
 #[cfg(feature = "postgres")]
 fn map_postgres_error(error: ksp_store_postgres_lib::PostgresBackendError, backend_kind: crate::StoreBackendKind, network: &str) -> ksp_store_api::Error {
-    let code = match error.kind() {
+    let code = postgres_error_code(error.kind());
+    return ksp_store_api::Error::new(code, "PostgreSQL Store backend lifecycle operation failed")
+        .with_context("backend", backend_kind.code())
+        .with_context("network", network)
+        .with_context("phase", error.phase());
+}
+
+#[cfg(feature = "postgres")]
+fn map_postgres_runtime_snapshot(
+    snapshot: ksp_store_postgres_lib::PostgresBackendRuntimeSnapshot,
+    backend_kind: crate::StoreBackendKind,
+    network: ksp_store_api::RawNetworkId,
+) -> crate::StoreRuntimeSnapshot {
+    return crate::StoreRuntimeSnapshot::new(
+        backend_kind,
+        network,
+        snapshot.pool_capacity(),
+        snapshot.pool_size(),
+        snapshot.pool_available(),
+        snapshot.pool_waiting(),
+    );
+}
+
+#[cfg(feature = "postgres")]
+fn map_postgres_health_snapshot(
+    snapshot: ksp_store_postgres_lib::PostgresBackendHealthSnapshot,
+    backend_kind: crate::StoreBackendKind,
+    network: ksp_store_api::RawNetworkId,
+) -> crate::StoreHealthSnapshot {
+    let state = if snapshot.is_ready() { crate::StoreHealthState::Ready } else { crate::StoreHealthState::NotReady };
+    let error_code = snapshot.error_kind().map(|kind| return postgres_error_code(kind));
+    let runtime = map_postgres_runtime_snapshot(snapshot.runtime().clone(), backend_kind, network);
+    return crate::StoreHealthSnapshot::new(state, runtime, snapshot.migration_version(), snapshot.pending_migration_count(), error_code);
+}
+
+#[cfg(feature = "postgres")]
+fn postgres_error_code(kind: ksp_store_postgres_lib::PostgresBackendErrorKind) -> ksp_store_api::ErrorCode {
+    return match kind {
         ksp_store_postgres_lib::PostgresBackendErrorKind::ConfigInvalid => crate::ERROR_CODE_POSTGRES_CONFIG_INVALID,
         ksp_store_postgres_lib::PostgresBackendErrorKind::ConnectFailed => crate::ERROR_CODE_POSTGRES_CONNECT_FAILED,
+        ksp_store_postgres_lib::PostgresBackendErrorKind::HealthFailed => crate::ERROR_CODE_POSTGRES_HEALTH_FAILED,
         ksp_store_postgres_lib::PostgresBackendErrorKind::PoolTimeout => crate::ERROR_CODE_POSTGRES_POOL_TIMEOUT,
         ksp_store_postgres_lib::PostgresBackendErrorKind::MigrationFailed => crate::ERROR_CODE_POSTGRES_MIGRATION_FAILED,
         ksp_store_postgres_lib::PostgresBackendErrorKind::MigrationMismatch => crate::ERROR_CODE_POSTGRES_MIGRATION_MISMATCH,
@@ -147,10 +223,6 @@ fn map_postgres_error(error: ksp_store_postgres_lib::PostgresBackendError, backe
         ksp_store_postgres_lib::PostgresBackendErrorKind::TlsFailed => crate::ERROR_CODE_POSTGRES_TLS_FAILED,
         _ => crate::ERROR_CODE_BACKEND_OPEN_FAILED,
     };
-    return ksp_store_api::Error::new(code, "PostgreSQL Store backend lifecycle operation failed")
-        .with_context("backend", backend_kind.code())
-        .with_context("network", network)
-        .with_context("phase", error.phase());
 }
 
 #[cfg(not(feature = "postgres"))]