557 lines
21 KiB
Rust
557 lines
21 KiB
Rust
// 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 Config {
|
|
/// Application-level metadata and global behavior.
|
|
pub app: AppConfig,
|
|
/// Tracing and log output configuration.
|
|
pub logging: LoggingConfig,
|
|
/// Data directory configuration.
|
|
pub data: DataConfig,
|
|
/// Solana endpoint configuration.
|
|
pub solana: SolanaConfig,
|
|
/// Database configuration.
|
|
pub database: DatabaseConfig,
|
|
}
|
|
|
|
impl Config {
|
|
/// Returns the default path of the JSON configuration file.
|
|
pub fn default_path() -> std::path::PathBuf {
|
|
return 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::Error> {
|
|
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::Error::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::Error::Json(format!(
|
|
"cannot parse configuration file '{}': {error}",
|
|
path_ref.display()
|
|
)));
|
|
},
|
|
};
|
|
let validation_result = config.validate();
|
|
match validation_result {
|
|
Ok(()) => return Ok(config),
|
|
Err(error) => return Err(error),
|
|
}
|
|
}
|
|
|
|
/// Validates the current configuration.
|
|
pub fn validate(&self) -> Result<(), crate::Error> {
|
|
if self.app.name.trim().is_empty() {
|
|
return Err(crate::Error::Config("app.name must not be empty".to_string()));
|
|
}
|
|
if self.app.environment.trim().is_empty() {
|
|
return Err(crate::Error::Config("app.environment must not be empty".to_string()));
|
|
}
|
|
if self.logging.level.trim().is_empty() {
|
|
return Err(crate::Error::Config("logging.level must not be empty".to_string()));
|
|
}
|
|
if self.logging.directory.trim().is_empty() {
|
|
return Err(crate::Error::Config("logging.directory must not be empty".to_string()));
|
|
}
|
|
if self.logging.file_prefix.trim().is_empty() {
|
|
return Err(crate::Error::Config("logging.file_prefix must not be empty".to_string()));
|
|
}
|
|
if self.data.sqlite_path.trim().is_empty() {
|
|
return Err(crate::Error::Config("data.sqlite_path must not be empty".to_string()));
|
|
}
|
|
if self.data.wallets_directory.trim().is_empty() {
|
|
return Err(crate::Error::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::Error::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::Error::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::Error::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);
|
|
}
|
|
}
|
|
return Ok(());
|
|
}
|
|
|
|
/// Creates the basic runtime directories required by the current configuration.
|
|
pub fn prepare_filesystem(&self) -> Result<(), crate::Error> {
|
|
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::Error::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::Error::Io(format!(
|
|
"cannot create wallets directory '{}': {error}",
|
|
wallets_directory.display()
|
|
)));
|
|
}
|
|
let sqlite_path = self.database.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::Error::Io(format!(
|
|
"cannot create database parent directory '{}': {error}",
|
|
sqlite_parent.display()
|
|
)));
|
|
}
|
|
}
|
|
}
|
|
return Ok(());
|
|
}
|
|
|
|
/// Finds one HTTP endpoint by its logical name.
|
|
pub fn find_http_endpoint(
|
|
&self,
|
|
endpoint_name: &str,
|
|
) -> std::option::Option<&HttpEndpointConfig> {
|
|
return self
|
|
.solana
|
|
.http_endpoints
|
|
.iter()
|
|
.find(|endpoint| return endpoint.name == endpoint_name);
|
|
}
|
|
|
|
/// Returns a named WebSocket endpoint by reference.
|
|
pub fn find_ws_endpoint(&self, endpoint_name: &str) -> std::option::Option<&WsEndpointConfig> {
|
|
return self
|
|
.solana
|
|
.ws_endpoints
|
|
.iter()
|
|
.find(|endpoint| return endpoint.name == endpoint_name);
|
|
}
|
|
|
|
fn validate_http_endpoint(
|
|
&self,
|
|
endpoint: &HttpEndpointConfig,
|
|
endpoint_names: &mut std::vec::Vec<std::string::String>,
|
|
) -> Result<(), crate::Error> {
|
|
if endpoint.name.trim().is_empty() {
|
|
return Err(crate::Error::Config("http endpoint name must not be empty".to_string()));
|
|
}
|
|
if endpoint_names.iter().any(|name| return name == &endpoint.name) {
|
|
return Err(crate::Error::Config(format!(
|
|
"duplicated endpoint name '{}'",
|
|
endpoint.name
|
|
)));
|
|
}
|
|
if !endpoint.url.starts_with("http://") && !endpoint.url.starts_with("https://") {
|
|
return Err(crate::Error::Config(format!(
|
|
"http endpoint '{}' must start with http:// or https://",
|
|
endpoint.name
|
|
)));
|
|
}
|
|
if endpoint.requests_per_second == 0 {
|
|
return Err(crate::Error::Config(format!(
|
|
"http endpoint '{}' requests_per_second must be > 0",
|
|
endpoint.name
|
|
)));
|
|
}
|
|
if endpoint.burst_capacity == 0 {
|
|
return Err(crate::Error::Config(format!(
|
|
"http endpoint '{}' burst_capacity must be > 0",
|
|
endpoint.name
|
|
)));
|
|
}
|
|
if endpoint.connect_timeout_ms == 0 {
|
|
return Err(crate::Error::Config(format!(
|
|
"http endpoint '{}' connect_timeout_ms must be > 0",
|
|
endpoint.name
|
|
)));
|
|
}
|
|
if endpoint.request_timeout_ms == 0 {
|
|
return Err(crate::Error::Config(format!(
|
|
"http endpoint '{}' request_timeout_ms must be > 0",
|
|
endpoint.name
|
|
)));
|
|
}
|
|
endpoint_names.push(endpoint.name.clone());
|
|
return Ok(());
|
|
}
|
|
|
|
fn validate_ws_endpoint(
|
|
&self,
|
|
endpoint: &WsEndpointConfig,
|
|
endpoint_names: &mut std::vec::Vec<std::string::String>,
|
|
) -> Result<(), crate::Error> {
|
|
if endpoint.name.trim().is_empty() {
|
|
return Err(crate::Error::Config("ws endpoint name must not be empty".to_string()));
|
|
}
|
|
if endpoint_names.iter().any(|name| return name == &endpoint.name) {
|
|
return Err(crate::Error::Config(format!(
|
|
"duplicated endpoint name '{}'",
|
|
endpoint.name
|
|
)));
|
|
}
|
|
if !endpoint.url.starts_with("ws://") && !endpoint.url.starts_with("wss://") {
|
|
return Err(crate::Error::Config(format!(
|
|
"ws endpoint '{}' must start with ws:// or wss://",
|
|
endpoint.name
|
|
)));
|
|
}
|
|
if endpoint.max_subscriptions == 0 {
|
|
return Err(crate::Error::Config(format!(
|
|
"ws endpoint '{}' max_subscriptions must be > 0",
|
|
endpoint.name
|
|
)));
|
|
}
|
|
if endpoint.connect_timeout_ms == 0 {
|
|
return Err(crate::Error::Config(format!(
|
|
"ws endpoint '{}' connect_timeout_ms must be > 0",
|
|
endpoint.name
|
|
)));
|
|
}
|
|
if endpoint.request_timeout_ms == 0 {
|
|
return Err(crate::Error::Config(format!(
|
|
"ws endpoint '{}' request_timeout_ms must be > 0",
|
|
endpoint.name
|
|
)));
|
|
}
|
|
if endpoint.unsubscribe_timeout_ms == 0 {
|
|
return Err(crate::Error::Config(format!(
|
|
"ws endpoint '{}' unsubscribe_timeout_ms must be > 0",
|
|
endpoint.name
|
|
)));
|
|
}
|
|
if endpoint.write_channel_capacity == 0 {
|
|
return Err(crate::Error::Config(format!(
|
|
"ws endpoint '{}' write_channel_capacity must be > 0",
|
|
endpoint.name
|
|
)));
|
|
}
|
|
if endpoint.event_channel_capacity == 0 {
|
|
return Err(crate::Error::Config(format!(
|
|
"ws endpoint '{}' event_channel_capacity must be > 0",
|
|
endpoint.name
|
|
)));
|
|
}
|
|
endpoint_names.push(endpoint.name.clone());
|
|
return Ok(());
|
|
}
|
|
}
|
|
|
|
/// Generic application settings.
|
|
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
|
|
pub struct AppConfig {
|
|
/// 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 LoggingConfig {
|
|
/// 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>,
|
|
}
|
|
|
|
impl LoggingConfig {
|
|
/// Returns the resolved logging directory path.
|
|
pub fn directory_path(&self) -> std::path::PathBuf {
|
|
return resolve_workspace_relative_path(&self.directory);
|
|
}
|
|
}
|
|
|
|
/// Local data paths used by the application.
|
|
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
|
|
pub struct DataConfig {
|
|
/// 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,
|
|
}
|
|
|
|
impl DataConfig {
|
|
/// Returns the resolved SQLite database path.
|
|
pub fn sqlite_path_buf(&self) -> std::path::PathBuf {
|
|
return resolve_workspace_relative_path(&self.sqlite_path);
|
|
}
|
|
|
|
/// Returns the resolved wallets directory path.
|
|
pub fn wallets_directory_path(&self) -> std::path::PathBuf {
|
|
return resolve_workspace_relative_path(&self.wallets_directory);
|
|
}
|
|
}
|
|
|
|
/// Solana transport configuration.
|
|
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
|
|
pub struct SolanaConfig {
|
|
/// Named HTTP endpoints.
|
|
pub http_endpoints: std::vec::Vec<HttpEndpointConfig>,
|
|
/// Named WebSocket endpoints.
|
|
pub ws_endpoints: std::vec::Vec<WsEndpointConfig>,
|
|
}
|
|
|
|
/// HTTP endpoint configuration.
|
|
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
|
|
#[serde(rename_all = "camelCase")]
|
|
pub struct HttpEndpointConfig {
|
|
/// Logical endpoint name.
|
|
pub name: std::string::String,
|
|
/// Whether this endpoint is enabled.
|
|
pub enabled: bool,
|
|
/// Provider name.
|
|
pub provider: std::string::String,
|
|
/// Base HTTP URL.
|
|
pub url: std::string::String,
|
|
/// Optional environment variable name containing an API key.
|
|
pub api_key_env_var: std::option::Option<std::string::String>,
|
|
/// Allowed roles for this endpoint.
|
|
pub roles: std::vec::Vec<std::string::String>,
|
|
/// Requests per second allowed by the local limiter for general RPC methods.
|
|
pub requests_per_second: u32,
|
|
/// Maximum local burst capacity for general RPC methods.
|
|
pub burst_capacity: u32,
|
|
/// Optional requests per second override for `sendTransaction`-class methods.
|
|
pub send_transaction_requests_per_second: std::option::Option<u32>,
|
|
/// Optional burst override for `sendTransaction`-class methods.
|
|
pub send_transaction_burst_capacity: std::option::Option<u32>,
|
|
/// Optional requests per second override for heavy read methods.
|
|
pub heavy_requests_per_second: std::option::Option<u32>,
|
|
/// Optional burst override for heavy read methods.
|
|
pub heavy_burst_capacity: std::option::Option<u32>,
|
|
/// Connect timeout in milliseconds.
|
|
pub connect_timeout_ms: u64,
|
|
/// Total request timeout in milliseconds.
|
|
pub request_timeout_ms: u64,
|
|
/// Maximum idle pooled connections per host.
|
|
pub max_idle_connections_per_host: usize,
|
|
/// Automatic pause duration after an HTTP 429 response, in milliseconds.
|
|
pub pause_after_http_429_ms: std::option::Option<u64>,
|
|
/// Maximum number of concurrent in-flight HTTP requests for this endpoint.
|
|
pub max_concurrent_requests_per_endpoint: usize,
|
|
}
|
|
|
|
impl HttpEndpointConfig {
|
|
/// Returns the resolved URL, replacing an `${ENV_VAR}` placeholder when
|
|
/// `api_key_env_var` is configured.
|
|
pub fn resolved_url(&self) -> Result<std::string::String, crate::Error> {
|
|
let env_var_name_option = self.api_key_env_var.as_ref();
|
|
let env_var_name = match env_var_name_option {
|
|
Some(env_var_name) => env_var_name,
|
|
None => {
|
|
return Ok(self.url.clone());
|
|
},
|
|
};
|
|
let api_key_result = std::env::var(env_var_name);
|
|
let api_key = match api_key_result {
|
|
Ok(api_key) => api_key,
|
|
Err(error) => {
|
|
return Err(crate::Error::Config(format!(
|
|
"cannot resolve api key env var '{}' for http endpoint '{}': {}",
|
|
env_var_name, self.name, error
|
|
)));
|
|
},
|
|
};
|
|
let placeholder = format!("${{{}}}", env_var_name);
|
|
if self.url.contains(&placeholder) {
|
|
return Ok(self.url.replace(&placeholder, &api_key));
|
|
}
|
|
return Ok(self.url.clone());
|
|
}
|
|
}
|
|
|
|
/// WebSocket endpoint configuration.
|
|
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
|
|
pub struct WsEndpointConfig {
|
|
/// 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 WsEndpointConfig {
|
|
/// Returns the resolved endpoint URL.
|
|
pub fn resolved_url(&self) -> Result<std::string::String, crate::Error> {
|
|
return resolve_endpoint_url(&self.url, &self.api_key_env_var);
|
|
}
|
|
}
|
|
|
|
/// SQLite configuration.
|
|
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
|
|
#[serde(rename_all = "camelCase")]
|
|
pub struct SqliteDatabaseConfig {
|
|
/// SQLite database path.
|
|
pub path: std::string::String,
|
|
/// Whether the file should be created if missing.
|
|
pub create_if_missing: bool,
|
|
/// SQLite busy timeout in milliseconds.
|
|
pub busy_timeout_ms: u64,
|
|
/// Maximum pool connections.
|
|
pub max_connections: u32,
|
|
/// Whether the schema should be initialized automatically at startup.
|
|
pub auto_initialize_schema: bool,
|
|
/// Whether WAL journal mode should be enabled.
|
|
pub use_wal: bool,
|
|
}
|
|
|
|
impl SqliteDatabaseConfig {
|
|
/// Returns the resolved SQLite database path.
|
|
pub fn path_buf(&self) -> std::path::PathBuf {
|
|
return resolve_workspace_relative_path(&self.path);
|
|
}
|
|
}
|
|
|
|
/// Database configuration.
|
|
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
|
|
#[serde(rename_all = "camelCase")]
|
|
pub struct DatabaseConfig {
|
|
/// Whether the database layer is enabled.
|
|
pub enabled: bool,
|
|
/// Selected backend.
|
|
pub backend: crate::DatabaseBackend,
|
|
/// SQLite-specific configuration.
|
|
pub sqlite: SqliteDatabaseConfig,
|
|
}
|
|
|
|
fn workspace_root_dir() -> std::path::PathBuf {
|
|
let manifest_dir = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
|
match manifest_dir.parent() {
|
|
Some(parent) => return parent.to_path_buf(),
|
|
None => return manifest_dir,
|
|
}
|
|
}
|
|
|
|
fn 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;
|
|
}
|
|
return workspace_root_dir().join(input_path);
|
|
}
|
|
|
|
fn resolve_endpoint_url(
|
|
url: &str,
|
|
api_key_env_var: &std::option::Option<std::string::String>,
|
|
) -> Result<std::string::String, crate::Error> {
|
|
let env_var_name_option = api_key_env_var.as_deref();
|
|
let env_var_name = match env_var_name_option {
|
|
Some(env_var_name) => env_var_name,
|
|
None => {
|
|
return Ok(url.to_string());
|
|
},
|
|
};
|
|
let placeholder = format!("${{{env_var_name}}}");
|
|
if !url.contains(&placeholder) {
|
|
return Ok(url.to_string());
|
|
}
|
|
let env_value_result = std::env::var(env_var_name);
|
|
let env_value = match env_value_result {
|
|
Ok(env_value) => env_value,
|
|
Err(error) => {
|
|
return Err(crate::Error::Config(format!(
|
|
"environment variable '{}' is required to resolve endpoint url '{}': {error}",
|
|
env_var_name, url
|
|
)));
|
|
},
|
|
};
|
|
return Ok(url.replace(&placeholder, &env_value));
|
|
}
|