dash 2.12.0 → 3.0.1

data/lib/kamal/configuration/proxy.rb

@@ -4,15 +4,178 @@ class Kamal::Configuration::Proxy
   DEFAULT_LOG_REQUEST_HEADERS = [ "Cache-Control", "Last-Modified", "User-Agent" ]
   CONTAINER_NAME = "kamal-proxy"
   LOADBALANCER_CONTAINER_NAME = "kamal-loadbalancer"
+  CLIENT_CA_FILENAME = "client-ca.pem"
 
-  delegate :argumentize, :optionize, to: Kamal::Utils
+  # What `compress: true` offers. kamal-proxy has no "on" state without an
+  # explicit list - --compress *is* the list - so the shorthand has to pick.
+  # Best ratio first, matching the proxy's own default ordering; the client's
+  # Accept-Encoding q-values still outrank this preference.
+  DEFAULT_COMPRESSION_ENCODINGS = %w[ zstd br gzip ].freeze
+
+  SUPPORTED_COMPRESSION_ENCODINGS = %w[ gzip br zstd ].freeze
+
+  # kamal-proxy maps `brotli` onto the `br` token that travels in Content-Encoding.
+  COMPRESSION_ENCODING_ALIASES = { "brotli" => "br" }.freeze
+
+  # The layering contract. When the fork's load balancer fronts the per-host
+  # proxies, every deploy option lives at exactly one layer — or at both, on
+  # purpose. Nothing is allowed to be undecided: #deploy_options refuses to
+  # emit a key that has no disposition here, and test/proxy_layering_test.rb
+  # fails the build if a new option is added without one.
+  #
+  #   :edge    — only where clients connect. Stripped from the per-app deploy,
+  #              applied by the load balancer.
+  #   :per_app — only next to the app. Applied per-app, stripped from the
+  #              load balancer.
+  #   :both    — each layer genuinely has its own copy of the concern.
+  #
+  # Without load balancing the single proxy is every layer at once and the
+  # whole surface applies to it.
+  DEPLOY_OPTION_DISPOSITIONS = {
+    # --- Edge: TLS terminates where the handshake happens, and kamal-proxy
+    # gates TLSRedirect on TLSEnabled, so the whole family travels together.
+    host: :edge,
+    tls: :edge,
+    "tls-staging": :edge,
+    "tls-certificate-path": :edge,
+    "tls-private-key-path": :edge,
+    "tls-redirect": :edge,
+    "tls-domains-source": :edge,
+    "tls-domains-interval": :edge,
+    "tls-domains-batch-size": :edge,
+    "tls-on-demand-url": :edge,
+    "tls-client-ca-path": :edge,
+
+    # --- Edge: the load balancer is the only proxy that ever sees the real
+    # client address — an allow list on a per-app proxy would refuse every
+    # request (its peer is the LB) and one limiter would count the whole
+    # fleet as a single client.
+    "allow-ip": :edge,
+    "trusted-proxy": :edge,
+    "client-ip-header": :edge,
+    "rate-limit": :edge,
+    "rate-limit-burst": :edge,
+    "rate-limit-exempt": :edge,
+
+    # --- Edge: kamal-proxy deletes the Authorization header once a service
+    # enforces basic auth, so an inner proxy would 401 the credential-less
+    # request the load balancer forwards. Credentials belong at the edge only.
+    "basic-auth": :edge,
+
+    # --- Edge: both layers used to pin with the same cookie name but separate
+    # HMAC keys, so the inner proxy clobbered the edge pin every other request.
+    # Only the edge pin can stick.
+    "session-affinity": :edge,
+    "session-affinity-cookie": :edge,
+
+    # --- Edge: redirectURLIfNeeded consults r.TLS only, so behind the LB a
+    # per-app redirect emits http:// Locations to HTTPS clients.
+    "canonical-host": :edge,
+    redirect: :edge,
+
+    # --- Edge: one response cache, at the edge — two layers of cache would
+    # double the storage and let the inner cache serve entries the edge
+    # already invalidated. The store it writes into is proxy-wide (proxy/run).
+    cache: :edge,
+    "cache-max-ttl": :edge,
+    "cache-max-body": :edge,
+    "cache-max-variants": :edge,
+    "cache-vary-header": :edge,
+    "cache-vary-cookie": :edge,
+    "cache-allow-set-cookie": :edge,
+
+    # --- Edge: splitting reads from writes is a fleet-level routing decision;
+    # per-app proxies each front a single host and have nothing to split.
+    "read-target": :edge,
+    "read-target-websockets": :edge,
+    "writer-affinity-timeout": :edge,
+
+    # --- Per-app: applied next to the app, exactly once. The LB forwards to
+    # the per-host proxies, so running these at both layers would add a header
+    # twice or run a rewrite over its own output.
+    "set-request-header": :per_app,
+    "add-request-header": :per_app,
+    "remove-request-header": :per_app,
+    "set-response-header": :per_app,
+    "add-response-header": :per_app,
+    "remove-response-header": :per_app,
+    rewrite: :per_app,
+    "intercept-errors": :per_app,
+
+    # --- Per-app: sleep stops and starts app containers through the docker
+    # socket — the LB has neither the socket nor the containers, and its
+    # targets are host addresses, so a sleep flag there fails the deploy.
+    "sleep-after": :per_app,
+    "wake-timeout": :per_app,
+    "sleep-container": :per_app,
+
+    # --- Per-app: compress once, next to the app. Double-running was only
+    # safe by accident of the Content-Encoding guard.
+    compress: :per_app,
+    "compress-content-type": :per_app,
+    "compress-min-length": :per_app,
+
+    # --- Both, deliberately: each layer has a real connection pool to its own
+    # targets (LB -> per-host proxies, per-host proxy -> app containers), so
+    # pool tuning and request deadlines apply to each hop.
+    "target-timeout": :both,
+    "target-max-conns": :both,
+    "target-max-idle-conns": :both,
+    "target-idle-conn-timeout": :both,
+    "target-dial-timeout": :both,
+    "target-disable-keep-alives": :both,
+    "target-try-duration": :both,
+    "target-try-interval": :both,
+    "path-timeout": :both,
+    "request-timeout": :both,
+    "path-request-timeout": :both,
+    "deploy-timeout": :both,
+    "drain-timeout": :both,
+
+    # --- Both: each layer health-checks its own targets, buffers its own
+    # connections, routes its own paths and writes its own logs.
+    "health-check-interval": :both,
+    "health-check-timeout": :both,
+    "health-check-path": :both,
+    "health-check-port": :both,
+    "health-check-host": :both,
+    "buffer-requests": :both,
+    "buffer-responses": :both,
+    "buffer-memory": :both,
+    "max-request-body": :both,
+    "max-response-body": :both,
+    "path-prefix": :both,
+    "strip-path-prefix": :both,
+    "forward-headers": :both,
+    "log-request-header": :both,
+    "log-response-header": :both,
+    "error-pages": :both,
+    "exclude-metrics-path": :both
+  }.freeze
+
+  # Refusing beats guessing: a deploy option nobody placed would silently land
+  # on both layers, which is how session affinity broke in the only topology
+  # where it matters.
+  def self.disposition(key)
+    DEPLOY_OPTION_DISPOSITIONS.fetch(key) do
+      raise Kamal::ConfigurationError,
+        "proxy deploy option --#{key} has no layering disposition - add it to Kamal::Configuration::Proxy::DEPLOY_OPTION_DISPOSITIONS"
+    end
+  end
+
+  delegate :argumentize, :optionize, :seconds_duration, to: Kamal::Utils
 
   attr_reader :config, :proxy_config, :role_name, :run, :secrets
