dash 4.0.4 → 4.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 762f586250ded9a4e4f60850a91b1358bd993bcb1d4c6e291dfec93dc6d516e2
-  data.tar.gz: d87d3161396bfdb38f9feb3d3946d0830bdd2b1dc2921e569a275e65f4285cb1
+  metadata.gz: d13e0fdb207715506d85fa85be2a719ca70640130f22ca948c075fd787b3dd88
+  data.tar.gz: cc42a4346178f4ffbcf7b7b2f03820e49f99e9d54c78ab864493a0c0b8b214e4
 SHA512:
-  metadata.gz: 86a1e05606121be7d85b83c2da117d8bcc2a2badbf080a5e5d0237b3175dd98ac9abba3d1afa154495d6be85923d8ef7d915e3bb877241b69a637ab47de00658
-  data.tar.gz: 9bca1f4085e3ad18ca778eba0dc3344b6592404839fdb4628a2a1bc05d81d869c4b4a837a18f66659f2c0b9fba307da4f14d877f0c088f709d72806a68bf2927
+  metadata.gz: cdf2135081cc1acc7de1d73d7c7156f93262ad82a5848a6db6aaf484bf4859ed3e529fede60ac0c67df99ec021acdd2cbf6a9175982af8f31873afa03cc2113b
+  data.tar.gz: 30eae7e9f41f2b216be4dd8d16ce583f5a8e2392d3b05b3ad15fcd4ba40645441c05c39a643cca2bf01876ee28aec2fa668a7ffe2a474e27c69b46edc341dbc6

data/bin/dash

@@ -3,6 +3,11 @@
 # Prevent failures from being reported twice.
 Thread.report_on_exception = false
 
+# Ruby block-buffers stdout when it is not a TTY, which is every CI runner. Line-by-line
+# writes keep the runner's timestamps attributable to the command that printed them.
+$stdout.sync = true
+$stderr.sync = true
+
 require "dash"
 
 begin

data/lib/dash/cli/app/boot.rb

@@ -14,22 +14,26 @@ class Dash::Cli::App::Boot
   end
 
   def run
-    old_version = old_version_renamed_if_clashing
+    DASH.timings.phase("#{role} #{host}", depth: 1) do |timing|
+      @timing = timing
 
-    wait_at_barrier if queuer?
+      old_version = old_version_renamed_if_clashing
 
-    begin
-      start_new_version
-    rescue => e
-      close_barrier if gatekeeper?
-      stop_new_version
-      raise
-    end
+      wait_at_barrier if queuer?
+
+      begin
+        start_new_version
+      rescue => e
+        close_barrier if gatekeeper?
+        stop_new_version
+        raise
+      end
 
-    release_barrier if gatekeeper?
+      release_barrier if gatekeeper?
 
-    if old_version
-      stop_old_version(old_version)
+      if old_version
+        stop_old_version(old_version)
+      end
     end
   end
 
@@ -59,10 +63,10 @@ class Dash::Cli::App::Boot
 
         run_hook "pre-proxy-deploy", hosts: host.to_s, role: role.name
         info "Deploying #{role} on #{host} via dash-proxy (waiting up to #{DASH.config.deploy_timeout}s for it to become healthy)..."
-        execute *app.deploy(target: endpoint)
+        timing_healthy { execute *app.deploy(target: endpoint) }
         run_hook "post-proxy-deploy", hosts: host.to_s, role: role.name
       else
-        Dash::Cli::Healthcheck::Poller.wait_for_healthy(role: role) { health_status }
+        timing_healthy { Dash::Cli::Healthcheck::Poller.wait_for_healthy(role: role) { health_status } }
       end
     rescue => e
       error "Failed to boot #{role} on #{host}"
@@ -136,6 +140,15 @@ class Dash::Cli::App::Boot
       end
     end
 
