Error System Documentation¶

pub trait AppError: std::error::Error + Send + Sync + 'static {
    fn status_code(&self) -> StatusCode;           // HTTP status code
    fn user_message(&self) -> String;              // User-friendly message
    fn error_code(&self) -> &'static str;          // Frontend error code
    fn error_category(&self) -> ErrorCategory;     // Error categorization
    fn error_severity(&self) -> ErrorSeverity;     // Severity level
    fn suppression_key(&self) -> Option<String>;   // For repeated error handling
    fn suggested_action(&self) -> Option<String>;  // Recovery suggestions
}

// Examples
UserError::NotFound
UserError::DuplicateUsername { username: "john_doe" }
UserError::PermissionDenied { reason: "Admin access required" }
UserError::InvalidCredentials
UserError::DeleteRestricted { id, reason: "Cannot delete your own account" }

// Examples  
SourceError::ConnectionFailed { details: "Network timeout" }
SourceError::InvalidPath { path: "/invalid/path" }
SourceError::AuthenticationFailed { name: "my-webdav", reason: "Invalid credentials" }
SourceError::SyncInProgress { name: "backup-source" }
SourceError::ConfigurationInvalid { details: "Missing server URL" }

// Examples
LabelError::DuplicateName { name: "Important" }
LabelError::SystemLabelModification { name: "system-label" }
LabelError::InvalidColor { color: "#gggggg" }
LabelError::LabelInUse { document_count: 42 }
LabelError::MaxLabelsReached { max_labels: 100 }

// Examples
SettingsError::InvalidLanguage { language: "xx", available_languages: "en,es,fr" }
SettingsError::ValueOutOfRange { setting_name: "timeout", value: 3600, min: 1, max: 300 }
SettingsError::InvalidOcrConfiguration { details: "DPI too high" }
SettingsError::ConflictingSettings { setting1: "auto_detect", setting2: "fixed_language" }

// Examples
SearchError::QueryTooShort { length: 1, min_length: 2 }
SearchError::TooManyResults { result_count: 15000, max_results: 10000 }
SearchError::IndexUnavailable { reason: "Rebuilding index" }
SearchError::InvalidPagination { offset: -1, limit: 0 }

use crate::errors::user::UserError;

async fn create_user(
    auth_user: AuthUser,
    State(state): State<Arc<AppState>>,
    Json(user_data): Json<CreateUser>,
) -> Result<Json<UserResponse>, UserError> {
    require_admin(&auth_user)?;

    let user = state
        .db
        .create_user(user_data)
        .await
        .map_err(|e| {
            let error_msg = e.to_string();
            if error_msg.contains("username") && error_msg.contains("unique") {
                UserError::duplicate_username(&user_data.username)
            } else if error_msg.contains("email") && error_msg.contains("unique") {
                UserError::duplicate_email(&user_data.email)
            } else {
                UserError::internal_server_error(format!("Database error: {}", e))
            }
        })?;

    Ok(Json(user.into()))
}

// Instead of verbose enum construction
UserError::DuplicateUsername { username: username.clone() }

// Use convenience methods
UserError::duplicate_username(&username)
UserError::permission_denied("Admin access required")
UserError::not_found_by_id(user_id)

LabelError::invalid_color("#gggggg") 
// Returns: "Invalid color format - use hex format like #0969da"
// Suggestion: "Use a valid hex color format like #0969da or #ff5722"

SourceError::rate_limit_exceeded("my-source", 300)
// Returns: "Rate limit exceeded, try again in 300 seconds" 
// Suggestion: "Wait 300 seconds before retrying"

// Good
return Err(UserError::duplicate_username(&username));

// Avoid
return Err(UserError::BadRequest { message: "Username exists".to_string() });

// Good
SourceError::connection_failed(format!("Failed to connect to {}: {}", url, e))

// Less helpful
SourceError::connection_failed("Connection failed")

.map_err(|e| {
    let error_msg = e.to_string();
    if error_msg.contains("unique constraint") {
        UserError::duplicate_username(&username)
    } else if error_msg.contains("not found") {
        UserError::not_found()
    } else {
        UserError::internal_server_error(format!("Database error: {}", e))
    }
})?