-  def initialize(config:, proxy_config:, role_name: nil, secrets:, context: "proxy")
+
+  # `load_balanced: false` marks a registration the fork's load balancer can
+  # never front - accessories, whose targets it does not collect. Such a proxy
+  # keeps its own host/TLS/basic-auth instead of deferring them to the edge.
+  def initialize(config:, proxy_config:, role_name: nil, secrets:, context: "proxy", load_balanced: true)
     @config = config
     @proxy_config = proxy_config
     @proxy_config = {} if @proxy_config.nil?
     @role_name = role_name
+    @load_balanced = load_balanced
     @secrets = secrets
     validate! @proxy_config, with: Kamal::Configuration::Validator::Proxy, context: context
     @run = Kamal::Configuration::Proxy::Run.new(config, run_config: @proxy_config["run"], context: "#{context}/run") if @proxy_config && @proxy_config["run"].present?
@@ -34,14 +197,25 @@ class Kamal::Configuration::Proxy
     proxy_config["loadbalancer"]
   end
 
+  # Root-level `proxy` setting only; ignored inside role-specific proxy blocks.
+  def reboot_on_deploy?
+    proxy_config.fetch("reboot_on_deploy", true)
+  end
+
   def load_balancing?
     effective_loadbalancer.present?
   end
 
