problem 0.1.0

data/lib/problem/detailable.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "active_support/concern"
+require "active_support/core_ext/class/attribute"
+require "problem/details"
+
+module Problem
+  # Declares an exception class as an RFC 9457 problem.
+  #
+  #   class InsufficientBalance < StandardError
+  #     include Problem::Detailable
+  #
+  #     type "insufficient-balance"
+  #     status 403
+  #     title "Insufficient Balance"
+  #   end
+  #
+  #   raise InsufficientBalance.new(detail: "Required: 100, Available: 50")
+  #
+  # This holds only what RFC 9457 defines: a type, a title, a status, a per-occurrence
+  # detail, and the conversion to Problem::Details. Each is declared literally, which is
+  # all a deployment needs to render an error.
+  #
+  # A deployment that keeps a catalogue of its problems — a registry, an enum, a locale
+  # file — derives those three from it instead, by prepending a module to the error
+  # class's singleton that overrides `type`, `status` and `title` and calls `super` for a
+  # class the catalogue does not cover. Three things make that work and none of them are
+  # visible at the call site: ClassMethods is attached with `extend`, so a singleton
+  # prepend sits ahead of it; the gem never defines those three on the including class
+  # itself; and #to_problem reaches them through `self.class` rather than reading the
+  # class attributes behind them.
+  #
+  # @rbs module-self ::Exception
+  # @rbs module-self _DetailableSelf
+  module Detailable
+    extend ActiveSupport::Concern
+
+    # The occurrence's own explanation, which RFC 9457 §3.1 defines as specific to this
+    # occurrence rather than to the problem type.
+    attr_reader :detail #: String?
+
+    # `self` inside an ActiveSupport::Concern block is the including class, which RBS has
+    # no way to name; the accessors these install are declared in sig/manual instead.
+    # steep:ignore:start
+    included do
+      class_attribute :problem_status, instance_accessor: false
+      class_attribute :problem_title, instance_accessor: false
+      class_attribute :problem_uri, instance_accessor: false
+      class_attribute :problem_type_prefix, instance_accessor: false
+    end
+    # steep:ignore:end
+
+    # Extended into the including class by ActiveSupport::Concern, which picks up a nested
+    # ClassMethods by name. Written as a module rather than a `class_methods` block so the
+    # body is ordinary code that RBS can describe.
+    #
+    # @rbs module-self _DetailableClass
+    module ClassMethods
+      # Each reader doubles as its own setter so a subclass can override one declaration
+      # and inherit the rest, which is what class_attribute buys over a constant.
+      #: (?Integer?) -> Integer?
+      def status(value = nil)
+        value ? self.problem_status = value : problem_status
+      end
+
+      # The identifier this class publishes, resolved against the type prefix when the
+      # occurrence is converted.
+      #: (?String?) -> String?
+      def type(value = nil)
+        value ? self.problem_uri = value : problem_uri
+      end
+
+      # `interpolations` is part of the signature even though a literal title rarely needs
+      # it: a catalogue-backed override reads a template, and this is where the occurrence
+      # hands it the values.
+      #: (?String?, ?interpolations: Hash[Symbol, untyped]) -> String?
+      def title(value = nil, interpolations: {})
+        return self.problem_title = value if value
+
+        template = problem_title
+        return template if template.nil? || interpolations.empty?
+
+        template % interpolations
+      end
+
+      # Falls back to the global setting, so a deployment declares its authority once.
+      #: (?String?) -> String?
+      def type_prefix(value = nil)
+        return self.problem_type_prefix = value if value
+
+        problem_type_prefix || Problem.config.type_prefix
+      end
+    end
+
+    # Intercepts `detail:` and forwards everything else to the exception, so
+    # `raise Klass, "message"` keeps working.
+    #: (*untyped, ?detail: String?, **untyped) -> void
+    def initialize(*args, detail: nil, **kwargs)
+      @detail = detail #: String?
+      super(*args, **kwargs)
+    end
+
+    # Values the title template interpolates for this occurrence.
+    #: () -> Hash[Symbol, untyped]
+    def title_interpolations = {}
+
+    # Extension members this occurrence publishes alongside the RFC 9457 ones.
+    #: () -> Hash[Symbol, untyped]
+    def problem_extensions = {}
+
+    # A URI identifying this occurrence, which only the caller's request can supply.
+    #: () -> String?
+    def problem_instance = nil
+
+    # Response headers this occurrence needs, applied by Problem::Rescuable.
+    #: () -> Hash[String, String]
+    def problem_headers = {}
+
+    # This occurrence as an RFC 9457 document.
+    #: () -> Details
+    def to_problem
+      status = self.class.status
+      raise ArgumentError, "#{self.class} declares no problem status" if status.nil?
+
+      Details.new(
+        type: Problem.type_uri(self.class.type, prefix: self.class.type_prefix),
+        title: self.class.title(interpolations: title_interpolations),
+        status: status,
+        detail: detail,
+        instance: problem_instance,
+        extensions: problem_extensions,
+      )
+    end
+  end
+end

