impl: backends registry, KvsMap backend params

- Added `KvsBackendRegistry`.
- `KvsBuilder` accepts backend params through `KvsMap`.
- Built-in backend access is now hidden.
- `backend_registration` example.

Author: arkjedrz

README.md

@@ -183,12 +183,6 @@ Snapshot Count:
 Snapshot Restore:
     kvs_tool -o snapshotrestore -s 1
 
-Get KVS Filename:
-    kvs_tool -o getkvsfilename -s 1
-
-Get Hash Filename:
-    kvs_tool -o gethashfilename -s 1
-
 ---------------------------------------
 
 Create Test Data:

src/rust/rust_kvs/examples/backend_registration.rs

@@ -0,0 +1,111 @@
+//! Example for custom backend registration.
+//! - Implementation of `KvsBackend` traits.
+//! - Registration of custom backend.
+//! - Creation of KVS instance utilizing custom backend.
+
+use rust_kvs::prelude::*;
+use tempfile::tempdir;
+
+/// Mock backend implementation.
+/// Only `load_kvs` is implemented.
+struct MockBackend;
+
+impl KvsBackend for MockBackend {
+    fn load_kvs(
+        &self,
+        _instance_id: InstanceId,
+        _snapshot_id: SnapshotId,
+    ) -> Result<KvsMap, ErrorCode> {
+        println!("`load_kvs` used");
+        Ok(KvsMap::new())
+    }
+
+    fn load_defaults(&self, _instance_id: InstanceId) -> Result<KvsMap, ErrorCode> {
+        unimplemented!()
+    }
+
+    fn flush(&self, _instance_id: InstanceId, _kvs_map: &KvsMap) -> Result<(), ErrorCode> {
+        unimplemented!()
+    }
+
+    fn snapshot_count(&self, _instance_id: InstanceId) -> usize {
+        unimplemented!()
+    }
+
+    fn snapshot_max_count(&self) -> usize {
+        unimplemented!()
+    }
+
+    fn snapshot_restore(
+        &self,
+        _instance_id: InstanceId,
+        _snapshot_id: SnapshotId,
+    ) -> Result<KvsMap, ErrorCode> {
+        unimplemented!()
+    }
+}
+
+/// Mock backend factory implementation.
+struct MockBackendFactory;
+
+impl KvsBackendFactory for MockBackendFactory {
+    fn create(&self, _parameters: &KvsMap) -> Result<Box<dyn KvsBackend>, ErrorCode> {
+        Ok(Box::new(MockBackend))
+    }
+}
+
+fn main() -> Result<(), ErrorCode> {
+    // Temporary directory.
+    let dir = tempdir()?;
+    let dir_string = dir.path().to_string_lossy().to_string();
+
+    // Register `MockBackendFactory`.
+    KvsBackendRegistry::register("mock", || Box::new(MockBackendFactory))?;
+
+    // Build KVS instance with mock backend.
+    {
+        let instance_id = InstanceId(0);
+        let parameters = KvsMap::from([("name".to_string(), KvsValue::String("mock".to_string()))]);
+        let builder = KvsBuilder::new(instance_id)
+            .backend_parameters(parameters)
+            .defaults(KvsDefaults::Ignored);
+        let kvs = builder.build()?;
+
+        println!(
+            "KVS instance with mock backend - parameters: {:?}",
+            kvs.parameters()
+        );
+    }
+
+    // Build KVS instance with JSON backend - default parameters.
+    {
+        let instance_id = InstanceId(1);
+        let builder = KvsBuilder::new(instance_id).defaults(KvsDefaults::Ignored);
+        let kvs = builder.build()?;
+
+        println!(
+            "KVS instance with default JSON backend - parameters: {:?}",
+            kvs.parameters()
+        );
+    }
+
+    // Build KVS instance with JSON backend - `working_dir` set.
+    {
+        let instance_id = InstanceId(2);
+        let parameters = KvsMap::from([
+            ("name".to_string(), KvsValue::String("json".to_string())),
+            ("working_dir".to_string(), KvsValue::String(dir_string)),
+        ]);
+        let builder = KvsBuilder::new(instance_id)
+            .backend_parameters(parameters)
+            .defaults(KvsDefaults::Ignored);
+        let kvs = builder.build()?;
+
+        println!(
+            "KVS instance with JSON backend - parameters: {:?}",
+            kvs.parameters()
+        );
+    }
+
+    Ok(())
+}

