gemstack 0.2.5 → 0.3.0

data/lib/gemstack/dev/supervisor.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Dev
+    # Runs `gemstack dev`: the gateway on the public port, the Ruby API and
+    # Next.js on private ports chosen automatically, prefixed output, restarts
+    # of the API when configuration changes, and a clean shutdown on Ctrl-C.
+    class Supervisor
+      LOOPBACK = "127.0.0.1"
+      TICK = 0.25
+
+      attr_reader :gateway, :processes
+
+      def initialize(root:, config: GemStack.config, terminal: Terminal.new, env: ENV)
+        @root = Pathname.new(root)
+        @config = config
+        @dev = config.dev
+        @terminal = terminal
+        @env = env
+        @processes = {}
+        @stopping = false
+      end
+
+      def run
+        if frontend?
+          check_node!
+          prepare_frontend
+        end
+        start
+        install_signal_handlers
+        loop_until_stopped
+      ensure
+        shutdown
+      end
+
+      def start
+        @started_at = monotonic
+        api_port = Ports.free(LOOPBACK)
+        web_port = Ports.free(LOOPBACK) if frontend?
+        @gateway = Gateway.new(
+          port: @dev.port, bind: @dev.bind, api_path: @config.http.api_path,
+          api: Gateway::Upstream.new(:api, LOOPBACK, api_port, "Ruby API"),
+          frontend: web_port && Gateway::Upstream.new(:next, LOOPBACK, web_port, "Next.js"),
+          on_error: ->(e) { @terminal.line("gateway", "#{e.class}: #{e.message}") }
+        ).start
+
+        start_processes(api_port, web_port)
+        @restart_watcher = FileWatcher.new(@dev.restart_on, root: @root, exclude: @dev.restart_exclude)
+        @recovery_watcher = FileWatcher.new(["app/**/*", "config/**/*", "Gemfile.lock"], root: @root)
+        @jobs_watcher = FileWatcher.new(["app/**/*.rb", "db/migrations/*.rb"], root: @root) if @dev.jobs_command
+        start_jobs if jobs_enabled?
+        if web_port && @dev.contract_command
+          @contract_watcher = FileWatcher.new(@dev.contract_watch, root: @root)
+          @contract_pending = true # generate once at startup
+        end
+        banner
+        watch_readiness
+        self
+      end
+
+      def start_processes(api_port, web_port)
+        @processes[:api] = spawn("api", @dev.api_command, @root, api_env(api_port))
+        @processes[:next] = spawn("next", frontend_command(web_port), frontend_dir, frontend_env(api_port)) if web_port
+      end
+
+      def spawn(name, command, dir, env)
+        ManagedProcess.new(name, command, terminal: @terminal, chdir: dir, env: env).start
+      end
+
+      def stop!
+        @stopping = true
+      end
+
+      def shutdown
+        return if @shut_down
+
+        @shut_down = true
+        @terminal.puts
+        @terminal.line("gemstack", "shutting down…")
+        @processes.values.map { |process| Thread.new { process.stop } }.each(&:join)
+        @gateway&.stop
+      end
+
+      private
+
+      def frontend? = frontend_dir.join("package.json").file?
+      def frontend_dir = @root.join(@dev.frontend_dir)
+
+      def api_env(port)
+        {
+          "GEMSTACK_ENV" => @env.fetch("GEMSTACK_ENV", "development"),
+          "GEMSTACK_API_HOST" => LOOPBACK,
+          "GEMSTACK_API_PORT" => port.to_s,
+          "GEMSTACK_LOG_COLOR" => @terminal.color ? "1" : "0",
+          "PORT" => nil # the public port belongs to the gateway
+        }
+      end
+
+      def frontend_env(api_port)
+        {
+          "GEMSTACK_API_URL" => "http://#{LOOPBACK}:#{api_port}",
+          "NEXT_PUBLIC_GEMSTACK_API_PATH" => @config.http.api_path,
+          "FORCE_COLOR" => @terminal.color ? "1" : nil,
+          "PORT" => nil
+        }
+      end
+
+      def frontend_command(port)
+        return Array(@dev.frontend_command) + ["--port", port.to_s] if @dev.frontend_command
+
+        [frontend_dir.join("node_modules/.bin/next").to_s, "dev", "--hostname", LOOPBACK, "--port", port.to_s]
+      end
+
+      # Next.js exits at once on an old Node.js with a line that's easy to miss
+      # among the other output; say it up front, with the command that fixes it.
+      def check_node!(node = Toolchain.node)
+        return if node && Toolchain.node_ok?(node[:version])
+
+        wanted = [@root.join(".node-version"), @root.join(".nvmrc")].find(&:file?)&.read&.strip
+        wanted = Toolchain::LTS_NODE if wanted.nil? || wanted.empty?
+        found = node ? "Node.js #{node[:version]} (#{node[:path]})" : "no `node` on the PATH"
+        raise Error, "Next.js needs Node.js #{Toolchain::MIN_NODE.join(".")} or newer; found #{found}.\n  " \
+                     "→ #{Toolchain.node_hint(wanted, Toolchain.node_manager(node&.fetch(:path)))}"
+      end
+
+      # Installs frontend dependencies on first run so `gemstack new && gemstack dev`
+      # works even with --skip-install.
+      def prepare_frontend
+        return if frontend_dir.join("node_modules/.bin/next").exist?
+
+        manager = package_manager
+        @terminal.line("gemstack", "installing frontend dependencies with #{manager} (first run)…")
+        installer = ManagedProcess.new(manager, [manager, "install"], terminal: @terminal, chdir: frontend_dir).start
+        sleep 0.1 while installer.running?
+        return if installer.status.is_a?(Process::Status) && installer.status.success?
+
+        raise Error, "#{manager} install failed (#{installer.describe_status}) in #{frontend_dir}"
+      end
+
+      def package_manager
+        {
+          "pnpm-lock.yaml" => "pnpm", "yarn.lock" => "yarn", "bun.lockb" => "bun", "bun.lock" => "bun"
+        }.each { |lock, manager| return manager if frontend_dir.join(lock).exist? }
+        "npm"
+      end
+
+      def banner
+        url = "http://localhost:#{@gateway.port}"
+        t = @terminal
+        t.puts
+        t.puts("  #{t.bold("GemStack")} #{t.dim("v#{GemStack::VERSION} · #{@env.fetch("GEMSTACK_ENV",
+                                                                                      "development")}")}")
+        t.puts
+        split = t.dim("(#{@config.http.api_path}/* → Ruby, everything else → Next.js)")
+        t.puts("  #{t.green("✓")} Gateway    #{url}  #{split}")
+        t.puts("  #{t.yellow("…")} Ruby API   #{t.dim("starting on #{@gateway.api} (internal)")}")
+        if @gateway.frontend
+          t.puts("  #{t.yellow("…")} Next.js    #{t.dim("starting on #{@gateway.frontend} (internal)")}")
+        else
+          t.puts("  #{t.dim("-")} Next.js    #{t.dim("no #{@dev.frontend_dir}/package.json — API only")}")
+        end
+        t.puts
+        t.puts("  Application: #{t.bold(url)}")
+        t.puts
+      end
+
+      def watch_readiness
+        [@gateway.api, @gateway.frontend].compact.each do |upstream|
+          Thread.new do
+            until @stopping
+              if Ports.open?(upstream.host, upstream.port)
+                seconds = (monotonic - @started_at).round(1)
+                @terminal.line("gemstack", "#{@terminal.green("✓")} #{upstream.label} ready (#{seconds}s)")
+                break
+              end
+              sleep TICK
+            end
+          end
+        end
+      end
+
+      def install_signal_handlers
+        %w[INT TERM].each { |signal| trap(signal) { @stopping = true } }
+      end
+
+      def loop_until_stopped
+        until @stopping
+          sleep TICK
+          supervise
+        end
+      end
+
+      def supervise
+        api = @processes[:api]
+        if @restart_watcher.changed?
+          restart_api("configuration changed")
+        elsif !api.running? && api.exited?
+          report_exit(api)
+          restart_api("files changed") if @recovery_watcher.changed?
+        end
+        web = @processes[:next]
+        report_exit(web) if web && !web.running? && web.exited?
+        supervise_contract
+        supervise_jobs
+      end
+
+      # A worker only makes sense with the database queue and its table.
+      def jobs_enabled?
+        return false unless @dev.jobs_command && defined?(GemStack::Jobs) && @config.respond_to?(:jobs)
+        return false unless %w[database postgres].include?(@config.jobs.adapter.to_s)
+
+        Dir.glob(@root.join("db/migrations/*_create_gemstack_jobs.rb").to_s).any?
+      end
+
+      def start_jobs
+        @processes[:jobs] = spawn("jobs", @dev.jobs_command, @root, { "GEMSTACK_ENV" => "development" })
+      end
+
+      # The worker doesn't reload code, so restart it when app/ changes
+      # (it finishes running jobs first), and start it once the jobs table exists.
+      def supervise_jobs
+        return unless @jobs_watcher&.changed?
+
+        jobs = @processes[:jobs]
+        if jobs&.running?
+          @terminal.line("gemstack", "app changed — restarting job worker")
+          jobs.restart
+        elsif jobs_enabled?
+          start_jobs
+        end
+      end
+
+      # One contract run at a time; changes during a run queue exactly one more.
+      def supervise_contract
+        return unless @contract_watcher
+
+        @contract_pending = true if @contract_watcher.changed?
+        running = @processes[:contract]&.running?
+        return if running || !@contract_pending
+
+        @contract_pending = false
+        @processes[:contract] = spawn("contract", @dev.contract_command, @root, { "GEMSTACK_ENV" => "development" })
+      end
+
+      # Both watchers overlap (config/), so re-baseline both after a restart
+      # to avoid restarting twice for a single change.
+      def restart_api(reason)
+        @terminal.line("gemstack", "#{reason} — restarting Ruby API")
+        @processes[:api].restart
+        @restart_watcher.changed?
+        @recovery_watcher.changed?
+        @reported_exit = nil
+      end
+
+      def report_exit(process)
+        key = [process.name, process.pid]
+        return if @reported_exit&.include?(key)
+
+        (@reported_exit ||= []) << key
+        hint = process.name == "api" ? " — fix the error; it restarts when you save a file" : ""
+        @terminal.line("gemstack", @terminal.red("#{process.name} exited (#{process.describe_status})#{hint}"))
+      end
+
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/gemstack/dev/terminal.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module GemStack
+  module Dev
+    # Serialised, prefixed, coloured output for multiple processes:
+    #
+    #   api     │ 12:00:01.120 INFO  GET /api/health status=200 ms=0.4
+    #   next    │ ✓ Compiled / in 812ms
+    class Terminal
+      COLORS = { "api" => 35, "next" => 36, "gateway" => 33, "gemstack" => 32, "jobs" => 34 }.freeze
+      WIDTH = 8
+
+      def initialize(io = $stdout, color: io.respond_to?(:tty?) && io.tty?)
+        @io = io
+        @io.sync = true if @io.respond_to?(:sync=) # output may be a pipe or file
+        @color = color
+        @mutex = Mutex.new
+      end
+
+      attr_reader :color
+
+      def line(name, text)
+        prefix = paint(name.ljust(WIDTH), COLORS.fetch(name, 37))
+        text = text.to_s.chomp
+        @mutex.synchronize { @io.puts("#{prefix}│ #{text}") }
+      end
+
+      def puts(text = "")
+        @mutex.synchronize { @io.puts(text) }
+      end
+
+      def paint(text, code) = @color ? "\e[#{code}m#{text}\e[0m" : text
+      def bold(text) = @color ? "\e[1m#{text}\e[0m" : text
+      def dim(text) = paint(text, 90)
+      def green(text) = paint(text, 32)
+      def red(text) = paint(text, 31)
+      def yellow(text) = paint(text, 33)
+    end
+  end
+end

data/lib/gemstack/dev/toolchain.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "open3"
+require "rbconfig"
+
+module GemStack
+  module Dev
+    # The Ruby and Node.js a developer runs, and how to change them — for
+    # whichever version manager installed them (rbenv, rvm, asdf, mise,
+    # chruby, nvm, fnm, nodenv, Volta, Homebrew…). GemStack pins versions in
+    # files every manager reads (.ruby-version, .node-version, .nvmrc,
+    # .tool-versions) and never assumes one manager.
+    module Toolchain
+      MIN_RUBY = "3.3"
+      MIN_NODE = [20, 9].freeze # Next.js 16
+      LTS_NODE = "22"
+
+      # [pattern in the executable's path, manager name]; the first match wins.
+      RUBY_MANAGERS = [
+        [%r{/\.rbenv/}, :rbenv], [%r{/\.rvm/|/rvm/rubies/}, :rvm], [%r{/\.asdf/|/asdf/installs/}, :asdf],
+        [%r{/mise/installs/|/\.local/share/mise/}, :mise], [%r{/\.rubies/|/opt/rubies/}, :chruby],
+        [%r{/(?:opt/)?homebrew/|/usr/local/Cellar/}, :homebrew]
+      ].freeze
+      NODE_MANAGERS = [
+        [%r{/\.nvm/}, :nvm], [%r{/fnm/|/\.fnm/|fnm_multishells}, :fnm], [%r{/\.nodenv/}, :nodenv],
+        [%r{/\.asdf/|/asdf/installs/}, :asdf], [%r{/mise/installs/|/\.local/share/mise/}, :mise],
+        [%r{/\.volta/}, :volta], [%r{/(?:opt/)?homebrew/|/usr/local/Cellar/}, :homebrew]
+      ].freeze
+
+      module_function
+
+      def ruby_manager(path = RbConfig.ruby) = detect(RUBY_MANAGERS, path)
+      def node_manager(path) = path && detect(NODE_MANAGERS, path)
+
+      def detect(managers, path)
+        managers.find { |pattern, _| path.to_s.match?(pattern) }&.last
+      end
+
+      # How to install and select a Ruby, with the manager in use.
+      def ruby_hint(version, manager = ruby_manager)
+        {
+          rbenv: "rbenv install #{version} && rbenv local #{version}",
+          rvm: "rvm install #{version} && rvm use #{version}",
+          asdf: "asdf install ruby #{version} && asdf set ruby #{version}",
+          mise: "mise use ruby@#{version}",
+          chruby: "ruby-install ruby #{version}, then: chruby #{version}",
+          homebrew: "brew upgrade ruby (or install #{version} with rbenv, rvm, asdf or mise)"
+        }.fetch(manager, "install Ruby #{version} (e.g. with rbenv, rvm, asdf or mise) and make it the active Ruby")
+      end
+
+      # How to install and select a Node.js, with the manager in use.
+      def node_hint(version, manager)
+        {
+          nvm: "nvm install #{version} && nvm use #{version}",
+          fnm: "fnm install #{version} && fnm use #{version}",
+          nodenv: "nodenv install #{version} && nodenv local #{version}",
+          asdf: "asdf install nodejs #{version} && asdf set nodejs #{version}",
+          mise: "mise use node@#{version}",
+          volta: "volta install node@#{version}",
+          homebrew: "brew install node@#{version} (or use nvm, fnm, asdf or mise)"
+        }.fetch(manager, "install Node.js #{version} (e.g. with nvm, fnm, asdf or mise) and make it the active node")
+      end
+
+      # { version: "22.11.0", path: "/…/bin/node" } or nil when there's no node.
+      def node(run = ->(*cmd) { Open3.capture2e(*cmd) })
+        out, status = run.call("node", "-p", "process.version + ' ' + process.execPath")
+        return nil unless status.success?
+
+        version, path = out.strip.split(" ", 2)
+        { version: version.delete_prefix("v"), path: path }
+      rescue SystemCallError
+        nil
+      end
+
+      def node_ok?(version) = (version.to_s.split(".").map(&:to_i) <=> MIN_NODE) >= 0
+      def ruby_ok?(version = RUBY_VERSION) = Gem::Version.new(version) >= Gem::Version.new(MIN_RUBY)
+
+      # The Node.js version new apps pin: the one running `gemstack new` when
+      # it's new enough, else the current LTS line.
+      def pinned_node_version(run = ->(*cmd) { Open3.capture2e(*cmd) })
+        found = node(run)
+        found && node_ok?(found[:version]) ? found[:version] : LTS_NODE
+      end
+    end
+  end
+end

data/lib/gemstack/dev.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "gemstack/core"
+
+module GemStack
+  # Development tooling: the single-origin gateway and the process
+  # supervisor behind `gemstack dev` (ARCHITECTURE §5). Nothing here is
+  # loaded in production unless explicitly required.
+  module Dev
+    autoload :FileWatcher, "gemstack/dev/file_watcher"
+    autoload :Gateway, "gemstack/dev/gateway"
+    autoload :ManagedProcess, "gemstack/dev/managed_process"
+    autoload :Ports, "gemstack/dev/ports"
+    autoload :Supervisor, "gemstack/dev/supervisor"
+    autoload :Terminal, "gemstack/dev/terminal"
+    autoload :Toolchain, "gemstack/dev/toolchain"
+
+    class Config < Settings
+      # The single public port.
+      setting :port, default: -> { Integer(ENV.fetch("PORT", 3000)) }
+      # Interfaces the gateway listens on. Both loopback families, because
+      # browsers may resolve "localhost" to either.
+      setting :bind, default: %w[127.0.0.1 ::1]
+      setting :frontend_dir, default: "frontend"
+      setting :api_command, default: %w[bundle exec puma -C config/puma.rb]
+      # nil = run the frontend's own `next` binary in dev mode.
+      setting :frontend_command, default: nil
+      # Changes here restart the Ruby process. app/ and config/routes.rb are
+      # reloaded in-process instead and don't need a restart.
+      setting :restart_on, default: ["config/**/*.rb", "Gemfile.lock", ".env*"]
+      setting :restart_exclude, default: ["config/routes.rb"]
+      # Regenerates TypeScript types/clients when backend code changes
+      # (only when the app has a frontend). nil disables.
+      setting :contract_command, default: %w[bundle exec gemstack contract --quiet]
+      setting :contract_watch, default: ["app/**/*.rb", "config/routes.rb"]
+      # Background job worker, run when the app uses the :postgres job
+      # adapter and has the gemstack_jobs migration. Restarted when app/ changes.
+      setting :jobs_command, default: %w[bundle exec gemstack jobs]
+    end
+  end
+
+  Config.namespace(:dev, Dev::Config)
+end

data/lib/gemstack/dotenv.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module GemStack
+  # Minimal `.env` file support.
+  #
+  # Supported syntax:
+  #   KEY=value
+  #   export KEY=value
+  #   KEY="double quoted, supports \n \t \" escapes"
+  #   KEY='single quoted, literal'
+  #   KEY=value # trailing comment (unquoted values only)
+  #   # full-line comment
+  #
+  # Variables already present in the environment are never overwritten: the
+  # real environment always wins over files.
+  module Dotenv
+    LINE = /\A\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_.]*)\s*=\s*(.*)\z/
+    ESCAPES = { "n" => "\n", "t" => "\t", "r" => "\r", '"' => '"', "\\" => "\\" }.freeze
+
+    module_function
+
+    # Loads the given files (in order; earlier files take precedence) into env.
+    # Returns the hash of variables that were actually set.
+    def load(*files, env: ENV)
+      loaded = {}
+      files.flatten.each do |file|
+        next unless File.file?(file)
+
+        parse(File.read(file)).each do |key, value|
+          next if env.key?(key) || loaded.key?(key)
+
+          env[key] = value
+          loaded[key] = value
+        end
+      end
+      loaded
+    end
+
+    def parse(source)
+      source.each_line.with_object({}) do |raw, vars|
+        line = raw.chomp
+        next if line.strip.empty? || line.lstrip.start_with?("#")
+
+        match = LINE.match(line) or next
+        vars[match[1]] = parse_value(match[2].strip)
+      end
+    end
+
+    def parse_value(value)
+      case value[0]
+      when '"'
+        body = value[1..][/\A((?:[^"\\]|\\.)*)"/, 1] || value[1..]
+        body.gsub(/\\(.)/) { ESCAPES.fetch(::Regexp.last_match(1), "\\#{::Regexp.last_match(1)}") }
+      when "'"
+        value[1..][/\A([^']*)'/, 1] || value[1..]
+      else
+        value.sub(/\s+#.*\z/, "")
+      end
+    end
+  end
+end

data/lib/gemstack/environment.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module GemStack
+  # The running environment: development, test, production, or any custom name.
+  #
+  #   GemStack.env.production?  # => false
+  #   GemStack.env.to_s         # => "development"
+  class Environment
+    KNOWN = %w[development test production].freeze
+
+    attr_reader :name
+
+    def self.detect(env = ENV)
+      new(env["GEMSTACK_ENV"] || env["RACK_ENV"] || "development")
+    end
+
+    def initialize(name)
+      @name = name.to_s.strip.downcase
+      raise ArgumentError, "environment name cannot be empty" if @name.empty?
+    end
+
+    def development? = name == "development"
+    def test? = name == "test"
+    def production? = name == "production"
+
+    # Anything that isn't development or test is treated like production for
+    # safety-related defaults (hiding error details, JSON logs, ...).
+    def local? = development? || test?
+
+    def to_s = name
+    def to_sym = name.to_sym
+    def ==(other) = name == other.to_s
+    alias eql? ==
+    def hash = name.hash
+    def inspect = "#<GemStack::Environment #{name}>"
+  end
+end

data/lib/gemstack/error_mapping.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module GemStack
+  # Translates third-party exceptions into GemStack errors, so modules can
+  # give library errors an HTTP meaning without depending on the HTTP layer:
+  #
+  #   GemStack::ErrorMapping.register(Sequel::NoMatchingRow) { GemStack::NotFound.new }
+  #   GemStack::ErrorMapping.register(Stripe::CardError) { |e| GemStack::Error.new(e.message, status: 402, code: "card_declined") }
+  #
+  # The HTTP error renderer consults this registry before rendering. The most
+  # recently registered matching class wins, so applications can override
+  # module defaults.
+  module ErrorMapping
+    @mappings = []
+    @mutex = Mutex.new
+
+    class << self
+      def register(exception_class, &translator)
+        raise ArgumentError, "ErrorMapping.register needs a block" unless translator
+
+        @mutex.synchronize { @mappings.unshift([exception_class, translator]) }
+      end
+
+      def unregister(exception_class)
+        @mutex.synchronize { @mappings.reject! { |klass, _| klass == exception_class } }
+      end
+
+      # Returns the translated error, or the original exception if no mapping applies.
+      def translate(exception)
+        _, translator = @mappings.find { |klass, _| exception.is_a?(klass) }
+        return exception unless translator
+
+        translator.call(exception) || exception
+      end
+    end
+  end
+end

data/lib/gemstack/errors.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module GemStack
+  # Base class for every GemStack error.
+  #
+  # Errors carry an HTTP-oriented *suggestion* (`status`, `code`) so that any
+  # module — including ones that know nothing about HTTP, such as a database
+  # adapter — can raise an error that the HTTP layer renders correctly. Any
+  # exception that responds to #status and #code is rendered this way, so
+  # applications can define their own errors without subclassing these.
+  class Error < StandardError
+    class << self
+      attr_writer :default_status, :default_code, :default_message
+
+      def default_status = @default_status || inherited_default(:default_status, 500)
+      def default_code = @default_code || inherited_default(:default_code, "internal_error")
+      def default_message = @default_message || inherited_default(:default_message, "Internal Server Error")
+
+      # Declares the status/code/message for an error class.
+      def status(status, code, message)
+        self.default_status = status
+        self.default_code = code
+        self.default_message = message
+      end
+
+      private
+
+      def inherited_default(name, fallback) = superclass.respond_to?(name) ? superclass.public_send(name) : fallback
+    end
+
+    attr_reader :status, :code, :details, :headers
+
+    # details: optional field => [messages] hash, rendered as `errors`.
+    # headers: extra response headers (e.g. "allow" for 405, "retry-after" for 429).
+    def initialize(message = nil, status: nil, code: nil, details: nil, headers: nil)
+      @status = status || self.class.default_status
+      @code = code || self.class.default_code
+      @details = details
+      @headers = headers || {}
+      super(message || self.class.default_message)
+    end
+
+    # Whether the message is safe to show to API clients. Server errors are
+    # not: their messages may contain internal information.
+    def expose_message? = status < 500
+  end
+
+  # Raised for invalid framework or application configuration.
+  class ConfigurationError < Error; end
+
+  class BadRequest < Error
+    status 400, "bad_request", "Bad Request"
+  end
+
+  class Unauthorized < Error
+    status 401, "unauthorized", "Unauthorized"
+  end
+
+  class Forbidden < Error
+    status 403, "forbidden", "Forbidden"
+  end
+
+  class NotFound < Error
+    status 404, "not_found", "Not Found"
+  end
+
+  class MethodNotAllowed < Error
+    status 405, "method_not_allowed", "Method Not Allowed"
+  end
+
+  class Conflict < Error
+    status 409, "conflict", "Conflict"
+  end
+
+  class PayloadTooLarge < Error
+    status 413, "payload_too_large", "Payload Too Large"
+  end
+
+  class UnsupportedMediaType < Error
+    status 415, "unsupported_media_type", "Unsupported Media Type"
+  end
+
+  class ValidationError < Error
+    status 422, "validation_failed", "Validation failed"
+
+    def initialize(message = nil, errors: {}, **)
+      super(message, details: errors, **)
+    end
+
+    def errors = details
+  end
+
+  class TooManyRequests < Error
+    status 429, "too_many_requests", "Too Many Requests"
+  end
+
+  class ServiceUnavailable < Error
+    status 503, "service_unavailable", "Service Unavailable"
+  end
+end