From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gate001.proxmox.com (gate001.proxmox.com [IPv6:2a0f:8001:1:32::40]) by lore.proxmox.com (Postfix) with ESMTPS id F20551FF0E0 for ; Thu, 09 Jul 2026 14:00:57 +0200 (CEST) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id 12B81217E0; Thu, 09 Jul 2026 13:58:21 +0200 (CEST) From: Lukas Wagner To: pbs-devel@lists.proxmox.com, pve-devel@lists.proxmox.com Subject: [PATCH proxmox 11/29] notify: matcher: add expression support Date: Thu, 9 Jul 2026 13:56:58 +0200 Message-ID: <20260709115716.299836-12-l.wagner@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20260709115716.299836-1-l.wagner@proxmox.com> References: <20260709115716.299836-1-l.wagner@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1783598238862 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.000 Adjusted score from AWL reputation of From: address DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment (newer systems) SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: B6D356QV6D73HTBZCBYC3RGD3AE4BKRE X-Message-ID-Hash: B6D356QV6D73HTBZCBYC3RGD3AE4BKRE X-MailFrom: l.wagner@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox Backup Server development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: 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 --- 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 { + 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 = 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, + values: Vec, }, Regex { field: String, - matched_regex: Regex, + #[serde(with = "serde_regex")] + regex: Regex, }, } impl MatchDirective for FieldMatcher { fn matches(&self, notification: &Notification) -> Result { 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, + /// 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, + /// 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, 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 { - let mode = self.mode.unwrap_or_default(); - let mut is_match = mode.neutral_element(); + pub(crate) fn generate_expression_from_legacy_config(&self) -> Expression { + 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, + pub(crate) severities: Vec, } impl MatchDirective for SeverityMatcher { -- 2.47.3