footing 0.6.5

Feature-gated foundations for Rust backend services
Documentation
use std::fmt;

use serde::{Deserialize, Deserializer, Serialize, Serializer};
use serde_json::{Map, Value};
use thiserror::Error;

use crate::result::{ClassifyError, ErrorKind};

/// Maximum supported event name length.
pub const MAX_EVENT_NAME_LENGTH: usize = 128;
/// Maximum supported event field length.
pub const MAX_EVENT_FIELD_LENGTH: usize = 512;

#[derive(Clone, PartialEq, Serialize, Deserialize)]
#[non_exhaustive]
#[serde(try_from = "DomainEventWire")]
/// A domain event with JSON metadata.
///
/// All fields are serialized, including absent optional values. Binary Serde
/// formats encode metadata as a JSON string so arbitrary JSON values round-trip
/// without requiring a self-describing binary format.
/// Subject, actor, idempotency, and correlation identifiers are preserved verbatim.
/// When present, they must be nonempty, no longer than [`MAX_EVENT_FIELD_LENGTH`]
/// bytes, and free of control characters and surrounding whitespace. Metadata keys
/// additionally use lowercase ASCII letters, digits, underscores, dots, or hyphens.
/// Invalid input is rejected, never truncated.
pub struct DomainEvent {
    name: String,
    subject: Option<String>,
    actor: Option<String>,
    idempotency_key: Option<String>,
    correlation_id: Option<String>,
    #[serde(serialize_with = "serialize_metadata")]
    metadata: Map<String, Value>,
}

impl fmt::Debug for DomainEvent {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("DomainEvent")
            .field("name", &self.name)
            .field("subject", &self.subject.as_ref().map(|_| "[REDACTED]"))
            .field("actor", &self.actor.as_ref().map(|_| "[REDACTED]"))
            .field(
                "idempotency_key",
                &self.idempotency_key.as_ref().map(|_| "[REDACTED]"),
            )
            .field(
                "correlation_id",
                &self.correlation_id.as_ref().map(|_| "[REDACTED]"),
            )
            .field("metadata", &"[REDACTED]")
            .field("metadata_fields", &self.metadata.len())
            .finish()
    }
}

impl DomainEvent {
    /// Creates an event with a validated name and empty optional fields.
    pub fn new(name: impl Into<String>) -> Result<Self, DomainEventError> {
        Ok(Self {
            name: normalize_event_name(name)?,
            subject: None,
            actor: None,
            idempotency_key: None,
            correlation_id: None,
            metadata: Map::new(),
        })
    }

    /// Sets a validated subject.
    pub fn with_subject(mut self, subject: impl Into<String>) -> Result<Self, DomainEventError> {
        self.subject = Some(event_field(subject.into(), "subject")?);
        Ok(self)
    }

    /// Sets a validated actor.
    pub fn with_actor(mut self, actor: impl Into<String>) -> Result<Self, DomainEventError> {
        self.actor = Some(event_field(actor.into(), "actor")?);
        Ok(self)
    }

    /// Sets a validated idempotency key without changing its identity.
    pub fn with_idempotency_key(
        mut self,
        key: impl Into<String>,
    ) -> Result<Self, DomainEventError> {
        self.idempotency_key = Some(event_field(key.into(), "idempotency_key")?);
        Ok(self)
    }

    /// Sets a validated correlation identifier.
    pub fn with_correlation_id(mut self, id: impl Into<String>) -> Result<Self, DomainEventError> {
        self.correlation_id = Some(event_field(id.into(), "correlation_id")?);
        Ok(self)
    }

    /// Replaces metadata after validating every key.
    pub fn with_metadata(mut self, metadata: Map<String, Value>) -> Result<Self, DomainEventError> {
        validate_metadata(&metadata)?;
        self.metadata = metadata;
        Ok(self)
    }

    /// Sets a metadata value after validating its key.
    pub fn with_metadata_value(
        mut self,
        key: impl Into<String>,
        value: impl Into<Value>,
    ) -> Result<Self, DomainEventError> {
        let key = key.into();
        validate_metadata_key(&key)?;
        self.metadata.insert(key, value.into());
        Ok(self)
    }

    #[must_use]
    /// Returns the validated event name.
    pub fn name(&self) -> &str {
        &self.name
    }

    #[must_use]
    /// Returns the subject.
    pub fn subject(&self) -> Option<&str> {
        self.subject.as_deref()
    }

    #[must_use]
    /// Returns the actor.
    pub fn actor(&self) -> Option<&str> {
        self.actor.as_deref()
    }

    #[must_use]
    /// Returns the idempotency key.
    pub fn idempotency_key(&self) -> Option<&str> {
        self.idempotency_key.as_deref()
    }

    #[must_use]
    /// Returns the correlation identifier.
    pub fn correlation_id(&self) -> Option<&str> {
        self.correlation_id.as_deref()
    }

