headless_lms_server/domain/

error.rs

/*!
Contains error and result types for all the controllers.
*/

use std::panic::Location;

use crate::domain::authorization::AuthorizedResponse;
use crate::domain::oauth::redirects::error_redirect_url;
use actix_web::{
    HttpResponse, HttpResponseBuilder, error,
    http::{StatusCode, header::ContentType},
};
use backtrace::Backtrace;
use derive_more::Display;
use dpop_verifier::error::DpopError;
use headless_lms_authorization::error::{AuthorizationError, AuthorizationErrorType};
use headless_lms_base::error::{backend_error::BackendError, clean_format::ColorChoice};
use headless_lms_chatbot::prelude::{ChatbotError, ChatbotErrorType};
use headless_lms_credit_registration::error::{
    CreditRegistrationError, CreditRegistrationErrorType,
};
use headless_lms_models::{ModelError, ModelErrorType, prelude::UtilErrorType};
use headless_lms_utils::error::util_error::{SisuErrorVariant, UtilError};
use headless_lms_utils::http::escape_auth_param;
use serde::{Deserialize, Serialize};
use tracing_error::SpanTrace;

use uuid::Uuid;

const MISSING_EXERCISE_TYPE_DESCRIPTION: &str = "Missing exercise type for exercise task.";

/**
Used as the result types for all controllers.
Only put information here that you want to be visible to users.

See also [ControllerError] for documentation on how to return errors from controllers.
*/
pub type ControllerResult<T, E = ControllerError> = std::result::Result<AuthorizedResponse<T>, E>;

/// The type of [ControllerError] that occured.
#[derive(Debug, Display, Serialize, Deserialize)]
pub enum ControllerErrorType {
    /// HTTP status code 500.
    #[display("Internal server error")]
    InternalServerError,

    /// HTTP status code 400.
    #[display("Bad request")]
    BadRequest,

    /// HTTP status code 400.
    #[display("Bad request")]
    BadRequestWithData(ErrorMetadata),

    /// HTTP status code 422 with a specific domain reason, so clients can branch
    /// on a stable `message_key` instead of parsing the human-readable message.
    #[display("Bad request")]
    BadRequestWithReason(BadRequestReason),

    /// HTTP status code 426. The client is too old and must be upgraded.
    #[display("Upgrade required")]
    UpgradeRequired,

    /// HTTP status code 404.
    #[display("Not found")]
    NotFound,

    /// HTTP status code 429.
    #[display("Too many requests")]
    TooManyRequests,

    /// HTTP status code 401. Needs to log in.
    #[display("Unauthorized")]
    Unauthorized,

    /// HTTP status code 401 with a specific domain reason.
    #[display("Unauthorized")]
    UnauthorizedWithReason(UnauthorizedReason),

    /// HTTP status code 403. Is logged in but is not allowed to access the resource.
    #[display("Forbidden")]
    Forbidden,

    /// Varied response based on error
    #[display("OAuthError")]
    OAuthError(Box<OAuthErrorData>),

    /// SISUERROR
    #[display("SisuError")]
    SisuError(SisuErrorType),
}

#[derive(Debug, Display, Serialize, Deserialize, Clone, Copy, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum UnauthorizedReason {
    #[display("Chapter not open yet")]
    ChapterNotOpenYet,
    #[display("Authentication required for exam exercise")]
    AuthenticationRequiredForExamExercise,
}

impl UnauthorizedReason {
    /// Returns the stable message key for this unauthorized reason.
    fn message_key(self) -> &'static str {
        match self {
            Self::ChapterNotOpenYet => "chapter_not_open_yet",
            Self::AuthenticationRequiredForExamExercise => {
                "authentication_required_for_exam_exercise"
            }
        }
    }
}

/// Builds a 422 whose `message_key` the client keys its error handling on.
pub fn bad_request_with_reason(reason: BadRequestReason, message: String) -> ControllerError {
    controller_err!(BadRequestWithReason(reason), message)
}

/// Bad request reasons a client can branch on. Only `CourseSlugAlreadyTaken` has a web-frontend
/// translation; the rest are consumed by the VSCode client, which renders its own message.
#[derive(Debug, Display, Serialize, Deserialize, Clone, Copy, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum BadRequestReason {
    #[display("Course slug already taken")]
    CourseSlugAlreadyTaken,
    #[display("Foreign key violation")]
    ForeignKeyViolation,
    /// The user is not enrolled on the course the requested exercise belongs to.
    #[display("Not enrolled")]
    NotEnrolled,
    /// A submission named a file that was uploaded but has since been reaped.
    #[display("Upload expired")]
    UploadExpired,
    /// A submission named a file the host has no upload record of for this exercise and user.
    #[display("Unknown upload")]
    UnknownUpload,
    /// A submission named the same uploaded file more than once.
    #[display("Duplicate upload")]
    DuplicateUpload,
    /// A save named a version of the record that is no longer the latest.
    #[display("Stale version")]
    StaleVersion,
}

impl BadRequestReason {
    /// Returns the stable message key for this bad request reason.
    fn message_key(self) -> &'static str {
        match self {
            Self::CourseSlugAlreadyTaken => "course_slug_already_taken",
            Self::ForeignKeyViolation => "foreign_key_violation",
            Self::NotEnrolled => "not_enrolled",
            Self::UploadExpired => "upload_expired",
            Self::UnknownUpload => "unknown_upload",
            Self::DuplicateUpload => "duplicate_upload",
            Self::StaleVersion => "stale_version",
        }
    }

    /// Both slug indexes collapse into one reason: they guard the same user mistake.
    fn from_database_constraint(constraint: &str) -> Option<Self> {
        match constraint {
            "courses_slug_key_when_not_deleted"
            | "course_language_groups_slug_unique_non_deleted" => {
                Some(Self::CourseSlugAlreadyTaken)
            }
            _ => None,
        }
    }
}

#[derive(Debug, Display, Serialize, Deserialize, Clone, Copy, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum SisuErrorType {
    #[display("invalid course code")]
    InvalidCourseCode,
    #[display("generic sisu error")]
    GenericSisuError,
    #[display("sisu resource not found")]
    SisuResourceNotFound,
}

