refactor(config): compile-time env var mappings eliminate runtime ambiguity

Replace dynamic path inference with derive macro that generates
explicit mappings at compile time. Field attribute #[config_env(leaf)]
gives users control over nested vs value type handling without
hardcoding type names in the macro.

Author: hubcio

.github/config/components.yml

@@ -37,10 +37,17 @@ components:
     paths:
       - "core/sdk/**"
 
+  rust-internals:
+    depends_on:
+      - "rust-workspace"
+    paths:
+      - "core/internals/**"
+      - "core/internals_derive/**"
+
   rust-common:
     depends_on:
-      - "rust-workspace" # Common is affected by workspace changes
-      - "ci-infrastructure" # CI changes trigger full regression
+      - "rust-workspace"
+      - "rust-internals"
     paths:
       - "core/common/**"
 
@@ -51,28 +58,52 @@ components:
     paths:
       - "core/binary_protocol/**"
 
+  rust-clock:
+    depends_on:
+      - "rust-workspace"
+    paths:
+      - "core/clock/**"
+
+  rust-journal:
+    depends_on:
+      - "rust-workspace"
+    paths:
+      - "core/journal/**"
+
+  rust-partitions:
+    depends_on:
+      - "rust-workspace"
+    paths:
+      - "core/partitions/**"
+
   rust-server:
     depends_on:
-      - "rust-workspace" # Server is affected by workspace changes
-      - "ci-infrastructure" # CI changes trigger full regression
+      - "rust-workspace"
+      - "rust-internals"
       - "rust-common"
       - "rust-binary-protocol"
+      - "rust-journal"
+      - "rust-partitions"
     paths:
       - "core/server/**"
 
   rust-cluster:
     depends_on:
-      - "rust-workspace" # Cluster is affected by workspace changes
-      - "ci-infrastructure" # CI changes trigger full regression
+      - "rust-workspace"
+      - "rust-clock"
     paths:
-      - "core/consensus/"
-      - "core/metadata/"
-      - "core/message_bus/"
+      - "core/consensus/**"
+      - "core/metadata/**"
+      - "core/message_bus/**"
 
   # Main Rust workspace testing
   rust:
     depends_on:
       - "rust-workspace"
+      - "rust-internals"
+      - "rust-clock"
+      - "rust-journal"
+      - "rust-partitions"
       - "rust-sdk"
       - "rust-common"
       - "rust-binary-protocol"
@@ -84,7 +115,7 @@ components:
       - "rust-connectors"
       - "rust-mcp"
       - "rust-integration"
-      - "ci-infrastructure" # CI changes trigger full regression
+      - "ci-infrastructure"
     paths:
       - "Dockerfile*"
       - "!foreign/**" # Exclude foreign SDKs
@@ -121,13 +152,15 @@ components:
   rust-connectors:
     depends_on:
       - "rust-sdk"
+      - "rust-internals"
     paths:
       - "core/connectors/**"
 
   # MCP AI component
   rust-mcp:
     depends_on:
       - "rust-sdk"
+      - "rust-internals"
     paths:
       - "core/ai/mcp/**"
 
@@ -138,6 +171,7 @@ components:
       - "rust-common"
       - "rust-binary-protocol"
       - "rust-server"
+      - "rust-internals"
     paths:
       - "core/integration/**"
 

Cargo.lock

