backbone_bucket/presentation/http/

upload_session_handler.rs

//! UploadSession REST handlers
//!
//! Generated by metaphor-schema. Do not edit manually.
//!
//! Uses Axum and backbone-core's BackboneCrudHandler for all 12 CRUD endpoints.

use std::collections::HashMap;
use std::sync::Arc;

use axum::Router;
use serde::{Deserialize, Serialize};
use uuid::Uuid;
use chrono::{DateTime, Utc};

// Backbone framework imports
use backbone_core::http::{ApiResponse, BackboneCrudHandler};

// Auth integration (optional)
#[cfg(feature = "auth")]
use backbone_auth::middleware::AuthContext;
#[cfg(feature = "auth")]
use backbone_auth::AuthMiddleware;

// Domain imports
use crate::domain::entity::*;
use crate::application::service::{UploadSessionService, ServiceError};

// DTO imports
use crate::presentation::dto::{CreateUploadSessionDto, UpdateUploadSessionDto, PatchUploadSessionDto, UploadSessionResponseDto};

use crate::domain::state_machine::{UploadSessionState, UploadSessionStateMachine, UploadSessionTransition};

/// Application error type
#[derive(Debug, thiserror::Error)]
pub enum UploadSessionError {
    #[error("Not found: {0}")]
    NotFound(String),
    #[error("Validation error: {0}")]
    Validation(String),
    #[error("Database error: {0}")]
    Database(String),
    #[error("Internal error: {0}")]
    Internal(String),
    // Domain-specific errors from hook rules
    #[error("Target bucket must exist: {0}")]
    BucketNotFound(String),
    #[error("Bucket must accept uploads: {0}")]
    BucketNotActive(String),
    #[error("File size must be positive: {0}")]
    InvalidFileSize(String),
    #[error("Chunk size must be at least 5MB: {0}")]
    ChunkTooSmall(String),
    #[error("Chunk size must not exceed 5GB: {0}")]
    ChunkTooLarge(String),
    #[error("Total chunks must match file size and chunk size: {0}")]
    InvalidChunkCount(String),
    #[error("Path must be valid and not contain traversal: {0}")]
    InvalidPath(String),
    #[error("Expiration must be in future: {0}")]
    InvalidExpiration(String),
    #[error("Expiration must be within 7 days: {0}")]
    ExpirationTooFar(String),
    #[error("Session has expired: {0}")]
    SessionExpired(String),
}

impl From<ServiceError> for UploadSessionError {
    fn from(err: ServiceError) -> Self {
        match err {
            ServiceError::NotFound => Self::NotFound(err.to_string()),
            ServiceError::Validation(ref msg) => Self::Validation(msg.clone()),
            ServiceError::AlreadyExists(ref msg) => Self::Validation(msg.clone()),
            ServiceError::Repository(ref e) => Self::Database(e.to_string()),
            ServiceError::Internal(ref msg) => Self::Internal(msg.clone()),
            ServiceError::Violations(_) => Self::Validation(err.to_string()),
        }
    }
}

impl axum::response::IntoResponse for UploadSessionError {
    fn into_response(self) -> axum::response::Response {
        use axum::http::StatusCode;
        use axum::Json;

        let (status, code) = match &self {
            Self::NotFound(_) => (StatusCode::NOT_FOUND, "UPLOADSESSION_NOT_FOUND"),
            Self::Validation(_) => (StatusCode::BAD_REQUEST, "UPLOADSESSION_VALIDATION_ERROR"),
            Self::Database(_) => (StatusCode::INTERNAL_SERVER_ERROR, "UPLOADSESSION_DATABASE_ERROR"),
            Self::Internal(_) => (StatusCode::INTERNAL_SERVER_ERROR, "UPLOADSESSION_INTERNAL_ERROR"),
            Self::BucketNotFound(_) => (StatusCode::UNPROCESSABLE_ENTITY, "UPLOADSESSION_BUCKET_NOT_FOUND"),
            Self::BucketNotActive(_) => (StatusCode::UNPROCESSABLE_ENTITY, "UPLOADSESSION_BUCKET_NOT_ACTIVE"),
            Self::InvalidFileSize(_) => (StatusCode::UNPROCESSABLE_ENTITY, "UPLOADSESSION_INVALID_FILE_SIZE"),
            Self::ChunkTooSmall(_) => (StatusCode::UNPROCESSABLE_ENTITY, "UPLOADSESSION_CHUNK_TOO_SMALL"),
            Self::ChunkTooLarge(_) => (StatusCode::UNPROCESSABLE_ENTITY, "UPLOADSESSION_CHUNK_TOO_LARGE"),
            Self::InvalidChunkCount(_) => (StatusCode::UNPROCESSABLE_ENTITY, "UPLOADSESSION_INVALID_CHUNK_COUNT"),
            Self::InvalidPath(_) => (StatusCode::UNPROCESSABLE_ENTITY, "UPLOADSESSION_INVALID_PATH"),
            Self::InvalidExpiration(_) => (StatusCode::UNPROCESSABLE_ENTITY, "UPLOADSESSION_INVALID_EXPIRATION"),
            Self::ExpirationTooFar(_) => (StatusCode::UNPROCESSABLE_ENTITY, "UPLOADSESSION_EXPIRATION_TOO_FAR"),
            Self::SessionExpired(_) => (StatusCode::UNPROCESSABLE_ENTITY, "UPLOADSESSION_SESSION_EXPIRED"),
        };

        let body = serde_json::json!({
            "success": false,
            "error": code,
            "message": self.to_string(),
        });

        (status, Json(body)).into_response()
    }
}

