aster_forge_tasks/

runtime_metadata.rs

//! Runtime task metadata registration helpers.
//!
//! Product crates still own their runtime task enum and presentation codes. This module only
//! provides compact definition types plus helpers that generate consistent lookup and wire-format
//! handling from one registration list. This keeps product-specific task catalogs in the product
//! crate while Forge owns the boring mechanics: stable string encoding, legacy string fallback, and
//! display-name derivation for unknown historical task names.

use serde::{Deserialize, Serialize};

/// Product-owned runtime task metadata registered with Forge helpers.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct RuntimeTaskDefinition<Kind, PresentationCode> {
    /// Product-owned task enum variant.
    pub kind: Kind,
    /// Stable wire value stored in task payloads.
    pub wire_value: &'static str,
    /// Operator-facing display name.
    pub display_name: &'static str,
    /// Product-owned presentation code for UI/i18n mapping.
    pub presentation_code: PresentationCode,
}

/// Lookup contract implemented by product-owned runtime task enums.
///
/// Implementations should normally delegate to the module generated by
/// [`crate::runtime_task_registry!`]. Forge uses this trait to provide product-neutral
/// serialization and display helpers without owning the task enum itself.
pub trait RegisteredRuntimeTaskKind: Copy {
    /// Returns the stable wire value stored in task payloads.
    fn as_str(self) -> &'static str;

    /// Returns the operator-facing display name for this runtime task.
    fn display_name(self) -> &'static str;

    /// Decodes a runtime task kind from a stable wire value.
    fn from_wire_value(value: &str) -> Option<Self>;
}

/// Runtime task name stored in product payloads.
///
/// Known names decode to the product-owned task enum. Unknown values are preserved as legacy
/// strings so old database rows, removed tasks, or future task kinds can still be displayed and
/// round-tripped instead of failing deserialization.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum RuntimeTaskName<K> {
    /// A task kind registered by the product crate.
    Known(K),
    /// A historical or otherwise unknown wire value.
    Legacy(String),
}

impl<K> RuntimeTaskName<K>
where
    K: RegisteredRuntimeTaskKind,
{
    /// Builds a known task name from a product-owned task kind.
    pub const fn from_kind(kind: K) -> Self {
        Self::Known(kind)
    }

    /// Parses a task name from a stored wire value, preserving unknown values as legacy strings.
    pub fn parse(value: impl Into<String>) -> Self {
        let value = value.into();
        K::from_wire_value(&value)
            .map(Self::Known)
            .unwrap_or(Self::Legacy(value))
    }

    /// Returns the stable wire value.
    pub fn as_str(&self) -> &str {
        match self {
            Self::Known(kind) => kind.as_str(),
            Self::Legacy(value) => value.as_str(),
        }
    }

    /// Returns a display name for operator-facing UI.
    pub fn display_name(&self) -> String {
        match self {
            Self::Known(kind) => kind.display_name().to_string(),
            Self::Legacy(value) => value.replace('-', " "),
        }
    }

    /// Returns the decoded product task kind when this name is known.
    pub fn known_kind(&self) -> Option<K> {
        match self {
            Self::Known(kind) => Some(*kind),
            Self::Legacy(_) => None,
        }
    }

    /// Returns the decoded product task kind when this name is known.
    ///
    /// This is an ergonomic alias for [`RuntimeTaskName::known_kind`].
    pub fn known(&self) -> Option<K> {
        self.known_kind()
    }
}

impl<K> From<K> for RuntimeTaskName<K>
where
    K: RegisteredRuntimeTaskKind,
{
    fn from(value: K) -> Self {
        Self::Known(value)
    }
}

impl<K> From<String> for RuntimeTaskName<K>
where
    K: RegisteredRuntimeTaskKind,
{
    fn from(value: String) -> Self {
        Self::parse(value)
    }
}

impl<K> From<&str> for RuntimeTaskName<K>
where
    K: RegisteredRuntimeTaskKind,
{
    fn from(value: &str) -> Self {
        Self::parse(value)
    }
}

impl<K> std::fmt::Display for RuntimeTaskName<K>
where
    K: RegisteredRuntimeTaskKind,
{
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter.write_str(self.as_str())
    }
}

impl<K> Serialize for RuntimeTaskName<K>
where
    K: RegisteredRuntimeTaskKind,
{
    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serializer.serialize_str(self.as_str())
    }
}

impl<'de, K> Deserialize<'de> for RuntimeTaskName<K>
where
    K: RegisteredRuntimeTaskKind,
{
    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        String::deserialize(deserializer).map(Self::parse)
    }
}

