v0.2.1-pre.006

crates/ksp-config-lib/src/lib.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-config-lib/src/lib.rs
-// version: 11
+// version: 12
 #![warn(missing_docs)]
 #![deny(unreachable_pub)]
 #![forbid(unsafe_code)]
@@ -8,8 +8,8 @@
 //!
 //! The `0.1.3` surface owns bootstrap roots, the logical file registry, JSON/JSON Schema validation, standard-document profiles, generic composites and
 //! KSP/KSPB environment resolution through process + `.env` + fallback precedence. Resolved values preserve real/safe representations, sensitivity and
-//! provenance. The standard Logging document maps explicitly to `ksp_logging_lib::LoggingSettings`, while the management surface provides typed Logging
-//! mutation, safe environment reports, explicit privileged reveal calls and atomic JSON/`.env` persistence.
+//! provenance. Standard Logging and HTTP Transport documents map explicitly to their runtime settings contracts, while the management surface provides
+//! typed Logging mutation, safe environment reports, explicit privileged reveal calls and atomic JSON/`.env` persistence.
 
 mod bootstrap;
 mod composite;
@@ -23,6 +23,7 @@ mod persistence;
 mod profile;
 mod registry;
 mod sensitivity;
+mod transport;
 
 pub(crate) use self::constants::TRACING_TARGET;
 
@@ -144,12 +145,20 @@ pub use self::registry::DEFAULT_COMPOSITE_SCHEMA_FILENAME;
 pub use self::registry::DEFAULT_STD_LOGGING_FILENAME;
 /// Default physical filename for the standard Logging JSON Schema document.
 pub use self::registry::DEFAULT_STD_LOGGING_SCHEMA_FILENAME;
+/// Default physical filename for the standard HTTP Transport configuration document.
+pub use self::registry::DEFAULT_STD_TRANSPORT_FILENAME;
+/// Default physical filename for the standard HTTP Transport JSON Schema document.
+pub use self::registry::DEFAULT_STD_TRANSPORT_SCHEMA_FILENAME;
 /// Logical file identifier for the generic composite JSON Schema document.
 pub use self::registry::FILE_ID_SCHEMA_COMPOSITE;
 /// Logical file identifier for the standard Logging JSON Schema document.
 pub use self::registry::FILE_ID_SCHEMA_STD_LOGGING;
+/// Logical file identifier for the standard HTTP Transport JSON Schema document.
+pub use self::registry::FILE_ID_SCHEMA_STD_TRANSPORT;
 /// Logical file identifier for the standard Logging configuration document.
 pub use self::registry::FILE_ID_STD_LOGGING;
+/// Logical file identifier for the standard HTTP Transport configuration document.
+pub use self::registry::FILE_ID_STD_TRANSPORT;
 /// Sensitivity assigned to one Config value after environment resolution.
 pub use self::sensitivity::ConfigSensitivity;
 /// Provenance segment participating in one resolved Config value.
@@ -160,3 +169,5 @@ pub use self::sensitivity::REDACTED_CONFIG_VALUE;
 pub use self::sensitivity::ResolvedConfigJson;
 /// One resolved Config string preserving real/safe representations and provenance.
 pub use self::sensitivity::ResolvedConfigText;
+/// Effective standard HTTP Transport configuration mapped to `ksp_onchain_transport_lib::HttpTransportSettings`.
+pub use self::transport::ResolvedTransportConfig;

crates/ksp-config-lib/src/registry.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-config-lib/src/registry.rs
-// version: 4
+// version: 5
 
 /// Bootstrap argument used to replace a known Config filename mapping.
 pub const ARG_FILE_MAP: &str = "--filemap";
@@ -7,12 +7,20 @@ pub const ARG_FILE_MAP: &str = "--filemap";
 pub const FILE_ID_STD_LOGGING: &str = "cfg.std.logging";
 /// Logical file identifier for the standard Logging JSON Schema document.
 pub const FILE_ID_SCHEMA_STD_LOGGING: &str = "schema.std.logging";
