From: Lukas Wagner <l.wagner@proxmox.com>
To: pve-devel@lists.proxmox.com
Subject: [PATCH proxmox 37/55] notify: replace notification instantiation with builder pattern
Date: Fri, 13 Nov 2026 16:08:10 +0100 [thread overview]
Message-ID: <20261113150828.756836-38-l.wagner@proxmox.com> (raw)
In-Reply-To: <20261113150828.756836-1-l.wagner@proxmox.com>
This makes constructing a notification quite a bit more ergonomic, and
allows us to add new optional fields later without issues.
For the template data, we now handle serialization ourselves instead of
taking serde_json::Value.
It would have been possible to provide the old functions alongside the
new ones, but since this change is performed in the context of larger,
breaking changes anyway, a clean break seemed appropriate.
Signed-off-by: Lukas Wagner <l.wagner@proxmox.com>
---
.../src/api_types/matcher/calendar.rs | 6 +-
proxmox-notify/src/api_types/matcher/field.rs | 27 ++-
proxmox-notify/src/api_types/matcher/mod.rs | 6 +-
.../src/api_types/matcher/severity.rs | 10 +-
proxmox-notify/src/endpoints/webhook.rs | 14 +-
proxmox-notify/src/notification.rs | 169 +++++++++++++-----
proxmox-notify/src/send.rs | 20 +--
7 files changed, 167 insertions(+), 85 deletions(-)
diff --git a/proxmox-notify/src/api_types/matcher/calendar.rs b/proxmox-notify/src/api_types/matcher/calendar.rs
index 738b14cf8..25109cd83 100644
--- a/proxmox-notify/src/api_types/matcher/calendar.rs
+++ b/proxmox-notify/src/api_types/matcher/calendar.rs
@@ -140,8 +140,10 @@ mod test {
#[test]
fn test_calendar_matcher() {
- let mut notification =
- Notification::from_template(Severity::Notice, "test", Value::Null, Default::default());
+ let mut notification = Notification::template_builder("test", Value::Null)
+ .severity(Severity::Notice)
+ .build()
+ .unwrap();
// Fr 22 Mai 2026 12:45:00 CEST
notification.metadata.timestamp = 1779446700;
diff --git a/proxmox-notify/src/api_types/matcher/field.rs b/proxmox-notify/src/api_types/matcher/field.rs
index a00d46c3e..0bd0e5387 100644
--- a/proxmox-notify/src/api_types/matcher/field.rs
+++ b/proxmox-notify/src/api_types/matcher/field.rs
@@ -231,10 +231,13 @@ pub mod inline {
#[test]
fn test_matching() {
let mut fields = HashMap::new();
- fields.insert("foo".into(), "bar".into());
+ fields.insert("foo".to_string(), "bar".to_string());
- let notification =
- Notification::from_template(Severity::Notice, "test", Value::Null, fields);
+ let notification = Notification::template_builder("test", Value::Null)
+ .fields(fields)
+ .severity(Severity::Notice)
+ .build()
+ .unwrap();
let matcher: InlineFieldMatcher = "exact:foo=bar".parse().unwrap();
assert!(matcher.matches(¬ification).unwrap());
@@ -249,17 +252,23 @@ pub mod inline {
assert!(matcher.matches(¬ification).unwrap());
let mut fields = HashMap::new();
- fields.insert("foo".into(), "test".into());
+ fields.insert("foo".to_string(), "test".to_string());
- let notification =
- Notification::from_template(Severity::Notice, "test", Value::Null, fields);
+ let notification = Notification::template_builder("test", Value::Null)
+ .fields(fields)
+ .severity(Severity::Notice)
+ .build()
+ .unwrap();
assert!(matcher.matches(¬ification).unwrap());
let mut fields = HashMap::new();
- fields.insert("foo".into(), "notthere".into());
+ fields.insert("foo".to_string(), "notthere".to_string());
- let notification =
- Notification::from_template(Severity::Notice, "test", Value::Null, fields);
+ let notification = Notification::template_builder("test", Value::Null)
+ .fields(fields)
+ .severity(Severity::Notice)
+ .build()
+ .unwrap();
assert!(!matcher.matches(¬ification).unwrap());
assert!("regex:'3=b.*".parse::<InlineFieldMatcher>().is_err());
diff --git a/proxmox-notify/src/api_types/matcher/mod.rs b/proxmox-notify/src/api_types/matcher/mod.rs
index e65063c5e..fe2b61a9d 100644
--- a/proxmox-notify/src/api_types/matcher/mod.rs
+++ b/proxmox-notify/src/api_types/matcher/mod.rs
@@ -395,8 +395,10 @@ mod tests {
use crate::Severity;
use serde_json::Value;
- let notification =
- Notification::from_template(Severity::Notice, "test", Value::Null, Default::default());
+ let notification = Notification::template_builder("test", Value::Null)
+ .severity(Severity::Notice)
+ .build()
+ .unwrap();
for mode in [MatchModeOperator::All, MatchModeOperator::Any] {
let config = MatcherConfig {
diff --git a/proxmox-notify/src/api_types/matcher/severity.rs b/proxmox-notify/src/api_types/matcher/severity.rs
index ed0278888..9bd3019f1 100644
--- a/proxmox-notify/src/api_types/matcher/severity.rs
+++ b/proxmox-notify/src/api_types/matcher/severity.rs
@@ -103,12 +103,10 @@ pub mod inline {
#[test]
fn test_severities() {
- let notification = Notification::from_template(
- Severity::Notice,
- "test",
- Value::Null,
- Default::default(),
- );
+ let notification = Notification::template_builder("test", Value::Null)
+ .severity(Severity::Notice)
+ .build()
+ .unwrap();
let matcher: InlineSeverityMatcher = "info,notice,warning,error".parse().unwrap();
assert!(matcher.matches(¬ification).unwrap());
diff --git a/proxmox-notify/src/endpoints/webhook.rs b/proxmox-notify/src/endpoints/webhook.rs
index 2eaa71633..05ae325ea 100644
--- a/proxmox-notify/src/endpoints/webhook.rs
+++ b/proxmox-notify/src/endpoints/webhook.rs
@@ -309,18 +309,11 @@ fn handlebars_escape(
#[cfg(test)]
mod tests {
- use std::collections::HashMap;
-
use super::*;
use crate::{Severity, api_types::KeyAndBase64Val, context::test};
#[test]
fn test_build_request() {
- let data = HashMap::from_iter([
- ("hello".into(), "hello world".into()),
- ("test".into(), "escaped\nstring".into()),
- ]);
-
let body_template = r#"
{{ fields.test }}
{{ escape fields.test }}
@@ -365,7 +358,12 @@ hello%20world
},
};
- let notification = Notification::from_template(Severity::Info, "foo", json!({}), data);
+ let notification = Notification::template_builder("foo", json!({}))
+ .severity(Severity::Info)
+ .field("hello", "hello world")
+ .field("test", "escaped\nstring")
+ .build()
+ .unwrap();
let context = test::test_context();
diff --git a/proxmox-notify/src/notification.rs b/proxmox-notify/src/notification.rs
index 88940bcf5..41667ef44 100644
--- a/proxmox-notify/src/notification.rs
+++ b/proxmox-notify/src/notification.rs
@@ -133,42 +133,36 @@ pub struct Notification {
}
impl Notification {
- pub fn from_template<S: AsRef<str>>(
- severity: Severity,
+ /// Create a builder for a notification that is rendered from a template.
+ pub fn template_builder<S: Into<String>, D: Serialize>(
template_name: S,
- template_data: Value,
- fields: HashMap<String, String>,
- ) -> Self {
- Self {
- metadata: Metadata {
- severity,
- additional_fields: fields,
- timestamp: proxmox_time::epoch_i64(),
- },
- content: Content::Template {
- template_name: template_name.as_ref().to_string(),
- data: template_data,
- },
- id: Uuid::generate(),
- recipient: Recipient::Matcher,
+ template_data: D,
+ ) -> NotificationBuilder {
+ let template_name = template_name.into();
+
+ let content = serde_json::to_value(template_data)
+ .map_err(|err| Error::other_with_source("could not serialize template data type", err))
+ .map(move |value| Content::Template {
+ template_name,
+ data: value,
+ });
+
+ NotificationBuilder {
+ severity: None,
+ content,
+ fields: Default::default(),
+ recipient: Default::default(),
}
}
- pub fn new_forwarded_mail(
- severity: Severity,
- raw_mail: Vec<u8>,
- fields: HashMap<String, String>,
- ) -> Result<Self, Error> {
- Ok(Self {
- content: Content::ForwardedMail { raw: raw_mail },
- metadata: Metadata {
- severity,
- additional_fields: fields,
- timestamp: proxmox_time::epoch_i64(),
- },
- id: Uuid::generate(),
- recipient: Recipient::Matcher,
- })
+ /// Create a builder for a notification that forwards a raw mail.
+ pub fn forwarded_mail_builder(raw_mail: Vec<u8>) -> NotificationBuilder {
+ NotificationBuilder {
+ severity: None,
+ content: Ok(Content::ForwardedMail { raw: raw_mail }),
+ fields: Default::default(),
+ recipient: Default::default(),
+ }
}
/// Return the unique ID of this notification.
@@ -202,6 +196,65 @@ impl Notification {
}
}
+/// Builder for [`Notification`].
+///
+/// Created via [`Notification::template_builder`] or [`Notification::forwarded_mail_builder`].
+#[derive(Debug)]
+pub struct NotificationBuilder {
+ severity: Option<Severity>,
+ content: Result<Content, Error>,
+ fields: HashMap<String, String>,
+ recipient: Recipient,
+}
+
+impl NotificationBuilder {
+ /// Set the severity of the notification.
+ ///
+ /// If not set, the severity will default to [`Severity::Unknown`].
+ pub fn severity(mut self, severity: Severity) -> Self {
+ self.severity = Some(severity);
+ self
+ }
+
+ /// Add a single metadata field, replacing any previous value for the same key.
+ pub fn field<K: Into<String>, V: Into<String>>(mut self, key: K, value: V) -> Self {
+ self.fields.insert(key.into(), value.into());
+ self
+ }
+
+ /// Add multiple metadata fields, replacing any previous values for the same keys.
+ pub fn fields<I, K, V>(mut self, fields: I) -> Self
+ where
+ I: IntoIterator<Item = (K, V)>,
+ K: Into<String>,
+ V: Into<String>,
+ {
+ self.fields
+ .extend(fields.into_iter().map(|(k, v)| (k.into(), v.into())));
+ self
+ }
+
+ /// Set the recipient of the notification. Defaults to [`Recipient::Matcher`].
+ pub fn recipient(mut self, recipient: Recipient) -> Self {
+ self.recipient = recipient;
+ self
+ }
+
+ /// Build the notification, assigning a new unique ID and the current time as timestamp.
+ pub fn build(self) -> Result<Notification, Error> {
+ Ok(Notification {
+ content: self.content?,
+ metadata: Metadata {
+ severity: self.severity.unwrap_or(Severity::Unknown),
+ timestamp: proxmox_time::epoch_i64(),
+ additional_fields: self.fields,
+ },
+ id: Uuid::generate(),
+ recipient: self.recipient,
+ })
+ }
+}
+
#[cfg(test)]
mod tests {
use serde_json::json;
@@ -249,15 +302,29 @@ mod tests {
}
#[test]
- fn from_template() {
- let fields = HashMap::from([("hostname".to_string(), "pve".to_string())]);
+ fn template_builder() {
let data = json!({"key": "value"});
- let notification =
- Notification::from_template(Severity::Warning, "test", data.clone(), fields.clone());
+ let notification = Notification::template_builder("test", data.clone())
+ .severity(Severity::Error)
+ .field("hostname", "pve")
+ .fields([("type", "vzdump"), ("hostname", "pbs")])
+ .recipient(Recipient::Target("mail-to-root".into()))
+ .build()
+ .unwrap();
- assert_eq!(notification.severity(), Severity::Warning);
- assert_eq!(notification.fields(), &fields);
+ assert_eq!(notification.severity(), Severity::Error);
+ assert_eq!(
+ notification.fields(),
+ &HashMap::from([
+ ("hostname".to_string(), "pbs".to_string()),
+ ("type".to_string(), "vzdump".to_string()),
+ ])
+ );
+ assert_eq!(
+ notification.recipient,
+ Recipient::Target("mail-to-root".into())
+ );
assert_eq!(
notification.content,
Content::Template {
@@ -268,22 +335,24 @@ mod tests {
}
#[test]
- fn new_forwarded_mail() {
+ fn forwarded_mail_builder() {
let raw = TEST_MAIL.to_vec();
- let notification =
- Notification::new_forwarded_mail(Severity::Unknown, raw.clone(), HashMap::new())
- .unwrap();
+ let notification = Notification::forwarded_mail_builder(raw.clone())
+ .build()
+ .unwrap();
assert_eq!(notification.severity(), Severity::Unknown);
assert!(notification.fields().is_empty());
+ assert_eq!(notification.recipient, Recipient::Matcher);
assert_eq!(notification.content, Content::ForwardedMail { raw });
}
#[test]
fn fields_mut() {
- let mut notification =
- Notification::from_template(Severity::Info, "test", Value::Null, HashMap::new());
+ let mut notification = Notification::template_builder("test", Value::Null)
+ .build()
+ .unwrap();
notification
.fields_mut()
@@ -331,9 +400,17 @@ mod tests {
#[test]
fn serde_roundtrip() {
let fields = HashMap::from([("hostname".to_string(), "pve".to_string())]);
+
let notifications = [
- Notification::from_template(Severity::Error, "test", json!({"a": [1, 2]}), fields),
- Notification::new_forwarded_mail(Severity::Info, TEST_MAIL.to_vec(), HashMap::new())
+ Notification::template_builder("test", json!({"a": [1, 2]}))
+ .severity(Severity::Info)
+ .fields(fields.clone())
+ .build()
+ .unwrap(),
+ Notification::forwarded_mail_builder(TEST_MAIL.to_vec())
+ .severity(Severity::Unknown)
+ .fields(fields)
+ .build()
.unwrap(),
];
diff --git a/proxmox-notify/src/send.rs b/proxmox-notify/src/send.rs
index 42cd0bb1a..d08d5af30 100644
--- a/proxmox-notify/src/send.rs
+++ b/proxmox-notify/src/send.rs
@@ -308,12 +308,10 @@ mod tests {
// Send directly to endpoint
bus.send(
&context,
- &Notification::from_template(
- Severity::Info,
- "test",
- Default::default(),
- Default::default(),
- ),
+ &Notification::template_builder("test", None::<()>)
+ .severity(Severity::Info)
+ .build()
+ .unwrap(),
);
let messages = mock.messages();
assert_eq!(messages.len(), 1);
@@ -358,12 +356,10 @@ mod tests {
});
let send_with_severity = |severity| {
- let notification = Notification::from_template(
- severity,
- "test",
- Default::default(),
- Default::default(),
- );
+ let notification = Notification::template_builder("test", None::<()>)
+ .severity(severity)
+ .build()
+ .unwrap();
bus.send(&context, ¬ification);
};
--
2.47.3
next prev parent reply other threads:[~2026-11-13 15:16 UTC|newest]
Thread overview: 58+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-13 15:07 [PATCH many 00/55] notify: maintenance, PDM preparations, queue + worker Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 01/55] notify: disallow `unsafe` code Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 02/55] notify: refactor error type Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 03/55] notify: move `Endpoint` trait to endpoint module as pub(crate) Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 04/55] notify: use ConfigDigest instead of raw byte arrays Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 05/55] notify: remove static context and pass context as parameter Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 06/55] notify: matcher: drop unused field matcher verifiers Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 07/55] notify: introduce 'send-impl', 'api-impl' and 'api-types' features Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 08/55] notify: matcher: make matcher validation methods public Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 09/55] notify: make SendmailEndpoint and SmtpEndpoint private types Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 10/55] notify: move `send`, `test_target` and `Bus` to new `send` module Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 11/55] notify: move Origin type to api_types module Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 12/55] notify: move Target " Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 13/55] notify: move Config to config module Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 14/55] notify: move Notification and sub-types to `notification` module Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 15/55] notify: move schema module to api_types Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 16/55] notify: move check_matches from api_types::matcher to send::Bus Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 17/55] notify: move TemplateSource to context module Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 18/55] notify: config: cleanup helpers names and visibility Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 19/55] notify: config: rename section config parser/writer methods Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 20/55] notify: config: pass builtins explicitly when parsing section config Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 21/55] notify: implement PartialEq for all Config types Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 22/55] notify: use typed SectionConfigData Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 23/55] notify: api: api types: rename Deleteable* -> Deletable* Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 24/55] notify: context: parse builtin config only once Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 25/55] notify: context: parse proxy config in trait impl, not at the callsite Lukas Wagner
2026-11-13 15:07 ` [PATCH proxmox 26/55] notify: gate sub-modules with the appropriate feature flags Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox 27/55] notify: fold mail-forwarder feature into send-impl Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox 28/55] notify: forwarded mails: don't hardcode severity and metadata fields Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox 29/55] notify: don't pass uid when instantiating forwarded mail notifications Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox 30/55] notify: derive PartialEq for Notification type Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox 31/55] notify: add getters for severity and fields on " Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox 32/55] notify: add test suite for " Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox 33/55] notify: serialize raw, forwarded mail content as base64 Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox 34/55] notify: unify code paths for legacy-sendmail and regular notifications Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox 35/55] notify: add backwards-compat note to Notification type Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox 36/55] notify: remove 'test_target' API Lukas Wagner
2026-11-13 15:08 ` Lukas Wagner [this message]
2026-11-13 15:08 ` [PATCH proxmox 38/55] notify: add send receipts Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox 39/55] notify: implement notification queue submitter Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox 40/55] notify: context: add read_config Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox 41/55] notify: queue: add queue consumer Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox 42/55] notify: queue: add worker task Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox-backup 43/55] notifications: don't ignore verification errors in legacy-sendmail mode Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox-backup 44/55] notifications: adapt to proxmox-notify API changes Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox-backup 45/55] api: notification: send test notification via proxmox_notify::send Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox-backup 46/55] notifications: send all notifications via proxmox-notify's queue Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox-perl-rs 47/55] pve: notify: adapt to changes in the public API of proxmox-notify Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox-perl-rs 48/55] pve: notify: add `PVE::RS::Notify::enqueue` method Lukas Wagner
2026-11-13 15:08 ` [PATCH pve-cluster 49/55] notify: send notifications via notification queue Lukas Wagner
2026-11-13 15:08 ` [PATCH manager 50/55] vzdump: send legacy-sendmail notifications via simplified API Lukas Wagner
2026-11-13 15:08 ` [PATCH manager 51/55] pve-notify-worker: add new rust-based notification worker daemon Lukas Wagner
2026-11-13 15:08 ` [PATCH manager 52/55] debian: add 'pve-notify-worker' as a dependency Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox-mail-forward 53/55] forward mails via notification queue Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox-mail-forward 54/55] use return code to signal permanent or temporary failure Lukas Wagner
2026-11-13 15:08 ` [PATCH proxmox-mail-forward 55/55] limit size of mail read from stdin Lukas Wagner
2026-11-17 9:35 ` [PATCH many 00/55] notify: maintenance, PDM preparations, queue + worker Lukas Wagner
2026-11-18 9:55 ` superseded: " Lukas Wagner
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20261113150828.756836-38-l.wagner@proxmox.com \
--to=l.wagner@proxmox.com \
--cc=pve-devel@lists.proxmox.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.