dash 2.12.0 → 3.0.0

data/lib/kamal/configuration/role.rb

@@ -3,7 +3,7 @@ class Kamal::Configuration::Role
 
   delegate :argumentize, :optionize, to: Kamal::Utils
 
-  attr_reader :name, :config, :specialized_env, :specialized_logging, :specialized_proxy
+  attr_reader :name, :config, :specialized_env, :specialized_logging, :specialized_proxy, :healthcheck
 
   alias to_s name
 
@@ -24,6 +24,13 @@ class Kamal::Configuration::Role
       logging_config: specializations.fetch("logging", {}),
       context: "servers/#{name}/logging"
 
+    # `healthcheck: false` is an opt-out, not a healthcheck — it leaves @healthcheck nil.
+    if healthcheck_config = specializations["healthcheck"]
+      @healthcheck = Kamal::Configuration::Role::Healthcheck.new \
+        healthcheck_config: healthcheck_config,
+        context: "servers/#{name}/healthcheck"
+    end
+
     initialize_specialized_proxy
   end
 
@@ -39,6 +46,14 @@ class Kamal::Configuration::Role
     tagged_hosts.fetch(host).collect { |tag| config.env_tag(tag) }.compact
   end
 
+  # The role's own hosts carrying `tag` in deploy.yml. Accessory `tag:`/`tags:` resolution
+  # comes through here rather than re-walking raw_config.servers, so it inherits
+  # extract_hosts_from_config's handling of every legal role shape — bare list, `hosts:`
+  # mapping, and the top-level `servers:` array.
+  def hosts_with_tag(tag)
+    tagged_hosts.select { |_host, tags| tags.include?(tag) }.keys
+  end
+
   def cmd
     specializations["cmd"]
   end
@@ -63,10 +78,40 @@ class Kamal::Configuration::Role
     logging.args
   end
 
+  # Kept out of option_args on purpose: Commands::App::Execution splats those into
+  # one-shot `kamal app exec` containers, which must not inherit a service healthcheck.
+  def healthcheck_args
+    healthcheck&.args || []
+  end
+
   def logging
     @logging ||= config.logging.merge(specialized_logging)
   end
 
+  # nil unless the role paces its own hosts. Deliberately not falling back to the global
+  # boot: that limit is already spent slicing the cross-role host list in
+  # Cli::App#host_boot_groups, and handing it to the per-role runner as well would sleep
+  # `boot.wait` a second time inside every group.
+  #
+  # Built on first read rather than in the initializer — Servers.new constructs every Role
+  # before Kamal::Configuration#initialize has finished assigning its own collaborators.
+  def boot
+    return @boot if defined?(@boot)
+
+    @boot =
+      if (boot_config = specializations["boot"])
+        Kamal::Configuration::Boot.new \
+          config: config, boot_config: boot_config, context: "servers/#{name}/boot"
+      end
+  end
+
+  # `hosts` is what on_roles is about to pace — `role.hosts & the run's hosts`, so
+  # --roles/--hosts have already narrowed it. A percentage limit has to count that, not
+  # the role's configured hosts.
+  def boot_runner_options(hosts)
+    boot&.runner_options_for(hosts) || {}
+  end
+
   def proxy
     @proxy ||= specialized_proxy.merge(config.proxy) if running_proxy?
   end
@@ -79,6 +124,49 @@ class Kamal::Configuration::Role
     running_proxy? && proxy.ssl?
   end
 
+  # Where a deploy of this role actually waits for readiness before stopping the
+  # old container. Without a proxy or a docker healthcheck, Healthcheck::Poller
+  # only sees `.State.Status`, so staying `running` for the readiness delay is
+  # the whole gate. `:healthcheck_exec` is the odd one out: the container declares no
+  # docker healthcheck, the deploy host polls the probe itself.
+  def readiness_source
+    if running_proxy?
+      :proxy
+    elsif healthcheck&.exec?
+      :healthcheck_exec
+    elsif healthcheck
+      :healthcheck
+    elsif health_cmd_option?
+      :docker_options
+    else
+      :none
+    end
+  end
+
+  # One-line rendering of readiness_source, shared by the deploy banner and `kamal doctor`
+  # so both name the same gate the same way.
+  def readiness_description
+    case readiness_source
+    when :proxy
+      [ "kamal-proxy health check", proxy.healthcheck_path ].compact.join(" ")
+    when :healthcheck
+      healthcheck.port ? "healthcheck #{healthcheck.path}:#{healthcheck.port}" : "healthcheck (custom cmd)"
+    when :healthcheck_exec
+      "healthcheck exec probe (#{healthcheck.exec})"
+    when :docker_options
+      "docker healthcheck (options: health-cmd)"
+    else
+      "NONE (old container stops #{readiness_delay}s after boot)"
+    end
+  end
+
+  # Whether the operator has made a readiness decision for this role at all — declared a
+  # healthcheck, hand-rolled a health-cmd option, or accepted the gap with `healthcheck: false`.
+  # Distinct from readiness_source, which reports what actually gates the deploy.
+  def readiness_gated?
+    healthcheck.present? || health_cmd_option? || healthcheck_disabled?
+  end
+
   def stop_args
     # When deploying with the proxy, kamal-proxy will drain request before returning so we don't need to wait.
     timeout = stop_timeout || (running_proxy? ? nil : config.drain_timeout)
@@ -90,6 +178,13 @@ class Kamal::Configuration::Role
     specializations["stop_timeout"] || config.stop_timeout
   end
 
+  # How long a role that has no healthcheck must merely keep running before the deploy
+  # accepts it. Role-specialized so a role that legitimately opts out can be tuned
+  # without slowing every other role down.
+  def readiness_delay
+    specializations["readiness_delay"] || config.readiness_delay
+  end
+
   def env(host)
     @envs ||= {}
     @envs[host] ||= [ config.env, specialized_env, *env_tags(host).map(&:env) ].reduce(:merge)
@@ -230,6 +325,14 @@ class Kamal::Configuration::Role
       docker_options.find { |key, _| key.to_s == "restart" }&.last
     end
 
+    def health_cmd_option?
+      docker_options.any? { |key, _| key.to_s == "health-cmd" }
+    end
+
+    def healthcheck_disabled?
+      specializations["healthcheck"] == false
+    end
+
     def custom_labels
       Hash.new.tap do |labels|
         labels.merge!(config.labels) if config.labels.present?