dash 2.12.0 → 3.0.0

data/lib/kamal/configuration/validator/role.rb

@@ -8,6 +8,32 @@ class Kamal::Configuration::Validator::Role < Kamal::Configuration::Validator
       super
       validate_labels!(config["labels"])
       validate_docker_options!(config["options"])
+      validate_healthcheck_options!(config["healthcheck"], config["options"])
     end
   end
+
+  private
+    # `healthcheck: false` is the explicit opt-out from the readiness gate, so the
+    # example's hash shape is not the only legal one.
+    def validate_key_override!(key, value)
+      return false unless key.to_s == "healthcheck"
+
+      case value
+      when false then true
+      when Hash then false
+      else error "should be a hash, or false to accept no readiness gate for this role"
+      end
+    end
+
+    # Docker takes the last --health-* flag it sees, so overlapping sources would
+    # silently pick a winner. Refuse the ambiguity instead.
+    def validate_healthcheck_options!(healthcheck, options)
+      return if healthcheck.blank?
+
+      if health_option = options&.find { |key, _| key.to_s.start_with?("health-") }
+        with_context("healthcheck") do
+          error "cannot be combined with options/#{health_option.first}, remove one of them"
+        end
+      end
+    end
 end

data/lib/kamal/configuration/validator.rb

@@ -27,7 +27,7 @@ class Kamal::Configuration::Validator
               unless key.to_s == "proxy" && boolean?(value.class)
                 validate_type! value, *(Array if key == :servers), Hash
               end
-            elsif key.to_s == "ssl"
+            elsif key.to_s == "ssl" || key.to_s == "compress"
                 validate_type! value, TrueClass, FalseClass, Hash
             elsif key.to_s == "hooks_output"
                 validate_hooks_output!(value)
@@ -47,10 +47,10 @@ class Kamal::Configuration::Validator
               case key.to_s
               when "options", "args"
                 validate_type! value, Hash
-              when "labels"
+              when "labels", "path_response_timeouts", "path_request_timeouts"
                 validate_hash_of! value, example_value.first[1].class
               else
-                validate_against_example! value, example_value
+                validate_against_example! value, example_value unless validate_key_override!(key, value)
               end
             else
               validate_type! value, example_value.class
@@ -180,6 +180,12 @@ class Kamal::Configuration::Validator
       type_error(*types) unless types.any? { |type| valid_type?(value, type) }
     end
 
+    # Hook for subclasses that accept a shape the example cannot express. Return true
+    # when the key was fully validated here and the example should be skipped.
+    def validate_key_override!(key, value)
+      false
+    end
+
     def error(message)
       raise Kamal::ConfigurationError, "#{error_context}#{message}"
     end
@@ -235,6 +241,23 @@ class Kamal::Configuration::Validator
       if restart_policy = options&.find { |key, _| key.to_s == "restart" }
         validate_restart_policy!(restart_policy.last)
       end
+
+      validate_health_option_expansion!(options)
+    end
+
+    # Kamal::Utils::DOLLAR_SIGN_WITHOUT_SHELL_EXPANSION_REGEX escapes a bare `$` but exempts
+    # `${...}`, leaving it for the deploy host's shell to expand at docker run time. Role env
+    # never reaches that shell, so `${SOME_ENV}` in a health command silently becomes empty and
+    # the container sits `starting` until deploy_timeout. Reject it where it is most likely written.
+    def validate_health_option_expansion!(options)
+      options&.each do |key, value|
+        next unless key.to_s.start_with?("health-")
+        next unless Array(value).any? { |entry| entry.to_s.include?("${") }
+
+        with_context("options/#{key}") do
+          error "cannot contain ${...}, which the deploy host's shell expands at docker run time, not the container — a role env var resolves to empty. Use the bare $VAR form, which expands in the container, or a literal value"
+        end
+      end
     end
 
     def validate_restart_policy!(restart_policy)

data/lib/kamal/configuration.rb

@@ -87,7 +87,42 @@ class Kamal::Configuration
     ensure_unique_hosts_for_ssl_roles
     ensure_local_registry_remote_builder_has_ssh_url
     ensure_no_conflicting_proxy_runs
+    ensure_valid_loadbalancer
     ensure_valid_hooks_output!