/// Domain-specific error codes for UploadSession
pub mod upload_session_errors {
    pub const BUCKET_NOT_FOUND: &str = "UPLOADSESSION_BUCKET_NOT_FOUND";
    pub const BUCKET_NOT_ACTIVE: &str = "UPLOADSESSION_BUCKET_NOT_ACTIVE";
    pub const INVALID_FILE_SIZE: &str = "UPLOADSESSION_INVALID_FILE_SIZE";
    pub const CHUNK_TOO_SMALL: &str = "UPLOADSESSION_CHUNK_TOO_SMALL";
    pub const CHUNK_TOO_LARGE: &str = "UPLOADSESSION_CHUNK_TOO_LARGE";
    pub const INVALID_CHUNK_COUNT: &str = "UPLOADSESSION_INVALID_CHUNK_COUNT";
    pub const INVALID_PATH: &str = "UPLOADSESSION_INVALID_PATH";
    pub const INVALID_EXPIRATION: &str = "UPLOADSESSION_INVALID_EXPIRATION";
    pub const EXPIRATION_TOO_FAR: &str = "UPLOADSESSION_EXPIRATION_TOO_FAR";
    pub const SESSION_EXPIRED: &str = "UPLOADSESSION_SESSION_EXPIRED";
}

// =============================================================================
// Route Configuration
// =============================================================================

/// Create Axum router with all 16 Backbone endpoints for UploadSession.
///
/// # Routes
///
/// | Method | Path | Description |
/// |--------|------|-------------|
/// | GET | /upload_sessions | List with pagination |
/// | POST | /upload_sessions | Create new |
/// | GET | /upload_sessions/:id | Get by ID |
/// | PUT | /upload_sessions/:id | Full update |
/// | PATCH | /upload_sessions/:id | Partial update |
/// | DELETE | /upload_sessions/:id | Soft delete |
/// | POST | /upload_sessions/bulk | Bulk create |
/// | POST | /upload_sessions/upsert | Upsert |
/// | GET | /upload_sessions/trash | List deleted |
/// | POST | /upload_sessions/:id/restore | Restore |
/// | DELETE | /upload_sessions/empty | Empty trash |
/// | GET | /upload_sessions/:id/deleted | Get deleted by ID |
/// | DELETE | /upload_sessions/trash/:id | Permanent delete from trash |
/// | GET | /upload_sessions/count | Count active entities |
/// | GET | /upload_sessions/trash/count | Count deleted entities |
///
/// # Example
///
/// ```text
/// let service = Arc::new(UploadSessionService::with_repository(repository));
/// let router = create_upload_session_routes(service);
/// ```
pub fn create_upload_session_routes(service: Arc<UploadSessionService>) -> Router {
    BackboneCrudHandler::<UploadSessionService, UploadSession, CreateUploadSessionDto, UpdateUploadSessionDto, UploadSessionResponseDto>::routes(
        service,
        "/upload_sessions",
    )
}

/// Create Axum router with only the read (GET) endpoints for UploadSession.
///
/// Safe for public, unauthenticated exposure (e.g., reference data).
/// Mutations must be served separately via `create_upload_session_write_routes`,
/// typically wrapped in an auth middleware layer.
pub fn create_upload_session_read_routes(service: Arc<UploadSessionService>) -> Router {
    BackboneCrudHandler::<UploadSessionService, UploadSession, CreateUploadSessionDto, UpdateUploadSessionDto, UploadSessionResponseDto>::read_routes(
        service,
        "/upload_sessions",
    )
}

/// Create Axum router with only the write (mutation) endpoints for UploadSession.
///
/// These routes must NOT be publicly exposed. Wrap them with an auth
/// middleware before nesting into the application router.
///
/// # This is unguarded generic CRUD, not a validated write path
///
/// These are plain create/update/patch/delete mutations over the entity row —
/// they bypass all business invariants. If the module exposes a validated write
/// service (e.g. a command router over its domain engine), serve THAT instead
/// for any mutation that must respect domain rules.
pub fn create_upload_session_write_routes(service: Arc<UploadSessionService>) -> Router {
    BackboneCrudHandler::<UploadSessionService, UploadSession, CreateUploadSessionDto, UpdateUploadSessionDto, UploadSessionResponseDto>::write_routes(
        service,
        "/upload_sessions",
    )
}

