arcature 2026.1.0

//! `UserLoader<S>` — how to load a user from a session ID + state (A9).
//!
//! The application implements this for its `User` type to tell the framework
//! how to load a user from the session-stored ID and the application state
//! (which typically carries a `Db` handle). This is the loading seam between
//! the session and the database.
//!
//! # Example
//!
//! ```ignore
//! impl arcature::UserLoader<AppState> for User {
//!     type Error = sea_orm::DbErr;
//!     async fn load_user(id: &Uuid, state: &AppState) -> Result<Option<User>, DbErr> {
//!         // load from DB via state.db
//!     }
//! }
//! ```

use std::future::Future;

use crate::dx::auth_user::AuthUser;

/// How to load a [`AuthUser`] from its session ID and application state.
///
/// The app implements this for its user type. `Auth<U>` and
/// `OptionalAuth<U>` call `U::load_user(id, state)` to resolve the
/// authenticated user from the session.
pub trait UserLoader<S>: AuthUser + Sized {
    /// The typed error from the load operation.
    type Error: std::error::Error + Send + Sync + 'static;

    /// Load the user by its session ID from application state. Return
    /// `Ok(None)` if the user does not exist (the session is stale — the
    /// extractor maps this to 401). Return `Err` for database errors.
    fn load_user(
        id: &Self::Id,
        state: &S,
    ) -> impl Future<Output = Result<Option<Self>, Self::Error>> + Send;
}