onair-cli 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1faf09e85aa982fd64a664e4d1f566c4aaf836cc3f196cde37ef9477a42c498f
-  data.tar.gz: 41404044b99b5624b947bc726cefb8e85910622f95ff31b2419bd12c612b56bb
+  metadata.gz: 1eb5f2eb79c1eb2da95ef69cb65f8bef60b72dc3d98563a6235573b4ae139fd6
+  data.tar.gz: f5a38c5ef53340a88e41c9c007e68c34d1035d0427b953ac7b4193421201dde7
 SHA512:
-  metadata.gz: 2343601742f56a59b9141dd06d597f040ca1f55eae53295dd34dad9da10127372cb544b5bf9ff6bff98fdcaf1b2d938eab0e3ea0c9309f93ebd000da9a298566
-  data.tar.gz: 4ae9c7a4348ded957fb88a922cc44d8ebebeba36f6c870303663fe922be631bed2b2ac5ea82acbfc4ac2111bffdeefc0e8ac05c60e8dbb8d9068c51a33fb1eee
+  metadata.gz: 133e4480b8e8c22835294d0c2b18e79f9ee6ba065ee080c7c5f0e0c61a1a8bf92aecc6ee2e6092bce8ba095ffe7937ce8b6cb6526ca20938ae3d3d54dc39062e
+  data.tar.gz: b4e08f469025a62273c6c848b4d790e8b9a1520a6ce6ab24f0b845bcd7453cfa2040b1d40b3d0a29fe73c13e9c3d4242779022b0b2c43ba11c968f0e5ae74be5

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-08
+
+- Heroku: a rollout line under Deployed counts the dynos of each process type
+  running the deployed release (`web 1/3, 2 starting`) and says when every
+  dyno is up on it. With preboot on, the handoff from the previous web dynos
+  shows as an estimate. `--json` gains a `rollout` object.
+
 ## [0.2.0] - 2026-10-07
 
 - Heroku: Deployed is the release Heroku is serving, not the newest one. A

data/README.md

@@ -72,6 +72,11 @@ the API is a faster transport, never a cache.
   author, and a delta against `origin/main`: `★ current` or
   `↓ N commits behind`. If the relationship is unknown (diverged history,
   commits unavailable), no marker is shown - silence over speculation.
+- **Rollout** - under the Deployed row, how many dynos of each process type
+  run that release: `⟳ rolling out v1234: web 1/3, 2 starting` while dynos
+  restart, `✓ rolled out` once every dyno is up on it. With preboot on, the
+  previous web dynos keep serving for about three minutes after the new ones
+  are up; that window shows as an estimate.
 - **Pending** - an in-flight build that's about to replace the deploy.
 - **Releasing** - a newer release whose release phase (e.g. migrations) is
   still running; production still serves the Deployed row until it finishes.
@@ -130,6 +135,13 @@ additively:
   },
   "pending": null,
   "release": null,
+  "rollout": {
+    "version": 1234, "complete": true,
+    "processes": [
+      { "type": "web", "up": 3, "total": 3, "waiting": {}, "previous": 0 }
+    ],
+    "overlap_until": null
+  },
   "delta": { "status": "current", "behind_by": 0 },
   "pinned": null,
   "yours": null
@@ -143,6 +155,12 @@ additively:
   "subject", "author" }` when a release newer than the running one is not
   live; `status` is `"pending"` (release phase running) or `"failed"`. While
   it carries a different sha, `delta.status` is never `"current"`.
+- `rollout`: dynos per process type against the running release. `up`
+  counts dynos serving it, `waiting` counts the rest of its dynos by state
+  (`starting`, `crashed`, ...), `previous` counts dynos on an older release.
+  `overlap_until` is an estimated end of the preboot handoff while it lasts,
+  otherwise `null`. `complete` is true once every dyno serves the running
+  release and no handoff remains. `null` when the dynos can't be read.
 - `pinned`: `{ "version", "description", "latest_built_sha" }` when a newer
   build succeeded but is not running.
 - `yours`: `{ "sha", "had_own_build", "subject", "author" }` when your commit
@@ -155,7 +173,7 @@ additively:
 
 ```sh
 bundle install
