kiosk-server 0.5.20

data/lib/kiosk/server/handler_mixin.rb

@@ -0,0 +1,418 @@
+# frozen_string_literal: true
+
+require 'action_controller'
+require 'action_dispatch'
+
+module Kiosk
+  module Server
+    # Implementation behind `include Kiosk::Handler`. The macros above a `def` make it a wire verb;
+    # a method with no pending declaration stays off the wire.
+    module HandlerMixin
+      KINDS = %i[action query].freeze
+
+      # The four reaches of §7.2; the first is the default.
+      REACHES = %i[principal published consented role].freeze
+
+      # The strictest reach, so an undeclared verb is never widened.
+      DEFAULT_REACH = :principal
+
+      # §8.1: a verb name is one path segment.
+      NAME_PATTERN = /\A[a-z][a-z0-9_]*\z/
+
+      # First path segments the engine draws under the mount; keep in step with its routes.
+      RESERVED_NAMES = %w[agents auth events kyc oauth pay payment_setup request_kyc schema].freeze
+
+      # The declaration members a verb registry entry takes.
+      REGISTERED_KEYS = %i[reach description input_schema output_schema example_params example_row].freeze
+
+      # Required on every verb (§8.3); a declaration missing either is refused at class load.
+      REQUIRED_DECLARATIONS = %i[input_schema output_schema].freeze
+
+      # Installs the mixin. Called from Kiosk::Handler.included.
+      def self.install(base)
+        raise ArgumentError, Refusal::NOT_A_CONTROLLER unless base.is_a?(Class) && base <= ::ActionController::Metal
+
+        # An operator's base class and its subclass may both include the mixin.
+        return if base.respond_to?(:kiosk_declarations)
+
+        base.extend(ClassMethods)
+        base.include(InstanceMethods)
+
+        # The wire authenticates by bearer token, never by cookie, so CSRF protection does not apply.
+        base.skip_forgery_protection if base.respond_to?(:skip_forgery_protection)
+
+        # Registered at include time, so an operator's own `rescue_from` declared later wins.
+        base.rescue_from(StandardError, with: :kiosk_rescue_to_wire) if base.respond_to?(:rescue_from)
+      end
+
+      # Resolved lazily so this file can be required before the registries.
+      def self.registry_for(kind)
+        kind == :action ? Actions : Queries
+      end
+
+      # The sentences a refused declaration raises with.
+      module Refusal
+        module_function
+
+        NOT_A_CONTROLLER =
+          'include Kiosk::Handler into a controller class — each verb route reaches ' \
+          'a controller action, which needs an ActionController subclass. ' \
+          'Pick the base class yourself (ApplicationController, ActionController::API, …); ' \
+          'Kiosk does not impose one.'
+
+        def mount_path = Kiosk.configuration.mount_path
+
+        def bad_kind(owner, value)
+          "#{owner} declared `kind #{value.inspect}`, which is not a Kiosk verb kind. " \
+            "It is :query (reached by GET #{mount_path}/<name>) or " \
+            ":action (POST #{mount_path}/<name>)."
+        end
+
+        def bad_reach(owner, value)
+          "#{owner} declared `reach #{value.inspect}`, which is not a Kiosk verb reach. " \
+            "It is :principal (the default — only the calling principal's own rows, or rows " \
+            'that belong to no principal), :published (the operator publishes owner-carrying ' \
+            'rows to everyone, by intent), :consented (a principal shared them, and the ' \
+            'operator can point at the artefact that says so) or :role (the reach follows the ' \
+            "caller's operator-assigned role claim). A verb that touches nobody else's rows " \
+            'declares nothing at all.'
+        end
+
+        def bad_topic_name(owner, name)
+          "#{owner} declared `topic #{name.inspect}`, which is not a legal Kiosk name. " \
+            "A topic name is a wire name: #{NAME_PATTERN.inspect}."
+        end
+
+        def reserved_topic(owner, name)
+          "#{owner} declared `topic #{name.inspect}`, but that name is reserved by the " \
+            "engine itself: #{RESERVED_NAMES.join(', ')}. Give the topic a name of its own."
+        end
+
+        # The §8.1/§8.3 name rules and required fields, first failure first; nil when none fails.
+        # `clash` is a declaration of the same name earlier in this class body.
+        def declaration(where, name, declaration, clash)
+          return missing_kind(where, name) if declaration[:kind].nil?
+          return name_clash(where, name, declaration, clash) if clash
+          return illegal_name(where, name) unless NAME_PATTERN.match?(name)
+          return reserved_name(where, name) if RESERVED_NAMES.include?(name)
+
+          missing = REQUIRED_DECLARATIONS.reject { |key| declaration.key?(key) }
+          return missing_schemas(where, name, missing) unless missing.empty?
+
+          reserved_parameter(where, name, ArgumentDecoder.fetch(declaration[:input_schema], :properties))
+        end
+
+        # §8.1 item 6: no verb declares `cursor`; a verb that declares `limit` declares an integer.
+        def reserved_parameter(where, name, properties)
+          return declared_cursor(where, name) if ArgumentDecoder.fetch(properties, :cursor)
+
+          limit = ArgumentDecoder.fetch(properties, :limit)
+          declared_limit(where, name, limit) unless limit.nil? || ArgumentDecoder.declared_type(limit) == 'integer'
+        end
+
+        def declared_cursor(where, name)
+          "#{where} declares `cursor` in the input_schema of #{name.inspect}. `cursor` is reserved: " \
+            'the engine accepts it on every query, and it carries the token of your `next` link. ' \
+            'Remove `cursor` from the input_schema.'
+        end
+
+        def declared_limit(where, name, limit)
+          "#{where} declares `limit` in the input_schema of #{name.inspect} as #{limit.inspect}. " \
+            '`limit` is the page size, an integer. Declare it `{ type: "integer", maximum: <your largest page> }`, ' \
+            'or remove it from the input_schema.'
+        end
+
+        def missing_kind(where, name)
+          "#{where} declares the Kiosk verb #{name.inspect} without a `kind`. " \
+            "Add `kind :query` (GET #{mount_path}/#{name}) or `kind :action` (POST #{mount_path}/#{name})."
+        end
+
+        # One name declared twice in one class body; the cross-class case is {HandlerRegistrations}.
+        def name_clash(where, name, declaration, clash)
+          return same_name(where, name, clash) if clash[:kind] == declaration[:kind]
+
+          "#{where} declares #{name.inspect} as a#{'n' if declaration[:kind] == :action} " \
+            "#{declaration[:kind]}, but ##{clash[:method_name]} on this class already " \
+            "declares it as a#{'n' if clash[:kind] == :action} #{clash[:kind]}. " \
+            'Rename one, or give it a `wire_name` of its own.'
+        end
+
+        def same_name(where, name, clash)
+          "#{where} declares the Kiosk verb #{name.inspect}, which ##{clash[:method_name]} " \
+            'on this class already declares. Rename one of the methods, or give one of them a ' \
+            '`wire_name` of its own.'
+        end
+
+        def illegal_name(where, name)
+          "#{where} declares the Kiosk verb #{name.inspect}, which is not a legal verb " \
+            "name (#{NAME_PATTERN.source}). Rename the method, or give it a legal `wire_name`."
+        end
+
+        def reserved_name(where, name)
+          "#{where} declares the Kiosk verb #{name.inspect}, which the engine reserves " \
+            "(#{RESERVED_NAMES.join(', ')}). Give it a `wire_name` of its own."
+        end
+
+        def missing_schemas(where, name, missing)
+          "#{where} declares the Kiosk verb #{name.inspect} without #{missing.join(' and ')}. " \
+            'Declare both; a verb that takes nothing declares ' \
+            '`input_schema type: "object", additionalProperties: false, properties: {}`.'
+        end
+      end
+
+      # Evaluates a `topic` block, keeping its declarations out of the verb macros' pending state.
+      class TopicDeclaration
+        attr_reader :reach_value, :description_value, :payload_schema_value,
+                    :subject_reachable_value
+
+        def examples_value = (@examples_value ||= [])
+
+        def reach(value)
+          unless REACHES.include?(value)
+            raise ArgumentError,
+                  "a topic declared `reach #{value.inspect}`, which is not a Kiosk reach. " \
+                  "It is :principal (the default — only the calling principal's own events), " \
+                  ':published (the operator publishes to everyone, by intent), :consented (a ' \
+                  'principal shared the subject, and the operator can point at the artefact ' \
+                  "that says so) or :role (the reach follows the caller's operator-assigned " \
+                  'role claim).'
+          end
+
+          @reach_value = value
+        end
+
+        def description(text)
+          declared << :description
+          @description_value = text
+        end
+
+        def payload_schema(schema = nil, **kwargs)
+          declared << :payload_schema
+          @payload_schema_value = schema || kwargs
+        end
+
+        # One example `data` per call; each must satisfy `payload_schema`.
+        def example(data) = examples_value << data
+
+        # `(subject, identity) -> Boolean`; runs outside any request, so it cannot read {CurrentRequest}.
+        def subject_reachable(callable) = @subject_reachable_value = callable
+
+        # What {Events.register} takes for the topic `name`.
+        def registration(name)
+          { name: name, reach: reach_value || :principal, description: description_value,
+            payload_schema: payload_schema_value, examples: examples_value,
+            subject_reachable: subject_reachable_value }
+        end
+
+        # Each macro must be called; `description nil` is a valid answer (§8.5.1).
+        def validate!(owner:, name:)
+          missing = Events::REQUIRED - declared
+          unless missing.empty?
+            raise ArgumentError,
+                  "#{owner} declared `topic #{name.inspect}` without " \
+                  "#{missing.join(' and ')}. A topic carries `description` for semantics and " \
+                  '`payload_schema` for shape; a subscriber with neither has to receive a ' \
+                  'message to find out what it is.'
+          end
+
+          validate_examples!(owner: owner, name: name)
+        end
+
+        private
+
+        def declared = (@declared ||= [])
+
+        def validate_examples!(owner:, name:)
+          return if examples_value.empty?
+
+          require 'json_schemer'
+          schema = JSONSchemer.schema(RequestValidation.normalize(payload_schema_value))
+          examples_value.each do |data|
+            errors = schema.validate(RequestValidation.normalize(data)).map { it['error'] }
+            next if errors.empty?
+
+            raise ArgumentError,
+                  "#{owner} declared `topic #{name.inspect}` with an example that does not " \
+                  "satisfy its payload_schema: #{errors.join('; ')}"
+          end
+        end
+      end
+
+      module ClassMethods
+        # Which HTTP method reaches the next-defined method; one controller may declare both.
+        def kind(value)
+          raise ArgumentError, Refusal.bad_kind(self, value) unless KINDS.include?(value)
+
+          kiosk_pending[:kind] = value
+        end
+
+        # Whose rows the next verb may touch (§7.2); the default is :principal.
+        def reach(value)
+          raise ArgumentError, Refusal.bad_reach(self, value) unless REACHES.include?(value)
+
+          kiosk_pending[:reach] = value
+        end
+
+        def description(text)
+          kiosk_pending[:description] = text
+        end
+
+        def input_schema(schema = nil, **kwargs)
+          kiosk_pending[:input_schema] = schema || kwargs
+        end
+
+        def output_schema(schema = nil, **kwargs)
+          kiosk_pending[:output_schema] = schema || kwargs
+        end
+
+        def example_params(example = nil, **kwargs)
+          kiosk_pending[:example_params] = example || kwargs
+        end
+
+        def example_row(example = nil, **kwargs)
+          kiosk_pending[:example_row] = example || kwargs
+        end
+
+        def wire_name(name)
+          kiosk_pending[:wire_name] = name.to_s
+        end
+
+        # Declares an event topic; the block holds `reach`, `description`, `payload_schema`,
+        # `example` and `subject_reachable`.
+        def topic(name, &block)
+          name = name.to_s
+          raise ArgumentError, Refusal.bad_topic_name(self, name) unless name.match?(NAME_PATTERN)
+          raise ArgumentError, Refusal.reserved_topic(self, name) if RESERVED_NAMES.include?(name)
+
+          declaration = TopicDeclaration.new
+          declaration.instance_eval(&block) if block
+          declaration.validate!(owner: self, name: name)
+          kiosk_topic_declarations[name] = declaration.registration(name)
+        end
+
+        # `super` first: AbstractController::Base also hooks method_added.
+        def method_added(method_name)
+          super
+          pending = @kiosk_pending
+          return if pending.blank?
+
+          @kiosk_pending = nil
+          kiosk_declare(method_name, pending)
+        end
+
+        # Wire name → declaration for the verbs on this class, one per name.
+        def kiosk_declarations
+          @kiosk_declarations ||= {}
+        end
+
+        # Wire name → declaration for the topics on this class.
+        def kiosk_topic_declarations
+          @kiosk_topic_declarations ||= {}
+        end
+
+        # Runs as the class body is read; call it directly only to restore registrations after a test reset.
+        def kiosk_register!
+          kiosk_declarations.each_value { |declaration| kiosk_register_one(declaration) }
+          kiosk_topic_declarations.each_value { |declaration| Events.register(**declaration) }
+          self
+        end
+
+        private
+
+        def kiosk_pending
+          @kiosk_pending ||= {}
+        end
+
+        def kiosk_declare(method_name, pending)
+          declaration = pending.merge(
+            method_name: method_name.to_s,
+            wire_name: (pending[:wire_name] || method_name).to_s,
+            reach: pending[:reach] || HandlerMixin::DEFAULT_REACH
+          )
+          kiosk_refuse_bad_declaration!(declaration)
+          kiosk_declarations[declaration[:wire_name]] = declaration
+          kiosk_register_one(declaration)
+        end
+
+        # The §8.1/§8.3 name rules and required fields, refused at class load.
+        def kiosk_refuse_bad_declaration!(declaration)
+          name = declaration[:wire_name]
+          where = "#{self}##{declaration[:method_name]}"
+          refusal = Refusal.declaration(where, name, declaration, kiosk_declarations[name])
+          raise ArgumentError, refusal if refusal
+        end
+
+        def kiosk_register_one(declaration)
+          handler = ControllerVerb.new(
+            controller: self,
+            method_name: declaration[:method_name],
+            wire_name: declaration[:wire_name],
+            kind: declaration[:kind]
+          )
+          HandlerMixin.registry_for(declaration[:kind]).declare(
+            declaration[:wire_name], handler, **REGISTERED_KEYS.index_with { |key| declaration[key] }
+          )
+        end
+      end
+
+      # Handler-side helpers, private so none is mistaken for a controller action.
+      module InstanceMethods
+        include HandlerServing
+
+        private
+
+        # The acting {Kiosk::Identity}; nil outside a wire request.
+        def kiosk_identity = CurrentRequest.identity
+
+        # Differs from the method name only under `wire_name`.
+        def kiosk_wire_name = @_kiosk_wire_name
+
+        # One page of rows; a nil `next_cursor` is the last page. `total` counts every matching row and
+        # nil omits `X-Total-Count`. The body stays the bare rows; the page facts leave as headers.
+        # Without `rows` the action's own template renders them.
+        def render_kiosk_page(rows = nil, next_cursor: nil, total: nil)
+          @_kiosk_page = { next_cursor: next_cursor, total: total }
+          rows.nil? ? render : render(json: rows)
+        end
+
+        # A validation failure answers 400 with the errors' full messages. Any other raise Rails knows
+        # a status for maps to its lone wire code, its own message going to the operator's log and
+        # never onto the wire; anything else is re-raised.
+        def kiosk_rescue_to_wire(exception)
+          raise exception if exception.is_a?(Kiosk::Server::Errors::Base)
+
+          invalid = kiosk_invalid_model(exception)
+          raise Kiosk::Server::Errors::BadRequest, invalid.errors.full_messages.join('; ') if invalid
+
+          code = kiosk_rescued_code(exception)
+          raise exception if code.nil?
+
+          kiosk_render_rescued(exception, code)
+        end
+
+        def kiosk_rescued_code(exception)
+          status = ::ActionDispatch::ExceptionWrapper.rescue_responses[exception.class.name]
+          Kiosk::Server::Errors::STATUS_CODES[::Rack::Utils.status_code(status)]
+        end
+
+        def kiosk_render_rescued(exception, code)
+          Kiosk::Server::FailureLog.report(
+            "verb #{kiosk_wire_name.inspect} answered #{code} for #{exception.class}", exception
+          )
+
+          # Raised inside the rescue, so the exception reaches the audit sink as `cause`.
+          wire = Kiosk::Server::Errors.rescued_wire(code, verb: kiosk_wire_name)
+          raise Kiosk::Server::Errors::WireError.new(wire[:message], code: code, hint: wire[:hint])
+        end
+
+        # A failed model validation is an argument outside its domain: 400, in the model's own words.
+        def kiosk_invalid_model(exception)
+          case exception
+          when ::ActiveModel::ValidationError then exception.model
+          when ::ActiveRecord::RecordInvalid  then exception.record
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/server/handler_registrations.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # Rebuilds the verb and topic registries from every class that includes
+    # Kiosk::Handler. The engine calls {reload!} from `to_prepare`, so a verb
+    # added, edited or removed in development is served after the next reload.
+    module HandlerRegistrations
+      HANDLERS_DIR = 'app/controllers/kiosk'
+
+      class << self
+        def add(handler)
+          handlers << handler.name if handler.name
+        end
+
+        def reload!
+          clear!
+          load_handlers_dir
+          handlers.select! { |name| name.safe_constantize&.kiosk_register! }
+          PaymentSetup.register! if Kiosk.configuration.payment_provider
+          Kyc.register! if Kiosk.configuration.kyc_provider
+          refuse_cross_kind_collisions!
+        end
+
+        def clear!
+          [Actions, Queries, Events].each do |registry|
+            registry.known.each { |name| registry.unregister(name) }
+          end
+        end
+
+        def handlers
+          @handlers ||= Set.new
+        end
+
+        private
+
+        def load_handlers_dir
+          return unless defined?(::Rails) && ::Rails.application
+
+          dir = ::Rails.root.join(HANDLERS_DIR)
+          ::Rails.autoloaders.main.eager_load_dir(dir) if dir.directory?
+        end
+
+        def refuse_cross_kind_collisions!
+          both = Actions.known & Queries.known
+          return if both.empty?
+
+          raise Errors::ConfigurationError,
+                "#{both.sort.join(', ')} #{both.one? ? 'is' : 'are'} declared as BOTH a query and " \
+                "an action. GET #{Kiosk.configuration.mount_path}/<name> is a query and " \
+                "POST #{Kiosk.configuration.mount_path}/<name> is an action, so one name cannot be " \
+                'both. Rename one of them, or give it a `wire_name` of its own.'
+        end
+      end
+    end
+  end
+end