impl SisuErrorType {
    /// Returns the stable message key for this unauthorized reason.
    fn message_key(self) -> &'static str {
        match self {
            Self::InvalidCourseCode => "invalid_course_code",
            Self::GenericSisuError => "generic_sisu_error",
            Self::SisuResourceNotFound => "sisu_resource_not_found",
        }
    }
}

/**
Represents error messages that are sent in responses. Used as the error type in [ControllerError], which is used by all the controllers in the application.

All the information in the error is meant to be seen by the user. The type of error is determined by the [ControllerErrorType] enum, which is stored inside this struct. The type of the error determines which HTTP status code will be sent to the user.

## Examples

### Usage without source error

```no_run
# use headless_lms_server::prelude::*;
# fn random_function() -> ControllerResult<web::Json<()>> {
#    let token = skip_authorize();
#    let erroneous_condition = 1 == 1;
if erroneous_condition {
    return Err(ControllerError::new(
        ControllerErrorType::BadRequest,
        "Cannot create a new account when signed in.".to_string(),
        None,
    ));
}
# token.authorized_ok(web::Json(()))
# }
```

### Usage with a source error

Used when calling a function that returns an error that cannot be automatically converted to an ControllerError. (See `impl From<X>` implementations on this struct.)

```no_run
# use headless_lms_server::prelude::*;
# fn some_function_returning_an_error() -> ControllerResult<web::Json<()>> {
#    return Err(ControllerError::new(
#         ControllerErrorType::BadRequest,
#         "Cannot create a new account when signed in.".to_string(),
#         None,
#     ));
# }
#
# fn random_function() -> ControllerResult<web::Json<()>> {
#    let token = skip_authorize();
#    let erroneous_condition = 1 == 1;
some_function_returning_an_error().map_err(|original_error| {
    ControllerError::new(
        ControllerErrorType::InternalServerError,
        "Could not read file".to_string(),
        Some(original_error.into()),
    )
})?;
# token.authorized_ok(web::Json(()))
# }
```

### Example HTTP response from an error

```json
{
    "title": "Internal Server Error",
    "message": "pool timed out while waiting for an open connection",
    "source": "source of error"
}
```
*/
pub struct ControllerError {
    error_type: <ControllerError as BackendError>::ErrorType,
    message: String,
    /// Original error that caused this error.
    source: Option<anyhow::Error>,
    /// A trace of tokio tracing spans, generated automatically when the error is generated.
    span_trace: Box<SpanTrace>,
    /// Stack trace, generated automatically when the error is created.
    backtrace: Box<Backtrace>,
    /// Source location where the error was raised.
    location: Option<&'static Location<'static>>,
}

// Generate the clean developer `Debug`/`clean_string` and a cause resolver.
headless_lms_base::impl_clean_debug!(
    ControllerError,
    [
        ControllerError,
        AuthorizationError,
        ChatbotError,
        CreditRegistrationError,
        ModelError,
        UtilError
    ]
);

impl std::error::Error for ControllerError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        self.source
            .as_deref()
            .map(|e| e as &(dyn std::error::Error + 'static))
    }

    fn cause(&self) -> Option<&dyn std::error::Error> {
        self.source()
    }
}

impl std::fmt::Display for ControllerError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(
            f,
            "ControllerError {:?} {:?}",
            self.error_type, self.message
        )
    }
}

impl BackendError for ControllerError {
    type ErrorType = ControllerErrorType;

    fn backtrace(&self) -> Option<&Backtrace> {
        Some(&self.backtrace)
    }

    fn error_type(&self) -> &Self::ErrorType {
        &self.error_type
    }

    fn message(&self) -> &str {
        &self.message
    }

    fn span_trace(&self) -> &SpanTrace {
        &self.span_trace
    }

    fn location(&self) -> Option<&'static Location<'static>> {
        self.location
    }

    fn new_with_traces_and_location<M: Into<String>, S: Into<Option<anyhow::Error>>>(
        error_type: Self::ErrorType,
        message: M,
        source_error: S,
        backtrace: Backtrace,
        span_trace: SpanTrace,
        location: Option<&'static Location<'static>>,
    ) -> Self {
        Self {
            error_type,
            message: message.into(),
            source: source_error.into(),
            span_trace: Box::new(span_trace),
            backtrace: Box::new(backtrace),
            location,
        }
    }
}

#[derive(Debug, Serialize, Deserialize, Clone)]
#[serde(rename_all = "snake_case")]
pub enum ErrorMetadata {
    BlockId(Uuid),
    ForeignKeyViolationMetadata {
        constraint: Option<String>,
        table: Option<String>,
    },
}

#[derive(Debug, Serialize, Deserialize, utoipa::ToSchema)]
pub struct ApiErrorIssue {
    pub path: Option<String>,
    pub code: Option<String>,
    pub message: String,
}

#[derive(Debug, Serialize, Deserialize, Clone, Copy)]
#[serde(rename_all = "snake_case")]
pub enum ValidationIssueCode {
    MissingExerciseType,
}

impl ValidationIssueCode {
    /// Returns stable API-facing code value for validation issues.
    fn as_api_code(self) -> String {
        serde_json::to_value(self)
            .ok()
            .and_then(|v| v.as_str().map(|code| code.to_string()))
            .unwrap_or_else(|| "unknown_validation_issue".to_string())
    }
}

/// Canonical API error envelope returned for controlled application errors.
#[derive(Debug, Serialize, Deserialize, utoipa::ToSchema)]
pub struct ApiErrorResponse {
    #[serde(rename = "type")]
    pub error_type: String,
    pub message_key: String,
    pub message: String,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub errors: Vec<ApiErrorIssue>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub metadata: Option<serde_json::Value>,
}

