axn-webhooks 0.1.0

data/lib/axn/webhooks/inbound/endpoint.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Axn
+  module Webhooks
+    module Inbound
+      # A registered inbound webhook endpoint. Verifies a request's signature, dispatches
+      # the (verified, parsed) event to a handler Axn, and maps the pipeline's outcome to an
+      # HTTP Response. Challenge (GET) and Rack mount arrive in a later phase.
+      class Endpoint
+        def initialize(name:, verifier:, dispatch: nil, respond: nil, static_respond: nil, challenge: nil,
+                       unauthorized_headers: nil, challenge_required: nil)
+          if dispatch && dispatch[:mode] == :async && respond
+            raise Axn::Webhooks::Error,
+                  "inbound endpoint `#{name}` declares a custom `respond` but explicit `dispatch mode: :async` " \
+                  "can't produce a handler_result for it to read — use `mode: :sync` (or omit mode) or drop the respond block"
+          end
+
+          if respond && static_respond
+            raise Axn::Webhooks::Error,
+                  "inbound endpoint `#{name}` declares both `respond` and `static_respond` — declare only one; " \
+                  "`respond` reads the handler's result, `static_respond` doesn't and renders on every non-error outcome"
+          end
+
+          @name = name.to_sym
+          @verifier = verifier
+          @dispatch = dispatch
+          @respond = respond
+          @static_respond = static_respond
+          @challenge = challenge
+          @unauthorized_headers = unauthorized_headers
+          @challenge_required = challenge_required
+
+          validate_challenge!
+        end
+
+        attr_reader :name
+
+        # Headers attached to the 401 a verify failure produces. Empty for the signature
+        # strategies — there is nothing for a signing client to be challenged *with* — but
+        # mandatory for HTTP Basic auth (RFC 7617), where a client that doesn't authenticate
+        # preemptively sends its first request bare and repeats it with credentials only after a
+        # 401 carrying `WWW-Authenticate`. Without this the second leg never comes and every
+        # request from such a client is dropped, uniformly and silently.
+        #
+        # An explicit `unauthorized_headers` declaration wins, so a custom `verify` block can
+        # supply its own challenge; otherwise the verifier speaks for itself.
+        def unauthorized_headers
+          return @unauthorized_headers if @unauthorized_headers
+          return @verifier.unauthorized_headers if @verifier.respond_to?(:unauthorized_headers)
+
+          {}
+        end
+
+        # Is this request an authentication attempt at all? When it isn't, there is nothing to
+        # verify — it's a protocol precondition, not a failed verification — and #to_response
+        # answers with the challenge without invoking Verify (PRO-3148). Under a two-legged scheme
+        # like RFC 7617 Basic auth a reactive client sends one such request per *successful*
+        # webhook, so recording them as verify failures made the highest-volume outcome on a healthy
+        # endpoint a recorded failure, and a cross-vendor verify-failure monitor unusable without
+        # knowing which vendors happen to use Basic auth.
+        #
+        # False unless something says otherwise, so the signature strategies — which have no
+        # challenge to offer and no second leg to wait for — are untouched: no predicate means no
+        # ChallengeRequired call either, not merely a false answer from one.
+        #
+        # Note this is NOT the `challenge` declaration (that's the vendor's GET handshake, see
+        # #challenge_response). Same word, different protocol: this one is the 401 kind.
+        def challenge_required?(request)
+          predicate = challenge_predicate
+          return false unless predicate
+
+          # Inside an Axn boundary: the predicate is request-dependent code the gem doesn't own, and
+          # it runs ahead of every other boundary on the POST path. A crash settles not-ok and is read
+          # as "can't tell" -> verify normally (see ChallengeRequired for why that's the safe answer).
+          checked = ChallengeRequired.call(request:, predicate:, vendor: @name)
+          checked.ok? && checked.required
+        end
+
+        # Verify the request's signature. Returns an Axn::Result: ok? when verified,
+        # a failure on mismatch, an exception if the verifier raises.
+        def verify(request)
+          Verify.call(request:, verifier: @verifier, vendor: @name)
+        end
+
+        # Full pipeline: verify, then (if a dispatch is declared and verification passed)
+        # parse + route to the handler. Returns the final Axn::Result.
+        def handle(request)
+          verified = verify(request)
+          return verified unless verified.ok? && @dispatch
+
+          Dispatch.call(request:, router: @dispatch[:router], parse: @dispatch[:parse],
+                        mode: @dispatch[:mode], respond_declared: !@respond.nil?, vendor: @name)
+        end
+
+        # The staged HTTP outcome mapping (spec: "Respond + staged outcome model"). Verify and
+        # dispatch are mapped in separate branches — deliberately NOT a single outcome->status
+        # rule, because a verify failure (401) and a handler business fail! (2xx) are both
+        # `outcome.failure?` but mean opposite things at the HTTP layer.
+        def to_response(request)
+          # Ahead of verify, deliberately: a request that isn't an authentication attempt gets the
+          # challenge rather than a recorded verify failure (see #challenge_required?). Same 401 on
+          # the wire, and it still can't reach a handler — strictly safer than the `done!` that
+          # would settle this leg as a *success*.
+          return Response.new(status: 401, headers: unauthorized_headers) if challenge_required?(request)
+
+          verified = verify(request)
+          return Response.new(status: 401, headers: unauthorized_headers) unless verified.ok?
+          return default_ack unless @dispatch
+
+          dispatched = Dispatch.call(request:, router: @dispatch[:router], parse: @dispatch[:parse],
+                                     mode: @dispatch[:mode], respond_declared: !@respond.nil?, vendor: @name)
+          response_for(dispatched)
+        end
+
+        # The GET branch (spec: the mount owns the whole path, every verb). Testable without a Rack
+        # env, mirroring #verify/#handle/#to_response.
+        def challenge_response(request)
+          return Response.new(status: 405) unless @challenge
+
+          # The Challenge axn computes the exact Response (200 echo / 403 guard-fail / 400 nil).
+          # Only a raising resolver/guard makes it not-ok -> a reported 500.
+          result = Challenge.call(request:, resolver: @challenge[:resolver], guard: @challenge[:guard], vendor: @name)
+          result.ok? ? result.response : Response.new(status: 500)
+        end
+
+        # The Rack app entry point (spec: mount-first packaging). `Inbound[:vendor]` (this object)
+        # is directly `mount`-able in Rails routes.rb or `run`-able in a bare Rack::Builder — the
+        # mount owns the whole path and every verb: POST -> #to_response, GET -> #challenge_response,
+        # anything else -> 405. Named `call`, deliberately reserved since Phase 3 (see #handle).
+        def call(env)
+          built = BuildRequest.call(env:, vendor: @name)
+          return Response.new(status: 500).to_rack unless built.ok?
+
+          request = built.request
+          response =
+            case request.http_method
+            when "POST" then to_response(request)
+            when "GET" then challenge_response(request)
+            else Response.new(status: 405)
+            end
+          response.to_rack
+        end
+
+        private
+
+        # The declared block, else the verifier's own bound predicate, else nil for "nobody claims a
+        # challenge" — the signature strategies and every plain `verify` lambda. Same precedence as
+        # #unauthorized_headers: a declaration wins, so a custom block can speak for a verifier the
+        # gem can't see through.
+        def challenge_predicate
+          return @challenge_required if @challenge_required
+          return @verifier.method(:challenge_required?) if @verifier.respond_to?(:challenge_required?)
+
+          nil
+        end
+
+        # A challenge with nothing in it is the PRO-3146 silent drop: the client is told to retry and
+        # never told how, so every request is dropped forever — and now without even a verify failure
+        # recorded, since answering the challenge skips Verify. Fails the boot rather than shipping an
+        # endpoint that is both broken and invisible.
+        #
+        # Both halves read the *effective* value, not the declaration: a predicate can arrive from a
+        # registered verifier (`Verifiers.register` is public) as easily as from a `challenge_required`
+        # block, and either can be paired with a challenge from the other side. So `verify :basic_auth`
+        # plus a declared predicate is fine, a declared pair is fine, and only an endpoint that claims
+        # a challenge is required without saying what to challenge with lands here.
+        def validate_challenge!
+          return unless challenge_predicate && unauthorized_headers.empty?
+
+          raise Axn::Webhooks::Error,
+                "inbound endpoint `#{@name}` requires a challenge (`challenge_required`, or a verifier that " \
+                "answers `#challenge_required?`) but has no challenge to send — declare `unauthorized_headers`, " \
+                "or the challenged client is never told how to retry"
+        end
+
+        def response_for(dispatched)
+          return Response.service_unavailable(retry_after: dispatched.retry_after) if dispatched.retry_later
+          return default_ack(status: unparseable_status) if unparseable?(dispatched)
+          return Response.new(status: 500) if dispatched.outcome.exception?
+          return default_ack if dispatched.outcome.failure?    # handler fail! -> quiet ack (or static body)
+          return default_ack if dispatched.handler_result.nil? # otherwise: :ack / async enqueue -> ack (or static body)
+          return default_ack unless @respond
+
+          # Run the user's respond block inside the Respond axn so a raise in it (e.g. reading a
+          # missing exposure) becomes a reported 500, not an exception escaping the HTTP mapper.
+          responded = Respond.call(handler_result: dispatched.handler_result, responder: @respond, vendor: @name)
+          responded.ok? ? responded.response : Response.new(status: 500)
+        end
+
+        # A verified request whose body doesn't parse (PRO-3143). Checked ahead of the generic
+        # exception -> 500 branch: it IS an exception outcome (already reported via on_exception, which
+        # is how you learn a vendor is sending garbage), but a retry can never fix malformed bytes, so
+        # the HTTP answer is terminal instead of an invitation to redeliver forever.
+        def unparseable?(dispatched) = dispatched.exception.is_a?(Axn::Webhooks::UnparseableBody)
+
+        # This endpoint's declaration wins over the global setting; see the setting's own comment for
+        # why the default is a 2xx rather than the semantically-tidier 400.
+        def unparseable_status = @dispatch[:unparseable_status] || Axn::Webhooks.config.unparseable_status
+
+        # The bare-ack default, or the declared static_respond body in its place. Every branch
+        # above that used to hardcode `Response.ack` (dispatch.failure?, nil handler_result, no
+        # respond declared, no dispatch at all) now goes through here — static_respond, unlike
+        # respond, has no handler_result to read, so it renders on all of them uniformly.
+        #
+        # `status:` restamps the rendered response, for the one caller (the unparseable-body row) whose
+        # status the gem decides rather than the block. Left nil by every other caller, so a block that
+        # picked its own status — `text("queued", status: 202)` — still keeps it on the success rows.
+        # A raising/non-Response static_respond block is still a 500 here: an internal error in the
+        # endpoint's own body-rendering isn't the vendor's malformed body, and shouldn't be acked as one.
+        def default_ack(status: nil)
+          return Response.ack(status: status || 200) unless @static_respond
+
+          responded = StaticRespond.call(responder: @static_respond, vendor: @name)
+          return Response.new(status: 500) unless responded.ok?
+
+          status ? responded.response.with_status(status) : responded.response
+        end
+      end
+    end
+  end
+end

