[PATCH proxmox 11/29] notify: matcher: add expression support

[Lukas Wagner <l.wagner@proxmox.com>]

This commit adds support for the new 'expression' parameter in the
matcher configuration. It contains a JSON-serialized match expression
(based on the new proxmox-match-expression crate). It is intended as a
replacement for the existing match-field, match-calendar,
match-severity, mode and invert-match keys.

The match expression implements a strict superset of the existing
configuration keys, any existing configuration can be converted into
an expression.

Expressions lift some of limitations of the old approach, namely they
allow arbitrary nesting of match rules and combinators.

The following expressions are supported
  - all-of (corresponds to the former mode 'all')
  - any-of (corresponds to the former mode 'any')
  - one-of (new)
  - not    (corresponds to former 'invert-match')
  - match-calendar (unchanged)
  - match-field    (unchanged)
  - match-severity (unchanged)

The combinators all-of, any-of and one-of support an arbitrary number of
child expressions (where each child can be a combinator, not, or a
match-* expression).

Internally, existing, 'old-style' matchers are converted on the fly to
expressions, meaning there is only a single code path for the matching
logic. If any matcher has any of the old configuration keys and the new
expression set, the old keys will be ignored and a warning will be
logged.

Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>
---
 Cargo.toml                               |   1 +
 proxmox-notify/Cargo.toml                |   2 +
 proxmox-notify/src/matcher/expression.rs |  84 ++++++++++++++
 proxmox-notify/src/matcher/field.rs      |  31 +++--
 proxmox-notify/src/matcher/mod.rs        | 142 +++++++++++++----------
 proxmox-notify/src/matcher/severity.rs   |   6 +-
 6 files changed, 185 insertions(+), 81 deletions(-)
 create mode 100644 proxmox-notify/src/matcher/expression.rs

diff --git a/Cargo.toml b/Cargo.toml
index fcb06704..690f3436 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -137,6 +137,7 @@ serde-xml-rs = "0.5"
 serde_cbor = "0.11.1"
 serde_json = "1.0"
 serde_plain = "1.0"
+serde_regex = "1.1"
 syn = { version = "2", features = [ "full", "visit-mut" ] }
 sync_wrapper = "1"
 tar = "0.4"
diff --git a/proxmox-notify/Cargo.toml b/proxmox-notify/Cargo.toml
index bc63e19d..ae82f649 100644
--- a/proxmox-notify/Cargo.toml
+++ b/proxmox-notify/Cargo.toml
@@ -24,11 +24,13 @@ percent-encoding = { workspace = true, optional = true }
 regex.workspace = true
 serde = { workspace = true, features = ["derive"] }
 serde_json.workspace = true
+serde_regex.workspace = true
 
 proxmox-base64 = { workspace = true, optional = true }
 proxmox-http = { workspace = true, features = ["client-sync"], optional = true }
 proxmox-http-error.workspace = true
 proxmox-human-byte.workspace = true
+proxmox-match-expression.workspace = true
 proxmox-schema = { workspace = true, features = ["api-macro", "api-types"] }
 proxmox-section-config = { workspace = true }
 proxmox-serde.workspace = true