+    ensure_unproxied_roles_are_readiness_gated
+    ensure_role_boot_can_pace_its_hosts
+    ensure_boot_wait_paces_something
+    ensure_rate_limit_can_identify_clients
+    ensure_intercepted_errors_have_pages
+    ensure_sleep_has_a_docker_socket
+    ensure_proxy_protocol_names_its_peers
+    ensure_max_idle_conns_meaningful
+  end
+
+  # Resolves every secret the deploy will need so a missing secret fails fast,
+  # before any registry login or SSH connection. Secret adapters run here
+  # instead of mid-deploy — same work, done earlier.
+  def validate_secrets!(include_accessories: false)
+    registry.username
+    registry.password
+    builder.secrets
+
+    roles.each do |role|
+      role.secrets_io(role.hosts.first) if role.hosts.any?
+
+      if role.running_proxy?
+        role.proxy.run&.secrets_io
+
+        if role.proxy.custom_ssl_certificate?
+          role.proxy.certificate_pem_content
+          role.proxy.private_key_pem_content
+        end
+      end
+    end
+
+    accessories.each(&:secrets_io) if include_accessories
+
+    true
   end
 
   def version=(version)
@@ -137,6 +172,14 @@ class Kamal::Configuration
     roles.select { |role| role.hosts.include?(host) }
   end
 
+  # Whether app commands iterate role-first. A role pacing its own hosts needs that: the
+  # host-first branch of on_roles has no per-role runner to hand boot options to. Setting
+  # `boot` on a role only overrides an unset parallel_roles — an explicit false conflicts
+  # and is rejected in ensure_role_boot_can_pace_its_hosts.
+  def parallel_roles?
+    !!(boot.parallel_roles || roles.any?(&:boot))
+  end
+
   def host_accessories(host)
     accessories.select { |accessory| accessory.hosts.include?(host) }
   end
@@ -400,6 +443,150 @@ class Kamal::Configuration
       true
     end
 
