problem 0.1.0

data/sig/generated/problem/detailable.rbs

@@ -0,0 +1,90 @@
+# Generated from lib/problem/detailable.rb with RBS::Inline
+
+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 : ::Exception, _DetailableSelf
+    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?
+
+    # 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 : _DetailableClass
+      # 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: (?Integer?) -> Integer?
+
+      # The identifier this class publishes, resolved against the type prefix when the
+      # occurrence is converted.
+      # : (?String?) -> String?
+      def type: (?String?) -> String?
+
+      # `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: (?String?, ?interpolations: Hash[Symbol, untyped]) -> String?
+
+      # Falls back to the global setting, so a deployment declares its authority once.
+      # : (?String?) -> String?
+      def type_prefix: (?String?) -> String?
+    end
+
+    # Intercepts `detail:` and forwards everything else to the exception, so
+    # `raise Klass, "message"` keeps working.
+    # : (*untyped, ?detail: String?, **untyped) -> void
+    def initialize: (*untyped, ?detail: String?, **untyped) -> void
+
+    # Values the title template interpolates for this occurrence.
+    # : () -> Hash[Symbol, untyped]
+    def title_interpolations: () -> Hash[Symbol, untyped]
+
+    # Extension members this occurrence publishes alongside the RFC 9457 ones.
+    # : () -> Hash[Symbol, untyped]
+    def problem_extensions: () -> Hash[Symbol, untyped]
+
+    # A URI identifying this occurrence, which only the caller's request can supply.
+    # : () -> String?
+    def problem_instance: () -> String?
+
+    # Response headers this occurrence needs, applied by Problem::Rescuable.
+    # : () -> Hash[String, String]
+    def problem_headers: () -> Hash[String, String]
+
+    # This occurrence as an RFC 9457 document.
+    # : () -> Details
+    def to_problem: () -> Details
+  end
+end

data/sig/generated/problem/document.rbs

@@ -0,0 +1,36 @@
+# Generated from lib/problem/document.rb with RBS::Inline
+
+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 : _Document
+    # The members RFC 9457 §3.1 defines, in the order they are serialized.
+    MEMBERS: Array[Symbol]
+
+    # The type of a problem that says nothing beyond its HTTP status (RFC 9457 §4.2.1).
+    ABOUT_BLANK: String
+
+    # The media type a problem document is served as (RFC 9457 §3).
+    CONTENT_TYPE: 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: () -> Hash[Symbol, untyped]
+
+    # 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: (?untyped) -> Hash[String, untyped]
+
+    # 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: (*untyped) -> String
+  end
+end

data/sig/generated/problem/exceptions_app.rbs

@@ -0,0 +1,40 @@
+# Generated from lib/problem/exceptions_app.rb with RBS::Inline
+
+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: (untyped app) -> void
+
+    # Answers with a problem document, or hands the request to the wrapped app.
+    # : (Hash[String, untyped]) -> [Integer, Hash[String, String], Array[String]]
+    def call: (Hash[String, untyped]) -> [ Integer, Hash[String, String], Array[String] ]
+
+    # Browser traffic keeps getting the wrapped app's static error pages.
+    # : (Hash[String, untyped]) -> bool
+    private def html?: (Hash[String, untyped]) -> bool
+
+    # 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, Hash[String, untyped]) -> Details
+
+    # : (Details) -> [Integer, Hash[String, String], Array[String]]
+    private def render_problem: (Details) -> [ Integer, Hash[String, String], Array[String] ]
+  end
+end

data/sig/generated/problem/i18nable.rbs

@@ -0,0 +1,55 @@
+# Generated from lib/problem/i18nable.rb with RBS::Inline
+
+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 : ::Exception, _DetailableSelf
+    extend ActiveSupport::Concern
+
+    include Detailable
+
+    # Where titles live unless a class says otherwise.
+    DEFAULT_SCOPE: String
+
+    # @rbs module-self _I18nableClass
+    module ClassMethods : _I18nableClass
+      # The I18n scope titles are looked up under.
+      # : (?String?) -> String
+      def title_scope: (?String?) -> String
+
+      # The key within that scope, derived from the declared type unless it is set.
+      # : (?(String | Symbol)?) -> String?
+      def title_key: (?(String | Symbol)?) -> String?
+
+      # 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: (?String?, ?interpolations: Hash[Symbol, untyped]) -> String?
+    end
+  end
+end