data/lib/problem/details.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "problem/document"
+
+module Problem
+  # The members of an RFC 9457 problem document, plus the extension members a problem
+  # adds to them. Behaviour is defined on the reopening below.
+  Details = Data.define(:type, :title, :status, :detail, :instance, :extensions)
+
+  # An RFC 9457 problem document as a value object.
+  #
+  # `type` is stored verbatim: resolving a declared slug against a prefix is
+  # Problem::Detailable's job, so a Details built by hand is never rewritten.
+  #
+  # Reopened rather than customized in a `Data.define` block, so the body is an ordinary
+  # class body that RBS can describe and Steep can check.
+  class Details
+    include Document
+
+    # `status` is required and must be the HTTP status of the response carrying it;
+    # every other member is optional, and `extensions` holds the members RFC 9457 §3.2
+    # lets a problem add.
+    #: (status: Integer, ?type: String?, ?title: String?, ?detail: String?, ?instance: String?, ?extensions: Hash[untyped, untyped]) -> void
+    def initialize(status:, type: nil, title: nil, detail: nil, instance: nil, extensions: {})
+      raise ArgumentError, "status must be an Integer, got #{status.class}" unless status.is_a?(Integer)
+
+      super(type:, title:, status:, detail:, instance:, extensions: sanitized_extensions(extensions))
+    end
+
+    # An extension that shadowed `status` would contradict the HTTP status in the same
+    # response, so a collision is refused here rather than at render time.
+    private def sanitized_extensions(extensions)
+      sanitized = extensions.to_h { |key, value| [key.to_sym, value] }
+      collisions = sanitized.keys & Document::MEMBERS
+
+      unless collisions.empty?
+        raise ArgumentError, "extension members shadow RFC 9457 members: #{collisions.join(", ")}"
+      end
+
+      sanitized.freeze
+    end
+  end
+end