+    # A role without a proxy and without a healthcheck has no readiness gate: the deploy
+    # accepts the container as ready once it is merely still running after readiness_delay,
+    # then stops the old one. Warn-only for now so existing configs keep deploying.
+    def ensure_unproxied_roles_are_readiness_gated
+      offenders = roles.reject { |role| role.hosts.empty? || role.running_proxy? || role.readiness_gated? }
+      return true if offenders.empty?
+
+      warn "Non-proxied role(s) #{offenders.map(&:name).join(", ")} have no healthcheck. " \
+        "Without one, Kamal accepts the container as ready #{readiness_delay}s after it merely starts " \
+        "and then stops the previous container — traffic can be dropped. Add a `healthcheck:` block, " \
+        "or opt out explicitly with `healthcheck: false`. This warning will become an error in a future release."
+
+      true
+    end
+
+    # A PROXY protocol header rewrites the connecting address, which is the one
+    # thing on a request nothing else can influence — and the one every access
+    # control decision keys on. Honouring it from any peer that can reach the
+    # port hands that address to whoever asks. Warn rather than raise: a proxy on
+    # a private network with no other route in is a legitimate configuration.
+    def ensure_proxy_protocol_names_its_peers
+      offenders = all_hosts.select { |host| proxy_run(host)&.proxy_protocol_unrestricted? }
+      return true if offenders.empty?
+
+      warn "Host(s) #{offenders.sort.join(", ")}: proxy_protocol is enabled without proxy_protocol_allow_ips, " \
+        "so kamal-proxy honours a PROXY header from any peer that can reach the port. That header sets the client " \
+        "address `allow_ips`, `rate_limit` and the access log all use. Name the load balancers you actually run."
+
+      true
+    end
+
+    # Scale-to-zero is a deploy-time setting with a boot-time prerequisite: the
+    # proxy can only stop and start containers through the runtime socket, and it
+    # is only mounted when proxy/run/docker_socket names it. Without that, the
+    # first request after an idle period hangs until wake_timeout and 503s, which
+    # reads as a broken proxy rather than as a missing key. Say the key instead.
+    #
+    # Checked here rather than in Validator::Proxy because a role may carry
+    # `sleep` while the root carries the socket — role.proxy is the merged view,
+    # the validator only ever sees one side.
+    def ensure_sleep_has_a_docker_socket
+      offenders = roles.select do |role|
+        next false unless role.running_proxy?
+
+        role.proxy.proxy_config.dig("sleep", "after").present? && role.proxy.run&.docker_socket.blank?
+      end
+
+      return true if offenders.empty?
+
+      raise Kamal::ConfigurationError, "Role(s) #{offenders.map(&:name).join(", ")}: " \
+        "proxy/sleep requires proxy/run/docker_socket - kamal-proxy can only stop and start containers " \
+        "through the container runtime socket, and it is not mounted into the proxy without it"
+    end
+
+    # kamal-proxy resolves a zero max_idle_conns to its default of 100
+    # (target_pool.go resolves defaults from zeros), so the one value an
+    # operator writes to mean "keep none" is the one value that cannot mean it.
+    # Legal, so warn rather than raise.
+    def ensure_max_idle_conns_meaningful
+      offenders = roles.select do |role|
+        role.running_proxy? && role.proxy.proxy_config.dig("target", "max_idle_conns") == 0
+      end
+      return true if offenders.empty?
+
+      warn "Role(s) #{offenders.map(&:name).join(", ")}: target/max_idle_conns: 0 means the proxy default of 100, " \
+        "not \"keep none\" - kamal-proxy resolves its defaults from zeros. Leave it unset for the default, " \
+        "or set 1 for the practical minimum."
+
+      true
+    end
+
+    # `intercept_errors` discards the app's error body and renders the proxy's own
+    # page instead. With no pages to render, kamal-proxy falls back to a bare
+    # plaintext status line — so the app's error page is thrown away and replaced
+    # by the words "Bad Gateway". Legal, and almost never the intent.
+    def ensure_intercepted_errors_have_pages
+      return true if error_pages_path.present?
+
+      offenders = roles.select { |role| role.running_proxy? && role.proxy.proxy_config["intercept_errors"].present? }
+      return true if offenders.empty?
+
+      warn "Role(s) #{offenders.map(&:name).join(", ")}: intercept_errors is set but no error_pages_path is " \
+        "configured, so kamal-proxy replaces the app's error page with a bare plaintext status line. " \
+        "Set `error_pages_path:` to serve your own pages, or remove `intercept_errors` to let the app's through."
+
+      true
+    end
+
+    # A rate limiter is only as correct as the address it keys on. `forward_headers:
+    # true` says something sits in front of the proxy, and without `trusted_proxies`
+    # kamal-proxy keys on that something's address rather than the client's — so the
+    # limiter throttles the whole world as one client, or nobody at all. Warn rather
+    # than raise: the config is legal, just almost certainly not what was meant.
+    def ensure_rate_limit_can_identify_clients
+      offenders = roles.select do |role|
+        next false unless role.running_proxy?
+
+        proxy_config = role.proxy.proxy_config
+        proxy_config.dig("rate_limit", "requests").present? &&
+          proxy_config["forward_headers"] &&
+          Array(proxy_config.dig("client_ip", "trusted_proxies")).empty?
+      end
+
+      return true if offenders.empty?
+
+      warn "Role(s) #{offenders.map(&:name).join(", ")}: rate_limit is set with forward_headers, " \
+        "but no proxy/client_ip/trusted_proxies. kamal-proxy will key the limiter on the address of " \
+        "whatever sits in front of it, not on the client's — so it throttles every visitor as one " \
+        "client, or none of them. Declare the proxies in front with `client_ip: trusted_proxies:`."
+
+      true
+    end
+
+    # `parallel_roles: false` iterates host-first, running each host's roles one after
+    # another inside a single per-host thread. There is no per-role runner there to pace,
+    # so the two keys cannot both be honoured — say which one to drop rather than quietly
+    # ignoring either.
+    def ensure_role_boot_can_pace_its_hosts
+      # select, not find: this is also where every role-scoped Boot gets built, so a bad
+      # one raises here rather than partway through a deploy.
+      paced = roles.select(&:boot)
+      return true if paced.empty? || boot.parallel_roles != false
+
+      raise Kamal::ConfigurationError, "servers/#{paced.first.name}/boot cannot be combined with boot/parallel_roles: false, " \
+        "which boots each host's roles in turn and so cannot pace one role's hosts. Remove one of them"
+    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
+    # 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? }
+
+      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`."
+      end
+
+      true
+    end
+
     def ensure_unique_hosts_for_ssl_roles
       hosts = roles.select(&:ssl?).flat_map { |role| role.proxy.hosts }
       duplicates = hosts.tally.filter_map { |host, count| host if count > 1 }
@@ -432,6 +619,16 @@ class Kamal::Configuration
       (host_roles(host) + host_accessories(host)).map(&:proxy).compact.map(&:run).compact
     end
 
+    # `loadbalancer: true` resolves to the primary role's first host, so an
+    # accessories-only configuration has nothing to run it on.
+    def ensure_valid_loadbalancer
+      if proxy.loadbalancer == true && primary_role.nil?
+        raise Kamal::ConfigurationError, "proxy/loadbalancer: can't be enabled without servers"
+      end
+
+      true
+    end
+
     def role_names
       raw_config.servers.is_a?(Array) ? [ "web" ] : raw_config.servers.keys.sort
     end

data/lib/kamal/sshkit_with_ext.rb

@@ -209,6 +209,26 @@ class SSHKit::Runner::Parallel
   prepend CompleteAll
 end
 
+class SSHKit::Runner::Group
+  # SSHKit sleeps after every slice, including the last, so a paced role pays one wait
+  # interval buying nothing — there is no next group for it to pace against. Kamal's boot
+  # wait means "hold off before starting the next group", which is what Sequential already
+  # does by popping its last host.
+  module NoTrailingWait
+    def execute
+      slices = hosts.each_slice(group_size).to_a
+
+      slices.each_with_index.flat_map do |group_hosts, index|
+        result = SSHKit::Runner::Parallel.new(group_hosts, &block).execute
+        sleep wait_interval if index < slices.size - 1
+        result
+      end
+    end
+  end
+
+  prepend NoTrailingWait
+end
+
 # Avoid net-ssh debug, until https://github.com/net-ssh/net-ssh/pull/953 is merged
 module NetSshForwardingNoPuts
   def puts(*)
@@ -228,17 +248,22 @@ module SSHKitDslRoles
   #   parallel: When true, each role runs in its own thread with separate
   #             connections. When false, hosts run in parallel but roles on each
   #             host run sequentially (default: true)
+  #   rolling:  When true, each role's own `boot` config paces its hosts through
+  #             the SSHKit runner, so one role can boot serially while its
+  #             siblings still boot in parallel. Only for commands that start
+  #             containers — it would needlessly serialize read-only commands.
+  #             Requires parallel: there is no per-role runner otherwise.
   #
   # Example:
   #   on_roles(roles) do |host, role|
   #     # deploy role to host
   #   end
-  def on_roles(roles, hosts:, parallel: true, &block)
+  def on_roles(roles, hosts:, parallel: true, rolling: false, &block)
     if parallel
       threads = roles.filter_map do |role|
         if (role_hosts = role.hosts & hosts).any?
           Thread.new do
-            on(role_hosts) { |host| instance_exec(host, role, &block) }
+            on(role_hosts, rolling ? role.boot_runner_options(role_hosts) : {}) { |host| instance_exec(host, role, &block) }
           rescue StandardError => e
             raise SSHKit::Runner::ExecuteError.new(e), "Exception while executing on #{role}: #{e.message}"
           end

data/lib/kamal/utils.rb

@@ -21,16 +21,36 @@ module Kamal::Utils
   end
 
   # Returns a list of shell-dashed option arguments. If the value is true, it's treated like a value-less option.
+  # A Sensitive value stays Sensitive: the rendered option keeps the real value
+  # for execution and a redacted form for anything kamal prints - same contract
+  # as argumentize's `sensitive:` kwarg, but decided per value by the caller.
   def optionize(args, with: nil, escape: true)
     options = if with
-      flatten_args(args).collect { |(key, value)| value == true ? "--#{key}" : "--#{key}#{with}#{escape ? escape_shell_value(value) : value}" }
+      flatten_args(args).collect do |(key, value)|
+        if value == true
+          "--#{key}"
+        else
+          rendered = "--#{key}#{with}#{escape ? escape_shell_value(value) : value}"
+          value.is_a?(Kamal::Utils::Sensitive) ? sensitive(rendered, redaction: "--#{key}#{with}#{value.redaction}") : rendered
+        end
+      end
     else
-      flatten_args(args).collect { |(key, value)| [ "--#{key}", value == true ? nil : escape ? escape_shell_value(value) : value ] }
+      flatten_args(args).collect do |(key, value)|
+        rendered = value == true ? nil : escape ? escape_shell_value(value) : value
+        rendered = sensitive(rendered, redaction: value.redaction) if value.is_a?(Kamal::Utils::Sensitive)
+        [ "--#{key}", rendered ]
+      end
     end
 
     options.flatten.compact
   end
 
+  # kamal-proxy takes durations as Go duration strings; deploy.yml takes plain
+  # seconds. Zero is a real value (it disables the timeout), so only nil drops out.
+  def seconds_duration(value)
+    "#{value}s" if value
+  end
+
   # Flattens a one-to-many structure into an array of two-element arrays each containing a key-value pair
   def flatten_args(args)
     args.flat_map { |key, value| value.try(:map) { |entry| [ key, entry ] } || [ [ key, value ] ] }

data/lib/kamal/version.rb

@@ -1,3 +1,3 @@
 module Kamal
-  VERSION = "2.12.0"
+  VERSION = "3.0.0"
 end

data/lib/kamal.rb

@@ -8,6 +8,17 @@ require "yaml"
 require "tmpdir"
 require "pathname"
 require "uri"
+# Proxy::Run.digest reaches for Digest::SHA256 from inside `on(KAMAL.proxy_hosts)`,
+# so the first reference happens in several SSHKit threads at once. Digest defines
+# SHA256 lazily — `Digest.const_missing(:SHA256)` runs `require "digest/sha2"`, and
+# that path is not mutex-guarded — so the threads race it and one loses with
+# "Digest::Base cannot be directly inherited in Ruby", failing `kamal proxy boot`
+# on a random host.
+#
+# Requiring "digest" alone does NOT fix this: it defines the module but leaves
+# SHA256 to const_missing. Pull in the implementation itself, before any threads
+# exist to race it.
+require "digest/sha2"
 
 loader = Zeitwerk::Loader.for_gem
 loader.ignore(File.join(__dir__, "kamal", "sshkit_with_ext.rb"))

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dash
 version: !ruby/object:Gem::Version
-  version: 2.12.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -236,17 +236,27 @@ files:
 - lib/kamal/cli/app/assets.rb
 - lib/kamal/cli/app/boot.rb
 - lib/kamal/cli/app/error_pages.rb
+- lib/kamal/cli/app/rollout_boot.rb
 - lib/kamal/cli/app/ssl_certificates.rb
 - lib/kamal/cli/base.rb
 - lib/kamal/cli/build.rb
 - lib/kamal/cli/build/clone.rb
 - lib/kamal/cli/build/port_forwarding.rb
+- lib/kamal/cli/doctor.rb
+- lib/kamal/cli/doctor/config_checks.rb
+- lib/kamal/cli/doctor/endpoint_checks.rb
+- lib/kamal/cli/doctor/host_checks.rb
 - lib/kamal/cli/healthcheck/barrier.rb
+- lib/kamal/cli/healthcheck/drift_error.rb
 - lib/kamal/cli/healthcheck/error.rb
 - lib/kamal/cli/healthcheck/poller.rb
 - lib/kamal/cli/lock.rb
 - lib/kamal/cli/main.rb
 - lib/kamal/cli/proxy.rb
+- lib/kamal/cli/proxy/drift.rb
+- lib/kamal/cli/proxy/loadbalancer_claim.rb
+- lib/kamal/cli/proxy/loadbalancer_reboot.rb
+- lib/kamal/cli/proxy/reboot.rb
 - lib/kamal/cli/prune.rb
 - lib/kamal/cli/registry.rb
 - lib/kamal/cli/secrets.rb
@@ -254,12 +264,16 @@ files:
 - lib/kamal/cli/templates/deploy.yml
 - lib/kamal/cli/templates/sample_hooks/docker-setup.sample
 - lib/kamal/cli/templates/sample_hooks/post-app-boot.sample
+- lib/kamal/cli/templates/sample_hooks/post-app-stop.sample
 - lib/kamal/cli/templates/sample_hooks/post-deploy.sample
+- lib/kamal/cli/templates/sample_hooks/post-proxy-deploy.sample
 - lib/kamal/cli/templates/sample_hooks/post-proxy-reboot.sample
 - lib/kamal/cli/templates/sample_hooks/pre-app-boot.sample
+- lib/kamal/cli/templates/sample_hooks/pre-app-stop.sample
 - lib/kamal/cli/templates/sample_hooks/pre-build.sample
 - lib/kamal/cli/templates/sample_hooks/pre-connect.sample
 - lib/kamal/cli/templates/sample_hooks/pre-deploy.sample
+- lib/kamal/cli/templates/sample_hooks/pre-proxy-deploy.sample
 - lib/kamal/cli/templates/sample_hooks/pre-proxy-reboot.sample
 - lib/kamal/cli/templates/secrets
 - lib/kamal/commander.rb
@@ -318,10 +332,12 @@ files:
 - lib/kamal/configuration/logging.rb
 - lib/kamal/configuration/output.rb
 - lib/kamal/configuration/proxy.rb
+- lib/kamal/configuration/proxy/acme.rb
 - lib/kamal/configuration/proxy/boot.rb
 - lib/kamal/configuration/proxy/run.rb
 - lib/kamal/configuration/registry.rb
 - lib/kamal/configuration/role.rb
+- lib/kamal/configuration/role/healthcheck.rb
 - lib/kamal/configuration/servers.rb
 - lib/kamal/configuration/ssh.rb
 - lib/kamal/configuration/sshkit.rb
@@ -375,7 +391,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="