diff --git a/proxmox-notify/src/matcher/expression.rs b/proxmox-notify/src/matcher/expression.rs
new file mode 100644
index 00000000..308987ad
--- /dev/null
+++ b/proxmox-notify/src/matcher/expression.rs
@@ -0,0 +1,84 @@
+use serde::{Deserialize, Serialize};
+
+use proxmox_match_expression::MatchExpression;
+
+use crate::{Error, Notification};
+
+use super::{calendar::CalendarMatcher, field::FieldMatcher, severity::SeverityMatcher};
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+#[serde(rename_all = "kebab-case", tag = "type")]
+pub enum NotificationMatcher {
+    /// Match a notification's metadata field.
+    Field(FieldMatcher),
+    /// Match a notification's timestamp.
+    Calendar(CalendarMatcher),
+    /// Match the severity of a notification.
+    Severity(SeverityMatcher),
+}
+
+impl MatchExpression for NotificationMatcher {
+    type Data = Notification;
+    type Error = Error;
+
+    fn evaluate(&self, data: &Notification) -> Result<bool, Error> {
+        use super::MatchDirective;
+
+        match self {
+            NotificationMatcher::Field(field_matcher) => field_matcher.matches(data),
+            NotificationMatcher::Calendar(calendar_matcher) => calendar_matcher.matches(data),
+            NotificationMatcher::Severity(severity_matcher) => severity_matcher.matches(data),
+        }
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use proxmox_match_expression::Expression;
+
+    use super::*;
+
+    #[test]
+    fn test_matcher_deser() {
+        let e = r#"
+            {
+              "any-of": [
+                {
+                  "match": {
+                    "type": "severity",
+                    "severities": [
+                      "info",
+                      "notice"
+                    ]
+                  }
+                },
+                {
+                  "match": {
+                    "type": "field",
+                    "field": "something",
+                    "regex": "^abc$"
+                    }
+                },
+                {
+                  "match": {
+                    "type": "field",
+                    "field": "something",
+                    "values": [
+                      "a",
+                      "b",
+                      "c"
+                    ]
+                  }
+                },
+                {
+                  "match": {
+                    "type": "calendar",
+                    "schedule": "sat,sun 10-14"
+                  }
+                }
+              ]
+            }"#;
+
+        let s: Expression<NotificationMatcher> = serde_json::from_str(e).unwrap();
+    }
+}
diff --git a/proxmox-notify/src/matcher/field.rs b/proxmox-notify/src/matcher/field.rs
index ad04b388..fd25939c 100644
--- a/proxmox-notify/src/matcher/field.rs
+++ b/proxmox-notify/src/matcher/field.rs
@@ -6,6 +6,7 @@ use regex::Regex;
 use proxmox_schema::{
     ApiStringFormat, Schema, StringSchema, api_types::SAFE_ID_REGEX_STR, const_regex,
 };
+use serde::{Deserialize, Serialize};
 
 use crate::{Error, Notification};
 
@@ -30,42 +31,38 @@ pub const MATCH_FIELD_ENTRY_SCHEMA: Schema = StringSchema::new("Match metadata f
     .schema();
 
 /// Check if the notification metadata fields match
-#[derive(Clone, Debug)]
+#[derive(Clone, Debug, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case", untagged)]
 pub enum FieldMatcher {
     Exact {
         field: String,
-        matched_values: Vec<String>,
+        values: Vec<String>,
     },
     Regex {
         field: String,
-        matched_regex: Regex,
+        #[serde(with = "serde_regex")]
+        regex: Regex,
     },
 }
 
 impl MatchDirective for FieldMatcher {
     fn matches(&self, notification: &Notification) -> Result<bool, Error> {
         Ok(match self {
-            FieldMatcher::Exact {
-                field,
-                matched_values,
-            } => {
+            FieldMatcher::Exact { field, values } => {
                 let value = notification.metadata.additional_fields.get(field);
 
                 if let Some(value) = value {
-                    matched_values.contains(value)
+                    values.contains(value)
                 } else {
                     // Metadata field does not exist, so we do not match
                     false
                 }
             }
-            FieldMatcher::Regex {
-                field,
-                matched_regex,
-            } => {
+            FieldMatcher::Regex { field, regex } => {
                 let value = notification.metadata.additional_fields.get(field);
 
                 if let Some(value) = value {
-                    matched_regex.is_match(value)
+                    regex.is_match(value)
                 } else {
                     // Metadata field does not exist, so we do not match
                     false
@@ -96,14 +93,14 @@ impl fmt::Display for InlineFieldMatcher {
         match &self.0 {
             FieldMatcher::Exact {
                 field,
-                matched_values,
+                values: matched_values,
             } => {
                 let values = matched_values.join(",");
                 write!(f, "exact:{field}={values}")
             }
             FieldMatcher::Regex {
                 field,
-                matched_regex,
+                regex: matched_regex,
             } => {
                 let re = matched_regex.as_str();
                 write!(f, "regex:{field}={re}")
@@ -132,7 +129,7 @@ impl FromStr for InlineFieldMatcher {
 
                     Ok(Self(FieldMatcher::Regex {
                         field: field.into(),
-                        matched_regex: regex,
+                        regex,
                     }))
                 }
             }
@@ -149,7 +146,7 @@ impl FromStr for InlineFieldMatcher {
                         .collect();
                     Ok(Self(FieldMatcher::Exact {
                         field: field.into(),
-                        matched_values: values,
+                        values,
                     }))
                 }
             }
diff --git a/proxmox-notify/src/matcher/mod.rs b/proxmox-notify/src/matcher/mod.rs
index a5d53d8a..429692a4 100644
--- a/proxmox-notify/src/matcher/mod.rs
+++ b/proxmox-notify/src/matcher/mod.rs
@@ -1,16 +1,19 @@
 use std::collections::HashSet;
 use std::fmt::Debug;
 
+use proxmox_match_expression::Expression;
 use serde::{Deserialize, Serialize};
 use tracing::{error, info};
 
 use proxmox_schema::api_types::COMMENT_SCHEMA;
 use proxmox_schema::{Updater, api};
 
+use crate::matcher::expression::NotificationMatcher;
 use crate::schema::ENTITY_NAME_SCHEMA;
 use crate::{Error, Notification, Origin};
 
 pub mod calendar;
+pub mod expression;
 pub mod field;
 pub mod severity;
 
@@ -32,24 +35,6 @@ pub enum MatchModeOperator {
     Any,
 }
 
-impl MatchModeOperator {
-    /// Apply the mode operator to two bools, lhs and rhs
-    fn apply(&self, lhs: bool, rhs: bool) -> bool {
-        match self {
-            MatchModeOperator::All => lhs && rhs,
-            MatchModeOperator::Any => lhs || rhs,
-        }
-    }
-
-    // https://en.wikipedia.org/wiki/Identity_element
-    fn neutral_element(&self) -> bool {
-        match self {
-            MatchModeOperator::All => true,
-            MatchModeOperator::Any => false,
-        }
-    }
-}
-
 #[api(
     properties: {
         name: {
@@ -121,6 +106,20 @@ pub struct MatcherConfig {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub invert_match: Option<bool>,
 
+    /// Match expression as inline JSON. This option is mutually exclusive with
+    /// the following options.
+    ///
+    ///   - match-field
+    ///   - match-calendar
+    ///   - match-severity
+    ///   - invert-match
+    ///   - mode
+    ///
+    /// All of the above can be represented as (sub)-expressions of this
+    /// expression.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub expression: Option<String>,
+
     /// Targets to notify.
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     #[updater(serde(skip_serializing_if = "Option::is_none"))]
@@ -146,57 +145,76 @@ trait MatchDirective {
 
 impl MatcherConfig {
     pub fn matches(&self, notification: &Notification) -> Result<Option<&[String]>, Error> {
-        let mode = self.mode.unwrap_or_default();
+        let expression = if let Some(expression_str) = &self.expression {
+            self.warn_about_ignored_properties();
 
-        let mut is_match = mode.neutral_element();
-        // If there are no matching directives, the matcher will always match
-        let mut no_matchers = true;
-
-        if !self.match_severity.is_empty() {
-            no_matchers = false;
-            is_match = mode.apply(
-                is_match,
-                self.check_matches(notification, &self.match_severity)?,
-            );
-        }
-        if !self.match_field.is_empty() {
-            no_matchers = false;
-            is_match = mode.apply(
-                is_match,
-                self.check_matches(notification, &self.match_field)?,
-            );
-        }
-        if !self.match_calendar.is_empty() {
-            no_matchers = false;
-            is_match = mode.apply(
-                is_match,
-                self.check_matches(notification, &self.match_calendar)?,
-            );
-        }
-
-        let invert_match = self.invert_match.unwrap_or_default();
-
-        Ok(if is_match != invert_match || no_matchers {
-            Some(&self.target)
+            serde_json::from_str(expression_str).map_err(|err| {
+                Error::FilterFailed(format!("could not deserialize filter expression: {err:#}"))
+            })?
         } else {
-            None
-        })
+            self.generate_expression_from_legacy_config()
+        };
+
+        // Later, once we have a notification history, we can also save the evaluated expression.
+        // This gives the user a trace of which rules matched and which did not.
+        let evaluated_expression = expression.evaluate(notification)?;
+
+        Ok(evaluated_expression
+            .is_match()
+            .then_some(self.target.as_slice()))
     }
 
-    /// Check if given `MatchDirectives` match a notification.
-    fn check_matches(
-        &self,
-        notification: &Notification,
-        matchers: &[impl MatchDirective],
-    ) -> Result<bool, Error> {
-        let mode = self.mode.unwrap_or_default();
-        let mut is_match = mode.neutral_element();
+    pub(crate) fn generate_expression_from_legacy_config(&self) -> Expression<NotificationMatcher> {
+        if self.match_severity.is_empty()
+            && self.match_field.is_empty()
+            && self.match_calendar.is_empty()
+        {
+            // No match clauses means that the matcher always matches.
+            // Also, 'invert-match' does not have any effect then.
+            return Expression::Constant(true);
+        }
+        let mut expressions = Vec::new();
 
-        for field_matcher in matchers {
-            is_match = mode.apply(is_match, field_matcher.matches(notification)?);
+        for m in self.match_calendar.clone() {
+            expressions.push(Expression::Match(NotificationMatcher::Calendar(
+                m.into_inner(),
+            )));
+        }
+        for m in self.match_field.clone() {
+            expressions.push(Expression::Match(NotificationMatcher::Field(
+                m.into_inner(),
+            )));
+        }
+        for m in self.match_severity.clone() {
+            expressions.push(Expression::Match(NotificationMatcher::Severity(
+                m.into_inner(),
+            )));
         }
 
-        Ok(is_match)
+        let root = match self.mode.unwrap_or_default() {
+            MatchModeOperator::All => Expression::AllOf(expressions),
+            MatchModeOperator::Any => Expression::AnyOf(expressions),
+        };
+
+        if self.invert_match.unwrap_or_default() {
+            Expression::Not(Box::new(root))
+        } else {
+            root
+        }
+    }
+
+    fn warn_about_ignored_properties(&self) {
+        if !self.match_severity.is_empty()
+            || !self.match_calendar.is_empty()
+            || !self.match_field.is_empty()
+            || self.mode.is_some()
+            || self.invert_match.is_some()
+        {
+            tracing::warn!(
+                "matcher '{}' has 'expression' set - 'match-*', 'invert-match' and 'mode' are ignored",
+                self.name
+            );
+        }
     }
 }
 
diff --git a/proxmox-notify/src/matcher/severity.rs b/proxmox-notify/src/matcher/severity.rs
index e12f2260..64472fab 100644
--- a/proxmox-notify/src/matcher/severity.rs
+++ b/proxmox-notify/src/matcher/severity.rs
@@ -1,14 +1,16 @@
 use std::fmt;
 use std::str::FromStr;
 
+use serde::{Deserialize, Serialize};
+
 use crate::{Error, Notification, Severity};
 
 use super::MatchDirective;
 
 /// Match severity of the notification.
-#[derive(Clone, Debug)]
+#[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct SeverityMatcher {
-    severities: Vec<Severity>,
+    pub(crate) severities: Vec<Severity>,
 }
 
 impl MatchDirective for SeverityMatcher {
-- 
2.47.3