data/lib/problem/document.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "json"
+
+module Problem
+  # Serializes an RFC 9457 problem document.
+  #
+  # Included by Problem::Details, and by any value object that carries the same readers —
+  # the way to add typed members is to define a Data over Problem::Details.members rather
+  # than to subclass Details, which cannot gain members.
+  #
+  # @rbs module-self _Document
+  module Document
+    # The members RFC 9457 §3.1 defines, in the order they are serialized.
+    MEMBERS = %i[type title status detail instance].freeze #: Array[Symbol]
+
+    # The type of a problem that says nothing beyond its HTTP status (RFC 9457 §4.2.1).
+    ABOUT_BLANK = "about:blank" #: String
+
+    # The media type a problem document is served as (RFC 9457 §3).
+    CONTENT_TYPE = "application/problem+json" #: String
+
+    # Extension members are members of the problem object itself, not a nested container,
+    # so they merge at the top level. An absent member is omitted rather than sent as null.
+    #: () -> Hash[Symbol, untyped]
+    def to_h
+      {
+        type: type || ABOUT_BLANK,
+        title: title,
+        status: status,
+        detail: detail,
+        instance: instance,
+      }.reject { |_, value| value.nil? || value == "" }.merge(extensions)
+    end
+
+    # The document with string keys, so a member whose value knows how to render itself
+    # gets the chance before JSON.generate sees it.
+    #: (?untyped) -> Hash[String, untyped]
+    def as_json(options = nil)
+      to_h.to_h { |key, value| [key.to_s, value.respond_to?(:as_json) ? value.as_json(options) : value] }
+    end
+
+    # Defined explicitly because the generic Object#to_json would serialize the Data's
+    # inspect output, which looks like a response body until someone reads one.
+    #: (*untyped) -> String
+    def to_json(*) = JSON.generate(as_json)
+  end
+end

data/lib/problem/exceptions_app.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "action_dispatch"
+require "action_dispatch/middleware/exception_wrapper"
+require "problem/detailable"
+require "problem/details"
+
+module Problem
+  # Answers an exception that escaped the controller — a routing error, an unreadable
+  # body, a failure in middleware — as application/problem+json. Nothing else sees those:
+  # they are raised before dispatch, so no controller rescue_from ever runs.
+  #
+  #   config.exceptions_app = Problem::ExceptionsApp.new(
+  #     ActionDispatch::PublicExceptions.new(Rails.public_path),
+  #   )
+  #
+  # A wrapper rather than an ActionDispatch::PublicExceptions subclass, so each layer of a
+  # deployment's stack claims the requests it recognizes and passes on the rest; a
+  # subclass can only ever be the innermost one.
+  class ExceptionsApp
+    # Wraps the exceptions app to fall back to, which keeps whatever it already answers
+    # for the requests this one does not claim.
+    #: (untyped app) -> void
+    def initialize(app)
+      @app = app
+    end
+
+    # Answers with a problem document, or hands the request to the wrapped app.
+    #: (Hash[String, untyped]) -> [Integer, Hash[String, String], Array[String]]
+    def call(env)
+      exception = env["action_dispatch.exception"]
+      return @app.call(env) if exception.nil? || html?(env)
+
+      render_problem(problem_for(exception, env))
+    end
+
+    # Browser traffic keeps getting the wrapped app's static error pages.
+    #: (Hash[String, untyped]) -> bool
+    private def html?(env)
+      ActionDispatch::Request.new(env).formats.first&.html? || false
+    rescue ActionDispatch::Http::MimeNegotiation::InvalidType
+      false
+    end
+
+    # The problem to send for an escaped exception. The title is the status's own text,
+    # never the exception's message, which can quote internals.
+    #
+    # Override to publish a type: a deployment with a catalogue of problems maps the
+    # status onto it here, so every identifier a client can see comes from one place.
+    #: (Exception, Hash[String, untyped]) -> Details
+    private def problem_for(exception, env)
+      return exception.to_problem if exception.is_a?(Detailable)
+
+      # Read the way ActionDispatch::PublicExceptions reads it, so `rescue_responses` stays
+      # the one place the application classifies an exception.
+      status = ActionDispatch::ExceptionWrapper.new(
+        env["action_dispatch.backtrace_cleaner"], exception
+      ).status_code
+
+      Details.new(status: status, title: Rack::Utils::HTTP_STATUS_CODES.fetch(status, "Error"))
+    end
+
+    #: (Details) -> [Integer, Hash[String, String], Array[String]]
+    private def render_problem(problem)
+      body = problem.to_json
+
+      [
+        problem.status,
+        {"content-type" => Document::CONTENT_TYPE, "content-length" => body.bytesize.to_s},
+        [body],
+      ]
+    end
+  end
+end

