Pattern d’extension PMOServer (`pmoserver_ext`)

Vue d’ensemble

Le pattern pmoserver_ext permet d’étendre les fonctionnalités du serveur HTTP pmoserver de manière modulaire et découplée. Chaque crate spécialisée peut ajouter ses propres routes HTTP sans que pmoserver ne dépende de ces crates.

Principe : Définir un trait d’extension que pmoserver::Server implémente via une feature Cargo.

Anatomie d’une extension

1. Structure du module

Créer un module pmoserver_ext.rs dans la crate :

// pmoXXX/src/pmoserver_ext.rs

#[cfg(feature = "pmoserver")]
use crate::{/* types internes de la crate */};
#[cfg(feature = "pmoserver")]
use async_trait::async_trait;
#[cfg(feature = "pmoserver")]
use axum::{Router, routing::get, Json, extract::{State, Path}};
#[cfg(feature = "pmoserver")]
use std::sync::Arc;


Déclarer le module dans lib.rs :
// pmoXXX/src/lib.rs
#[cfg(feature = "pmoserver")]
pub mod pmoserver_ext;

#[cfg(feature = "pmoserver")]
pub use pmoserver_ext::XXXExt;

Ajouter la feature dans Cargo.toml :
[features]
pmoserver = ["dep:axum", "dep:async-trait"]

[dependencies]
axum = { version = "0.8", optional = true }
async-trait = { version = "0.1", optional = true }
pmoserver = { path = "../pmoserver" }

2. Définir le trait
d’extension
Convention de nommage : {Domaine}Ext
avec méthodes préfixées init_*
/// Trait pour étendre pmoserver avec les fonctionnalités XXX
#[cfg(feature = "pmoserver")]
#[async_trait]
pub trait XXXExt {
    /// Initialise l'extension XXX et enregistre les routes HTTP
    ///
    /// # Arguments
    /// * `param1` - Description du paramètre
    ///
    /// # Returns
    /// Instance partagée de la ressource créée
    ///
    /// # Exemple
    /// ```ignore
    /// use pmoserver::ServerBuilder;
    /// use pmoXXX::XXXExt;
    ///
    /// let mut server = ServerBuilder::new(...).build();
    /// let resource = server.init_xxx(param1).await?;
    /// ```
    async fn init_xxx(&mut self, param1: String) -> anyhow::Result<Arc<Resource>>;
}

3. Implémenter le trait
Implémenter le trait pour pmoserver::Server :
#[cfg(feature = "pmoserver")]
#[async_trait]
impl XXXExt for pmoserver::Server {
    async fn init_xxx(&mut self, param1: String) -> anyhow::Result<Arc<Resource>> {
        // 1. Créer la ressource interne
        let resource = Arc::new(Resource::new(param1)?);
        
        // 2. Créer l'état partagé pour les handlers
        let state = XxxState::new(resource.clone());
        
        // 3. Créer le router avec les routes
        let router = create_xxx_router(state);
        
        // 4. Enregistrer le router sur le serveur
        self.add_router("/api/xxx", router).await;
        
        // 5. Retourner la ressource pour usage ultérieur
        Ok(resource)
    }
}

4. État partagé (State)
Créer une structure d’état cloneable pour les handlers :
/// État partagé pour les handlers XXX
#[derive(Clone)]
pub struct XxxState {
    resource: Arc<Resource>,
}

impl XxxState {
    pub fn new(resource: Arc<Resource>) -> Self {
        Self { resource }
    }
}

5. Créer le router
Définir les routes et handlers :
/// Crée le router pour l'API XXX
fn create_xxx_router(state: XxxState) -> Router {
    Router::new()
        .route("/items", get(list_items).post(create_item))
        .route("/items/{id}", get(get_item).delete(delete_item))
        .with_state(state)
}

// Handlers
async fn list_items(
    State(state): State<XxxState>
) -> Json<Vec<ItemSummary>> {
    let items = state.resource.list_items();
    Json(items)
}

async fn get_item(
    State(state): State<XxxState>,
    Path(id): Path<String>,
) -> Result<Json<Item>, StatusCode> {
    state.resource.get_item(&id)
        .ok_or(StatusCode::NOT_FOUND)
        .map(Json)
}