data/lib/axn/webhooks/inbound/parsers.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Axn
+  module Webhooks
+    # Builds the callable that turns a Request into the parsed `event` a dispatcher routes on.
+    module Parsers
+      module_function
+
+      def build(option)
+        case option
+        when nil, :json then ->(request) { JSON.parse(request.raw_body) }
+        when Proc       then option
+        else raise Axn::Webhooks::Error, "unknown parse option #{option.inspect} (use :json or a proc)"
+        end
+      end
+    end
+  end
+end

data/lib/axn/webhooks/inbound/respond_context.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Axn
+  module Webhooks
+    module Inbound
+      # instance_exec context for a `respond` block: exposes `ack`/`text`/`xml`/`json` as bare calls,
+      # so a respond proc reads `text("...")` rather than `Axn::Webhooks::Response.text("...")` —
+      # mirrors how the `verify` custom block gets `header`/`params`/etc. as bare calls from DSL.
+      class RespondContext
+        def ack(**) = Response.ack(**)
+        def text(body, **) = Response.text(body, **)
+        def xml(body, **) = Response.xml(body, **)
+        def json(body, **) = Response.json(body, **)
+      end
+    end
+  end
+end

data/lib/axn/webhooks/inbound/router.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Axn
+  module Webhooks
+    module Inbound
+      # Resolves a parsed webhook event to the handler to invoke. Pure logic (no Axn) —
+      # a missing constant or an unmatched key with no `otherwise:` raises, and the
+      # Dispatch Axn turns that raise into a reported exception + formatted result.
+      class Router
+        # rubocop:disable Naming/MethodParameterName
+        def initialize(to:, on: nil, otherwise: nil, via: nil)
+          # rubocop:enable Naming/MethodParameterName
+          raise Axn::Webhooks::Error, "dispatch needs a `to:` target" if to.nil?
+
+          @to = to
+          @on = on
+          @otherwise = otherwise
+          @via = via
+        end
+
+        # → [handler_class, kwargs, route_async] for a matched handler, or :ack.
+        def resolve(event)
+          return handler_for(@to, event) if @on.nil?
+
+          key = @on.call(event)
+          @to.is_a?(Hash) ? resolve_mapped(key, event) : resolve_by_convention(key, event)
+        end
+
+        private
+
+        def resolve_mapped(key, event)
+          entry = @to.fetch(key) { return unmatched(key, event) }
+          handler_for(entry, event)
+        end
+
+        def resolve_by_convention(key, event)
+          transform = @via || method(:default_transform)
+          [constantize("#{@to}::#{transform.call(key)}"), { event: }, nil]
+        end
+
+        def handler_for(entry, event)
+          case entry
+          when String, Module then [constantize(entry), { event: }, nil]
+          when Hash
+            [constantize(entry.fetch(:call)), args_for(entry, event), route_async(entry)]
+          else
+            raise Axn::Webhooks::Error, "invalid dispatch target: #{entry.inspect}"
+          end
+        end
+
+        # Handler kwargs from a map entry: no `with:` passes the whole event as `event:`, a Symbol
+        # passes it under that name instead (for endpoints whose parsed object isn't naturally an
+        # "event" — e.g. a Slack interaction `payload`), and a callable projects it to whatever it
+        # returns. Non-callables raise here rather than NoMethodError-ing on `.call`.
+        def args_for(entry, event)
+          return { event: } unless entry.key?(:with)
+
+          extractor = entry.fetch(:with)
+          return { extractor => event } if extractor.is_a?(Symbol)
+
+          raise Axn::Webhooks::Error, "dispatch entry `with:` must be a Symbol or a callable (got #{extractor.inspect})" unless extractor.respond_to?(:call)
+
+          extractor.call(event)
+        end
+
+        def unmatched(key, event)
+          case @otherwise
+          when :ack then :ack
+          when nil  then raise Axn::Webhooks::Error, "no handler for webhook event #{key.inspect} (and no `otherwise:`)"
+          else
+            @otherwise.call(event) # user callable (e.g. alerting); return value ignored
+            :ack
+          end
+        end
+
+        # Optional per-route sync/async opt-out from a map entry: true=async, false=sync,
+        # absent=nil (no opinion — Dispatch falls through to endpoint mode / respond default).
+        def route_async(entry)
+          return nil unless entry.key?(:async)
+
+          value = entry.fetch(:async)
+          return value if [true, false, nil].include?(value)
+
+          raise Axn::Webhooks::Error, "dispatch entry `async:` must be true or false (got #{value.inspect})"
+        end
+
+        # Accepts a class-name String (resolved late) or a Class/Module target. A named Module is
+        # re-resolved via const_get on EVERY call, so a class object passed at declaration time stays
+        # reload-safe under Rails/Zeitwerk (a captured object would go stale when the constant is
+        # reassigned on reload). A target whose name doesn't actually resolve to a constant — a truly
+        # anonymous class (name.nil?), or an Axn::Factory product (whose debug name is a String but was
+        # never assigned to a constant) — has nothing to re-resolve by, so it's used as-is.
+        def constantize(target)
+          return Object.const_get(target) unless target.is_a?(Module)
+
+          name = target.name
+          name && Object.const_defined?(name) ? Object.const_get(name) : target
+        end
+
+        def default_transform(key) = key.to_s.split(/[._]/).reject(&:empty?).map(&:capitalize).join
+      end
+    end
+  end
+end

