Crate masterror

Crate masterror 

Source
Expand description

Framework-agnostic application error types for backend services.

§Overview

A small, pragmatic error model designed for API-heavy services.
The core is framework-agnostic; integrations are optional and enabled via feature flags.

Core types:

  • AppError — thin wrapper around a semantic error kind and optional message
  • AppErrorKind — stable internal taxonomy of application errors
  • AppResult — convenience alias Result<T, AppError>
  • ErrorResponse — stable wire-level JSON payload for HTTP APIs
  • AppCode — public, machine-readable error code for clients

Key properties:

  • Stable, predictable error categories (AppErrorKind).
  • Conservative and stable HTTP mappings.
  • Internal error sources are never serialized to clients (only logged).
  • Messages are safe to expose (human-oriented, non-sensitive).

§Minimum Supported Rust Version (MSRV)

MSRV is 1.89. New minor releases may increase MSRV with a changelog note, but never in a patch release.

§Feature flags

Enable only what you need:

  • axum — implements IntoResponse for AppError and ErrorResponse with JSON body
  • actix — implements Responder for ErrorResponse (and Actix integration for AppError)
  • openapi — derives an OpenAPI schema for ErrorResponse (via utoipa)
  • sqlx — From<sqlx::Error> mapping
  • redis — From<redis::RedisError> mapping
  • validator — From<validator::ValidationErrors> mapping
  • config — From<config::ConfigError> mapping
  • tokio — From<tokio::time::error::Elapsed> mapping
  • reqwest — From<reqwest::Error> mapping
  • serde_json — support for structured JSON details in ErrorResponse; also pulled transitively by axum
  • multipart — compatibility flag for Axum multipart

§Error taxonomy

Applications convert domain/infrastructure failures into AppError with a semantic AppErrorKind and optional public message:

use masterror::{AppError, AppErrorKind};

let err = AppError::new(AppErrorKind::BadRequest, "Flag must be set");
assert!(matches!(err.kind, AppErrorKind::BadRequest));

AppErrorKind controls the default HTTP status mapping.
AppCode provides a stable machine-readable code for clients.
Together, they form the wire contract in ErrorResponse.

§Wire payload: ErrorResponse

The stable JSON payload for HTTP APIs contains:

  • status: u16 — HTTP status code
  • code: AppCode — stable machine-readable error code
  • message: String — human-friendly, safe-to-expose text
  • details — optional details (JSON if serde_json, otherwise string)
  • retry — optional retry advice (Retry-After)
  • www_authenticate — optional authentication challenge

Example construction:

use masterror::{AppCode, ErrorResponse};

let resp = ErrorResponse::new(404, AppCode::NotFound, "User not found");

Conversion from AppError:

use masterror::{AppCode, AppError, AppErrorKind, ErrorResponse};

let app_err = AppError::new(AppErrorKind::NotFound, "user_not_found");
let resp: ErrorResponse = (&app_err).into();
assert_eq!(resp.status, 404);
assert!(matches!(resp.code, AppCode::NotFound));

§Axum integration

With the axum feature enabled, you can return AppError directly from handlers. It is automatically converted into an ErrorResponse JSON payload.

ⓘ
use axum::{routing::get, Router};
use masterror::{AppError, AppResult};

async fn handler() -> AppResult<&'static str> {
    Err(AppError::forbidden("No access"))
}

let app = Router::new().route("/demo", get(handler));

§OpenAPI integration

With the openapi feature enabled, ErrorResponse derives utoipa::ToSchema and can be referenced in OpenAPI operation responses.

§Versioning policy

This crate follows semantic versioning. Any change to the public API or wire contract is considered a breaking change and requires a major version bump.

§Safety

This crate does not use unsafe.

§License

Licensed under either of

  • Apache License, Version 2.0
  • MIT license

at your option.

Modules§

prelude
Minimal prelude re-exporting core types for handler signatures. Minimal, opt-in prelude for application crates.

Structs§

AppError
Thin error wrapper: kind + optional message.
ErrorResponse
Public, wire-level error payload for HTTP APIs.
RetryAdvice
Retry advice intended for API clients.

Enums§

AppCode
Stable machine-readable error code exposed to clients.
AppErrorKind
Canonical application error taxonomy.

Type Aliases§

AppResult
Conventional result alias for application code.