From 1d9198f030fb0faacde4a4f974fc5901c8387f7d Mon Sep 17 00:00:00 2001 From: RA <70325462+RAprogramm@users.noreply.github.com> Date: Sun, 21 Sep 2025 06:43:27 +0700 Subject: [PATCH] Publish masterror-template for derive releases --- CHANGELOG.md | 51 ++++++++++++++++++++++ Cargo.lock | 6 +-- Cargo.toml | 6 +-- README.md | 15 +++---- masterror-derive/Cargo.toml | 2 +- masterror-derive/README.md | 68 +++++++++++++++++++++++++++++ masterror-template/Cargo.toml | 3 +- masterror-template/README.md | 81 +++++++++++++++++++++++++++++++++++ 8 files changed, 215 insertions(+), 17 deletions(-) create mode 100644 masterror-derive/README.md create mode 100644 masterror-template/README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 286bbe9..183f1fd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,33 @@ All notable changes to this project will be documented in this file. ## [Unreleased] +## [0.10.7] - 2025-10-24 + +### Fixed +- Published the shared template parser crate so `masterror-derive` no longer + depends on a workspace-only package when uploaded to crates.io. + +### Changed +- Bumped `masterror-derive` to `0.6.6` and `masterror-template` to `0.3.6` so + downstream users rely on the newly published parser crate. + +### Documentation +- Added a dedicated README for `masterror-template` describing installation, + parsing examples and formatter metadata for crates.io readers. + +## [0.10.6] - 2025-09-21 + +### Fixed +- Added a crate-local README for `masterror-derive` so `cargo publish` passes + when crates.io validates the `readme` manifest key. + +### Changed +- Bumped `masterror-derive` to `0.6.2` to capture the packaging fix. + +### Documentation +- Documented the derive macros and supported attributes in + `masterror-derive/README.md` for crates.io readers. + ## [0.10.5] - 2025-09-20 ### Added @@ -140,6 +167,12 @@ All notable changes to this project will be documented in this file. - Documented the `#[app_error(...)]` attribute in the README, outlining the struct and enum mapping patterns and the `message` flag behaviour. +## [0.6.6] - 2025-10-24 + +### Fixed +- Pointed the derive crate at the published `masterror-template` dependency so + `cargo publish` succeeds without private workspace patches. + ## [0.6.5] - 2025-10-12 ### Added @@ -437,6 +470,15 @@ All notable changes to this project will be documented in this file. ### Documentation - Documented browser/WASM support and console logging workflow in the README and crate docs. +## [0.3.6] - 2025-10-24 + +### Added +- Wrote a README for crates.io explaining installation and parser usage. + +### Fixed +- Removed the `publish = false` flag so the shared template parser can be + released alongside the derive crate. + ## [0.3.5] - 2025-09-12 ### Added - Conversion from `teloxide_core::RequestError` into `AppError` (feature `teloxide`). @@ -537,10 +579,19 @@ All notable changes to this project will be documented in this file. - **MSRV:** 1.89 - **No unsafe:** the crate forbids `unsafe`. +[0.10.7]: https://github.com/RAprogramm/masterror/releases/tag/v0.10.7 +[0.10.6]: https://github.com/RAprogramm/masterror/releases/tag/v0.10.6 +[0.6.6]: https://github.com/RAprogramm/masterror/releases/tag/v0.6.6 +[0.6.5]: https://github.com/RAprogramm/masterror/releases/tag/v0.6.5 +[0.6.4]: https://github.com/RAprogramm/masterror/releases/tag/v0.6.4 +[0.6.3]: https://github.com/RAprogramm/masterror/releases/tag/v0.6.3 +[0.6.2]: https://github.com/RAprogramm/masterror/releases/tag/v0.6.2 +[0.6.0]: https://github.com/RAprogramm/masterror/releases/tag/v0.6.0 [0.5.2]: https://github.com/RAprogramm/masterror/releases/tag/v0.5.2 [0.5.1]: https://github.com/RAprogramm/masterror/releases/tag/v0.5.1 [0.5.0]: https://github.com/RAprogramm/masterror/releases/tag/v0.5.0 [0.4.0]: https://github.com/RAprogramm/masterror/releases/tag/v0.4.0 +[0.3.6]: https://github.com/RAprogramm/masterror/releases/tag/v0.3.6 [0.3.5]: https://github.com/RAprogramm/masterror/releases/tag/v0.3.5 [0.3.4]: https://github.com/RAprogramm/masterror/releases/tag/v0.3.4 [0.3.3]: https://github.com/RAprogramm/masterror/releases/tag/v0.3.3 diff --git a/Cargo.lock b/Cargo.lock index f9dc7cb..a280190 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1606,7 +1606,7 @@ dependencies = [ [[package]] name = "masterror" -version = "0.10.5" +version = "0.10.7" dependencies = [ "actix-web", "axum", @@ -1636,7 +1636,7 @@ dependencies = [ [[package]] name = "masterror-derive" -version = "0.6.1" +version = "0.6.6" dependencies = [ "masterror-template", "proc-macro2", @@ -1646,7 +1646,7 @@ dependencies = [ [[package]] name = "masterror-template" -version = "0.3.1" +version = "0.3.6" [[package]] name = "matchit" diff --git a/Cargo.toml b/Cargo.toml index 32b82e1..9cddd72 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "masterror" -version = "0.10.5" +version = "0.10.7" rust-version = "1.90" edition = "2024" license = "MIT OR Apache-2.0" @@ -71,8 +71,8 @@ turnkey = [] openapi = ["dep:utoipa"] [workspace.dependencies] -masterror-derive = { version = "0.6.1" } -masterror-template = { version = "0.3.1" } +masterror-derive = { version = "0.6.6" } +masterror-template = { version = "0.3.6" } [dependencies] masterror-derive = { version = "0.6" } diff --git a/README.md b/README.md index 02da5d2..24b4ddf 100644 --- a/README.md +++ b/README.md @@ -29,9 +29,9 @@ Stable categories, conservative HTTP mapping, no `unsafe`. ~~~toml [dependencies] -masterror = { version = "0.10.5", default-features = false } +masterror = { version = "0.10.7", default-features = false } # or with features: -# masterror = { version = "0.10.5", features = [ +# masterror = { version = "0.10.7", features = [ # "axum", "actix", "openapi", "serde_json", # "sqlx", "sqlx-migrate", "reqwest", "redis", # "validator", "config", "tokio", "multipart", @@ -66,10 +66,10 @@ masterror = { version = "0.10.5", default-features = false } ~~~toml [dependencies] # lean core -masterror = { version = "0.10.5", default-features = false } +masterror = { version = "0.10.7", default-features = false } # with Axum/Actix + JSON + integrations -# masterror = { version = "0.10.5", features = [ +# masterror = { version = "0.10.7", features = [ # "axum", "actix", "openapi", "serde_json", # "sqlx", "sqlx-migrate", "reqwest", "redis", # "validator", "config", "tokio", "multipart", @@ -623,13 +623,13 @@ assert_eq!(resp.status, 401); Minimal core: ~~~toml -masterror = { version = "0.10.5", default-features = false } +masterror = { version = "0.10.7", default-features = false } ~~~ API (Axum + JSON + deps): ~~~toml -masterror = { version = "0.10.5", features = [ +masterror = { version = "0.10.7", features = [ "axum", "serde_json", "openapi", "sqlx", "reqwest", "redis", "validator", "config", "tokio" ] } @@ -638,7 +638,7 @@ masterror = { version = "0.10.5", features = [ API (Actix + JSON + deps): ~~~toml -masterror = { version = "0.10.5", features = [ +masterror = { version = "0.10.7", features = [ "actix", "serde_json", "openapi", "sqlx", "reqwest", "redis", "validator", "config", "tokio" ] } @@ -709,4 +709,3 @@ MSRV = 1.90 (may raise in minor, never in patch). Apache-2.0 OR MIT, at your option. - diff --git a/masterror-derive/Cargo.toml b/masterror-derive/Cargo.toml index d764ec5..c9ba1a6 100644 --- a/masterror-derive/Cargo.toml +++ b/masterror-derive/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "masterror-derive" rust-version = "1.90" -version = "0.6.1" +version = "0.6.6" edition = "2024" license = "MIT OR Apache-2.0" repository = "https://github.com/RAprogramm/masterror" diff --git a/masterror-derive/README.md b/masterror-derive/README.md new file mode 100644 index 0000000..9848d2a --- /dev/null +++ b/masterror-derive/README.md @@ -0,0 +1,68 @@ +# masterror-derive + +Procedural macros that power [`masterror`](https://crates.io/crates/masterror)'s +`#[derive(Error)]`. The derive generates ergonomic `std::error::Error` and +`Display` implementations together with seamless integration into +`masterror`'s domain-centric `AppError` type. + +> **Tip:** Depend on the `masterror` crate in application code and import the +> macros from there (`use masterror::Error;`). This standalone crate is +> published to make `cargo install`/`cargo package` flows happy and to support +> advanced macro integrations. + +## Quick start + +```toml +[dependencies] +masterror = "0.10" +``` + +```rust +use masterror::{AppError, Error}; + +#[derive(Error)] +#[error(display = "failed to parse payload: {source}")] +#[app_error(kind = "BadRequest")] +pub struct PayloadInvalid { + #[source] + pub source: serde_json::Error, +} + +fn parse(input: &str) -> Result<(), AppError> { + serde_json::from_str::(input) + .map(|_| ()) + .map_err(PayloadInvalid::from) +} +``` + +The derive implements `Display`, `std::error::Error`, and conversion glue so +you can return rich `AppError` values with a single `?`. + +## Supported attributes + +- `#[error(display = ...)]` – formats the error message using captured fields. +- `#[source]` / `#[from]` – wires source error propagation and conversion. +- `#[backtrace]` – exposes an optional captured `Backtrace`. +- `#[app_error(...)]` – configures how the error maps into `AppError` + (kind, HTTP status, telemetry). +- `#[provide(...)]` – attaches structured telemetry providers that surface + typed context (IDs, domains, tenant information) through tracing layers. + +See the main [`masterror` README](https://github.com/RAprogramm/masterror/blob/HEAD/README.md) for an end-to-end guide and +advanced examples covering templated display strings, telemetry providers and +OpenAPI/schema integrations. + +## License + +Licensed under either of + +- Apache License, Version 2.0, ([LICENSE-APACHE](https://github.com/RAprogramm/masterror/blob/HEAD/LICENSE-APACHE) or + ) +- MIT license ([LICENSE-MIT](https://github.com/RAprogramm/masterror/blob/HEAD/LICENSE-MIT) or ) + +at your option. + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in the work by you, as defined in the Apache-2.0 license, shall be +licensed as above, without any additional terms or conditions. + diff --git a/masterror-template/Cargo.toml b/masterror-template/Cargo.toml index 62bc80b..7ceec57 100644 --- a/masterror-template/Cargo.toml +++ b/masterror-template/Cargo.toml @@ -1,12 +1,11 @@ [package] name = "masterror-template" -version = "0.3.1" +version = "0.3.6" rust-version = "1.90" edition = "2024" repository = "https://github.com/RAprogramm/masterror" readme = "README.md" description = "Template utilities for masterror and its derive macros" -publish = false license = "MIT OR Apache-2.0" [dependencies] diff --git a/masterror-template/README.md b/masterror-template/README.md new file mode 100644 index 0000000..e1c15ff --- /dev/null +++ b/masterror-template/README.md @@ -0,0 +1,81 @@ +# masterror-template + +`masterror-template` packages the template parser shared by the [`masterror`][masterror] runtime crate and the [`masterror-derive`][derive] procedural macros. It understands the `#[error("...")]` formatting language popularised by `thiserror` v2, producing a structured representation that downstream code can inspect or render. + +The crate is intentionally small: it exposes just enough API for advanced applications that want to inspect derived error displays, implement custom derive helpers, or perform static analysis over formatting placeholders. + +## Installation + +Add the crate alongside `masterror` if you need direct access to the parser: + +```toml +[dependencies] +masterror-template = { version = "0.3.6" } +``` + +`masterror-template` targets Rust 1.90 and builds on stable and nightly toolchains alike. + +## Parsing templates + +Call [`ErrorTemplate::parse`](https://docs.rs/masterror-template/latest/masterror_template/template/struct.ErrorTemplate.html#method.parse) to turn an `&str` into a structured template: + +```rust +use masterror_template::template::{ErrorTemplate, TemplateIdentifier}; + +fn inspect(template: &str) { + let parsed = ErrorTemplate::parse(template).expect("valid template"); + + for placeholder in parsed.placeholders() { + match placeholder.identifier() { + TemplateIdentifier::Named(name) => println!("named placeholder: {name}"), + TemplateIdentifier::Positional(index) => println!("positional placeholder: {index}"), + TemplateIdentifier::Implicit(index) => println!("implicit placeholder: {index}"), + } + } +} +``` + +The parser preserves literal text and exposes every placeholder with span metadata, making it straightforward to surface diagnostics or transform templates programmatically. + +## Formatter metadata + +Each [`TemplatePlaceholder`](https://docs.rs/masterror-template/latest/masterror_template/template/struct.TemplatePlaceholder.html) advertises the requested formatter through [`TemplateFormatter`](https://docs.rs/masterror-template/latest/masterror_template/template/enum.TemplateFormatter.html) and [`TemplateFormatterKind`](https://docs.rs/masterror-template/latest/masterror_template/template/enum.TemplateFormatterKind.html): + +```rust +use masterror_template::template::{ErrorTemplate, TemplateFormatterKind}; + +let template = ErrorTemplate::parse("{value:#x}").expect("parse"); +let placeholder = template.placeholders().next().expect("placeholder"); +let formatter = placeholder.formatter(); +assert_eq!(formatter.kind(), TemplateFormatterKind::LowerHex); +assert!(formatter.is_alternate()); +``` + +This mirrors the formatting traits accepted by `core::fmt`, enabling consumers to route values through `Display`, `Debug`, hexadecimal, binary, pointer, or exponential renderers. + +## Error reporting + +Parsing failures produce [`TemplateError`](https://docs.rs/masterror-template/latest/masterror_template/template/enum.TemplateError.html) variants with precise byte ranges. The metadata simplifies IDE integrations and procedural macros that need to point at the offending part of the template. + +```rust +use masterror_template::template::ErrorTemplate; + +let err = ErrorTemplate::parse("{foo").unwrap_err(); +assert!(matches!(err, masterror_template::template::TemplateError::UnterminatedPlaceholder { .. })); +``` + +## License + +Dual licensed under either of + +- Apache License, Version 2.0, ([LICENSE-APACHE](../LICENSE-APACHE) or ) +- MIT license ([LICENSE-MIT](../LICENSE-MIT) or ) + +at your option. + +### Contribution + +Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. + +[masterror]: https://crates.io/crates/masterror +[derive]: https://crates.io/crates/masterror-derive