deployangel 0.1.35 → 0.1.37

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 275f765f13eee93ddc36007727d1f2278b343a524562c062eeab1a258f8abb16
-  data.tar.gz: f167ad720f710b5cf3a527632795972a5dbbe972309bbbf470a937425d0282e7
+  metadata.gz: 618c24521dbd9aa6102fdd7c3a6c105494abcde74072fa37d8bd2e27f2737f49
+  data.tar.gz: 55e402796d95fe4aee557b342fcb0814933b9f39c965bba504b160fdaf557c0d
 SHA512:
-  metadata.gz: cdd30481a4d28645ef05f5d570f253d73029258581743045677e5a7e1c19a395b28082656aa44f588eac2c8be074b01a93240102143a822d166fa250325efd93
-  data.tar.gz: 5190303791d16fb83affbed23cd01e5b20c1b28a245f94824ee9f01670ec454a9b6c9696d632cabc3ce7c0990da8d0809adb14b7c3eddeda7aa8a5ec077f7f54
+  metadata.gz: 4df4ece416d4c1d16729bbaaff61c0e196d3635796f1a743b754b189d91109891c38232bd484e1240fa55a28db6c85898a3b550fd3bd781337de4f05d18ecfc3
+  data.tar.gz: 4a523fc4d15f677b80671a3a09490e267ad1c322fcd0b45d7f2c37dd68ea54586c36efd6204e22f2d20cea15185a2d2072c53bf5f0857fa5011442198ad61431

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.1.37 (2026-11-03)
+
+- An exception raised entirely in gems, with no frame from the app's
+  code, now sends its first library frames as its stack trace
+  (`net-smtp/lib/net/smtp.rb#start`), normalized like the top frame, with
+  no absolute paths or versions. Before, it sent none, so an error such as
+  a mailer job's `Net::ReadTimeout` showed no trace.
+
+## 0.1.36 (2026-11-01)
+
+- `deployangel exercise --param id=42` fills path parameters (`:id`,
+  `{id}`, `<int:id>`), so routes like `GET /apps/:app_id/deployments/:id`
+  can be exercised. Skipped routes name the parameters they need.
+- `deployangel exercise --header="Name: value"`, or
+  `DEPLOYANGEL_EXERCISE_HEADERS` (one per line), sends headers with every
+  request, such as a Bearer token or a test account's session cookie. The
+  output names them but never shows their values, and they go only to the
+  `--url` host.
+
 ## 0.1.35 (2026-11-01)
 
 - `deployangel exercise` prints each route's status codes (`404 ×1`)

data/README.md

@@ -149,7 +149,8 @@ the dashboard says so.
 - Release identity, runtime versions, and a per-process instance ID.
 
 - Exceptions: a stable fingerprint, the exception class, the first line of the
-  message, and application frames only. In the message, numbers, IDs, emails,
+  message, and application frames only, or the first library frames (gem
+  paths without versions) when none is the app's. In the message, numbers, IDs, emails,
   UUIDs, long hex strings, and quoted values are replaced with placeholders, and
   so are the request's host and, with ros-apartment, the tenants the request or
   job switched to. Other words are kept: `Payment failed for Jane Doe` is sent
@@ -238,7 +239,7 @@ end
 ### Exception messages
 
 To send exceptions without any message, only their class, fingerprint, and