Méthodes disponibles du
serveur
pmoserver::Server expose ces méthodes pour enregistrer
des routes :







Méthode
Usage




add_handler(path, handler)
Ajoute un handler simple sans état


add_handler_with_state(path, handler, state)
Ajoute un handler avec état partagé


add_router(path, router)
Monte un sous-router Axum


add_openapi(router, doc, tag)
Enregistre une API avec documentation OpenAPI


add_spa::<W>(path)
Sert une Single Page Application (RustEmbed)


base_url()
Récupère l’URL de base du serveur



Documentation OpenAPI avec
utoipa
La documentation OpenAPI est essentielle pour une extension
pmoserver. Elle génère automatiquement une interface
Swagger UI et documente les endpoints de l’API.
Configuration de base
Ajouter utoipa dans Cargo.toml :
[dependencies]
utoipa = { version = "5", features = ["axum_extras"] }
serde = { version = "1", features = ["derive"] }

1. Définir les schémas de
données
Annoter les structures de réponse/requête avec
#[derive(ToSchema)] :
use serde::{Serialize, Deserialize};
use utoipa::ToSchema;

/// Information sur un item
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
pub struct ItemInfo {
    /// ID unique de l'item
    #[schema(example = "item-123")]
    pub id: String,
    
    /// Nom de l'item
    #[schema(example = "Mon Item")]
    pub name: String,
    
    /// Description optionnelle
    #[schema(example = "Une description détaillée")]
    pub description: Option<String>,
    
    /// Timestamp de création (millisecondes)
    #[schema(example = 1234567890)]
    pub created_at: u64,
}

/// Liste d'items
#[derive(Debug, Clone, Serialize, ToSchema)]
pub struct ItemList {
    /// Nombre total d'items
    pub total: usize,
    
    /// Items de la page courante
    pub items: Vec<ItemInfo>,
}

/// Requête de création d'item
#[derive(Debug, Clone, Deserialize, ToSchema)]
pub struct CreateItemRequest {
    /// Nom de l'item à créer
    #[schema(example = "Nouvel Item")]
    pub name: String,
    
    /// Description optionnelle
    pub description: Option<String>,
}

/// Réponse d'erreur standard
#[derive(Debug, Clone, Serialize, ToSchema)]
pub struct ErrorResponse {
    /// Message d'erreur
    #[schema(example = "Item not found")]
    pub error: String,
}

Points clés : -
#[schema(example = "...")] : Fournit des exemples pour la
doc Swagger - Documenter chaque champ avec /// pour
apparaître dans l’API - Utiliser Option<T> pour les
champs optionnels
2. Annoter les handlers
Utiliser #[utoipa::path(...)] pour documenter chaque
endpoint :
/// GET /items - Liste tous les items
#[utoipa::path(
    get,
    path = "/items",
    params(
        ("limit" = Option<u32>, Query, description = "Nombre max d'items à retourner"),
        ("offset" = Option<u32>, Query, description = "Offset pour la pagination")
    ),
    responses(
        (status = 200, description = "Liste des items", body = ItemList),
        (status = 500, description = "Erreur serveur", body = ErrorResponse)
    ),
    tag = "items"
)]
async fn list_items(
    State(state): State<XxxState>,
    Query(params): Query<ListParams>,
) -> Result<Json<ItemList>, (StatusCode, Json<ErrorResponse>)> {
    let items = state.resource.list_items(params.limit, params.offset)
        .map_err(|e| (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(ErrorResponse { error: e.to_string() })
        ))?;
    
    Ok(Json(ItemList {
        total: items.len(),
        items,
    }))
}

/// GET /items/{id} - Récupère un item spécifique
#[utoipa::path(
    get,
    path = "/items/{id}",
    params(
        ("id" = String, Path, description = "ID unique de l'item")
    ),
    responses(
        (status = 200, description = "Item trouvé", body = ItemInfo),
        (status = 404, description = "Item non trouvé", body = ErrorResponse),
        (status = 500, description = "Erreur serveur", body = ErrorResponse)
    ),
    tag = "items"
)]
async fn get_item(
    State(state): State<XxxState>,
    Path(id): Path<String>,
) -> Result<Json<ItemInfo>, (StatusCode, Json<ErrorResponse>)> {
    state.resource.get_item(&id)
        .ok_or_else(|| (
            StatusCode::NOT_FOUND,
            Json(ErrorResponse {
                error: format!("Item {} not found", id)
            })
        ))
        .map(Json)
}

