problem 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 476a7c373272d8029f0162849ab784ee875af959cbb230b96ebe35d96713fa06
+  data.tar.gz: 17659bc6344e26a107943c95c4d37e3d05b282a4020ca22190ca60d50b89562f
+SHA512:
+  metadata.gz: 82e739ccf9de64bf38e046c84288e34ad9d252f2fd1ebed7d00ed5bdf36658efb7363b778b23644ab69748518fdd305948e9c18faed198464abbb1714914a9c5
+  data.tar.gz: 139c2cd5274e5c57a4b070265a40355455f987622f6df583b7069c8957125240dce027e1d41bff1e5493b502a34d37ee442adbe5f7375f20ee8a3b76e8890e16

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 - 2026-09-22
+
+Initial release.
+
+- `Problem::Detailable` declares an exception class as an RFC 9457 problem, with a
+  class-level `type` / `status` / `title` DSL and a per-occurrence `detail`.
+- `Problem::Rescuable` renders those as `application/problem+json`, with overridable
+  steps for building, reporting and rendering.
+- `Problem::ExceptionsApp` answers exceptions that escape the controller.
+- `Problem::I18nable` looks titles up through I18n.
+- `Problem::RetryAfter` publishes a retry interval as a header and an extension member.

data/DESIGN.md

