v0.1.3-pre.010

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

@@ -0,0 +1,451 @@
+// file: crates/ksp-config-lib/src/environment.rs
+// version: 1
+
+/// Default local environment file read by Config from the process launch directory.
+pub const DEFAULT_DOTENV_PATH: &str = ".env";
+
+/// Versioned environment contract template expected at the repository/runtime root.
+pub const DEFAULT_DOTENV_EXAMPLE_PATH: &str = ".env.example";
+
+const LOGGING_TARGET: &str = "ksp-config-lib";
+const LOGGING_DOMAIN: &str = "config.environment";
+
+/// Source that supplied one resolved Config environment variable.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ConfigEnvironmentSource {
+    /// Value was present in the environment inherited by the current process.
+    Process,
+    /// Value was absent from the process environment and came from the local `.env` file.
+    DotEnv,
+    /// Value was absent from both external sources and came from the placeholder/API fallback.
+    Fallback,
+}
+
+/// One resolved Config environment variable and its winning source.
+///
+/// This type intentionally does not implement `Debug`: environment values may contain secrets. Sensitivity-aware safe representations are added by the next
+/// bounded Config prerelease.
+#[derive(Clone, Eq, PartialEq)]
+pub struct ConfigEnvironmentValue {
+    variable_name: String,
+    value: String,
+    source: ConfigEnvironmentSource,
+}
+
+impl ConfigEnvironmentValue {
+    /// Returns the resolved variable name.
+    #[must_use]
+    pub fn variable_name(&self) -> &str {
+        return self.variable_name.as_str();
+    }
+
+    /// Returns the real resolved value.
+    #[must_use]
+    pub fn value(&self) -> &str {
+        return self.value.as_str();
+    }
+
+    /// Returns the source that won process > `.env` > fallback resolution.
+    #[must_use]
+    pub const fn source(&self) -> ConfigEnvironmentSource {
+        return self.source;
+    }
+}
+
+/// Config-owned snapshot of KSP/KSPB process environment values and the local `.env` file.
+///
+/// The process environment is captured first and always has priority over `.env`. An absent `.env` file is equivalent to an empty local environment source.
+/// Config never mutates the parent/process environment through this type.
+#[derive(Clone, Eq, PartialEq)]
+pub struct ConfigEnvironment {
+    process: std::collections::BTreeMap<String, String>,
+    dotenv: std::collections::BTreeMap<String, String>,
+    dotenv_path: std::path::PathBuf,
+}
+
+impl ConfigEnvironment {
+    /// Captures supported variables from the current process and reads `./.env` when it exists.
+    pub fn load() -> ksp_core_lib::Result<Self> {
+        return Self::load_from_dotenv_path(std::path::Path::new(DEFAULT_DOTENV_PATH));
+    }
+
+    /// Returns the local `.env` path used by this environment snapshot.
+    #[must_use]
+    pub fn dotenv_path(&self) -> &std::path::Path {
+        return self.dotenv_path.as_path();
+    }
+
+    /// Resolves one KSP/KSPB variable using process > `.env` > fallback priority.
+    ///
+    /// The fallback is used only when the variable is absent. An explicitly defined empty string is a real value and therefore wins over the fallback.
+    pub fn resolve_variable(&self, variable_name: &str, fallback: std::option::Option<&str>) -> ksp_core_lib::Result<ConfigEnvironmentValue> {
+        let validation = validate_supported_variable_name(variable_name);
+        if let std::result::Result::Err(error) = validation {
+            return std::result::Result::Err(error);
+        }
+        if let std::option::Option::Some(value) = self.process.get(variable_name) {
+            return std::result::Result::Ok(ConfigEnvironmentValue {
+                variable_name: variable_name.to_owned(),
+                value: value.clone(),
+                source: ConfigEnvironmentSource::Process,
+            });
+        }
+        if let std::option::Option::Some(value) = self.dotenv.get(variable_name) {
+            return std::result::Result::Ok(ConfigEnvironmentValue {
+                variable_name: variable_name.to_owned(),
+                value: value.clone(),
+                source: ConfigEnvironmentSource::DotEnv,
+            });
+        }
+        if let std::option::Option::Some(value) = fallback {
+            return std::result::Result::Ok(ConfigEnvironmentValue {
+                variable_name: variable_name.to_owned(),
+                value: value.to_owned(),
+                source: ConfigEnvironmentSource::Fallback,
+            });
+        }
+        emit_missing_variable_warning(variable_name);
+        return std::result::Result::Err(missing_variable_error(variable_name));
+    }
+
+    /// Resolves `${NAME}` and `${NAME:-fallback}` placeholders embedded in one UTF-8 string.
+    ///
+    /// Multiple placeholders are supported. Fallback text is literal in this prerelease and is not recursively interpreted as another placeholder expression.
+    pub fn resolve_text(&self, source: &str) -> ksp_core_lib::Result<String> {
+        let mut output = String::new();
+        let mut remaining = source;
+        loop {
+            let start = remaining.find("${");
+            let start = match start {
+                std::option::Option::Some(value) => value,
+                std::option::Option::None => {
+                    output.push_str(remaining);
+                    return std::result::Result::Ok(output);
+                },
+            };
+            output.push_str(&remaining[..start]);
+            let expression_and_tail = &remaining[start + 2..];
+            let end = expression_and_tail.find('}');
+            let end = match end {
+                std::option::Option::Some(value) => value,
+                std::option::Option::None => return std::result::Result::Err(invalid_placeholder_error("placeholder is missing its closing '}'")),
+            };
+            let expression = &expression_and_tail[..end];
+            let parsed = parse_placeholder_expression(expression);
+            let (variable_name, fallback) = match parsed {
+                std::result::Result::Ok(value) => value,
+                std::result::Result::Err(error) => return std::result::Result::Err(error),
+            };
+            let resolved = self.resolve_variable(variable_name, fallback);
+            let resolved = match resolved {
+                std::result::Result::Ok(value) => value,
+                std::result::Result::Err(error) => return std::result::Result::Err(error),
+            };
+            output.push_str(resolved.value());
+            remaining = &expression_and_tail[end + 1..];
+        }
+    }
+
+    /// Recursively resolves environment placeholders in JSON string values while preserving keys and non-string JSON values.
+    pub fn resolve_json(&self, source: &serde_json::Value) -> ksp_core_lib::Result<serde_json::Value> {
+        return match source {
+            serde_json::Value::Null | serde_json::Value::Bool(_) | serde_json::Value::Number(_) => std::result::Result::Ok(source.clone()),
+            serde_json::Value::String(value) => {
+                let resolved = self.resolve_text(value.as_str());
+                match resolved {
+                    std::result::Result::Ok(value) => std::result::Result::Ok(serde_json::Value::String(value)),
+                    std::result::Result::Err(error) => std::result::Result::Err(error),
+                }
+            },
+            serde_json::Value::Array(values) => resolve_array(self, values),
+            serde_json::Value::Object(values) => {
+                let resolved = self.resolve_map(values);
+                match resolved {
+                    std::result::Result::Ok(value) => std::result::Result::Ok(serde_json::Value::Object(value)),
+                    std::result::Result::Err(error) => std::result::Result::Err(error),
+                }
+            },
+        };
+    }
+
+    /// Recursively resolves environment placeholders in one JSON object map while leaving the map keys unchanged.
+    pub fn resolve_map(&self, source: &serde_json::Map<String, serde_json::Value>) -> ksp_core_lib::Result<serde_json::Map<String, serde_json::Value>> {
+        let mut output = serde_json::Map::<String, serde_json::Value>::new();
+        for (key, value) in source {
+            let resolved = self.resolve_json(value);
+            let resolved = match resolved {
+                std::result::Result::Ok(value) => value,
+                std::result::Result::Err(error) => return std::result::Result::Err(error),
+            };
+            output.insert(key.clone(), resolved);
+        }
+        return std::result::Result::Ok(output);
+    }
+
+    fn load_from_dotenv_path(dotenv_path: &std::path::Path) -> ksp_core_lib::Result<Self> {
+        let process = collect_process_environment(std::env::vars_os());
+        let process = match process {
+            std::result::Result::Ok(value) => value,
+            std::result::Result::Err(error) => return std::result::Result::Err(error),
+        };
+        let dotenv = load_dotenv_file(dotenv_path);
+        let dotenv = match dotenv {
+            std::result::Result::Ok(value) => value,
+            std::result::Result::Err(error) => return std::result::Result::Err(error),
+        };
+        return std::result::Result::Ok(Self { process, dotenv, dotenv_path: dotenv_path.to_path_buf() });
+    }
+
+    #[cfg(test)]
+    fn from_maps(process: std::collections::BTreeMap<String, String>, dotenv: std::collections::BTreeMap<String, String>) -> Self {
+        return Self { process, dotenv, dotenv_path: std::path::PathBuf::from(DEFAULT_DOTENV_PATH) };
+    }
+}
+
+fn collect_process_environment<I>(values: I) -> ksp_core_lib::Result<std::collections::BTreeMap<String, String>>
+where
+    I: std::iter::IntoIterator<Item = (std::ffi::OsString, std::ffi::OsString)>,
+{
+    let mut output = std::collections::BTreeMap::<String, String>::new();
+    for (name, value) in values {
+        let name = match name.to_str() {
+            std::option::Option::Some(value) => value,
+            std::option::Option::None => continue,
+        };
+        if !has_supported_namespace(name) {
+            continue;
+        }
+        let validation = validate_supported_variable_name(name);
+        if let std::result::Result::Err(error) = validation {
+            return std::result::Result::Err(error);
+        }
+        let value = value.into_string();
+        let value = match value {
+            std::result::Result::Ok(value) => value,
+            std::result::Result::Err(_) => return std::result::Result::Err(invalid_environment_value_error(name)),
+        };
+        output.insert(name.to_owned(), value);
+    }
+    return std::result::Result::Ok(output);
+}
+
+fn load_dotenv_file(path: &std::path::Path) -> ksp_core_lib::Result<std::collections::BTreeMap<String, String>> {
+    let content = std::fs::read_to_string(path);
+    let content = match content {
+        std::result::Result::Ok(value) => value,
+        std::result::Result::Err(error) if error.kind() == std::io::ErrorKind::NotFound => return std::result::Result::Ok(std::collections::BTreeMap::new()),
+        std::result::Result::Err(error) => return std::result::Result::Err(dotenv_read_error(path, error)),
+    };
+    return parse_dotenv_content(path, content.as_str());
+}
+
+fn parse_dotenv_content(path: &std::path::Path, content: &str) -> ksp_core_lib::Result<std::collections::BTreeMap<String, String>> {
+    let mut output = std::collections::BTreeMap::<String, String>::new();
+    for (line_index, raw_line) in content.lines().enumerate() {
+        let raw_line = if line_index == 0 { raw_line.trim_start_matches('\u{feff}') } else { raw_line };
+        let line = raw_line.trim();
+        if line.is_empty() || line.starts_with('#') {
+            continue;
+        }
+        let assignment = match line.strip_prefix("export ") {
+            std::option::Option::Some(value) => value.trim_start(),
+            std::option::Option::None => line,
+        };
+        let separator = assignment.find('=');
+        let separator = match separator {
+            std::option::Option::Some(value) => value,
+            std::option::Option::None => return std::result::Result::Err(dotenv_syntax_error(path, line_index + 1, "assignment is missing '='")),
+        };
+        let variable_name = assignment[..separator].trim();
+        if !is_generic_dotenv_name(variable_name) {
+            return std::result::Result::Err(dotenv_syntax_error(path, line_index + 1, "variable name is invalid"));
+        }
+        let raw_value = assignment[separator + 1..].trim();
+        let value = parse_dotenv_value(path, line_index + 1, raw_value);
+        let value = match value {
+            std::result::Result::Ok(value) => value,
+            std::result::Result::Err(error) => return std::result::Result::Err(error),
+        };
+        if !has_supported_namespace(variable_name) {
+            continue;
+        }
+        let validation = validate_supported_variable_name(variable_name);
+        if let std::result::Result::Err(error) = validation {
+            return std::result::Result::Err(error);
+        }
+        let entry = output.entry(variable_name.to_owned());
+        match entry {
+            std::collections::btree_map::Entry::Occupied(_) => {
+                return std::result::Result::Err(dotenv_duplicate_error(path, line_index + 1, variable_name));
+            },
+            std::collections::btree_map::Entry::Vacant(entry) => {
+                entry.insert(value);
+            },
+        }
+    }
+    return std::result::Result::Ok(output);
+}
+
+fn parse_dotenv_value(path: &std::path::Path, line_number: usize, raw_value: &str) -> ksp_core_lib::Result<String> {
+    if raw_value.starts_with('\'') && (raw_value.len() < 2 || !raw_value.ends_with('\'')) {
+        return std::result::Result::Err(dotenv_syntax_error(path, line_number, "single-quoted value is not terminated"));
+    }
+    if raw_value.starts_with('\'') {
+        return std::result::Result::Ok(raw_value[1..raw_value.len() - 1].to_owned());
+    }
+    if raw_value.starts_with('"') && (raw_value.len() < 2 || !raw_value.ends_with('"')) {
+        return std::result::Result::Err(dotenv_syntax_error(path, line_number, "double-quoted value is not terminated"));
+    }
+    if raw_value.starts_with('"') {
+        return parse_double_quoted_value(path, line_number, &raw_value[1..raw_value.len() - 1]);
+    }
+    let inline_comment = raw_value.find(" #");
+    let value = match inline_comment {
+        std::option::Option::Some(index) => raw_value[..index].trim_end(),
+        std::option::Option::None => raw_value,
+    };
+    return std::result::Result::Ok(value.to_owned());
+}
+
+fn parse_double_quoted_value(path: &std::path::Path, line_number: usize, source: &str) -> ksp_core_lib::Result<String> {
+    let mut output = String::new();
+    let mut escaped = false;
+    for character in source.chars() {
+        if escaped {
+            let mapped = match character {
+                'n' => '\n',
+                'r' => '\r',
+                't' => '\t',
+                '\\' => '\\',
+                '"' => '"',
+                _ => return std::result::Result::Err(dotenv_syntax_error(path, line_number, "double-quoted value contains an unsupported escape")),
+            };
+            output.push(mapped);
+            escaped = false;
+        } else if character == '\\' {
+            escaped = true;
+        } else {
+            output.push(character);
+        }
+    }
+    if escaped {
+        return std::result::Result::Err(dotenv_syntax_error(path, line_number, "double-quoted value ends with an incomplete escape"));
+    }
+    return std::result::Result::Ok(output);
+}
+
+fn parse_placeholder_expression(expression: &str) -> ksp_core_lib::Result<(&str, std::option::Option<&str>)> {
+    if expression.is_empty() || expression.contains("${") {
+        return std::result::Result::Err(invalid_placeholder_error("placeholder expression is empty or nested"));
+    }
+    let fallback_separator = expression.find(":-");
+    let (variable_name, fallback) = match fallback_separator {
+        std::option::Option::Some(index) => (&expression[..index], std::option::Option::Some(&expression[index + 2..])),
+        std::option::Option::None => (expression, std::option::Option::None),
+    };
+    let validation = validate_supported_variable_name(variable_name);
+    if let std::result::Result::Err(error) = validation {
+        return std::result::Result::Err(error);
+    }
+    return std::result::Result::Ok((variable_name, fallback));
+}
+
+fn resolve_array(environment: &ConfigEnvironment, source: &[serde_json::Value]) -> ksp_core_lib::Result<serde_json::Value> {
+    let mut output = std::vec::Vec::<serde_json::Value>::with_capacity(source.len());
+    for value in source {
+        let resolved = environment.resolve_json(value);
+        let resolved = match resolved {
+            std::result::Result::Ok(value) => value,
+            std::result::Result::Err(error) => return std::result::Result::Err(error),
+        };
+        output.push(resolved);
+    }
+    return std::result::Result::Ok(serde_json::Value::Array(output));
+}
+
+fn validate_supported_variable_name(variable_name: &str) -> ksp_core_lib::Result<()> {
+    if !has_supported_namespace(variable_name) {
+        return std::result::Result::Err(invalid_variable_error(variable_name, "variable must use the KSP_ or KSPB_ namespace"));
+    }
+    let prefix_length = if variable_name.starts_with("KSPB_") { 5 } else { 4 };
+    if variable_name.len() <= prefix_length {
+        return std::result::Result::Err(invalid_variable_error(variable_name, "variable namespace must be followed by a name"));
+    }
+    for byte in variable_name.bytes() {
+        let valid = byte.is_ascii_uppercase() || byte.is_ascii_digit() || byte == b'_';
+        if !valid {
+            return std::result::Result::Err(invalid_variable_error(variable_name, "variable names use uppercase ASCII letters, digits and underscores"));
+        }
+    }
+    return std::result::Result::Ok(());
+}
+
+fn has_supported_namespace(variable_name: &str) -> bool {
+    return variable_name.starts_with("KSP_") || variable_name.starts_with("KSPB_");
+}
+
+fn is_generic_dotenv_name(variable_name: &str) -> bool {
+    let mut bytes = variable_name.bytes();
+    let first = match bytes.next() {
+        std::option::Option::Some(value) => value,
+        std::option::Option::None => return false,
+    };
+    if !(first.is_ascii_alphabetic() || first == b'_') {
+        return false;
+    }
+    for byte in bytes {
+        if !(byte.is_ascii_alphanumeric() || byte == b'_') {
+            return false;
+        }
+    }
+    return true;
+}
+
+fn emit_missing_variable_warning(variable_name: &str) {
+    ksp_logging_lib::warn!(target: LOGGING_TARGET, domain = LOGGING_DOMAIN, variable_name = variable_name, "Config environment variable is missing");
+}
+
+fn missing_variable_error(variable_name: &str) -> ksp_core_lib::Error {
+    return ksp_core_lib::Error::new(crate::ERROR_CODE_ENVIRONMENT_VARIABLE_MISSING, "required Config environment variable is missing")
+        .with_context("variable_name", variable_name);
+}
+
+fn invalid_variable_error(variable_name: &str, reason: &'static str) -> ksp_core_lib::Error {
+    return ksp_core_lib::Error::new(crate::ERROR_CODE_ENVIRONMENT_VARIABLE_INVALID, "Config environment variable name is invalid")
+        .with_context("variable_name", variable_name)
+        .with_context("reason", reason);
+}
+
+fn invalid_environment_value_error(variable_name: &str) -> ksp_core_lib::Error {
+    return ksp_core_lib::Error::new(crate::ERROR_CODE_ENVIRONMENT_VALUE_INVALID, "Config environment variable value is not valid UTF-8")
+        .with_context("variable_name", variable_name);
+}
+
+fn invalid_placeholder_error(reason: &'static str) -> ksp_core_lib::Error {
+    return ksp_core_lib::Error::new(crate::ERROR_CODE_ENVIRONMENT_PLACEHOLDER_INVALID, "Config environment placeholder is invalid")
+        .with_context("reason", reason);
+}
+
+fn dotenv_read_error(path: &std::path::Path, source: std::io::Error) -> ksp_core_lib::Error {
+    return ksp_core_lib::Error::new(crate::ERROR_CODE_DOTENV_FILE_READ_FAILED, "Config cannot read the local .env file")
+        .with_context("path", path.to_string_lossy().into_owned())
+        .with_source(source);
+}
+
+fn dotenv_syntax_error(path: &std::path::Path, line_number: usize, reason: &'static str) -> ksp_core_lib::Error {
+    return ksp_core_lib::Error::new(crate::ERROR_CODE_DOTENV_SYNTAX_INVALID, "Config local .env syntax is invalid")
+        .with_context("path", path.to_string_lossy().into_owned())
+        .with_context("line", line_number.to_string())
+        .with_context("reason", reason);
+}
+
+fn dotenv_duplicate_error(path: &std::path::Path, line_number: usize, variable_name: &str) -> ksp_core_lib::Error {
+    return ksp_core_lib::Error::new(crate::ERROR_CODE_DOTENV_SYNTAX_INVALID, "Config local .env contains a duplicate KSP variable")
+        .with_context("path", path.to_string_lossy().into_owned())
+        .with_context("line", line_number.to_string())
+        .with_context("variable_name", variable_name);
+}
+
+#[cfg(test)]
+#[path = "../unit_tests/environment.rs"]
+mod tests;