/// POST /items - Crée un nouvel item
#[utoipa::path(
    post,
    path = "/items",
    request_body = CreateItemRequest,
    responses(
        (status = 201, description = "Item créé", body = ItemInfo),
        (status = 400, description = "Requête invalide", body = ErrorResponse),
        (status = 500, description = "Erreur serveur", body = ErrorResponse)
    ),
    tag = "items"
)]
async fn create_item(
    State(state): State<XxxState>,
    Json(req): Json<CreateItemRequest>,
) -> Result<(StatusCode, Json<ItemInfo>), (StatusCode, Json<ErrorResponse>)> {
    let item = state.resource.create_item(req.name, req.description)
        .map_err(|e| (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(ErrorResponse { error: e.to_string() })
        ))?;
    
    Ok((StatusCode::CREATED, Json(item)))
}

/// DELETE /items/{id} - Supprime un item
#[utoipa::path(
    delete,
    path = "/items/{id}",
    params(
        ("id" = String, Path, description = "ID unique de l'item")
    ),
    responses(
        (status = 204, description = "Item supprimé"),
        (status = 404, description = "Item non trouvé", body = ErrorResponse),
        (status = 500, description = "Erreur serveur", body = ErrorResponse)
    ),
    tag = "items"
)]
async fn delete_item(
    State(state): State<XxxState>,
    Path(id): Path<String>,
) -> Result<StatusCode, (StatusCode, Json<ErrorResponse>)> {
    state.resource.delete_item(&id)
        .map_err(|e| (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(ErrorResponse { error: e.to_string() })
        ))?;
    
    Ok(StatusCode::NO_CONTENT)
}

Structure de #[utoipa::path] : -
Méthode HTTP : get, post,
put, delete, patch -
path : Chemin de l’endpoint (doit
correspondre au router) - params :
Paramètres Path ou Query avec description -
request_body : Type du body pour POST/PUT
- responses : Liste des réponses possibles
avec codes HTTP - tag : Groupe d’endpoints
dans Swagger UI
3. Créer la structure OpenAPI
Définir une structure avec #[derive(OpenApi)] :
use utoipa::OpenApi;

/// Documentation OpenAPI pour l'API XXX
#[derive(OpenApi)]
#[openapi(
    info(
        title = "XXX API",
        version = "1.0.0",
        description = r#"
# API REST pour XXX

Cette API permet de gérer les items XXX avec les fonctionnalités suivantes :

## Fonctionnalités

- **CRUD complet** : Création, lecture, mise à jour et suppression d'items
- **Pagination** : Support de limit/offset pour les listes
- **Filtrage** : Recherche par critères multiples
- **Validation** : Vérification automatique des données

## Exemples d'utilisation

### Lister les items

GET /api/xxx/items?limit=10&offset=0

### Créer un item

POST /api/xxx/items Content-Type: application/json
{ “name”: “Mon Item”, “description”: “Description détaillée” }

### Récupérer un item

GET /api/xxx/items/item-123

### Supprimer un item

DELETE /api/xxx/items/item-123
        "#
    ),
    paths(
        list_items,
        get_item,
        create_item,
        delete_item,
    ),
    components(schemas(
        ItemInfo,
        ItemList,
        CreateItemRequest,
        ErrorResponse,
    )),
    tags(
        (name = "items", description = "Opérations sur les items")
    )
)]
pub struct ApiDoc;