/// Generates product-local runtime task metadata lookup functions.
///
/// The generated module exposes:
///
/// - `DEFINITIONS`
/// - `as_str(kind)`
/// - `display_name(kind)`
/// - `presentation_code(kind)`
/// - `from_wire_value(value)`
///
/// This keeps runtime task wire values, display names, and presentation codes registered in one
/// product-local place while preserving product-owned enums and UI codes.
#[macro_export]
macro_rules! runtime_task_registry {
    (
        $(#[$meta:meta])*
        $vis:vis mod $module:ident {
            kind: $kind:ty;
            presentation: $presentation:ty;
            tasks {
                $(
                    $kind_value:path => {
                        wire: $wire:literal,
                        display: $display:literal,
                        presentation: $presentation_value:path $(,)?
                    }
                ),+ $(,)?
            }
        }
    ) => {
        $(#[$meta])*
        $vis mod $module {
            /// Registered runtime task definitions in product order.
            pub const DEFINITIONS: &[
                $crate::RuntimeTaskDefinition<$kind, $presentation>
            ] = &[
                $(
                    $crate::RuntimeTaskDefinition {
                        kind: $kind_value,
                        wire_value: $wire,
                        display_name: $display,
                        presentation_code: $presentation_value,
                    },
                )+
            ];

            /// Returns the stable wire value for a registered runtime task kind.
            pub const fn as_str(kind: $kind) -> &'static str {
                match kind {
                    $(
                        $kind_value => $wire,
                    )+
                }
            }

            /// Returns the operator-facing display name for a registered runtime task kind.
            pub const fn display_name(kind: $kind) -> &'static str {
                match kind {
                    $(
                        $kind_value => $display,
                    )+
                }
            }

            /// Returns the product-owned presentation code for a registered runtime task kind.
            pub const fn presentation_code(kind: $kind) -> $presentation {
                match kind {
                    $(
                        $kind_value => $presentation_value,
                    )+
                }
            }

            /// Decodes a runtime task kind from its stable wire value.
            pub fn from_wire_value(value: &str) -> Option<$kind> {
                match value {
                    $(
                        $wire => Some($kind_value),
                    )+
                    _ => None,
                }
            }

            #[cfg(test)]
            mod runtime_task_metadata_tests {
                use super::*;

                #[test]
                fn registered_runtime_task_metadata_is_consistent() {
                    for (index, definition) in DEFINITIONS.iter().enumerate() {
                        assert!(
                            !definition.wire_value.is_empty(),
                            "runtime task wire value at index {index} must not be empty"
                        );
                        assert!(
                            !definition.display_name.is_empty(),
                            "runtime task display name at index {index} must not be empty"
                        );
                        assert_eq!(as_str(definition.kind), definition.wire_value);
                        assert_eq!(display_name(definition.kind), definition.display_name);
                        assert_eq!(presentation_code(definition.kind), definition.presentation_code);
                        assert_eq!(from_wire_value(definition.wire_value), Some(definition.kind));
                    }

                    for (left_index, left) in DEFINITIONS.iter().enumerate() {
                        for right in DEFINITIONS.iter().skip(left_index + 1) {
                            assert_ne!(
                                left.wire_value,
                                right.wire_value,
                                "runtime task wire value '{}' is registered more than once",
                                left.wire_value
                            );
                        }
                    }
                }
            }
        }
    };
}

#[cfg(test)]
mod tests {
    use super::{RegisteredRuntimeTaskKind, RuntimeTaskName};

    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    enum TestRuntimeTaskKind {
        Cleanup,
        Health,
    }

    impl RegisteredRuntimeTaskKind for TestRuntimeTaskKind {
        fn as_str(self) -> &'static str {
            match self {
                Self::Cleanup => "cleanup",
                Self::Health => "system-health",
            }
        }

        fn display_name(self) -> &'static str {
            match self {
                Self::Cleanup => "Cleanup",
                Self::Health => "System health",
            }
        }

        fn from_wire_value(value: &str) -> Option<Self> {
            match value {
                "cleanup" => Some(Self::Cleanup),
                "system-health" => Some(Self::Health),
                _ => None,
            }
        }
    }

    #[test]
    fn runtime_task_name_round_trips_known_values() {
        let name = RuntimeTaskName::<TestRuntimeTaskKind>::from("system-health");

        assert_eq!(name.known_kind(), Some(TestRuntimeTaskKind::Health));
        assert_eq!(name.as_str(), "system-health");
        assert_eq!(name.display_name(), "System health");
        assert_eq!(name.to_string(), "system-health");
        assert_eq!(
            serde_json::to_string(&name).expect("known task name should serialize"),
            r#""system-health""#
        );
    }

    #[test]
    fn runtime_task_name_preserves_legacy_values() {
        let name = RuntimeTaskName::<TestRuntimeTaskKind>::from("old-maintenance-job");

        assert_eq!(name.known_kind(), None);
        assert_eq!(name.as_str(), "old-maintenance-job");
        assert_eq!(name.display_name(), "old maintenance job");
        assert_eq!(
            serde_json::to_string(&name).expect("legacy task name should serialize"),
            r#""old-maintenance-job""#
        );
    }

    #[test]
    fn runtime_task_name_deserializes_known_and_legacy_values() {
        let known: RuntimeTaskName<TestRuntimeTaskKind> =
            serde_json::from_str(r#""cleanup""#).expect("known task name should deserialize");
        let legacy: RuntimeTaskName<TestRuntimeTaskKind> =
            serde_json::from_str(r#""removed-task""#).expect("legacy task name should deserialize");

        assert_eq!(known.known_kind(), Some(TestRuntimeTaskKind::Cleanup));
        assert_eq!(legacy.known_kind(), None);
        assert_eq!(legacy.as_str(), "removed-task");
    }
}