axn-webhooks 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6afafb259befddc2850cf02b18286b55948c9e061c1e07377203dd5430c75f77
-  data.tar.gz: 79bf28d109278e3c6a63a22093758e32f02496e9747edebcf33cbaf8c8ec0635
+  metadata.gz: c8b8fbe499b148a37eeebd9a111dd27343dd39618c11ebf00c2d01b0c5a21a30
+  data.tar.gz: 99a2eb19546c6f49ec060811cfa83d0b063e0bf1dc77a8156843c4da6197e1fe
 SHA512:
-  metadata.gz: ccea01ad6d3b8f9da8347466c715b843e87d3a638f6851d025dba9258e83256e8d51f00ad4b065cf3e1c6a5f8a12f8640c2b883f0dda77065ffa0c3f0699508f
-  data.tar.gz: a1460ca78f2eeb544e90728e4c559d2c1e473cd4ddd5ba197aa3cc8d2a92f93d42e325628baa3480dd012e848fb34a0ab53dfd3132351bd3f0aae0409aaff5aa
+  metadata.gz: aa876a263ff34769f2e442483b67709a62efeaa3bd1f270b5fd72329497a98726098213d0644458f1f813fc4d7d2299c1c2d7c47f5ddcfbf8086add4d1dd2619
+  data.tar.gz: 85dd9e4689f05f29cca902ac947d93db1ec76323ba1ab47427468d3918c6bb5805ecdbcdbb09aa44cc30ebe5832ef8c9c864bd3adb125b941053a26078c9c1dd

data/CHANGELOG.md

@@ -7,6 +7,28 @@ All notable changes to this project are documented here. This project adheres to
 
 _Nothing yet._
 