Sections importantes : -
info : Titre, version et description
Markdown de l’API - paths : Liste des
fonctions handler annotées -
components(schemas(...)) : Liste des
structures ToSchema - tags :
Organisation des endpoints en groupes
4. Enregistrer l’API avec
OpenAPI
Dans l’implémentation du trait d’extension :
#[async_trait]
impl XxxExt for pmoserver::Server {
    async fn init_xxx(&mut self) -> anyhow::Result<Arc<Resource>> {
        let resource = Arc::new(Resource::new()?);
        let state = XxxState { resource: resource.clone() };
        
        // Créer le router avec les routes
        let router = Router::new()
            .route("/items", get(list_items).post(create_item))
            .route("/items/{id}", get(get_item).delete(delete_item))
            .with_state(state);
        
        // Enregistrer avec OpenAPI (génère aussi /swagger-ui/xxx)
        let openapi = ApiDoc::openapi();
        self.add_openapi(router, openapi, "xxx").await;
        
        Ok(resource)
    }
}

Ce que fait add_openapi : - Monte le
router sur /api/{tag}/ - Génère la spec OpenAPI JSON sur
/api/{tag}/openapi.json - Crée une UI Swagger sur
/swagger-ui/{tag}/
5. Exemple complet : Radio
Paradise
Extrait de
pmoparadise/src/pmoserver_ext.rs:93-315
/// Information sur un morceau
#[derive(Debug, Clone, Serialize, ToSchema)]
pub struct SongInfo {
    /// Index dans le block
    pub index: usize,
    /// Artiste
    pub artist: String,
    /// Titre
    pub title: String,
    /// Album
    pub album: String,
    /// Année
    pub year: Option<u32>,
    /// Temps écoulé depuis le début du block (ms)
    pub elapsed_ms: u64,
    /// Durée du morceau (ms)
    pub duration_ms: u64,
    /// URL de la pochette
    pub cover_url: Option<String>,
}

/// Réponse pour l'URL de streaming
#[derive(Debug, Clone, Serialize, ToSchema)]
pub struct StreamUrlResponse {
    /// Event ID du block
    #[schema(example = 1234567)]
    pub event: u64,
    /// URL de streaming FLAC
    #[schema(example = "https://apps.radioparadise.com/blocks/chan/0/4/1234567-1234580.flac")]
    pub stream_url: String,
    /// Durée totale (ms)
    #[schema(example = 900000)]
    pub length_ms: u64,
}

/// GET /stream-url/{event_id} - Récupère l'URL de streaming
#[utoipa::path(
    get,
    path = "/stream-url/{event_id}",
    params(
        ("event_id" = u64, Path, description = "Event ID du block"),
        ("channel" = Option<u8>, Query, description = "Channel ID (0-3)")
    ),
    responses(
        (status = 200, description = "URL de streaming", body = StreamUrlResponse),
        (status = 500, description = "Erreur serveur")
    ),
    tag = "Radio Paradise"
)]
async fn get_stream_url(
    State(state): State<RadioParadiseState>,
    Path(event_id): Path<u64>,
    Query(params): Query<ParadiseQuery>,
) -> Result<Json<StreamUrlResponse>, StatusCode> {
    let client = state.client_for_params(&params).await?;
    let block = client.get_block(Some(event_id)).await.map_err(|e| {
        tracing::error!("Failed to fetch block {}: {}", event_id, e);
        StatusCode::INTERNAL_SERVER_ERROR
    })?;

    Ok(Json(StreamUrlResponse {
        event: block.event,
        stream_url: block.url,
        length_ms: block.length,
    }))
}

#[derive(OpenApi)]
#[openapi(
    info(
        title = "Radio Paradise API",
        version = "1.0.0",
        description = "API REST pour accéder aux métadonnées Radio Paradise"
    ),
    paths(
        get_now_playing,
        get_current_block,
        get_stream_url,
    ),
    components(schemas(
        SongInfo,
        StreamUrlResponse,
    )),
    tags(
        (name = "Radio Paradise", description = "Endpoints Radio Paradise")
    )
)]
pub struct RadioParadiseApiDoc;

Résultat : Interface Swagger
Après avoir appelé init_xxx(), l’API est accessible
:

API JSON :
http://localhost:8080/api/xxx/
Spec OpenAPI :
http://localhost:8080/api/xxx/openapi.json
Swagger UI :
http://localhost:8080/swagger-ui/xxx/

