v0.1.3-pre.004

crates/ksp-logging-lib/src/settings.rs

@@ -1,5 +1,5 @@
 // file: crates/ksp-logging-lib/src/settings.rs
-// version: 2
+// version: 3
 
 /// Runtime filter level used by KSP logging settings.
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
@@ -18,7 +18,7 @@ pub enum LogFilterLevel {
     Trace,
 }
 
-/// Per-target filter override owned by Logging.
+/// Per-target filter override owned by Logging for the global KSP takeover policy.
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct TargetFilter {
     target_prefix: std::string::String,
@@ -56,6 +56,74 @@ pub enum SpanEvents {
     Full,
 }
 
+/// Output format requested for one Logging sink.
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+pub enum LogFormat {
+    /// Standard human-readable formatter with metadata.
+    Human,
+    /// Compact human-readable formatter.
+    Compact,
+    /// Expanded pretty human-readable formatter.
+    Pretty,
+    /// Structured JSON formatter.
+    Json,
+}
+
+/// Per-output routing filter applied in addition to the global KSP takeover policy.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct OutputFilter {
+    level: crate::LogFilterLevel,
+    targets: std::vec::Vec<std::string::String>,
+    domains: std::vec::Vec<std::string::String>,
+}
+
+impl OutputFilter {
+    /// Creates an explicit per-output filter.
+    ///
+    /// `targets` contains KSP target prefixes or the single wildcard `*`. `domains` contains domain prefixes or the single wildcard `*`.
+    #[must_use]
+    pub fn new(level: crate::LogFilterLevel, targets: std::vec::Vec<std::string::String>, domains: std::vec::Vec<std::string::String>) -> Self {
+        return Self { level, targets, domains };
+    }
+
+    /// Creates an unrestricted routing filter that does not further constrain the global KSP takeover policy.
+    #[must_use]
+    pub fn unrestricted() -> Self {
+        return Self::new(crate::LogFilterLevel::Trace, std::vec!["*".to_string()], std::vec!["*".to_string()]);
+    }
+
+    /// Returns the maximum verbosity accepted by this output.
+    #[must_use]
+    pub const fn level(&self) -> crate::LogFilterLevel {
+        return self.level;
+    }
+
+    /// Returns target selectors in declaration order.
+    #[must_use]
+    pub fn targets(&self) -> &[std::string::String] {
+        return self.targets.as_slice();
+    }
+
+    /// Returns domain selectors in declaration order.
+    #[must_use]
+    pub fn domains(&self) -> &[std::string::String] {
+        return self.domains.as_slice();
+    }
+
+    /// Returns whether this filter leaves routing entirely to the global takeover policy.
+    pub(crate) fn is_unrestricted(&self) -> bool {
+        let targets_all = match self.targets.as_slice() {
+            [selector] => selector == "*",
+            _ => false,
+        };
+        let domains_all = match self.domains.as_slice() {
+            [selector] => selector == "*",
+            _ => false,
+        };
+        return self.level == crate::LogFilterLevel::Trace && targets_all && domains_all;
+    }
+}
+
 /// Console stream selected for human-readable logs.
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
 pub enum ConsoleOutput {
@@ -66,22 +134,38 @@ pub enum ConsoleOutput {
 }
 
 /// Runtime settings for the optional console output.
-#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+#[derive(Clone, Debug, Eq, PartialEq)]
 pub struct ConsoleSettings {
+    enabled: bool,
     output: crate::ConsoleOutput,
+    ansi: bool,
+    format: crate::LogFormat,
+    filter: crate::OutputFilter,
 }
 
 impl ConsoleSettings {
-    /// Creates console settings targeting standard output.
+    /// Creates explicit console settings.
     #[must_use]
-    pub const fn stdout() -> Self {
-        return Self { output: crate::ConsoleOutput::Stdout };
+    pub fn new(enabled: bool, output: crate::ConsoleOutput, ansi: bool, format: crate::LogFormat, filter: crate::OutputFilter) -> Self {
+        return Self { enabled, output, ansi, format, filter };
     }
 
-    /// Creates console settings targeting standard error.
+    /// Creates enabled standard-output settings compatible with the `0.1.2` runtime behavior.
     #[must_use]
-    pub const fn stderr() -> Self {
-        return Self { output: crate::ConsoleOutput::Stderr };
+    pub fn stdout() -> Self {
+        return Self::new(true, crate::ConsoleOutput::Stdout, false, crate::LogFormat::Human, crate::OutputFilter::unrestricted());
+    }
+
+    /// Creates enabled standard-error settings compatible with the `0.1.2` runtime behavior.
+    #[must_use]
+    pub fn stderr() -> Self {
+        return Self::new(true, crate::ConsoleOutput::Stderr, false, crate::LogFormat::Human, crate::OutputFilter::unrestricted());
+    }
+
+    /// Returns whether this console output is enabled.
+    #[must_use]
+    pub const fn enabled(&self) -> bool {
+        return self.enabled;
     }
 
     /// Returns the selected console stream.
@@ -89,9 +173,27 @@ impl ConsoleSettings {
     pub const fn output(&self) -> crate::ConsoleOutput {
         return self.output;
     }
+
+    /// Returns whether ANSI formatting is requested for the console output.
+    #[must_use]
+    pub const fn ansi(&self) -> bool {
+        return self.ansi;
+    }
+
+    /// Returns the requested console format.
+    #[must_use]
+    pub const fn format(&self) -> crate::LogFormat {
+        return self.format;
+    }
+
+    /// Returns the routing filter associated with the console output.
+    #[must_use]
+    pub const fn filter(&self) -> &crate::OutputFilter {
+        return &self.filter;
+    }
 }
 
-/// Rotation cadence for the optional file output.
+/// Rotation cadence for a file output.
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
 pub enum FileRotation {
     /// Keeps a single non-rotating file.
@@ -102,23 +204,62 @@ pub enum FileRotation {
     Daily,
 }
 
-/// Runtime settings for the optional file output.
+/// Runtime settings for one file output.
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct FileSettings {
+    output_id: std::string::String,
+    enabled: bool,
     directory: std::path::PathBuf,
     file_name_prefix: std::string::String,
     rotation: crate::FileRotation,
+    format: crate::LogFormat,
+    ansi: bool,
+    filter: crate::OutputFilter,
 }
 
 impl FileSettings {
-    /// Creates file output settings.
+    /// Creates explicit file output settings.
     #[must_use]
     pub fn new(
+        output_id: impl std::convert::Into<std::string::String>,
+        enabled: bool,
         directory: impl std::convert::Into<std::path::PathBuf>,
         file_name_prefix: impl std::convert::Into<std::string::String>,
         rotation: crate::FileRotation,
+        format: crate::LogFormat,
+        filter: crate::OutputFilter,
     ) -> Self {
-        return Self { directory: directory.into(), file_name_prefix: file_name_prefix.into(), rotation };
+        return Self {
+            output_id: output_id.into(),
+            enabled,
+            directory: directory.into(),
+            file_name_prefix: file_name_prefix.into(),
+            rotation,
+            format,
+            ansi: false,
+            filter,
+        };
+    }
+
+    /// Sets whether ANSI formatting is requested and returns the updated settings.
+    ///
+    /// Persistent file outputs are required to keep this value `false`; [`crate::LoggingSettings::validate`] rejects `true`.
+    #[must_use]
+    pub fn with_ansi(mut self, ansi: bool) -> Self {
+        self.ansi = ansi;
+        return self;
+    }
+
+    /// Returns the stable output identifier used for diagnostics and reload accounting.
+    #[must_use]
+    pub fn output_id(&self) -> &str {
+        return self.output_id.as_str();
+    }
+
+    /// Returns whether this file output is enabled.
+    #[must_use]
+    pub const fn enabled(&self) -> bool {
+        return self.enabled;
     }
 
     /// Returns the directory containing log files.
@@ -138,6 +279,24 @@ impl FileSettings {
     pub const fn rotation(&self) -> crate::FileRotation {
         return self.rotation;
     }
+
+    /// Returns the requested file format.
+    #[must_use]
+    pub const fn format(&self) -> crate::LogFormat {
+        return self.format;
+    }
+
+    /// Returns whether ANSI formatting was requested for this file output.
+    #[must_use]
+    pub const fn ansi(&self) -> bool {
+        return self.ansi;
+    }
+
+    /// Returns the routing filter associated with this file output.
+    #[must_use]
+    pub const fn filter(&self) -> &crate::OutputFilter {
+        return &self.filter;
+    }
 }
 
 /// Complete runtime settings consumed by `ksp-logging-lib` initialization and reload.
@@ -147,29 +306,29 @@ pub struct LoggingSettings {
     target_filters: std::vec::Vec<crate::TargetFilter>,
     span_events: crate::SpanEvents,
     console: std::option::Option<crate::ConsoleSettings>,
-    file: std::option::Option<crate::FileSettings>,
+    files: std::vec::Vec<crate::FileSettings>,
 }
 
 impl LoggingSettings {
-    /// Creates explicit Logging settings without any target override.
+    /// Creates explicit Logging settings without any global target override.
     #[must_use]
     pub fn new(
         default_filter: crate::LogFilterLevel,
         span_events: crate::SpanEvents,
         console: std::option::Option<crate::ConsoleSettings>,
-        file: std::option::Option<crate::FileSettings>,
+        files: std::vec::Vec<crate::FileSettings>,
     ) -> Self {
-        return Self { default_filter, target_filters: std::vec::Vec::new(), span_events, console, file };
+        return Self { default_filter, target_filters: std::vec::Vec::new(), span_events, console, files };
     }
 
-    /// Adds one target-prefix override and returns the updated settings.
+    /// Adds one target-prefix override to the global KSP takeover policy and returns the updated settings.
     #[must_use]
     pub fn with_target_filter(mut self, target_filter: crate::TargetFilter) -> Self {
         self.target_filters.push(target_filter);
         return self;
     }
 
-    /// Returns the default level applied to KSP-owned targets.
+    /// Returns the default level applied to KSP-owned targets by the global takeover policy.
     #[must_use]
     pub const fn default_filter(&self) -> crate::LogFilterLevel {
         return self.default_filter;
@@ -187,16 +346,16 @@ impl LoggingSettings {
         return self.span_events;
     }
 
-    /// Returns console settings when console output is enabled.
+    /// Returns console settings when the console output is declared.
     #[must_use]
     pub fn console(&self) -> std::option::Option<&crate::ConsoleSettings> {
         return self.console.as_ref();
     }
 
-    /// Returns file settings when file output is enabled.
+    /// Returns all declared file outputs in declaration order.
     #[must_use]
-    pub fn file(&self) -> std::option::Option<&crate::FileSettings> {
-        return self.file.as_ref();
+    pub fn files(&self) -> &[crate::FileSettings] {
+        return self.files.as_slice();
     }
 
     /// Validates backend-independent invariants of the runtime settings.
@@ -216,18 +375,142 @@ impl LoggingSettings {
                 );
             }
         }
-        if let std::option::Option::Some(file) = self.file.as_ref()
-            && file.file_name_prefix().is_empty()
-        {
-            return std::result::Result::Err(
-                ksp_core_lib::Error::new(crate::ERROR_CODE_INVALID_SETTINGS, "file name prefix must not be empty")
-                    .with_context("field", "file.file_name_prefix"),
-            );
+        if let std::option::Option::Some(console) = self.console.as_ref() {
+            let validation_result = validate_output_filter(console.filter(), "console.filter");
+            if let std::result::Result::Err(error) = validation_result {
+                return std::result::Result::Err(error);
+            }
+        }
+        for (index, file) in self.files.iter().enumerate() {
+            let output_id_validation = validate_output_id(file.output_id(), index);
+            if let std::result::Result::Err(error) = output_id_validation {
+                return std::result::Result::Err(error);
+            }
+            if file.directory().as_os_str().is_empty() {
+                return std::result::Result::Err(
+                    ksp_core_lib::Error::new(crate::ERROR_CODE_INVALID_SETTINGS, "file output directory must not be empty")
+                        .with_context("field", format!("files[{index}].directory"))
+                        .with_context("output_id", file.output_id()),
+                );
+            }
+            if file.file_name_prefix().is_empty() {
+                return std::result::Result::Err(
+                    ksp_core_lib::Error::new(crate::ERROR_CODE_INVALID_SETTINGS, "file name prefix must not be empty")
+                        .with_context("field", format!("files[{index}].file_name_prefix"))
+                        .with_context("output_id", file.output_id()),
+                );
+            }
+            if file.ansi() {
+                return std::result::Result::Err(
+                    ksp_core_lib::Error::new(crate::ERROR_CODE_INVALID_SETTINGS, "ANSI sequences are not allowed in persistent file outputs")
+                        .with_context("field", format!("files[{index}].ansi"))
+                        .with_context("output_id", file.output_id()),
+                );
+            }
+            let filter_validation = validate_output_filter(file.filter(), format!("files[{index}].filter").as_str());
+            if let std::result::Result::Err(error) = filter_validation {
+                return std::result::Result::Err(error.with_context("output_id", file.output_id()));
+            }
+            for previous in &self.files[..index] {
+                if previous.output_id() == file.output_id() {
+                    return std::result::Result::Err(
+                        ksp_core_lib::Error::new(crate::ERROR_CODE_INVALID_SETTINGS, "file output identifiers must be unique")
+                            .with_context("field", format!("files[{index}].output_id"))
+                            .with_context("output_id", file.output_id()),
+                    );
+                }
+            }
         }
         return std::result::Result::Ok(());
     }
 }
 
+fn validate_output_id(output_id: &str, index: usize) -> ksp_core_lib::Result<()> {
+    let mut previous_was_separator = true;
+    if output_id.is_empty() {
+        return invalid_output_id(output_id, index);
+    }
+    for byte in output_id.bytes() {
+        if byte == b'.' {
+            if previous_was_separator {
+                return invalid_output_id(output_id, index);
+            }
+            previous_was_separator = true;
+            continue;
+        }
+        if !(byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'_' || byte == b'-') {
+            return invalid_output_id(output_id, index);
+        }
+        previous_was_separator = false;
+    }
+    if previous_was_separator {
+        return invalid_output_id(output_id, index);
+    }
+    return std::result::Result::Ok(());
+}
+
+fn invalid_output_id(output_id: &str, index: usize) -> ksp_core_lib::Result<()> {
+    return std::result::Result::Err(
+        ksp_core_lib::Error::new(crate::ERROR_CODE_INVALID_SETTINGS, "file output identifier is invalid")
+            .with_context("field", format!("files[{index}].output_id"))
+            .with_context("output_id", output_id),
+    );
+}
+
+fn validate_output_filter(filter: &crate::OutputFilter, field: &str) -> ksp_core_lib::Result<()> {
+    let target_validation = validate_selectors(filter.targets(), true, format!("{field}.targets").as_str());
+    if let std::result::Result::Err(error) = target_validation {
+        return std::result::Result::Err(error);
+    }
+    let domain_validation = validate_selectors(filter.domains(), false, format!("{field}.domains").as_str());
+    if let std::result::Result::Err(error) = domain_validation {
+        return std::result::Result::Err(error);
+    }
+    return std::result::Result::Ok(());
+}
+
+fn validate_selectors(selectors: &[std::string::String], target_dimension: bool, field: &str) -> ksp_core_lib::Result<()> {
+    if selectors.is_empty() {
+        return std::result::Result::Err(
+            ksp_core_lib::Error::new(crate::ERROR_CODE_INVALID_SETTINGS, "output selector list must not be empty").with_context("field", field),
+        );
+    }
+    if selectors.len() > 1
+        && selectors.iter().any(|selector| -> bool {
+            return selector == "*";
+        })
+    {
+        return std::result::Result::Err(
+            ksp_core_lib::Error::new(crate::ERROR_CODE_INVALID_SETTINGS, "wildcard selector must be used alone").with_context("field", field),
+        );
+    }
+    for (index, selector) in selectors.iter().enumerate() {
+        if selector.trim().is_empty() {
+            return std::result::Result::Err(
+                ksp_core_lib::Error::new(crate::ERROR_CODE_INVALID_SETTINGS, "output selector must not be empty")
+                    .with_context("field", format!("{field}[{index}]")),
+            );
+        }
+        if target_dimension && selector != "*" && !selector.starts_with("ksp-") {
+            return std::result::Result::Err(
+                ksp_core_lib::Error::new(crate::ERROR_CODE_INVALID_SETTINGS, "output target selector must identify a KSP-owned target")
+                    .with_context("field", format!("{field}[{index}]"))
+                    .with_context("selector", selector),
+            );
+        }
+        for previous in &selectors[..index] {
+            if previous == selector {
+                return std::result::Result::Err(
+                    ksp_core_lib::Error::new(crate::ERROR_CODE_INVALID_SETTINGS, "output selectors must be unique")
+                        .with_context("field", format!("{field}[{index}]"))
+                        .with_context("selector", selector),
+                );
+            }
+        }
+    }
+    return std::result::Result::Ok(());
+}
+
 #[cfg(test)]
 #[path = "../unit_tests/settings.rs"]
 mod tests;