    #[must_use]
    /// Returns the metadata.
    pub const fn metadata(&self) -> &Map<String, Value> {
        &self.metadata
    }
}

#[derive(Deserialize)]
struct DomainEventWire {
    name: String,
    #[serde(default)]
    subject: Option<String>,
    #[serde(default)]
    actor: Option<String>,
    #[serde(default)]
    idempotency_key: Option<String>,
    #[serde(default)]
    correlation_id: Option<String>,
    #[serde(default, deserialize_with = "deserialize_metadata")]
    metadata: Map<String, Value>,
}

fn serialize_metadata<S: Serializer>(
    metadata: &Map<String, Value>,
    serializer: S,
) -> Result<S::Ok, S::Error> {
    if serializer.is_human_readable() {
        metadata.serialize(serializer)
    } else {
        serde_json::to_string(metadata)
            .map_err(serde::ser::Error::custom)?
            .serialize(serializer)
    }
}

fn deserialize_metadata<'de, D: Deserializer<'de>>(
    deserializer: D,
) -> Result<Map<String, Value>, D::Error> {
    if deserializer.is_human_readable() {
        Map::deserialize(deserializer)
    } else {
        let json = String::deserialize(deserializer)?;
        serde_json::from_str(&json).map_err(serde::de::Error::custom)
    }
}

impl TryFrom<DomainEventWire> for DomainEvent {
    type Error = DomainEventError;

    fn try_from(value: DomainEventWire) -> Result<Self, Self::Error> {
        let name = normalize_event_name(value.name)?;
        validate_metadata(&value.metadata)?;
        Ok(Self {
            name,
            subject: value
                .subject
                .map(|v| event_field(v, "subject"))
                .transpose()?,
            actor: value.actor.map(|v| event_field(v, "actor")).transpose()?,
            idempotency_key: value
                .idempotency_key
                .map(|v| event_field(v, "idempotency_key"))
                .transpose()?,
            correlation_id: value
                .correlation_id
                .map(|v| event_field(v, "correlation_id"))
                .transpose()?,
            metadata: value.metadata,
        })
    }
}

#[derive(Debug, Clone, PartialEq, Eq, Error)]
#[non_exhaustive]
/// Errors that can occur while handling domain event.
pub enum DomainEventError {
    #[error("domain event name must not be empty")]
    /// The name is empty.
    EmptyName,
    #[error("domain event name must be less than or equal to {max} bytes")]
    /// The name exceeds the supported length.
    NameTooLong {
        #[doc = "The configured upper bound."]
        max: usize,
    },
    #[error("domain event name contains unsupported characters")]
    /// The name is invalid.
    InvalidName,
    #[error("domain event {field} is invalid")]
    /// A supplied identifier or metadata key violates the field constraints.
    InvalidField {
        /// The field whose value failed validation; never contains input data.
        field: &'static str,
    },
}

impl ClassifyError for DomainEventError {
    fn error_kind(&self) -> ErrorKind {
        ErrorKind::Validation
    }

    fn error_code(&self) -> crate::result::ErrorCode {
        crate::result::ErrorCode::internal(match self {
            Self::EmptyName => "domain_event_empty_name",
            Self::NameTooLong { .. } => "domain_event_name_too_long",
            Self::InvalidName => "domain_event_invalid_name",
            Self::InvalidField { .. } => "domain_event_invalid_field",
        })
    }
}

fn normalize_event_name(value: impl Into<String>) -> Result<String, DomainEventError> {
    let value = value.into().trim().to_owned();
    if value.is_empty() {
        return Err(DomainEventError::EmptyName);
    }
    if value.len() > MAX_EVENT_NAME_LENGTH {
        return Err(DomainEventError::NameTooLong {
            max: MAX_EVENT_NAME_LENGTH,
        });
    }
    if !value
        .bytes()
        .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'.')
    {
        return Err(DomainEventError::InvalidName);
    }
    Ok(value)
}

fn event_field(value: String, field: &'static str) -> Result<String, DomainEventError> {
    if value.is_empty()
        || value.len() > MAX_EVENT_FIELD_LENGTH
        || value.trim() != value
        || value.chars().any(char::is_control)
    {
        return Err(DomainEventError::InvalidField { field });
    }
    Ok(value)
}

fn validate_metadata(metadata: &Map<String, Value>) -> Result<(), DomainEventError> {
    metadata
        .keys()
        .try_for_each(|key| validate_metadata_key(key))
}

fn validate_metadata_key(value: &str) -> Result<(), DomainEventError> {
    if value.is_empty()
        || value.len() > MAX_EVENT_FIELD_LENGTH
        || !value.bytes().all(|byte| {
            byte.is_ascii_lowercase() || byte.is_ascii_digit() || matches!(byte, b'_' | b'.' | b'-')
        })
    {
        return Err(DomainEventError::InvalidField {
            field: "metadata_key",
        });
    }
    Ok(())
}