-application frames:
+stack frames:
 
 ```ruby
 DeployAngel.configure do |config|
@@ -597,8 +598,8 @@ evidence. A release deployed during an app's first 24 hours can't clear,
 so its plan lists nothing.
 
 `deployangel exercise --url=<production URL>` does the read-only part for
-you, from wherever it runs: it requests the plan's GET routes that have no
-path parameters, spreading any request shortfall across them (at most 200
+you, from wherever it runs: it requests the plan's GET routes whose path
+parameters it can fill, spreading any request shortfall across them (at most 200
 requests, about 5 a second, as `DeployAngel-Exercise`), then records what it
 sent on the release, where the page lists it under "Exercised from your
 side". It skips and names routes that change data or need a path
@@ -608,6 +609,19 @@ every page answers 404, 405, or 410, it records nothing and exits 5, since
 the URL is probably not the app's own host (a marketing site, say). A "CLI
 & coding agents" token can run it. `--dry-run` shows what it would send.
 
+`--param id=42` fills a path parameter (`:id`, `{id}`, `<int:id>`) in every
+route that has it, so `--param app_id=3 --param id=212` reaches
+`GET /apps/:app_id/deployments/:id`. A value fills every route with that
+name, so a wrong one just gets a 404 and no more requests.
+
+`--header="Name: value"` sends a header with every request, such as
+`Authorization: Bearer …` for an API or a test account's session cookie for
+signed-in pages. Put secrets in `DEPLOYANGEL_EXERCISE_HEADERS` instead (one
+header per line), which keeps them out of shell history. Headers go only to
+the `--url` host, since redirects aren't followed. The output names them
+but never shows their values, and they're never sent to DeployAngel. Use a
+test account with as little access as possible: its cookie is a full sign-in.
+
 ### Suggested instructions for your coding agent
 
 `deployangel install agents` adds instructions like these. To add them
@@ -639,8 +653,9 @@ verdict: call the `wait_for_verification` MCP tool with the commit and
   If its status is "exercisable" or "waiting_for_activity", run
   `bundle exec deployangel exercise --url=<production URL>`: it sends the
   plan's read-only requests and records them on the release. Offer to
-  exercise what it skips: routes that change data only with a test account
-  or after asking. If the status is "warm_up", nothing run can clear it.
+  exercise what it skips: fill a route's IDs with `--param name=value`,
+  using an ID you can see in the app, and run routes that change data only
+  with a test account or after asking. If the status is "warm_up", nothing run can clear it.
 ```
 
 ## Development

data/lib/deployangel/cli.rb

@@ -34,7 +34,8 @@ module DeployAngel
         plan       What to exercise so a release  [--commit=SHA | --version=V | --deployment=ID]
                    clears sooner                 [--format=text|json]
         exercise   Send the plan's read-only      --url=PRODUCTION_URL [--commit=SHA | --version=V | --deployment=ID]
-                   requests to production        [--max-requests=200] [--dry-run]
+                   requests to production        [--param=NAME=VALUE] [--header="Name: value"]
+                                                 [--max-requests=200] [--dry-run]
         exception  Details for a fingerprint     deployangel exception FINGERPRINT
         check      Report a smoke test result    --name=NAME --status=pass|fail [--covers=a,b]
                                                  [--commit=SHA | --deployment=ID] [--details-url=URL]
@@ -116,8 +117,9 @@ module DeployAngel
         If its status is "exercisable" or "waiting_for_activity", run
         `bundle exec deployangel exercise --url=<production URL>`: it sends the
         plan's read-only requests and records them on the release. Offer to
-        exercise what it skips: routes that change data only with a test account
-        or after asking. If the status is "warm_up", nothing run can clear it.
+        exercise what it skips: fill a route's IDs with `--param name=value`,
+        using an ID you can see in the app, and run routes that change data only
+        with a test account or after asking. If the status is "warm_up", nothing run can clear it.
       - Confidence `medium` clears a release just as `high` does (high also needs 80%
         coverage and a full baseline), so don't call a medium clearance weak.
         Warnings (`suspicious: true`) aren't failures: report them as "watching
@@ -282,8 +284,10 @@ module DeployAngel
       # Sends the plan's read-only requests from here, then records what it
       # sent on the release (spec §16, Exercise records).
       def exercise
-        options = parse(max_requests: Exerciser::MAX_REQUESTS, dry_run: false) do |o, opts|
+        options = parse(max_requests: Exerciser::MAX_REQUESTS, dry_run: false, headers: [], params: []) do |o, opts|
           o.on("--url=URL") { |v| opts[:url] = v }
+          o.on("--header=HEADER") { |v| opts[:headers] << v }
+          o.on("--param=NAME=VALUE") { |v| opts[:params] << v }
           o.on("--commit=SHA") { |v| opts[:commit] = v }
           o.on("--version=VERSION") { |v| opts[:version] = v }
           o.on("--deployment=ID") { |v| opts[:deployment_id] = v }