data/lib/problem/i18nable.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "i18n"
+require "active_support/concern"
+require "problem/detailable"
+
+module Problem
+  # Looks a problem's title up through I18n instead of declaring it in Ruby.
+  #
+  #   class ApiError < StandardError
+  #     include Problem::I18nable
+  #   end
+  #
+  #   class NotFound < ApiError
+  #     type "not-found"
+  #     status 404
+  #   end
+  #
+  #   en:
+  #     problem_details:
+  #       titles:
+  #         not_found: "Not Found"
+  #
+  # Titles are keyed by the declared type, dashes replaced, so two classes publishing one
+  # type publish one title as well. That is what keeps a subclass written to be
+  # indistinguishable from its parent indistinguishable in the title too.
+  #
+  # A class that declares a literal title keeps it, so a codebase can move over gradually.
+  #
+  # i18n is not a declared dependency of this gem. Referencing this module is opting in,
+  # and it is autoloaded so that a host which never does pays nothing for it.
+  #
+  # @rbs module-self ::Exception
+  # @rbs module-self _DetailableSelf
+  module I18nable
+    extend ActiveSupport::Concern
+
+    # Brings the DSL this overrides, and orders the two so `super` reaches it whichever
+    # way round a class mixes them in.
+    include Detailable
+
+    # Where titles live unless a class says otherwise.
+    DEFAULT_SCOPE = "problem_details.titles" #: String
+
+    # steep:ignore:start
+    included do
+      class_attribute :problem_title_scope, instance_accessor: false
+      class_attribute :problem_title_key, instance_accessor: false
+    end
+    # steep:ignore:end
+
+    # @rbs module-self _I18nableClass
+    module ClassMethods
+      # The I18n scope titles are looked up under.
+      #: (?String?) -> String
+      def title_scope(value = nil)
+        return self.problem_title_scope = value if value
+
+        problem_title_scope || DEFAULT_SCOPE
+      end
+
+      # The key within that scope, derived from the declared type unless it is set.
+      #: (?(String | Symbol)?) -> String?
+      def title_key(value = nil)
+        return self.problem_title_key = value.to_s if value
+
+        problem_title_key || type&.tr("-", "_")
+      end
+
+      # Falls through to the literal DSL for a class that declares a title of its own, or
+      # that has no type to build a key from.
+      #: (?String?, ?interpolations: Hash[Symbol, untyped]) -> String?
+      def title(value = nil, interpolations: {})
+        return super if value || problem_title
+
+        key = title_key
+        return super if key.nil?
+
+        I18n.t(key, scope: title_scope, **interpolations)
+      end
+    end
+  end
+end

data/lib/problem/railtie.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "rails/railtie"
+
+module Problem
+  # Wires the gem into a Rails application on boot.
+  #
+  #   config.problem.type_prefix = "https://api-probs.example.com/"
+  #
+  # config.exceptions_app is deliberately left alone: replacing what an application set
+  # there is not an initializer's business, so Problem::ExceptionsApp is wired by hand.
+  class Railtie < ::Rails::Railtie
+    config.problem = ActiveSupport::OrderedOptions.new
+
+    # After config/initializers, so the prefix can be set there as well as in
+    # config/application.rb and the environment files.
+    initializer("problem.config", after: :load_config_initializers) do |app|
+      prefix = app.config.problem.type_prefix
+      Problem.config.type_prefix = prefix if prefix
+    end
+
+    initializer("problem.renderer") { Problem.install! }
+  end
+end