@@ -41,6 +41,8 @@ members = [
     "core/connectors/sources/random_source",
     "core/consensus",
     "core/integration",
+    "core/internals",
+    "core/internals_derive",
     "core/journal",
     "core/message_bus",
     "core/metadata",
@@ -114,6 +116,7 @@ console-subscriber = "0.5.0"
 crossbeam = "0.8.4"
 cyper = { version = "0.7.1", features = ["rustls"], default-features = false }
 cyper-axum = { version = "0.7.1" }
+darling = "0.20"
 dashmap = "6.1.0"
 derive-new = "0.7.0"
 derive_builder = "0.20.2"
@@ -140,6 +143,8 @@ iggy_binary_protocol = { path = "core/binary_protocol", version = "0.8.1-edge.1"
 iggy_common = { path = "core/common", version = "0.8.1-edge.1" }
 iggy_connector_sdk = { path = "core/connectors/sdk", version = "0.1.1-edge.1" }
 integration = { path = "core/integration" }
+internals = { path = "core/internals", version = "0.1.0" }
+internals_derive = { path = "core/internals_derive", version = "0.1.0" }
 keyring = { version = "3.6.3", features = ["sync-secret-service", "vendored"] }
 lazy_static = "1.5.0"
 left-right = "0.11"
@@ -172,7 +177,9 @@ parquet = "=55.2.0"
 passterm = "=2.0.1"
 postcard = { version = "1.1.3", features = ["alloc"] }
 predicates = "3.1.3"
+proc-macro2 = "1"
 quinn = "0.11.9"
+quote = "1"
 rand = "0.9.2"
 rand_xoshiro = "0.7.0"
 regex = "1.12.2"
@@ -199,6 +206,7 @@ simd-json = { version = "0.17.0", features = ["serde_impl"] }
 slab = "0.4.1"
 strum = { version = "0.27.2", features = ["derive"] }
 strum_macros = "0.27.2"
+syn = { version = "2", features = ["full", "extra-traits"] }
 sysinfo = "0.37.2"
 tempfile = "3.24.0"
 test-case = "3.3.1"

Cargo.toml

@@ -417,6 +417,8 @@ inotify-sys: 0.1.5, "ISC",
 inout: 0.1.4, "Apache-2.0 OR MIT",
 integer-encoding: 3.0.4, "MIT",
 integration: 0.0.1, "Apache-2.0",
+internals: 0.1.0, "Apache-2.0",
+internals_derive: 0.1.0, "Apache-2.0",
 inventory: 0.3.21, "Apache-2.0 OR MIT",
 io-uring: 0.7.11, "Apache-2.0 OR MIT",
 io_uring_buf_ring: 0.2.3, "MIT",

DEPENDENCIES.md

@@ -34,7 +34,8 @@ dotenvy = { workspace = true }
 figlet-rs = { workspace = true }
 figment = { workspace = true }
 iggy = { workspace = true }
-iggy_common = { workspace = true }
+internals = { workspace = true }
+internals_derive = { workspace = true }
 opentelemetry = { workspace = true }
 opentelemetry-appender-tracing = { workspace = true }
 opentelemetry-otlp = { workspace = true }

core/ai/mcp/Cargo.toml

@@ -24,64 +24,69 @@ use figment::{
     value::Dict,
 };
 use iggy::prelude::{DEFAULT_ROOT_PASSWORD, DEFAULT_ROOT_USERNAME};
-use iggy_common::{CustomEnvProvider, FileConfigProvider};
+use internals::{FileConfigProvider, TypedEnvProvider};
+use internals_derive::ConfigEnv;
 use serde::{Deserialize, Serialize};
 use std::fmt::{Display as FmtDisplay, Formatter};
 use std::str::FromStr;
 use strum::Display;
 use tower_http::cors::{AllowOrigin, CorsLayer};
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, ConfigEnv)]
+#[config_env(prefix = "IGGY_MCP_")]
 #[serde(default)]
 pub struct McpServerConfig {
     pub http: HttpConfig,
     pub iggy: IggyConfig,
     pub permissions: PermissionsConfig,
+    #[config_env(leaf)]
     pub transport: McpTransport,
     pub telemetry: TelemetryConfig,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
+#[derive(Debug, Clone, Serialize, Deserialize, ConfigEnv)]
 pub struct IggyConfig {
     pub address: String,
     pub username: String,
+    #[config_env(secret)]
     pub password: String,
+    #[config_env(secret)]
     pub token: String,
     pub consumer: String,
     pub tls: IggyTlsConfig,
 }
 
-#[derive(Debug, Default, Clone, Serialize, Deserialize)]
+#[derive(Debug, Default, Clone, Serialize, Deserialize, ConfigEnv)]
 pub struct IggyTlsConfig {
     pub enabled: bool,
     pub ca_file: String,
     pub domain: Option<String>,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, ConfigEnv)]
 pub struct PermissionsConfig {
     pub create: bool,
     pub read: bool,
     pub update: bool,
     pub delete: bool,
 }
 
-#[derive(Debug, Clone, Deserialize, Serialize)]
+#[derive(Debug, Clone, Deserialize, Serialize, ConfigEnv)]
 pub struct HttpConfig {
     pub address: String,
     pub path: String,
     pub cors: HttpCorsConfig,
     pub tls: HttpTlsConfig,
 }
 
-#[derive(Debug, Default, Deserialize, Serialize, Clone)]
+#[derive(Debug, Default, Deserialize, Serialize, Clone, ConfigEnv)]
 pub struct HttpTlsConfig {
     pub enabled: bool,
     pub cert_file: String,
     pub key_file: String,
 }
 
-#[derive(Debug, Default, Deserialize, Serialize, Clone)]
+#[derive(Debug, Default, Deserialize, Serialize, Clone, ConfigEnv)]
 pub struct HttpCorsConfig {
     pub enabled: bool,
     pub allowed_methods: Vec<String>,
@@ -103,7 +108,7 @@ pub enum McpTransport {
     Stdio,
 }
 
-#[derive(Debug, Deserialize, Serialize, Clone)]
+#[derive(Debug, Deserialize, Serialize, Clone, ConfigEnv)]
 pub struct TelemetryConfig {
     pub enabled: bool,
     pub service_name: String,
@@ -132,8 +137,9 @@ impl FmtDisplay for TelemetryConfig {
     }
 }
 
-#[derive(Debug, Deserialize, Serialize, Clone)]
+#[derive(Debug, Deserialize, Serialize, Clone, ConfigEnv)]
 pub struct TelemetryLogsConfig {
+    #[config_env(leaf)]
     pub transport: TelemetryTransport,
     pub endpoint: String,
 }
@@ -157,8 +163,9 @@ impl FmtDisplay for TelemetryLogsConfig {
     }
 }
 
-#[derive(Debug, Deserialize, Serialize, Clone)]
+#[derive(Debug, Deserialize, Serialize, Clone, ConfigEnv)]
 pub struct TelemetryTracesConfig {
+    #[config_env(leaf)]
     pub transport: TelemetryTransport,
     pub endpoint: String,
 }
@@ -394,15 +401,17 @@ impl McpServerConfig {
     }
 }
 
+const SECRET_KEYS: [&str; 2] = ["IGGY_MCP_IGGY_PASSWORD", "IGGY_MCP_IGGY_TOKEN"];
+
 #[derive(Debug, Clone)]
 pub struct McpServerEnvProvider {
-    provider: CustomEnvProvider<McpServerConfig>,
+    provider: TypedEnvProvider<McpServerConfig>,
 }
 
 impl Default for McpServerEnvProvider {
     fn default() -> Self {
         Self {
-            provider: CustomEnvProvider::new("IGGY_MCP_", &[]),
+            provider: TypedEnvProvider::new("IGGY_MCP_", &SECRET_KEYS),
         }
     }
 }
@@ -413,8 +422,6 @@ impl Provider for McpServerEnvProvider {
     }
 
     fn data(&self) -> Result<figment::value::Map<Profile, Dict>, figment::Error> {
-        self.provider.deserialize().map_err(|_| {
-            figment::Error::from("Cannot deserialize environment variables for MCP config")
-        })
+        self.provider.data()
     }
 }