216 lines
13 KiB
Rust
216 lines
13 KiB
Rust
// file: crates/ksp-config-lib/src/lib.rs
|
|
// version: 17
|
|
|
|
#![warn(missing_docs)]
|
|
#![deny(unreachable_pub)]
|
|
#![forbid(unsafe_code)]
|
|
|
|
//! KSP-owned application configuration facade.
|
|
//!
|
|
//! 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. Standard Logging, HTTP Transport and Wallet documents map explicitly to their runtime consumer 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;
|
|
mod constants;
|
|
mod document;
|
|
mod environment;
|
|
mod error;
|
|
mod logging;
|
|
mod management;
|
|
mod packaging;
|
|
mod persistence;
|
|
mod profile;
|
|
mod registry;
|
|
mod sensitivity;
|
|
mod transport;
|
|
mod wallet;
|
|
|
|
/// Bootstrap argument used to replace the configuration document root.
|
|
pub use self::bootstrap::ARG_CFG_PATH;
|
|
/// Bootstrap argument used to replace the schema root.
|
|
pub use self::bootstrap::ARG_SCHEMA_PATH;
|
|
/// Non-recursive bootstrap options required before Config can resolve any managed document.
|
|
pub use self::bootstrap::ConfigBootstrapOptions;
|
|
/// Default root containing KSP runtime configuration documents.
|
|
pub use self::bootstrap::DEFAULT_CFG_PATH;
|
|
/// Default root containing KSP JSON schemas.
|
|
pub use self::bootstrap::DEFAULT_SCHEMA_PATH;
|
|
/// One resolved document component selected by a composite profile.
|
|
pub use self::composite::ResolvedCompositeComponent;
|
|
/// Validated composite document resolved to one profile and its referenced standard documents.
|
|
pub use self::composite::ResolvedConfigComposite;
|
|
/// Generic JSON/JSON Schema engine owned by Config.
|
|
pub use self::document::ConfigDocumentEngine;
|
|
/// A Config-managed JSON document after syntax, schema and current semantic validation.
|
|
pub use self::document::ConfigJsonDocument;
|
|
/// Config-owned snapshot of KSP/KSPB process environment values and the local `.env` file.
|
|
pub use self::environment::ConfigEnvironment;
|
|
/// Source that supplied one resolved Config environment variable.
|
|
pub use self::environment::ConfigEnvironmentSource;
|
|
/// One resolved Config environment variable with real/safe values, sensitivity and its winning source.
|
|
pub use self::environment::ConfigEnvironmentValue;
|
|
/// Versioned environment contract template expected at the repository/runtime root.
|
|
pub use self::environment::DEFAULT_DOTENV_EXAMPLE_PATH;
|
|
/// Default local environment file read by Config from the process launch directory.
|
|
pub use self::environment::DEFAULT_DOTENV_PATH;
|
|
/// Error code used when a Config bootstrap argument is missing its value.
|
|
pub use self::error::ERROR_CODE_BOOTSTRAP_ARGUMENT_MISSING_VALUE;
|
|
/// Error code used when a Config bootstrap path is empty, inaccessible, or resolves to an existing non-directory path.
|
|
pub use self::error::ERROR_CODE_BOOTSTRAP_INVALID_PATH;
|
|
/// Error code used when a composite document contains an invalid or unsupported document reference.
|
|
pub use self::error::ERROR_CODE_COMPOSITE_REFERENCE_INVALID;
|
|
/// Error code used when a schema-valid Config document violates KSP semantic invariants.
|
|
pub use self::error::ERROR_CODE_DOCUMENT_SEMANTIC_INVALID;
|
|
/// Error code used when the local `.env` file cannot be read for a reason other than absence.
|
|
pub use self::error::ERROR_CODE_DOTENV_FILE_READ_FAILED;
|
|
/// Error code used when the local `.env` file contains invalid syntax.
|
|
pub use self::error::ERROR_CODE_DOTENV_SYNTAX_INVALID;
|
|
/// Error code used when an environment-resolved Config cannot map safely to a runtime consumer contract.
|
|
pub use self::error::ERROR_CODE_EFFECTIVE_CONFIG_INVALID;
|
|
/// Error code used when a Config environment placeholder is malformed.
|
|
pub use self::error::ERROR_CODE_ENVIRONMENT_PLACEHOLDER_INVALID;
|
|
/// Error code used when a supported Config environment variable has a non-UTF-8 process value.
|
|
pub use self::error::ERROR_CODE_ENVIRONMENT_VALUE_INVALID;
|
|
/// Error code used when a Config environment variable name is invalid or outside KSP/KSPB namespaces.
|
|
pub use self::error::ERROR_CODE_ENVIRONMENT_VARIABLE_INVALID;
|
|
/// Error code used when a referenced Config environment variable is absent and has no fallback.
|
|
pub use self::error::ERROR_CODE_ENVIRONMENT_VARIABLE_MISSING;
|
|
/// Error code used when the same logical Config file identifier is registered more than once.
|
|
pub use self::error::ERROR_CODE_FILE_ID_DUPLICATE;
|
|
/// Error code used when a logical Config file identifier is malformed.
|
|
pub use self::error::ERROR_CODE_FILE_ID_INVALID;
|
|
/// Error code used when a requested logical Config file identifier is not registered.
|
|
pub use self::error::ERROR_CODE_FILE_ID_UNKNOWN;
|
|
/// Error code used when a Config filename mapping or descriptor relation is invalid.
|
|
pub use self::error::ERROR_CODE_FILE_MAPPING_INVALID;
|
|
/// Error code used when a Config-managed JSON document or schema cannot be read.
|
|
pub use self::error::ERROR_CODE_JSON_FILE_READ_FAILED;
|
|
/// Error code used when a Config-managed file contains invalid JSON syntax.
|
|
pub use self::error::ERROR_CODE_JSON_SYNTAX_INVALID;
|
|
/// Error code used when an explicit management operation is unsupported or targets the wrong managed resource kind.
|
|
pub use self::error::ERROR_CODE_MANAGEMENT_OPERATION_INVALID;
|
|
/// Error code used when packaged desktop resources cannot initialize the shared writable KSP runtime layout.
|
|
pub use self::error::ERROR_CODE_PACKAGED_RUNTIME_PREPARATION_FAILED;
|
|
/// Error code used when atomic managed Config or `.env` persistence fails before commit.
|
|
pub use self::error::ERROR_CODE_PERSISTENCE_WRITE_FAILED;
|
|
/// Error code used when an explicitly requested Config profile does not exist.
|
|
pub use self::error::ERROR_CODE_PROFILE_NOT_FOUND;
|
|
/// Error code used when a JSON Schema document is itself invalid.
|
|
pub use self::error::ERROR_CODE_SCHEMA_INVALID;
|
|
/// Error code used when a Config document fails its registered JSON Schema validation.
|
|
pub use self::error::ERROR_CODE_SCHEMA_VALIDATION_FAILED;
|
|
/// Effective standard Logging configuration mapped to `ksp_logging_lib::LoggingSettings`.
|
|
pub use self::logging::ResolvedLoggingConfig;
|
|
/// Result of one validated Config document persistence operation.
|
|
pub use self::management::ConfigDocumentChangeReport;
|
|
/// Result of one persistent `.env` mutation.
|
|
pub use self::management::ConfigEnvironmentChangeReport;
|
|
/// Safe desired/effective/shadow view of one KSP/KSPB environment variable.
|
|
pub use self::management::ConfigEnvironmentReport;
|
|
/// Raw source of one registered Config document read through the explicit management surface.
|
|
pub use self::management::ConfigManagedSource;
|
|
/// Explicit Config management facade for source inspection and validated persistent mutations.
|
|
pub use self::management::ConfigManagement;
|
|
/// Typed source contract for `config/std.logging.json`.
|
|
pub use self::management::LoggingConfigDocument;
|
|
/// Typed source contract for the standard Logging console output.
|
|
pub use self::management::LoggingConsoleConfig;
|
|
/// Typed source contract for one persistent Logging file output.
|
|
pub use self::management::LoggingFileConfig;
|
|
/// Typed source contract for one Logging sink selector/filter.
|
|
pub use self::management::LoggingOutputFilterConfig;
|
|
/// Typed source contract for one profile in `std.logging.json`.
|
|
pub use self::management::LoggingProfileConfig;
|
|
/// Typed source contract for one global Logging target override.
|
|
pub use self::management::LoggingTargetFilterConfig;
|
|
/// Writable KSP runtime roots prepared from packaged Config resources.
|
|
pub use self::packaging::PackagedRuntimeLayout;
|
|
/// Prepares the shared writable KSP desktop runtime from immutable packaged resources.
|
|
pub use self::packaging::prepare_packaged_runtime;
|
|
/// Source that selected an effective standard Config profile.
|
|
pub use self::profile::ConfigProfileSelectionSource;
|
|
/// Origin of one top-level value in a resolved standard Config profile.
|
|
pub use self::profile::ConfigValueOrigin;
|
|
/// Validated standard Config document resolved to one profile with global/profile provenance.
|
|
pub use self::profile::ResolvedConfigProfile;
|
|
/// Bootstrap argument used to replace a known Config filename mapping.
|
|
pub use self::registry::ARG_FILE_MAP;
|
|
/// Logical descriptor associating a stable file identifier with its physical filename and validation schema.
|
|
pub use self::registry::ConfigFileDescriptor;
|
|
/// Stable logical identifier for a Config-managed file.
|
|
pub use self::registry::ConfigFileId;
|
|
/// Physical root category used to resolve a Config-managed file.
|
|
pub use self::registry::ConfigFileKind;
|
|
/// Registry of KSP-known logical Config files and their replaceable physical filenames.
|
|
pub use self::registry::ConfigFileRegistry;
|
|
/// Default physical filename for the Wallet Desk composite configuration document.
|
|
pub use self::registry::DEFAULT_COMPOSITE_KSP_APP_WALLET_DESK_FILENAME;
|
|
/// Default physical filename for the generic composite JSON Schema document.
|
|
pub use self::registry::DEFAULT_COMPOSITE_SCHEMA_FILENAME;
|
|
/// Default physical filename for the standard Logging configuration document.
|
|
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 + WebSocket Transport configuration document.
|
|
pub use self::registry::DEFAULT_STD_TRANSPORT_FILENAME;
|
|
/// Default physical filename for the standard HTTP + WebSocket Transport JSON Schema document.
|
|
pub use self::registry::DEFAULT_STD_TRANSPORT_SCHEMA_FILENAME;
|
|
/// Default physical filename for the standard Wallet configuration document.
|
|
pub use self::registry::DEFAULT_STD_WALLET_FILENAME;
|
|
/// Default physical filename for the standard Wallet JSON Schema document.
|
|
pub use self::registry::DEFAULT_STD_WALLET_SCHEMA_FILENAME;
|
|
/// Logical file identifier for the Wallet Desk composite configuration document.
|
|
pub use self::registry::FILE_ID_COMPOSITE_KSP_APP_WALLET_DESK;
|
|
/// 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 + WebSocket Transport JSON Schema document.
|
|
pub use self::registry::FILE_ID_SCHEMA_STD_TRANSPORT;
|
|
/// Logical file identifier for the standard Wallet JSON Schema document.
|
|
pub use self::registry::FILE_ID_SCHEMA_STD_WALLET;
|
|
/// Logical file identifier for the standard Logging configuration document.
|
|
pub use self::registry::FILE_ID_STD_LOGGING;
|
|
/// Logical file identifier for the standard HTTP + WebSocket Transport configuration document.
|
|
pub use self::registry::FILE_ID_STD_TRANSPORT;
|
|
/// Logical file identifier for the standard Wallet configuration document.
|
|
pub use self::registry::FILE_ID_STD_WALLET;
|
|
/// Sensitivity assigned to one Config value after environment resolution.
|
|
pub use self::sensitivity::ConfigSensitivity;
|
|
/// Provenance segment participating in one resolved Config value.
|
|
pub use self::sensitivity::ConfigValueProvenance;
|
|
/// Replacement used for secret environment fragments in safe diagnostic representations.
|
|
pub use self::sensitivity::REDACTED_CONFIG_VALUE;
|
|
/// Recursively resolved JSON value preserving real/safe trees and provenance.
|
|
pub use self::sensitivity::ResolvedConfigJson;
|
|
/// One resolved Config string preserving real/safe representations and provenance.
|
|
pub use self::sensitivity::ResolvedConfigText;
|
|
/// Effective standard Transport configuration mapped to HTTP and optional WebSocket runtime settings.
|
|
pub use self::transport::ResolvedTransportConfig;
|
|
/// Effective standard Wallet configuration resolved to validated filesystem roots.
|
|
pub use self::wallet::ResolvedWalletConfig;
|
|
|
|
/// Validates composite document contract.
|
|
pub(crate) use self::composite::validate_composite_document_contract;
|
|
/// Owning tracing target for events emitted by the Config crate.
|
|
pub(crate) use self::constants::TRACING_TARGET;
|
|
/// Executes the crate-internal parse dotenv content operation for the owning module.
|
|
pub(crate) use self::environment::parse_dotenv_content;
|
|
/// Validates supported variable name.
|
|
pub(crate) use self::environment::validate_supported_variable_name;
|
|
/// Executes the crate-internal atomic write operation for the owning module.
|
|
pub(crate) use self::persistence::atomic_write;
|
|
/// Executes the crate-internal atomic write private operation for the owning module.
|
|
pub(crate) use self::persistence::atomic_write_private;
|
|
/// Loads resolved profile with source.
|
|
pub(crate) use self::profile::load_resolved_profile_with_source;
|
|
/// Validates document profile contract.
|
|
pub(crate) use self::profile::validate_document_profile_contract;
|
|
/// Executes the crate-internal build registry operation for the owning module.
|
|
pub(crate) use self::registry::build_registry;
|
|
/// Validates standard Wallet source path invariants before environment resolution.
|
|
pub(crate) use self::wallet::validate_wallet_document_contract;
|