data/lib/problem/renderer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "action_controller"
+require "problem/document"
+
+module Problem
+  # Registers the application/problem+json media type and the `problem:` renderer.
+  #
+  #   render problem: error.to_problem
+  #
+  # Installed by Problem::Railtie on boot; a Rack host or a spec that never boots Rails
+  # calls Problem.install! itself.
+  module Renderer
+    # Renders whatever it is handed, so a deployment can pass its own serializer's object
+    # rather than a Problem::Details as long as it answers #status and #to_json.
+    #: () -> void
+    def self.install!
+      Mime::Type.register(Document::CONTENT_TYPE, :problem) unless Mime[:problem]
+
+      # `self` in a renderer block is the controller instance, which RBS cannot name here.
+      # steep:ignore:start
+      ActionController::Renderers.add(:problem) do |problem, options|
+        self.content_type = Mime[:problem]
+        self.status = options[:status] || problem.status
+        problem.to_json
+      end
+      # steep:ignore:end
+    end
+  end
+end

data/lib/problem/rescuable.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "active_support"
+require "active_support/concern"
+require "problem/detailable"
+
+module Problem
+  # Renders any Problem::Detailable a controller raises as application/problem+json.
+  #
+  #   class ApplicationController < ActionController::API
+  #     include Problem::Rescuable
+  #   end
+  #
+  # One registration covers every error class that mixed Problem::Detailable in, because
+  # rescue_from matches a Module with ===.
+  #
+  # Each step is its own method, so a deployment overrides the one it needs and a
+  # different transport — a Connect RPC error, say — replaces only #render_problem.
+  #
+  # @rbs module-self _RescuableSelf
+  module Rescuable
+    extend ActiveSupport::Concern
+
+    # steep:ignore:start
+    included do
+      rescue_from Problem::Detailable, with: :render_problem_detailable
+    end
+    # steep:ignore:end
+
+    #: (detailable_error) -> void
+    private def render_problem_detailable(error)
+      around_problem_render do
+        problem = problem_for(error)
+        report_problem(error, problem) if report_problem?(error, problem)
+        apply_problem_headers(error)
+        render_problem(problem, error)
+      end
+    end
+
+    # Wraps building, reporting and rendering. Override to re-establish per-request state
+    # that has already unwound: ActionController::Rescue wraps
+    # AbstractController::Callbacks, so an around_action is gone by the time a rescue_from
+    # handler runs, and #problem_for may read a translation.
+    #
+    #   private def around_problem_render(&) = I18n.with_locale(negotiated_locale, &)
+    #
+    #: () { () -> void } -> void
+    private def around_problem_render = yield
+
+    # Override to fill members only the request can supply, such as `instance`.
+    #: (detailable_error) -> Details
+    private def problem_for(error) = error.to_problem
+
+    # A client error the API expected is not an incident; a server-side failure is.
+    #: (detailable_error, Details) -> bool
+    private def report_problem?(_error, problem) = problem.status >= 500
+
+    # A rescue_from handler swallows the exception, so nothing logs it and no error
+    # reporter sees it. Reported through the registry Rails error reporters subscribe to,
+    # rather than to a particular one.
+    #: (detailable_error, Details) -> void
+    private def report_problem(error, _problem)
+      ActiveSupport.error_reporter.report(error, handled: true, severity: :error, source: "problem")
+    end
+
+    #: (detailable_error) -> void
+    private def apply_problem_headers(error)
+      headers = error.problem_headers
+      response.headers.merge!(headers) unless headers.empty?
+    end
+
+    # The only transport-specific step.
+    #: (Details, detailable_error) -> void
+    private def render_problem(problem, _error) = render(problem: problem)
+  end
+end

