deployangel 0.1.34 → 0.1.36

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e0552271dfa638f21feb4c8591729a8c226df32dc75201a12a8e41843534f75
-  data.tar.gz: d62f917c014872a66458dab5e73de67b87b594b0e654b519388d193cd62d4965
+  metadata.gz: eb03031f58bd01feb61e1f478f4108eb3c969527e28cf86d970355a6bede0031
+  data.tar.gz: 3dd9679d37e80b23e449ee99ffd29bd3db9700bf8e2b5bfa665bf4413e2e4fb7
 SHA512:
-  metadata.gz: 9e116aca53991800ed66a98f288fad4706f51baf45b174678156cfcd51202bac16e7d151ef5c323ad97d14f6ca774bf2092f034ef2764fd2106d530f2a48c0ec
-  data.tar.gz: 2f31abc979d9de0d0fac5da35d975025240144df25bc82693c25c5ca271ecb206032437cbfbca61571a78a70559f40b5083e423d98d94f1a35290968fa5b01bd
+  metadata.gz: bbaff8f03fce84081cdf13786dac7d26912ffeb9eae1c3f032f91d3b00afd23ba95a076c6213846cd44390017e8b7f8cdfd7b63833a07fcef9f782b4e9576dc0
+  data.tar.gz: 2919b83e169d1ac91175c733d9366df8e05b4910f8722a99cb3fdae57a07dda205be55dce418f2c0c7e1d8e382dc17a9007e23c96126b0174d24ed24588c13be

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 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`)
+  instead of their class (`1 4xx`). When every page answers 404, 405, or
+  410, as when `--url` is the app's marketing site rather than its own
+  host, it says so, records nothing on the release, and exits 5.
+
 ## 0.1.34 (2026-11-01)
 
 - `deployangel verify` prints a failed release's next steps: the last

data/README.md

@@ -597,14 +597,29 @@ 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
 parameter, and stops requesting a page after its first 404, sending its
-share to the pages that answered. A "CLI & coding agents" token can run
-it. `--dry-run` shows what it would send.
+share to the pages that answered. It prints each route's status codes. If
+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
 
@@ -637,8 +652,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,27 +321,55 @@ 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"]}: #{r["statuses"].map { |kind, n| "#{n} #{kind}" }.join(", ")}" })
-        @stdout.puts("Skipped:", *result.skipped.map { |s| "  #{s["key"]} (#{s["reason"]})" }) if result.skipped.any?
+          *result.routes.map { |r| "  #{r["key"]} ×#{r["requests"]}: #{status_codes(result.codes[r["key"]])}" })
+        @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.
+        if result.routes.any? && result.nothing_served? && !result.unreachable
+          @stdout.puts("", "No page answered at #{options[:url]}: every route said it doesn't exist. Is that the app's own host, " \
+            "and not a marketing site or a different domain? Pass the URL where the app's pages load.")
+          @stdout.puts("#{result.unsent} more requests weren't sent, since no route answered.") if result.unsent.positive?
+          @stdout.puts("Nothing was recorded on the release.")
+          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(", ")
+      end
+
       def exception
         fingerprint = @argv.shift or return usage_error("exception needs a FINGERPRINT")
         format = parse(format: nil) { |o, opts| o.on("--format=FORMAT", %w[text json]) { |v| opts[:format] = v } }[:format]

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,14 +20,53 @@ 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)
-    Result = Struct.new(:routes, :skipped, :sent, :unreachable, keyword_init: true)
+    # codes: each route's exact status codes, nil for no answer, for
+    # display; routes carries status classes, which is what's recorded.
+    # unsent: requests the plan wanted that went nowhere, since no route
+    # answered.
+    Result = Struct.new(:routes, :skipped, :sent, :unreachable, :codes, :unsent, keyword_init: true) do
+      # Every answer said the page isn't served. Usually the wrong host,
+      # like the app's marketing site.
+      def nothing_served?
+        answers = codes.values.flat_map(&:keys)
+        answers.any? && answers.all? { |code| NOT_SERVED.include?(code) }
+      end
+    end
+
+    # 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
 
-    def initialize(base_url:, max_requests: MAX_REQUESTS, sleeper: ->(seconds) { sleep(seconds) }, requester: nil)
+    # 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)
@@ -40,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)
@@ -59,6 +100,7 @@ module DeployAngel
     def run(exercise_plan)
       targets, skipped = plan(exercise_plan)
       @statuses = Hash.new { |hash, key| hash[key] = Hash.new(0) }
+      @codes = Hash.new { |hash, key| hash[key] = Hash.new(0) }
       @sent = 0
       @errors_in_a_row = 0
       leftover = 0
@@ -76,12 +118,32 @@ module DeployAngel
         answered << target if @statuses[target.key].keys.intersect?(%w[2xx 3xx])
       end
       leftover.times { |i| send_request(answered[i % answered.size]) unless unreachable? } if answered.any?
+      unsent = answered.empty? ? leftover : 0
 
       routes = targets.filter_map do |target|
         statuses = @statuses.fetch(target.key, nil) or next
         { "key" => target.key, "requests" => statuses.values.sum, "statuses" => statuses.to_h }
       end
-      Result.new(routes: routes, skipped: skipped, sent: @sent, unreachable: unreachable?)
+      Result.new(routes: routes, skipped: skipped, sent: @sent, unreachable: unreachable?,
+        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)
@@ -94,10 +156,11 @@ 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
+        @codes[target.key][status] += 1
         @errors_in_a_row = kind == "error" ? @errors_in_a_row + 1 : 0
         status
       end
@@ -124,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/version.rb

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

metadata

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