Refactoring de l'API rest des musicsources

pmosource/src/pmoserver_ext.rs

@@ -0,0 +1,188 @@
+//! # Music Source Extension Trait
+//!
+//! Ce module définit le trait d'extension [`MusicSourceExt`] qui permet d'ajouter
+//! facilement la gestion des sources musicales à un serveur `pmoserver::Server`.
+//!
+//! ## Architecture
+//!
+//! Ce trait suit le pattern d'extension utilisé par les autres crates de l'écosystème
+//! PMOMusic (`pmocovers`, `pmoaudiocache`, `pmoqobuz`, etc.). Il permet à `pmosource`
+//! d'étendre `pmoserver::Server` sans que `pmoserver` ne connaisse `pmosource`.
+//!
+//! ## Exemple d'utilisation
+//!
+//! ```rust,ignore
+//! use pmosource::{MusicSourceExt, MusicSource};
+//! use pmoserver::ServerBuilder;
+//! use std::sync::Arc;
+//!
+//! # async fn example() -> anyhow::Result<()> {
+//! let mut server = ServerBuilder::new_configured().build();
+//!
+//! // Initialiser le gestionnaire de sources avec API
+//! server.init_music_sources().await?;
+//!
+//! // Enregistrer une source
+//! let source: Arc<dyn MusicSource> = Arc::new(MySource::new());
+//! server.register_music_source(source).await;
+//!
+//! // Lister les sources
+//! let sources = server.list_music_sources().await;
+//! println!("{} sources registered", sources.len());
+//!
+//! server.start().await;
+//! # Ok(())
+//! # }
+//! ```
+
+use crate::MusicSource;
+use anyhow::Result;
+use std::sync::Arc;
+
+/// Extension trait pour ajouter la gestion des sources musicales à un serveur
+///
+/// Ce trait étend `pmoserver::Server` avec des fonctionnalités de gestion de sources
+/// musicales, incluant :
+/// - Enregistrement de sources implémentant [`MusicSource`]
+/// - API REST pour lister et gérer les sources
+/// - Documentation OpenAPI automatique
+/// - Intégration avec le registre global de sources
+///
+/// # Thread Safety
+///
+/// Toutes les opérations sont thread-safe et utilisent un registre partagé
+/// accessible via `Arc<SourceRegistry>`.
+///
+/// # Examples
+///
+/// ```rust,ignore
+/// use pmosource::MusicSourceExt;
+/// use pmoserver::ServerBuilder;
+///
+/// let mut server = ServerBuilder::new_configured().build();
+///
+/// // Initialiser le système de sources (enregistre les routes API)
+/// server.init_music_sources().await?;
+///
+/// // Le serveur est maintenant prêt à accepter des sources
+/// ```
+#[cfg_attr(feature = "server", async_trait::async_trait)]
+pub trait MusicSourceExt {
+    /// Initialise le système de gestion des sources musicales
+    ///
+    /// Cette méthode :
+    /// 1. Initialise le registre global de sources
+    /// 2. Enregistre les routes API REST (`/api/sources/*`)
+    /// 3. Configure la documentation OpenAPI
+    ///
+    /// Cette méthode doit être appelée avant d'enregistrer des sources.
+    ///
+    /// # Returns
+    ///
+    /// `Ok(())` si l'initialisation réussit.
+    ///
+    /// # Errors
+    ///
+    /// Retourne une erreur si le système de sources est déjà initialisé
+    /// ou si l'enregistrement des routes échoue.
+    ///
+    /// # Examples
+    ///
+    /// ```rust,ignore
+    /// server.init_music_sources().await?;
+    /// ```
+    #[cfg(feature = "server")]
+    async fn init_music_sources(&mut self) -> Result<()>;
+
+    /// Enregistre une source musicale
+    ///
+    /// Ajoute une source au registre global, la rendant disponible pour
+    /// les clients UPnP et l'API REST.
+    ///
+    /// # Arguments
+    ///
+    /// * `source` - La source musicale à enregistrer (implémente [`MusicSource`])
+    ///
+    /// # Examples
+    ///
+    /// ```rust,ignore
+    /// let source = Arc::new(QobuzSource::new(client, base_url));
+    /// server.register_music_source(source).await;
+    /// ```
+    #[cfg(feature = "server")]
+    async fn register_music_source(&mut self, source: Arc<dyn MusicSource>);
+
+    /// Désenregistre une source musicale par son ID
+    ///
+    /// Retire la source du registre global.
+    ///
+    /// # Arguments
+    ///
+    /// * `source_id` - L'ID unique de la source à retirer
+    ///
+    /// # Returns
+    ///
+    /// `true` si la source a été trouvée et retirée, `false` sinon.
+    ///
+    /// # Examples
+    ///
+    /// ```rust,ignore
+    /// if server.unregister_music_source("qobuz").await {
+    ///     println!("Qobuz source removed");
+    /// }
+    /// ```
+    #[cfg(feature = "server")]
+    async fn unregister_music_source(&mut self, source_id: &str) -> bool;
+
+    /// Liste toutes les sources enregistrées
+    ///
+    /// Retourne une copie de toutes les sources actuellement enregistrées
+    /// dans le registre global.
+    ///
+    /// # Returns
+    ///
+    /// Un vecteur de `Arc<dyn MusicSource>` contenant toutes les sources.
+    ///
+    /// # Examples
+    ///
+    /// ```rust,ignore
+    /// let sources = server.list_music_sources().await;
+    /// for source in sources {
+    ///     println!("- {} ({})", source.name(), source.id());
+    /// }
+    /// ```
+    #[cfg(feature = "server")]
+    async fn list_music_sources(&self) -> Vec<Arc<dyn MusicSource>>;
+
+    /// Récupère une source spécifique par son ID
+    ///
+    /// # Arguments
+    ///
+    /// * `source_id` - L'ID unique de la source recherchée
+    ///
+    /// # Returns
+    ///
+    /// `Some(Arc<dyn MusicSource>)` si la source existe, `None` sinon.
+    ///
+    /// # Examples
+    ///
+    /// ```rust,ignore
+    /// if let Some(source) = server.get_music_source("qobuz").await {
+    ///     println!("Found: {}", source.name());
+    /// }
+    /// ```
+    #[cfg(feature = "server")]
+    async fn get_music_source(&self, source_id: &str) -> Option<Arc<dyn MusicSource>>;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Les tests fonctionnels nécessitent l'implémentation du trait,
+    // voir pmoserver_impl.rs
+    #[test]
+    fn test_trait_exists() {
+        // Ce test vérifie simplement que le trait compile
+    }
+}