+    # The readiness wait is the part of a host's boot an operator can actually tune
+    # (health check interval, app boot time), so it gets called out on the host's entry.
+    def timing_healthy
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      yield
+    ensure
+      @timing.detail = format("healthy after %.1fs", Process.clock_gettime(Process::CLOCK_MONOTONIC) - started)
+    end
+
     def barrier_role?
       role == DASH.primary_role
     end

data/lib/dash/cli/app.rb

@@ -426,10 +426,24 @@ class Dash::Cli::App < Dash::Cli::Base
       end
     end
 
+    # Canary hosts each form a group of one and go first; whatever is left is sliced by
+    # `limit` (a percentage counts those remaining hosts, the set it actually slices) or
+    # boots as a single group. No canary and no limit is the one-group default.
     def host_boot_groups
       hosts = DASH.app_hosts
-      limit = DASH.config.boot.limit_for(hosts)
+      canary_hosts = canary_boot_hosts(hosts)
+      rest = hosts - canary_hosts
+      limit = DASH.config.boot.limit_for(rest)
 
-      limit ? hosts.each_slice(limit).to_a : [ hosts ]
+      rest_groups = limit ? rest.each_slice(limit).to_a : [ rest ]
+
+      canary_hosts.map { |host| [ host ] } + rest_groups.reject(&:empty?)
+    end
+
+    # The first N primary-role hosts of this run. `--roles`/`--hosts` may leave none, in
+    # which case there is nothing to prove ahead of the others and no canary group.
+    def canary_boot_hosts(hosts)
+      count = DASH.config.boot.canary
+      count ? (DASH.primary_role.hosts & hosts).first(count) : []
     end
 end

data/lib/dash/cli/base.rb

@@ -140,13 +140,22 @@ module Dash::Cli
         end
       end
 
+      # `setup` wraps `deploy`, so this nests. Each level reports its own total; the phase
+      # table belongs to the outermost, which is the one that saw every phase.
       def print_runtime
         started_at = Time.now
+        @print_runtime_depth = @print_runtime_depth.to_i + 1
         yield
         Time.now - started_at
       ensure
+        @print_runtime_depth -= 1
         runtime = Time.now - started_at
         puts "  Finished all in #{sprintf("%.1f seconds", runtime)}"
+        puts DASH.timings.lines if @print_runtime_depth.zero? && DASH.timings.any?
+      end
+
+      def timed(name, depth: 0, &block)
+        DASH.timings.phase(name, depth: depth, &block)
       end
 
       # Deploy lock outside, server lock inside. Every caller acquires in that

data/lib/dash/cli/doctor/host_checks.rb

@@ -113,7 +113,12 @@ class Dash::Cli::Doctor::HostChecks
       elsif version.nil?
         result :proxy_version, :ok, "not running (will be started on deploy)"
       elsif Dash::Utils.older_version?(version, minimum)
-        result :proxy_version, :fail, "#{version} is older than the minimum #{minimum}, run `dash proxy reboot` to update"
+        if deploy_reboots_proxy?
+          result :proxy_version, :ok,
+            "#{version} is older than the minimum #{minimum}; the next deploy reboots the proxy to update it"
+        else
+          result :proxy_version, :fail, "#{version} is older than the minimum #{minimum}, run `dash proxy reboot` to update"
+        end
       else
         result :proxy_version, :ok, "#{version} (minimum #{minimum})"
       end
@@ -121,6 +126,18 @@ class Dash::Cli::Doctor::HostChecks
       result :proxy_version, :warn, "running image tag #{version} is not a version number"
     end
 
+    # Mirrors `proxy boot`: with reboot_on_deploy enabled it reboots a drifted
+    # proxy on its own, and a MINIMUM_VERSION bump moves the expected config
+    # digest, so a merely-stale proxy is converged by the very deploy this
+    # doctor gates. Only a version the deploy would not touch — pinned in the
+    # config, or with automatic reboots disabled — is a real failure. Any error
+    # probing drift falls back to the conservative answer.
+    def deploy_reboots_proxy?
+      DASH.config.proxy.reboot_on_deploy? && Dash::Cli::Proxy::Drift.new(host, sshkit).drifted?
+    rescue StandardError
+      false
+    end
+
     # What a container path has to look like to count as a container runtime
     # socket when the config no longer names one.
     DOCKER_SOCKET_PATTERN = %r{docker\.sock\z}

