[pve-devel] [PATCH v2 proxmox 05/42] notify: preparation for the first endpoint plugin
Lukas Wagner
l.wagner at proxmox.com
Wed May 24 15:56:12 CEST 2023
Signed-off-by: Lukas Wagner <l.wagner at proxmox.com>
---
Cargo.toml | 1 +
proxmox-notify/Cargo.toml | 9 +
proxmox-notify/src/config.rs | 51 +++++
proxmox-notify/src/endpoints/mod.rs | 0
proxmox-notify/src/lib.rs | 299 ++++++++++++++++++++++++++++
proxmox-notify/src/schema.rs | 43 ++++
6 files changed, 403 insertions(+)
create mode 100644 proxmox-notify/src/config.rs
create mode 100644 proxmox-notify/src/endpoints/mod.rs
create mode 100644 proxmox-notify/src/schema.rs
diff --git a/Cargo.toml b/Cargo.toml
index f8a691a1..1003022e 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -94,6 +94,7 @@ proxmox-lang = { version = "1.1", path = "proxmox-lang" }
proxmox-rest-server = { version = "0.4.0", path = "proxmox-rest-server" }
proxmox-router = { version = "1.3.1", path = "proxmox-router" }
proxmox-schema = { version = "1.3.7", path = "proxmox-schema" }
+proxmox-section-config = { version = "1.0.2", path = "proxmox-section-config" }
proxmox-serde = { version = "0.1.1", path = "proxmox-serde", features = [ "serde_json" ] }
proxmox-sortable-macro = { version = "0.1.2", path = "proxmox-sortable-macro" }
proxmox-sys = { version = "0.5.0", path = "proxmox-sys" }
diff --git a/proxmox-notify/Cargo.toml b/proxmox-notify/Cargo.toml
index 2e69d5b0..37d175f0 100644
--- a/proxmox-notify/Cargo.toml
+++ b/proxmox-notify/Cargo.toml
@@ -8,3 +8,12 @@ repository.workspace = true
exclude.workspace = true
[dependencies]
+lazy_static.workspace = true
+log.workspace = true
+openssl.workspace = true
+proxmox-schema = { workspace = true, features = ["api-macro"]}
+proxmox-section-config = { workspace = true }
+proxmox-sys.workspace = true
+regex.workspace = true
+serde.workspace = true
+serde_json.workspace = true
diff --git a/proxmox-notify/src/config.rs b/proxmox-notify/src/config.rs
new file mode 100644
index 00000000..362ca0fc
--- /dev/null
+++ b/proxmox-notify/src/config.rs
@@ -0,0 +1,51 @@
+use lazy_static::lazy_static;
+use proxmox_schema::{ApiType, ObjectSchema};
+use proxmox_section_config::{SectionConfig, SectionConfigData, SectionConfigPlugin};
+
+use crate::schema::BACKEND_NAME_SCHEMA;
+use crate::Error;
+
+lazy_static! {
+ pub static ref CONFIG: SectionConfig = config_init();
+ pub static ref PRIVATE_CONFIG: SectionConfig = private_config_init();
+}
+
+fn config_init() -> SectionConfig {
+ let mut config = SectionConfig::new(&BACKEND_NAME_SCHEMA);
+
+ config
+}
+
+fn private_config_init() -> SectionConfig {
+ let mut config = SectionConfig::new(&BACKEND_NAME_SCHEMA);
+
+ config
+}
+
+pub fn config(raw_config: &str) -> Result<(SectionConfigData, [u8; 32]), Error> {
+ let digest = openssl::sha::sha256(raw_config.as_bytes());
+ let data = CONFIG
+ .parse("notifications.cfg", raw_config)
+ .map_err(|err| Error::ConfigDeserialization(err.into()))?;
+ Ok((data, digest))
+}
+
+pub fn private_config(raw_config: &str) -> Result<(SectionConfigData, [u8; 32]), Error> {
+ let digest = openssl::sha::sha256(raw_config.as_bytes());
+ let data = PRIVATE_CONFIG
+ .parse("priv/notifications.cfg", raw_config)
+ .map_err(|err| Error::ConfigDeserialization(err.into()))?;
+ Ok((data, digest))
+}
+
+pub fn write(config: &SectionConfigData) -> Result<String, Error> {
+ CONFIG
+ .write("notifications.cfg", config)
+ .map_err(|err| Error::ConfigSerialization(err.into()))
+}
+
+pub fn write_private(config: &SectionConfigData) -> Result<String, Error> {
+ PRIVATE_CONFIG
+ .write("priv/notifications.cfg", config)
+ .map_err(|err| Error::ConfigSerialization(err.into()))
+}
diff --git a/proxmox-notify/src/endpoints/mod.rs b/proxmox-notify/src/endpoints/mod.rs
new file mode 100644
index 00000000..e69de29b
diff --git a/proxmox-notify/src/lib.rs b/proxmox-notify/src/lib.rs
index e69de29b..a55d4e33 100644
--- a/proxmox-notify/src/lib.rs
+++ b/proxmox-notify/src/lib.rs
@@ -0,0 +1,299 @@
+use std::fmt::Display;
+
+use proxmox_schema::api;
+use proxmox_section_config::SectionConfigData;
+use serde::{Deserialize, Serialize};
+use serde_json::json;
+use serde_json::Value;
+
+use std::error::Error as StdError;
+
+mod config;
+pub mod endpoints;
+pub mod schema;
+
+#[derive(Debug)]
+pub enum Error {
+ ConfigSerialization(Box<dyn StdError + Send + Sync + 'static>),
+ ConfigDeserialization(Box<dyn StdError + Send + Sync + 'static>),
+ NotifyFailed(String, Box<dyn StdError + Send + Sync + 'static>),
+ EndpointDoesNotExist(String),
+}
+
+impl Display for Error {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ match self {
+ Error::ConfigSerialization(err) => {
+ write!(f, "could not serialize configuration: {err}")
+ }
+ Error::ConfigDeserialization(err) => {
+ write!(f, "could not deserialize configuration: {err}")
+ }
+ Error::NotifyFailed(endpoint, err) => {
+ write!(f, "could not notify via endpoint(s): {endpoint}: {err}")
+ }
+ Error::EndpointDoesNotExist(endpoint) => {
+ write!(f, "endpoint '{endpoint}' does not exist")
+ }
+ }
+ }
+}
+
+impl StdError for Error {
+ fn source(&self) -> Option<&(dyn StdError + 'static)> {
+ match self {
+ Error::ConfigSerialization(err) => Some(&**err),
+ Error::ConfigDeserialization(err) => Some(&**err),
+ Error::NotifyFailed(_, err) => Some(&**err),
+ Error::EndpointDoesNotExist(_) => None,
+ }
+ }
+}
+
+#[api()]
+#[derive(Clone, Debug, Copy, Serialize, Deserialize, PartialEq, Eq, PartialOrd)]
+#[serde(rename_all = "kebab-case")]
+/// Severity of a notification
+pub enum Severity {
+ /// General information
+ Info,
+ /// A noteworthy event
+ Notice,
+ /// Warning
+ Warning,
+ /// Error
+ Error,
+}
+
+/// Notification endpoint trait, implemented by all endpoint plugins
+pub trait Endpoint {
+ /// Send a documentation
+ fn send(&self, notification: &Notification) -> Result<(), Error>;
+
+ /// The name/identifier for this endpoint
+ fn name(&self) -> &str;
+}
+
+#[derive(Debug, Clone)]
+/// Notification which can be sent
+pub struct Notification {
+ /// Notification severity
+ pub severity: Severity,
+ /// The title of the notification
+ pub title: String,
+ /// Notification text
+ pub body: String,
+ /// Additional metadata for the notification
+ pub properties: Option<Value>,
+}
+
+/// Notification configuration
+pub struct Config {
+ config: SectionConfigData,
+ private_config: SectionConfigData,
+ digest: [u8; 32],
+ private_digest: [u8; 32],
+}
+
+impl Clone for Config {
+ fn clone(&self) -> Self {
+ Self {
+ config: SectionConfigData {
+ sections: self.config.sections.clone(),
+ order: self.config.order.clone(),
+ },
+ private_config: SectionConfigData {
+ sections: self.private_config.sections.clone(),
+ order: self.private_config.order.clone(),
+ },
+ digest: self.digest,
+ private_digest: self.private_digest,
+ }
+ }
+}
+
+impl Config {
+ /// Parse raw config
+ pub fn new(raw_config: &str, raw_private_config: &str) -> Result<Self, Error> {
+ let (config, digest) = config::config(raw_config)?;
+ let (private_config, private_digest) = config::private_config(raw_private_config)?;
+
+ Ok(Self {
+ config,
+ digest,
+ private_config,
+ private_digest,
+ })
+ }
+
+ /// Serialize config
+ pub fn write(&self) -> Result<(String, String), Error> {
+ Ok((
+ config::write(&self.config)?,
+ config::write_private(&self.private_config)?,
+ ))
+ }
+}
+
+/// Notification bus - distributes notifications to all registered endpoints
+// The reason for the split between `Config` and this struct is to make testing with mocked
+// endpoints a bit easier.
+#[derive(Default)]
+pub struct Bus {
+ endpoints: Vec<Box<dyn Endpoint>>,
+}
+
+#[allow(unused_macros)]
+macro_rules! parse_endpoints_with_private_config {
+ ($config:ident, $public_config:ty, $private_config:ty, $endpoint_type:ident, $type_name:expr) => {
+ (|| -> Result<Vec<Box<dyn Endpoint>>, Error> {
+ let mut endpoints: Vec<Box<dyn Endpoint>> = Vec::new();
+
+ let configs: Vec<$public_config> = $config
+ .config
+ .convert_to_typed_array($type_name)
+ .map_err(|err| Error::ConfigDeserialization(err.into()))?;
+
+ let private_configs: Vec<$private_config> = $config
+ .private_config
+ .convert_to_typed_array($type_name)
+ .map_err(|err| Error::ConfigDeserialization(err.into()))?;
+
+ for config in configs {
+ if let Some(private_config) = private_configs.iter().find(|p| p.name == config.name)
+ {
+ endpoints.push(Box::new($endpoint_type {
+ config,
+ private_config: private_config.clone(),
+ }));
+ } else {
+ log::error!(
+ "Could not instantiate endpoint '{name}': private config does not exist",
+ name = config.name
+ );
+ }
+ }
+
+ Ok(endpoints)
+ })()
+ };
+}
+
+#[allow(unused_macros)]
+macro_rules! parse_endpoints_without_private_config {
+ ($config:ident, $public_config:ty, $endpoint_type:ident, $type_name:expr) => {
+ (|| -> Result<Vec<Box<dyn Endpoint>>, Error> {
+ let mut endpoints: Vec<Box<dyn Endpoint>> = Vec::new();
+
+ let configs: Vec<$public_config> = $config
+ .config
+ .convert_to_typed_array($type_name)
+ .map_err(|err| Error::ConfigDeserialization(err.into()))?;
+
+ for config in configs {
+ endpoints.push(Box::new($endpoint_type { config }));
+ }
+
+ Ok(endpoints)
+ })()
+ };
+}
+
+impl Bus {
+ pub fn from_config(config: &Config) -> Result<Self, Error> {
+ let mut endpoints = Vec::new();
+
+ Ok(Bus { endpoints })
+ }
+
+ #[cfg(test)]
+ pub fn add_endpoint(&mut self, endpoint: Box<dyn Endpoint>) {
+ self.endpoints.push(endpoint);
+ }
+
+ /// Send a notification to all registered endpoints
+ pub fn send(&self, notification: &Notification) -> Result<(), Error> {
+ log::info!(
+ "sending notification with title '{title}'",
+ title = notification.title
+ );
+
+ for endpoint in &self.endpoints {
+ endpoint.send(notification).unwrap_or_else(|e| {
+ log::error!(
+ "could not notfiy via endpoint `{name}`: {e}",
+ name = endpoint.name()
+ )
+ })
+ }
+
+ Ok(())
+ }
+
+ pub fn test_endpoint(&self, endpoint_name: &str) -> Result<(), Error> {
+ let endpoint = self
+ .endpoints
+ .iter()
+ .find(|e| e.name() == endpoint_name)
+ .ok_or(Error::EndpointDoesNotExist(endpoint_name.into()))?;
+
+ endpoint.send(&Notification {
+ severity: Severity::Info,
+ title: "Test".into(),
+ body: "This is a test of the notification endpoint '{{ endpoint }}'".into(),
+ properties: Some(json!({ "endpoint": endpoint_name })),
+ })?;
+
+ Ok(())
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use std::{cell::RefCell, rc::Rc};
+
+ use super::*;
+
+ #[derive(Default, Clone)]
+ struct MockEndpoint {
+ messages: Rc<RefCell<Vec<Notification>>>,
+ }
+
+ impl Endpoint for MockEndpoint {
+ fn send(&self, message: &Notification) -> Result<(), Error> {
+ self.messages.borrow_mut().push(message.clone());
+
+ Ok(())
+ }
+
+ fn name(&self) -> &str {
+ "mock-endpoint"
+ }
+ }
+
+ impl MockEndpoint {
+ fn messages(&self) -> Vec<Notification> {
+ self.messages.borrow().clone()
+ }
+ }
+
+ #[test]
+ fn test_add_mock_endpoint() -> Result<(), Error> {
+ let mock = MockEndpoint::default();
+
+ let mut bus = Bus::default();
+
+ bus.add_endpoint(Box::new(mock.clone()));
+
+ bus.send(&Notification {
+ title: "Title".into(),
+ body: "Body".into(),
+ severity: Severity::Info,
+ properties: Default::default(),
+ })?;
+ let messages = mock.messages();
+ assert_eq!(messages.len(), 1);
+
+ Ok(())
+ }
+}
diff --git a/proxmox-notify/src/schema.rs b/proxmox-notify/src/schema.rs
new file mode 100644
index 00000000..dea1fdd0
--- /dev/null
+++ b/proxmox-notify/src/schema.rs
@@ -0,0 +1,43 @@
+use proxmox_schema::{const_regex, ApiStringFormat, Schema, StringSchema};
+
+// Copied from PBS
+macro_rules! proxmox_safe_id_regex_str {
+ () => {
+ r"(?:[A-Za-z0-9_][A-Za-z0-9._\-]*)"
+ };
+}
+
+const_regex! {
+ pub SINGLE_LINE_COMMENT_REGEX = r"^[[:^cntrl:]]*$";
+ pub PROXMOX_SAFE_ID_REGEX = concat!(r"^", proxmox_safe_id_regex_str!(), r"$");
+}
+
+const SINGLE_LINE_COMMENT_FORMAT: ApiStringFormat =
+ ApiStringFormat::Pattern(&SINGLE_LINE_COMMENT_REGEX);
+
+pub const COMMENT_SCHEMA: Schema = StringSchema::new("Comment.")
+ .format(&SINGLE_LINE_COMMENT_FORMAT)
+ .max_length(128)
+ .schema();
+
+pub const EMAIL_SCHEMA: Schema = StringSchema::new("E-Mail Address.")
+ .format(&SINGLE_LINE_COMMENT_FORMAT)
+ .min_length(2)
+ .max_length(64)
+ .schema();
+
+pub const PROXMOX_SAFE_ID_FORMAT: ApiStringFormat =
+ ApiStringFormat::Pattern(&PROXMOX_SAFE_ID_REGEX);
+
+pub const BACKEND_NAME_SCHEMA: Schema = StringSchema::new("Notification backend name.")
+ .format(&PROXMOX_SAFE_ID_FORMAT)
+ .min_length(3)
+ .max_length(32)
+ .schema();
+
+pub const ENTITY_NAME_SCHEMA: Schema =
+ StringSchema::new("Name schema for endpoints, filters and channels")
+ .format(&PROXMOX_SAFE_ID_FORMAT)
+ .min_length(2)
+ .max_length(32)
+ .schema();
--
2.30.2
More information about the pve-devel
mailing list