+/// Logical file identifier for the standard HTTP Transport configuration document.
+pub const FILE_ID_STD_TRANSPORT: &str = "cfg.std.transport";
+/// Logical file identifier for the standard HTTP Transport JSON Schema document.
+pub const FILE_ID_SCHEMA_STD_TRANSPORT: &str = "schema.std.transport";
 /// Logical file identifier for the generic composite JSON Schema document.
 pub const FILE_ID_SCHEMA_COMPOSITE: &str = "schema.composite";
 /// Default physical filename for the standard Logging configuration document.
 pub const DEFAULT_STD_LOGGING_FILENAME: &str = "std.logging.json";
 /// Default physical filename for the standard Logging JSON Schema document.
 pub const DEFAULT_STD_LOGGING_SCHEMA_FILENAME: &str = "std.logging.schema.json";
+/// Default physical filename for the standard HTTP Transport configuration document.
+pub const DEFAULT_STD_TRANSPORT_FILENAME: &str = "std.transport.json";
+/// Default physical filename for the standard HTTP Transport JSON Schema document.
+pub const DEFAULT_STD_TRANSPORT_SCHEMA_FILENAME: &str = "std.transport.schema.json";
 /// Default physical filename for the generic composite JSON Schema document.
 pub const DEFAULT_COMPOSITE_SCHEMA_FILENAME: &str = "composite.schema.json";
 
@@ -135,13 +143,29 @@ impl ConfigFileRegistry {
             std::result::Result::Ok(value) => value,
             std::result::Result::Err(error) => return std::result::Result::Err(error),
         };
+        let transport = ConfigFileDescriptor::new(
+            FILE_ID_STD_TRANSPORT,
+            ConfigFileKind::Config,
+            DEFAULT_STD_TRANSPORT_FILENAME,
+            std::option::Option::Some(FILE_ID_SCHEMA_STD_TRANSPORT),
+        );
+        let transport = match transport {
+            std::result::Result::Ok(value) => value,
+            std::result::Result::Err(error) => return std::result::Result::Err(error),
+        };
+        let transport_schema =
+            ConfigFileDescriptor::new(FILE_ID_SCHEMA_STD_TRANSPORT, ConfigFileKind::Schema, DEFAULT_STD_TRANSPORT_SCHEMA_FILENAME, std::option::Option::None);
+        let transport_schema = match transport_schema {
+            std::result::Result::Ok(value) => value,
+            std::result::Result::Err(error) => return std::result::Result::Err(error),
+        };
         let composite_schema =
             ConfigFileDescriptor::new(FILE_ID_SCHEMA_COMPOSITE, ConfigFileKind::Schema, DEFAULT_COMPOSITE_SCHEMA_FILENAME, std::option::Option::None);
         let composite_schema = match composite_schema {
             std::result::Result::Ok(value) => value,
             std::result::Result::Err(error) => return std::result::Result::Err(error),
         };
-        return build_registry([logging, logging_schema, composite_schema]);
+        return build_registry([logging, logging_schema, transport, transport_schema, composite_schema]);
     }
 
     /// Creates the default registry and applies repeatable `--filemap=<file_id>=<filename>` overrides from raw process arguments.

crates/ksp-config-lib/src/transport.rs