data/lib/axn/webhooks/inbound.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative "inbound/dsl"
+require_relative "inbound/endpoint"
+require_relative "inbound/router"
+
+module Axn
+  module Webhooks
+    # Process-global registry of inbound webhook endpoints, populated by
+    # `Axn::Webhooks.inbound(:vendor) { ... }` and looked up as `Inbound[:vendor]`.
+    module Inbound
+      @registry = {}
+      # declaration name => the registry keys it owns. Once one `inbound :slack` can produce N
+      # endpoints, re-declaring it has to be able to REMOVE keys, not just overwrite them.
+      @declared = {}
+      # registry key => the declaration that CURRENTLY owns it. Needed because two declarations can
+      # generate the same endpoint name, and a stale claim must never delete a live route.
+      @owners = {}
+
+      class << self
+        def register(name, endpoint) = @registry[name.to_sym] = endpoint
+        def [](name) = @registry.fetch(name.to_sym) { raise KeyError, "no inbound webhook registered for #{name.inspect}" }
+        def registered = @registry.keys
+
+        # Publish everything one `inbound <name>` declaration defines, dropping whatever that same
+        # declaration registered last time. Covers every transition — fewer children, more children,
+        # nested becoming plain, plain becoming nested — each of which previously left a route
+        # mounted with its old verifier and handler (Codex review).
+        #
+        # Reclaims only the keys this declaration STILL owns. Two declarations can generate the same
+        # endpoint name (`inbound :slack` with `endpoint(:events)` vs. a plain `inbound
+        # :slack_events`); last writer wins, which predates nesting — but without the ownership
+        # check, re-declaring the FIRST one would then delete the second one's live route and not
+        # restore it. That deletion is not pre-existing: before this bookkeeping, registration only
+        # ever overwrote (Codex review). A takeover warns rather than raising: the collision is
+        # recoverable, and the endpoint that loses is named so it can be found.
+        def replace_declaration(name, endpoints)
+          key = name.to_sym
+
+          (@declared[key] || []).each do |registered_name|
+            next unless @owners[registered_name] == key
+
+            @registry.delete(registered_name)
+            @owners.delete(registered_name)
+          end
+
+          endpoints.each do |endpoint_name, endpoint|
+            warn_takeover(endpoint_name, key) if @owners.key?(endpoint_name) && @owners[endpoint_name] != key
+            @registry[endpoint_name] = endpoint
+            @owners[endpoint_name] = key
+          end
+
+          @declared[key] = endpoints.keys
+        end
+
+        def reset!
+          @registry.clear
+          @declared.clear
+          @owners.clear
+        end
+
+        private
+
+        def warn_takeover(endpoint_name, new_owner)
+          Axn.config.logger.warn(
+            "[axn-webhooks] inbound endpoint #{endpoint_name.inspect} is now registered by " \
+            "`inbound #{new_owner.inspect}`, replacing the one from `inbound #{@owners[endpoint_name].inspect}` — " \
+            "two declarations generate the same endpoint name",
+          )
+        end
+      end
+    end
+
+    # Declare an inbound webhook endpoint. Evaluated at boot (e.g. a Rails initializer)
+    # so registration is deterministic, in or out of Rails.
+    #
+    # With one or more nested `endpoint` blocks, this registers one endpoint per child, named
+    # :"#{name}_#{child}", and does NOT register `name` itself — see Inbound::DSL#endpoint.
+    def self.inbound(name, &block)
+      raise ArgumentError, "Axn::Webhooks.inbound requires a block" unless block
+
+      dsl = Inbound::DSL.new
+      dsl.instance_exec(&block)
+      children = dsl.__children__
+      return Inbound.replace_declaration(name, { name.to_sym => build_endpoint(name, dsl) }) if children.empty?
+
+      # A parent with children is a container, not an endpoint. A top-level `dispatch` is what
+      # would make it look like one, and registering both it and the children would leave an extra
+      # endpoint nobody mounted, silently — so that combination is a declaration mistake, caught at
+      # boot. A parent `respond`/`static_respond` is NOT: it renders nothing on its own, and
+      # sharing one renderer across a vendor's endpoints is precisely what nesting is for, so it
+      # inherits like every other declaration (Codex review).
+      if dsl.__dispatch_declared?
+        raise ArgumentError,
+              "inbound #{name.inspect} declares `endpoint` blocks AND its own `dispatch` — a parent " \
+              "with endpoints registers nothing itself; move the dispatch into an endpoint"
+      end
+
+      # Build and validate EVERY child before publishing any: the registry is process-global, so
+      # registering as we go left earlier children live when a later one raised — a rescued
+      # declaration failure or a reload would mix endpoints from different declarations
+      # (Codex review).
+      built = children.map { |child, child_block| [:"#{name}_#{child}", build_endpoint(:"#{name}_#{child}", dsl.__child_dsl__(child_block))] }
+      Inbound.replace_declaration(name, built.to_h)
+    end
+
+    # Each child is a complete, independently valid endpoint by the time it gets here, so the
+    # existing per-endpoint validation (__verifier__'s "declared no `verify`" check, Endpoint's
+    # respond/static_respond exclusivity) runs per child, unchanged.
+    def self.build_endpoint(name, dsl)
+      Inbound::Endpoint.new(
+        name:,
+        verifier: dsl.__verifier__,
+        dispatch: dsl.__dispatch__,
+        respond: dsl.__respond__,
+        static_respond: dsl.__static_respond__,
+        challenge: dsl.__challenge__,
+        unauthorized_headers: dsl.__unauthorized_headers__,
+        challenge_required: dsl.__challenge_required__,
+      )
+    end
+    private_class_method :build_endpoint
+  end
+end

