Finalize context error migration

CHANGELOG.md

@@ -3,6 +3,19 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.18.0] - 2025-09-28
+
+### Added
+- Added the `AppCode::UserAlreadyExists` classification and mapped it to RFC7807
+  responses with the appropriate retry hint.
+
+### Changed
+- Switched all integration converters in `src/convert/*` to build structured
+  `Context` metadata before producing `Error` values, including HTTP status,
+  operation, endpoint, duration and retry/edit flags.
+- Extended integration tests to validate the enriched metadata, retry behavior
+  and error code/category mappings across the updated converters.
+
 ## [0.17.0] - 2025-09-27
 
 ### Added

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "masterror"
-version = "0.17.0"
+version = "0.18.0"
 rust-version = "1.90"
 edition = "2024"
 license = "MIT OR Apache-2.0"

README.md

@@ -38,9 +38,9 @@ guides, comparisons with `thiserror`/`anyhow`, and troubleshooting recipes.
 
 ~~~toml
 [dependencies]
-masterror = { version = "0.17.0", default-features = false }
+masterror = { version = "0.18.0", default-features = false }
 # or with features:
-# masterror = { version = "0.17.0", features = [
+# masterror = { version = "0.18.0", features = [
 #   "axum", "actix", "openapi", "serde_json",
 #   "tracing", "metrics", "backtrace", "sqlx",
 #   "sqlx-migrate", "reqwest", "redis", "validator",
@@ -78,10 +78,10 @@ masterror = { version = "0.17.0", default-features = false }
 ~~~toml
 [dependencies]
 # lean core
-masterror = { version = "0.17.0", default-features = false }
+masterror = { version = "0.18.0", default-features = false }
 
 # with Axum/Actix + JSON + integrations
-# masterror = { version = "0.17.0", features = [
+# masterror = { version = "0.18.0", features = [
 #   "axum", "actix", "openapi", "serde_json",
 #   "tracing", "metrics", "backtrace", "sqlx",
 #   "sqlx-migrate", "reqwest", "redis", "validator",
@@ -720,13 +720,13 @@ assert_eq!(problem.grpc.expect("grpc").name, "UNAUTHENTICATED");
 Minimal core:
 
 ~~~toml
-masterror = { version = "0.17.0", default-features = false }
+masterror = { version = "0.18.0", default-features = false }
 ~~~
 
 API (Axum + JSON + deps):
 
 ~~~toml