+  def load_balanced?
+    @load_balanced
+  end
+
   def effective_loadbalancer
+    return nil unless load_balanced?
     return false if loadbalancer == false
+    return primary_role_first_host if loadbalancer == true
     return loadbalancer if loadbalancer.present?
-    return config.primary_role.hosts.first if config.primary_role && Array(config.primary_role.hosts).size > 1
+    return primary_role_first_host if auto_load_balanced_primary_role?
 
     nil
   end
@@ -84,22 +258,87 @@ class Kamal::Configuration::Proxy
     tls_path(config.proxy_boot.tls_container_directory, "key.pem") if custom_ssl_certificate?
   end
 
+  # Everything TLS lives in the one `ssl` hash - certificate material,
+  # on-demand issuance and the mTLS client CA. One naming family instead of a
+  # separate `tls:` block.
+  def ssl_config
+    proxy_config["ssl"].is_a?(Hash) ? proxy_config["ssl"] : {}
+  end
+
+  def on_demand_url
+    ssl_config["on_demand_url"]
+  end
+
+  # The name of a secret in .kamal/secrets holding the CA bundle client
+  # certificates must chain to - mirroring ssl.certificate_pem, not a local
+  # file path. Kamal uploads the content into the app's TLS directory, which
+  # the proxy container already mounts, and hands the proxy the path it sees
+  # there.
+  def client_ca_pem
+    ssl_config["client_ca_pem"]
+  end
+
+  def client_ca?
+    client_ca_pem.present?
+  end
+
+  # Resolved at upload time, not config time, so `kamal app logs` and friends
+  # work on machines without the secret. A blank secret raises like
+  # basic_auth.password_secret - silently deploying without the client CA
+  # would turn mTLS off.
+  def client_ca_pem_content
+    secrets[client_ca_pem].tap do |content|
+      if content.blank?
+        raise Kamal::ConfigurationError, "proxy/ssl: client_ca_pem secret '#{client_ca_pem}' is empty"
+      end
+    end
+  end
+
+  def host_client_ca
+    tls_file_path(config.proxy_boot.tls_directory, CLIENT_CA_FILENAME) if client_ca?
+  end
+
+  def container_client_ca
+    tls_file_path(config.proxy_boot.tls_container_directory, CLIENT_CA_FILENAME) if client_ca?
+  end
+
   def path_prefixes
     proxy_config["path_prefixes"] || proxy_config["path_prefix"]&.split(",") || []
   end
 
+  # Nil when unset: the default lives in kamal-proxy, not here.
+  def healthcheck_path
+    proxy_config.dig("healthcheck", "path")
+  end
+
   def deploy_options