-bundle exec rake        # specs + rubocop
+bundle exec rake        # specs + standard
 ```
 
 The behavioral source of truth is `reference/prod-release.sh`, the

data/lib/onair/cli.rb

@@ -64,16 +64,17 @@ module Onair
       git = Git.new(fetch_allowed: config.fetch)
       adapter = Platform.build(config)
       repo = config.repo || git.origin_repo
-      report = Orchestrator.new(config: config, adapter: adapter, git: git, repo: repo).run
+      now = Time.now
+      report = Orchestrator.new(config: config, adapter: adapter, git: git, repo: repo, now: now).run
 
       if flags[:json]
         puts Renderer::Json.new(report: report, app: config.app, platform: config.platform,
-                                branch: config.branch, repo: repo, task: config.task).render
+          branch: config.branch, repo: repo, task: config.task).render
       else
         tty = $stdout.tty?
         print Renderer::Tty.new(report: report, app: config.app, platform_label: adapter.display_name,
-                                branch: config.branch, repo: repo, task: config.task,
-                                color: tty && !no_color?, hyperlinks: tty, now: Time.now).render
+          branch: config.branch, repo: repo, task: config.task,
+          color: tty && !no_color?, hyperlinks: tty, now: now).render
       end
     end
 

data/lib/onair/git.rb

@@ -91,7 +91,7 @@ module Onair
     end
 
     def opts
-      @dir ? { chdir: @dir } : {}
+      @dir ? {chdir: @dir} : {}
     end
   end
 end

data/lib/onair/orchestrator.rb

@@ -4,11 +4,12 @@ module Onair
   # Runs the platform adapter and git concurrently, lazily fetches missing
   # commits at most once, and assembles the Report.
   class Orchestrator
-    def initialize(config:, adapter:, git:, repo: nil)
+    def initialize(config:, adapter:, git:, repo: nil, now: Time.now)
       @config = config
       @adapter = adapter
       @git = git
       @repo = repo
+      @now = now
     end
 
     def run
@@ -20,7 +21,7 @@ module Onair
       needed = [snapshot.deployed&.sha, snapshot.pending&.sha, snapshot.release&.sha, remote_head].compact
       @git.fetch_once! if needed.any? { |sha| !@git.has_commit?(sha) }
 
-      Report.build(snapshot: snapshot, remote_head: remote_head, git: @git)
+      Report.build(snapshot: snapshot, remote_head: remote_head, git: @git, now: @now)
     end
 
     private

data/lib/onair/platform/base.rb

@@ -13,7 +13,7 @@ module Onair
         klass = @registry[config.platform]
         if klass.nil?
           raise Error,
-                "unknown platform #{config.platform.inspect} (available: #{@registry.keys.join(', ')})"
+            "unknown platform #{config.platform.inspect} (available: #{@registry.keys.join(", ")})"
         end
 
         klass.new(config)
@@ -29,6 +29,9 @@ module Onair
     #                     running (release phase pending or failed), or nil
     #   latest_built_sha: newest successfully built sha, or nil
     #   succeeded_shas:   recent succeeded build shas, newest first
+    #   rollout:          per process type, how many dynos run the running
+    #                     release, plus an optional estimate of when the
+    #                     previous release stops serving; nil when unknown
     #
     # Adapters own their internal concurrency and auth. Everything above
     # (delta, pinned, mine, rendering) is platform-agnostic and must not

data/lib/onair/platform/heroku.rb

@@ -10,15 +10,24 @@ module Onair
       HOST = "api.heroku.com"
       RELEASE_WINDOW = 10
       IN_FLIGHT_STATUSES = %w[pending failed].freeze
+      ONE_OFF_TYPES = %w[run scheduler release].freeze
+      # An eco dyno asleep on the running release boots that release on wake.
+      SERVING_STATES = %w[up idle].freeze
+      # With preboot, Heroku keeps routing to the previous web dynos for about
+      # three minutes after the new ones come up.
+      PREBOOT_HANDOFF = 180
 
       def snapshot
         token = resolve_token
         releases_thread = quiet_thread { releases(token) }
         builds_thread = quiet_thread { builds(token) }
+        dynos_thread = quiet_thread { dynos(token) }
         deployed, release = releases_thread.value
         pending, succeeded_shas = builds_thread.value
+        dyno_rows, preboot = dynos_thread.value
         Snapshot.new(deployed: deployed, pending: pending, release: release,
-                     latest_built_sha: succeeded_shas.first, succeeded_shas: succeeded_shas)
+          latest_built_sha: succeeded_shas.first, succeeded_shas: succeeded_shas,
+          rollout: rollout(dyno_rows, preboot, deployed.version))
       end
 
       private
@@ -62,7 +71,7 @@ module Onair
 
       def deployed(row, sha)
         Deployed.new(sha: sha, version: row["version"], description: row["description"],
-                     deployed_at: parse_time(row["created_at"]))
+          deployed_at: parse_time(row["created_at"]))
       end
 
       # Only the newest release counts: an older failed one was superseded by
@@ -71,11 +80,11 @@ module Onair
         return nil if newest.equal?(running) || !IN_FLIGHT_STATUSES.include?(newest["status"])
 
         slug_id = newest.dig("slug", "id")
-        sha = slug_id == running.dig("slug", "id") ? running_sha : slug_commit(http, token, slug_id)
+        sha = (slug_id == running.dig("slug", "id")) ? running_sha : slug_commit(http, token, slug_id)
         return nil if sha.nil?
 
         Release.new(sha: sha, version: newest["version"], description: newest["description"],
-                    status: newest["status"].to_sym, started_at: parse_time(newest["created_at"]))
+          status: newest["status"].to_sym, started_at: parse_time(newest["created_at"]))
       end
 
       def slug_commit(http, token, slug_id)
@@ -96,12 +105,62 @@ module Onair
         pending_sha = pending_build&.dig("source_blob", "version")
         pending = pending_sha && Pending.new(sha: pending_sha, started_at: parse_time(pending_build["created_at"]))
         succeeded = builds.select { |build| build["status"] == "succeeded" }
-                          .filter_map { |build| build.dig("source_blob", "version") }
+          .filter_map { |build| build.dig("source_blob", "version") }
         [pending, succeeded]
       rescue Error
         [nil, []]
       end
 
+      # A failed dynos call drops the rollout and nothing else; a failed
+      # preboot lookup only drops the handoff estimate.
+      def dynos(token)
+        with_http do |http|
+          rows = get(http, token, "/apps/#{app}/dynos")
+          [rows, preboot?(http, token)]
+        end
+      rescue Error
+        [nil, false]
+      end
+
+      def preboot?(http, token)
+        get(http, token, "/apps/#{app}/features/preboot")["enabled"] == true
+      rescue Error
+        false
+      end
+
+      def rollout(rows, preboot, version)
+        return nil if rows.nil? || version.nil?
+
+        formation = rows.reject { |dyno| ONE_OFF_TYPES.include?(dyno["type"]) }
+        return nil if formation.empty?
+
+        processes = formation.group_by { |dyno| dyno["type"] }
+          .sort_by { |type, _| [(type == "web") ? 0 : 1, type] }
+          .map { |type, dynos| process_rollout(type, dynos, version) }
+        Rollout.new(version: version, processes: processes,
+          overlap_until: preboot ? preboot_handoff(formation, version) : nil)
+      end
+
+      def process_rollout(type, dynos, version)
+        current, previous = dynos.partition { |dyno| dyno.dig("release", "version") == version }
+        waiting = current.map { |dyno| dyno["state"] }.reject { |state| SERVING_STATES.include?(state) }.tally
+        ProcessRollout.new(type: type, total: dynos.size, up: current.size - waiting.values.sum,
+          waiting: waiting, previous: previous.size)
+      end
+
+      # Old web dynos still listed are already counted as previous; the
+      # estimate covers only the handoff the dynos list does not show.
+      def preboot_handoff(formation, version)
+        web = formation.select { |dyno| dyno["type"] == "web" }
+        return nil if web.empty?
+        return nil unless web.all? do |dyno|
+          dyno.dig("release", "version") == version && SERVING_STATES.include?(dyno["state"])
+        end
+
+        last_up = web.filter_map { |dyno| parse_time(dyno["updated_at"]) }.max
+        last_up && (last_up + PREBOOT_HANDOFF)
+      end
+
       # One connection per thread — the dependent releases → slug pair must
       # not pay a second TLS handshake.
       def with_http(&)

data/lib/onair/remote_head.rb

@@ -38,7 +38,7 @@ module Onair
 
       sha = JSON.parse(response.body).dig("object", "sha")
       sha&.match?(/\A\h{40}\z/) ? sha : nil
-    rescue StandardError
+    rescue
       nil
     end
     private_class_method :api_head

data/lib/onair/renderer/json.rb

@@ -31,6 +31,7 @@ module Onair
           deployed: deployed_payload,
           pending: pending_payload,
           release: release_payload,
+          rollout: rollout_payload,
           delta: delta_payload,
           pinned: pinned_payload,
           yours: yours_payload
@@ -59,7 +60,7 @@ module Onair
         pending = snapshot.pending
         return nil if pending.nil?
 
-        { sha: pending.sha, started_at: iso(pending.started_at) }.merge(commit_fields(pending.sha))
+        {sha: pending.sha, started_at: iso(pending.started_at)}.merge(commit_fields(pending.sha))
       end
 
       def release_payload
@@ -75,11 +76,26 @@ module Onair
         }.merge(commit_fields(release.sha))
       end
 
+      def rollout_payload
+        rollout = @report.rollout
+        return nil if rollout.nil?
+
+        {
+          version: rollout.version,
+          complete: rollout.complete?,
+          processes: rollout.processes.map do |process|
+            {type: process.type, up: process.up, total: process.total,
+             waiting: process.waiting, previous: process.previous}
+          end,
+          overlap_until: iso(rollout.overlap_until)
+        }
+      end
+
       def delta_payload
         case @report.delta
-        when :current then { status: "current", behind_by: 0 }
-        when Integer then { status: "behind", behind_by: @report.delta }
-        else { status: "unknown", behind_by: nil }
+        when :current then {status: "current", behind_by: 0}
+        when Integer then {status: "behind", behind_by: @report.delta}
+        else {status: "unknown", behind_by: nil}
         end
       end
 
@@ -98,19 +114,19 @@ module Onair
         mine = @report.mine
         return nil if mine.nil?
 
-        { sha: mine.sha, had_own_build: mine.had_own_build }.merge(commit_fields(mine.sha))
+        {sha: mine.sha, had_own_build: mine.had_own_build}.merge(commit_fields(mine.sha))
       end
 
       def commit_fields(sha)
         info = sha && @report.commits[sha]
-        { subject: info&.subject, author: info&.author_name, task: task_fields(info&.subject) }
+        {subject: info&.subject, author: info&.author_name, task: task_fields(info&.subject)}
       end
 
       def task_fields(subject)
         task_id = @task&.find(subject)
         return nil if task_id.nil?
 
-        { id: task_id, url: @task.url_for(task_id) }
+        {id: task_id, url: @task.url_for(task_id)}
       end
 
       def iso(time)

data/lib/onair/renderer/tty.rb

@@ -61,10 +61,10 @@ module Onair
         detail = "v#{release.version}"
         detail = "#{detail}: #{release.description}" if release.sha == snapshot.deployed&.sha
         label, color, note = if release.status == :failed
-                               ["Failed:", :red, "✗ release phase failed (#{detail})"]
-                             else
-                               ["Releasing:", :yellow, "⟳ release phase (#{detail})"]
-                             end
+          ["Failed:", :red, "✗ release phase failed (#{detail})"]
+        else
+          ["Releasing:", :yellow, "⟳ release phase (#{detail})"]
+        end
         row_lines(label, color, release.sha, age(release.started_at), extra: paint(note, color)) + [""]
       end
 
@@ -72,6 +72,7 @@ module Onair
         deployed = snapshot.deployed
         if deployed&.sha
           lines = row_lines("Deployed:", :green, deployed.sha, age(deployed.deployed_at), extra: delta_text)
+          lines << rollout_line if @report.rollout
           lines << pinned_line if @report.pinned
           lines.concat(yours_lines)
           lines
@@ -81,6 +82,35 @@ module Onair
         end
       end
 
+      # The dynos list can look finished while preboot still routes some
+      # traffic to the previous release, so that window gets its own line.
+      def rollout_line
+        rollout = @report.rollout
+        text, color = if rollout.complete?
+          ["✓ rolled out v#{rollout.version}: #{process_counts(rollout)}", :dim]
+        elsif rollout.processes.all?(&:complete?)
+          ["⟳ preboot: previous web dynos may still serve for " \
+           "~#{remaining(rollout.overlap_until)} (estimate)", :yellow]
+        else
+          ["⟳ rolling out v#{rollout.version}: #{process_counts(rollout)}", :yellow]
+        end
+        "  #{paint(text, color)}"
+      end
+
+      def process_counts(rollout)
+        rollout.processes.map do |process|
+          parts = ["#{process.type} #{process.up}/#{process.total}"]
+          parts.concat(process.waiting.map { |state, count| "#{count} #{state}" })
+          parts << "#{process.previous} on older release" if process.previous.positive?
+          parts.join(", ")
+        end.join(" · ")
+      end
+
+      def remaining(time)
+        seconds = (time - @now).ceil.clamp(0..)
+        (seconds < 60) ? "#{seconds}s" : "#{(seconds / 60.0).ceil}m"
+      end
+
       def yours_lines
         mine = @report.mine
         return [] if mine.nil?
@@ -98,7 +128,7 @@ module Onair
         padded = label.ljust(LABEL_WIDTH)
         first = "  #{paint(padded, color_key)}  #{paint(sha[0, 9], :bold)}  #{paint("#{age_blurb}by #{author}", :dim)}"
         first = "#{first}  #{extra}" if extra
-        [first, "  #{paint('→', :dim)} #{linkify(subject, info ? sha : nil)}"]
+        [first, "  #{paint("→", :dim)} #{linkify(subject, info ? sha : nil)}"]
       end
 
       def delta_text
@@ -107,7 +137,7 @@ module Onair
           paint("★ current", :green)
         when Integer
           count = @report.delta
-          paint("↓ #{count} #{count == 1 ? 'commit' : 'commits'} behind origin/#{@branch}", :yellow)
+          paint("↓ #{count} #{(count == 1) ? "commit" : "commits"} behind origin/#{@branch}", :yellow)
         end
       end
 

data/lib/onair/report.rb

@@ -10,8 +10,10 @@ module Onair
   # mine:    the local user's commit just below someone else's deployed head.
   # commits: sha => CommitInfo (or nil when absent locally) for every sha a
   #          renderer may need to describe.
-  Report = Data.define(:snapshot, :remote_head, :delta, :pinned, :mine, :commits) do
-    def self.build(snapshot:, remote_head:, git:)
+  # rollout: the snapshot's rollout, its handoff estimate dropped once `now`
+  #          has passed it, or nil when unknown.
+  Report = Data.define(:snapshot, :remote_head, :delta, :pinned, :mine, :commits, :rollout) do
+    def self.build(snapshot:, remote_head:, git:, now:)
       # Pinned is judged before the stale pending is dropped: during the
       # stale window the newest *succeeded* build is still the previous
       # deploy, which must not read as a rollback.
@@ -20,17 +22,24 @@ module Onair
       deployed_sha = snapshot.deployed&.sha
       mine = compute_mine(snapshot, git)
       commits = [deployed_sha, snapshot.pending&.sha, snapshot.release&.sha, mine&.sha]
-                .compact.uniq.to_h { |sha| [sha, git.commit_info(sha)] }
+        .compact.uniq.to_h { |sha| [sha, git.commit_info(sha)] }
       new(
         snapshot: snapshot,
         remote_head: remote_head,
         delta: compute_delta(snapshot, remote_head, git),
         pinned: pinned,
         mine: mine,
-        commits: commits
+        commits: commits,
+        rollout: live_rollout(snapshot.rollout, now)
       )
     end
 
+    def self.live_rollout(rollout, now)
+      return rollout if rollout.nil? || rollout.overlap_until.nil? || rollout.overlap_until > now
+
+      rollout.with(overlap_until: nil)
+    end
+
     # Right after a deploy finishes, the platform's builds list can still
     # report the just-released build as pending while the releases endpoint
     # already shows it running — the same commit would render as both
@@ -91,6 +100,6 @@ module Onair
     end
 
     private_class_method :drop_superseded_pending, :compute_delta, :pinned?, :release_of_other_commit?,
-                         :compute_mine, :identity_match?
+      :compute_mine, :identity_match?, :live_rollout
   end
 end

data/lib/onair/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Onair
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/onair.rb

@@ -18,10 +18,27 @@ module Onair
   # release phase is still running (status :pending) or it failed (:failed).
   Release = Data.define(:sha, :version, :description, :status, :started_at)
 
+  # Dynos of one process type against the running release. `up` counts dynos
+  # on the running version that serve (or idle until woken); `waiting` counts
+  # the rest of them by state; `previous` counts dynos on an older release.
+  ProcessRollout = Data.define(:type, :total, :up, :waiting, :previous) do
+    def complete?
+      up == total
+    end
+  end
+
+  # How far the running release has reached its dynos. `overlap_until` is an
+  # estimate of when the previous release stops serving traffic, or nil.
+  Rollout = Data.define(:version, :processes, :overlap_until) do
+    def complete?
+      processes.all?(&:complete?) && overlap_until.nil?
+    end
+  end
+
   # What a platform adapter returns. `latest_built_sha` is the newest
   # successfully built sha (rollback detection); `succeeded_shas` lists all
   # recent succeeded build shas, newest first ("yours had its own deploy").
-  Snapshot = Data.define(:deployed, :pending, :release, :latest_built_sha, :succeeded_shas)
+  Snapshot = Data.define(:deployed, :pending, :release, :latest_built_sha, :succeeded_shas, :rollout)
 
   Mine = Data.define(:sha, :had_own_build)
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: onair-cli
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Eugene