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 426FE1FF0B7 for ; Fri, 13 Nov 2026 16:18:04 +0100 (CET) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id 25BA521D99; Fri, 13 Nov 2026 16:10:23 +0100 (CET) From: Lukas Wagner To: pve-devel@lists.proxmox.com Subject: [PATCH proxmox 38/55] notify: add send receipts Date: Fri, 13 Nov 2026 16:08:11 +0100 Message-ID: <20261113150828.756836-39-l.wagner@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20261113150828.756836-1-l.wagner@proxmox.com> References: <20261113150828.756836-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: 1794582527838 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.201 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) RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust 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: 34JICNZ2XAEOMZQ37SBCRD4H3VRYTDOR X-Message-ID-Hash: 34JICNZ2XAEOMZQ37SBCRD4H3VRYTDOR 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 VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: Instead of only logging errors on proxmox_notify::send, return a receipt that includes information such as: - the evaluation results of matchers - which targets these matchers yielded - a per-target status, including errors if there were any Signed-off-by: Lukas Wagner --- proxmox-notify/src/api_types/matcher/mod.rs | 13 +- proxmox-notify/src/api_types/mod.rs | 3 + proxmox-notify/src/api_types/receipt.rs | 138 ++++++++++++++++ proxmox-notify/src/send.rs | 172 ++++++++++++++++---- 4 files changed, 287 insertions(+), 39 deletions(-) create mode 100644 proxmox-notify/src/api_types/receipt.rs diff --git a/proxmox-notify/src/api_types/matcher/mod.rs b/proxmox-notify/src/api_types/matcher/mod.rs index fe2b61a9d..6dd6d5bc5 100644 --- a/proxmox-notify/src/api_types/matcher/mod.rs +++ b/proxmox-notify/src/api_types/matcher/mod.rs @@ -1,6 +1,6 @@ use std::fmt::Debug; -use proxmox_match_expression::Expression; +use proxmox_match_expression::{EvaluatedExpressionWithResult, Expression}; use serde::{Deserialize, Serialize}; use proxmox_api_macro::api; @@ -150,7 +150,10 @@ trait MatchDirective { } impl MatcherConfig { - pub fn matches(&self, notification: &Notification) -> Result, Error> { + pub fn matches( + &self, + notification: &Notification, + ) -> Result, Error> { #[cfg(feature = "legacy-matchers")] self.warn_about_invalid_configuration(); @@ -178,9 +181,7 @@ impl MatcherConfig { // 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())) + Ok(evaluated_expression) } #[cfg(feature = "legacy-matchers")] @@ -407,7 +408,7 @@ mod tests { ..Default::default() }; - assert!(config.matches(¬ification).unwrap().is_some()) + assert!(config.matches(¬ification).unwrap().is_match()) } } diff --git a/proxmox-notify/src/api_types/mod.rs b/proxmox-notify/src/api_types/mod.rs index f3b381a8b..f445618c1 100644 --- a/proxmox-notify/src/api_types/mod.rs +++ b/proxmox-notify/src/api_types/mod.rs @@ -27,6 +27,9 @@ pub use matcher::*; mod schema; pub use schema::*; +mod receipt; +pub use receipt::*; + #[api] #[derive(Clone, Debug, Copy, Serialize, Deserialize, PartialEq, Eq, PartialOrd)] #[serde(rename_all = "kebab-case")] diff --git a/proxmox-notify/src/api_types/receipt.rs b/proxmox-notify/src/api_types/receipt.rs new file mode 100644 index 000000000..d05135ba3 --- /dev/null +++ b/proxmox-notify/src/api_types/receipt.rs @@ -0,0 +1,138 @@ +//! Types describing the outcome of sending a notification. +//! +//! Sending a notification yields a [`Receipt`], which records how the notification was routed and +//! whether it reached its destinations: +//! +//! - One [`MatcherReceipt`] per configured matcher, if the notification was routed through the +//! matchers. It states whether the matcher matched, did not match, was disabled or failed to +//! be evaluated. For evaluated matchers, it also contains the evaluated match expression, which +//! shows why the notification was or was not matched. +//! - One [`TargetReceipt`] per target the notification was dispatched to, stating whether the +//! notification was delivered, the target was disabled, or delivery failed. +//! +//! Delivery failures are reported in the receipt rather than as an error, so that the caller can +//! inspect the result of every single target, even if only some of them failed. + +use serde::{Deserialize, Serialize}; + +use proxmox_match_expression::EvaluatedExpressionWithResult; + +use crate::api_types::expression::NotificationMatcher; + +/// Outcome of sending a single notification. +/// +/// Records which matchers were evaluated and which targets the notification was dispatched to, +/// together with the result for each of them. +#[derive(Clone, Debug, Serialize, Deserialize)] +#[serde(rename_all = "kebab-case")] +pub struct Receipt { + pub(crate) target_receipts: Vec, + pub(crate) matcher_receipts: Vec, +} + +impl Receipt { + /// Returns the receipts of all targets the notification was dispatched to. + pub fn target_receipts(&self) -> &[TargetReceipt] { + &self.target_receipts + } + + /// Returns the receipts of all matchers that were evaluated for the notification. + /// + /// This is empty if the notification was sent to a target or email recipient directly, + /// without going through the matchers. + pub fn matcher_receipts(&self) -> &[MatcherReceipt] { + &self.matcher_receipts + } +} + +/// Result of dispatching a notification to a single target. +#[derive(Clone, Debug, Serialize, Deserialize)] +#[serde(rename_all = "kebab-case")] +pub struct TargetReceipt { + pub(crate) target: String, + #[serde(flatten)] + pub(crate) status: TargetReceiptStatus, + pub(crate) timestamp: i64, +} + +impl TargetReceipt { + /// Returns the name of the target. + pub fn target(&self) -> &str { + &self.target + } + + /// Returns the delivery status for this target. + pub fn status(&self) -> &TargetReceiptStatus { + &self.status + } + + /// Returns the time the delivery attempt finished, as seconds since the UNIX epoch. + pub fn timestamp(&self) -> i64 { + self.timestamp + } +} + +/// Delivery status of a notification for a single target. +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] +#[serde(rename_all = "kebab-case", tag = "status")] +pub enum TargetReceiptStatus { + /// The notification was -- to the best of our knowledge -- delivered successfully. + Delivered, + /// Target was disabled. + Disabled, + /// The notification was -- to the best of our knowledge -- not delivered to the recipient. + #[serde(rename_all = "kebab-case")] + Error { + /// Human-readable description of the error. + error_message: String, + }, +} + +/// Result of evaluating a single notification matcher. +#[derive(Clone, Debug, Serialize, Deserialize)] +#[serde(rename_all = "kebab-case", tag = "status")] +pub enum MatcherReceiptStatus { + /// The matcher's expression matched the notification. + #[serde(rename_all = "kebab-case")] + Matched { + /// The evaluated match expression, including the results of its sub-expressions. + evaluated_expression: EvaluatedExpressionWithResult, + /// Targets configured for this matcher, which the notification is dispatched to. + targets: Vec, + }, + /// The matcher's expression did not match the notification. + #[serde(rename_all = "kebab-case")] + NoMatch { + /// The evaluated match expression, including the results of its sub-expressions. + evaluated_expression: EvaluatedExpressionWithResult, + }, + /// Matcher was disabled and therefore not evaluated. + Disabled, + /// The matcher could not be evaluated. Its targets were not notified on its behalf. + #[serde(rename_all = "kebab-case")] + Error { + /// Human-readable description of the error. + error_message: String, + }, +} + +/// Result of evaluating a single notification matcher, identified by its name. +#[derive(Clone, Debug, Serialize, Deserialize)] +#[serde(rename_all = "kebab-case")] +pub struct MatcherReceipt { + pub(crate) matcher: String, + #[serde(flatten)] + pub(crate) status: MatcherReceiptStatus, +} + +impl MatcherReceipt { + /// Returns the name of the matcher. + pub fn matcher(&self) -> &str { + &self.matcher + } + + /// Returns the evaluation result of the matcher. + pub fn status(&self) -> &MatcherReceiptStatus { + &self.status + } +} diff --git a/proxmox-notify/src/send.rs b/proxmox-notify/src/send.rs index d08d5af30..9fc3864ed 100644 --- a/proxmox-notify/src/send.rs +++ b/proxmox-notify/src/send.rs @@ -3,7 +3,10 @@ use std::collections::{HashMap, HashSet}; use proxmox_section_config::typed::{convert_to_typed_array, lookup}; use tracing::{error, info}; -use crate::api_types::{MatcherConfig, SendmailConfig}; +use crate::api_types::{ + MatcherConfig, MatcherReceipt, MatcherReceiptStatus, Receipt, SendmailConfig, TargetReceipt, + TargetReceiptStatus, +}; use crate::config::{ConfigEntity, PrivateConfigEntity}; use crate::endpoints::Endpoint; use crate::endpoints::gotify::GotifyEndpoint; @@ -16,11 +19,13 @@ use crate::{Config, Context, EmailRecipient, Error, Notification, Recipient}; /// /// The caller is responsible for any needed permission checks. /// Returns an `anyhow::Error` in case of an error. -pub fn send(context: &Context, config: &Config, notification: &Notification) -> Result<(), Error> { +pub fn send( + context: &Context, + config: &Config, + notification: &Notification, +) -> Result { let bus = Bus::from_config(config)?; - bus.send(context, notification); - - Ok(()) + Ok(bus.send(context, notification)) } /// Notification bus - distributes notifications to all registered endpoints @@ -129,20 +134,43 @@ impl Bus { /// the notification. /// /// Any errors will not be returned but only logged. - pub fn send(&self, context: &Context, notification: &Notification) { + pub fn send(&self, context: &Context, notification: &Notification) -> Receipt { + let mut target_receipts = Vec::new(); + let mut matcher_receipts = Vec::new(); + match notification.recipient() { - Recipient::Email(params) => self.send_to_email(context, notification, params), + Recipient::Email(params) => { + target_receipts.push(self.send_to_email(context, notification, params)) + } Recipient::Target(target) => { - self.send_to_target(context, notification, target); + target_receipts.push(self.send_to_target(context, notification, target)); } Recipient::Matcher => { - let targets = self.check_matches(notification); + matcher_receipts = self.check_matches(notification); - for target in targets { - self.send_to_target(context, notification, target); + let (matching_matchers, targets) = + Self::matching_matchers_and_targets_from_receipts(&matcher_receipts); + + if !matching_matchers.is_empty() { + info!( + "notification matched the following matchers: {}. The following targets will be notified: {}", + matching_matchers.join(", "), + targets.join(", ") + ); + } else { + info!("notification was not matched by any matcher"); + } + + for target in &targets { + target_receipts.push(self.send_to_target(context, notification, target)); } } } + + Receipt { + target_receipts, + matcher_receipts, + } } fn send_to_email( @@ -150,7 +178,7 @@ impl Bus { context: &Context, notification: &Notification, email_recipient: &EmailRecipient, - ) { + ) -> TargetReceipt { let recipient_list = email_recipient.mailto.join(", "); let endpoint = SendmailEndpoint { @@ -165,72 +193,150 @@ impl Bus { match endpoint.send(context, notification) { Ok(_) => { info!("notified via `{recipient_list}`"); + TargetReceipt { + target: "legacy-sendmail".into(), + status: TargetReceiptStatus::Delivered, + timestamp: proxmox_time::epoch_i64(), + } } Err(e) => { // Only log on errors, do not propagate fail to the caller. error!("could not notify via `{recipient_list}`: {e}"); + TargetReceipt { + target: "legacy-sendmail".into(), + status: TargetReceiptStatus::Error { + error_message: e.to_string(), + }, + timestamp: proxmox_time::epoch_i64(), + } } } } - fn send_to_target(&self, context: &Context, notification: &Notification, target: &str) { + fn send_to_target( + &self, + context: &Context, + notification: &Notification, + target: &str, + ) -> TargetReceipt { if let Some(endpoint) = self.endpoints.get(target) { let name = endpoint.name(); if endpoint.disabled() { // Skip this target if it is disabled info!("skipping disabled target '{name}'"); - return; + + return TargetReceipt { + target: name.to_string(), + status: TargetReceiptStatus::Disabled, + timestamp: proxmox_time::epoch_i64(), + }; } match endpoint.send(context, notification) { Ok(_) => { info!("notified via target `{name}`"); + TargetReceipt { + target: name.to_string(), + status: TargetReceiptStatus::Delivered, + timestamp: proxmox_time::epoch_i64(), + } } Err(e) => { // Only log on errors, do not propagate fail to the caller. error!("could not notify via target `{name}`: {e}"); + TargetReceipt { + target: name.to_string(), + status: TargetReceiptStatus::Error { + error_message: e.to_string(), + }, + timestamp: proxmox_time::epoch_i64(), + } } } } else { error!("could not notify via target '{target}', it does not exist"); + TargetReceipt { + target: target.to_string(), + status: TargetReceiptStatus::Error { + error_message: Error::target_does_not_exist(target).to_string(), + }, + timestamp: proxmox_time::epoch_i64(), + } } } - fn check_matches(&self, notification: &Notification) -> HashSet<&str> { - let mut targets = HashSet::new(); - let mut matching_matchers = Vec::new(); + fn check_matches(&self, notification: &Notification) -> Vec { + let mut receipts = Vec::new(); for matcher in &self.matchers { + let name = matcher.name.clone(); + if matcher.disable.unwrap_or_default() { // Skip this matcher if it is disabled - info!("skipping disabled matcher '{name}'", name = matcher.name); + info!("skipping disabled matcher '{name}'"); + + receipts.push(MatcherReceipt { + matcher: name, + status: MatcherReceiptStatus::Disabled, + }); + continue; } match matcher.matches(notification) { - Ok(Some(t)) => { - matching_matchers.push(matcher.name.as_str()); - targets.extend(t.iter().map(|s| s.as_str())); + Ok(evaluated_expression) => { + if evaluated_expression.is_match() { + receipts.push(MatcherReceipt { + matcher: name, + status: MatcherReceiptStatus::Matched { + evaluated_expression, + targets: matcher.target.clone(), + }, + }); + } else { + receipts.push(MatcherReceipt { + matcher: name, + status: MatcherReceiptStatus::NoMatch { + evaluated_expression, + }, + }); + } + } + Err(err) => { + receipts.push(MatcherReceipt { + matcher: name, + status: MatcherReceiptStatus::Error { + error_message: err.to_string(), + }, + }); + error!("matcher '{matcher}' failed: {err}", matcher = matcher.name); } - Ok(None) => {} - Err(err) => error!("matcher '{matcher}' failed: {err}", matcher = matcher.name), } } - if !matching_matchers.is_empty() { - let target_list = Vec::from_iter(targets.iter().copied()); + receipts + } - info!( - "notification matched the following matchers: {}. The following targets will be notified: {}", - matching_matchers.join(", "), - target_list.join(", ") - ); - } else { - info!("notification was not matched by any matcher"); + fn matching_matchers_and_targets_from_receipts( + matcher_receipts: &[MatcherReceipt], + ) -> (Vec, Vec) { + let mut matchers = Vec::new(); + let mut deduplicated_targets = HashSet::new(); + + for receipt in matcher_receipts { + if let MatcherReceiptStatus::Matched { targets, .. } = &receipt.status { + matchers.push(receipt.matcher.clone()); + deduplicated_targets.extend(targets); + } } - targets + let mut targets = Vec::from_iter(deduplicated_targets.into_iter().cloned()); + targets.sort(); + + matchers.sort(); + + (matchers, targets) } } -- 2.47.3