sta/backend/src/domain/relay/repository.rs

use async_trait::async_trait;

use super::types::{RelayId, RelayLabel};

/// Errors that can occur during repository operations.
///
/// This enum provides structured error handling for all data persistence
/// operations related to relay management.
#[derive(Debug, thiserror::Error)]
pub enum RepositoryError {
    /// A database operation failed with the given error message.
    #[error("Database error: {0}")]
    DatabaseError(String),
    /// The requested relay was not found in the repository.
    #[error("Relay not found: {0}")]
    NotFound(RelayId),
}

/// Repository trait for persisting and retrieving relay labels.
///
/// This trait abstracts data persistence operations for relay labels,
/// enabling different storage implementations (e.g., `SQLite`, `PostgreSQL`, in-memory).
/// Implementations must be thread-safe (`Send + Sync`) for use in async contexts.
#[async_trait]
pub trait RelayLabelRepository: Send + Sync {
    /// Retrieves the label for a specific relay.
    ///
    /// Returns `None` if no label has been set for the relay.
    ///
    /// # Errors
    ///
    /// Returns `RepositoryError::DatabaseError` if the database operation fails.
    async fn get_label(&self, id: RelayId) -> Result<Option<RelayLabel>, RepositoryError>;

    /// Saves or updates the label for a specific relay.
    ///
    /// If a label already exists for the relay, it will be overwritten.
    ///
    /// # Errors
    ///
    /// Returns `RepositoryError::DatabaseError` if the database operation fails.
    async fn save_label(&self, id: RelayId, label: RelayLabel) -> Result<(), RepositoryError>;

    /// Retrieves all relay labels from the repository.
    ///
    /// Returns a vector of tuples containing relay IDs and their corresponding labels.
    /// Relays without labels are not included in the result.
    ///
    /// # Errors
    ///
    /// Returns `RepositoryError::DatabaseError` if the database operation fails.
    async fn get_all_labels(&self) -> Result<Vec<(RelayId, RelayLabel)>, RepositoryError>;
}