L’interface Swagger permet : - Parcourir tous les endpoints avec leur
documentation - Tester les requêtes directement depuis le navigateur -
Voir les schémas de données avec exemples - Consulter les codes de
réponse HTTP possibles
Patterns courants
Pattern 1 : Extension
simple avec router
Exemple : pmoparadise
(pmoparadise/src/pmoserver_ext.rs:367-392)
#[async_trait]
impl RadioParadiseExt for pmoserver::Server {
    async fn init_radioparadise(&mut self) -> anyhow::Result<State> {
        let state = RadioParadiseState::new().await?;
        
        // Créer le router API
        let api_router = create_api_router(state.clone());
        
        // Enregistrer avec OpenAPI
        self.add_openapi(api_router, ApiDoc::openapi(), "radioparadise")
            .await;
        
        Ok(state)
    }
}

Pattern 2 :
Extension avec cache et fichiers
Exemple : pmoaudiocache
(pmoaudiocache/src/lib.rs:225-260)
#[async_trait]
impl AudioCacheExt for pmoserver::Server {
    async fn init_audio_cache(
        &mut self,
        cache_dir: &str,
        limit: usize,
    ) -> anyhow::Result<Arc<Cache>> {
        let cache = Arc::new(new_cache(cache_dir, limit)?);
        
        // Router pour servir les fichiers FLAC
        let file_router = create_file_router(cache.clone(), "audio/flac");
        self.add_router("/", file_router).await;
        
        // API REST
        let api_router = Router::new()
            .route("/", get(list).post(add))
            .route("/{pk}", get(get_info).delete(delete))
            .with_state(cache.clone());
        
        self.add_openapi(api_router, ApiDoc::openapi(), "audio").await;
        
        Ok(cache)
    }
}

Pattern 3 :
Extension avec routes dynamiques
Exemple : pmomediaserver
(pmomediaserver/src/paradise_streaming.rs:70-148)
#[async_trait]
impl ParadiseStreamingExt for pmoserver::Server {
    async fn init_paradise_streaming(&mut self) -> Result<Arc<Manager>> {
        // 1. Récupérer/créer les ressources partagées
        let audio_cache = get_or_init_audio_cache(self).await?;
        let manager = Arc::new(Manager::new(audio_cache).await?);
        
        // 2. Créer l'état partagé
        let state = Arc::new(StreamingState { manager: manager.clone() });
        
        // 3. Enregistrer les routes pour chaque canal
        for descriptor in ALL_CHANNELS.iter() {
            let slug = descriptor.slug;
            
            // Route streaming FLAC
            let path = format!("/stream/{}/flac", slug);
            self.add_handler_with_state(
                &path,
                move |State(s): State<Arc<StreamingState>>| async move {
                    stream_flac(s.manager.clone(), descriptor.id).await
                },
                state.clone(),
            ).await;
            
            // Route streaming OGG
            let path = format!("/stream/{}/ogg", slug);
            self.add_handler_with_state(
                &path,
                move |State(s): State<Arc<StreamingState>>| async move {
                    stream_ogg(s.manager.clone(), descriptor.id).await
                },
                state.clone(),
            ).await;
        }
        
        Ok(manager)
    }
}

Gestion des opérations
longues
Utiliser
spawn_blocking pour le code synchrone
Pour éviter de bloquer le runtime Tokio avec du code synchrone :
async fn list_renderers(
    State(state): State<ControlPointState>
) -> Json<Vec<Summary>> {
    let control_point = state.control_point.clone();
    
    let summaries = tokio::task::spawn_blocking(move || {
        let renderers = control_point.list_music_renderers();
        renderers.into_iter()
            .map(|r| Summary::from(&r))
            .collect()
    })
    .await
    .unwrap_or_default();
    
    Json(summaries)
}

Ajouter des
timeouts pour les opérations réseau
const COMMAND_TIMEOUT: Duration = Duration::from_secs(5);

