0.0.2

kb_lib/src/config.rs

@@ -0,0 +1,455 @@
+// file: kb_lib/src/config.rs
+
+//! JSON configuration structures and loading helpers for `kb_lib`.
+
+/// Root application configuration loaded from `config.json`.
+#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
+pub struct KbConfig {
+    /// Application-level metadata and global behavior.
+    pub app: KbAppConfig,
+    /// Tracing and log output configuration.
+    pub logging: KbLoggingConfig,
+    /// Data directory configuration.
+    pub data: KbDataConfig,
+    /// Solana endpoint configuration.
+    pub solana: KbSolanaConfig,
+}
+
+/// Generic application settings.
+#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
+pub struct KbAppConfig {
+    /// Human-readable application name.
+    pub name: std::string::String,
+    /// Current environment name such as `development` or `production`.
+    pub environment: std::string::String,
+    /// Default reconnection preference used by future UI settings.
+    pub auto_reconnect_default: bool,
+}
+
+/// Logging and tracing configuration.
+///
+/// In version `0.0.2`, the project actively uses:
+/// `level`, `console_enabled`, `console_ansi`, `file_enabled`,
+/// `directory`, `file_prefix`, and `rotation`.
+///
+/// The fields `message_format` and `time_format` are already stored in the
+/// configuration so that the format policy is stabilized early, even though
+/// their handling will be refined in later versions.
+#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
+pub struct KbLoggingConfig {
+    /// Global default log level.
+    pub level: std::string::String,
+    /// Enables console logging.
+    pub console_enabled: bool,
+    /// Enables ANSI colors on console output.
+    pub console_ansi: bool,
+    /// Enables file logging.
+    pub file_enabled: bool,
+    /// Directory where log files are stored.
+    pub directory: std::string::String,
+    /// Prefix used for log file names.
+    pub file_prefix: std::string::String,
+    /// File rotation strategy such as `daily`, `hourly`, or `never`.
+    pub rotation: std::string::String,
+    /// Preferred message formatting preset.
+    pub message_format: std::string::String,
+    /// Preferred time formatting preset.
+    pub time_format: std::string::String,
+    /// Per-target log level overrides.
+    pub target_filters: std::collections::BTreeMap<std::string::String, std::string::String>,
+}
+
+/// Local data paths used by the application.
+#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
+pub struct KbDataConfig {
+    /// SQLite database path.
+    pub sqlite_path: std::string::String,
+    /// Directory storing Solana wallets and related material in future versions.
+    pub wallets_directory: std::string::String,
+}
+
+/// Solana transport configuration.
+#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
+pub struct KbSolanaConfig {
+    /// Named HTTP endpoints.
+    pub http_endpoints: std::vec::Vec<KbHttpEndpointConfig>,
+    /// Named WebSocket endpoints.
+    pub ws_endpoints: std::vec::Vec<KbWsEndpointConfig>,
+}
+
+/// HTTP endpoint configuration.
+#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
+pub struct KbHttpEndpointConfig {
+    /// Stable internal endpoint name used by the application.
+    pub name: std::string::String,
+    /// Enables or disables the endpoint.
+    pub enabled: bool,
+    /// Provider name such as `solana-public`, `helius`, or `custom`.
+    pub provider: std::string::String,
+    /// Base HTTP RPC URL.
+    pub url: std::string::String,
+    /// Optional environment variable name used to resolve an API key later.
+    pub api_key_env_var: std::option::Option<std::string::String>,
+    /// Logical roles assigned to this endpoint.
+    pub roles: std::vec::Vec<std::string::String>,
+    /// Allowed average request rate.
+    pub requests_per_second: u32,
+    /// Burst capacity for future rate-limiting.
+    pub burst: u32,
+    /// HTTP connect timeout in milliseconds.
+    pub connect_timeout_ms: u64,
+    /// HTTP request timeout in milliseconds.
+    pub request_timeout_ms: u64,
+}
+
+/// WebSocket endpoint configuration.
+#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
+pub struct KbWsEndpointConfig {
+    /// Stable internal endpoint name used by the application.
+    pub name: std::string::String,
+    /// Enables or disables the endpoint.
+    pub enabled: bool,
+    /// Provider name such as `solana-public`, `helius`, or `custom`.
+    pub provider: std::string::String,
+    /// Base WebSocket RPC URL.
+    pub url: std::string::String,
+    /// Optional environment variable name used to resolve an API key later.
+    pub api_key_env_var: std::option::Option<std::string::String>,
+    /// Logical roles assigned to this endpoint.
+    pub roles: std::vec::Vec<std::string::String>,
+    /// Maximum number of subscriptions allowed on this endpoint.
+    pub max_subscriptions: u32,
+    /// WebSocket connect timeout in milliseconds.
+    pub connect_timeout_ms: u64,
+    /// Timeout for request/response round-trips in milliseconds.
+    pub request_timeout_ms: u64,
+    /// Timeout used during unsubscribe on disconnect in milliseconds.
+    pub unsubscribe_timeout_ms: u64,
+    /// Capacity of the future outgoing write channel.
+    pub write_channel_capacity: usize,
+    /// Capacity of the future event channel.
+    pub event_channel_capacity: usize,
+    /// Enables future automatic reconnection behavior.
+    pub auto_reconnect: bool,
+}
+
+impl KbConfig {
+    /// Returns the default path of the JSON configuration file.
+    pub fn default_path() -> std::path::PathBuf {
+        kb_workspace_root_dir().join("config.json")
+    }
+
+    /// Loads a configuration from a JSON file and validates it.
+    pub fn load_from_path<P: AsRef<std::path::Path>>(path: P) -> Result<Self, crate::KbError> {
+        let path_ref = path.as_ref();
+        let content_result = std::fs::read_to_string(path_ref);
+        let content = match content_result {
+            Ok(content) => content,
+            Err(error) => {
+                return Err(crate::KbError::Io(format!(
+                    "cannot read configuration file '{}': {error}",
+                    path_ref.display()
+                )));
+            }
+        };
+        let config_result = serde_json::from_str::<Self>(&content);
+        let config = match config_result {
+            Ok(config) => config,
+            Err(error) => {
+                return Err(crate::KbError::Json(format!(
+                    "cannot parse configuration file '{}': {error}",
+                    path_ref.display()
+                )));
+            }
+        };
+        let validation_result = config.validate();
+        match validation_result {
+            Ok(()) => Ok(config),
+            Err(error) => Err(error),
+        }
+    }
+
+    /// Validates the current configuration.
+    pub fn validate(&self) -> Result<(), crate::KbError> {
+        if self.app.name.trim().is_empty() {
+            return Err(crate::KbError::Config(
+                "app.name must not be empty".to_string(),
+            ));
+        }
+        if self.app.environment.trim().is_empty() {
+            return Err(crate::KbError::Config(
+                "app.environment must not be empty".to_string(),
+            ));
+        }
+        if self.logging.level.trim().is_empty() {
+            return Err(crate::KbError::Config(
+                "logging.level must not be empty".to_string(),
+            ));
+        }
+        if self.logging.directory.trim().is_empty() {
+            return Err(crate::KbError::Config(
+                "logging.directory must not be empty".to_string(),
+            ));
+        }
+        if self.logging.file_prefix.trim().is_empty() {
+            return Err(crate::KbError::Config(
+                "logging.file_prefix must not be empty".to_string(),
+            ));
+        }
+        if self.data.sqlite_path.trim().is_empty() {
+            return Err(crate::KbError::Config(
+                "data.sqlite_path must not be empty".to_string(),
+            ));
+        }
+        if self.data.wallets_directory.trim().is_empty() {
+            return Err(crate::KbError::Config(
+                "data.wallets_directory must not be empty".to_string(),
+            ));
+        }
+        if self.logging.rotation != "daily"
+            && self.logging.rotation != "hourly"
+            && self.logging.rotation != "never"
+        {
+            return Err(crate::KbError::Config(format!(
+                "unsupported logging.rotation '{}'",
+                self.logging.rotation
+            )));
+        }
+        if self.logging.message_format != "full"
+            && self.logging.message_format != "compact"
+            && self.logging.message_format != "pretty"
+            && self.logging.message_format != "json"
+        {
+            return Err(crate::KbError::Config(format!(
+                "unsupported logging.message_format '{}'",
+                self.logging.message_format
+            )));
+        }
+        if self.logging.time_format != "rfc3339"
+            && self.logging.time_format != "rfc3339_millis"
+            && self.logging.time_format != "none"
+        {
+            return Err(crate::KbError::Config(format!(
+                "unsupported logging.time_format '{}'",
+                self.logging.time_format
+            )));
+        }
+        let mut endpoint_names: std::vec::Vec<std::string::String> = std::vec::Vec::new();
+        for endpoint in &self.solana.http_endpoints {
+            let validation_result = self.validate_http_endpoint(endpoint, &mut endpoint_names);
+            if let Err(error) = validation_result {
+                return Err(error);
+            }
+        }
+        for endpoint in &self.solana.ws_endpoints {
+            let validation_result = self.validate_ws_endpoint(endpoint, &mut endpoint_names);
+            if let Err(error) = validation_result {
+                return Err(error);
+            }
+        }
+        Ok(())
+    }
+
+    /// Creates the basic runtime directories required by the current configuration.
+    pub fn prepare_filesystem(&self) -> Result<(), crate::KbError> {
+        let logging_directory = self.logging.directory_path();
+        let create_logs_result = std::fs::create_dir_all(&logging_directory);
+        if let Err(error) = create_logs_result {
+            return Err(crate::KbError::Io(format!(
+                "cannot create logging directory '{}': {error}",
+                logging_directory.display()
+            )));
+        }
+        let wallets_directory = self.data.wallets_directory_path();
+        let create_wallets_result = std::fs::create_dir_all(&wallets_directory);
+        if let Err(error) = create_wallets_result {
+            return Err(crate::KbError::Io(format!(
+                "cannot create wallets directory '{}': {error}",
+                wallets_directory.display()
+            )));
+        }
+        let sqlite_path = self.data.sqlite_path_buf();
+        let sqlite_parent_option = sqlite_path.parent();
+        if let Some(sqlite_parent) = sqlite_parent_option {
+            if !sqlite_parent.as_os_str().is_empty() {
+                let create_db_parent_result = std::fs::create_dir_all(sqlite_parent);
+                if let Err(error) = create_db_parent_result {
+                    return Err(crate::KbError::Io(format!(
+                        "cannot create database parent directory '{}': {error}",
+                        sqlite_parent.display()
+                    )));
+                }
+            }
+        }
+        Ok(())
+    }
+
+    /// Returns a named HTTP endpoint by reference.
+    pub fn find_http_endpoint(
+        &self,
+        endpoint_name: &str,
+    ) -> std::option::Option<&KbHttpEndpointConfig> {
+        self.solana
+            .http_endpoints
+            .iter()
+            .find(|endpoint| endpoint.name == endpoint_name)
+    }
+
+    /// Returns a named WebSocket endpoint by reference.
+    pub fn find_ws_endpoint(
+        &self,
+        endpoint_name: &str,
+    ) -> std::option::Option<&KbWsEndpointConfig> {
+        self.solana
+            .ws_endpoints
+            .iter()
+            .find(|endpoint| endpoint.name == endpoint_name)
+    }
+
+    fn validate_http_endpoint(
+        &self,
+        endpoint: &KbHttpEndpointConfig,
+        endpoint_names: &mut std::vec::Vec<std::string::String>,
+    ) -> Result<(), crate::KbError> {
+        if endpoint.name.trim().is_empty() {
+            return Err(crate::KbError::Config(
+                "http endpoint name must not be empty".to_string(),
+            ));
+        }
+        if endpoint_names.iter().any(|name| name == &endpoint.name) {
+            return Err(crate::KbError::Config(format!(
+                "duplicated endpoint name '{}'",
+                endpoint.name
+            )));
+        }
+        if !endpoint.url.starts_with("http://") && !endpoint.url.starts_with("https://") {
+            return Err(crate::KbError::Config(format!(
+                "http endpoint '{}' must start with http:// or https://",
+                endpoint.name
+            )));
+        }
+        if endpoint.requests_per_second == 0 {
+            return Err(crate::KbError::Config(format!(
+                "http endpoint '{}' requests_per_second must be > 0",
+                endpoint.name
+            )));
+        }
+        if endpoint.burst == 0 {
+            return Err(crate::KbError::Config(format!(
+                "http endpoint '{}' burst must be > 0",
+                endpoint.name
+            )));
+        }
+        if endpoint.connect_timeout_ms == 0 {
+            return Err(crate::KbError::Config(format!(
+                "http endpoint '{}' connect_timeout_ms must be > 0",
+                endpoint.name
+            )));
+        }
+        if endpoint.request_timeout_ms == 0 {
+            return Err(crate::KbError::Config(format!(
+                "http endpoint '{}' request_timeout_ms must be > 0",
+                endpoint.name
+            )));
+        }
+        endpoint_names.push(endpoint.name.clone());
+        Ok(())
+    }
+
+    fn validate_ws_endpoint(
+        &self,
+        endpoint: &KbWsEndpointConfig,
+        endpoint_names: &mut std::vec::Vec<std::string::String>,
+    ) -> Result<(), crate::KbError> {
+        if endpoint.name.trim().is_empty() {
+            return Err(crate::KbError::Config(
+                "ws endpoint name must not be empty".to_string(),
+            ));
+        }
+        if endpoint_names.iter().any(|name| name == &endpoint.name) {
+            return Err(crate::KbError::Config(format!(
+                "duplicated endpoint name '{}'",
+                endpoint.name
+            )));
+        }
+        if !endpoint.url.starts_with("ws://") && !endpoint.url.starts_with("wss://") {
+            return Err(crate::KbError::Config(format!(
+                "ws endpoint '{}' must start with ws:// or wss://",
+                endpoint.name
+            )));
+        }
+        if endpoint.max_subscriptions == 0 {
+            return Err(crate::KbError::Config(format!(
+                "ws endpoint '{}' max_subscriptions must be > 0",
+                endpoint.name
+            )));
+        }
+        if endpoint.connect_timeout_ms == 0 {
+            return Err(crate::KbError::Config(format!(
+                "ws endpoint '{}' connect_timeout_ms must be > 0",
+                endpoint.name
+            )));
+        }
+        if endpoint.request_timeout_ms == 0 {
+            return Err(crate::KbError::Config(format!(
+                "ws endpoint '{}' request_timeout_ms must be > 0",
+                endpoint.name
+            )));
+        }
+        if endpoint.unsubscribe_timeout_ms == 0 {
+            return Err(crate::KbError::Config(format!(
+                "ws endpoint '{}' unsubscribe_timeout_ms must be > 0",
+                endpoint.name
+            )));
+        }
+        if endpoint.write_channel_capacity == 0 {
+            return Err(crate::KbError::Config(format!(
+                "ws endpoint '{}' write_channel_capacity must be > 0",
+                endpoint.name
+            )));
+        }
+        if endpoint.event_channel_capacity == 0 {
+            return Err(crate::KbError::Config(format!(
+                "ws endpoint '{}' event_channel_capacity must be > 0",
+                endpoint.name
+            )));
+        }
+        endpoint_names.push(endpoint.name.clone());
+        Ok(())
+    }
+}
+
+fn kb_workspace_root_dir() -> std::path::PathBuf {
+    let manifest_dir = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    match manifest_dir.parent() {
+        Some(parent) => parent.to_path_buf(),
+        None => manifest_dir,
+    }
+}
+
+fn kb_resolve_workspace_relative_path<P: AsRef<std::path::Path>>(path: P) -> std::path::PathBuf {
+    let input_path = std::path::PathBuf::from(path.as_ref());
+    if input_path.is_absolute() {
+        return input_path;
+    }
+    kb_workspace_root_dir().join(input_path)
+}
+
+impl KbLoggingConfig {
+    /// Returns the resolved logging directory path.
+    pub fn directory_path(&self) -> std::path::PathBuf {
+        kb_resolve_workspace_relative_path(&self.directory)
+    }
+}
+
+impl KbDataConfig {
+    /// Returns the resolved SQLite database path.
+    pub fn sqlite_path_buf(&self) -> std::path::PathBuf {
+        kb_resolve_workspace_relative_path(&self.sqlite_path)
+    }
+
+    /// Returns the resolved wallets directory path.
+    pub fn wallets_directory_path(&self) -> std::path::PathBuf {
+        kb_resolve_workspace_relative_path(&self.wallets_directory)
+    }
+}