+## [0.1.1] - 2026-09-03
+
+_Prepared, not yet tagged — the version is cut immediately on merge. Update this date if that slips._
+
+### Observability
+
+- Bumped the `axn` floor to `>= 0.1.0-alpha.6` for `Axn::Extensions::InvokedVia`. Every public
+  `Endpoint` entrypoint — `#call` (the Rack app), `#handle`, `#to_response`, `#challenge_response`,
+  `#verify`, and `#challenge_required?` (the controller-driven alternatives README/DESIGN-NOTES
+  document alongside mounting) — now wraps itself in `InvokedVia.with(:webhooks)`, so every axn in a
+  request's call tree — `BuildRequest`,
+  `ChallengeRequired`, `Verify`, `Dispatch`, `Respond`/`StaticRespond`, `Challenge`, and the consuming
+  app's own handler axn — is stamped with an `invoked_via: :webhooks` dimension regardless of which
+  entrypoint a caller uses, with no per-class opt-in required (unlike the
+  [vendor facet](#per-vendor-observability), which is declared per-class and threaded through
+  explicitly). Wraps nest safely, so calling one entrypoint from another (e.g. `#call` -> `#to_response`
+  -> `#verify`) re-stamps the same value harmlessly.
+- Known gap, not addressed here: a route dispatched via `:auto`/`:async` mode enqueues a background
+  job from inside the wrapped tree, so the *enqueue* is tagged — but the job's *performed* execution
+  runs in a separate process, outside the ambient stamp's scope, so the handler's own execution
+  metrics won't carry `invoked_via` in that mode.
+
 ## [0.1.0] - 2026-08-24
 
 _Prepared, not yet tagged — the version is cut immediately on merge. Update this date if that slips._

data/README.md

@@ -621,6 +621,28 @@ This governs the **vendor** facet only. The [`reason` dimension](#why-verificati
 stamped — it's a closed enum, so there's no cardinality decision to defer. Group by `reason`, filter
 by `vendor`.
 
+## Entry-point attribution
+
+Every inbound request — however it arrives, the mounted Rack app (`#call`) or one of the
+controller-driven entrypoints (`#verify`, `#handle`, `#to_response`, `#challenge_response`,
+`#challenge_required?`; see [Mounting](#mounting)) — is wrapped in [`axn`](https://github.com/teamshares/axn)'s
+`Axn::Extensions::InvokedVia.with(:webhooks)`. Each entrypoint carries its own wrap (they nest safely,
+so `#call` calling into `#to_response` calling into `#verify` just re-stamps the same value), which
+stamps an `invoked_via: "webhooks"` dimension on the *whole* call tree reached from wherever a caller
+enters: `BuildRequest`, `ChallengeRequired`, `Verify`, `Dispatch`, `Respond`/`StaticRespond`,
+`Challenge`, and — with no opt-in required — the handler axn your `dispatch` block routes to. Unlike
+the [vendor facet](#per-vendor-observability) above, there's no config flag: it's always on, and no
+per-class declaration is needed, because `InvokedVia` is ambient rather than a value threaded through
+each `.call`.
+
+This lets a Datadog/OTel dashboard separate webhook-driven traffic from an Axn class's other callers
+without that class knowing it's mounted behind a webhook at all.
+
+One gap: a route dispatched with `mode: :auto`/`:async` enqueues the handler as a background job from
+*inside* the wrapped call tree, so the enqueue itself is tagged — but the job's **performed**
+execution runs in a separate process, outside the ambient stamp's scope, so the handler's own
+execution metrics won't carry `invoked_via` in that mode.
+
 ---
 
 # Outbound

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

@@ -65,62 +65,84 @@ module Axn
         #
         # 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.
+        #
+        # DESIGN-NOTES.md documents this as public for controllers driving #verify/#handle
+        # themselves, so — like them — it carries its own InvokedVia wrap (Codex review, PR #31).
         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
+          Axn::Extensions::InvokedVia.with(:webhooks) do
+            # 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 safe).
+            checked = ChallengeRequired.call(request:, predicate:, vendor: @name)
+            checked.ok? && checked.required
+          end
         end
 
         # Verify the request's signature. Returns an Axn::Result: ok? when verified,
         # a failure on mismatch, an exception if the verifier raises.
+        #
+        # A standalone entrypoint too (README: "drive it yourself from a controller"), so it carries
+        # its own InvokedVia wrap — nests harmlessly when reached via #handle/#to_response/#call, which
+        # already wrap themselves.
         def verify(request)
-          Verify.call(request:, verifier: @verifier, vendor: @name)
+          Axn::Extensions::InvokedVia.with(:webhooks) { 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.
+        #
+        # A second, independent entrypoint alongside #call (the Rack app) — not called from it, so it
+        # carries its own Axn::Extensions::InvokedVia wrap rather than inheriting one.
         def handle(request)
-          verified = verify(request)
-          return verified unless verified.ok? && @dispatch
+          Axn::Extensions::InvokedVia.with(:webhooks) do
+            verified = verify(request)
+            next verified unless verified.ok? && @dispatch
 
-          Dispatch.call(request:, router: @dispatch[:router], parse: @dispatch[:parse],
-                        mode: @dispatch[:mode], respond_declared: !@respond.nil?, vendor: @name)
+            Dispatch.call(request:, router: @dispatch[:router], parse: @dispatch[:parse],
+                          mode: @dispatch[:mode], respond_declared: !@respond.nil?, vendor: @name)
+          end
         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.
+        #
+        # Also a standalone entrypoint (README: "drive it yourself from a controller") reachable
+        # without going through #call, so it carries its own InvokedVia wrap (Codex review, PR #31).
         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)
+          Axn::Extensions::InvokedVia.with(:webhooks) do
+            # 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*.
+            next Response.new(status: 401, headers: unauthorized_headers) if challenge_required?(request)
+
+            verified = verify(request)
+            next Response.new(status: 401, headers: unauthorized_headers) unless verified.ok?
+            next 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
         end
 
         # The GET branch (spec: the mount owns the whole path, every verb). Testable without a Rack
-        # env, mirroring #verify/#handle/#to_response.
+        # env, mirroring #verify/#handle/#to_response — and, like them, a standalone entrypoint that
+        # carries its own InvokedVia wrap rather than relying on #call.
         def challenge_response(request)
-          return Response.new(status: 405) unless @challenge
+          Axn::Extensions::InvokedVia.with(:webhooks) do
+            next 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)
+            # 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
         end
 
         # The Rack app entry point (spec: mount-first packaging). `Inbound[:vendor]` (this object)
@@ -128,17 +150,19 @@ module Axn
         # 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
+          Axn::Extensions::InvokedVia.with(:webhooks) do
+            built = BuildRequest.call(env:, vendor: @name)
+            next 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
         end
 
         private

data/lib/axn/webhooks/version.rb

@@ -2,6 +2,6 @@
 
 module Axn
   module Webhooks
-    VERSION = "0.1.0"
+    VERSION = "0.1.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: axn-webhooks
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Kali Donovan
@@ -15,7 +15,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0.pre.alpha.5
+        version: 0.1.0.pre.alpha.6
     - - "<"
       - !ruby/object:Gem::Version
         version: 0.2.0
@@ -25,7 +25,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0.pre.alpha.5
+        version: 0.1.0.pre.alpha.6
     - - "<"
       - !ruby/object:Gem::Version
         version: 0.2.0