/// Create authenticated routes with auth middleware.
///
/// Requires the `auth` feature flag. The `AuthMiddleware` implementation
/// is responsible for extracting and validating tokens, then providing
/// an `AuthContext` via request extensions.
#[cfg(feature = "auth")]
pub fn create_protected_upload_session_routes<A: AuthMiddleware + Send + Sync + 'static>(
    service: Arc<UploadSessionService>,
    auth: Arc<A>,
) -> Router {
    use axum::middleware;
    use axum::response::IntoResponse;

    let auth_layer = auth.clone();
    create_upload_session_routes(service)
        .layer(middleware::from_fn(move |mut req: axum::extract::Request, next: axum::middleware::Next| {
            let auth = auth_layer.clone();
            async move {
                let token = req.headers()
                    .get(axum::http::header::AUTHORIZATION)
                    .and_then(|h| h.to_str().ok())
                    .and_then(|raw| raw.strip_prefix("Bearer ").or_else(|| raw.strip_prefix("bearer ")))
                    .unwrap_or("");
                match auth.authenticate(token).await {
                    Ok(ctx) => {
                        req.extensions_mut().insert(ctx);
                        next.run(req).await
                    }
                    Err(_) => {
                        (axum::http::StatusCode::UNAUTHORIZED,
                         axum::Json(serde_json::json!({
                             "success": false,
                             "error": "unauthorized",
                             "message": "Authentication required"
                         }))
                        ).into_response()
                    }
                }
            }
        }))
}

// =============================================================================
// State Transition Handlers
// =============================================================================

/// Execute start_upload transition on a UploadSession.
///
/// POST /upload_sessions/:id/transitions/start_upload
pub async fn start_upload_transition(
    axum::extract::State(service): axum::extract::State<Arc<UploadSessionService>>,
    axum::extract::Path(id): axum::extract::Path<String>,
    #[cfg(feature = "auth")] axum::Extension(auth): axum::Extension<AuthContext>,
) -> impl axum::response::IntoResponse {
    use axum::{http::StatusCode, Json};

    // Get current entity
    let entity = match service.get_by_id(&id).await {
        Ok(Some(e)) => e,
        Ok(None) => return (StatusCode::NOT_FOUND, Json(ApiResponse::<UploadSessionResponseDto>::not_found("UploadSession", &id))),
        Err(e) => return (StatusCode::INTERNAL_SERVER_ERROR, Json(ApiResponse::<UploadSessionResponseDto>::error(e.to_string()))),
    };

    // Check permission (if auth enabled)
    #[cfg(feature = "auth")]
    {
        let allowed_roles = UploadSessionTransition::StartUpload.allowed_roles();
        let has_specific_perm = auth.permissions.iter().any(|p| p == "upload_session:transition:start_upload");
        let has_update_perm = auth.permissions.iter().any(|p| p == "upload_session:update");
        let has_role = auth.roles.iter().any(|r| allowed_roles.contains(&r.as_str()));
        if !has_specific_perm && !has_role {
            if !has_update_perm {
                return (StatusCode::FORBIDDEN, Json(ApiResponse::<UploadSessionResponseDto>::error("Insufficient permissions for start_upload transition")));
            }
            tracing::warn!(target: "backbone::write_guard", entity = "UploadSession", verb = "start_upload", code = "transition_by_update_permission", "a transition granted only by upload_session:update, running in shadow; it needs upload_session:transition:start_upload or a role of ["system", "user"]");
        }
    }

    // Create state machine from entity's actual status and validate transition
    let current_state: UploadSessionState = match entity.status.to_string().parse() {
        Ok(s) => s,
        Err(_) => return (StatusCode::CONFLICT, Json(ApiResponse::<UploadSessionResponseDto>::error("The stored state is not a state of this machine"))),
    };
    let sm = UploadSessionStateMachine::from_state(current_state);
    if !sm.can_transition(UploadSessionTransition::StartUpload) {
        return (StatusCode::BAD_REQUEST, Json(ApiResponse::<UploadSessionResponseDto>::error("Transition not allowed from current state")));
    }

    // Guard `now() - metadata.created_at <= INTERVAL '1 hour'` not compiled (unexpected `'1 hour'` after a complete expression); the transition is not checked against it.
    // Apply transition via partial update
    let mut fields: HashMap<String, serde_json::Value> = HashMap::new();
    fields.insert("status".to_string(), serde_json::Value::String("uploading".to_string()));

    match backbone_core::write_guard::as_transition("start_upload", service.partial_update(&id, fields)).await {
        Ok(Some(updated)) => {
            let response: UploadSessionResponseDto = updated.into();
            (StatusCode::OK, Json(ApiResponse::ok(response)))
        }
        Ok(None) => (StatusCode::NOT_FOUND, Json(ApiResponse::<UploadSessionResponseDto>::not_found("UploadSession", &id))),
        Err(e) => (StatusCode::INTERNAL_SERVER_ERROR, Json(ApiResponse::<UploadSessionResponseDto>::error(e.to_string()))),
    }
}