data/lib/axn/webhooks/outbound/callable_arity.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Axn
+  module Webhooks
+    module Outbound
+      # Whether `callable.call(*args)` actually works for exactly `count` positional arguments — via
+      # `#parameters`, which correctly distinguishes required/optional/rest/keyword params uniformly
+      # across a lambda, a non-strict Proc, and a plain object's `#call` Method. `#arity` alone can't
+      # tell "one required positional" apart from "one required KEYWORD" (same arity, one raises) or
+      # "needs 2+ positional, has a splat" (negative arity, but still too few args at `count == 1`) —
+      # both boot-time-valid under a bare arity check, both raising `ArgumentError` on the very first
+      # real invocation (Codex P2 findings, on `backoff`, `user_agent`, and the signing `secret`).
+      module CallableArity
+        module_function
+
+        def accepts?(callable, count)
+          params = callable.respond_to?(:parameters) ? callable.parameters : callable.method(:call).parameters
+          return false if params.any? { |(type, _)| type == :keyreq }
+
+          required = params.count { |(type, _)| type == :req }
+          return false if required > count
+
+          optional = params.count { |(type, _)| type == :opt }
+          rest = params.any? { |(type, _)| type == :rest }
+          required + optional + (rest ? 1 : 0) >= count
+        end
+
+        # Which keyword names `callable.call(**kwargs)` actually accepts: `:all` for a callable that
+        # double-splats (accepts anything), else the Array of Symbol names it declares (required and
+        # optional alike). Used to filter a fixed kwarg set down to what a caller-supplied signing
+        # block declares (`CustomSigner`), so a block written against today's `(id:, timestamp:,
+        # body:)` contract keeps working byte-for-byte when a widened caller starts also offering
+        # `url:`/`subscriber:` — those become a plain ArgumentError from a *filtered* call, not a
+        # silent widening the block didn't ask for.
+        def accepted_keywords(callable)
+          params = callable.respond_to?(:parameters) ? callable.parameters : callable.method(:call).parameters
+          return :all if params.any? { |(type, _)| type == :keyrest }
+
+          params.select { |(type, _)| %i[key keyreq].include?(type) }.map { |(_, name)| name }
+        end
+
+        # Which keyword names `callable.call(**kwargs)` REQUIRES — a strict subset of
+        # `accepted_keywords` (excludes optional `:key` params). Used to catch a callable that
+        # needs a keyword outside a fixed supplied set (e.g. `sign { |id:, vendor:| … }`, where
+        # `vendor:` is never one of the kwargs this gem passes a signer) — the one shape that
+        # genuinely fails on every call, as opposed to a callable that simply ignores some/all of
+        # what it's offered (which Ruby's own Proc/block semantics already tolerate fine).
+        def required_keywords(callable)
+          params = callable.respond_to?(:parameters) ? callable.parameters : callable.method(:call).parameters
+          params.select { |(type, _)| type == :keyreq }.map { |(_, name)| name }
+        end
+
+        # The ORIGINAL `subscribers`/`to:` resolver dispatch rule, preserved byte-for-byte (Codex P2
+        # finding): "pass the event unless the callable's raw arity is EXACTLY zero." Deliberately
+        # raw #arity, not #parameters-based: a Proc (non-lambda) with a single OPTIONAL/default
+        # param reports arity `0` (a Ruby quirk -- lambda-with-default reports NEGATIVE instead),
+        # and that quirk is exactly what a pre-existing `proc { |event = :all| … }` resolver already
+        # relied on to keep using its own default. Only made callable-object-safe here (falls back
+        # to `Method#arity` via `#call`) -- the dispatch RULE itself is unchanged.
+        def zero_arity?(callable)
+          raw_arity(callable).zero?
+        end
+
+        # For a newly-introduced 0-OR-1-arity callable (PRO-3214's per-subscriber `secret`/
+        # `headers`): prefer a zero-arg call whenever genuinely possible. Raw arity, not
+        # `#parameters`-based `accepts?`: a plain `proc { |subscriber| … }` (NO default) reports its
+        # param as `:opt` via `#parameters` -- indistinguishable from a genuine default by that
+        # API -- but its raw arity is still the correct POSITIVE `1`, so this is the one signal that
+        # tells "has a real default/rest" apart from "merely tolerates a missing arg, Proc-style,
+        # but was never given one to default from" (Codex P1 finding: passing `nil` in place of the
+        # subscriber for exactly this shape).
+        #
+        # ONLY arity `0` (a truly empty/all-defaulted signature) or `-1` (Ruby's `-(required + 1)`
+        # encoding with `required == 0` -- zero REQUIRED params, any number of optional/rest ones)
+        # genuinely means "callable with zero args". A more negative arity still has a required
+        # LEADING param: `->(subscriber, cache = nil)` is arity `-2` (required == 1) and raises if
+        # actually called with zero args -- `arity <= 0` wrongly matched it too (Codex P1 finding,
+        # round 5: passed nothing, so a resolver shaped exactly like this raised on every attempt).
+        def prefers_zero_args?(callable)
+          [0, -1].include?(raw_arity(callable))
+        end
+
+        # Shared by `zero_arity?`/`prefers_zero_args?`: raw `#arity`, falling back to
+        # `Method#arity` via `#call` for a plain callable object with none of its own.
+        def raw_arity(callable)
+          callable.respond_to?(:arity) ? callable.arity : callable.method(:call).arity
+        end
+
+        # Whether `callable` declares at least one POSITIONAL parameter (required, optional, or
+        # rest) -- used by `Signer::CustomSigner` to detect the historical "single options-hash
+        # positional" custom-signer shape (`sign { |options| … }`, no keyword params at all).
+        def accepts_positional?(callable)
+          params = callable.respond_to?(:parameters) ? callable.parameters : callable.method(:call).parameters
+          params.any? { |(type, _)| %i[req opt rest].include?(type) }
+        end
+      end
+    end
+  end
+end