v0.3.2-pre.003

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

@@ -0,0 +1,56 @@
+// file: crates/ksp-store-lib/src/store.rs
+// version: 1
+
+/// Opaque common Store runtime facade.
+///
+/// A successful value is returned only after the selected backend has completed its bounded readiness path. `0.3.2-pre.003` establishes the lifecycle
+/// contract but intentionally has no successful opening path until the PostgreSQL runtime foundation is materialized by later prereleases.
+#[derive(Debug)]
+#[non_exhaustive]
+pub struct Store;
+
+impl Store {
+    /// Validates settings, selects the requested backend and opens a ready Store runtime.
+    ///
+    /// A known backend whose Cargo feature is absent is rejected before any I/O. During `0.3.2-pre.003`, the compiled PostgreSQL path also stops before I/O
+    /// with [`crate::ERROR_CODE_BACKEND_OPEN_FAILED`] because physical connection ownership is introduced in `pre.005`.
+    pub async fn open(settings: crate::StoreSettings) -> ksp_store_api::Result<Self> {
+        let validation = settings.validate();
+        if let std::result::Result::Err(error) = validation {
+            return std::result::Result::Err(error);
+        }
+        let backend_kind = settings.backend_kind();
+        return match backend_kind {
+            crate::StoreBackendKind::Postgres => open_postgres_contract(backend_kind).await,
+        };
+    }
+
+    /// Explicitly closes the Store runtime and consumes its facade handle.
+    ///
+    /// `pre.003` cannot yet produce a successful Store instance, so the physical bounded shutdown path remains reserved for backend composition. The consuming
+    /// async signature is fixed here so no pool or backend handle needs to escape later.
+    pub async fn close(self) -> ksp_store_api::Result<()> {
+        return std::result::Result::Ok(());
+    }
+}
+
+#[cfg(feature = "postgres")]
+async fn open_postgres_contract(backend_kind: crate::StoreBackendKind) -> ksp_store_api::Result<Store> {
+    return std::result::Result::Err(
+        ksp_store_api::Error::new(crate::ERROR_CODE_BACKEND_OPEN_FAILED, "PostgreSQL Store runtime opening is not materialized in this prerelease")
+            .with_context("backend", backend_kind.code())
+            .with_context("stage", "runtime_foundation_pending"),
+    );
+}
+
+#[cfg(not(feature = "postgres"))]
+async fn open_postgres_contract(backend_kind: crate::StoreBackendKind) -> ksp_store_api::Result<Store> {
+    return std::result::Result::Err(
+        ksp_store_api::Error::new(crate::ERROR_CODE_BACKEND_NOT_COMPILED, "Selected Store backend is not compiled")
+            .with_context("backend", backend_kind.code()),
+    );
+}
+
+#[cfg(test)]
+#[path = "../unit_tests/store.rs"]
+mod tests;