/// Execute add_part transition on a UploadSession.
///
/// POST /upload_sessions/:id/transitions/add_part
pub async fn add_part_transition(
    axum::extract::State(service): axum::extract::State<Arc<UploadSessionService>>,
    axum::extract::Path(id): axum::extract::Path<String>,
    #[cfg(feature = "auth")] axum::Extension(auth): axum::Extension<AuthContext>,
) -> impl axum::response::IntoResponse {
    use axum::{http::StatusCode, Json};

    // Get current entity
    let entity = match service.get_by_id(&id).await {
        Ok(Some(e)) => e,
        Ok(None) => return (StatusCode::NOT_FOUND, Json(ApiResponse::<UploadSessionResponseDto>::not_found("UploadSession", &id))),
        Err(e) => return (StatusCode::INTERNAL_SERVER_ERROR, Json(ApiResponse::<UploadSessionResponseDto>::error(e.to_string()))),
    };

    // Check permission (if auth enabled)
    #[cfg(feature = "auth")]
    {
        let allowed_roles = UploadSessionTransition::AddPart.allowed_roles();
        let has_specific_perm = auth.permissions.iter().any(|p| p == "upload_session:transition:add_part");
        let has_update_perm = auth.permissions.iter().any(|p| p == "upload_session:update");
        let has_role = auth.roles.iter().any(|r| allowed_roles.contains(&r.as_str()));
        if !has_specific_perm && !has_role {
            if !has_update_perm {
                return (StatusCode::FORBIDDEN, Json(ApiResponse::<UploadSessionResponseDto>::error("Insufficient permissions for add_part transition")));
            }
            tracing::warn!(target: "backbone::write_guard", entity = "UploadSession", verb = "add_part", code = "transition_by_update_permission", "a transition granted only by upload_session:update, running in shadow; it needs upload_session:transition:add_part or a role of ["system", "user"]");
        }
    }

    // Create state machine from entity's actual status and validate transition
    let current_state: UploadSessionState = match entity.status.to_string().parse() {
        Ok(s) => s,
        Err(_) => return (StatusCode::CONFLICT, Json(ApiResponse::<UploadSessionResponseDto>::error("The stored state is not a state of this machine"))),
    };
    let sm = UploadSessionStateMachine::from_state(current_state);
    if !sm.can_transition(UploadSessionTransition::AddPart) {
        return (StatusCode::BAD_REQUEST, Json(ApiResponse::<UploadSessionResponseDto>::error("Transition not allowed from current state")));
    }

    // Guard `$context.part_number >= 1 && $context.part_number <= total_chunks && !completed_parts.contains($context.part_number)` not compiled (reads `$context.part_number`, which a row rule cannot); the transition is not checked against it.
    // Apply transition via partial update
    let mut fields: HashMap<String, serde_json::Value> = HashMap::new();
    fields.insert("status".to_string(), serde_json::Value::String("uploading".to_string()));

    match backbone_core::write_guard::as_transition("add_part", service.partial_update(&id, fields)).await {
        Ok(Some(updated)) => {
            let response: UploadSessionResponseDto = updated.into();
            (StatusCode::OK, Json(ApiResponse::ok(response)))
        }
        Ok(None) => (StatusCode::NOT_FOUND, Json(ApiResponse::<UploadSessionResponseDto>::not_found("UploadSession", &id))),
        Err(e) => (StatusCode::INTERNAL_SERVER_ERROR, Json(ApiResponse::<UploadSessionResponseDto>::error(e.to_string()))),
    }
}