impl error::ResponseError for ControllerError {
    fn error_response(&self) -> HttpResponse {
        if let ControllerErrorType::InternalServerError = &self.error_type {
            // Clean format, colored only on a TTY (Auto); the DB report below stays plain.
            error!(
                "Internal server error:\n{}",
                self.clean_string(ColorChoice::Auto)
            );

            if let Some(pool) = crate::domain::internal_error_reporting::error_reporting_pool() {
                let pool = pool.clone();
                let message = self.message.clone();
                let stack_trace = format!("{:?}", self);
                let details = serde_json::json!({
                    "kind": "controller_error",
                    "controller_error_type": self.error_type.to_string(),
                });

                // Uses the main DB pool intentionally for best-effort reporting; this can amplify outage pressure.
                actix_web::rt::spawn(async move {
                    let report = headless_lms_models::errors::NewErrorReport {
                        service: "headless-lms".to_string(),
                        error_source: Some(headless_lms_models::errors::ErrorSource::Backend),
                        message,
                        stack_trace: Some(stack_trace),
                        path: None,
                        app_version: None,
                        details: Some(details),
                    };
                    headless_lms_models::errors::insert_best_effort(&pool, &report).await;
                });
            }
        }
        if let ControllerErrorType::OAuthError(data) = &self.error_type {
            if let Some(location) = data.redirect_uri.as_deref().and_then(|redirect_uri| {
                error_redirect_url(
                    redirect_uri,
                    &data.error,
                    Some(&data.error_description),
                    data.state.as_deref(),
                    data.issuer.as_deref(),
                )
            }) {
                return HttpResponse::Found()
                    .append_header(("Location", location))
                    .finish();
            }

            let status = match data.error.as_str() {
                "invalid_client" => StatusCode::UNAUTHORIZED,     // 401
                "invalid_token" => StatusCode::UNAUTHORIZED,      // 401 (bearer)
                "invalid_dpop_proof" => StatusCode::UNAUTHORIZED, // 401 (dpop)
                "use_dpop_nonce" => StatusCode::UNAUTHORIZED,     // 401 (dpop)
                "insufficient_scope" => StatusCode::FORBIDDEN,    // 403
                _ => StatusCode::BAD_REQUEST,
            };

            let mut res = HttpResponse::build(status);

            match data.error.as_str() {
                // OAuth2 Bearer challenges (RFC 6750 §3)
                "invalid_client" | "invalid_token" | "insufficient_scope" | "invalid_request" => {
                    let err = escape_auth_param(&data.error);
                    let desc = escape_auth_param(&data.error_description);
                    let hdr = format!(r#"Bearer error="{}", error_description="{}""#, err, desc);
                    res.append_header(("WWW-Authenticate", hdr));
                }

                // DPoP auth challenges (RFC 9449 §12.2)
                "invalid_dpop_proof" => {
                    let err = escape_auth_param(&data.error);
                    let desc = escape_auth_param(&data.error_description);
                    let hdr = format!(r#"DPoP error="{}", error_description="{}""#, err, desc);
                    res.append_header(("WWW-Authenticate", hdr));
                }

                "use_dpop_nonce" => {
                    let err = escape_auth_param(&data.error);
                    let desc = escape_auth_param(&data.error_description);
                    let hdr = format!(r#"DPoP error="{}", error_description="{}""#, err, desc);
                    res.append_header(("WWW-Authenticate", hdr));

                    // Provide the server-generated nonce (clients must echo it in the next proof)
                    if let Some(nonce) = &data.nonce {
                        res.append_header(("DPoP-Nonce", nonce.clone()));
                    }
                }

                _ => {}
            }

            // Prevent caching per RFC 6749 §5.1 (common practice for error responses too)
            res.append_header(("Cache-Control", "no-store"))
                .append_header(("Pragma", "no-cache"));

            // OAuth token/introspection semantics are standardized around `error` and
            // `error_description`; keep compatibility for protocol clients.
            return res.json(serde_json::json!({
                "error": data.error,
                "error_description": data.error_description
            }));
        }

        let status = self.status_code();

        let metadata = match &self.error_type {
            ControllerErrorType::BadRequestWithData(data) => Some(data.clone()),
            _ => None,
        };

        let metadata_json = metadata.map(|metadata| match metadata {
            ErrorMetadata::BlockId(id) => serde_json::json!({ "block_id": id }),
            ErrorMetadata::ForeignKeyViolationMetadata { constraint, table } => {
                serde_json::json!({
            "constraint": constraint,
            "table": table })
            }
        });

        let (error_type, message_key) = self.error_type_and_message_key();
        let errors = self.validation_issues();
        let error_response = ApiErrorResponse {
            error_type: error_type.to_string(),
            message_key: message_key.to_string(),
            message: self.message.clone(),
            errors,
            metadata: metadata_json,
        };

        HttpResponseBuilder::new(status)
            .append_header(ContentType::json())
            .body(serde_json::to_string(&error_response).unwrap_or_else(|e| {
                error!("Error while serialising error response: {e}");
                r#"{"type":"internal_error","message_key":"internal_error","message":"Internal server error"}"#.to_string()
            }))
    }

    fn status_code(&self) -> StatusCode {
        match self.error_type {
            ControllerErrorType::InternalServerError => StatusCode::INTERNAL_SERVER_ERROR,
            ControllerErrorType::BadRequest => StatusCode::UNPROCESSABLE_ENTITY,
            ControllerErrorType::BadRequestWithData(_) => StatusCode::UNPROCESSABLE_ENTITY,
            ControllerErrorType::BadRequestWithReason(_) => StatusCode::UNPROCESSABLE_ENTITY,
            ControllerErrorType::UpgradeRequired => StatusCode::UPGRADE_REQUIRED,
            ControllerErrorType::NotFound => StatusCode::NOT_FOUND,
            ControllerErrorType::TooManyRequests => StatusCode::TOO_MANY_REQUESTS,
            ControllerErrorType::Unauthorized => StatusCode::UNAUTHORIZED,
            ControllerErrorType::UnauthorizedWithReason(_) => StatusCode::UNAUTHORIZED,
            ControllerErrorType::Forbidden => StatusCode::FORBIDDEN,
            ControllerErrorType::OAuthError(_) => StatusCode::OK,
            ControllerErrorType::SisuError(SisuErrorType::InvalidCourseCode) => {
                StatusCode::BAD_REQUEST
            }
            ControllerErrorType::SisuError(SisuErrorType::GenericSisuError) => {
                StatusCode::BAD_GATEWAY
            }
            ControllerErrorType::SisuError(SisuErrorType::SisuResourceNotFound) => {
                StatusCode::NOT_FOUND
            }
        }
    }
}

impl ControllerError {
    /// Adds the authorization server's issuer to an OAuth error that redirects to the client.
    pub fn with_oauth_issuer(mut self, issuer: String) -> Self {
        if let ControllerErrorType::OAuthError(data) = &mut self.error_type
            && data.redirect_uri.is_some()
        {
            data.issuer = Some(issuer);
        }
        self
    }

    fn error_type_and_message_key(&self) -> (&'static str, &'static str) {
        match self.error_type {
            ControllerErrorType::InternalServerError => ("internal_error", "internal_error"),
            ControllerErrorType::BadRequest => ("validation_error", "validation_error"),
            ControllerErrorType::BadRequestWithData(ErrorMetadata::BlockId(_)) => {
                ("validation_error", "validation_error_with_metadata")
            }
            ControllerErrorType::BadRequestWithData(
                ErrorMetadata::ForeignKeyViolationMetadata { .. },
            ) => ("validation_error", "foreign_key_violation"),
            ControllerErrorType::BadRequestWithReason(reason) => {
                ("validation_error", reason.message_key())
            }
            ControllerErrorType::UpgradeRequired => ("obsolete_client", "obsolete_client"),
            ControllerErrorType::NotFound => ("not_found", "not_found"),
            // Matches the rate limit middleware's response.
            ControllerErrorType::TooManyRequests => ("rate_limit", "rate_limited"),
            ControllerErrorType::Unauthorized => ("unauthorized", "unauthorized"),
            ControllerErrorType::UnauthorizedWithReason(reason) => {
                ("unauthorized", reason.message_key())
            }
            ControllerErrorType::Forbidden => ("forbidden", "forbidden"),
            ControllerErrorType::OAuthError(_) => ("oauth_error", "oauth_error"),
            ControllerErrorType::SisuError(error_type) => ("sisu_error", error_type.message_key()),
        }
    }

    /// Derives issue-level validation details from known backend validation cases.
    fn validation_issues(&self) -> Vec<ApiErrorIssue> {
        match &self.error_type {
            ControllerErrorType::BadRequestWithData(_)
                if self.message == MISSING_EXERCISE_TYPE_DESCRIPTION =>
            {
                vec![ApiErrorIssue {
                    path: Some("exercise_type".to_string()),
                    code: Some(ValidationIssueCode::MissingExerciseType.as_api_code()),
                    message: self.message.clone(),
                }]
            }
            _ => Vec::new(),
        }
    }
}

#[derive(Debug, Serialize, Deserialize, Clone, Default)]
#[serde(rename_all = "snake_case")]
pub struct OAuthErrorData {
    pub error: String,
    pub error_description: String,
    pub redirect_uri: Option<String>,
    pub state: Option<String>,
    pub nonce: Option<String>,
    /// Sent with errors redirected to the client (RFC 9207); see
    /// [`ControllerError::with_oauth_issuer`].
    pub issuer: Option<String>,
}

impl OAuthErrorData {
    /// An error answered as JSON; set `redirect_uri` to send it to the client instead.
    pub fn new(code: OAuthErrorCode, description: impl Into<String>) -> Self {
        Self {
            error: code.as_str().to_string(),
            error_description: description.into(),
            ..Default::default()
        }
    }
}

pub enum OAuthErrorCode {
    InvalidGrant,
    InvalidRequest,
    InvalidClient,
    InvalidToken,
    InsufficientScope,
    InvalidScope,
    UnauthorizedClient,
    UnsupportedGrantType,
    UnsupportedResponseType,
    /// RFC 8707: the requested resource is unknown or not allowed.
    InvalidTarget,
    ServerError,
    TemporarilyUnavailable,
    // OpenID Connect Core §3.1.2.6 authorization errors.
    LoginRequired,
    ConsentRequired,
    RequestNotSupported,
    InvalidDpopProof,
    UseDpopNonce,
    // RFC 8628 Device Authorization Grant token-endpoint errors. All map to
    // HTTP 400 (the default in `error_response`), which is RFC-compliant.
    AuthorizationPending,
    SlowDown,
    ExpiredToken,
    AccessDenied,
}

impl OAuthErrorCode {
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::InvalidGrant => "invalid_grant",
            Self::InvalidRequest => "invalid_request",
            Self::InvalidClient => "invalid_client",
            Self::InvalidToken => "invalid_token",
            Self::InsufficientScope => "insufficient_scope",
            Self::InvalidScope => "invalid_scope",
            Self::UnauthorizedClient => "unauthorized_client",
            Self::UnsupportedGrantType => "unsupported_grant_type",
            Self::UnsupportedResponseType => "unsupported_response_type",
            Self::InvalidTarget => "invalid_target",
            Self::ServerError => "server_error",
            Self::TemporarilyUnavailable => "temporarily_unavailable",
            Self::LoginRequired => "login_required",
            Self::ConsentRequired => "consent_required",
            Self::RequestNotSupported => "request_not_supported",
            Self::InvalidDpopProof => "invalid_dpop_proof",
            Self::UseDpopNonce => "use_dpop_nonce",
            Self::AuthorizationPending => "authorization_pending",
            Self::SlowDown => "slow_down",
            Self::ExpiredToken => "expired_token",
            Self::AccessDenied => "access_denied",
        }
    }
}

impl From<anyhow::Error> for ControllerError {
    fn from(err: anyhow::Error) -> ControllerError {
        if let Some(sqlx::Error::RowNotFound) = err.downcast_ref::<sqlx::Error>() {
            return Self::new(ControllerErrorType::NotFound, err.to_string(), Some(err));
        }

        Self::new(
            ControllerErrorType::InternalServerError,
            err.to_string(),
            Some(err),
        )
    }
}

impl From<uuid::Error> for ControllerError {
    fn from(err: uuid::Error) -> ControllerError {
        Self::new(
            ControllerErrorType::BadRequest,
            err.to_string(),
            Some(err.into()),
        )
    }
}

impl From<sqlx::Error> for ControllerError {
    fn from(err: sqlx::Error) -> ControllerError {
        Self::new(
            ControllerErrorType::InternalServerError,
            err.to_string(),
            Some(err.into()),
        )
    }
}

impl From<git2::Error> for ControllerError {
    fn from(err: git2::Error) -> ControllerError {
        Self::new(
            ControllerErrorType::InternalServerError,
            err.to_string(),
            Some(err.into()),
        )
    }
}

impl From<actix_web::Error> for ControllerError {
    fn from(err: actix_web::Error) -> Self {
        Self::new(
            ControllerErrorType::InternalServerError,
            err.to_string(),
            None,
        )
    }
}

impl From<actix_multipart::MultipartError> for ControllerError {
    fn from(err: actix_multipart::MultipartError) -> Self {
        Self::new(
            ControllerErrorType::InternalServerError,
            err.to_string(),
            None,
        )
    }
}

impl From<jsonwebtoken::errors::Error> for ControllerError {
    fn from(err: jsonwebtoken::errors::Error) -> Self {
        Self::new(
            ControllerErrorType::InternalServerError,
            err.to_string(),
            None,
        )
    }
}

impl From<ModelError> for ControllerError {
    fn from(err: ModelError) -> Self {
        let backtrace: Backtrace =
            match headless_lms_base::error::backend_error::BackendError::backtrace(&err) {
                Some(backtrace) => backtrace.clone(),
                _ => Backtrace::new(),
            };
        let span_trace = err.span_trace().clone();
        match err.error_type() {
            ModelErrorType::RecordNotFound => Self::new_with_traces(
                ControllerErrorType::NotFound,
                err.to_string(),
                Some(err.into()),
                backtrace,
                span_trace,
            ),
            ModelErrorType::NotFound => Self::new_with_traces(
                ControllerErrorType::NotFound,
                err.to_string(),
                Some(err.into()),
                backtrace,
                span_trace,
            ),
            ModelErrorType::PreconditionFailed => Self::new_with_traces(
                ControllerErrorType::BadRequest,
                err.message().to_string(),
                Some(err.into()),
                backtrace,
                span_trace,
            ),
            ModelErrorType::PreconditionFailedWithCMSAnchorBlockId { description, id } => {
                Self::new_with_traces(
                    ControllerErrorType::BadRequestWithData(ErrorMetadata::BlockId(*id)),
                    description.to_string(),
                    Some(err.into()),
                    backtrace,
                    span_trace,
                )
            }
            ModelErrorType::DatabaseConstraint {
                constraint,
                description,
            } => Self::new_with_traces(
                BadRequestReason::from_database_constraint(constraint)
                    .map_or(ControllerErrorType::BadRequest, |reason| {
                        ControllerErrorType::BadRequestWithReason(reason)
                    }),
                description.to_string(),
                Some(err.into()),
                backtrace,
                span_trace,
            ),
            ModelErrorType::StaleVersion => Self::new_with_traces(
                ControllerErrorType::BadRequestWithReason(BadRequestReason::StaleVersion),
                err.message().to_string(),
                Some(err.into()),
                backtrace,
                span_trace,
            ),
            ModelErrorType::InvalidRequest => Self::new_with_traces(
                ControllerErrorType::BadRequest,
                err.message().to_string(),
                Some(err.into()),
                backtrace,
                span_trace,
            ),
            ModelErrorType::ForeignKeyViolation { constraint, table } => Self::new_with_traces(
                ControllerErrorType::BadRequestWithData(
                    ErrorMetadata::ForeignKeyViolationMetadata {
                        constraint: constraint.to_owned(),
                        table: table.to_owned(),
                    },
                ),
                err.message().to_string(),
                Some(err.into()),
                backtrace,
                span_trace,
            ),
            _ => Self::new_with_traces(
                ControllerErrorType::InternalServerError,
                err.to_string(),
                Some(err.into()),
                backtrace,
                span_trace,
            ),
        }
    }
}

impl From<AuthorizationError> for ControllerError {
    fn from(err: AuthorizationError) -> Self {
        // A check that failed because the models layer did is mapped like any other
        // ModelError, so that e.g. authorizing against a nonexistent page still answers 404.
        let err = match err.into_model_error() {
            Ok(model_error) => return model_error.into(),
            Err(err) => err,
        };

        let backtrace: Backtrace = match BackendError::backtrace(&err) {
            Some(backtrace) => backtrace.clone(),
            _ => Backtrace::new(),
        };
        let span_trace = err.span_trace().clone();
        let error_type = match err.error_type() {
            AuthorizationErrorType::Unauthorized => ControllerErrorType::Unauthorized,
            AuthorizationErrorType::Forbidden => ControllerErrorType::Forbidden,
            AuthorizationErrorType::InternalServerError | AuthorizationErrorType::Model => {
                ControllerErrorType::InternalServerError
            }
        };
        // `message()`, not `to_string()`: the message reaches the user verbatim, while the
        // nested role and action detail stays reachable through the source chain.
        let message = err.message().to_string();

        Self::new_with_traces(error_type, message, Some(err.into()), backtrace, span_trace)
    }
}

impl From<UtilError> for ControllerError {
    fn from(err: UtilError) -> Self {
        let backtrace: Backtrace =
            match headless_lms_base::error::backend_error::BackendError::backtrace(&err) {
                Some(backtrace) => backtrace.clone(),
                _ => Backtrace::new(),
            };
        let span_trace = err.span_trace().clone();

        match err.error_type() {
            UtilErrorType::SisuClientError(SisuErrorVariant::GenericSisuError) => {
                Self::new_with_traces(
                    ControllerErrorType::SisuError(SisuErrorType::GenericSisuError),
                    err.to_string(),
                    Some(err.into()),
                    backtrace,
                    span_trace,
                )
            }
            UtilErrorType::SisuClientError(SisuErrorVariant::InvalidCourseCode) => {
                Self::new_with_traces(
                    ControllerErrorType::SisuError(SisuErrorType::InvalidCourseCode),
                    err.to_string(),
                    Some(err.into()),
                    backtrace,
                    span_trace,
                )
            }
            UtilErrorType::SisuClientError(SisuErrorVariant::SisuResourceNotFound) => {
                Self::new_with_traces(
                    ControllerErrorType::SisuError(SisuErrorType::SisuResourceNotFound),
                    err.to_string(),
                    Some(err.into()),
                    backtrace,
                    span_trace,
                )
            }
            _ => Self::new_with_traces(
                ControllerErrorType::InternalServerError,
                err.to_string(),
                Some(err.into()),
                backtrace,
                span_trace,
            ),
        }
    }
}

impl From<serde_json::Error> for ControllerError {
    fn from(err: serde_json::Error) -> Self {
        Self::new(
            ControllerErrorType::InternalServerError,
            err.to_string(),
            Some(err.into()),
        )
    }
}

impl From<base64::DecodeError> for ControllerError {
    fn from(err: base64::DecodeError) -> Self {
        Self::new(
            ControllerErrorType::InternalServerError,
            err.to_string(),
            Some(err.into()),
        )
    }
}

impl From<std::string::FromUtf8Error> for ControllerError {
    fn from(err: std::string::FromUtf8Error) -> Self {
        Self::new(
            ControllerErrorType::InternalServerError,
            err.to_string(),
            Some(err.into()),
        )
    }
}

impl From<pkcs8::spki::Error> for ControllerError {
    fn from(err: pkcs8::spki::Error) -> Self {
        Self::new(
            ControllerErrorType::InternalServerError,
            err.to_string(),
            Some(err.into()),
        )
    }
}

impl From<dpop_verifier::error::DpopError> for ControllerError {
    fn from(err: DpopError) -> Self {
        let oauth_error = match &err {
            DpopError::MultipleDpopHeaders
            | DpopError::InvalidDpopHeader
            | DpopError::MissingDpopHeader
            | DpopError::MalformedJws
            | DpopError::InvalidAlg(_)
            | DpopError::UnsupportedAlg(_)
            | DpopError::InvalidSignature
            | DpopError::BadJwk(_)
            | DpopError::MissingClaim(_)
            | DpopError::InvalidMethod
            | DpopError::HtmMismatch
            | DpopError::MalformedHtu
            | DpopError::HtuMismatch
            | DpopError::AthMalformed
            | DpopError::MissingAth
            | DpopError::AthMismatch
            | DpopError::FutureSkew
            | DpopError::Stale
            | DpopError::Replay
            | DpopError::JtiTooLong
            | DpopError::NonceMismatch
            | DpopError::NonceStale
            | DpopError::InvalidHmacConfig
            | DpopError::MissingNonce => {
                OAuthErrorData::new(OAuthErrorCode::InvalidDpopProof, err.to_string())
            }
            DpopError::Store(e) => OAuthErrorData::new(
                OAuthErrorCode::ServerError,
                format!("DPoP storage error: {e}"),
            ),
            // RFC 9449 §12.2
            DpopError::UseDpopNonce { nonce } => OAuthErrorData {
                nonce: Some(nonce.clone()),
                ..OAuthErrorData::new(OAuthErrorCode::UseDpopNonce, "Server requires DPoP nonce")
            },
        };

        ControllerError::new(
            ControllerErrorType::OAuthError(Box::new(oauth_error)),
            err.to_string(),
            Some(err.into()),
        )
    }
}

#[derive(Debug, thiserror::Error)]
pub enum PkceFlowError {
    /// Request is malformed or missing a required PKCE parameter
    #[error("{0}")]
    InvalidRequest(&'static str),

    /// PKCE check failed (e.g., code_verifier doesn't match stored challenge)
    #[error("{0}")]
    InvalidGrant(&'static str),

    /// Server-side (DB/state) problem
    #[error("{0}")]
    ServerError(&'static str),
}

impl From<PkceFlowError> for ControllerError {
    fn from(err: PkceFlowError) -> Self {
        let data = match &err {
            PkceFlowError::InvalidRequest(msg) => {
                OAuthErrorData::new(OAuthErrorCode::InvalidRequest, *msg)
            }
            PkceFlowError::InvalidGrant(msg) => {
                OAuthErrorData::new(OAuthErrorCode::InvalidGrant, *msg)
            }
            PkceFlowError::ServerError(msg) => {
                OAuthErrorData::new(OAuthErrorCode::ServerError, *msg)
            }
        };

        ControllerError::new(
            ControllerErrorType::OAuthError(Box::new(data)),
            err.to_string(),
            Some(anyhow::anyhow!(err)),
        )
    }
}

impl From<crate::domain::oauth::pkce::PkceError> for PkceFlowError {
    fn from(_err: crate::domain::oauth::pkce::PkceError) -> Self {
        // Both BadLength and BadCharset are "invalid_request" per OAuth spec
        PkceFlowError::InvalidRequest("invalid code_verifier")
    }
}

impl From<crate::domain::oauth::pkce::PkceError> for ControllerError {
    fn from(err: crate::domain::oauth::pkce::PkceError) -> Self {
        PkceFlowError::from(err).into()
    }
}

impl From<ChatbotError> for ControllerError {
    fn from(err: ChatbotError) -> Self {
        // A failure that came from the models layer is mapped like any other ModelError, so
        // that e.g. a chatbot conversation referencing a deleted course answers 404.
        let err = match err.into_model_error() {
            Ok(model_error) => return model_error.into(),
            Err(err) => err,
        };

        let backtrace: Backtrace = match BackendError::backtrace(&err) {
            Some(backtrace) => backtrace.clone(),
            _ => Backtrace::new(),
        };
        let span_trace = err.span_trace().clone();
        let error_type = match err.error_type() {
            // The one chatbot error the caller can fix, so the only one it is told about.
            ChatbotErrorType::InvalidToolAnswer => ControllerErrorType::BadRequest,
            ChatbotErrorType::InvalidMessageShape
            | ChatbotErrorType::InvalidToolName
            | ChatbotErrorType::InvalidToolArguments
            | ChatbotErrorType::ToolUseError
            | ChatbotErrorType::ChatbotModelError
            | ChatbotErrorType::ChatbotMessageSuggestError
            | ChatbotErrorType::UrlParse
            | ChatbotErrorType::TokioIo
            | ChatbotErrorType::SerdeJson
            | ChatbotErrorType::SqlxError
            | ChatbotErrorType::ReqwestError
            | ChatbotErrorType::Other
            | ChatbotErrorType::DeserializationError
            | ChatbotErrorType::AzureAISearchFilterError
            | ChatbotErrorType::UpstreamReportedError
            | ChatbotErrorType::ResponseIncomplete
            | ChatbotErrorType::StreamEndedEarly
            | ChatbotErrorType::UnexpectedProtocolShape
            | ChatbotErrorType::StreamInvariantViolation
            | ChatbotErrorType::ContentCleaning
            | ChatbotErrorType::AzureRequestBuildError
            | ChatbotErrorType::FailedAzureResponse
            | ChatbotErrorType::SisuDescriptionError
            | ChatbotErrorType::ChatbotUtilError => ControllerErrorType::InternalServerError,
        };
        let message = err.message().to_string();

        Self::new_with_traces(error_type, message, Some(err.into()), backtrace, span_trace)
    }
}

impl From<CreditRegistrationError> for ControllerError {
    fn from(err: CreditRegistrationError) -> Self {
        // A failure that came from the models layer is mapped like any other ModelError, so that
        // e.g. a resend for a deleted course answers 404.
        let err = match err.into_model_error() {
            Ok(model_error) => return model_error.into(),
            Err(err) => err,
        };

        let backtrace: Backtrace = match BackendError::backtrace(&err) {
            Some(backtrace) => backtrace.clone(),
            _ => Backtrace::new(),
        };
        let span_trace = err.span_trace().clone();
        let error_type = match err.error_type() {
            CreditRegistrationErrorType::Model | CreditRegistrationErrorType::Database => {
                ControllerErrorType::InternalServerError
            }
        };
        let message = err.message().to_string();

        Self::new_with_traces(error_type, message, Some(err.into()), backtrace, span_trace)
    }
}

// Generate error creation macros for ControllerError
headless_lms_utils::define_err_macro!(
    controller_err,
    ControllerError,
    ControllerErrorType,
    ControllerErrorType,
    "Create a ControllerError with less boilerplate."
);

/// Helper function for `.map_err()` chains to wrap any error as ControllerError.
///
/// This function creates a closure that converts any error into a `ControllerError`
/// with the specified error type and message, including the original error as the source.
///
/// # Examples
///
/// ```ignore
/// // Instead of:
/// .map_err(|e| ControllerError::new(ControllerErrorType::BadRequest, e.to_string(), Some(e.into())))?
///
/// // You can write:
/// .map_err(as_controller_error(ControllerErrorType::BadRequest, "Failed to process".to_string()))?
/// ```
pub fn as_controller_error<E>(
    error_type: ControllerErrorType,
    message: impl Into<String>,
) -> impl FnOnce(E) -> ControllerError
where
    E: Into<anyhow::Error>,
{
    let msg = message.into();
    move |e| ControllerError::new(error_type, msg, Some(e.into()))
}

/// Helper function for `.ok_or_else()` to create ControllerError on None.
///
/// This function creates a closure that generates a `ControllerError` with the
/// specified error type and message when called.
///
/// # Examples
///
/// ```ignore
/// // Instead of:
/// .ok_or_else(|| ControllerError::new(ControllerErrorType::NotFound, "Item not found".to_string(), None))
///
/// // You can write:
/// .ok_or_else(missing_controller_error(ControllerErrorType::NotFound, "Item not found".to_string()))
/// ```
pub fn missing_controller_error(
    error_type: ControllerErrorType,
    message: impl Into<String>,
) -> impl FnOnce() -> ControllerError {
    let msg = message.into();
    move || ControllerError::new(error_type, msg, None)
}

#[cfg(test)]
mod tests {
    use super::*;
    use actix_web::ResponseError;
    use futures_util::FutureExt;

    #[test]
    fn test_controller_err_macro_without_source() {
        let err = controller_err!(BadRequest, "Test error message".to_string());
        assert_eq!(err.message(), "Test error message");
        assert!(matches!(err.error_type(), ControllerErrorType::BadRequest));
    }

    #[test]
    fn test_controller_err_macro_with_source() {
        let source_err = std::io::Error::new(std::io::ErrorKind::NotFound, "file not found");
        let err = controller_err!(InternalServerError, "Wrapped error".to_string(), source_err);
        assert_eq!(err.message(), "Wrapped error");
    }

    #[test]
    fn test_controller_err_macro_tuple_variant_with_source() {
        let source_err = std::io::Error::other("source");
        let err = controller_err!(
            UnauthorizedWithReason(UnauthorizedReason::ChapterNotOpenYet),
            "Wrapped error".to_string(),
            source_err
        );
        assert!(matches!(
            err.error_type(),
            ControllerErrorType::UnauthorizedWithReason(_)
        ));
    }

    #[test]
    fn test_as_controller_error_helper() {
        let result: Result<(), std::io::Error> = Err(std::io::Error::new(
            std::io::ErrorKind::NotFound,
            "test error",
        ));
        let controller_result = result.map_err(as_controller_error(
            ControllerErrorType::BadRequest,
            "Invalid input".to_string(),
        ));

        assert!(controller_result.is_err());
        let err = controller_result.unwrap_err();
        assert_eq!(err.message(), "Invalid input");
        assert!(matches!(err.error_type(), ControllerErrorType::BadRequest));
    }

    #[test]
    fn test_missing_controller_error_helper() {
        let option: Option<String> = None;
        let result = option.ok_or_else(missing_controller_error(
            ControllerErrorType::NotFound,
            "Resource not found".to_string(),
        ));

        assert!(result.is_err());
        let err = result.unwrap_err();
        assert_eq!(err.message(), "Resource not found");
        assert!(matches!(err.error_type(), ControllerErrorType::NotFound));
    }

    #[test]
    fn test_controller_err_with_format() {
        let user_id = 42;
        let err = controller_err!(Unauthorized, format!("User {} is not authorized", user_id));
        assert_eq!(err.message(), "User 42 is not authorized");
    }

    #[test]
    fn test_controller_err_all_variants() {
        // Test that macros work with all standard error type variants
        let _ = controller_err!(InternalServerError, "test".to_string());
        let _ = controller_err!(BadRequest, "test".to_string());
        let _ = controller_err!(NotFound, "test".to_string());
        let _ = controller_err!(Unauthorized, "test".to_string());
        let _ = controller_err!(
            UnauthorizedWithReason(UnauthorizedReason::ChapterNotOpenYet),
            "test".to_string()
        );
        let _ = controller_err!(
            BadRequestWithData(ErrorMetadata::BlockId(Uuid::nil())),
            "test".to_string()
        );
        let _ = controller_err!(Forbidden, "test".to_string());
    }

    #[test]
    fn test_canonical_error_envelope_shape() {
        let err = controller_err!(BadRequest, "Validation failed".to_string());
        let response = err.error_response();
        assert_eq!(response.status(), StatusCode::UNPROCESSABLE_ENTITY);

        let bytes = actix_web::body::to_bytes(response.into_body())
            .now_or_never()
            .expect("response should resolve immediately")
            .expect("body bytes");
        let value: serde_json::Value = serde_json::from_slice(&bytes).expect("json");
        assert_eq!(value["type"], "validation_error");
        assert_eq!(value["message_key"], "validation_error");
        assert_eq!(value["message"], "Validation failed");
        assert!(value.get("status").is_none());
        assert!(value.get("request_id").is_none());
    }

    #[test]
    fn test_error_envelope_schema_requires_type_message_key_and_message() {
        let schema = serde_json::to_value(<ApiErrorResponse as utoipa::PartialSchema>::schema())
            .expect("schema json");
        let mut required: Vec<&str> = schema["required"]
            .as_array()
            .expect("required list")
            .iter()
            .map(|v| v.as_str().expect("field name"))
            .collect();
        required.sort_unstable();
        assert_eq!(required, ["message", "message_key", "type"]);
    }

    #[test]
    fn test_validation_issue_code_is_serialized_for_missing_exercise_type() {
        let err = ControllerError::new(
            ControllerErrorType::BadRequestWithData(ErrorMetadata::BlockId(Uuid::nil())),
            MISSING_EXERCISE_TYPE_DESCRIPTION.to_string(),
            None,
        );
        let response = err.error_response();
        let bytes = actix_web::body::to_bytes(response.into_body())
            .now_or_never()
            .expect("response should resolve immediately")
            .expect("body bytes");
        let value: serde_json::Value = serde_json::from_slice(&bytes).expect("json");

        assert_eq!(value["type"], "validation_error");
        assert_eq!(value["message_key"], "validation_error_with_metadata");
        assert_eq!(value["errors"][0]["code"], "missing_exercise_type");
        assert_eq!(value["errors"][0]["path"], "exercise_type");
    }

    #[test]
    fn test_chapter_not_open_uses_dedicated_message_key() {
        let err = ControllerError::new(
            ControllerErrorType::UnauthorizedWithReason(UnauthorizedReason::ChapterNotOpenYet),
            "Chapter is not open yet.".to_string(),
            None,
        );
        let response = err.error_response();
        let bytes = actix_web::body::to_bytes(response.into_body())
            .now_or_never()
            .expect("response should resolve immediately")
            .expect("body bytes");
        let value: serde_json::Value = serde_json::from_slice(&bytes).expect("json");

        assert_eq!(value["type"], "unauthorized");
        assert_eq!(value["message_key"], "chapter_not_open_yet");
        assert_eq!(value["message"], "Chapter is not open yet.");
    }

    #[test]
    fn test_exam_exercise_auth_requirement_uses_dedicated_message_key() {
        let err = ControllerError::new(
            ControllerErrorType::UnauthorizedWithReason(
                UnauthorizedReason::AuthenticationRequiredForExamExercise,
            ),
            "User must be authenticated to view exam exercises".to_string(),
            None,
        );
        let response = err.error_response();
        let bytes = actix_web::body::to_bytes(response.into_body())
            .now_or_never()
            .expect("response should resolve immediately")
            .expect("body bytes");
        let value: serde_json::Value = serde_json::from_slice(&bytes).expect("json");

        assert_eq!(value["type"], "unauthorized");
        assert_eq!(
            value["message_key"],
            "authentication_required_for_exam_exercise"
        );
        assert_eq!(
            value["message"],
            "User must be authenticated to view exam exercises"
        );
    }

    #[test]
    fn test_not_enrolled_uses_dedicated_message_key_and_422() {
        let err = ControllerError::new(
            ControllerErrorType::BadRequestWithReason(BadRequestReason::NotEnrolled),
            "User is not enrolled to this exercise's course".to_string(),
            None,
        );
        let response = err.error_response();
        assert_eq!(response.status(), StatusCode::UNPROCESSABLE_ENTITY);
        let bytes = actix_web::body::to_bytes(response.into_body())
            .now_or_never()
            .expect("response should resolve immediately")
            .expect("body bytes");
        let value: serde_json::Value = serde_json::from_slice(&bytes).expect("json");

        assert_eq!(value["type"], "validation_error");
        assert_eq!(value["message_key"], "not_enrolled");
    }

    #[test]
    fn test_upgrade_required_uses_obsolete_client_key_and_426() {
        let err = ControllerError::new(
            ControllerErrorType::UpgradeRequired,
            "Client is too old".to_string(),
            None,
        );
        let response = err.error_response();
        assert_eq!(response.status(), StatusCode::UPGRADE_REQUIRED);
        let bytes = actix_web::body::to_bytes(response.into_body())
            .now_or_never()
            .expect("response should resolve immediately")
            .expect("body bytes");
        let value: serde_json::Value = serde_json::from_slice(&bytes).expect("json");

        assert_eq!(value["type"], "obsolete_client");
        assert_eq!(value["message_key"], "obsolete_client");
    }

    #[test]
    fn test_generic_unauthorized_uses_unauthorized_message_key() {
        let err = ControllerError::new(
            ControllerErrorType::Unauthorized,
            "Unauthorized".to_string(),
            None,
        );
        let response = err.error_response();
        let bytes = actix_web::body::to_bytes(response.into_body())
            .now_or_never()
            .expect("response should resolve immediately")
            .expect("body bytes");
        let value: serde_json::Value = serde_json::from_slice(&bytes).expect("json");

        assert_eq!(value["type"], "unauthorized");
        assert_eq!(value["message_key"], "unauthorized");
        assert_eq!(value["message"], "Unauthorized");
    }

    #[test]
    fn debug_renders_clean_format() {
        let err = controller_err!(InternalServerError, "database exploded".to_string());
        let debug = format!("{err:?}");
        assert!(
            debug.contains("ControllerError · InternalServerError: database exploded"),
            "got: {debug}"
        );
        // No error-infrastructure leakage in the raise line.
        assert!(!debug.contains("backend_error.rs"), "got: {debug}");
        assert!(!debug.contains("macros.rs"), "got: {debug}");
    }

    #[test]
    fn debug_renders_wrapped_model_error_as_cause_node() {
        let model_error = ModelError::new(ModelErrorType::Generic, "row missing".to_string(), None);
        let err = ControllerError::from(model_error);

        let debug = format!("{err:?}");
        assert!(debug.contains("ControllerError ·"), "got: {debug}");
        assert!(debug.contains("caused by:"), "got: {debug}");
        assert!(
            debug.contains("1. ModelError · Generic: row missing"),
            "got: {debug}"
        );
        assert!(!debug.contains("(external)"), "got: {debug}");
    }
}