impl AppError for SearchError {
    fn suppression_key(&self) -> Option<String> {
        match self {
            // Suppress repeated "no results" errors
            SearchError::NoResults => Some("search_no_results".to_string()),
            // Don't suppress validation errors - users need to see them
            SearchError::QueryTooShort { .. } => None,
            // Suppress by specific source for connection errors
            SearchError::IndexUnavailable { .. } => Some("search_index_unavailable".to_string()),
            _ => None,
        }
    }
}

// Before
.map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?

// After
.map_err(|e| UserError::internal_server_error(format!("Operation failed: {}", e)))?

// Before
assert_eq!(response.status(), StatusCode::CONFLICT);

// After - check JSON response
let error: serde_json::Value = response.json().await;
assert_eq!(error["code"], "USER_DELETE_RESTRICTED");

use crate::errors::user::UserError;

async fn register_user(
    State(state): State<Arc<AppState>>,
    Json(user_data): Json<CreateUser>,
) -> Result<Json<UserResponse>, UserError> {
    // Validate input
    if user_data.username.len() < 3 {
        return Err(UserError::invalid_username(
            &user_data.username, 
            "Username must be at least 3 characters"
        ));
    }

    // Create user
    let user = state.db.create_user(user_data).await
        .map_err(|e| {
            let error_msg = e.to_string();
            if error_msg.contains("username") && error_msg.contains("unique") {
                UserError::duplicate_username(&user_data.username)
            } else if error_msg.contains("email") && error_msg.contains("unique") {
                UserError::duplicate_email(&user_data.email)
            } else {
                UserError::internal_server_error(format!("Database error: {}", e))
            }
        })?;

    Ok(Json(user.into()))
}

use crate::errors::source::SourceError;

async fn test_webdav_connection(
    State(state): State<Arc<AppState>>,
    Path(source_id): Path<Uuid>,
    auth_user: AuthUser,
) -> Result<Json<ConnectionTestResponse>, SourceError> {
    let source = state.db.get_source(source_id).await
        .map_err(|_| SourceError::not_found_by_id(source_id))?;

    // Check ownership
    if source.user_id != auth_user.user.id {
        return Err(SourceError::permission_denied(
            "You can only test your own sources"
        ));
    }

    // Test connection
    match test_webdav_connection_internal(&source).await {
        Ok(()) => Ok(Json(ConnectionTestResponse { success: true })),
        Err(e) if e.to_string().contains("authentication") => {
            Err(SourceError::authentication_failed(&source.name, &e.to_string()))
        },
        Err(e) if e.to_string().contains("timeout") => {
            Err(SourceError::network_timeout(&source.url, 30))
        },
        Err(e) => {
            Err(SourceError::connection_failed(format!("Connection test failed: {}", e)))
        }
    }
}

use crate::errors::search::SearchError;

async fn search_documents(
    State(state): State<Arc<AppState>>,
    Query(params): Query<SearchParams>,
    auth_user: AuthUser,
) -> Result<Json<SearchResponse>, SearchError> {
    // Validate query length
    if params.query.len() < 2 {
        return Err(SearchError::query_too_short(params.query.len(), 2));
    }

    if params.query.len() > 500 {
        return Err(SearchError::query_too_long(params.query.len(), 500));
    }

    // Check pagination
    if params.limit > 1000 {
        return Err(SearchError::invalid_pagination(params.offset, params.limit));
    }

    // Perform search
    let results = state.search_service.search(&params, auth_user.user.id).await
        .map_err(|e| match e {
            SearchServiceError::IndexUnavailable => {
                SearchError::index_unavailable("Search index is being rebuilt")
            },
            SearchServiceError::TooManyResults(count) => {
                SearchError::too_many_results(count, 10000)
            },
            SearchServiceError::InvalidSyntax(details) => {
                SearchError::invalid_syntax(details)
            },
            _ => SearchError::internal_error(format!("Search failed: {}", e)),
        })?;

    Ok(Json(results))
}