/// Execute complete transition on a UploadSession.
///
/// POST /upload_sessions/:id/transitions/complete
pub async fn complete_transition(
    axum::extract::State(service): axum::extract::State<Arc<UploadSessionService>>,
    axum::extract::Path(id): axum::extract::Path<String>,
    #[cfg(feature = "auth")] axum::Extension(auth): axum::Extension<AuthContext>,
) -> impl axum::response::IntoResponse {
    use axum::{http::StatusCode, Json};

    // Get current entity
    let entity = match service.get_by_id(&id).await {
        Ok(Some(e)) => e,
        Ok(None) => return (StatusCode::NOT_FOUND, Json(ApiResponse::<UploadSessionResponseDto>::not_found("UploadSession", &id))),
        Err(e) => return (StatusCode::INTERNAL_SERVER_ERROR, Json(ApiResponse::<UploadSessionResponseDto>::error(e.to_string()))),
    };

    // Check permission (if auth enabled)
    #[cfg(feature = "auth")]
    {
        let allowed_roles = UploadSessionTransition::Complete.allowed_roles();
        let has_specific_perm = auth.permissions.iter().any(|p| p == "upload_session:transition:complete");
        let has_update_perm = auth.permissions.iter().any(|p| p == "upload_session:update");
        let has_role = auth.roles.iter().any(|r| allowed_roles.contains(&r.as_str()));
        if !has_specific_perm && !has_role {
            if !has_update_perm {
                return (StatusCode::FORBIDDEN, Json(ApiResponse::<UploadSessionResponseDto>::error("Insufficient permissions for complete transition")));
            }
            tracing::warn!(target: "backbone::write_guard", entity = "UploadSession", verb = "complete", code = "transition_by_update_permission", "a transition granted only by upload_session:update, running in shadow; it needs upload_session:transition:complete or a role of ["system", "user"]");
        }
    }

    // Create state machine from entity's actual status and validate transition
    let current_state: UploadSessionState = match entity.status.to_string().parse() {
        Ok(s) => s,
        Err(_) => return (StatusCode::CONFLICT, Json(ApiResponse::<UploadSessionResponseDto>::error("The stored state is not a state of this machine"))),
    };
    let sm = UploadSessionStateMachine::from_state(current_state);
    if !sm.can_transition(UploadSessionTransition::Complete) {
        return (StatusCode::BAD_REQUEST, Json(ApiResponse::<UploadSessionResponseDto>::error("Transition not allowed from current state")));
    }

    {
        use backbone_core::row_rule as r;
        let row = &serde_json::to_value(&entity).unwrap_or_default();
        let state = row.get("status").and_then(|v| v.as_str()).unwrap_or_default();
        // Guard: uploaded_chunks == total_chunks
        if ["uploading"].contains(&state) && !r::holds(&r::eq(r::field(row, "uploaded_chunks"), r::field(row, "total_chunks"))) {
            return (StatusCode::UNPROCESSABLE_ENTITY, Json(ApiResponse::<UploadSessionResponseDto>::error("The complete transition's guard does not hold: uploaded_chunks == total_chunks")));
        }
    }

    // Apply transition via partial update
    let mut fields: HashMap<String, serde_json::Value> = HashMap::new();
    fields.insert("status".to_string(), serde_json::Value::String("completing".to_string()));

    match backbone_core::write_guard::as_transition("complete", service.partial_update(&id, fields)).await {
        Ok(Some(updated)) => {
            let response: UploadSessionResponseDto = updated.into();
            (StatusCode::OK, Json(ApiResponse::ok(response)))
        }
        Ok(None) => (StatusCode::NOT_FOUND, Json(ApiResponse::<UploadSessionResponseDto>::not_found("UploadSession", &id))),
        Err(e) => (StatusCode::INTERNAL_SERVER_ERROR, Json(ApiResponse::<UploadSessionResponseDto>::error(e.to_string()))),
    }
}

/// Execute finish transition on a UploadSession.
///
/// POST /upload_sessions/:id/transitions/finish
pub async fn finish_transition(
    axum::extract::State(service): axum::extract::State<Arc<UploadSessionService>>,
    axum::extract::Path(id): axum::extract::Path<String>,
    #[cfg(feature = "auth")] axum::Extension(auth): axum::Extension<AuthContext>,
) -> impl axum::response::IntoResponse {
    use axum::{http::StatusCode, Json};

    // Get current entity
    let entity = match service.get_by_id(&id).await {
        Ok(Some(e)) => e,
        Ok(None) => return (StatusCode::NOT_FOUND, Json(ApiResponse::<UploadSessionResponseDto>::not_found("UploadSession", &id))),
        Err(e) => return (StatusCode::INTERNAL_SERVER_ERROR, Json(ApiResponse::<UploadSessionResponseDto>::error(e.to_string()))),
    };

    // Check permission (if auth enabled)
    #[cfg(feature = "auth")]
    {
        let allowed_roles = UploadSessionTransition::Finish.allowed_roles();
        let has_specific_perm = auth.permissions.iter().any(|p| p == "upload_session:transition:finish");
        let has_update_perm = auth.permissions.iter().any(|p| p == "upload_session:update");
        let has_role = auth.roles.iter().any(|r| allowed_roles.contains(&r.as_str()));
        if !has_specific_perm && !has_role {
            if !has_update_perm {
                return (StatusCode::FORBIDDEN, Json(ApiResponse::<UploadSessionResponseDto>::error("Insufficient permissions for finish transition")));
            }
            tracing::warn!(target: "backbone::write_guard", entity = "UploadSession", verb = "finish", code = "transition_by_update_permission", "a transition granted only by upload_session:update, running in shadow; it needs upload_session:transition:finish or a role of ["system"]");
        }
    }

    // Create state machine from entity's actual status and validate transition
    let current_state: UploadSessionState = match entity.status.to_string().parse() {
        Ok(s) => s,
        Err(_) => return (StatusCode::CONFLICT, Json(ApiResponse::<UploadSessionResponseDto>::error("The stored state is not a state of this machine"))),
    };
    let sm = UploadSessionStateMachine::from_state(current_state);
    if !sm.can_transition(UploadSessionTransition::Finish) {
        return (StatusCode::BAD_REQUEST, Json(ApiResponse::<UploadSessionResponseDto>::error("Transition not allowed from current state")));
    }

    // Apply transition via partial update
    let mut fields: HashMap<String, serde_json::Value> = HashMap::new();
    fields.insert("status".to_string(), serde_json::Value::String("completed".to_string()));

    match backbone_core::write_guard::as_transition("finish", service.partial_update(&id, fields)).await {
        Ok(Some(updated)) => {
            let response: UploadSessionResponseDto = updated.into();
            (StatusCode::OK, Json(ApiResponse::ok(response)))
        }
        Ok(None) => (StatusCode::NOT_FOUND, Json(ApiResponse::<UploadSessionResponseDto>::not_found("UploadSession", &id))),
        Err(e) => (StatusCode::INTERNAL_SERVER_ERROR, Json(ApiResponse::<UploadSessionResponseDto>::error(e.to_string()))),
    }
}

