Common/Storage/StorageProvider.rs
1//! # StorageProvider Trait
2//!
3//! Defines the abstract service trait for Memento-style persistent key-value
4//! storage capabilities.
5
6use async_trait::async_trait;
7use serde_json::Value;
8
9use crate::{Environment::Environment::Environment, Error::CommonError::CommonError};
10
11/// An abstract service contract for an environment component that provides
12/// persistent key-value storage, similar to VS Code's Memento API.
13///
14/// This trait is implemented by `MountainEnvironment` and is responsible for
15/// reading from and writing to the appropriate JSON storage files on disk,
16
17/// separating global state from workspace-specific state.
18#[async_trait]
19pub trait StorageProvider: Environment + Send + Sync {
20 /// Retrieves a value from storage for a given key and scope.
21 ///
22 /// # Parameters
23 /// * `IsGlobalScope`: If `true`, retrieves from global storage; otherwise,
24
25 /// retrieves from the current workspace's storage.
26 /// * `Key`: The key of the value to retrieve.
27 ///
28 /// # Returns
29 /// A `Result` containing an `Option<Value>`. It resolves to
30 /// `Ok(Some(Value))` if the key exists, `Ok(None)` if it does not, or an
31 /// `Err` on failure (e.g., I/O error).
32 async fn GetStorageValue(&self, IsGlobalScope:bool, Key:&str) -> Result<Option<Value>, CommonError>;
33
34 /// Updates or stores a value in storage for a given key and scope.
35 ///
36 /// # Parameters
37 /// * `IsGlobalScope`: If `true`, updates global storage; otherwise,
38
39 /// workspace storage.
40 /// * `Key`: The key of the value to update.
41 /// * `ValueToSet`: The `serde_json::Value` to store. If this is `None`, the
42 /// key should be deleted from storage.
43 async fn UpdateStorageValue(
44 &self,
45
46 IsGlobalScope:bool,
47
48 Key:String,
49
50 ValueToSet:Option<Value>,
51 ) -> Result<(), CommonError>;
52
53 /// Retrieves the entire storage state for a given scope.
54 async fn GetAllStorage(&self, IsGlobalScope:bool) -> Result<Value, CommonError>;
55
56 /// Overwrites the entire storage state for a given scope with a new state.
57 async fn SetAllStorage(&self, IsGlobalScope:bool, FullState:Value) -> Result<(), CommonError>;
58}