zappb-exceptions 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7c0be24c4d6adeab3ed623c2a0f6b6318506fbe85895fe0d992e5ade463cc09c
+  data.tar.gz: c015a50b34a83af5f391cc0ad948272dd09423635e71dff51bd30391f9c37bc0
+SHA512:
+  metadata.gz: c5420706184acb30a4585ff6b7cf1a820da1ed336c54c4c2c781e6a08615320c37f194996e6973eb9b75657a044625246bdf204425d898eab9cde237963981cf
+  data.tar.gz: 51475fa8e66e36a7d30dd8dea75973960b0f54c85db770592054d6ffa029f99ab79610b3bb17a89394d43e6884faefbfa64cbe07bf178d31b161661b7549a41a

data/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+## [Unreleased]
+
+## [1.0.0] - 2026-11-09
+
+### Added
+
+- Catalog: `Definition`, `Registry`, `ClassFactory`, `Resolver`, `Envelope`, `Notifier`, `Handler` (Rails), `Rack` and the base catalog of generic HTTP errors.
+- `ZappbException::NoMethodError`, `NameError`, `ArgumentError` and `Exception` exist in the namespace and inherit from `BaseError`.
+- A single `rescue_from StandardError` resolves by class hierarchy (independent of catalog order).
+- NATS layer: `Nats.reply`, `Nats.error_response?`, `Nats.raise_on_error!(response, on_nil:, meta:)` and `RemoteError.from` (tolerant reading, `RemoteError::NoResponse`). `on_nil` accepts an exception class or instance.
+- `RemoteError#success?` (strict: a Hash with `success` true or "true"; different from `ok?`) and `RemoteError#extra`. `NoResponse` and `ForwardedError` support them.
+- `ForwardedError#remote`, `#status`, `#code`, `#kind?`, `#success?`, `#extra`, `#detail` and `#remote_meta`.
+- Test helpers: `zappb_exception/testing` (`Testing.error_response(..., extra:, meta:)`, `success_response`) and `zappb_exception/rspec` (`be_zappb_error`, `raise_zappb_error`, `match_error_envelope(meta:)`). `Testing.error_response` reports the same `error.exception` as the real Envelope, including the adopted class name for `klass:` entries.
+- The Handler registers a `Proc` instead of an instance method, so class-level `rescue_with_handler` works.
+- `Rack.render` notifies through the Notifier by default (`notify: false` to disable).
+- Extra data in `error`: `BaseError#extra_data`, `PayloadError`, `register(payload: true)`, merged in the Envelope without overwriting `exception`/`detail`.
+- `register(payload: %i[retry_after])`: readers, `extra_data` with every declared key (nil by default), `ArgumentError` for undeclared keys, `ConfigurationError` for reserved keys.
+- Namespaced internal names (`register "Billing::InvoiceError"`): the gem creates `ZappbException::Billing::InvoiceError` and the intermediate modules (nestable, any registration order). I18n key: the full name with `::`.
+- Per-service meta: `config.meta_key`; `BaseError#meta` / `with_meta`; `meta:` keyword in `Handler.handle`, `Rack.render`, `Nats.reply`, `Nats.raise_on_error!` and `generate_json`; `PayloadError` and `ForwardedError` accept `meta:`. The Envelope signs local meta with `meta_key`, keeps the remote meta of a `ForwardedError` and merges both (local wins). Events include `meta`; `RemoteError#meta`.
+- Base entry `MissingConfiguration` (500-90) and per-entry `register(safe_detail:)`, which overrides `config.safe_detail` (events still receive the full message).
+- `Configuration#alias_external(class_name, to:)`: maps an external class to an existing entry without `override:`.
+- `ZappbException.describe(exception)` returning `Description(status, code, message)`.
+- `ZappbException.log_level(exception)` and `Description#level`: `:warn` (< 500) or `:error` (>= 500); the Notifier uses the same function.
+- Events `zappb_exception.error` and `zappb_exception.forwarded_error` include `extra` (omitted when empty).
+- Default safe detail in the base catalog: `safe_detail: true` in `RecordNotFound` (and its `ActiveRecord::RecordNotFound` alias), `Exception`, `NameError`, `NoMethodError`, `Wrong200`, `TokenError`, `ActionView::Template::Error`, `ServiceUnavailable` and `GatewayTimeout`; the `500-<P>00` fallback also hides the detail of non-`BaseError` exceptions (unless a global `config.safe_detail` of `true`/callable is set). `RecordInvalid` is not hidden.
+- Reserved numbers: 90-99 of every status are reserved for future base entries.
+- I18n: English (`en.yml`) and Spanish (`es.yml`) base messages and the new `config.locale` option (`nil` follows `I18n.locale`; a Symbol/String forces that locale for every message the gem produces). Locale files are added to `I18n.load_path` with and without Rails.
+- Railtie freezes the catalog in `after_initialize`.
+
+### Changed
+
+- English is the default language: base catalog messages, the `Unhandled exception` fallback and every text the gem generates (`ConfigurationError`, `ArgumentError`, ...) are in English. The previous Spanish messages remain available in `es.yml` (`c.locale = :es`).
+- Error numbers are integers >= 1 (no octal literals).
+- `ForwardedError` responds with the real status of the received hash.
+- `ZappbException.define_exceptions!` is deprecated: an idempotent no-op.
+- Gemspec summary and description in English; homepage set to the rubygems page.
+- Code comments removed from `lib/`; maintainer documentation lives in `CLAUDE.md`.
+
+### Breaking
+
+- A name with `::` no longer implies `external`. Only `external: true` (or `klass:` with a namespaced name) makes an entry external; otherwise the internal class `ZappbException::<A>::<B>` is created. The base entries `ActionView::Template::Error`, `ActiveRecord::RecordInvalid` and `ActionDispatch::Http::Parameters::ParseError` are `external: true`.
+- `error.detail` of foreign exceptions covered by the default safe detail is now the class name.
+- Default message language is English (see "Changed"); services that relied on Spanish base messages must set `c.locale = :es`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BPO Advisors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,457 @@
+# zappb-exceptions
+
+Exception handling for microservices in an MSA architecture that communicate through messaging (NATS, used together
+with the `nats_messaging` gem) and expose HTTP APIs. Each service declares its own error catalog; a stable JSON
+error contract travels between services and to clients. The gem ships only generic HTTP errors: business errors
+always belong to the service that declares them.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "zappb-exceptions", "~> 1.0"
+```
+
+Requirements: Ruby >= 3.2 and `activesupport >= 8.0` (Rails 8 or later when you use the Rails integration). The
+`Railtie` is loaded only when `Rails::Railtie` is defined; everything else works without Rails.
+
+## Configuration
+
+```ruby
+# config/initializers/zappb_exception.rb
+ZappbException.configure do |c|
+  c.code_prefix   = "OR"            # "404-OR02" (default "" => "404-02")
+  c.service_label = "Orders"        # error.detail => "[Orders] ..." (default: the Rails app module name)
+  c.meta_key      = :orders         # key under which this service signs its meta (default nil)
+  c.safe_detail   = true            # true | false | ->(exception) { String }
+  c.locale        = :es             # explicit message locale (default nil => I18n.locale)
+  c.logger        = Rails.logger    # default: Rails.logger, or a Logger on $stdout
+
+  c.register "OrderNotFound", status: 404, number: 3, message: "Order not found"
+  c.register "OrderLocked",   status: 409, number: 1, code: "order_locked", message: "Order locked"
+end
+```
+
+| Option | Meaning |
+|---|---|
+| `code_prefix` | Prefix of the visible code, `<status>-<PREFIX><NN>`. Converted with `to_s`. |
+| `service_label` | Label prepended to `error.detail` as `[Label] `. `nil` or empty disables it. |
+| `meta_key` | `nil`, or a non-empty String/Symbol. Signs this service's local meta (see "Meta"). Otherwise `ConfigurationError`. |
+| `safe_detail` | `true`, `false` or a callable. See "Detail sanitization". Otherwise `ConfigurationError`. |
+| `locale` | `nil`, or a non-empty String/Symbol. See "I18n". Otherwise `ConfigurationError`. |
+| `logger` | Logger used when `Rails.event` is not available and for internal failures. |
+
+### `register`
+
+```ruby
+c.register(name, status:, message:, number: nil, code: nil, external: false, klass: nil,
+           payload: false, aliases: [], safe_detail: nil, override: false)
+```
+
+| Option | Meaning |
+|---|---|
+| `status` | Integer, 400..599. |
+| `number` | Integer >= 1. `status` + `number` must be unique unless the entry has `code:`. Numbers 90-99 of every status are reserved for the gem's base catalog: services must not use them. |
+| `message` | Default text (required). Can be overridden through I18n. |
+| `code` | Readable visible code (`"order_locked"`) instead of `<status>-<PREFIX><NN>`. |
+| `external` | `true` for a class that is not created by the gem (a library error): it is matched by class name in the resolver and no constant is defined. A `::` in the name does not imply `external`. |
+| `klass` | Adopts an existing class (a Class or a lazy lambda returning one): `klass: -> { CustomFailure }`. A namespaced name with `klass:` is treated as external. |
+| `payload` | `true` (free payload) or an Array of declared keys. See "Raising errors". |
+| `aliases` | Other class names that resolve to this entry. |
+| `safe_detail` | Per-entry override of `config.safe_detail`. |
+| `override` | Required to redefine a base or already registered entry. |
+
+Internal entries create `ZappbException::<Name>`, a subclass of `ZappbException::BaseError` (or of `PayloadError`
+when `payload:` is set). Names may be namespaced; each segment must be a valid constant name:
+
+```ruby
+c.register "Billing::InvoiceError",        status: 409, number: 3, message: "Invalid invoice"
+c.register "Inventory::Stock::OutOfStock", status: 409, number: 4, message: "Out of stock"
+
+raise ZappbException::Billing::InvoiceError, "missing tax id"
+# error.exception => "ZappbException::Billing::InvoiceError"
+```
+
+Intermediate segments are created as modules (or reused when they already exist in `ZappbException`); registering
+`"A"` and `"A::Error"` works in either order. `"Error"` and `"Billing::Error"` are distinct entries.
+
+### `alias_external`
+
+```ruby
+c.alias_external "Vendor::AccessDenied", to: "Forbidden"
+```
+
+Maps an external class (by name, resolved lazily) to an entry that is already registered (base or service), without
+`override:`. Raises `ConfigurationError` if the target does not exist. `error.exception` keeps the real class name.
+
+### Code format and catalog freezing
+
+Visible code: `code:` if present, otherwise `"<status>-<PREFIX><NN>"` with `NN` zero-padded (`"404-OR03"`). The
+fallback for unregistered exceptions is `"500-<PREFIX>00"`.
+
+The catalog is frozen in `after_initialize` (Railtie) or with `ZappbException.finalize!`: a late `register` raises
+`ZappbException::FrozenRegistryError`. `ZappbException.reset!` restores the base catalog and default configuration
+(meant for tests).
+
+## Raising errors
+
+```ruby
+raise ZappbException::OrderNotFound, "order 7"
+raise ZappbException::Billing::InvoiceError.new("missing tax id", meta: { channel: "sms" })
+raise ZappbException::BadRequest, "missing field"
+```
+
+Payload: with `payload: true` the class inherits from `ZappbException::PayloadError`; keyword arguments are exposed in
+`payload` and merged into `error`:
+
+```ruby
+c.register "OutOfStock", status: 409, number: 4, message: "Out of stock", payload: true
+
+raise ZappbException::OutOfStock.new("SKU A1 unavailable", missing: ["A1"])   # error: { exception:, detail:, missing: ["A1"] }
+raise ZappbException::OutOfStock                                              # message => "ZappbException::OutOfStock"
+```
+
+Declared keys (`payload: %i[retry_after]`) generate readers, `extra_data` always includes every declared key (`nil`
+when not given) and an undeclared key raises `ArgumentError`:
+
+```ruby
+c.register "Billing::Throttled", status: 429, number: 5, message: "Rate limited", payload: %i[retry_after]
+
+e = ZappbException::Billing::Throttled.new("slow down", retry_after: 3)
+e.retry_after   # => 3
+e.extra_data    # => { retry_after: 3 }
+ZappbException::Billing::Throttled.new("x", retry_aftr: 3)   # ArgumentError
+```
+
+The keys `meta`, `exception` and `detail` (and any name that is already a method of the exception, such as
+`message`) are reserved and raise `ConfigurationError` when registering. `exception` and `detail` can never be
+overwritten by extra data.
+
+Meta: pass `meta:` to the constructor, or use `with_meta` for subclasses with their own `initialize`:
+
+```ruby
+raise ZappbException::BadRequest.new("missing field", meta: { channel: "sms" })
+raise MyError.new("x", retry_after: 3).with_meta(foo: 1)
+```
+
+## Capturing errors
+
+All capture points share the same `Envelope` (the JSON shape) and the same notifier (events), and all accept
+`meta:` (local meta).
+
+### Rails controllers
+
+```ruby
+class ApplicationController < ActionController::API
+  include ZappbException::Handler
+end
+```
+
+`include ZappbException::Handler` registers a single `rescue_from StandardError`; the resolver walks the exception
+class ancestors and picks the most specific catalog entry. `rescue_from` declarations made after the `include` keep
+priority. To pass meta, declare the rescue explicitly:
+
+```ruby
+rescue_from StandardError do |e|
+  ZappbException::Handler.handle(self, e, meta: { request_id: request.request_id })
+end
+```
+
+Anything that does not match the catalog answers `500-<PREFIX>00` ("Unhandled exception").
+
+### Rack middlewares
+
+```ruby
+status, headers, body = ZappbException::Rack.render(exception, meta: { request_id: "abc" })
+# => [404, { "content-type" => "application/json" }, ["{...}"]]
+```
+
+`notify: false` disables event emission.
+
+### NATS listeners
+
+```ruby
+class OrdersListener
+  def handle(subject, msg)
+    ZappbException::Nats.reply(meta: { request_id: msg["request_id"] }) { process(subject, msg) }
+  end
+end
+```
+
+`Nats.reply` returns the block result untouched; if the block raises a `StandardError` it returns the compacted
+error envelope (same shape as `ZappbException.generate_json`) and emits the same events as the HTTP handler
+(`notify: false` to skip). A `ForwardedError` is forwarded with its hash. A failure while notifying is logged and
+never prevents the reply. `rescue_with_handler` at class level also works with the `Handler`.
+
+`ZappbException.generate_json(exception, name = exception.class.name, meta: {})` returns the same envelope without
+Rails or a request.
+
+## Sending and reading errors between services
+
+The gem does not depend on `nats_messaging`; it works on the response Hash (string or symbol keys).
+`nats_messaging` returns `nil` on timeout or transport error.
+
+```ruby
+response = nats.send_request(subject, payload, 5)
+ZappbException::Nats.raise_on_error!(response, meta: { division_id: 12 })
+```
+
+`Nats.raise_on_error!(response, on_nil: GatewayTimeout, meta: {})`:
+
+- `nil` raises `on_nil` (default `ZappbException::GatewayTimeout`, 504-01). `on_nil` accepts an exception class or
+  an instance (custom message); anything else raises `ArgumentError`. `meta` is applied when `on_nil` is a
+  `BaseError` class or instance.
+- An error response raises `ZappbException::ForwardedError` carrying the response (`meta` is its local meta).
+- Anything else is returned as is.
+
+```ruby
+ZappbException::Nats.raise_on_error!(response, on_nil: ZappbException::ServiceUnavailable.new("inventory is down"))
+```
+
+`Nats.error_response?(response)` is true when `success` is `false` (or `"false"`) or `error` is present and not
+empty. `nil` or a non-Hash is not an error response (it is "no response"), and `error: {}` with `success` other than
+`false` is not an error.
+
+### ForwardedError
+
+```ruby
+begin
+  ZappbException::Nats.raise_on_error!(response)
+rescue ZappbException::ForwardedError => e
+  e.status                          # => 409 (Integer or nil)
+  e.code                            # => "409-IV04"
+  e.kind?(:OutOfStock)              # exact match on the normalized remote class name
+  e.detail(strip_label: true)       # "[Inventory] SKU A1 unavailable" => "SKU A1 unavailable"
+  e.extra                           # => { missing: ["A1"] }
+  e.remote                          # RemoteError view of the response
+  e.remote_meta                     # meta of the remote hash (#meta is this exception's local meta)
+  raise                             # re-raising forwards the remote code and status unchanged
+end
+```
+
+`ForwardedError.new("status" => 404, ...)` (a hash without braces) arrives as keyword arguments, so a `meta` key is
+read as local meta; pass the hash in braces to forward a remote `meta`.
+
+### RemoteError
+
+```ruby
+err = ZappbException::RemoteError.from(response)   # never raises
+err.no_response?   # nil or a non-Hash (timeout)
+err.error?
+err.ok?            # "is not an error response": tolerates responses without `success`
+err.success?       # strict: true only for a Hash with success true or "true"
+err.status         # Integer or nil
+err.code
+err.message
+err.exception_name # without the "ZappbException::" prefix
+err.kind?(:OutOfStock, "ZappbException::NotFound")
+err.detail(strip_label: true)
+err.extra          # fields of `error` other than exception/detail, Symbol keys
+err.meta           # meta as received ({} if absent)
+err.to_forwarded_error   # ForwardedError (GatewayTimeout when there was no response)
+```
+
+`kind?` compares the complete normalized name: `kind?("Billing::InvoiceError")` matches, `kind?("InvoiceError")`
+does not. `ok?` and `success?` are not equivalent: use `success?` when you are going to consume the result.
+Without a response `RemoteError.from` returns `RemoteError::NoResponse` (a null object: `error?`, `ok?` and
+`success?` are false, the rest is `nil`/`{}`).
+
+### Meta
+
+Meta is context information added by services at the point of use; the gem never invents it.
+
+- Local meta: the `meta:` keyword of each capture point and/or the exception's own meta (`BaseError#meta`); when
+  both exist they are merged and the keyword wins.
+- With `config.meta_key` set, local meta is signed: `{ meta_key => local }`. Without `meta_key` (an edge service) it
+  goes at the root of `meta`.
+- When a `ForwardedError` is forwarded, the remote meta is kept and the signed local meta is merged into it; if a
+  key exists on both sides and both values are Hashes they are merged (local wins), otherwise local wins.
+- Empty final meta: the response has no `meta` key. Non-Hash values are ignored; keys are normalized to Symbols.
+
+A chain with fictitious services (`inventory` signs with `:inventory`, `billing` with `:billing`, an edge service
+without `meta_key`):
+
+```ruby
+# inventory replies:                              meta: { inventory: { channel: "sms" } }
+# billing forwards it with meta: { division_id: 12 }
+#                                                 meta: { inventory: { channel: "sms" }, billing: { division_id: 12 } }
+# the edge forwards it with meta: { request_id: "abc" }
+#                                                 meta: { request_id: "abc", inventory: { ... }, billing: { ... } }
+```
+
+## The JSON contract
+
+```json
+{
+  "success": false,
+  "status": 409,
+  "code": "409-IV04",
+  "message": "Out of stock",
+  "error": {
+    "exception": "ZappbException::OutOfStock",
+    "detail": "[Inventory] SKU A1 unavailable",
+    "missing": ["A1"]
+  },
+  "meta": { "inventory": { "warehouse": 3 } }
+}
+```
+
+- `success` is always `false`; `status` is the HTTP status; `code` the visible code; `message` the localized text.
+- `error.exception` is the class name (`ZappbException::` prefix for internal entries); `error.detail` is the
+  sanitized message with the service label; extra fields come from the payload of the exception.
+- `meta` appears only when there is meta. `nil` keys are removed from the top level of the response.
+
+A forwarded error keeps the remote body and status, and merges the meta of every hop. Forwarded by `orders`
+(`meta_key :orders`) with `meta: { order_id: 7 }`:
+
+```json
+{
+  "success": false,
+  "status": 409,
+  "code": "409-IV04",
+  "message": "Out of stock",
+  "error": {
+    "exception": "ZappbException::OutOfStock",
+    "detail": "[Inventory] SKU A1 unavailable",
+    "missing": ["A1"]
+  },
+  "meta": { "inventory": { "warehouse": 3 }, "orders": { "order_id": 7 } }
+}
+```
+
+## Base catalog
+
+Generic HTTP errors only. Numbers 90-99 are reserved for new base entries. Messages are shown in English; the
+gem also ships `es` translations (see "I18n").
+
+| Name | Code | Message | Aliases |
+|---|---|---|---|
+| Exception | 500-01 | Server error | |
+| NameError | 500-02 | Method not implemented | |
+| NoMethodError | 500-03 | Method not implemented | |
+| Wrong200 | 500-04 | Remote server error | |
+| TokenError | 500-05 | Remote server connection error | |
+| ActionView::Template::Error | 500-06 | Error rendering response | (external) |
+| MissingConfiguration | 500-90 | Incomplete service configuration | |
+| BadRequest | 400-01 | Invalid input parameters | ActionController::ParameterMissing |
+| ArgumentError | 400-02 | Invalid input parameters | |
+| ActiveRecord::RecordInvalid | 400-03 | Invalid input parameters | (external) |
+| ActionDispatch::Http::Parameters::ParseError | 400-04 | Invalid input parameters | (external) |
+| Unauthorized | 401-01 | Authentication error | |
+| Forbidden | 403-01 | You do not have permission to perform this action | |
+| NotFound | 404-01 | Page not found | |
+| RecordNotFound | 404-02 | Resource not available | ActiveRecord::RecordNotFound |
+| PayloadTooLarge | 413-01 | Request body exceeds the maximum allowed size | |
+| ServiceUnavailable | 503-01 | Service temporarily unavailable | |
+| GatewayTimeout | 504-01 | Timeout | NoResponseError, NatsTimeoutError |
+| (fallback) | 500-00 | Unhandled exception | any other exception |
+
+`Conflict` (409) and `UnprocessableEntity` (422) are not in the base: declare them in your service if needed.
+`Exception` only matches `ZappbException::Exception`; any other `StandardError` falls into the fallback.
+
+## Detail sanitization
+
+`error.detail` is the exception message prefixed with the service label. `safe_detail` controls what is exposed:
+
+- `false`: the exception message.
+- `true`: a `BaseError` shows its message; any other exception shows its class name.
+- callable: `->(exception) { String }`.
+
+Precedence: the entry's `safe_detail` wins over `config.safe_detail`; the global one applies to entries registered
+without `safe_detail:`. The base catalog hides foreign exception details by default (`safe_detail: true`) in
+`Exception`, `NameError`, `NoMethodError`, `Wrong200`, `TokenError`, `ActionView::Template::Error`,
+`RecordNotFound`, `ServiceUnavailable` and `GatewayTimeout`, and `MissingConfiguration` always answers the class name.
+The fallback also hides the detail unless the service sets its own global `safe_detail` (`true` or callable).
+`ActiveRecord::RecordInvalid` is deliberately not hidden. Events and logs always receive the full message.
+
+## Events and logging
+
+Events are published through `Rails.event`; when it is not available, one JSON line is written to the logger.
+
+- `zappb_exception.error`: `exception_class`, `http_status`, `error_code`, `message`, `backtrace` (10 lines for
+  status >= 500, 1 otherwise), `meta` and `extra` (omitted when empty).
+- `zappb_exception.forwarded_error`: `http_status`, `error_code`, `message`, `meta` and `extra` (read from the remote
+  hash; omitted when empty).
+
+Level: `error` for status >= 500, `warn` otherwise. The same function is public:
+
+```ruby
+ZappbException.log_level(exception)             # => :warn or :error
+ZappbException.log_level(forwarded_error)       # uses the remote status
+```
+
+## I18n
+
+Base messages are translated in `config/locales/en.yml` and `config/locales/es.yml` under
+`zappb_exception.errors.<Name>`, and both files are added to `I18n.load_path` (with or without Rails). The literal
+`message:` of an entry is the default when no translation exists.
+
+- Default: the message uses `I18n.locale`.
+- `c.locale = :es` forces that locale for every message the gem produces, regardless of `I18n.locale`
+  (`I18n.t(..., locale:)`). The value is a Symbol or String (or `nil` to follow `I18n.locale`).
+- Regional locales such as `es-CL` have no translation file in the gem: set `c.locale = :es` (or add your own
+  keys for the regional locale).
+- A service overrides any text with its own locale files, using the entry name as key (full name with `::` for
+  namespaced entries, quoted in YAML):
+
+```yaml
+es:
+  zappb_exception:
+    errors:
+      "OrderNotFound": "Pedido no encontrado"
+      "Billing::InvoiceError": "Factura invalida"
+```
+
+## `ZappbException.describe`
+
+```ruby
+ZappbException.describe(exception)
+# => #<data ZappbException::Describer::Description status=409, code="409-IV04", message="Out of stock">
+```
+
+Returns `status`, `code` and `message` according to the catalog (for a `ForwardedError`, the remote values) and
+`#level`. It does not notify and does not expose the class name; meant for jobs that persist an error.
+
+## Testing helpers
+
+Mocks for NATS responses (no RSpec required):
+
+```ruby
+require "zappb_exception/testing"
+
+ZappbException::Testing.error_response(:OutOfStock, detail: "none", extra: { missing: ["A1"] },
+                                       meta: { inventory: { channel: "sms" } })
+# => { success: false, status: 409, code: "409-IV04", message: "Out of stock",
+#      error: { exception: "ZappbException::OutOfStock", detail: "[Inventory] none", missing: ["A1"] },
+#      meta: { inventory: { channel: "sms" } } }
+
+ZappbException::Testing.success_response(id: 1)
+# => { success: true, status: 200, message: nil, data: { id: 1 }, meta: {} }
+```
+
+`error_response` uses the loaded catalog (prefix and label of the configuration) and raises `ArgumentError` for an
+unregistered name.
+
+RSpec matchers:
+
+```ruby
+require "zappb_exception/rspec"
+
+expect(error).to be_zappb_error(:BadRequest)                  # resolves through the catalog (aliases, subclasses)
+expect { call }.to raise_zappb_error(:NotFound, /order/)      # optional message
+expect(json).to match_error_envelope(code: "404-OR02", status: 404, exception: :OutOfStock)
+```
+
+`match_error_envelope` is partial: it accepts a Hash (string or symbol keys) or a JSON String and the keys `code`,
+`status`, `message`, `exception`, `detail` and `meta`; values may be matchers such as regular expressions.
+
+## Development
+
+```
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT. See `LICENSE.txt`.

data/config/locales/en.yml

@@ -0,0 +1,22 @@
+en:
+  zappb_exception:
+    errors:
+      "Exception": "Server error"
+      "NameError": "Method not implemented"
+      "NoMethodError": "Method not implemented"
+      "Wrong200": "Remote server error"
+      "TokenError": "Remote server connection error"
+      "ActionView::Template::Error": "Error rendering response"
+      "MissingConfiguration": "Incomplete service configuration"
+      "BadRequest": "Invalid input parameters"
+      "ArgumentError": "Invalid input parameters"
+      "ActiveRecord::RecordInvalid": "Invalid input parameters"
+      "ActionDispatch::Http::Parameters::ParseError": "Invalid input parameters"
+      "Unauthorized": "Authentication error"
+      "Forbidden": "You do not have permission to perform this action"
+      "NotFound": "Page not found"
+      "RecordNotFound": "Resource not available"
+      "PayloadTooLarge": "Request body exceeds the maximum allowed size"
+      "ServiceUnavailable": "Service temporarily unavailable"
+      "GatewayTimeout": "Timeout"
+      Unhandled: "Unhandled exception"

data/config/locales/es.yml

@@ -0,0 +1,22 @@
+es:
+  zappb_exception:
+    errors:
+      "Exception": "Error en el servidor"
+      "NameError": "Método no implementado"
+      "NoMethodError": "Método no implementado"
+      "Wrong200": "Error en servidor remoto"
+      "TokenError": "Error de conexión a servidor remoto"
+      "ActionView::Template::Error": "Error al renderizar respuesta"
+      "MissingConfiguration": "Configuración del servicio incompleta"
+      "BadRequest": "Error en parámetros de entrada"
+      "ArgumentError": "Error en parámetros de entrada"
+      "ActiveRecord::RecordInvalid": "Error en parámetros de entrada"
+      "ActionDispatch::Http::Parameters::ParseError": "Error en parámetros de entrada"
+      "Unauthorized": "Error de autenticación"
+      "Forbidden": "No cuentas con los permisos necesarios para realizar esta acción"
+      "NotFound": "Página no encontrada"
+      "RecordNotFound": "Recurso no disponible"
+      "PayloadTooLarge": "El cuerpo del request excede el tamaño máximo permitido"
+      "ServiceUnavailable": "Servicio temporalmente no disponible"
+      "GatewayTimeout": "Timeout"
+      Unhandled: "Excepción no controlada"

data/lib/zappb/exceptions.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "zappb_exception"

data/lib/zappb_exception/base_catalog.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ZappbException
+  BASE_CATALOG = [
+    { name: "Exception", status: 500, number: 1, message: "Server error", safe_detail: true },
+    { name: "NameError", status: 500, number: 2, message: "Method not implemented", safe_detail: true },
+    { name: "NoMethodError", status: 500, number: 3, message: "Method not implemented", safe_detail: true },
+    { name: "Wrong200", status: 500, number: 4, message: "Remote server error", safe_detail: true },
+    { name: "TokenError", status: 500, number: 5, message: "Remote server connection error", safe_detail: true },
+    { name: "ActionView::Template::Error", status: 500, number: 6, message: "Error rendering response",
+      external: true, safe_detail: true },
+    { name: "MissingConfiguration", status: 500, number: 90, message: "Incomplete service configuration",
+      safe_detail: ->(exception) { exception.class.name.to_s } },
+    { name: "BadRequest", status: 400, number: 1, message: "Invalid input parameters",
+      aliases: ["ActionController::ParameterMissing"] },
+    { name: "ArgumentError", status: 400, number: 2, message: "Invalid input parameters" },
+    { name: "ActiveRecord::RecordInvalid", status: 400, number: 3, message: "Invalid input parameters",
+      external: true },
+    { name: "ActionDispatch::Http::Parameters::ParseError", status: 400, number: 4,
+      message: "Invalid input parameters", external: true },
+    { name: "Unauthorized", status: 401, number: 1, message: "Authentication error" },
+    { name: "Forbidden", status: 403, number: 1,
+      message: "You do not have permission to perform this action" },
+    { name: "NotFound", status: 404, number: 1, message: "Page not found" },
+    { name: "RecordNotFound", status: 404, number: 2, message: "Resource not available",
+      safe_detail: true, aliases: ["ActiveRecord::RecordNotFound"] },
+    { name: "PayloadTooLarge", status: 413, number: 1,
+      message: "Request body exceeds the maximum allowed size" },
+    { name: "ServiceUnavailable", status: 503, number: 1, message: "Service temporarily unavailable",
+      safe_detail: true },
+    { name: "GatewayTimeout", status: 504, number: 1, message: "Timeout", safe_detail: true,
+      aliases: %w[NoResponseError NatsTimeoutError] }
+  ].freeze
+end