/// Execute fail transition on a UploadSession.
///
/// POST /upload_sessions/:id/transitions/fail
pub async fn fail_transition(
    axum::extract::State(service): axum::extract::State<Arc<UploadSessionService>>,
    axum::extract::Path(id): axum::extract::Path<String>,
    #[cfg(feature = "auth")] axum::Extension(auth): axum::Extension<AuthContext>,
) -> impl axum::response::IntoResponse {
    use axum::{http::StatusCode, Json};

    // Get current entity
    let entity = match service.get_by_id(&id).await {
        Ok(Some(e)) => e,
        Ok(None) => return (StatusCode::NOT_FOUND, Json(ApiResponse::<UploadSessionResponseDto>::not_found("UploadSession", &id))),
        Err(e) => return (StatusCode::INTERNAL_SERVER_ERROR, Json(ApiResponse::<UploadSessionResponseDto>::error(e.to_string()))),
    };

    // Check permission (if auth enabled)
    #[cfg(feature = "auth")]
    {
        let allowed_roles = UploadSessionTransition::Fail.allowed_roles();
        let has_specific_perm = auth.permissions.iter().any(|p| p == "upload_session:transition:fail");
        let has_update_perm = auth.permissions.iter().any(|p| p == "upload_session:update");
        let has_role = auth.roles.iter().any(|r| allowed_roles.contains(&r.as_str()));
        if !has_specific_perm && !has_role {
            if !has_update_perm {
                return (StatusCode::FORBIDDEN, Json(ApiResponse::<UploadSessionResponseDto>::error("Insufficient permissions for fail transition")));
            }
            tracing::warn!(target: "backbone::write_guard", entity = "UploadSession", verb = "fail", code = "transition_by_update_permission", "a transition granted only by upload_session:update, running in shadow; it needs upload_session:transition:fail or a role of ["system"]");
        }
    }

    // Create state machine from entity's actual status and validate transition
    let current_state: UploadSessionState = match entity.status.to_string().parse() {
        Ok(s) => s,
        Err(_) => return (StatusCode::CONFLICT, Json(ApiResponse::<UploadSessionResponseDto>::error("The stored state is not a state of this machine"))),
    };
    let sm = UploadSessionStateMachine::from_state(current_state);
    if !sm.can_transition(UploadSessionTransition::Fail) {
        return (StatusCode::BAD_REQUEST, Json(ApiResponse::<UploadSessionResponseDto>::error("Transition not allowed from current state")));
    }

    // Apply transition via partial update
    let mut fields: HashMap<String, serde_json::Value> = HashMap::new();
    fields.insert("status".to_string(), serde_json::Value::String("failed".to_string()));

    match backbone_core::write_guard::as_transition("fail", service.partial_update(&id, fields)).await {
        Ok(Some(updated)) => {
            let response: UploadSessionResponseDto = updated.into();
            (StatusCode::OK, Json(ApiResponse::ok(response)))
        }
        Ok(None) => (StatusCode::NOT_FOUND, Json(ApiResponse::<UploadSessionResponseDto>::not_found("UploadSession", &id))),
        Err(e) => (StatusCode::INTERNAL_SERVER_ERROR, Json(ApiResponse::<UploadSessionResponseDto>::error(e.to_string()))),
    }
}

