feat!: introduce AppCode and new ErrorResponse fields

Author: RAprogramm

CHANGELOG.md

@@ -1,17 +1,30 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
-## [Unreleased]
+## [0.3.0] - 2025-08-24
+### Added
+- `AppCode` — stable machine-readable error code (part of the wire contract).
+- `ErrorResponse.code`, `ErrorResponse.retry`, `ErrorResponse.www_authenticate` fields.
+- Axum/Actix integrations now set `Retry-After` and `WWW-Authenticate` headers when applicable.
+
+### Changed (breaking)
+- `ErrorResponse::new` now requires `(status: u16, code: AppCode, message: impl Into<String>)`.
+
+### Migration
+- Replace `ErrorResponse::new(status, "msg")` with  
+  `ErrorResponse::new(status, AppCode::<Variant>, "msg")`.
+- Optionally use `.with_retry_after_secs(...)` and/or `.with_www_authenticate(...)`
+  to populate the new fields.
 
 ## [0.2.1] - 2025-08-20
 ### Changed
-- Cleanup of feature flags: clarified `openapi` vs `openapi-*`.
+- Cleaned up feature flags: clarified `openapi` vs `openapi-*`.
 - Simplified error DTOs (`ErrorResponse`) with proper `ToSchema` support.
 - Minor code cleanup in Actix and SQLx integration.
 
 ### Notes
-- MSRV: 1.89
-- No unsafe
+- **MSRV:** 1.89
+- **No unsafe**
 
 ## [0.2.0] - 2025-08-20
 ### Added
@@ -29,6 +42,7 @@ All notable changes to this project will be documented in this file.
 - **MSRV:** 1.89
 - **No unsafe:** the crate forbids `unsafe`.
 
+[0.3.0]: https://github.com/RAprogramm/masterror/releases/tag/v0.3.0
 [0.2.1]: https://github.com/RAprogramm/masterror/releases/tag/v0.2.1
 [0.2.0]: https://github.com/RAprogramm/masterror/releases/tag/v0.2.0
 

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "masterror"
-version = "0.2.1"
+version = "0.3.0"
 rust-version = "1.89"
 edition = "2024"
 description = "Application error types and response mapping"

Cargo.toml

