[pve-devel] [PATCH v3 proxmox 02/66] notify: preparation for the first endpoint plugin

[Maximiliano Sandoval]

Lukas Wagner <l.wagner at proxmox.com> writes:

> 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           | 311 ++++++++++++++++++++++++++++
>  proxmox-notify/src/schema.rs        |  43 ++++
>  6 files changed, 415 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 317593f0..ef8a050a 100644
> --- a/Cargo.toml
> +++ b/Cargo.toml
> @@ -93,6 +93,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! {

Ideally this uses once_cell::sync::Lazy.

> +    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);

unneeded mut keyword

> +
> +    config
> +}
> +
> +fn private_config_init() -> SectionConfig {
> +    let mut config = SectionConfig::new(&BACKEND_NAME_SCHEMA);

Ditto

> +
> +    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..7b90ee15 100644
> --- a/proxmox-notify/src/lib.rs
> +++ b/proxmox-notify/src/lib.rs
> @@ -0,0 +1,311 @@
> +use std::collections::HashMap;
> +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>),
> +    TargetDoesNotExist(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::TargetDoesNotExist(target) => {
> +                write!(f, "notification target '{target}' does not exist")
> +            }
> +        }
> +    }
> +}
> +
> +impl StdError for Error {
> +    fn source(&self) -> Option<&(dyn StdError + 'static)> {
> +        match self {
> +            Error::ConfigSerialization(err) => Some(&**err),

Does this really need the double deref?

> +            Error::ConfigDeserialization(err) => Some(&**err),
> +            Error::NotifyFailed(_, err) => Some(&**err),
> +            Error::TargetDoesNotExist(_) => 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 {

Might be good to derive Debug here.

> +    config: SectionConfigData,
> +    private_config: SectionConfigData,
> +    digest: [u8; 32],
> +    private_digest: [u8; 32],
> +}
> +
> +impl Clone for Config {

You can just derive Clone on Config, in general if a Copy type does the correct
thing they will be copied when clone() is called.

> +    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)?,
> +        ))
> +    }
> +
> +    /// Returns the SHA256 digest of the configuration.
> +    /// The digest is only computed once when the configuration deserialized.
> +    pub fn digest(&self) -> &[u8; 32] {
> +        &self.digest
> +    }
> +}
> +
> +/// 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: HashMap<String, 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 {
> +    /// Instantiate notification bus from a given configuration.
> +    pub fn from_config(config: &Config) -> Result<Self, Error> {

We are not using the config here? underscore config -> `_config`.

> +        let mut endpoints = HashMap::new();

Remove this mut.

> +
> +        Ok(Bus { endpoints })
> +    }
> +
> +    #[cfg(test)]
> +    pub fn add_endpoint(&mut self, endpoint: Box<dyn Endpoint>) {
> +        self.endpoints.insert(endpoint.name().to_string(), endpoint);
> +    }
> +
> +    pub fn send(&self, target: &str, notification: &Notification) -> Result<(), Error> {
> +        log::info!(
> +            "sending notification with title '{title}'",
> +            title = notification.title
> +        );
> +
> +        let endpoint = self
> +            .endpoints
> +            .get(target)
> +            .ok_or(Error::TargetDoesNotExist(target.into()))?;

Clippy: Use ok_or_else here 📎

> +
> +        endpoint.send(notification).unwrap_or_else(|e| {
> +            log::error!(
> +                "could not notfiy via endpoint `{name}`: {e}",

typo notfiy.

> +                name = endpoint.name()
> +            )
> +        });
> +
> +        Ok(())
> +    }
> +
> +    pub fn test_target(&self, target: &str) -> Result<(), Error> {
> +        let endpoint = self
> +            .endpoints
> +            .get(target)
> +            .ok_or(Error::TargetDoesNotExist(target.into()))?;

ok_or_else 📎

> +
> +        endpoint.send(&Notification {
> +            severity: Severity::Info,
> +            title: "Test notification".into(),
> +            body: "This is a test of the notification target '{{ target }}'".into(),
> +            properties: Some(json!({ "target": target })),
> +        })?;
> +
> +        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 {

nit, maybe this trait method should return a static str instead.

> +            "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(
> +            "mock-endpoint",
> +            &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..68f11959
> --- /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 groups")
> +        .format(&PROXMOX_SAFE_ID_FORMAT)
> +        .min_length(2)
> +        .max_length(32)
> +        .schema();

nit, maybe these could go on the top.