/// Execute abort transition on a UploadSession.
///
/// POST /upload_sessions/:id/transitions/abort
pub async fn abort_transition(
    axum::extract::State(service): axum::extract::State<Arc<UploadSessionService>>,
    axum::extract::Path(id): axum::extract::Path<String>,
    #[cfg(feature = "auth")] axum::Extension(auth): axum::Extension<AuthContext>,
) -> impl axum::response::IntoResponse {
    use axum::{http::StatusCode, Json};

    // Get current entity
    let entity = match service.get_by_id(&id).await {
        Ok(Some(e)) => e,
        Ok(None) => return (StatusCode::NOT_FOUND, Json(ApiResponse::<UploadSessionResponseDto>::not_found("UploadSession", &id))),
        Err(e) => return (StatusCode::INTERNAL_SERVER_ERROR, Json(ApiResponse::<UploadSessionResponseDto>::error(e.to_string()))),
    };

    // Check permission (if auth enabled)
    #[cfg(feature = "auth")]
    {
        let allowed_roles = UploadSessionTransition::Abort.allowed_roles();
        let has_specific_perm = auth.permissions.iter().any(|p| p == "upload_session:transition:abort");
        let has_update_perm = auth.permissions.iter().any(|p| p == "upload_session:update");
        let has_role = auth.roles.iter().any(|r| allowed_roles.contains(&r.as_str()));
        if !has_specific_perm && !has_role {
            if !has_update_perm {
                return (StatusCode::FORBIDDEN, Json(ApiResponse::<UploadSessionResponseDto>::error("Insufficient permissions for abort transition")));
            }
            tracing::warn!(target: "backbone::write_guard", entity = "UploadSession", verb = "abort", code = "transition_by_update_permission", "a transition granted only by upload_session:update, running in shadow; it needs upload_session:transition:abort or a role of ["user", "admin"]");
        }
    }

    // Create state machine from entity's actual status and validate transition
    let current_state: UploadSessionState = match entity.status.to_string().parse() {
        Ok(s) => s,
        Err(_) => return (StatusCode::CONFLICT, Json(ApiResponse::<UploadSessionResponseDto>::error("The stored state is not a state of this machine"))),
    };
    let sm = UploadSessionStateMachine::from_state(current_state);
    if !sm.can_transition(UploadSessionTransition::Abort) {
        return (StatusCode::BAD_REQUEST, Json(ApiResponse::<UploadSessionResponseDto>::error("Transition not allowed from current state")));
    }

    // Guard `$actor.id == user_id || $actor.has_role('admin')` not compiled (reads the writer, the time or the row before the write); the transition is not checked against it.
    // Apply transition via partial update
    let mut fields: HashMap<String, serde_json::Value> = HashMap::new();
    fields.insert("status".to_string(), serde_json::Value::String("failed".to_string()));

    match backbone_core::write_guard::as_transition("abort", service.partial_update(&id, fields)).await {
        Ok(Some(updated)) => {
            let response: UploadSessionResponseDto = updated.into();
            (StatusCode::OK, Json(ApiResponse::ok(response)))
        }
        Ok(None) => (StatusCode::NOT_FOUND, Json(ApiResponse::<UploadSessionResponseDto>::not_found("UploadSession", &id))),
        Err(e) => (StatusCode::INTERNAL_SERVER_ERROR, Json(ApiResponse::<UploadSessionResponseDto>::error(e.to_string()))),
    }
}

/// Execute expire transition on a UploadSession.
///
/// POST /upload_sessions/:id/transitions/expire
pub async fn expire_transition(
    axum::extract::State(service): axum::extract::State<Arc<UploadSessionService>>,
    axum::extract::Path(id): axum::extract::Path<String>,
    #[cfg(feature = "auth")] axum::Extension(auth): axum::Extension<AuthContext>,
) -> impl axum::response::IntoResponse {
    use axum::{http::StatusCode, Json};

    // Get current entity
    let entity = match service.get_by_id(&id).await {
        Ok(Some(e)) => e,
        Ok(None) => return (StatusCode::NOT_FOUND, Json(ApiResponse::<UploadSessionResponseDto>::not_found("UploadSession", &id))),
        Err(e) => return (StatusCode::INTERNAL_SERVER_ERROR, Json(ApiResponse::<UploadSessionResponseDto>::error(e.to_string()))),
    };

    // Check permission (if auth enabled)
    #[cfg(feature = "auth")]
    {
        let allowed_roles = UploadSessionTransition::Expire.allowed_roles();
        let has_specific_perm = auth.permissions.iter().any(|p| p == "upload_session:transition:expire");
        let has_update_perm = auth.permissions.iter().any(|p| p == "upload_session:update");
        let has_role = auth.roles.iter().any(|r| allowed_roles.contains(&r.as_str()));
        if !has_specific_perm && !has_role {
            if !has_update_perm {
                return (StatusCode::FORBIDDEN, Json(ApiResponse::<UploadSessionResponseDto>::error("Insufficient permissions for expire transition")));
            }
            tracing::warn!(target: "backbone::write_guard", entity = "UploadSession", verb = "expire", code = "transition_by_update_permission", "a transition granted only by upload_session:update, running in shadow; it needs upload_session:transition:expire or a role of ["system"]");
        }
    }

    // Create state machine from entity's actual status and validate transition
    let current_state: UploadSessionState = match entity.status.to_string().parse() {
        Ok(s) => s,
        Err(_) => return (StatusCode::CONFLICT, Json(ApiResponse::<UploadSessionResponseDto>::error("The stored state is not a state of this machine"))),
    };
    let sm = UploadSessionStateMachine::from_state(current_state);
    if !sm.can_transition(UploadSessionTransition::Expire) {
        return (StatusCode::BAD_REQUEST, Json(ApiResponse::<UploadSessionResponseDto>::error("Transition not allowed from current state")));
    }

    // Guard `expires_at < now()` not compiled (reads the writer, the time or the row before the write); the transition is not checked against it.
    // Apply transition via partial update
    let mut fields: HashMap<String, serde_json::Value> = HashMap::new();
    fields.insert("status".to_string(), serde_json::Value::String("expired".to_string()));

    match backbone_core::write_guard::as_transition("expire", service.partial_update(&id, fields)).await {
        Ok(Some(updated)) => {
            let response: UploadSessionResponseDto = updated.into();
            (StatusCode::OK, Json(ApiResponse::ok(response)))
        }
        Ok(None) => (StatusCode::NOT_FOUND, Json(ApiResponse::<UploadSessionResponseDto>::not_found("UploadSession", &id))),
        Err(e) => (StatusCode::INTERNAL_SERVER_ERROR, Json(ApiResponse::<UploadSessionResponseDto>::error(e.to_string()))),
    }
}