data/lib/kiosk/server/handler_serving.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Kiosk
+  module Server
+    # How a controller that includes {Kiosk::Handler} answers a verb call.
+    # {Routing::VerbRoute} sends the wire request to the action that declares
+    # the verb. Around that action this module runs the gates of {VerbWire},
+    # the session and the transaction, and writes the action's render as the
+    # wire answer.
+    module HandlerServing
+      include VerbWire
+
+      # The Rack env key where {Routing::VerbRoute} puts the wire name it routed.
+      VERB_KEY = 'kiosk.verb'
+
+      # The one header of an action's render that reaches the wire: `Cache-Control`, on a 2xx (§3.7.4).
+      PROPAGATED_HEADERS = %w[Cache-Control].freeze
+
+      private
+
+      # Outside the operator's callbacks and `rescue_from`, which all run inside `super`.
+      def process_action(*)
+        declaration = self.class.kiosk_declarations[request.get_header(VERB_KEY)]
+        return kiosk_refuse_unrouted unless declaration && declaration[:method_name] == action_name
+
+        # Parses the parameters first, so a malformed body is refused before the identity.
+        request.parameters
+        kiosk_render_answer(kiosk_call(declaration) { super })
+      rescue Errors::Base => e
+        kiosk_render_refusal(e)
+      rescue ::ActionDispatch::Http::Parameters::ParseError
+        kiosk_render_refusal(Errors.malformed_json(hint: BODY_HINT))
+      end
+
+      # The verb's {Result}: the wire's gates, then the action inside the session.
+      def kiosk_call(declaration, &)
+        kind     = declaration[:kind]
+        name     = @_kiosk_wire_name = declaration[:wire_name]
+        command  = kind == :query ? :query : :run
+        identity = resolve_identity!
+        args     = arguments_for(command, name, HandlerMixin.registry_for(kind).describe(name))
+        handler  = ->(handler_args) { kiosk_answer(kind, handler_args, &) }
+        call_wire(command: command, args: args, identity: identity, name: name, handler: handler)
+      end
+
+      # Runs the action with the decoded arguments as its parameters, and reads its render as the answer.
+      def kiosk_answer(kind, args)
+        kiosk_wire_parameters!(args)
+        yield
+
+        status, headers, body = response.to_a
+        @_kiosk_headers = kiosk_propagated_headers(status, headers)
+        Answer.new(kind, @_kiosk_wire_name).value(status, kiosk_read_body(body), @_kiosk_page)
+      end
+
+      # The action's `params` are the decoded arguments; the wire answers JSON whatever the caller's
+      # `Accept`, so an action's template is its `.json` one.
+      def kiosk_wire_parameters!(args)
+        request.set_header('action_dispatch.request.request_parameters', args.dup)
+        request.set_header('action_dispatch.request.query_parameters', {})
+        request.delete_header('action_dispatch.request.parameters')
+        request.set_header('action_dispatch.request.formats', [Mime[:json]])
+      end
+
+      def kiosk_render_answer(result)
+        kiosk_fresh_response!
+        @_kiosk_headers.each { |header, value| response.headers[header] = value }
+        render_result(result)
+      end
+
+      def kiosk_propagated_headers(status, headers)
+        return {} unless (200...300).cover?(status)
+
+        PROPAGATED_HEADERS.index_with { headers[it].to_s }.reject { |_, value| value.empty? }
+      end
+
+      def kiosk_read_body(body)
+        raw = +''
+        body.each { |chunk| raw << chunk }
+        raw
+      ensure
+        body.close if body.respond_to?(:close)
+      end
+
+      def kiosk_render_refusal(error)
+        kiosk_fresh_response!
+        render_wire_error(error)
+      end
+
+      # The action's render was read; the wire answer is written into a fresh response.
+      def kiosk_fresh_response!
+        set_response!(self.class.make_response!(request))
+        @_response_body = nil
+      end
+
+      # A route drawn straight at a handler action, not through `kiosk do`, answers 404 `verb_not_found`.
+      def kiosk_refuse_unrouted
+        problem = Errors::VerbNotFound.new(
+          'Kiosk handlers are reachable through the Kiosk wire only',
+          hint: "call the verb's own route — " \
+                "GET #{Kiosk.configuration.mount_path}/<query-name> or " \
+                "POST #{Kiosk.configuration.mount_path}/<action-name>"
+        ).to_problem
+
+        render json: problem, status: :not_found, content_type: Errors::PROBLEM_CONTENT_TYPE
+      end
+
+      # An action's render as the verb's answer: its payload, or the wire error it means.
+      class Answer
+        def initialize(kind, wire_name)
+          @kind      = kind
+          @wire_name = wire_name
+        end
+
+        # A query answers its rows, or a {Page} when `render_kiosk_page` recorded the page facts.
+        def value(status, raw, page)
+          payload = decode(status, raw)
+          return payload unless @kind == :query
+
+          rows!(payload)
+          page ? Page.new(rows: payload, **page) : payload
+        end
+
+        private
+
+        # 2xx → the rendered JSON; otherwise the wire error it means.
+        def decode(status, raw)
+          return parse_json(raw) if status >= 200 && status < 300
+
+          parsed = begin
+            parse_json(raw)
+          rescue Errors::Base
+            nil
+          end
+          raise wire_error(status, parsed)
+        end
+
+        # A query answers an array of rows, paginated or not (§8.2).
+        def rows!(payload)
+          return if payload.is_a?(Array)
+
+          raise Errors::ActionFailed.new(
+            "query #{@wire_name.inspect} answered something that is not an array of rows",
+            hint: 'A query renders a JSON array of rows, paginated or not.'
+          )
+        end
+
+        # A body code travels only when it is in the vocabulary and matches the status; otherwise
+        # the status's lone code decides, and with none it is `action_failed`.
+        def wire_error(status, parsed)
+          error_obj = parsed.is_a?(Hash) && parsed['error'].is_a?(Hash) ? parsed['error'] : nil
+          code = code_for(error_obj, status)
+          return Errors::ActionFailed.new(error_message(parsed, status), hint: error_hint(parsed)) if code.nil?
+
+          extra = error_obj&.except('code', 'message', 'hint')&.transform_keys(&:to_sym)
+          Errors::WireError.new(error_message(parsed, status),
+                                code: code, hint: error_hint(parsed), extra: extra)
+        end
+
+        def code_for(error_obj, status)
+          rendered = error_obj && error_obj['code'].to_s
+          rendered && Errors::CODES[rendered] == status ? rendered : Errors::STATUS_CODES[status]
+        end
+
+        def parse_json(raw)
+          return nil if raw.nil? || raw.strip.empty?
+
+          JSON.parse(raw)
+        rescue JSON::ParserError
+          raise Errors::ActionFailed.new(
+            "#{@kind} #{@wire_name.inspect} rendered a non-JSON body",
+            hint: 'a Kiosk handler answers with `render json:` — HTML, redirects and ' \
+                  '`send_file` have no place on the wire'
+          )
+        end
+
+        # The operator's own message reaches the agent when the body carries one.
+        def error_message(parsed, status)
+          from_body = parsed.is_a?(Hash) ? (parsed['error'] || parsed['message']) : nil
+          from_body = from_body['message'] if from_body.is_a?(Hash)
+          return from_body.to_s unless from_body.nil? || from_body.to_s.empty?
+
+          "#{@kind} #{@wire_name.inspect} answered #{status}"
+        end
+
+        def error_hint(parsed)
+          return nil unless parsed.is_a?(Hash)
+
+          hint = parsed['hint'] || (parsed['error'].is_a?(Hash) ? parsed['error']['hint'] : nil)
+          hint&.to_s
+        end
+      end
+    end
+  end
+end