-    opts = {
+    all_deploy_options.select { |key, _| retained_dispositions.include?(self.class.disposition(key)) }
+  end
+
+  # The full option surface before the layering contract is applied — what a
+  # single proxy (no load balancer) deploys with. Public so the layering canary
+  # can enumerate every key the gem emits.
+  def all_deploy_options
+    {
       host: hosts,
       tls: ssl? ? true : nil,
+      "tls-staging": proxy_config["ssl_staging"] ? true : nil,
       "tls-certificate-path": container_tls_cert,
       "tls-private-key-path": container_tls_key,
       "deploy-timeout": seconds_duration(config.deploy_timeout),
       "drain-timeout": seconds_duration(config.drain_timeout),
       "health-check-interval": seconds_duration(proxy_config.dig("healthcheck", "interval")),
       "health-check-timeout": seconds_duration(proxy_config.dig("healthcheck", "timeout")),
-      "health-check-path": proxy_config.dig("healthcheck", "path"),
+      "health-check-path": healthcheck_path,
+      "health-check-port": proxy_config.dig("healthcheck", "port"),
+      "health-check-host": proxy_config.dig("healthcheck", "host"),
       "target-timeout": seconds_duration(proxy_config["response_timeout"]),
+      "read-target": proxy_config.dig("read_routing", "targets").presence,
+      "read-target-websockets": proxy_config.dig("read_routing", "websockets") ? true : nil,
+      "writer-affinity-timeout": seconds_duration(proxy_config.dig("read_routing", "writer_affinity_timeout")),
+      "path-timeout": path_timeout_args("path_response_timeouts"),
+      "request-timeout": seconds_duration(proxy_config["request_timeout"]),
+      "path-request-timeout": path_timeout_args("path_request_timeouts"),
       "buffer-requests": proxy_config.fetch("buffering", { "requests": true }).fetch("requests", true),
       "buffer-responses": proxy_config.fetch("buffering", { "responses": true }).fetch("responses", true),
       "buffer-memory": proxy_config.dig("buffering", "memory"),
@@ -109,23 +348,40 @@ class Kamal::Configuration::Proxy
       "strip-path-prefix": proxy_config.dig("strip_path_prefix"),
       "forward-headers": proxy_config.dig("forward_headers"),
       "tls-redirect": proxy_config.dig("ssl_redirect"),
+      "basic-auth": basic_auth_credential,
       "log-request-header": proxy_config.dig("logging", "request_headers") || DEFAULT_LOG_REQUEST_HEADERS,
       "log-response-header": proxy_config.dig("logging", "response_headers"),
-      "error-pages": error_pages
-    }.compact
-
-    if load_balancing?
-      opts.delete(:host)
-      opts.delete(:tls)
-    end
-
-    opts
+      "error-pages": error_pages,
+      # A deploy flag despite reading like metrics configuration: where the
+      # metrics are served and who may read them are proxy-wide and live under
+      # proxy/run, but which of *this service's* paths are counted is per service.
+      "exclude-metrics-path": proxy_config["exclude_metrics_paths"].presence
+    }.merge(ssl_domains_options).merge(tls_options).merge(cache_options).merge(compress_options)
+      .merge(access_control_options).merge(traffic_options).merge(lifecycle_options)
+      .merge(target_options).compact
   end
 
   def deploy_command_args(target:)
     optionize ({ target: "#{target}:#{app_port}" }).merge(deploy_options), with: "="
   end
 