@@ -292,6 +296,15 @@ module DeployAngel
         end
         return usage_error("exercise needs --url, the app's production URL, like https://example.com") unless options[:url].to_s.match?(%r{\Ahttps?://[^/\s]+})
 
+        # DEPLOYANGEL_EXERCISE_HEADERS, one per line, keeps a secret out of
+        # shell history and the process list.
+        begin
+          headers = Exerciser.parse_headers(options[:headers] + @env["DEPLOYANGEL_EXERCISE_HEADERS"].to_s.split("\n"))
+          params = Exerciser.parse_params(options[:params])
+        rescue ArgumentError => e
+          return usage_error(e.message)
+        end
+
         target = target_from(options)
         return usage_error("no target: pass --commit, --version, or --deployment, or run inside a git repository") unless target
 
@@ -308,19 +321,22 @@ module DeployAngel
           return 0
         end
 
-        exerciser = Exerciser.new(base_url: options[:url], max_requests: options[:max_requests].clamp(1, Exerciser::MAX_REQUESTS),
+        exerciser = Exerciser.new(base_url: options[:url], headers: headers, params: params, max_requests: options[:max_requests].clamp(1, Exerciser::MAX_REQUESTS),
           sleeper: @sleeper, requester: @requester)
+        header_names = ("With headers: #{headers.keys.join(", ")} (values not shown)" if headers.any?)
         if options[:dry_run]
           targets, skipped = exerciser.plan(plan)
           @stdout.puts("Would send #{targets.sum(&:count)} requests:", *targets.map { |t| "  #{exerciser.url_for(t.path)} ×#{t.count}" })
-          @stdout.puts("Skipped:", *skipped.map { |s| "  #{s["key"]} (#{s["reason"]})" }) if skipped.any?
+          @stdout.puts(header_names) if header_names
+          print_skipped(skipped)
           return 0
         end
 
         result = exerciser.run(plan)
         @stdout.puts("Sent #{result.sent} requests to #{options[:url]}:",
           *result.routes.map { |r| "  #{r["key"]} ×#{r["requests"]}: #{status_codes(result.codes[r["key"]])}" })
-        @stdout.puts("Skipped:", *result.skipped.map { |s| "  #{s["key"]} (#{s["reason"]})" }) if result.skipped.any?
+        @stdout.puts(header_names) if header_names
+        print_skipped(result.skipped)
         @stdout.puts("Stopped early: #{options[:url]} isn't answering.") if result.unreachable
         # Requests that reached no page aren't worth recording: the app
         # likely never saw them.
@@ -332,12 +348,23 @@ module DeployAngel
           return USAGE_ERROR
         end
         if result.routes.any?
-          client.record_exercise(document.dig("deployment", "id"), routes: result.routes, skipped: result.skipped, ran_at: @clock.call.utc.iso8601)
+          client.record_exercise(document.dig("deployment", "id"), routes: result.routes,
+            skipped: result.skipped.map { |s| s.except("missing") }, ran_at: @clock.call.utc.iso8601)
           @stdout.puts("Recorded on the release. Wait for the verdict with: deployangel verify --wait")
         end
         result.unreachable ? USAGE_ERROR : 0
       end
 
+      # Each skipped route and why, naming the parameters a --param would fill.
+      def print_skipped(skipped)
+        return if skipped.empty?
+
+        @stdout.puts("Skipped:", *skipped.map { |s| "  #{s["key"]} (#{s["reason"]}#{": #{s["missing"].join(", ")}" if s["missing"]&.any?})" })
+        return unless skipped.any? { |s| s["missing"]&.any? }
+
+        @stdout.puts("Fill path parameters with --param, such as --param #{skipped.find { |s| s["missing"]&.any? }["missing"].first}=42.")
+      end
+
       # "200 ×4, 500 ×1", in the order they came.
       def status_codes(codes)
         codes.map { |code, n| "#{code || "no answer"} ×#{n}" }.join(", ")

data/lib/deployangel/core/fingerprint.rb

@@ -46,10 +46,14 @@ module DeployAngel
       "#{normalize_path(path, root)}##{label}"
     end
 
-    # Application frames only, relative to the root.
+    # Application frames only, relative to the root. An exception raised
+    # entirely in gems (a mailer job's SMTP timeout) has none, so it gets its
+    # first frames instead, normalized as in top_frame: they're the only way
+    # to tell which gem's path failed.
     def backtrace(exception, root:)
-      locations(exception).select { |path, _| app_path?(path, root) }.first(MAX_BACKTRACE)
-        .map { |path, label| "#{normalize_path(path, root)}##{label}" }
+      frames = locations(exception)
+      app = frames.select { |path, _| app_path?(path, root) }
+      (app.empty? ? frames : app).first(MAX_BACKTRACE).map { |path, label| "#{normalize_path(path, root)}##{label}" }
     end
 
     # Only quoted values, numbers, emails, UUIDs, and long hex are replaced;

data/lib/deployangel/exerciser.rb

@@ -7,9 +7,10 @@ module DeployAngel
   # `deployangel exercise`: sends a release's exercise plan's read-only
   # requests to production from the customer's side, then records what it
   # sent, so the release page says which routes were exercised that way.
-  # Only GET routes with no path parameters and not marked as changing data;
-  # the rest are skipped and named, for the agent or a smoke test with a test
-  # account. The requests count like any traffic through the app's agent.
+  # Only GET routes not marked as changing data, and only those whose path
+  # parameters the caller filled (--param id=42); the rest are skipped and
+  # named, for the agent or a smoke test with a test account. The requests
+  # count like any traffic through the app's agent.
   class Exerciser
     MAX_REQUESTS = 200
     INTERVAL = 0.2 # about 5 requests a second
@@ -19,8 +20,14 @@ module DeployAngel
     # A route table can list pages an app doesn't serve, like the edit page
     # of a resource that has none. One answer like this is enough to know.
     NOT_SERVED = [ 404, 405, 410 ].freeze
-    # Rails' :id and *path, Django's <int:pk>, FastAPI's {id}.
-    PARAMETER = /\/[:*{<]/
+    # A path parameter, capturing its name: Rails' :id and *path, FastAPI's
+    # and ASP.NET Core's {id}, {id:int}, and {*path}, Django's <int:pk>.
+    PARAMETER = /[:*]([A-Za-z_]\w*)|\{\*{0,2}([A-Za-z_]\w*)(?::[^}]*)?\??\}|<(?:\w+:)?([A-Za-z_]\w*)>/
+    # One that can span segments, so its value keeps its slashes.
+    GLOB = %r{\A(?:\*|\{\*|\{\w+:path\}|<path:)}
+    PARAM = /\A([A-Za-z_]\w*)=(.+)\z/
+    # "Name: value", as with curl -H: a header name, then a value on one line.
+    HEADER = /\A([!#$%&'*+.^_`|~0-9A-Za-z-]+):[ \t]*(\S[^\r\n]*)\z/
 
     Target = Struct.new(:key, :path, :count)
     # codes: each route's exact status codes, nil for no answer, for
@@ -36,8 +43,30 @@ module DeployAngel
       end
     end
 
-    def initialize(base_url:, max_requests: MAX_REQUESTS, sleeper: ->(seconds) { sleep(seconds) }, requester: nil)
+    # Headers to send with every request, such as a token or a test
+    # account's session cookie, from "Name: value" lines. Raises
+    # ArgumentError naming the line, never its value.
+    def self.parse_headers(lines)
+      lines.map(&:strip).reject(&:empty?).each_with_index.to_h do |line, i|
+        match = HEADER.match(line) or raise ArgumentError, "header #{i + 1} must look like \"Name: value\""
+        [ match[1], match[2].rstrip ]
+      end
+    end
+
+    # Path parameter values, from "name=value" (--param id=42). Each fills
+    # that name in every route that has it.
+    def self.parse_params(pairs)
+      pairs.to_h do |pair|
+        match = PARAM.match(pair) or raise ArgumentError, "--param must look like name=value, such as --param id=42 (got #{pair.inspect})"
+        [ match[1], match[2] ]
+      end
+    end
+
+    # headers go only to base_url's host: redirects aren't followed.
+    def initialize(base_url:, headers: {}, params: {}, max_requests: MAX_REQUESTS, sleeper: ->(seconds) { sleep(seconds) }, requester: nil)
       @base = URI(base_url)
+      @headers = headers
+      @params = params
       @max_requests = max_requests
       @sleeper = sleeper
       @requester = requester || method(:get)
@@ -51,11 +80,12 @@ module DeployAngel
         next unless item["kind"] == "route"
 
         method, path = item["key"].to_s.split(" ", 2)
-        reason =
-          if item["mutating"] || method != "GET" then "changes data"
-          elsif path.nil? || path.match?(PARAMETER) then "needs a path parameter"
-          end
-        next skipped << { "key" => item["key"], "reason" => reason } if reason
+        next skipped << { "key" => item["key"], "reason" => "changes data" } if item["mutating"] || method != "GET"
+
+        path, missing = path ? fill(path) : [ nil, [] ]
+        if path.nil? || missing.any?
+          next skipped << { "key" => item["key"], "reason" => "needs a path parameter", "missing" => missing }
+        end
 
         needed = item["runs_needed"] ? item["runs_needed"].to_i - item["runs"].to_i : 1
         targets << Target.new(item["key"], path, [ needed, 1 ].max)
@@ -98,6 +128,24 @@ module DeployAngel
         codes: routes.to_h { |route| [ route["key"], @codes[route["key"]].to_h ] }, unsent: unsent)
     end
 
+    # The path with the given parameters filled in, and the names of any
+    # left unfilled.
+    def fill(path)
+      missing = []
+      filled = path.gsub(PARAMETER) do |segment|
+        name = $1 || $2 || $3
+        value = @params[name]
+        unless value
+          missing << name
+          next segment
+        end
+
+        glob = segment.match?(GLOB)
+        (glob ? value.split("/", -1) : [ value ]).map { |part| URI.encode_www_form_component(part).gsub("+", "%20") }.join("/")
+      end
+      [ filled, missing.uniq ]
+    end
+
     def url_for(path)
       uri = @base.dup
       uri.path = "#{@base.path.chomp("/")}#{path}"
@@ -108,7 +156,7 @@ module DeployAngel
     private
       def send_request(target)
         @sleeper.call(INTERVAL) if @sent.positive?
-        status = @requester.call(url_for(target.path))
+        status = @requester.call(url_for(target.path), @headers)
         @sent += 1
         kind = status ? "#{status / 100}xx" : "error"
         @statuses[target.key][kind] += 1
@@ -139,11 +187,12 @@ module DeployAngel
 
       # The status code, or nil when there was no answer. Redirects aren't
       # followed: the request already reached the app.
-      def get(url)
+      def get(url, headers)
         uri = URI(url)
         request = Net::HTTP::Get.new(uri)
         request["User-Agent"] = "DeployAngel-Exercise/#{DeployAngel::VERSION} (+https://www.deployangel.com/docs#exercise)"
         request["Accept"] = "text/html,application/json;q=0.9,*/*;q=0.8"
+        headers.each { |name, value| request[name] = value }
         Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: TIMEOUT, read_timeout: TIMEOUT) do |http|
           http.request(request).code.to_i
         end

data/lib/deployangel/mcp.rb

@@ -117,7 +117,7 @@ module DeployAngel
             TARGET_PROPERTIES),
           tool("list_deployments", "Recent deployments with their verification state and verdict.",
             { "limit" => { "type" => "integer", "minimum" => 1, "maximum" => 50, "default" => 10 } }),
-          tool("get_exception", "Sanitized details and the application stack trace for an exception fingerprint.",
+          tool("get_exception", "Sanitized details and a representative stack trace (application frames, or library frames when there are none) for an exception fingerprint.",
             { "fingerprint" => { "type" => "string" } }, required: %w[fingerprint]),
           tool("list_late_regressions", "Failures found after a release was cleared, on paths the clearance did not cover.",
             { "since" => { "type" => "string", "description" => "ISO 8601 time" },

data/lib/deployangel/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DeployAngel
-  VERSION = "0.1.35"
+  VERSION = "0.1.37"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: deployangel
 version: !ruby/object:Gem::Version
-  version: 0.1.35
+  version: 0.1.37
 platform: ruby
 authors:
 - Jordan Owens