@@ -0,0 +1,274 @@
+# Design
+
+Why this library is shaped the way it is. [README.md](README.md) covers using it.
+
+Extracted from a production API, where most of these decisions were paid for once
+already.
+
+## The declaration belongs on the error class
+
+The obvious alternative is a central table in `ApplicationController` pairing exception
+classes with statuses. It was rejected for three reasons.
+
+It drifts. The table sits far from the code that raises, so an error added in one place
+and registered in another eventually stops being registered at all.
+
+It makes adding an error a two-file change, which is the kind of friction that produces
+bare `head :forbidden` calls instead.
+
+It has no answer for a subclass that must render exactly as its parent. When telling two
+failures apart would leak something (which factor of an authentication attempt failed,
+whether a record exists at all), the response has to be byte-identical. With the
+declaration inherited, an empty subclass is the entire implementation. With a table, it
+is a second entry that has to be kept in sync by hand.
+
+`class_attribute` is what makes a declaration both inherited and overridable. A constant
+could not be overridden; an ivar on the singleton class would be invisible to subclasses.
+
+## Two halves, because the controller is not always there
+
+`Problem::Rescuable` is a controller concern. A `rescue_from` handler still has the
+controller, so it can reach `request`, the negotiated locale, and whatever a
+`before_action` computed. Middleware sees a Rack env and can do none of that.
+
+But an exception raised before dispatch never reaches a controller at all. A routing
+error, an unreadable body, a failure in another middleware: no `rescue_from` will ever
+run. So `Problem::ExceptionsApp` exists as a separate object, and the two are wired
+independently.
+
+`ExceptionsApp` wraps another exceptions app rather than subclassing
+`ActionDispatch::PublicExceptions`. A wrapper lets each layer of a stack claim the
+requests it recognizes and pass on the rest, which is what makes it composable with, say,
+a Connect RPC exceptions app in front of it:
+
+```ruby
+config.exceptions_app = ConnectExceptions.new(
+  Problem::ExceptionsApp.new(ActionDispatch::PublicExceptions.new(Rails.public_path)),
+)
+```
+
+A subclass can only ever be the innermost layer, and forces whoever wants the JSON branch
+to reimplement the HTML branch they did not want to touch.
+
+Its titles are the status text, never the exception message. A message can quote an id, a
+column name or a path, and this is the one place with no controller to have decided what
+a caller may see.
+
+## The value object
+
+`Problem::Details` is a frozen `Data` with no Rails in it, so building and serializing a
+document needs no controller and no boot.
+
+Extension members merge at the top level because RFC 9457 §3.2 defines them as members of
+the problem object, not a nested container. One that shadowed `status` would contradict
+the HTTP status in the same response, so a collision raises when the value object is
+built rather than at render time inside an error path.
+
+`to_json` is defined explicitly. The generic `Object#to_json` serializes a `Data` as its
+inspect output, which is a plausible-looking response body that no assertion on the
+status code would catch.
+
+Serialization lives in `Problem::Document`, a module written against readers. A `Data`
+cannot gain members by subclassing, so a deployment that wants a *typed* extension member
+defines its own `Data` over the member list:
+
+```ruby
+TracedProblem = Data.define(*Problem::Details.members, :trace_id) do
+  include Problem::Document
+
+  def to_h = super.merge(trace_id:)
+end
+```
+
+Nothing requires `#to_problem` to return a `Problem::Details`. `Problem::Rescuable` calls
+`#status`; the renderer calls `#status` and `#to_json`. That is also how a deployment
+keeps rendering through a serializer it already has.
+
+`Details` is written as a `Data.define` assignment reopened as a class, rather than
+`class Details < Data.define(...)`. Both rubocop and Steep prefer it: the first flags the
+inheritance form, and the second cannot see into a `Data.define` block.
+
+## Type URIs
+
+Resolution happens in `Detailable#to_problem`, not in `Details.new`. That keeps the value
+object pure, so a document built by hand is never rewritten behind the caller's back.
+
+| declared `type` | result |
+|---|---|
+| `nil` | serialized as `about:blank` |
+| `"about:blank"` | returned untouched |
+| carries a scheme | returned untouched, it is already absolute |
+| anything else | prefixed, or left alone when no prefix is set |
+
+`about:blank` is special-cased because prefixing it produces a URI that looks valid and
+identifies nothing, and it is the one `type` value the RFC assigns a meaning to.
+
+Leaving a slug unprefixed is legal: RFC 9457 defines `type` as a URI *reference*, not a
+URI. The prefix exists so sixty error classes do not each repeat an authority, which is
+sixty chances to typo it.
+
+## Plugging in a problem catalogue
+
+A deployment that keeps its problems in a registry (an enum, a YAML file, a table) wants
+type, status and title derived from it. `Problem::I18nable` is the shipped example of the
+simple case, overriding `title` in a `ClassMethods` that sits ahead of the DSL. When the
+catalogue layer is its own concern, prepend a module to the error class's singleton and
+call `super` for anything it does not cover:
+
+```ruby
+module Typeable
+  extend ActiveSupport::Concern
+
+  module Derivation
+    def type(value = nil)
+      return super if value || problem_type.nil?
+
+      CATALOGUE.fetch(problem_type).fetch(:type)
+    end
+  end
+
+  included { singleton_class.prepend(Derivation) }
+end
+```
+
+A prepend rather than a pluggable resolver object. A resolver would bless one catalogue
+shape, add global mutable state, and not compose with inheritance. `prepend` and `super`
+compose for free, and a class that wants a literal declaration simply makes one.
+
+Five things make this work, none of them visible at a call site. They are the real public
+contract of `Problem::Detailable`, and each fails silently rather than loudly:
+
+1. `ClassMethods` is attached with `extend`, so a singleton prepend sits ahead of it.
+2. The signatures stay `status(value = nil)`, `type(value = nil)` and
+   `title(value = nil, interpolations: {})`. The keyword *name* `interpolations:` is
+   load-bearing: a derivation calls `super` with it, and renaming it raises only while
+   rendering an error, in production, on a response that was already an error.
+3. Those three are never defined on the including class itself, only in `ClassMethods`,
+   or the prepend stops winning.
+4. `#to_problem` reaches them through `self.class` rather than reading the class
+   attributes behind them. Reading `problem_uri` directly is a one-word change that
+   disables the whole derivation layer with no error anywhere.
+5. The catalogue layer is included *before* `Problem::Detailable`. Included after, its
+   fallbacks shadow the real DSL and every literal declaration reads back `nil`.
+
+And one more, which is the trap people actually hit: extending a `ClassMethods` onto a
+subclass puts it *ahead* of the prepend its superclass holds. A concern that mixes in a
+catalogue layer has to re-apply the prepend itself, on every inclusion.
+
+`spec/problem/detailable_derivation_spec.rb` builds the whole arrangement and pins it,
+including both silent failure modes. Without that spec the extraction is one refactor
+away from breaking quietly.
+
+### Why I18nable needs none of that ceremony
+
+`Problem::I18nable` overrides the same method and is a plain `ActiveSupport::Concern`,
+with no prepend at all. It gets away with it by declaring `include Detailable` as a
+concern dependency: `ActiveSupport::Concern` then includes `Detailable` first and extends
+`I18nable::ClassMethods` afterwards, which puts it ahead in the singleton ancestry and
+leaves `super` pointing at the literal DSL. Re-including `Detailable` explicitly, in
+either order, changes nothing, because a module already in the ancestry is not moved.
+
+The prepend is only needed when the layer supplies terminal fallbacks of its own, as a
+catalogue concern does. `I18nable` supplies none; it defers to `super`.
+
+`i18n` is not a declared dependency of the gem, so `Problem::I18nable` is autoloaded
+rather than required. A host that never references the constant never loads `i18n`
+through it.
+
+## Rendering
+
+One `rescue_from`, registered against `Problem::Detailable` itself. A Module is matched
+with `===`, so a single registration covers every error class that mixed it in.
+
+The handler is split into named steps so a deployment overrides the one it needs, and so
+a different transport replaces only `#render_problem`. A Connect RPC controller carries
+the document as an error detail and answers in the protocol's own shape; nothing else
+about the handler changes.
+
+### Localization
+
+The gem never calls `I18n`. `around_problem_render` is the seam, and it wraps the whole
+handler rather than just the render for a reason worth writing down:
+`ActionController::Rescue` wraps `AbstractController::Callbacks`, so an `around_action`
+that established the locale has **already unwound** by the time a `rescue_from` handler
+runs. The title lookup happens while the problem is being built, not while it renders, so
+wrapping only the render would miss it.
+
+### Reporting
+
+`rescue_from` swallows the exception. Nothing logs it, and no error reporter's automatic
+capture sees it, which is a quiet way to lose every 5xx an API returns.
+
+Reports go through `ActiveSupport.error_reporter`, the registry Rails error reporters
+subscribe to, rather than naming a vendor. 4xx are not reported: an expected client error
+is not an incident.
+
+## Initialization
+
+A Railtie, because that is what Rails offers for exactly this, instead of an initializer
+every host copies. The same work is a plain `Problem.install!` for a Rack host or a spec
+that never boots Rails, which is how this gem's own suite reaches it.
+
+`problem.config` declares `after: :load_config_initializers`. A railtie initializer
+otherwise runs before `config/initializers` is loaded, which would make
+`config.problem.type_prefix` silently do nothing when set in the file an application
+would most expect to set it in.
+
+The renderer takes the status from the object it is handed and calls `to_json` on it,
+requiring nothing more. That is what lets a deployment render through its own serializer.
+
+The Railtie deliberately does not touch `config.exceptions_app`. Replacing what an
+application set there is not an initializer's business.
+
+## Types
+
+Signatures are inline `#:` annotations generated into `sig/generated`, which is checked
+in. CI asserts it is current with `git diff --exit-code`, because an annotation can change
+without anyone running `rake rbs`, and a stale signature means the type check is checking
+a shape the code no longer has.
+
+`sig/manual` holds what inline annotations cannot express:
+
+* the self-type of a mix-in, since `Problem::Rescuable` needs `render` and `response` from
+  whatever controller it lands in, and `Problem::Detailable` needs its own class-level DSL;
+* the accessors `class_attribute` installs at runtime;
+* `Problem::Details`, since a `Data.define` assignment has no inferable shape;
+* a `Data#initialize` stub, because core RBS declares none and a subclass overriding it
+  has nothing to call `super` on.
+
+Three DSL blocks are marked `steep:ignore`: `included do`, and the renderer registration.
+Their `self` is supplied by Rails at runtime and cannot be named in RBS. `class_methods do`
+was avoided entirely in favour of a nested `ClassMethods` module, which is ordinary code
+that Steep can check and which `ActiveSupport::Concern` picks up by name.
+
+## Layout
+
+```
+lib/problem/document.rb        to_h / as_json / to_json, and the media type
+lib/problem/details.rb         the value object
+lib/problem/detailable.rb      the class-level DSL, and #to_problem
+lib/problem/i18nable.rb        titles from I18n, autoloaded
+lib/problem/retry_after.rb     Retry-After, as a worked example of the hooks
+lib/problem/rescuable.rb       rescue_from, split into overridable steps
+lib/problem/exceptions_app.rb  the config.exceptions_app wrapper
+lib/problem/renderer.rb        the application/problem+json renderer
+lib/problem/railtie.rb         required only when Rails is present
+sig/manual/                    what RBS cannot infer
+```
+
+## Deliberately out of scope
+
+* A catalogue of problem types, and anything that reads one. The seam is above.
+* `Accept-Language` negotiation. `Problem::I18nable` translates a title once a locale is
+  set; choosing that locale is the application's job, and `around_problem_render` is
+  where it plugs in.
+* Validation-error serialization. RFC 9457 defines no `errors` member; use an extension.
+* `application/problem+xml`.
+* Anything Connect or gRPC. `render_problem` is the seam, and
+  [connect_rpc_rails](https://github.com/ivry-inc/connect_rpc_rails) is the other half.
+
+## A note on the name
+
+The top-level constant is `Problem`, generic enough to collide with a `Problem` model in
+a host application. Nothing here reopens or autoloads anything outside `Problem::`, but
+under Zeitwerk a same-named application constant is a conflict you would have to resolve.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Sorah Fukumori
+
+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,328 @@
+# problem: RFC 9457 Problem Details for Rails APIs
+
+`problem` renders the errors a Rails API raises as
+[RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html) problem details. An error class
+declares its type, title and status once, next to the code that raises it, and a
+controller concern turns any of them into an `application/problem+json` response. A
+companion exceptions app covers what Rails raises before your controller runs, so a
+routing error and a business rule violation come back in the same shape.
+
+```ruby
+class Errors::Forbidden < Errors::ApiError
+  type "forbidden"
+  status 403
+  title "Forbidden"
+end
+
+raise Errors::Forbidden.new(detail: "Only the owner can cancel this order")
+```
+
+```console
+$ curl -i https://api.example.com/orders/1/cancel
+HTTP/1.1 403 Forbidden
+Content-Type: application/problem+json
+
+{"type":"forbidden","title":"Forbidden","status":403,"detail":"Only the owner can cancel this order"}
+```
+
+## Features
+
+- **One place per error.** Status, title and type live on the class, not in a mapping
+  table that drifts away from the code raising it.
+- **Stable identifiers for clients.** Callers dispatch on `type`, so you can reword a
+  title without breaking them.
+- **Covers what the controller never sees.** Routing errors, unreadable bodies and
+  middleware failures render as problem documents too, carrying the status text rather
+  than the exception message.
+- **Localized titles**, keyed by type, with a one-line include.
+- **Small.** Two mixins, an exceptions app and a renderer. Under 250 lines of code, and
+  `actionpack` is the only dependency.
+- **Typed.** RBS signatures ship with the gem.
+
+## Requirements
+
+Ruby 3.3 or later, and `actionpack` 7.0 or later. `Problem::I18nable` additionally needs
+the `i18n` gem, which Rails already brings.
+
+## Installation
+
+```
+bundle add problem
+```
+
+Rails wires itself up through a railtie. Add an initializer for the URI prefix your type
+identifiers live under:
+
+```ruby
+# config/initializers/problem.rb
+Rails.application.configure do
+  config.problem.type_prefix = "https://api-probs.example.com/"
+end
+```
+
+`config/application.rb` and the environment files work too.
+
+Outside Rails, call `Problem.install!` at boot and configure it with
+`Problem.configure { |c| c.type_prefix = "..." }`.
+
+## Getting started
+
+### 1. Give your errors a common base
+
+```ruby
+# app/models/errors.rb
+module Errors
+  class ApiError < StandardError
+    include Problem::Detailable
+  end
+
+  class BadRequest < ApiError
+    type "bad-request"
+    status 400
+    title "Bad Request"
+  end
+
+  class Unauthorized < ApiError
+    type "unauthorized"
+    status 401
+    title "Unauthorized"
+  end
+
+  class Forbidden < ApiError
+    type "forbidden"
+    status 403
+    title "Forbidden"
+  end
+
+  class NotFound < ApiError
+    type "not-found"
+    status 404
+    title "Not Found"
+  end
+end
+```
+
+One base class carrying the concern is enough. Everything under it inherits the
+declaration and overrides only what differs.
+
+### 2. Rescue them once
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::API
+  include Problem::Rescuable
+end
+```
+
+### 3. Raise them
+
+```ruby
+raise Errors::NotFound unless @order
+
+raise Errors::Forbidden.new(detail: "Only the owner can cancel this order")
+```
+
+`detail` is the part that differs between two occurrences of the same problem. Everything
+else belongs to the class, so it is declared once.
+
+## Defining your own errors
+
+Inherit from the closest base and declare what changes:
+
+```ruby
+class Orders::AlreadyShipped < Errors::UnprocessableContent
+  type "order-already-shipped"
+  title "Order Already Shipped"
+end
+```
+
+A subclass that declares nothing renders exactly as its parent:
+
+```ruby
+class Errors::ConfidentialClientRequired < Errors::Unauthorized; end
+```
+
+That is worth knowing deliberately. When a caller must not be able to tell two failures
+apart, an empty subclass is the whole implementation.
+
+## Localized titles
+
+`title` is the only member written for a human, so it is the only one worth translating.
+Include `Problem::I18nable` in your base class:
+
+```ruby
+module Errors
+  class ApiError < StandardError
+    include Problem::I18nable
+  end
+end
+```
+
+```yaml
+# config/locales/en.yml
+en:
+  problem_details:
+    titles:
+      not_found: "Not Found"
+      forbidden: "Forbidden"
+```
+
+Titles are keyed by the declared type with dashes replaced, under
+`problem_details.titles`. Both are adjustable:
+
+```ruby
+class Errors::ApiError < StandardError
+  include Problem::I18nable
+
+  title_scope "errors.titles"      # inherited by subclasses
+end
+
+class Errors::NotFound < Errors::ApiError
+  type "gone-missing"
+  status 404
+  title_key :not_found             # when the key should not follow the type
+end
+```
+
+`Problem::I18nable` brings `Problem::Detailable` with it, so one include covers both. A
+class that spells out a literal `title` keeps it, which lets a codebase move over
+gradually.
+
+Then establish the locale around rendering:
+
+```ruby
+class ApplicationController < ActionController::API
+  include Problem::Rescuable
+
+  private def around_problem_render(&) = I18n.with_locale(negotiated_locale, &)
+end
+```
+
+That wrapper is not optional if you localize. Rails has already unwound your
+`around_action` by the time an error renders, so the locale has to be re-established
+here. [DESIGN.md](DESIGN.md#localization) explains why.
+
+## Catching what escapes the controller
+
+A routing error, an unreadable request body or a failure in middleware never reaches a
+controller, so `Problem::Rescuable` never sees it. Wire up the exceptions app:
+
+```ruby
+# config/initializers/problem.rb
+Rails.application.configure do
+  config.exceptions_app = Problem::ExceptionsApp.new(
+    ActionDispatch::PublicExceptions.new(Rails.public_path),
+  )
+end
+```
+
+Browsers keep getting the static error pages. Everything else gets a problem document,
+with the status Rails already mapped the exception to.
+
+## Error reporting
+
+5xx problems are reported through `ActiveSupport.error_reporter`, which Sentry and similar
+gems subscribe to. 4xx are not, on the grounds that an expected client error is not an
+incident. Both are overridable:
+
+```ruby
+private def report_problem(error, _problem) = Sentry.capture_exception(error)
+
+private def report_problem?(_error, problem) = problem.status >= 500
+```
+
+## Telling clients when to retry
+
+```ruby
+class Errors::TooManyRequests < Errors::ApiError
+  include Problem::RetryAfter
+
+  type "too-many-requests"
+  status 429
+  title "Try again in %{retry_after} seconds"
+end
+
+raise Errors::TooManyRequests.new(retry_after: 30)
+```
+
+Sends a `Retry-After` header, interpolates the wait into the title, and adds a
+`retry_after` member to the body. A `Time` works in place of seconds.
+
+## Extension members
+
+RFC 9457 lets a problem carry extra top-level members. Return them from the occurrence:
+
+```ruby
+class Orders::PaymentDeclined < Errors::UnprocessableContent
+  type "payment-declined"
+  title "Payment Declined"
+
+  def problem_extensions = {decline_code: "insufficient_funds"}
+end
+```
+
+```json
+{"type":"payment-declined","title":"Payment Declined","status":422,"decline_code":"insufficient_funds"}
+```
+
+To fill `instance`, which identifies the occurrence rather than the type, use the request:
+
+```ruby
+private def problem_for(error) = error.to_problem.with(instance: request.fullpath)
+```
+
+## Reference
+
+Members of the rendered document:
+
+| member | set by | notes |
+|---|---|---|
+| `type` | `type "slug"` | Resolved against `type_prefix`. Defaults to `about:blank`. |
+| `title` | `title "..."`, or `Problem::I18nable` | Short, human readable, constant for the type. |
+| `status` | `status 403` | Always matches the HTTP status. |
+| `detail` | `new(detail:)` | Specific to the occurrence. Omitted when absent. |
+| `instance` | `problem_instance` | Omitted when absent. |
+| anything else | `problem_extensions` | Serialized as top-level members. |
+
+Hooks on a controller including `Problem::Rescuable`:
+
+| hook | for |
+|---|---|
+| `problem_for(error)` | Adding `instance`, a request id, anything request-derived |
+| `around_problem_render(&)` | Locale, or other per-request state the handler needs |
+| `report_problem?(error, problem)` | What counts as reportable |
+| `report_problem(error, problem)` | Where reports go |
+| `render_problem(problem, error)` | Answering in a different shape entirely |
+
+## Caveats
+
+- The top-level constant is `Problem`. Under Zeitwerk, an application with its own
+  `Problem` model has a conflict to resolve.
+- `i18n` is not a declared dependency. `Problem::I18nable` is autoloaded, so a host that
+  never references it never loads it.
+- RFC 9457 defines no member for field-level validation errors. Use an extension member.
+- `application/problem+xml` is not implemented.
+
+## Development
+
+```
+bundle install
+bundle exec rake      # specs, then rbs and steep
+hk check --all        # rubocop, actionlint, zizmor
+hk install            # run the linters on commit
+```
+
+## See also
+
+- [DESIGN.md](DESIGN.md) for why the library is shaped this way, and how to derive
+  declarations from a problem catalogue of your own.
+- [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html), the format itself.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/sorah/problem.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT). Copyright (c) 2026 Sorah Fukumori.