async fn play_renderer(
    State(state): State<ControlPointState>,
    Path(id): Path<String>,
) -> Result<Json<Response>, (StatusCode, Json<Error>)> {
    let renderer = state.get_renderer(&id)
        .ok_or((StatusCode::NOT_FOUND, Json(Error::not_found())))?;
    
    let play_task = tokio::task::spawn_blocking(move || renderer.play());
    
    time::timeout(COMMAND_TIMEOUT, play_task)
        .await
        .map_err(|_| (
            StatusCode::GATEWAY_TIMEOUT,
            Json(Error::timeout())
        ))?
        .map_err(|e| (
            StatusCode::INTERNAL_SERVER_ERROR,
            Json(Error::internal(e))
        ))??;
    
    Ok(Json(Response::success()))
}

Utiliser
spawn pour les tâches en arrière-plan
Pour les opérations qui ne nécessitent pas d’attendre le résultat
:
async fn trigger_action(
    State(state): State<XxxState>,
    Json(req): Json<Request>,
) -> Json<Response> {
    // Valider la requête
    state.validate(&req)?;
    
    // Lancer l'action en arrière-plan
    let state_clone = state.clone();
    tokio::task::spawn(async move {
        match state_clone.perform_action(req).await {
            Ok(_) => debug!("Action completed"),
            Err(e) => warn!("Action failed: {}", e),
        }
    });
    
    // Retourner immédiatement
    Json(Response::accepted())
}

Checklist d’implémentation
Configuration de base

Créer le module
pmoserver_ext.rs avec
#[cfg(feature = "pmoserver")]
Ajouter la feature
pmoserver dans Cargo.toml avec dépendances
optionnelles
Re-exporter le trait dans
lib.rs

Définition du trait

Définir le trait
{Domaine}Ext avec méthode init_*
Créer la structure
{Domaine}State avec
#[derive(Clone)]
Implémenter le trait pour
pmoserver::Server

Documentation OpenAPI

Ajouter utoipa dans les
dépendances
Définir les schémas de
réponse/requête avec #[derive(ToSchema)]
Ajouter des exemples avec
#[schema(example = "...")]
Annoter chaque handler avec
#[utoipa::path(...)]
Créer la structure
#[derive(OpenApi)] avec documentation complète
Lister tous les paths et schemas
dans #[openapi(...)]

Handlers et routes

Créer les handlers avec les
extracteurs Axum appropriés
Gérer les erreurs avec des codes
HTTP sémantiques
Créer le router et l’enregistrer
avec add_openapi()
Ajouter des logs (debug, info, warn,
error)

Performance et robustesse

Utiliser spawn_blocking
pour le code synchrone
Ajouter des timeouts pour les
opérations réseau
Utiliser spawn pour les
tâches en arrière-plan si nécessaire

Exemple complet minimal
// pmoexample/src/pmoserver_ext.rs

#[cfg(feature = "pmoserver")]
use async_trait::async_trait;
#[cfg(feature = "pmoserver")]
use axum::{Router, routing::get, Json, extract::State};
#[cfg(feature = "pmoserver")]
use std::sync::Arc;
#[cfg(feature = "pmoserver")]
use crate::ExampleResource;

#[cfg(feature = "pmoserver")]
#[derive(Clone)]
pub struct ExampleState {
    resource: Arc<ExampleResource>,
}

#[cfg(feature = "pmoserver")]
#[async_trait]
pub trait ExampleExt {
    async fn init_example(&mut self) -> anyhow::Result<Arc<ExampleResource>>;
}

#[cfg(feature = "pmoserver")]
#[async_trait]
impl ExampleExt for pmoserver::Server {
    async fn init_example(&mut self) -> anyhow::Result<Arc<ExampleResource>> {
        let resource = Arc::new(ExampleResource::new());
        let state = ExampleState { resource: resource.clone() };
        
        let router = Router::new()
            .route("/items", get(list_items))
            .with_state(state);
        
        self.add_router("/api/example", router).await;
        
        Ok(resource)
    }
}

#[cfg(feature = "pmoserver")]
async fn list_items(State(state): State<ExampleState>) -> Json<Vec<String>> {
    let items = state.resource.list();
    Json(items)
}

Références
Exemples dans le codebase








Crate
Fichier
Pattern




pmoparadise
src/pmoserver_ext.rs:367-392
Extension simple avec OpenAPI


