dash 4.0.3 → 4.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 563633a7568cdc7c4567bbe4957af6e5212e37b3ae99ddda0e990552f949762f
-  data.tar.gz: dda127134f2d0ef7fc4e7636ce7132106842855f9084d082a5a3b65c41313b56
+  metadata.gz: ee8ed58f4d81341ced43dc7d970c081a4c92becc3492860cf3ec8fd1a80687ec
+  data.tar.gz: 588e1b33ca3f041a54beb773472cab9b8144892a32972b71ae9c58306cbb8612
 SHA512:
-  metadata.gz: 8ebab61a7f7f4df70ecd48e5e95415198a01990e6ae6ce93dca062775f2d11b91d2a971bcf9b0b13b4cd3aa6940700c45f8fc73bc1c50be64fe9478e2e1d7ca8
-  data.tar.gz: 5cda006f0c95a79eea3198c9caa089d5e3b3d064860b6d031efe12b65513b2d4219ce04b62b5a9c66532bbda38681ba0ec8dd6cd51143b270588a804be647488
+  metadata.gz: b24d5758340f3e3b7b7b6ecf1df765ffabab7360ddd5bc0df99dad3b90ba3662fc65dcbbe6bfa99af29dea90efb977f4b3d5a2d68454c1e652d57602857f9166
+  data.tar.gz: bbc5bfea941e10310fd01776548b462e9e0e82d4228ed25bb66a0c16b35083979473cb2232ccb7bab3820ccaa45ae32303f424ffebfe76ac321b84354c54cf2e

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/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/cli/proxy/loadbalancer_reboot.rb

@@ -19,6 +19,7 @@ class Dash::Cli::Proxy::LoadbalancerReboot
   def run
     execute *DASH.auditor.record("Rebooted loadbalancer"), verbosity: :debug
     execute *DASH.registry.login
+    ensure_network
 
     info "Stopping and removing #{DASH.loadbalancer.container_name} on #{host}, if running..."
     execute *DASH.loadbalancer.stop, raise_on_non_zero_exit: false
@@ -45,6 +46,16 @@ class Dash::Cli::Proxy::LoadbalancerReboot
   end
 
   private
+    # Before the old container is stopped: `docker run` against a missing
+    # network would otherwise fail with the edge already down. A dedicated
+    # loadbalancer host has no other path that creates the network
+    # (zoolutions/dash#140).
+    def ensure_network
+      execute *DASH.docker.create_network
+    rescue SSHKit::Command::Failed => e
+      raise unless e.message.include?("already exists")
+    end
+
     def wait_until_ready
       deadline = Time.now + READY_TIMEOUT
 

data/lib/dash/cli/proxy.rb

@@ -2,7 +2,7 @@ class Dash::Cli::Proxy < Dash::Cli::Base
   desc "boot", "Boot proxy on servers"
   def boot
     modify(lock: true, server_lock: true) do
-      on(DASH.hosts) do |host|
+      on(network_hosts) do |host|
         execute *DASH.docker.create_network
       rescue SSHKit::Command::Failed => e
         raise unless e.message.include?("already exists")
@@ -76,8 +76,10 @@ class Dash::Cli::Proxy < Dash::Cli::Base
           info "Starting loadbalancer on #{host}..."
           execute *DASH.registry.login
 
-          # Bring a pre-rename volume across before the container can be created
-          # against an empty one. A no-op once it has been.
+          # Bring a pre-rename host across before the container can be created
+          # against an empty volume or a network nothing else joined. A no-op
+          # once it has been.
+          execute *DASH.docker.connect_legacy_network_containers
           execute *DASH.loadbalancer.copy_legacy_config_volume
 
           # The load balancer terminates TLS and owns the cache, so its host
@@ -653,6 +655,15 @@ class Dash::Cli::Proxy < Dash::Cli::Base
   end
 
   private
+    # Every host that runs a container on the proxy network. A dedicated
+    # loadbalancer host is not in DASH.hosts, and nothing else creates the
+    # network there (zoolutions/dash#140).
+    def network_hosts
+      hosts = DASH.hosts
+      hosts |= [ DASH.config.proxy.effective_loadbalancer ] if DASH.config.proxy.load_balancing?
+      hosts
+    end
+
     # The host that owns TLS, and so the certificate store: the loadbalancer
     # host when load balancing (TLS terminates at the edge), else the primary
     # host - the same host `loadbalancer: true` would resolve to.

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.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.3"
+  VERSION = "4.0.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dash
 version: !ruby/object:Gem::Version
-  version: 4.0.3
+  version: 4.0.5
 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