aster_forge_utils/

id.rs

//! UUID and token generation helpers.
//!
//! The module provides plain random tokens as well as retry helpers for business-unique UUIDs.
//! Callers remain responsible for enforcing uniqueness at the database layer, but the helpers
//! centralize collision retry loops and error messages.

use std::future::Future;

use uuid::Uuid;

/// Maximum number of UUID candidates generated by unique UUID helpers.
pub const UNIQUE_UUID_MAX_ATTEMPTS: usize = 5;

/// Result of attempting to reserve or accept a generated UUID.
pub enum UniqueUuidAttempt<T> {
    /// Candidate was accepted and produced a value.
    Accepted(T),
    /// Candidate collided and should be retried with a new UUID.
    Collision,
}

/// Generates a UUID v4 string.
pub fn new_uuid() -> String {
    Uuid::new_v4().to_string()
}

fn unique_uuid_exhausted_message(value_name: &str) -> String {
    format!("failed to create unique {value_name} UUID after {UNIQUE_UUID_MAX_ATTEMPTS} attempts")
}

/// Runs an operation with a business-unique UUID and caller-owned error type.
///
/// The callback receives a fresh UUID candidate on every attempt. Returning
/// [`UniqueUuidAttempt::Collision`] asks the helper to retry with a new candidate, while returning
/// an error stops immediately and gives that error back to the caller. If all candidates collide,
/// the standard retry-budget error is converted into the caller's error type.
pub async fn with_unique_uuid<F, Fut, T, E>(
    value_name: &str,
    mut try_candidate: F,
) -> std::result::Result<T, E>
where
    F: FnMut(Uuid) -> Fut,
    Fut: Future<Output = std::result::Result<UniqueUuidAttempt<T>, E>>,
    E: From<crate::UtilsError>,
{
    for attempt in 1..=UNIQUE_UUID_MAX_ATTEMPTS {
        let candidate = Uuid::new_v4();
        match try_candidate(candidate).await? {
            UniqueUuidAttempt::Accepted(value) => return Ok(value),
            UniqueUuidAttempt::Collision => {
                tracing::warn!(
                    value_name,
                    attempt,
                    candidate = %candidate,
                    "uuid collision, retrying"
                );
            }
        }
    }

    Err(crate::UtilsError::invalid_value(unique_uuid_exhausted_message(value_name)).into())
}

/// Generates a business UUID and filters occupied candidates through caller-provided lookup.
///
/// This helper does not atomically reserve the value; callers must still rely on a database
/// uniqueness constraint in the later write path. Use [`with_unique_uuid`] when check-and-reserve
/// semantics are needed, and perform the write inside the callback.
pub async fn new_best_effort_uuid<F, Fut, E>(
    value_name: &str,
    mut is_taken: F,
) -> std::result::Result<Uuid, E>
where
    F: FnMut(Uuid) -> Fut,
    Fut: Future<Output = std::result::Result<bool, E>>,
    E: From<crate::UtilsError>,
{
    with_unique_uuid(value_name, |candidate| {
        let taken = is_taken(candidate);
        async move {
            if taken.await? {
                Ok(UniqueUuidAttempt::Collision)
            } else {
                Ok(UniqueUuidAttempt::Accepted(candidate))
            }
        }
    })
    .await
}

/// Generates a short 32-character hex token.
pub fn new_short_token() -> String {
    Uuid::new_v4().simple().to_string()
}