pmoaudiocache
src/lib.rs:225-260
Extension avec cache et fichiers


pmomediaserver
src/paradise_streaming.rs:70-148
Extension avec routes dynamiques


pmocontrol
src/pmoserver_ext.rs:68-92
Handlers avec spawn_blocking


pmoapp
src/lib.rs:145-165
Extension SPA avec RustEmbed



Dépendances communes

axum : Framework HTTP (Router, handlers,
extracteurs)
async-trait : Support des traits async
tokio : Runtime async (spawn, spawn_blocking,
timeout)
anyhow : Gestion d’erreurs pour init
tracing : Logging structuré
utoipa : Documentation OpenAPI/Swagger
serde : Sérialisation JSON

Crate	Fichier	Pattern
`pmoparadise`	`src/pmoserver_ext.rs:367-392`	Extension simple avec OpenAPI
`pmoaudiocache`	`src/lib.rs:225-260`	Extension avec cache et fichiers
`pmomediaserver`	`src/paradise_streaming.rs:70-148`	Extension avec routes dynamiques
`pmocontrol`	`src/pmoserver_ext.rs:68-92`	Handlers avec `spawn_blocking`
`pmoapp`	`src/lib.rs:145-165`	Extension SPA avec RustEmbed

Pattern d’extension PMOServer (`pmoserver_ext`)

Vue d’ensemble

Anatomie d’une extension

1. Structure du module

2. Définir le trait d’extension

3. Implémenter le trait

4. État partagé (State)

5. Créer le router

Méthodes disponibles du serveur

Documentation OpenAPI avec utoipa

Configuration de base

1. Définir les schémas de données

2. Annoter les handlers

3. Créer la structure OpenAPI

4. Enregistrer l’API avec OpenAPI

5. Exemple complet : Radio Paradise

Résultat : Interface Swagger

Patterns courants

Pattern 1 : Extension simple avec router

Pattern 2 : Extension avec cache et fichiers

Pattern 3 : Extension avec routes dynamiques

Gestion des opérations longues

Utiliser `spawn_blocking` pour le code synchrone

Ajouter des timeouts pour les opérations réseau

Utiliser `spawn` pour les tâches en arrière-plan

Checklist d’implémentation

Configuration de base

Définition du trait

Documentation OpenAPI

Handlers et routes

Performance et robustesse

Exemple complet minimal

Références

Exemples dans le codebase

Dépendances communes

Méthode	Usage
`add_handler(path, handler)`	Ajoute un handler simple sans état
`add_handler_with_state(path, handler, state)`	Ajoute un handler avec état partagé
`add_router(path, router)`	Monte un sous-router Axum
`add_openapi(router, doc, tag)`	Enregistre une API avec documentation OpenAPI
`add_spa::<W>(path)`	Sert une Single Page Application (RustEmbed)
`base_url()`	Récupère l’URL de base du serveur

Pattern d’extension PMOServer (pmoserver_ext)

Vue d’ensemble

Anatomie d’une extension

1. Structure du module

2. Définir le trait d’extension

3. Implémenter le trait

4. État partagé (State)

5. Créer le router

Méthodes disponibles du serveur

Documentation OpenAPI avec utoipa

Configuration de base

1. Définir les schémas de données

2. Annoter les handlers

3. Créer la structure OpenAPI

4. Enregistrer l’API avec OpenAPI

5. Exemple complet : Radio Paradise

Résultat : Interface Swagger

Patterns courants

Pattern 1 : Extension simple avec router

Pattern 2 : Extension avec cache et fichiers

Pattern 3 : Extension avec routes dynamiques

Gestion des opérations longues

Utiliser spawn_blocking pour le code synchrone

Ajouter des timeouts pour les opérations réseau

Utiliser spawn pour les tâches en arrière-plan

Checklist d’implémentation

Configuration de base

Définition du trait

Documentation OpenAPI

Handlers et routes

Performance et robustesse

Exemple complet minimal

Références

Exemples dans le codebase

Dépendances communes

Pattern d’extension PMOServer (`pmoserver_ext`)

Utiliser `spawn_blocking` pour le code synchrone

Utiliser `spawn` pour les tâches en arrière-plan