data/lib/dash/cli/main.rb

@@ -8,7 +8,7 @@ class Dash::Cli::Main < Dash::Cli::Base
         invoke_options = deploy_options
 
         say "Ensure Docker is installed...", :magenta
-        invoke "dash:cli:server:bootstrap", [], invoke_options
+        timed("Ensure Docker is installed") { invoke "dash:cli:server:bootstrap", [], invoke_options }
 
         deploy(boot_accessories: true)
       end
@@ -30,32 +30,32 @@ class Dash::Cli::Main < Dash::Cli::Base
 
         if options[:skip_push]
           say "Pull app image...", :magenta
-          invoke "dash:cli:build:pull", [], invoke_options
+          timed("Pull app image") { invoke "dash:cli:build:pull", [], invoke_options }
         else
           say "Build and push app image...", :magenta
-          invoke "dash:cli:build:deliver", [], invoke_options
+          timed("Build and push app image") { invoke "dash:cli:build:deliver", [], invoke_options }
         end
 
         modify(lock: true) do
           run_hook "pre-deploy", secrets: true
 
           say "Ensure dash-proxy is running...", :magenta
-          invoke "dash:cli:proxy:boot", [], invoke_options
+          timed("Ensure dash-proxy") { invoke "dash:cli:proxy:boot", [], invoke_options }
 
-          invoke "dash:cli:accessory:boot", [ "all" ], invoke_options if boot_accessories
+          timed("Boot accessories") { invoke "dash:cli:accessory:boot", [ "all" ], invoke_options } if boot_accessories
 
           say "Detect stale containers...", :magenta
-          invoke "dash:cli:app:stale_containers", [], invoke_options.merge(stop: true)
+          timed("Detect stale containers") { invoke "dash:cli:app:stale_containers", [], invoke_options.merge(stop: true) }
 
-          invoke "dash:cli:app:boot", [], invoke_options
+          timed("Boot") { invoke "dash:cli:app:boot", [], invoke_options }
 
           if DASH.config.proxy.load_balancing?
             say "Updating loadbalancer configuration...", :magenta
-            invoke "dash:cli:proxy:loadbalancer", [ "deploy" ], invoke_options
+            timed("Loadbalancer") { invoke "dash:cli:proxy:loadbalancer", [ "deploy" ], invoke_options }
           end
 
           say "Prune old containers and images...", :magenta
-          invoke "dash:cli:prune:all", [], invoke_options
+          timed("Prune") { invoke "dash:cli:prune:all", [], invoke_options }
         end
       end
 
@@ -78,23 +78,23 @@ class Dash::Cli::Main < Dash::Cli::Base
 
         if options[:skip_push]
           say "Pull app image...", :magenta
-          invoke "dash:cli:build:pull", [], invoke_options
+          timed("Pull app image") { invoke "dash:cli:build:pull", [], invoke_options }
         else
           say "Build and push app image...", :magenta
-          invoke "dash:cli:build:deliver", [], invoke_options
+          timed("Build and push app image") { invoke "dash:cli:build:deliver", [], invoke_options }
         end
 
         modify(lock: true) do
           run_hook "pre-deploy", secrets: true
 
           say "Detect stale containers...", :magenta
-          invoke "dash:cli:app:stale_containers", [], invoke_options.merge(stop: true)
+          timed("Detect stale containers") { invoke "dash:cli:app:stale_containers", [], invoke_options.merge(stop: true) }
 