data/sig/generated/problem/railtie.rbs

@@ -0,0 +1,12 @@
+# Generated from lib/problem/railtie.rb with RBS::Inline
+
+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
+  end
+end

data/sig/generated/problem/renderer.rbs

@@ -0,0 +1,16 @@
+# Generated from lib/problem/renderer.rb with RBS::Inline
+
+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!: () -> void
+  end
+end

data/sig/generated/problem/rescuable.rbs

@@ -0,0 +1,54 @@
+# Generated from lib/problem/rescuable.rb with RBS::Inline
+
+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 : _RescuableSelf
+    extend ActiveSupport::Concern
+
+    # : (detailable_error) -> void
+    private def render_problem_detailable: (detailable_error) -> void
+
+    # 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: () { () -> void } -> void
+
+    # Override to fill members only the request can supply, such as `instance`.
+    # : (detailable_error) -> Details
+    private def problem_for: (detailable_error) -> Details
+
+    # A client error the API expected is not an incident; a server-side failure is.
+    # : (detailable_error, Details) -> bool
+    private def report_problem?: (detailable_error, Details) -> bool
+
+    # 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: (detailable_error, Details) -> void
+
+    # : (detailable_error) -> void
+    private def apply_problem_headers: (detailable_error) -> void
+
+    # The only transport-specific step.
+    # : (Details, detailable_error) -> void
+    private def render_problem: (Details, detailable_error) -> void
+  end
+end

data/sig/generated/problem/retry_after.rbs

@@ -0,0 +1,47 @@
+# Generated from lib/problem/retry_after.rb with RBS::Inline
+
+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 : Detailable
+    # The response header the wait is published in.
+    HEADER: 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: (*untyped, retry_after: Integer | Time, **untyped) -> void
+
+    # A deadline that has already passed is published as 0 rather than as a negative wait.
+    # : () -> Integer
+    def retry_after_seconds: () -> Integer
+
+    # Adds the wait, so a title template can name it.
+    # : () -> Hash[Symbol, untyped]
+    def title_interpolations: () -> Hash[Symbol, untyped]
+
+    # Publishes the wait in the document as a `retry_after` extension member.
+    # : () -> Hash[Symbol, untyped]
+    def problem_extensions: () -> Hash[Symbol, untyped]
+
+    # Publishes the wait as a Retry-After header, which a generic HTTP client obeys.
+    # : () -> Hash[String, String]
+    def problem_headers: () -> Hash[String, String]
+  end
+end

data/sig/generated/problem/version.rbs

@@ -0,0 +1,6 @@
+# Generated from lib/problem/version.rb with RBS::Inline
+
+module Problem
+  # The gem's version.
+  VERSION: String
+end

data/sig/generated/problem.rbs

@@ -0,0 +1,39 @@
+# Generated from lib/problem.rb with RBS::Inline
+
+# RFC 9457 Problem Details for HTTP APIs.
+module Problem
+  # 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: Regexp
+
+  self.@config: Configuration?
+
+  # The settings in effect, created on first use.
+  # : () -> Configuration
+  def self.config: () -> Configuration
+
+  # 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: () { (Configuration) -> void } -> void
+
+  # 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!: () -> void
+
+  # 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: (String?, ?prefix: String?) -> String?
+end

data/sig/manual/core.rbs

@@ -0,0 +1,5 @@
+# `Data.define` generates a keyword-taking `initialize` on the class it returns, but core
+# RBS declares none, so a subclass overriding `initialize` has nothing to call `super` on.
+class Data
+  def initialize: (**untyped) -> void
+end

data/sig/manual/detailable.rbs