/// Execute retry transition on a UploadSession.
///
/// POST /upload_sessions/:id/transitions/retry
pub async fn retry_transition(
    axum::extract::State(service): axum::extract::State<Arc<UploadSessionService>>,
    axum::extract::Path(id): axum::extract::Path<String>,
    #[cfg(feature = "auth")] axum::Extension(auth): axum::Extension<AuthContext>,
) -> impl axum::response::IntoResponse {
    use axum::{http::StatusCode, Json};

    // Get current entity
    let entity = match service.get_by_id(&id).await {
        Ok(Some(e)) => e,
        Ok(None) => return (StatusCode::NOT_FOUND, Json(ApiResponse::<UploadSessionResponseDto>::not_found("UploadSession", &id))),
        Err(e) => return (StatusCode::INTERNAL_SERVER_ERROR, Json(ApiResponse::<UploadSessionResponseDto>::error(e.to_string()))),
    };

    // Check permission (if auth enabled)
    #[cfg(feature = "auth")]
    {
        let allowed_roles = UploadSessionTransition::Retry.allowed_roles();
        let has_specific_perm = auth.permissions.iter().any(|p| p == "upload_session:transition:retry");
        let has_update_perm = auth.permissions.iter().any(|p| p == "upload_session:update");
        let has_role = auth.roles.iter().any(|r| allowed_roles.contains(&r.as_str()));
        if !has_specific_perm && !has_role {
            if !has_update_perm {
                return (StatusCode::FORBIDDEN, Json(ApiResponse::<UploadSessionResponseDto>::error("Insufficient permissions for retry transition")));
            }
            tracing::warn!(target: "backbone::write_guard", entity = "UploadSession", verb = "retry", code = "transition_by_update_permission", "a transition granted only by upload_session:update, running in shadow; it needs upload_session:transition:retry or a role of ["user"]");
        }
    }

    // Create state machine from entity's actual status and validate transition
    let current_state: UploadSessionState = match entity.status.to_string().parse() {
        Ok(s) => s,
        Err(_) => return (StatusCode::CONFLICT, Json(ApiResponse::<UploadSessionResponseDto>::error("The stored state is not a state of this machine"))),
    };
    let sm = UploadSessionStateMachine::from_state(current_state);
    if !sm.can_transition(UploadSessionTransition::Retry) {
        return (StatusCode::BAD_REQUEST, Json(ApiResponse::<UploadSessionResponseDto>::error("Transition not allowed from current state")));
    }

    // Guard `$actor.id == user_id` not compiled (reads the writer, the time or the row before the write); the transition is not checked against it.
    // Apply transition via partial update
    let mut fields: HashMap<String, serde_json::Value> = HashMap::new();
    fields.insert("status".to_string(), serde_json::Value::String("initiated".to_string()));

    match backbone_core::write_guard::as_transition("retry", service.partial_update(&id, fields)).await {
        Ok(Some(updated)) => {
            let response: UploadSessionResponseDto = updated.into();
            (StatusCode::OK, Json(ApiResponse::ok(response)))
        }
        Ok(None) => (StatusCode::NOT_FOUND, Json(ApiResponse::<UploadSessionResponseDto>::not_found("UploadSession", &id))),
        Err(e) => (StatusCode::INTERNAL_SERVER_ERROR, Json(ApiResponse::<UploadSessionResponseDto>::error(e.to_string()))),
    }
}

/// Create routes for state transitions.
pub fn create_upload_session_transition_routes(service: Arc<UploadSessionService>) -> Router {
    use axum::routing::post;

    Router::new()
        .route("/upload_sessions/:id/transitions/start_upload", post(start_upload_transition))
        .route("/upload_sessions/:id/transitions/add_part", post(add_part_transition))
        .route("/upload_sessions/:id/transitions/complete", post(complete_transition))
        .route("/upload_sessions/:id/transitions/finish", post(finish_transition))
        .route("/upload_sessions/:id/transitions/fail", post(fail_transition))
        .route("/upload_sessions/:id/transitions/abort", post(abort_transition))
        .route("/upload_sessions/:id/transitions/expire", post(expire_transition))
        .route("/upload_sessions/:id/transitions/retry", post(retry_transition))
        .with_state(service)
}