src/rust/rust_kvs/examples/basic.rs

@@ -8,10 +8,13 @@ use std::collections::HashMap;
 use tempfile::tempdir;
 
 fn main() -> Result<(), ErrorCode> {
-    // Temporary directory and common backend.
+    // Temporary directory.
     let dir = tempdir()?;
-    let dir_path = dir.path().to_path_buf();
-    let backend = Box::new(JsonBackendBuilder::new().working_dir(dir_path).build());
+    let dir_string = dir.path().to_string_lossy().to_string();
+    let backend_parameters = KvsMap::from([
+        ("name".to_string(), KvsValue::String("json".to_string())),
+        ("working_dir".to_string(), KvsValue::String(dir_string)),
+    ]);
 
     // Instance ID for KVS object instances.
     let instance_id = InstanceId(0);
@@ -21,7 +24,7 @@ fn main() -> Result<(), ErrorCode> {
         // `kvs_load` is explicitly set to `KvsLoad::Optional`, but this is the default value.
         // KVS files are not required.
         let builder = KvsBuilder::new(instance_id)
-            .backend(backend.clone())
+            .backend_parameters(backend_parameters.clone())
             .kvs_load(KvsLoad::Optional);
         let kvs = builder.build()?;
 
@@ -66,7 +69,7 @@ fn main() -> Result<(), ErrorCode> {
         // Build KVS instance for given instance ID and temporary directory.
         // `kvs_load` is set to `KvsLoad::Required` - KVS files must already exist from previous KVS instance.
         let builder = KvsBuilder::new(instance_id)
-            .backend(backend)
+            .backend_parameters(backend_parameters)
             .kvs_load(KvsLoad::Required);
         let kvs = builder.build()?;
 

src/rust/rust_kvs/examples/defaults.rs

@@ -31,10 +31,13 @@ fn create_defaults_file(dir_path: PathBuf, instance_id: InstanceId) -> Result<()
 }
 
 fn main() -> Result<(), ErrorCode> {
-    // Temporary directory and common backend.
+    // Temporary directory.
     let dir = tempdir()?;
-    let dir_path = dir.path().to_path_buf();
-    let backend = Box::new(JsonBackendBuilder::new().working_dir(dir_path).build());
+    let dir_string = dir.path().to_string_lossy().to_string();
+    let backend_parameters = KvsMap::from([
+        ("name".to_string(), KvsValue::String("json".to_string())),
+        ("working_dir".to_string(), KvsValue::String(dir_string)),
+    ]);
 
     // Instance ID for KVS object instances.
     let instance_id = InstanceId(0);
@@ -45,7 +48,7 @@ fn main() -> Result<(), ErrorCode> {
     // Build KVS instance for given instance ID and temporary directory.
     // `defaults` is set to `KvsDefaults::Required` - defaults are required.
     let builder = KvsBuilder::new(instance_id)
-        .backend(backend.clone())
+        .backend_parameters(backend_parameters)
         .defaults(KvsDefaults::Required);
     let kvs = builder.build()?;
 

src/rust/rust_kvs/examples/snapshots.rs

@@ -8,8 +8,11 @@ use tempfile::tempdir;
 fn main() -> Result<(), ErrorCode> {
     // Temporary directory and common backend.
     let dir = tempdir()?;
-    let dir_path = dir.path().to_path_buf();
-    let backend = Box::new(JsonBackendBuilder::new().working_dir(dir_path).build());
+    let dir_string = dir.path().to_string_lossy().to_string();
+    let backend_parameters = KvsMap::from([
+        ("name".to_string(), KvsValue::String("json".to_string())),
+        ("working_dir".to_string(), KvsValue::String(dir_string)),
+    ]);
 
     // Instance ID for KVS object instances.
     let instance_id = InstanceId(0);
@@ -18,7 +21,7 @@ fn main() -> Result<(), ErrorCode> {
         println!("-> `snapshot_count` and `snapshot_max_count` usage");
 
         // Build KVS instance for given instance ID and temporary directory.
-        let builder = KvsBuilder::new(instance_id).backend(backend.clone());
+        let builder = KvsBuilder::new(instance_id).backend_parameters(backend_parameters.clone());
         let kvs = builder.build()?;
 
         let max_count = kvs.snapshot_max_count() as u32;
@@ -39,7 +42,7 @@ fn main() -> Result<(), ErrorCode> {
         println!("-> `snapshot_restore` usage");
 
         // Build KVS instance for given instance ID and temporary directory.
-        let builder = KvsBuilder::new(instance_id).backend(backend.clone());
+        let builder = KvsBuilder::new(instance_id).backend_parameters(backend_parameters);
         let kvs = builder.build()?;
 
         let max_count = kvs.snapshot_max_count() as u32;

src/rust/rust_kvs/src/error_code.rs

@@ -82,6 +82,15 @@ pub enum ErrorCode {
 
     /// Instance parameters mismatch
     InstanceParametersMismatch,
+
+    /// Requested unknown backend
+    UnknownBackend,
+
+    /// Backend already registered
+    BackendAlreadyRegistered,
+
+    /// Invalid backend parameters.
+    InvalidBackendParameters,
 }
 
 impl From<std::io::Error> for ErrorCode {

src/rust/rust_kvs/src/json_backend.rs

@@ -11,7 +11,7 @@
 
 use crate::error_code::ErrorCode;
 use crate::kvs_api::{InstanceId, SnapshotId};
-use crate::kvs_backend::KvsBackend;
+use crate::kvs_backend::{KvsBackend, KvsBackendFactory};
 use crate::kvs_value::{KvsMap, KvsValue};
 use std::collections::HashMap;
 use std::fs;
@@ -151,7 +151,7 @@ impl From<JsonGenerateError> for ErrorCode {
 }
 
 /// Builder for `JsonBackend`.
-pub struct JsonBackendBuilder {
+pub(crate) struct JsonBackendBuilder {
     working_dir: PathBuf,
     snapshot_max_count: usize,
 }
@@ -190,7 +190,7 @@ impl Default for JsonBackendBuilder {
 
 /// KVS backend implementation based on TinyJSON.
 #[derive(Clone, PartialEq)]
-pub struct JsonBackend {
+pub(crate) struct JsonBackend {
     working_dir: PathBuf,
     snapshot_max_count: usize,
 }
@@ -255,7 +255,7 @@ impl JsonBackend {
         ext.is_some_and(|ep| ep.to_str().is_some_and(|es| es == extension))
     }
 
-    pub(super) fn load(kvs_path: &Path, hash_path: Option<&PathBuf>) -> Result<KvsMap, ErrorCode> {
+    pub(crate) fn load(kvs_path: &Path, hash_path: Option<&PathBuf>) -> Result<KvsMap, ErrorCode> {
         if !Self::check_extension(kvs_path, "json") {
             return Err(ErrorCode::KvsFileReadError);
         }
@@ -299,7 +299,7 @@ impl JsonBackend {
         }
     }
 
-    pub(super) fn save(
+    pub(crate) fn save(
         kvs_map: &KvsMap,
         kvs_path: &Path,
         hash_path: Option<&PathBuf>,
@@ -433,13 +433,41 @@ impl KvsBackend for JsonBackend {
     }
 }
 
+/// `JsonBackend` factory.
+pub(crate) struct JsonBackendFactory;
+
+impl KvsBackendFactory for JsonBackendFactory {
+    fn create(&self, parameters: &KvsMap) -> Result<Box<dyn KvsBackend>, ErrorCode> {
+        let mut builder = JsonBackendBuilder::new();
+
+        // Set working directory.
+        if let Some(working_dir) = parameters.get("working_dir") {
+            if let KvsValue::String(working_dir) = working_dir {
+                builder = builder.working_dir(PathBuf::from(working_dir));
+            } else {
+                return Err(ErrorCode::InvalidBackendParameters);
+            }
+        }
+
+        // Set snapshot max count.
+        if let Some(snapshot_max_count) = parameters.get("snapshot_max_count") {
+            if let KvsValue::U64(snapshot_max_count) = snapshot_max_count {
+                builder = builder.snapshot_max_count(*snapshot_max_count as usize);
+            } else {
+                return Err(ErrorCode::InvalidBackendParameters);
+            }
+        }
+
+        Ok(Box::new(builder.build()))
+    }
+}
+
 #[cfg(test)]
 mod json_value_to_kvs_value_conversion_tests {
+    use crate::kvs_value::{KvsMap, KvsValue};
     use std::collections::HashMap;
     use tinyjson::JsonValue;
 
-    use crate::prelude::{KvsMap, KvsValue};
-
     #[test]
     fn test_i32_ok() {
         let jv = JsonValue::from(HashMap::from([
@@ -1356,3 +1384,59 @@ mod kvs_backend_tests {
         assert!(result.is_err_and(|e| e == ErrorCode::InvalidSnapshotId));
     }
 }
+
+#[cfg(test)]
+mod kvs_backend_factory_tests {
+    use crate::error_code::ErrorCode;
+    use crate::json_backend::JsonBackendFactory;
+    use crate::kvs_backend::KvsBackendFactory;
+    use crate::kvs_value::{KvsMap, KvsValue};
+
+    #[test]
+    fn test_create_default_ok() {
+        let factory = JsonBackendFactory;
+        let params = KvsMap::new();
+        let backend = factory.create(&params).unwrap();
+        // `working_dir` is not exposed in the API.
+        assert_eq!(backend.snapshot_max_count(), 3);
+    }
+
+    #[test]
+    fn test_create_params_ok() {
+        let factory = JsonBackendFactory;
+        let params = KvsMap::from([
+            (
+                "working_dir".to_string(),
+                KvsValue::String("/some/path/".to_string()),
+            ),
+            ("snapshot_max_count".to_string(), KvsValue::U64(1234)),
+        ]);
+        let backend = factory.create(&params).unwrap();
+        // `working_dir` is not exposed in the API.
+        assert_eq!(backend.snapshot_max_count(), 1234);
+    }
+
+    #[test]
+    fn test_create_working_dir_invalid_type() {
+        let factory = JsonBackendFactory;
+        let params = KvsMap::from([("working_dir".to_string(), KvsValue::Boolean(true))]);
+        let result = factory.create(&params);
+        assert!(result.is_err_and(|e| e == ErrorCode::InvalidBackendParameters));
+    }
+
+    #[test]
+    fn test_create_snapshot_max_count_invalid_type() {
+        let factory = JsonBackendFactory;
+        let params = KvsMap::from([("snapshot_max_count".to_string(), KvsValue::I32(-123))]);
+        let result = factory.create(&params);
+        assert!(result.is_err_and(|e| e == ErrorCode::InvalidBackendParameters));
+    }
+
+    #[test]
+    fn test_create_unknown_param_ok() {
+        let factory = JsonBackendFactory;
+        let params = KvsMap::from([("unknown_param".to_string(), KvsValue::I32(12345))]);
+        let result = factory.create(&params);
+        assert!(result.is_ok());
+    }
+}