@@ -0,0 +1,37 @@
+module Problem
+  # What `rescue_from Problem::Detailable` actually hands a handler: the exception itself,
+  # carrying the concern. A module self-type constrains includers, not the module's own
+  # type, so the two have to be spelled out together.
+  type detailable_error = ::Exception & Detailable
+
+  # The class-level state and DSL Problem::Detailable installs. Declared by hand because
+  # `class_attribute` defines its accessors at runtime and `class_methods do ... end`
+  # builds ClassMethods from a block, neither of which RBS can infer.
+  interface _DetailableClass
+    def problem_status: () -> Integer?
+    def problem_status=: (Integer?) -> void
+    def problem_title: () -> String?
+    def problem_title=: (String?) -> void
+    def problem_uri: () -> String?
+    def problem_uri=: (String?) -> void
+    def problem_type_prefix: () -> String?
+    def problem_type_prefix=: (String?) -> void
+
+    def status: (?Integer?) -> Integer?
+    def title: (?String?, ?interpolations: Hash[Symbol, untyped]) -> String?
+    def type: (?String?) -> String?
+    def type_prefix: (?String?) -> String?
+
+    def name: () -> String?
+  end
+
+  # #to_problem reaches the DSL through `self.class`, which is what keeps a prepended
+  # catalogue override in the path.
+  interface _DetailableSelf
+    def class: () -> _DetailableClass
+
+    # The including exception's own constructor, which #initialize forwards to. Its shape
+    # belongs to that class, so it is untyped here rather than pinned to Exception.
+    def initialize: (*untyped, **untyped) -> void
+  end
+end

data/sig/manual/details.rbs

@@ -0,0 +1,24 @@
+module Problem
+  # Hand-written: rbs-inline cannot describe a `Data.define` assignment, so
+  # lib/problem/details.rb carries no `rbs_inline` magic comment.
+  class Details < ::Data
+    include Document
+
+    attr_reader type: String?
+    attr_reader title: String?
+    attr_reader status: Integer
+    attr_reader detail: String?
+    attr_reader instance: String?
+    attr_reader extensions: Hash[Symbol, untyped]
+
+    def self.new: (status: Integer, ?type: String?, ?title: String?, ?detail: String?,
+                   ?instance: String?, ?extensions: Hash[untyped, untyped]) -> Details
+
+    def self.members: () -> Array[Symbol]
+
+    def initialize: (status: Integer, ?type: String?, ?title: String?, ?detail: String?,
+                     ?instance: String?, ?extensions: Hash[untyped, untyped]) -> void
+
+    private def sanitized_extensions: (Hash[untyped, untyped]) -> Hash[Symbol, untyped]
+  end
+end

data/sig/manual/document.rbs

@@ -0,0 +1,12 @@
+module Problem
+  # What Problem::Document needs from the value object including it. Declared by hand
+  # because a module cannot state the readers of its includers on its own.
+  interface _Document
+    def type: () -> String?
+    def title: () -> String?
+    def status: () -> Integer
+    def detail: () -> String?
+    def instance: () -> String?
+    def extensions: () -> Hash[Symbol, untyped]
+  end
+end

data/sig/manual/i18nable.rbs

@@ -0,0 +1,15 @@
+module Problem
+  # The class-level state Problem::I18nable adds, plus what it reaches on
+  # Problem::Detailable to fall through to.
+  interface _I18nableClass
+    def problem_title_scope: () -> String?
+    def problem_title_scope=: (String?) -> void
+    def problem_title_key: () -> String?
+    def problem_title_key=: (String?) -> void
+
+    def problem_title: () -> String?
+    def type: (?String?) -> String?
+    def title_scope: (?String?) -> String
+    def title_key: (?(String | Symbol)?) -> String?
+  end
+end

data/sig/manual/rails.rbs

@@ -0,0 +1,14 @@
+# Rails APIs the gem uses that gem_rbs_collection does not declare.
+module Rails
+  class Railtie
+    def self.initializer: (String, **untyped) ?{ (untyped) -> void } -> void
+  end
+
+  class Application
+    class Configuration
+      # Set by Problem::Railtie, read by its initializer.
+      def problem: () -> untyped
+      def problem=: (untyped) -> void
+    end
+  end
+end

data/sig/manual/rescuable.rbs

@@ -0,0 +1,19 @@
+module Problem
+  # What Problem::Rescuable needs from the controller it is mixed into. Declared by hand
+  # for the same reason the sibling gem declares its controller self-type: a mix-in cannot
+  # state the API of its includers.
+  interface _RescuableSelf
+    def render: (**untyped) -> void
+    def response: () -> untyped
+  end
+end
+
+module ActiveSupport
+  # Absent from gem_rbs_collection's activesupport signatures.
+  def self.error_reporter: () -> ErrorReporter
+
+  class ErrorReporter
+    def report: (Exception, ?handled: bool, ?severity: Symbol, ?context: Hash[Symbol, untyped],
+                 ?source: String?) -> void
+  end
+end