-masterror = { version = "0.17.0", features = [
+masterror = { version = "0.18.0", features = [
   "axum", "serde_json", "openapi",
   "sqlx", "reqwest", "redis", "validator", "config", "tokio"
 ] }
@@ -735,7 +735,7 @@ masterror = { version = "0.17.0", features = [
 API (Actix + JSON + deps):
 
 ~~~toml
-masterror = { version = "0.17.0", features = [
+masterror = { version = "0.18.0", features = [
   "actix", "serde_json", "openapi",
   "sqlx", "reqwest", "redis", "validator", "config", "tokio"
 ] }

src/code/app_code.rs

@@ -36,6 +36,11 @@ pub enum AppCode {
     /// Typically mapped to HTTP **409 Conflict**.
     Conflict,
 
+    /// Attempted to create a user that already exists (unique constraint).
+    ///
+    /// Typically mapped to HTTP **409 Conflict**.
+    UserAlreadyExists,
+
     /// Authentication required or failed (missing/invalid credentials).
     ///
     /// Typically mapped to HTTP **401 Unauthorized**.
@@ -149,6 +154,7 @@ impl AppCode {
             AppCode::NotFound => "NOT_FOUND",
             AppCode::Validation => "VALIDATION",
             AppCode::Conflict => "CONFLICT",
+            AppCode::UserAlreadyExists => "USER_ALREADY_EXISTS",
             AppCode::Unauthorized => "UNAUTHORIZED",
             AppCode::Forbidden => "FORBIDDEN",
             AppCode::NotImplemented => "NOT_IMPLEMENTED",

src/convert/config.rs

@@ -1,4 +1,4 @@
-//! Convert [`config::ConfigError`] into [`AppError`],
+//! Convert [`config::ConfigError`] into [`Error`],
 //! producing [`AppErrorKind::Config`].
 //!
 //! Enabled with the `config` feature.
@@ -7,36 +7,109 @@
 //!
 //! ```rust,ignore
 //! use config::ConfigError;
-//! use masterror::{AppError, AppErrorKind};
+//! use masterror::{AppErrorKind, Error};
 //!
 //! let err = ConfigError::Message("missing key".into());
-//! let app_err: AppError = err.into();
+//! let app_err: Error = err.into();
 //! assert!(matches!(app_err.kind, AppErrorKind::Config));
 //! ```
 #[cfg(feature = "config")]
 use config::ConfigError;
 
 #[cfg(feature = "config")]
-use crate::AppError;
+use crate::{
+    AppErrorKind,
+    app_error::{Context, Error, field}
+};
 
 #[cfg(feature = "config")]
 #[cfg_attr(docsrs, doc(cfg(feature = "config")))]
-impl From<ConfigError> for AppError {
+impl From<ConfigError> for Error {
     fn from(err: ConfigError) -> Self {
-        AppError::config(err.to_string())
+        build_context(&err).into_error(err)
+    }
+}
+
+#[cfg(feature = "config")]
+fn build_context(error: &ConfigError) -> Context {
+    match error {
+        ConfigError::Frozen => {
+            Context::new(AppErrorKind::Config).with(field::str("config.phase", "frozen"))
+        }
+        ConfigError::NotFound(key) => Context::new(AppErrorKind::Config)
+            .with(field::str("config.phase", "not_found"))
+            .with(field::str("config.key", key.clone())),
+        ConfigError::PathParse {
+            ..
+        } => Context::new(AppErrorKind::Config).with(field::str("config.phase", "path_parse")),
+        ConfigError::FileParse {
+            uri, ..
+        } => {
+            let mut ctx =
+                Context::new(AppErrorKind::Config).with(field::str("config.phase", "file_parse"));
+            if let Some(path) = uri {
+                ctx = ctx.with(field::str("config.uri", path.clone()));
+            }
+            ctx
+        }
+        ConfigError::Type {
+            origin,
+            unexpected,
+            expected,
+            key
+        } => {
+            let mut ctx = Context::new(AppErrorKind::Config)
+                .with(field::str("config.phase", "type"))
+                .with(field::str("config.expected", *expected))
+                .with(field::str("config.unexpected", unexpected.to_string()));
+            if let Some(origin) = origin {
+                ctx = ctx.with(field::str("config.origin", origin.clone()));
+            }
+            if let Some(key) = key {
+                ctx = ctx.with(field::str("config.key", key.clone()));
+            }
+            ctx
+        }
+        ConfigError::At {
+            origin,
+            key,
+            ..
+        } => {
+            let mut ctx =
+                Context::new(AppErrorKind::Config).with(field::str("config.phase", "at"));
+            if let Some(origin) = origin {
+                ctx = ctx.with(field::str("config.origin", origin.clone()));
+            }
+            if let Some(key) = key {
+                ctx = ctx.with(field::str("config.key", key.clone()));
+            }
+            ctx
+        }
+        ConfigError::Message(message) => Context::new(AppErrorKind::Config)
+            .with(field::str("config.phase", "message"))
+            .with(field::str("config.message", message.clone())),
+        ConfigError::Foreign(_) => {
+            Context::new(AppErrorKind::Config).with(field::str("config.phase", "foreign"))
+        }
     }
 }
 
 #[cfg(all(test, feature = "config"))]
 mod tests {
     use config::ConfigError;
 
-    use crate::{AppError, AppErrorKind};
+    use super::*;
+    use crate::{AppErrorKind, FieldValue};
 
     #[test]
     fn maps_to_config_kind() {
         let err = ConfigError::Message("dummy".into());
-        let app_err = AppError::from(err);
+        let app_err = Error::from(err);
         assert!(matches!(app_err.kind, AppErrorKind::Config));
+        let metadata = app_err.metadata();
+        assert_eq!(
+            metadata.get("config.phase"),
+            Some(&FieldValue::Str("message".into()))
+        );
     }
 }

src/convert/multipart.rs

@@ -1,4 +1,4 @@
-//! Maps [`MultipartError`] into [`AppError`] with
+//! Maps [`MultipartError`] into [`Error`] with
 //! [`AppErrorKind::BadRequest`], preserving the original message.
 //!
 //! Intended for Axum multipart form parsing so that client mistakes are
@@ -8,11 +8,16 @@
 
 use axum::extract::multipart::MultipartError;
 
-use crate::{AppError, AppErrorKind};
+use crate::{
+    AppErrorKind,
+    app_error::{Context, Error, field}
+};
 
-impl From<MultipartError> for AppError {
+impl From<MultipartError> for Error {
     fn from(err: MultipartError) -> Self {
-        AppError::with(AppErrorKind::BadRequest, format!("Multipart error: {err}"))
+        Context::new(AppErrorKind::BadRequest)
+            .with(field::str("multipart.reason", err.to_string()))
+            .into_error(err)
     }
 }
 
@@ -24,7 +29,7 @@ mod tests {
         http::Request
     };
 
-    use crate::{AppError, AppErrorKind};
+    use crate::{AppErrorKind, FieldValue};
 
     #[tokio::test]
     async fn multipart_error_maps_to_bad_request() {
@@ -42,10 +47,12 @@ mod tests {
             .expect("extractor");
 
         let err = multipart.next_field().await.expect_err("error");
-        let expected = format!("Multipart error: {err}");
-        let app_err: AppError = err.into();
+        let app_err: Error = err.into();
 
         assert_eq!(app_err.kind, AppErrorKind::BadRequest);
-        assert_eq!(app_err.message.as_deref(), Some(expected.as_str()));
+        assert_eq!(
+            app_err.metadata().get("multipart.reason"),
+            Some(&FieldValue::Str(err.to_string().into()))
+        );
     }
 }