data/lib/problem/retry_after.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "problem/detailable"
+
+module Problem
+  # Publishes when a rejected request may be retried, as a Retry-After response header
+  # (RFC 9110 §10.2.3) and a `retry_after` extension member carrying the same seconds.
+  #
+  # Mixed in after Problem::Detailable, whose hooks it extends rather than replaces:
+  #
+  #   class Throttled < StandardError
+  #     include Problem::Detailable
+  #     include Problem::RetryAfter
+  #
+  #     status 429
+  #     title "Try again in %{retry_after} seconds"
+  #   end
+  #
+  #   raise Throttled.new(retry_after: 30)
+  #
+  # @rbs module-self Detailable
+  module RetryAfter
+    # The response header the wait is published in.
+    HEADER = "Retry-After" #: String
+
+    # Seconds to wait, or the Time to wait until.
+    attr_reader :retry_after #: (Integer | Time)
+
+    # Takes the wait as seconds or as the Time to wait until, and forwards the rest.
+    #: (*untyped, retry_after: (Integer | Time), **untyped) -> void
+    def initialize(*args, retry_after:, **kwargs)
+      @retry_after = retry_after #: (Integer | Time)
+      super(*args, **kwargs)
+    end
+
+    # A deadline that has already passed is published as 0 rather than as a negative wait.
+    #: () -> Integer
+    def retry_after_seconds
+      value = retry_after
+      value.is_a?(Time) ? [(value - Time.now).ceil, 0].max : value.to_i
+    end
+
+    # Adds the wait, so a title template can name it.
+    #: () -> Hash[Symbol, untyped]
+    def title_interpolations = super.merge(retry_after: retry_after_seconds)
+
+    # Publishes the wait in the document as a `retry_after` extension member.
+    #: () -> Hash[Symbol, untyped]
+    def problem_extensions = super.merge(retry_after: retry_after_seconds)
+
+    # Publishes the wait as a Retry-After header, which a generic HTTP client obeys.
+    #: () -> Hash[String, String]
+    def problem_headers = super.merge(HEADER => retry_after_seconds.to_s)
+  end
+end

data/lib/problem/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+module Problem
+  # The gem's version.
+  VERSION = "0.1.0" #: String
+end

data/lib/problem.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copyright 2026 Sorah Fukumori
+# SPDX-License-Identifier: MIT
+
+require "problem/version"
+require "problem/document"
+require "problem/details"
+require "problem/detailable"
+require "problem/retry_after"
+require "problem/rescuable"
+require "problem/exceptions_app"
+
+# RFC 9457 Problem Details for HTTP APIs.
+module Problem
+  # Autoloaded because it is the one part of the gem that needs i18n, which is not a
+  # declared dependency.
+  autoload :I18nable, "problem/i18nable"
+
+  # Anything a deployment sets once, rather than per error class.
+  class Configuration
+    # Resolves a declared type slug into the URI a client dispatches on, so an error class
+    # names `"bad-request"` instead of repeating the deployment's authority. Left unset,
+    # a slug goes out as-is, which RFC 9457 allows: `type` is a URI reference.
+    attr_accessor :type_prefix #: String?
+  end
+
+  # A URI reference carrying a scheme is already absolute (RFC 3986 §3.1).
+  ABSOLUTE_URI = /\A[a-zA-Z][a-zA-Z0-9+.\-]*:/ #: Regexp
+
+  # @rbs self.@config: Configuration?
+
+  # The settings in effect, created on first use.
+  #: () -> Configuration
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  # Yields the settings, for a host that is not a Rails application.
+  #
+  #   Problem.configure { |c| c.type_prefix = "https://api-probs.example.com/" }
+  #
+  #: () { (Configuration) -> void } -> void
+  def self.configure
+    yield(config)
+  end
+
+  # Registers the application/problem+json media type and the `problem:` renderer. Called
+  # by Problem::Railtie on boot; a Rack host or a spec that never boots Rails calls it.
+  #: () -> void
+  def self.install!
+    require "problem/renderer"
+    Renderer.install!
+  end
+
+  # The type URI a declared value publishes. `about:blank` and anything already absolute
+  # are returned untouched — prefixing `about:blank` would produce a URI that looks valid
+  # and means nothing.
+  #: (String?, ?prefix: String?) -> String?
+  def self.type_uri(value, prefix: config.type_prefix)
+    return if value.nil?
+    return value if value == Document::ABOUT_BLANK || value.match?(ABSOLUTE_URI)
+
+    prefix ? "#{prefix}#{value}" : value
+  end
+end
+
+require "problem/railtie" if defined?(Rails::Railtie)