+  # kamal-proxy rollout deploy only accepts the target and the timeouts - the service already
+  # exists, so it keeps the host, TLS, buffering and logging options of the live deploy.
+  def rollout_deploy_options
+    {
+      "deploy-timeout": seconds_duration(config.deploy_timeout),
+      "drain-timeout": seconds_duration(config.drain_timeout)
+    }.compact
+  end
+
+  def rollout_deploy_command_args(target:)
+    optionize ({ target: "#{target}:#{app_port}" }).merge(rollout_deploy_options), with: "="
+  end
+
+  def rollout_set_command_args(percent: nil, list: nil)
+    optionize({ percent: percent, list: list }.compact, with: "=")
+  end
+
   def stop_options(drain_timeout: nil, message: nil)
     {
       "drain-timeout": seconds_duration(drain_timeout),
@@ -138,16 +394,237 @@ class Kamal::Configuration::Proxy
   end
 
   def merge(other)
-    self.class.new config: config, proxy_config: other.proxy_config.deep_merge(proxy_config), role_name: role_name, secrets: secrets
+    self.class.new config: config, proxy_config: other.proxy_config.deep_merge(proxy_config), role_name: role_name, secrets: secrets, load_balanced: load_balanced?
   end
 
   private
+    # Which dispositions this layer keeps. The per-app proxy behind a load
+    # balancer sheds the edge concerns; without load balancing there is no
+    # other layer to defer to. Kamal::Configuration::Loadbalancer overrides
+    # this to keep the edge and shed the per-app concerns.
+    def retained_dispositions
+      load_balancing? ? %i[ per_app both ] : %i[ edge per_app both ]
+    end
+
+    def primary_role_first_host
+      config.primary_role&.hosts&.first
+    end
+
+    # Auto-activation needs a role the load balancer can actually front. The
+    # target list is built from roles where `running_proxy?` (see
+    # Kamal::Cli::Proxy#loadbalancer), so a proxy-less primary role would boot a
+    # load balancer with an empty --target. An explicit `loadbalancer:` setting
+    # skips this check — the operator asked for it.
+    def auto_load_balanced_primary_role?
+      primary_role = config.primary_role
+
+      primary_role.present? && primary_role.running_proxy? && Array(primary_role.hosts).size > 1
+    end
+
+    # Flags for kamal-proxy's dynamic domain source (runtime TLS hostnames).
+    # TLS terminates wherever these flags land — :edge in the layering contract.
+    def ssl_domains_options
+      {
+        "tls-domains-source": proxy_config.dig("ssl_domains", "source"),
+        "tls-domains-interval": seconds_duration(proxy_config.dig("ssl_domains", "interval")),
+        "tls-domains-batch-size": proxy_config.dig("ssl_domains", "batch_size")
+      }.compact
+    end
+
+    # On-demand issuance and the mTLS client CA only matter where the
+    # handshake happens (:edge) - an ask endpoint or a client CA on a proxy
+    # that never terminates TLS would do nothing at all.
+    def tls_options
+      {
+        "tls-on-demand-url": on_demand_url,
+        "tls-client-ca-path": container_client_ca
+      }.compact
+    end
+
+    # The connection pool between the proxy and this app's containers, and how
+    # hard the proxy tries to place a request on a healthy one.
+    #
+    # Every value is passed through exactly as written. kamal-proxy resolves its
+    # own defaults from a zero (target_pool.go), and it has to do that server
+    # side because restored state and older RPC clients never see the CLI — so
+    # substituting a default here would be both redundant and wrong.
+    def target_options
+      target = proxy_config["target"] || {}
+
+      {
+        "target-max-conns": target["max_conns"],
+        "target-max-idle-conns": target["max_idle_conns"],
+        "target-idle-conn-timeout": seconds_duration(target["idle_conn_timeout"]),
+        "target-dial-timeout": seconds_duration(target["dial_timeout"]),
+        "target-disable-keep-alives": target["disable_keep_alives"] ? true : nil,
+        "target-try-duration": seconds_duration(target["try_duration"]),
+        "target-try-interval": seconds_duration(target["try_interval"])
+      }.compact
+    end
+
+    # Session affinity and scale-to-zero: which target a client keeps, and
+    # whether the targets are running at all. Not one layer: affinity is :edge
+    # (an inner pin would clobber the edge pin), sleep is :per_app (only the
+    # app hosts have the docker socket and the containers).
+    #
+    # Sleep needs the container runtime socket, which is a run-level setting -
+    # Kamal::Configuration#ensure_sleep_has_a_docker_socket refuses the pairing
+    # rather than letting the first request after an idle period hang.
+    def lifecycle_options
+      affinity = proxy_config["session_affinity"] || {}
+      sleep_config = proxy_config["sleep"] || {}
+      affinity_enabled = affinity["enabled"] ? true : nil
+
+      {
+        "session-affinity": affinity_enabled,
+        "session-affinity-cookie": (affinity["cookie"] if affinity_enabled),
+        "sleep-after": seconds_duration(sleep_config["after"]),
+        "wake-timeout": seconds_duration(sleep_config["wake_timeout"]),
+        "sleep-container": sleep_config["containers"].presence
+      }.compact
+    end
+
+    # Header rewriting, redirects, rewrites and error interception. Not one
+    # layer: headers/rewrites/error interception are :per_app (the LB would
+    # append an `add` header twice and run a rewrite over its own output),
+    # while canonical-host and redirect are :edge (they consult r.TLS, so
+    # behind the LB they would emit http:// Locations to HTTPS clients).
+    def traffic_options
+      {
+        "set-request-header": header_rules("request", "set"),
+        "add-request-header": header_rules("request", "add"),
+        "remove-request-header": headers_config.dig("request", "remove").presence,
+        "set-response-header": header_rules("response", "set"),
+        "add-response-header": header_rules("response", "add"),
+        "remove-response-header": headers_config.dig("response", "remove").presence,
+        redirect: path_rules("redirects"),
+        rewrite: path_rules("rewrites"),
+        "canonical-host": proxy_config["canonical_host"],
+        "intercept-errors": proxy_config["intercept_errors"].presence
+      }.compact
+    end
+
+    def headers_config
+      proxy_config["headers"] || {}
+    end
+
+    # kamal-proxy cuts a rule at the first colon, so a value carrying colons of
+    # its own arrives intact.
+    def header_rules(direction, verb)
+      (headers_config.dig(direction, verb) || {}).map { |name, value| "#{name}: #{value}" }.presence
+    end
+
+    # '<pattern>=<replacement>', with ';status=<code>' appended for a redirect
+    # that asks for one. Cut at the first '=' on the proxy side.
+    def path_rules(key)
+      Array(proxy_config[key]).map do |rule|
+        "#{rule["from"]}=#{rule["to"]}#{";status=#{rule["status"]}" if rule["status"]}"
+      end.presence
+    end
+
+    # Rate limiting, the IP allow list, and the client-IP identification both of
+    # them key on. :edge - the per-host proxy's peer is the load balancer, so an
+    # allow list there would refuse every request and one limiter would count
+    # the whole fleet as a single client.
+    def access_control_options
+      client_ip = proxy_config["client_ip"] || {}
+      rate_limit = proxy_config["rate_limit"] || {}
+
+      {
+        "allow-ip": proxy_config["allow_ips"].presence,
+        "trusted-proxy": client_ip["trusted_proxies"].presence,
+        "client-ip-header": client_ip["header"],
+        "rate-limit": rate_limit["requests"],
+        "rate-limit-burst": rate_limit["burst"],
+        "rate-limit-exempt": rate_limit["exempt"].presence
+      }.compact
+    end
+
+    # `compress: true` and the block form both land here. --compress is a list of
+    # encodings rather than a switch, so "on" always means naming them: a bare
+    # --compress would take the next flag on the command line as its value.
+    #
+    # An explicit `enabled: false` wins over encodings implying "on" - it is
+    # the off switch for a block whose tuning the operator wants to keep.
+    def compress_options
+      compress = proxy_config["compress"]
+      settings = compress.is_a?(Hash) ? compress : {}
+      return {} if settings["enabled"] == false
+      return {} unless compress == true || settings["enabled"] || settings["encodings"].present?
+
+      {
+        compress: settings["encodings"].presence || DEFAULT_COMPRESSION_ENCODINGS,
+        "compress-content-type": settings["content_types"].presence,
+        "compress-min-length": settings["min_length"]
+      }.compact
+    end
+
+    # The cache policy, which is per service - the store it writes into is
+    # proxy-wide and lives in proxy/run/cache. Only --cache is derived from a
+    # truthy key; every other default stays in kamal-proxy, so an unset key emits
+    # nothing rather than restating a default the gem would then have to track.
+    def cache_options
+      cache = proxy_config["cache"] || {}
+
+      {
+        cache: cache["enabled"] ? true : nil,
+        "cache-max-ttl": seconds_duration(cache["max_ttl"]),
+        "cache-max-body": cache["max_body"],
+        "cache-max-variants": cache["max_variants"],
+        "cache-vary-header": cache["vary_headers"].presence,
+        "cache-vary-cookie": cache["vary_cookies"].presence,
+        "cache-allow-set-cookie": cache["allow_set_cookie"] ? true : nil
+      }.compact
+    end
+
     def tls_path(directory, filename)
-      File.join([ directory, role_name, filename ].compact) if custom_ssl_certificate?
+      tls_file_path(directory, filename) if custom_ssl_certificate?
+    end
+
+    # The path construction on its own: a client CA bundle lives beside the
+    # server certificate but has nothing to do with whether one was configured.
+    def tls_file_path(directory, filename)
+      File.join([ directory, role_name, filename ].compact)
+    end
+
+    # kamal-proxy takes the credential as <username>:<password> and cuts at the
+    # first colon, so a password may contain colons but a username may not (the
+    # validator enforces that). The password is read from .kamal/secrets when
+    # password_secret names it, so it need not live in deploy.yml.
+    def basic_auth_credential
+      basic_auth = proxy_config["basic_auth"]
+      return nil unless basic_auth.is_a?(Hash)
+
+      password =
+        if (secret_name = basic_auth["password_secret"]).present?
+          secrets[secret_name]
+        else
+          basic_auth["password"]
+        end
+
+      # The validator guarantees a password was configured, so a blank one here
+      # means the named secret resolved empty. Fail rather than drop the flag —
+      # silently deploying an unprotected service is the worse outcome.
+      if password.blank?
+        raise Kamal::ConfigurationError, "proxy/basic_auth: password_secret '#{secret_name}' is empty"
+      end
+
+      # Sensitive, so SSHKit redacts the credential wherever kamal prints the
+      # deploy command - at :info verbosity it used to land in plain text
+      # (registry-login precedent; Utils.optionize passes the marking through).
+      Kamal::Utils.sensitive("#{basic_auth["username"]}:#{password}")
     end
 
-    def seconds_duration(value)
-      value ? "#{value}s" : nil
+    # Serves both --path-timeout and --path-request-timeout, which kamal-proxy
+    # reads with one parser. A duration may be a Go string ("5m") or plain
+    # seconds; 0 is a value, meaning no limit for that prefix.
+    def path_timeout_args(key)
+      if (timeouts = proxy_config[key]).present?
+        timeouts.map do |prefix, duration|
+          duration = seconds_duration(duration) if duration.is_a?(Numeric)
+          "#{prefix}=#{duration}"
+        end
+      end
     end
 
     def error_pages

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

@@ -0,0 +1,95 @@
+class Kamal::Configuration::Role::Healthcheck
+  DEFAULT_PATH = "/up"
+  DEFAULT_INTERVAL = 1
+
+  # Everything that only ever reaches docker as a `--health-*` flag. An exec probe emits
+  # none of those, so combining them would silently drop whatever the operator wrote.
+  DOCKER_ONLY_KEYS = %w[ cmd port path interval timeout retries start_period start_interval ]
+
+  attr_reader :healthcheck_config, :context
+  delegate :optionize, to: Kamal::Utils
+
+  def initialize(healthcheck_config:, context: "healthcheck")
+    @healthcheck_config = healthcheck_config
+    @context = context
+    validate!
+  end
+
+  # The command docker runs inside the container. Custom commands win; otherwise
+  # we build the same curl check Kamal 1 shipped.
+  def cmd
+    healthcheck_config["cmd"] || http_health_check
+  end
+
+  # The probe kamal `docker exec`s from the deploy host during a boot, for images whose
+  # HEALTHCHECK cannot be changed. Deploy-time only: docker never runs it, so `docker ps`
+  # shows no `(healthy)` and `docker inspect` keeps no probe history.
+  def exec
+    healthcheck_config["exec"]
+  end
+
+  def exec?
+    exec.present?
+  end
+
+  def port
+    healthcheck_config["port"]
+  end
+
+  def path
+    healthcheck_config.fetch("path", DEFAULT_PATH)
+  end
+
+  def interval
+    healthcheck_config.fetch("interval", DEFAULT_INTERVAL)
+  end
+
+  def args
+    return [] if exec?
+
+    optionize({
+        "health-cmd" => cmd,
+        "health-interval" => duration(interval),
+        "health-timeout" => duration(healthcheck_config["timeout"]),
+        "health-retries" => healthcheck_config["retries"],
+        "health-start-period" => duration(healthcheck_config["start_period"]),
+        "health-start-interval" => duration(healthcheck_config["start_interval"])
+      }.compact)
+  end
+
+  private
+    def http_health_check
+      "curl -f #{URI.join("http://localhost:#{port}", path)} || exit 1"
+    end
+
+    # Bare numbers are seconds, anything else is passed to docker as written.
+    def duration(value)
+      case value
+      when nil then nil
+      when /\A\d+\z/, Integer then "#{value}s"
+      else value.to_s
+      end
+    end
+
+    def validate!
+      if exec? && (conflicting = DOCKER_ONLY_KEYS.find { |key| healthcheck_config[key].present? })
+        error "cannot be combined with #{conflicting}, which only configures docker's own healthcheck " \
+          "— an exec probe is polled from the deploy host", context: "exec"
+      end
+
+      if healthcheck_config["cmd"].blank? && !exec? && port.blank?
+        error "port is required unless cmd or exec is set"
+      end
+
+      # Utils#escape_shell_value leaves ${...} alone, so it would expand in the
+      # deploy host's shell when docker run is assembled. `exec` has no such problem:
+      # Commands::App#health_probe single-quotes it, so it expands in the container.
+      if healthcheck_config["cmd"].to_s.include?("${")
+        error "cannot contain ${...}, it would expand on the deploy host, not in the container", context: "cmd"
+      end
+    end
+
+    def error(message, context: nil)
+      raise Kamal::ConfigurationError, "#{[ @context, context ].compact.join("/")}: #{message}"
+    end
+end