Что такое masterror?

masterror — это рабочее пространство для обработки ошибок в сервисах на Rust, которым нужно больше, чем Display и source(). Там, где thiserror ограничивается генерацией реализаций трейтов, а anyhow — распространением ошибок со стёртым типом, masterror доводит ошибку до самой транспортной границы:

• AppError — насыщенное значение ошибки с семантической категорией (AppErrorKind), стабильным машиночитаемым кодом (AppCode), опциональным безопасным публичным сообщением, структурированными метаданными и транспортными подсказками (Retry-After, WWW-Authenticate).
• Консервативные отображения HTTP и gRPC — каждый вид и код детерминированно отображается в HTTP-статус, дискриминант tonic::Code и URI type по RFC 7807.
• Типизированная телеметрия — метаданные хранятся как типизированные поля (строки, целые числа, числа с плавающей точкой, длительности, IP-адреса, UUID, JSON) с политиками редактирования для каждого поля, а не как самодельные String-карты.
• Нативные derive-макросы — #[derive(Error)] повторяет синтаксис thiserror, а #[app_error(...)] и #[derive(Masterror)] встраивают доменные ошибки в AppError с кодами, категориями, редактированием и таблицами отображений.
• Редактирование по замыслу — источники никогда не сериализуются для клиентов; сообщения, детали и поля метаданных могут быть удалены, захешированы или замаскированы на границе.

Без unsafe, с зафиксированным MSRV и поддержкой no_std при отключённой функции std, включённой по умолчанию.

Какую проблему он решает

Enum, произведённый thiserror, говорит, что случилось. masterror дополнительно решает, что увидит клиент (статус, код, безопасное сообщение, problem+json), что увидят операторы (структурированные поля, события tracing, счётчики) и что никогда не утечёт (источники, отредактированные поля).

Основные возможности

Быстрый пример

use masterror::{AppError, AppErrorKind, AppResult, ProblemJson, field};

fn find_user(id: u64) -> AppResult<()> {
    masterror::ensure!(id != 0, AppError::bad_request("id must be non-zero"));

    Err(AppError::not_found("user not found")
        .with_field(field::u64("user_id", id))
        .with_field(field::str("request_id", "abc123")))
}

let err = find_user(42).unwrap_err();
assert_eq!(err.kind, AppErrorKind::NotFound);
assert_eq!(err.kind.http_status(), 404);

let problem = ProblemJson::from_app_error(err);
assert_eq!(problem.status, 404);
assert_eq!(problem.code.as_str(), "NOT_FOUND");
assert_eq!(problem.grpc.expect("grpc").name, "NOT_FOUND");

Или объявите доменную ошибку один раз и позвольте derive-макросу выполнить отображение:

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

#[derive(Debug, Error)]
#[error("missing flag: {name}")]
#[app_error(kind = AppErrorKind::BadRequest, code = AppCode::BadRequest, message)]
struct MissingFlag {
    name: &'static str
}

let app: AppError = MissingFlag { name: "feature" }.into();
assert!(matches!(app.kind, AppErrorKind::BadRequest));

Крейты рабочего пространства

Документация

Начало работы

• Начало работы — установка, первые ошибки, макросы, первый derive
• Флаги возможностей — полный справочник флагов с зависимостями

Основные концепции

• Виды и коды ошибок — таксономия, таблицы HTTP/gRPC, problem+json
• Derive-макросы — #[derive(Error)], #[derive(Masterror)] и их атрибуты
• Контекст и метаданные — Context, ResultExt, поля, редактирование, цепочки

Интеграции

• Веб-фреймворки — Axum, Actix, tonic
• Интеграции — sqlx, redis, reqwest, validator и другие
• Наблюдаемость — tracing, metrics, бэктрейсы, режимы отображения

Продвинутое

• Без std — работа без стандартной библиотеки
• Лучшие практики — паттерны для сервисов и библиотек
• Миграция — переход с thiserror / anyhow