-          invoke "dash:cli:app:boot", [], invoke_options
+          timed("Boot") { invoke "dash:cli:app:boot", [], invoke_options }
 
           if DASH.config.proxy.load_balancing?
             say "Updating loadbalancer configuration...", :magenta
-            invoke "dash:cli:proxy:loadbalancer", [ "deploy" ], invoke_options
+            timed("Loadbalancer") { invoke "dash:cli:proxy:loadbalancer", [ "deploy" ], invoke_options }
           end
         end
       end
@@ -117,7 +117,7 @@ class Dash::Cli::Main < Dash::Cli::Base
           if container_available?(version)
             run_hook "pre-deploy", secrets: true
 
-            invoke "dash:cli:app:boot", [], invoke_options.merge(version: version)
+            timed("Boot") { invoke "dash:cli:app:boot", [], invoke_options.merge(version: version) }
             rolled_back = true
           else
             say "The app version '#{version}' is not available as a container (use 'dash app containers' for available versions)", :red

data/lib/dash/commander.rb

@@ -6,7 +6,7 @@ require "active_support/notifications"
 
 class Dash::Commander
   attr_accessor :verbosity, :holding_lock, :holding_server_lock, :connected, :logging, :lock_wait, :lock_wait_timeout, :lock_wait_interval
-  attr_reader :specific_roles, :specific_hosts
+  attr_reader :specific_roles, :specific_hosts, :timings
   delegate :hosts, :roles, :primary_host, :primary_role, :roles_on, :app_hosts, :proxy_hosts, :accessory_hosts, to: :specifics
 
   def initialize
@@ -23,6 +23,7 @@ class Dash::Commander
     self.lock_wait_timeout = 900
     self.lock_wait_interval = 15
     @modify_depth = 0
+    @timings = Dash::Timings.new
     @specifics = @specific_roles = @specific_hosts = nil
     @config = @config_kwargs = nil
     @output_logger = nil

data/lib/dash/configuration/boot.rb

@@ -8,6 +8,7 @@ class Dash::Configuration::Boot
   def initialize(config:, boot_config: nil, context: nil)
     @boot_config = boot_config || config.raw_config.boot || {}
     validate! @boot_config, context: context
+    validate_canary!(context || self.class.validation_config_key)
   end
 
   # The group size to slice `hosts` by. A percentage only means something against the set
@@ -35,6 +36,22 @@ class Dash::Configuration::Boot
     boot_config["wait"]
   end
 
+  # How many primary-role hosts boot alone, one at a time, before the rest boot together.
+  # Whole-deploy only — Cli::App#host_boot_groups is the sole consumer.
+  def canary
+    boot_config["canary"]
+  end
+
+  def canary?
+    canary.present?
+  end
+
+  # Whether this config splits hosts into more than one group at all — what `wait` needs
+  # in order to mean anything.
+  def groups?
+    limit? || canary?
+  end
+
   def parallel_roles
     boot_config["parallel_roles"]
   end
@@ -57,4 +74,20 @@ class Dash::Configuration::Boot
       { in: :groups, limit: limit, wait: wait.to_i }
     end
   end
+
+  private
+    # The example-driven validator has already checked the type; the range and the
+    # top-level-only rule are ours. A role-scoped Boot always carries a context.
+    def validate_canary!(context)
+      return unless canary?
+
+      if context != self.class.validation_config_key
+        raise Dash::ConfigurationError, "#{context}/canary is only supported at the top-level boot: " \
+          "it slices the primary role's hosts ahead of every other role"
+      end
+
+      if canary < 1
+        raise Dash::ConfigurationError, "#{context}/canary must be at least 1, got #{canary}"
+      end
+    end
 end

data/lib/dash/configuration/docs/boot.yml

@@ -26,6 +26,20 @@ boot:
   # moves on as soon as the last host is up.
   wait: 10
 