@@ -0,0 +1,330 @@
+//! Public machine-readable error codes (`AppCode`).
+//!
+//! ## What is `AppCode`?
+//! A **stable error code** you can return to clients (mobile apps, frontends,
+//! other services). It is part of the public wire contract and is intended
+//! to stay stable across versions. Humans see `message`; machines key off
+//! `code`.
+//!
+//! `AppCode` complements (but does not replace) HTTP status codes:
+//! - `status` (e.g., 404, 422, 500) tells **transport-level** outcome.
+//! - `code` (e.g., `NOT_FOUND`, `VALIDATION`) tells **semantic category**,
+//!   which remains stable even if your transport mapping changes.
+//!
+//! ## Stability and SemVer
+//! - New variants **may be added in minor releases** (non-breaking).
+//! - The enum is marked `#[non_exhaustive]` so downstream users must include a
+//!   wildcard arm (`_`) when matching, which keeps them forward-compatible.
+//!
+//! ## Typical usage
+//! Construct an `ErrorResponse` with a code and return it to clients:
+//!
+//! ```rust
+//! use masterror::{AppCode, ErrorResponse};
+//!
+//! let resp = ErrorResponse::new(404, AppCode::NotFound, "User not found");
+//! ```
+//!
+//! Convert from internal taxonomy (`AppErrorKind`) to a public code:
+//!
+//! ```rust
+//! use masterror::{AppCode, AppErrorKind};
+//!
+//! let code = AppCode::from(AppErrorKind::Validation);
+//! assert_eq!(code.as_str(), "VALIDATION");
+//! ```
+//!
+//! Serialize to JSON (uses SCREAMING_SNAKE_CASE):
+//!
+//! ```rust
+//! # #[cfg(feature = "serde_json")]
+//! # {
+//! use masterror::AppCode;
+//! let json = serde_json::to_string(&AppCode::RateLimited).unwrap();
+//! assert_eq!(json, r#""RATE_LIMITED""#);
+//! # }
+//! ```
+//!
+//! Match codes safely (note the wildcard arm due to `#[non_exhaustive]`):
+//!
+//! ```rust
+//! use masterror::AppCode;
+//!
+//! fn is_client_error(code: AppCode) -> bool {
+//!     match code {
+//!         AppCode::NotFound
+//!         | AppCode::Validation
+//!         | AppCode::Conflict
+//!         | AppCode::Unauthorized
+//!         | AppCode::Forbidden
+//!         | AppCode::NotImplemented
+//!         | AppCode::BadRequest
+//!         | AppCode::RateLimited
+//!         | AppCode::TelegramAuth
+//!         | AppCode::InvalidJwt => true,
+//!         _ => false // future-proof: treat unknown as not client error
+//!     }
+//! }
+//! ```
+
+use std::fmt::{self, Display};
+
+use serde::{Deserialize, Serialize};
+#[cfg(feature = "openapi")]
+use utoipa::ToSchema;
+
+use crate::kind::AppErrorKind;
+
+/// Stable machine-readable error code exposed to clients.
+///
+/// Values are serialized as **SCREAMING_SNAKE_CASE** strings (e.g.,
+/// `"NOT_FOUND"`). This type is part of the public wire contract.
+///
+/// Design rules:
+/// - Keep the set small and meaningful.
+/// - Prefer adding new variants over overloading existing ones.
+/// - Do not encode private/internal details in codes.
+#[cfg_attr(feature = "openapi", derive(ToSchema))]
+#[non_exhaustive]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+pub enum AppCode {
+    // ───────────── 4xx family (client-visible categories) ─────────────
+    /// Resource does not exist or is not visible to the caller.
+    ///
+    /// Typically mapped to HTTP **404 Not Found**.
+    NotFound,
+
+    /// Input failed validation (shape, constraints, business rules).
+    ///
+    /// Typically mapped to HTTP **422 Unprocessable Entity**.
+    Validation,
+
+    /// State conflict with an existing resource or concurrent update.
+    ///
+    /// Typically mapped to HTTP **409 Conflict**.
+    Conflict,
+
+    /// Authentication required or failed (missing/invalid credentials).
+    ///
+    /// Typically mapped to HTTP **401 Unauthorized**.
+    Unauthorized,
+
+    /// Authenticated but not allowed to perform the operation.
+    ///
+    /// Typically mapped to HTTP **403 Forbidden**.
+    Forbidden,
+
+    /// Operation is not implemented or not supported by this deployment.
+    ///
+    /// Typically mapped to HTTP **501 Not Implemented**.
+    NotImplemented,
+
+    /// Malformed request or missing required parameters.
+    ///
+    /// Typically mapped to HTTP **400 Bad Request**.
+    BadRequest,
+
+    /// Client exceeded rate limits or quota.
+    ///
+    /// Typically mapped to HTTP **429 Too Many Requests**.
+    RateLimited,
+
+    /// Telegram authentication flow failed (signature, timestamp, or payload).
+    ///
+    /// Typically mapped to HTTP **401 Unauthorized**.
+    TelegramAuth,
+
+    /// Provided JWT is invalid (expired, malformed, wrong signature/claims).
+    ///
+    /// Typically mapped to HTTP **401 Unauthorized**.
+    InvalidJwt,
+
+    // ───────────── 5xx family (server/infra categories) ─────────────
+    /// Unexpected server-side failure not captured by more specific kinds.
+    ///
+    /// Typically mapped to HTTP **500 Internal Server Error**.
+    Internal,
+
+    /// Database-related failure (query, connection, migration, etc.).
+    ///
+    /// Typically mapped to HTTP **500 Internal Server Error**.
+    Database,
+
+    /// Generic service-layer failure (business logic or orchestration).
+    ///
+    /// Typically mapped to HTTP **500 Internal Server Error**.
+    Service,
+
+    /// Configuration error (missing/invalid environment or runtime config).
+    ///
+    /// Typically mapped to HTTP **500 Internal Server Error**.
+    Config,
+
+    /// Failure in the Turnkey subsystem/integration.
+    ///
+    /// Typically mapped to HTTP **500 Internal Server Error**.
+    Turnkey,
+
+    /// Operation did not complete within the allotted time.
+    ///
+    /// Typically mapped to HTTP **504 Gateway Timeout**.
+    Timeout,
+
+    /// Network-level error (DNS, connect, TLS, request build).
+    ///
+    /// Typically mapped to HTTP **503 Service Unavailable**.
+    Network,
+
+    /// External dependency is unavailable or degraded (cache, broker,
+    /// third-party).
+    ///
+    /// Typically mapped to HTTP **503 Service Unavailable**.
+    DependencyUnavailable,
+
+    /// Failed to serialize data (encode).
+    ///
+    /// Typically mapped to HTTP **500 Internal Server Error**.
+    Serialization,
+
+    /// Failed to deserialize data (decode).
+    ///
+    /// Typically mapped to HTTP **500 Internal Server Error**.
+    Deserialization,
+
+    /// Upstream API returned an error or protocol-level failure.
+    ///
+    /// Typically mapped to HTTP **500 Internal Server Error**.
+    ExternalApi,
+
+    /// Queue processing failure (publish/consume/ack).
+    ///
+    /// Typically mapped to HTTP **500 Internal Server Error**.
+    Queue,
+
+    /// Cache subsystem failure (read/write/encoding).
+    ///
+    /// Typically mapped to HTTP **500 Internal Server Error**.
+    Cache
+}
+
+impl AppCode {
+    /// Get the canonical string form of this code (SCREAMING_SNAKE_CASE).
+    ///
+    /// This is equivalent to how the code is serialized to JSON.
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            // 4xx
+            AppCode::NotFound => "NOT_FOUND",
+            AppCode::Validation => "VALIDATION",
+            AppCode::Conflict => "CONFLICT",
+            AppCode::Unauthorized => "UNAUTHORIZED",
+            AppCode::Forbidden => "FORBIDDEN",
+            AppCode::NotImplemented => "NOT_IMPLEMENTED",
+            AppCode::BadRequest => "BAD_REQUEST",
+            AppCode::RateLimited => "RATE_LIMITED",
+            AppCode::TelegramAuth => "TELEGRAM_AUTH",
+            AppCode::InvalidJwt => "INVALID_JWT",
+
+            // 5xx
+            AppCode::Internal => "INTERNAL",
+            AppCode::Database => "DATABASE",
+            AppCode::Service => "SERVICE",
+            AppCode::Config => "CONFIG",
+            AppCode::Turnkey => "TURNKEY",
+            AppCode::Timeout => "TIMEOUT",
+            AppCode::Network => "NETWORK",
+            AppCode::DependencyUnavailable => "DEPENDENCY_UNAVAILABLE",
+            AppCode::Serialization => "SERIALIZATION",
+            AppCode::Deserialization => "DESERIALIZATION",
+            AppCode::ExternalApi => "EXTERNAL_API",
+            AppCode::Queue => "QUEUE",
+            AppCode::Cache => "CACHE"
+        }
+    }
+}
+
+impl Display for AppCode {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        // Stable human/machine readable form matching JSON representation.
+        f.write_str(self.as_str())
+    }
+}
+
+impl From<AppErrorKind> for AppCode {
+    /// Map internal taxonomy (`AppErrorKind`) to public machine code
+    /// (`AppCode`).
+    ///
+    /// The mapping is 1:1 today and intentionally conservative.
+    fn from(kind: AppErrorKind) -> Self {
+        match kind {
+            // 4xx
+            AppErrorKind::NotFound => Self::NotFound,
+            AppErrorKind::Validation => Self::Validation,
+            AppErrorKind::Conflict => Self::Conflict,
+            AppErrorKind::Unauthorized => Self::Unauthorized,
+            AppErrorKind::Forbidden => Self::Forbidden,
+            AppErrorKind::NotImplemented => Self::NotImplemented,
+            AppErrorKind::BadRequest => Self::BadRequest,
+            AppErrorKind::RateLimited => Self::RateLimited,
+            AppErrorKind::TelegramAuth => Self::TelegramAuth,
+            AppErrorKind::InvalidJwt => Self::InvalidJwt,
+
+            // 5xx
+            AppErrorKind::Internal => Self::Internal,
+            AppErrorKind::Database => Self::Database,
+            AppErrorKind::Service => Self::Service,
+            AppErrorKind::Config => Self::Config,
+            AppErrorKind::Turnkey => Self::Turnkey,
+            AppErrorKind::Timeout => Self::Timeout,
+            AppErrorKind::Network => Self::Network,
+            AppErrorKind::DependencyUnavailable => Self::DependencyUnavailable,
+            AppErrorKind::Serialization => Self::Serialization,
+            AppErrorKind::Deserialization => Self::Deserialization,
+            AppErrorKind::ExternalApi => Self::ExternalApi,
+            AppErrorKind::Queue => Self::Queue,
+            AppErrorKind::Cache => Self::Cache
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{AppCode, AppErrorKind};
+
+    #[test]
+    fn as_str_matches_json_serde_names() {
+        assert_eq!(AppCode::NotFound.as_str(), "NOT_FOUND");
+        assert_eq!(AppCode::RateLimited.as_str(), "RATE_LIMITED");
+        assert_eq!(
+            AppCode::DependencyUnavailable.as_str(),
+            "DEPENDENCY_UNAVAILABLE"
+        );
+    }
+
+    #[test]
+    fn mapping_from_kind_is_stable() {
+        // Spot checks to guard against accidental remaps.
+        assert!(matches!(
+            AppCode::from(AppErrorKind::NotFound),
+            AppCode::NotFound
+        ));
+        assert!(matches!(
+            AppCode::from(AppErrorKind::Validation),
+            AppCode::Validation
+        ));
+        assert!(matches!(
+            AppCode::from(AppErrorKind::Internal),
+            AppCode::Internal
+        ));
+        assert!(matches!(
+            AppCode::from(AppErrorKind::Timeout),
+            AppCode::Timeout
+        ));
+    }
+
+    #[test]
+    fn display_uses_screaming_snake_case() {
+        assert_eq!(AppCode::BadRequest.to_string(), "BAD_REQUEST");
+    }
+}