@@ -0,0 +1,316 @@
+// file: crates/ksp-config-lib/src/transport.rs
+// version: 1
+
+/// Effective standard HTTP Transport configuration resolved from Config and mapped to the Transport runtime contract.
+#[derive(Clone, Eq, PartialEq)]
+pub struct ResolvedTransportConfig {
+    file_id: crate::ConfigFileId,
+    source_path: std::path::PathBuf,
+    profile_id: String,
+    selection_source: crate::ConfigProfileSelectionSource,
+    effective: crate::ResolvedConfigJson,
+    settings: ksp_onchain_transport_lib::HttpTransportSettings,
+}
+
+impl ResolvedTransportConfig {
+    /// Returns the logical Config document identifier used by this runtime configuration.
+    #[must_use]
+    pub const fn file_id(&self) -> &crate::ConfigFileId {
+        return &self.file_id;
+    }
+
+    /// Returns the physical source Config document path.
+    #[must_use]
+    pub fn source_path(&self) -> &std::path::Path {
+        return self.source_path.as_path();
+    }
+
+    /// Returns the selected standard Transport profile identifier.
+    #[must_use]
+    pub fn profile_id(&self) -> &str {
+        return self.profile_id.as_str();
+    }
+
+    /// Returns the source that selected the standard Transport profile.
+    #[must_use]
+    pub const fn selection_source(&self) -> crate::ConfigProfileSelectionSource {
+        return self.selection_source;
+    }
+
+    /// Returns the detailed environment-resolved effective Config view.
+    ///
+    /// The real tree is available to legitimate runtime consumers. The safe tree redacts values originating from `KSP_SECRET_*` or `KSPB_SECRET_*`
+    /// placeholders and is the only representation used by this type's [`std::fmt::Debug`] implementation.
+    #[must_use]
+    pub const fn effective(&self) -> &crate::ResolvedConfigJson {
+        return &self.effective;
+    }
+
+    /// Returns the validated runtime HTTP Transport settings.
+    #[must_use]
+    pub const fn settings(&self) -> &ksp_onchain_transport_lib::HttpTransportSettings {
+        return &self.settings;
+    }
+
+    /// Consumes this resolved Config and returns the mapped runtime HTTP Transport settings.
+    #[must_use]
+    pub fn into_settings(self) -> ksp_onchain_transport_lib::HttpTransportSettings {
+        return self.settings;
+    }
+}
+
+impl std::fmt::Debug for ResolvedTransportConfig {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        return formatter
+            .debug_struct("ResolvedTransportConfig")
+            .field("file_id", &self.file_id)
+            .field("source_path", &self.source_path)
+            .field("profile_id", &self.profile_id)
+            .field("selection_source", &self.selection_source)
+            .field("effective", &self.effective)
+            .finish_non_exhaustive();
+    }
+}
+
+impl crate::ConfigDocumentEngine {
+    /// Loads the standard HTTP Transport document, selects a profile, resolves environment placeholders and maps it to Transport runtime settings.
+    ///
+    /// `requested_profile = None` uses the document `default_profile`; `Some(profile_id)` requests an explicit profile. Secret endpoint URLs are allowed
+    /// because the Transport URL wrapper owns runtime redaction. Invalid environment-resolved values are reported as
+    /// [`crate::ERROR_CODE_EFFECTIVE_CONFIG_INVALID`] without copying endpoint URL values into ordinary error context.
+    pub fn load_resolved_transport_config(
+        &self,
+        requested_profile: std::option::Option<&str>,
+        environment: &crate::ConfigEnvironment,
+    ) -> ksp_core_lib::Result<ResolvedTransportConfig> {
+        let file_id = crate::ConfigFileId::new(crate::FILE_ID_STD_TRANSPORT);
+        let file_id = match file_id {
+            std::result::Result::Ok(value) => value,
+            std::result::Result::Err(error) => return std::result::Result::Err(error),
+        };
+        let profile = self.load_resolved_profile(&file_id, requested_profile);
+        let profile = match profile {
+            std::result::Result::Ok(value) => value,
+            std::result::Result::Err(error) => return std::result::Result::Err(error),
+        };
+        return resolve_transport_profile(&profile, environment);
+    }
+}
+
+#[derive(serde::Deserialize)]
+#[serde(deny_unknown_fields)]
+struct EffectiveTransportSource {
+    format_version: u32,
+    profile_id: String,
+    retry: EffectiveRetrySource,
+    endpoints: std::vec::Vec<EffectiveEndpointSource>,
+}
+
+#[derive(serde::Deserialize)]
+#[serde(deny_unknown_fields)]
+struct EffectiveRetrySource {
+    max_retries: u32,
+    initial_backoff_ms: u64,
+    max_backoff_ms: u64,
+}
+
+#[derive(serde::Deserialize)]
+#[serde(deny_unknown_fields)]
+struct EffectiveEndpointSource {
+    name: String,
+    enabled: bool,
+    provider: String,
+    cluster: String,
+    url: String,
+    connect_timeout_ms: u64,
+    request_timeout_ms: u64,
+    max_idle_connections_per_host: std::option::Option<usize>,
+    roles: std::vec::Vec<EffectiveRoleSource>,
+}
+
+#[derive(serde::Deserialize)]
+#[serde(deny_unknown_fields)]
+struct EffectiveRoleSource {
+    role: String,
+    enabled: bool,
+    request_kinds: std::vec::Vec<String>,
+    priority: u32,
+    limits: EffectiveLimitsSource,
+}
+
+#[derive(serde::Deserialize)]
+#[serde(deny_unknown_fields)]
+struct EffectiveLimitsSource {
+    requests_per_second: std::option::Option<u32>,
+    burst_capacity: std::option::Option<u32>,
+    max_concurrent_requests: std::option::Option<u32>,
+    pause_after_rate_limit_ms: std::option::Option<u64>,
+}
+
+fn resolve_transport_profile(profile: &crate::ResolvedConfigProfile, environment: &crate::ConfigEnvironment) -> ksp_core_lib::Result<ResolvedTransportConfig> {
+    let effective = profile.resolve_effective_environment_detailed(environment);
+    let effective = match effective {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let source = serde_json::from_value::<EffectiveTransportSource>(effective.value().clone());
+    let source = match source {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => {
+            return std::result::Result::Err(
+                effective_error(profile, "effective Transport Config cannot be decoded into the runtime adapter contract").with_source(error),
+            );
+        },
+    };
+    if source.format_version != 1 {
+        return std::result::Result::Err(effective_error(profile, "effective Transport format_version is unsupported"));
+    }
+    if source.profile_id != profile.profile_id() {
+        return std::result::Result::Err(effective_error(profile, "effective Transport profile_id does not match the selected profile"));
+    }
+    let retry = ksp_onchain_transport_lib::HttpRetrySettings::new(
+        source.retry.max_retries,
+        std::time::Duration::from_millis(source.retry.initial_backoff_ms),
+        std::time::Duration::from_millis(source.retry.max_backoff_ms),
+    );
+    let endpoints = map_endpoints(source.endpoints, profile);
+    let endpoints = match endpoints {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) => return std::result::Result::Err(error),
+    };
+    let settings = ksp_onchain_transport_lib::HttpTransportSettings::new(endpoints, retry);
+    let validation = settings.validate();
+    if let std::result::Result::Err(error) = validation {
+        return std::result::Result::Err(transport_contract_error(profile, "effective Transport settings fail the Transport runtime contract", &error));
+    }
+    ksp_logging_lib::debug!(
+        target: crate::TRACING_TARGET,
+        profile_id = profile.profile_id(),
+        endpoint_count = settings.endpoints().len(),
+        "mapped standard Transport Config to runtime settings"
+    );
+    return std::result::Result::Ok(ResolvedTransportConfig {
+        file_id: profile.file_id().clone(),
+        source_path: profile.path().to_path_buf(),
+        profile_id: profile.profile_id().to_owned(),
+        selection_source: profile.selection_source(),
+        effective,
+        settings,
+    });
+}
+
+fn map_endpoints(
+    sources: std::vec::Vec<EffectiveEndpointSource>,
+    profile: &crate::ResolvedConfigProfile,
+) -> ksp_core_lib::Result<std::vec::Vec<ksp_onchain_transport_lib::HttpEndpointSettings>> {
+    let mut endpoints = std::vec::Vec::<ksp_onchain_transport_lib::HttpEndpointSettings>::with_capacity(sources.len());
+    for source in sources {
+        let endpoint_name = source.name.clone();
+        let url = ksp_onchain_transport_lib::HttpEndpointUrl::parse(source.url);
+        let url = match url {
+            std::result::Result::Ok(value) => value,
+            std::result::Result::Err(error) => {
+                return std::result::Result::Err(
+                    transport_contract_error(profile, "effective endpoint URL is invalid", &error).with_context("endpoint_name", endpoint_name),
+                );
+            },
+        };
+        let roles = map_roles(source.roles, profile, endpoint_name.as_str());
+        let roles = match roles {
+            std::result::Result::Ok(value) => value,
+            std::result::Result::Err(error) => return std::result::Result::Err(error),
+        };
+        endpoints.push(ksp_onchain_transport_lib::HttpEndpointSettings::new(
+            source.name,
+            source.enabled,
+            ksp_onchain_transport_lib::HttpProviderName::new(source.provider),
+            ksp_onchain_transport_lib::HttpClusterName::new(source.cluster),
+            url,
+            std::time::Duration::from_millis(source.connect_timeout_ms),
+            std::time::Duration::from_millis(source.request_timeout_ms),
+            source.max_idle_connections_per_host,
+            roles,
+        ));
+    }
+    return std::result::Result::Ok(endpoints);
+}
+
+fn map_roles(
+    sources: std::vec::Vec<EffectiveRoleSource>,
+    profile: &crate::ResolvedConfigProfile,
+    endpoint_name: &str,
+) -> ksp_core_lib::Result<std::vec::Vec<ksp_onchain_transport_lib::HttpEndpointRoleSettings>> {
+    let mut roles = std::vec::Vec::<ksp_onchain_transport_lib::HttpEndpointRoleSettings>::with_capacity(sources.len());
+    for source in sources {
+        let requests_per_second = map_non_zero(source.limits.requests_per_second, profile, "limits.requests_per_second", endpoint_name);
+        let requests_per_second = match requests_per_second {
+            std::result::Result::Ok(value) => value,
+            std::result::Result::Err(error) => return std::result::Result::Err(error),
+        };
+        let burst_capacity = map_non_zero(source.limits.burst_capacity, profile, "limits.burst_capacity", endpoint_name);
+        let burst_capacity = match burst_capacity {
+            std::result::Result::Ok(value) => value,
+            std::result::Result::Err(error) => return std::result::Result::Err(error),
+        };
+        let max_concurrent_requests = map_non_zero(source.limits.max_concurrent_requests, profile, "limits.max_concurrent_requests", endpoint_name);
+        let max_concurrent_requests = match max_concurrent_requests {
+            std::result::Result::Ok(value) => value,
+            std::result::Result::Err(error) => return std::result::Result::Err(error),
+        };
+        let pause_after_rate_limit = match source.limits.pause_after_rate_limit_ms {
+            std::option::Option::Some(value) => std::option::Option::Some(std::time::Duration::from_millis(value)),
+            std::option::Option::None => std::option::Option::None,
+        };
+        let limits = ksp_onchain_transport_lib::HttpRoleLimits::new(requests_per_second, burst_capacity, max_concurrent_requests, pause_after_rate_limit);
+        let mut request_kinds = std::vec::Vec::<ksp_onchain_transport_lib::HttpRequestKind>::with_capacity(source.request_kinds.len());
+        for request_kind in source.request_kinds {
+            request_kinds.push(ksp_onchain_transport_lib::HttpRequestKind::new(request_kind));
+        }
+        roles.push(ksp_onchain_transport_lib::HttpEndpointRoleSettings::new(
+            ksp_onchain_transport_lib::HttpRoleName::new(source.role),
+            source.enabled,
+            request_kinds,
+            source.priority,
+            limits,
+        ));
+    }
+    return std::result::Result::Ok(roles);
+}
+
+fn map_non_zero(
+    value: std::option::Option<u32>,
+    profile: &crate::ResolvedConfigProfile,
+    field: &'static str,
+    endpoint_name: &str,
+) -> ksp_core_lib::Result<std::option::Option<std::num::NonZeroU32>> {
+    let value = match value {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return std::result::Result::Ok(std::option::Option::None),
+    };
+    let non_zero = std::num::NonZeroU32::new(value);
+    return match non_zero {
+        std::option::Option::Some(value) => std::result::Result::Ok(std::option::Option::Some(value)),
+        std::option::Option::None => std::result::Result::Err(
+            effective_error(profile, "effective Transport role limit must be greater than zero")
+                .with_context("field", field)
+                .with_context("endpoint_name", endpoint_name),
+        ),
+    };
+}
+
+fn transport_contract_error(profile: &crate::ResolvedConfigProfile, reason: &'static str, transport_error: &ksp_core_lib::Error) -> ksp_core_lib::Error {
+    return effective_error(profile, reason)
+        .with_context("transport_error_domain", transport_error.code().domain())
+        .with_context("transport_error_code", transport_error.code().code());
+}
+
+fn effective_error(profile: &crate::ResolvedConfigProfile, reason: &'static str) -> ksp_core_lib::Error {
+    return ksp_core_lib::Error::new(crate::ERROR_CODE_EFFECTIVE_CONFIG_INVALID, "effective Config cannot be mapped to the requested runtime contract")
+        .with_context("file_id", profile.file_id().as_str())
+        .with_context("profile_id", profile.profile_id())
+        .with_context("reason", reason);
+}
+
+#[cfg(test)]
+#[path = "../unit_tests/transport.rs"]
+mod tests;