+  # The number of primary-role hosts to boot one at a time before the rest of the hosts boot.
+  #
+  # A canary is the gate people reach for `limit: 1` to get — prove the new version on one host
+  # before touching the fleet — without serialising every host after it. The first N hosts of the
+  # primary role each boot alone; a boot failure there stops the deploy before any other host is
+  # touched. The remaining hosts of every role then boot together, or in groups when `limit` is
+  # also set (a percentage limit counts those remaining hosts). `wait` paces canary and remaining
+  # groups alike. Behind dash-proxy this never reduces capacity: each host keeps serving the old
+  # container until the new one passes its health check.
+  #
+  # Top-level only. A role-scoped `boot` refuses it: the canary slices the primary role's hosts
+  # ahead of every other role, which a single role cannot express.
+  canary: 1
+
   # Whether to boot roles in parallel on a host.
   #
   # If a host has multiple roles, control whether they are booted in parallel or sequentially on that host.

data/lib/dash/configuration/docs/configuration.yml

@@ -82,7 +82,7 @@ asset_path: /path/to/assets
 # Hooks path
 #
 # Path to hooks, defaults to `.dash/hooks` (`.kamal/hooks` is still read when only that exists).
-# See https://kamal-deploy.org/docs/hooks for more information:
+# See https://dash.zoolutions.llc/docs/hooks for every hook, when it fires, and its environment:
 hooks_path: /user_home/kamal/hooks
 
 # Hook output

data/lib/dash/configuration/docs/env.yml

@@ -31,7 +31,7 @@ env:
 # RAILS_MASTER_KEY=$(cat config/master.key)
 # ```
 #
-# You can also use [secret helpers](../../commands/secrets) for some common password managers.
+# You can also use [secret helpers](https://dash.zoolutions.llc/docs/secrets) for common password managers and secret stores.
 #
 # ```shell
 # SECRETS=$(dash secrets fetch ...)

data/lib/dash/configuration/docs/proxy.yml

@@ -834,7 +834,7 @@ proxy:
                                    # below already embeds its ghcr.io host
     repository: ghcr.io/zoolutions/dash-proxy # Container repository for the
                                    # dash-proxy image (this is the default)
-    version: v1.1.0.0              # Version tag of the dash-proxy image to use.
+    version: v1.1.0.1              # Version tag of the dash-proxy image to use.
                                    # Defaults to the minimum version this gem
                                    # requires - only pin it to roll forward early,
                                    # never below the default

data/lib/dash/configuration/proxy/run.rb

@@ -1,5 +1,5 @@
 class Dash::Configuration::Proxy::Run
-  MINIMUM_VERSION = "v1.1.0.0"
+  MINIMUM_VERSION = "v1.1.0.1"
   DEFAULT_HTTP_PORT = 80
   DEFAULT_HTTPS_PORT = 443
   DEFAULT_LOG_MAX_SIZE = "10m"

data/lib/dash/configuration/registry.rb

@@ -4,6 +4,7 @@ class Dash::Configuration::Registry
   def initialize(config:, secrets:, context: "registry")
     @registry_config = config["registry"] || {}
     @secrets = secrets
+    @context = context
     validate! registry_config, context: context, with: Dash::Configuration::Validator::Registry
   end
 
@@ -28,13 +29,33 @@ class Dash::Configuration::Registry
   end
 
   private
-    attr_reader :registry_config, :secrets
+    attr_reader :registry_config, :secrets, :context
 
+    # A blank credential would reach the remote host as an empty `docker login -p`,
+    # where docker falls back to prompting and dies with the opaque "Cannot perform
+    # an interactive login from a non TTY device" — fail locally instead.
     def lookup(key)
+      value =
+        if registry_config[key].is_a?(Array)
+          secrets[registry_config[key].first]
+        else
+          registry_config[key]
+        end
+
+      validate_present! key, value unless local?
+      value
+    end
+
+    def validate_present!(key, value)
+      return if value.present?
+
       if registry_config[key].is_a?(Array)