/// Generates an ephemeral runtime instance identifier.
///
/// Runtime IDs are process-level identifiers for ownership and notification
/// echo filtering. They are intentionally not stable business IDs or
/// deployment node names.
pub fn new_runtime_id() -> String {
    format!("runtime-{}", new_short_token())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{Result, UtilsError};
    use std::sync::{
        Arc,
        atomic::{AtomicUsize, Ordering},
    };

    #[tokio::test]
    async fn new_best_effort_uuid_returns_first_free_candidate() {
        let attempts = Arc::new(AtomicUsize::new(0));
        let result: Result<Uuid> = new_best_effort_uuid("test value", {
            let attempts = Arc::clone(&attempts);
            move |_| {
                let attempts = Arc::clone(&attempts);
                async move {
                    attempts.fetch_add(1, Ordering::SeqCst);
                    Ok(false)
                }
            }
        })
        .await;

        assert!(result.is_ok());
        assert_eq!(attempts.load(Ordering::SeqCst), 1);
    }

    #[tokio::test]
    async fn with_unique_uuid_retries_collisions_and_returns_callback_value() {
        let attempts = Arc::new(AtomicUsize::new(0));
        let result: Result<String> = with_unique_uuid("test value", {
            let attempts = Arc::clone(&attempts);
            move |candidate| {
                let attempts = Arc::clone(&attempts);
                async move {
                    let attempt = attempts.fetch_add(1, Ordering::SeqCst);
                    if attempt < 2 {
                        Ok(UniqueUuidAttempt::Collision)
                    } else {
                        Ok(UniqueUuidAttempt::Accepted(candidate.to_string()))
                    }
                }
            }
        })
        .await;
        let result = result.expect("third candidate should be accepted");

        assert!(Uuid::parse_str(&result).is_ok());
        assert_eq!(attempts.load(Ordering::SeqCst), 3);
    }

    #[tokio::test]
    async fn with_unique_uuid_propagates_callback_errors_without_retrying() {
        let attempts = Arc::new(AtomicUsize::new(0));
        let result: Result<String> = with_unique_uuid("test value", {
            let attempts = Arc::clone(&attempts);
            move |_| {
                let attempts = Arc::clone(&attempts);
                async move {
                    attempts.fetch_add(1, Ordering::SeqCst);
                    Err(UtilsError::invalid_value("candidate check failed"))
                }
            }
        })
        .await;

        let error = result.expect_err("callback error should be returned");
        assert!(matches!(error, UtilsError::InvalidValue(_)));
        assert_eq!(attempts.load(Ordering::SeqCst), 1);
    }

    #[derive(Debug, PartialEq, Eq)]
    enum CustomUuidError {
        Callback,
        Exhausted(String),
    }

    impl From<UtilsError> for CustomUuidError {
        fn from(error: UtilsError) -> Self {
            Self::Exhausted(error.to_string())
        }
    }

    #[tokio::test]
    async fn with_unique_uuid_supports_caller_error_type() {
        let attempts = Arc::new(AtomicUsize::new(0));
        let result: std::result::Result<String, CustomUuidError> =
            with_unique_uuid("custom value", {
                let attempts = Arc::clone(&attempts);
                move |_| {
                    let attempts = Arc::clone(&attempts);
                    async move {
                        attempts.fetch_add(1, Ordering::SeqCst);
                        Err(CustomUuidError::Callback)
                    }
                }
            })
            .await;

        assert_eq!(result, Err(CustomUuidError::Callback));
        assert_eq!(attempts.load(Ordering::SeqCst), 1);
    }

    #[tokio::test]
    async fn with_unique_uuid_uses_caller_error_for_exhaustion() {
        let attempts = Arc::new(AtomicUsize::new(0));
        let result: std::result::Result<String, CustomUuidError> =
            with_unique_uuid("custom value", {
                let attempts = Arc::clone(&attempts);
                move |_| {
                    let attempts = Arc::clone(&attempts);
                    async move {
                        attempts.fetch_add(1, Ordering::SeqCst);
                        Ok(UniqueUuidAttempt::Collision)
                    }
                }
            })
            .await;

        assert_eq!(
            result,
            Err(CustomUuidError::Exhausted(
                "failed to create unique custom value UUID after 5 attempts".to_string()
            ))
        );
        assert_eq!(attempts.load(Ordering::SeqCst), UNIQUE_UUID_MAX_ATTEMPTS);
    }

    #[tokio::test]
    async fn new_best_effort_uuid_retries_taken_candidates() {
        let attempts = Arc::new(AtomicUsize::new(0));
        let result: Result<Uuid> = new_best_effort_uuid("test value", {
            let attempts = Arc::clone(&attempts);
            move |_| {
                let attempts = Arc::clone(&attempts);
                async move {
                    let attempt = attempts.fetch_add(1, Ordering::SeqCst);
                    Ok(attempt < 2)
                }
            }
        })
        .await;

        assert!(result.is_ok());
        assert_eq!(attempts.load(Ordering::SeqCst), 3);
    }

    #[tokio::test]
    async fn new_best_effort_uuid_stops_after_retry_budget_is_exhausted() {
        let attempts = Arc::new(AtomicUsize::new(0));
        let result: Result<Uuid> = new_best_effort_uuid("test value", {
            let attempts = Arc::clone(&attempts);
            move |_| {
                let attempts = Arc::clone(&attempts);
                async move {
                    attempts.fetch_add(1, Ordering::SeqCst);
                    Ok(true)
                }
            }
        })
        .await;

        let error = result.expect_err("all candidates were reported as taken");
        assert!(matches!(error, UtilsError::InvalidValue(_)));
        assert_eq!(attempts.load(Ordering::SeqCst), UNIQUE_UUID_MAX_ATTEMPTS);
    }

    #[test]
    fn new_short_token_uses_uuid_v4_hex_entropy() {
        let token = new_short_token();

        assert_eq!(token.len(), 32);
        assert!(!token.contains('-'));
        assert!(Uuid::parse_str(&token).is_ok());
    }

    #[test]
    fn new_runtime_id_uses_runtime_prefix_and_uuid_entropy() {
        let runtime_id = new_runtime_id();
        let token = runtime_id
            .strip_prefix("runtime-")
            .expect("runtime id should use runtime prefix");

        assert_eq!(token.len(), 32);
        assert!(Uuid::parse_str(token).is_ok());
    }
}