-        secrets[registry_config[key].first]
+        secret = registry_config[key].first
+        raise Dash::ConfigurationError,
+          "#{context}/#{key}: secret '#{secret}' resolved to an empty value — " \
+          "if your secrets file forwards it from the environment (#{secret}=$#{secret}), export the variable before running dash"
       else
-        registry_config[key]
+        raise Dash::ConfigurationError, "#{context}/#{key}: is blank"
       end
     end
 end

data/lib/dash/configuration.rb

@@ -592,17 +592,17 @@ class Dash::Configuration
     end
 
     # `wait` only ever fills the gap between one group of hosts and the next, and without a
-    # `limit` there are no gaps — every host boots in one group. Before #47 that silently
+    # `limit` or a `canary` there are no gaps — every host boots in one group. Before #47 that silently
     # cost a deploy one `wait` interval; now it silently does nothing at all. Either way the
     # operator asked for staggering and is not getting it, so say so.
     def ensure_boot_wait_paces_something
       offenders = [ [ "boot", boot ], *roles.filter_map { |role| [ "servers/#{role.name}/boot", role.boot ] if role.boot } ]
-        .select { |_context, boot_config| boot_config.wait.present? && !boot_config.limit? }
+        .select { |_context, boot_config| boot_config.wait.present? && !boot_config.groups? }
 
       offenders.each do |context, boot_config|
         warn "#{context}/wait is set to #{boot_config.wait} but #{context}/limit is not, so it does nothing. " \
           "`wait` paces one group of hosts against the next, and without a limit every host boots in a single group. " \
-          "Set `#{context}/limit` to stagger the boot, or remove `#{context}/wait`."
+          "Set `#{context}/limit` or `#{context}/canary` to stagger the boot, or remove `#{context}/wait`."
       end
 
       true

data/lib/dash/timings.rb

@@ -0,0 +1,45 @@
+# Wall-clock accounting for a deploy, printed under "Finished all in". The total on its
+# own says nothing about where the time went — a serialised boot, a slow pull, or a proxy
+# waiting on a health check all look the same from the outside.
+#
+# Entries land in start order and carry a depth, so a parent phase (Boot) prints above
+# the host entries it wraps even though the hosts finish first. Boot runs one thread per
+# host, so every mutation is behind the mutex.
+class Dash::Timings
+  Entry = Struct.new(:name, :seconds, :detail, :depth)
+
+  def initialize
+    @entries = []
+    @mutex = Mutex.new
+  end
+
+  # Times the block. The entry is yielded so the block can annotate it — a boot can say
+  # how long of its total was spent waiting for the container to become healthy.
+  def phase(name, depth: 0)
+    entry = Entry.new(name, nil, nil, depth)
+    @mutex.synchronize { @entries << entry }
+    started = clock
+
+    yield entry
+  ensure
+    entry.seconds = clock - started
+  end
+
+  def any?
+    @mutex.synchronize { @entries.any? }
+  end
+
+  def lines
+    @mutex.synchronize do
+      @entries.map do |entry|
+        line = format("  %s%-36s %6.1fs", "  " * entry.depth, entry.name, entry.seconds.to_f)
+        entry.detail ? "#{line} (#{entry.detail})" : line
+      end
+    end
+  end
+
+  private
+    def clock
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+end

data/lib/dash/version.rb

@@ -1,3 +1,3 @@
 module Dash
-  VERSION = "4.0.4"
+  VERSION = "4.0.7"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dash
 version: !ruby/object:Gem::Version
-  version: 4.0.4
+  version: 4.0.7
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -329,6 +329,7 @@ files:
 - lib/dash/secrets/dotenv/inline_command_substitution.rb
 - lib/dash/sshkit_with_ext.rb
 - lib/dash/tags.rb
+- lib/dash/timings.rb
 - lib/dash/utils.rb
 - lib/dash/utils/sensitive.rb
 - lib/dash/version.rb