dash 4.0.8 → 4.1.1

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

@@ -0,0 +1,39 @@
+# Deploy report
+#
+# Every deploy, redeploy, setup, rollback and standalone build prints a report: a table of
+# where the time went, the build steps underneath it, and advice about the Dockerfile and
+# the build context. The `report` key controls the advice half of that; the table always
+# prints.
+
+# Report options
+#
+# The options are specified under the report key in the configuration file.
+report:
+
+  # Advice
+  #
+  # Print the Advice block under the table. The measurements themselves are always
+  # collected — this only decides whether dash says anything about them.
+  advice: true
+
+  # hadolint
+  #
+  # Supplement dash's own rules with hadolint's when it is installed.
+  #
+  # `auto` runs it when `hadolint` is on PATH and stays silent when it is not; `false`
+  # never runs it. Any other value is a configuration error rather than a silent off.
+  # hadolint's exit status never affects the deploy, and its rule codes (DL3008 and
+  # friends) can be silenced through `ignore` like any other rule.
+  hadolint: auto
+
+  # History
+  #
+  # How many JSON reports to keep per destination under .dash/reports. Set to 0 to write
+  # none.
+  history: 20
+
+  # Ignore
+  #
+  # Rule ids to silence. The id is the string printed with each piece of advice.
+  ignore:
+    - root-user

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

@@ -107,22 +107,22 @@ servers:
     # A `healthcheck` cannot be combined with `health-*` keys under `options`.
     #
     # `exec` is the escape hatch for an image whose HEALTHCHECK you cannot change,
-    # or for an emergency override without a rebuild. Kamal `docker exec`s it from
-    # the deploy host on every poll and gates the deploy on the exit code — no HTTP
+    # or for an emergency override without a rebuild. Dash `docker exec`s it on the
+    # deploy host once a second and gates the deploy on the exit code — no HTTP
     # server and no published port needed, and unlike `cmd` it may use `${...}`,
     # which is quoted through to the container. It is strictly worse than `cmd` in
     # the general case, so reach for it only when `cmd` is not available:
     #
     #   - deploy-time only. Docker never runs it, so `docker ps` never shows
     #     `(healthy)` and `docker inspect` keeps no probe history.
-    #   - each poll costs an SSH round trip plus a process spawn (~100-300ms), which
-    #     rules out sub-second polling.
+    #   - each attempt costs a process spawn on the host (the whole wait is one SSH
+    #     round trip, so the cost does not grow with how long the boot takes).
     #   - nothing outside a deploy ever runs it.
     #
     # `exec` replaces docker's healthcheck rather than configuring it, so it cannot
-    # be combined with `cmd`, `port`, `path`, or any of the duration keys. Polling
-    # follows the deploy's own backoff and gives up at `deploy_timeout`; a probe that
-    # never exits zero fails the boot and leaves the old container running.
+    # be combined with `cmd`, `port`, `path`, or any of the duration keys. The wait
+    # gives up at `deploy_timeout`; a probe that never exits zero fails the boot and
+    # leaves the old container running.
     #
     # A non-proxied role with neither a `healthcheck` nor a `health-cmd` option
     # warns on every deploy, because the readiness delay is the only thing standing

data/lib/dash/configuration/proxy.rb

@@ -23,6 +23,9 @@ class Dash::Configuration::Proxy
   LEGACY_LOADBALANCER_CONTAINER_NAME = "kamal-loadbalancer"
   LEGACY_HOLDER_CONTAINER_NAME = "kamal-proxy-net"
   LEGACY_NETWORK = "kamal"
+  # Written into the run directory once a host is verifiably past the 3c rename, so the
+  # bridge costs it nothing but a `test -f` on every deploy after. Deleted in stage 3d.
+  LEGACY_RENAME_MARKER = ".legacy-renamed"
   LEGACY_CONFIG_VOLUME = "kamal-proxy-config"
   LEGACY_LOADBALANCER_CONFIG_VOLUME = "kamal-loadbalancer-config"
   LEGACY_IMAGE_TITLE = "kamal-proxy"

data/lib/dash/configuration/report.rb

@@ -0,0 +1,65 @@
+# The `report:` block: how much of the deploy report to print, and how much of it to keep.
+#
+# Every key is optional and the defaults are what an operator who has never heard of the
+# block gets — the table always prints, the advice under it prints, and hadolint joins in
+# only if they already have it installed.
+class Dash::Configuration::Report
+  include Dash::Configuration::Validation
+
+  DEFAULT_HISTORY = 20
+  HADOLINT_AUTO = "auto".freeze
+
+  attr_reader :report_config
+
+  HADOLINT_SETTINGS = [ HADOLINT_AUTO, true, false ].freeze
+
+  def initialize(config:)
+    @report_config = config.raw_config.report || {}
+    validate! @report_config unless @report_config.empty?
+    ensure_valid_hadolint_setting
+    ensure_valid_history
+  end
+
+  def advice?
+    report_config.fetch("advice", true)
+  end
+
+  def hadolint
+    report_config.fetch("hadolint", HADOLINT_AUTO)
+  end
+
+  # "auto" (or true) means run it when it is on PATH — the availability check itself
+  # lives in Dash::Dockerfile::Hadolint, because only it knows what running costs.
+  def hadolint?
+    hadolint != false
+  end
+
+  def history
+    report_config.fetch("history", DEFAULT_HISTORY).to_i
+  end
+
+  def ignore
+    Array(report_config["ignore"]).map(&:to_s)
+  end
+
+  def to_h
+    report_config
+  end
+
+  private
+    # A misspelling must not read as "off": the operator would lose findings and never
+    # learn why.
+    def ensure_valid_hadolint_setting
+      return if HADOLINT_SETTINGS.include?(hadolint)
+
+      raise Dash::ConfigurationError, "report/hadolint: must be auto or false, got #{hadolint.inspect}"
+    end
+
+    # Same reasoning: a negative count is a typo, and reading it as "keep none" would
+    # quietly stop saving the reports the operator was configuring.
+    def ensure_valid_history
+      return if history >= 0
+
+      raise Dash::ConfigurationError, "report/history: must be 0 or more, got #{report_config["history"].inspect}"
+    end
+end

data/lib/dash/configuration.rb

@@ -16,7 +16,7 @@ class Dash::Configuration
   delegate :argumentize, :optionize, to: Dash::Utils
 
   attr_reader :destination, :raw_config, :secrets
-  attr_reader :accessories, :aliases, :boot, :builder, :env, :logging, :output, :proxy, :proxy_boot, :servers, :ssh, :sshkit, :registry
+  attr_reader :accessories, :aliases, :boot, :builder, :env, :logging, :output, :proxy, :proxy_boot, :report, :servers, :ssh, :sshkit, :registry
 
   include Validation
 
@@ -76,6 +76,7 @@ class Dash::Configuration
 
     @logging = Logging.new(logging_config: @raw_config.logging)
     @output = Output.new(config: self)
+    @report = Report.new(config: self)
     @proxy = Proxy.new(config: self, proxy_config: @raw_config.proxy, secrets: secrets)
     @proxy_boot = Proxy::Boot.new(config: self)
     @ssh = Ssh.new(config: self)

data/lib/dash/dockerfile/analyzer.rb

@@ -0,0 +1,66 @@
+# Runs the rule set over a parsed Dockerfile and returns the advice.
+#
+# Rules that need measurements (`build:`) stay silent without them, so the same analyzer
+# serves `dash doctor` — static, no build, no SSH — and the block printed under a deploy,
+# where the numbers upgrade a static hint into "this cost you 84.1 seconds".
+class Dash::Dockerfile::Analyzer
+  RULES = [
+    Dash::Dockerfile::Rules::CopyBeforeInstall,
+    Dash::Dockerfile::Rules::ContextSize,
+    Dash::Dockerfile::Rules::MissingDockerignore,
+    Dash::Dockerfile::Rules::DockerignoreGaps,
+    Dash::Dockerfile::Rules::LatestBase,
+    Dash::Dockerfile::Rules::SecretInBuildArg,
+    Dash::Dockerfile::Rules::SingleStageBuildDeps,
+    Dash::Dockerfile::Rules::AptHygiene,
+    Dash::Dockerfile::Rules::CacheBustingArg,
+    Dash::Dockerfile::Rules::CacheExportCost,
+    Dash::Dockerfile::Rules::CurlPipeShell,
+    Dash::Dockerfile::Rules::InlineEnvBlob,
+    Dash::Dockerfile::Rules::NoCacheMount,
+    Dash::Dockerfile::Rules::UncachedInstall,
+    Dash::Dockerfile::Rules::RootUser
+  ].freeze
+
+  # Reads and parses the file. Missing is the caller's problem to report: `dash doctor`
+  # fails the check, a deploy stays quiet (a --skip-push deploy has no Dockerfile and no
+  # business complaining about it).
+  def self.for_file(path, **options)
+    new document: Dash::Dockerfile::Parser.parse(File.read(path)), path: path, file: path, **options
+  end
+
+  # `path` is what findings print (the operator's own `builder: dockerfile:`); `file` is
+  # where the file actually is, for the one rule that has to open it again.
+  def initialize(document:, context_dir: nil, build: nil, builder: nil, path: "Dockerfile", file: path, ignore: [], hadolint: false)
+    # A context that is not a local directory (a git URL, or a clone that has not been
+    # prepared yet) is not something the .dockerignore rules can say anything about.
+    directory = context_dir if context_dir && File.directory?(context_dir)
+
+    @context = Dash::Dockerfile::Context.new \
+      document: document, context_dir: directory, dockerignore: (Dash::Dockerfile::Dockerignore.in(directory) if directory),
+      build: build, builder: builder, path: path
+    @file = file
+    @ignore = Array(ignore).map(&:to_s)
+    @hadolint = hadolint
+  end
+
+  # Warnings first, then the informational findings, each group in rule order — an
+  # operator reading the block top down sees what is costing them before what is merely
+  # worth knowing.
+  def findings
+    (rule_findings + hadolint_findings)
+      .reject { |finding| @ignore.include?(finding.rule) }
+      .sort_by.with_index { |finding, index| [ finding.warn? ? 0 : 1, index ] }
+  end
+
+  private
+    def rule_findings
+      RULES.flat_map { |rule| rule.new(@context).findings }
+    end
+
+    def hadolint_findings
+      return [] unless @hadolint
+
+      Dash::Dockerfile::Hadolint.new(path: @context.path, file: @file).findings
+    end
+end

data/lib/dash/dockerfile/context.rb

@@ -0,0 +1,147 @@
+# Everything a rule is allowed to look at: the parsed Dockerfile, the build context on
+# disk, the builder's configuration, and — when the advice is printed next to a build
+# that actually ran — what that build measured.
+#
+# The shared predicates live here rather than in each rule so that "what counts as a
+# dependency install" has one answer, and so the measured half of a rule can find the
+# buildx vertex that corresponds to a Dockerfile line.
+class Dash::Dockerfile::Context
+  # The package managers whose install step is worth protecting from cache busting, and
+  # the cache directory each conventionally wants mounted.
+  DEPENDENCY_INSTALLS = [
+    [ /\bbundle\s+(?:_[\d._]+_\s+)?install\b/, "/usr/local/bundle/cache" ],
+    [ /\bnpm\s+(?:ci|install)\b/, "/root/.npm" ],
+    [ /\byarn\s+install\b/, "/usr/local/share/.cache/yarn" ],
+    [ /\bpnpm\s+install\b/, "/root/.local/share/pnpm/store" ],
+    [ /\bbun\s+install\b/, "/root/.bun/install/cache" ],
+    [ /\bpip3?\s+install\b/, "/root/.cache/pip" ],
+    [ /\bpoetry\s+install\b/, "/root/.cache/pypoetry" ],
+    [ /\bgo\s+mod\s+download\b/, "/go/pkg/mod" ],
+    [ /\bcargo\s+(?:build|fetch)\b/, "/usr/local/cargo/registry" ],
+    [ /\bcomposer\s+install\b/, "/root/.composer/cache" ],
+    [ /\bmix\s+deps\.get\b/, "/root/.hex" ],
+    [ /\bdotnet\s+restore\b/, "/root/.nuget/packages" ]
+  ].freeze
+
+  # apt takes its options before or after the verb (`apt-get -y install`,
+  # `apt-get -t bookworm-backports install`), so the verb is found past any of them. A
+  # shell separator is never an option or its value, so `apt-get -y && install` is not
+  # an apt install.
+  APT_OPTIONS = /(?:-[^\s;&|]+(?:\s+[^-\s;&|][^\s;&|]*)?\s+)*/
+  APT_INSTALL = [ /\bapt-get\s+#{APT_OPTIONS.source}install\b/, "/var/cache/apt" ].freeze
+
+  # A copy that ships the whole tree, so every commit invalidates it and everything
+  # layered on top of it.
+  BROAD_SOURCES = [ ".", "./", "*", "/" ].freeze
+
+  # buildx expands ARG and ENV references in the vertex name it prints, so a step's text
+  # and the Dockerfile line it came from stop agreeing at the first ${…}. Match on the
+  # longest shared prefix instead, and require enough of it that two unrelated RUNs
+  # cannot be confused for each other.
+  MINIMUM_STEP_MATCH = 12
+
+  attr_reader :document, :context_dir, :dockerignore, :build, :builder, :path
+
+  def initialize(document:, context_dir: nil, dockerignore: nil, build: nil, builder: nil, path: "Dockerfile")
+    @document = document
+    @context_dir = context_dir
+    @dockerignore = dockerignore
+    @build = build
+    @builder = builder
+    @path = path
+  end
+
+  def location_for(instruction)
+    "#{path}:#{instruction.line}"
+  end
+
+  def dependency_install?(instruction)
+    !install_match(instruction).nil?
+  end
+
+  # The command that made it a dependency install ("bundle install"), for advice that
+  # names what the operator wrote rather than the whole RUN.
+  def install_command(instruction)
+    install_match(instruction)&.first
+  end
+
+  def install_cache_target(instruction)
+    install_match(instruction)&.last
+  end
+
+  def apt_install?(instruction)
+    instruction.name == "RUN" && instruction.shell_command.match?(APT_INSTALL.first)
+  end
+
+  def broad_copy?(instruction)
+    return false unless %w[ COPY ADD ].include?(instruction.name)
+    return false if instruction.flag?("from")
+
+    sources(instruction).any? { |source| BROAD_SOURCES.include?(source) }
+  end
+
+  # A dependency install directly after a broad copy is invalidated by every commit,
+  # which is a finding of its own — rules that would otherwise report the same slow step
+  # twice defer to it.
+  def busted_by_broad_copy?(instruction)
+    stage = instruction.stage or return false
+
+    stage.instructions.any? { |other| other.line < instruction.line && broad_copy?(other) }
+  end
+
+  # buildx labels a step with its stage name except in a single-stage build, where it
+  # prints none. A multi-platform build reports the same step once per platform; the
+  # slowest one is the number worth quoting.
+  def build_step_for(instruction)
+    return unless build
+
+    text = normalize(instruction.to_s)
+    candidates = build.instruction_steps.select { |step| same_stage?(step, instruction) }
+
+    best = candidates.max_by do |step|
+      matched = normalize(step.instruction)
+      [ matched == text ? 1 : 0, shared_prefix(text, matched), step.seconds.to_f ]
+    end
+    return unless best
+
+    matched = normalize(best.instruction)
+    best if matched == text || shared_prefix(text, matched) >= MINIMUM_STEP_MATCH
+  end
+
+  def context_entries(name)
+    return [] unless context_dir
+
+    Dir.glob(name, base: context_dir, flags: ::File::FNM_DOTMATCH)
+  end
+
+  private
+    def install_match(instruction)
+      return unless instruction.name == "RUN"
+
+      command = instruction.shell_command
+      DEPENDENCY_INSTALLS.each do |pattern, target|
+        matched = command[pattern]
+        return [ matched, target ] if matched
+      end
+      nil
+    end
+
+    def same_stage?(step, instruction)
+      step.stage.nil? ? document.stages.one? : step.stage == instruction.stage&.name
+    end
+
+    def sources(instruction)
+      words = instruction.json? ? instruction.argv : instruction.args.split(/\s+/)
+      words.size > 1 ? words[0..-2] : words
+    end
+
+    def normalize(text)
+      text.to_s.squeeze(" ").strip
+    end
+
+    def shared_prefix(one, other)
+      length = 0
+      length += 1 while length < one.length && length < other.length && one[length] == other[length]
+      length
+    end
+end

data/lib/dash/dockerfile/dockerignore.rb

@@ -0,0 +1,29 @@
+# Just enough .dockerignore to answer "does this file ship in the build context?".
+#
+# Not a reimplementation of BuildKit's matcher: negations are skipped rather than
+# applied, so a path this says is covered might still ship. That direction is the safe
+# one — it costs a piece of advice, never a false accusation.
+class Dash::Dockerfile::Dockerignore
+  FILENAME = ".dockerignore"
+
+  attr_reader :patterns
+
+  def self.in(directory)
+    path = ::File.join(directory.to_s, FILENAME)
+    new(::File.read(path).lines) if ::File.file?(path)
+  end
+
+  def initialize(lines)
+    @patterns = lines
+      .map(&:strip)
+      .reject { |line| line.empty? || line.start_with?("#", "!") }
+      .map { |line| line.delete_prefix("**/").delete_prefix("./").delete_prefix("/").delete_suffix("/") }
+      .reject(&:empty?)
+  end
+
+  def covers?(path)
+    patterns.any? do |pattern|
+      ::File.fnmatch?(pattern, path, ::File::FNM_DOTMATCH) || path.start_with?("#{pattern}/")
+    end
+  end
+end

data/lib/dash/dockerfile/document.rb

@@ -0,0 +1,28 @@
+# A parsed Dockerfile: its instructions in file order, grouped into stages.
+#
+# Named Document rather than File so that `File.fnmatch` inside Dash::Dockerfile still
+# means the one in Ruby's core library.
+class Dash::Dockerfile::Document
+  attr_reader :instructions, :stages, :directives
+
+  def initialize(instructions:, stages:, directives: {})
+    @instructions = instructions
+    @stages = stages
+    @directives = directives
+  end
+
+  def shipped_stages
+    stages.select(&:shipped?)
+  end
+
+  def final_stage
+    stages.last
+  end
+
+  def each_instruction(name)
+    return to_enum(:each_instruction, name) unless block_given?
+
+    name = name.to_s.upcase
+    instructions.each { |instruction| yield instruction if instruction.name == name }
+  end
+end

data/lib/dash/dockerfile/finding.rb

@@ -0,0 +1,20 @@
+# One piece of advice about the Dockerfile or the build context.
+#
+# `rule` is a stable public string an operator can put in `report: ignore:`, so renaming
+# one is a breaking change to their deploy.yml. `location` is whatever they should open:
+# a Dockerfile line, `.dockerignore`, `build context`, or a deploy.yml key.
+Dash::Dockerfile::Finding = Struct.new(:rule, :severity, :location, :message, :suggestion, keyword_init: true) do
+  def warn?
+    severity == :warn
+  end
+
+  def self.from_h(hash)
+    hash = hash.transform_keys(&:to_sym)
+
+    new(**hash.slice(:rule, :location, :message, :suggestion), severity: hash[:severity].to_sym)
+  end
+
+  def to_h
+    { rule: rule, severity: severity.to_s, location: location, message: message, suggestion: suggestion }
+  end
+end

data/lib/dash/dockerfile/hadolint.rb

@@ -0,0 +1,75 @@
+require "json"
+require "open3"
+require "active_support/core_ext/string/filters"
+
+# Optional supplement to the built-in rules: whatever `hadolint` has to say about the same
+# file, when the operator already has it installed.
+#
+# Run as a plain local process rather than through SSHKit, so the command sequence a deploy
+# prints — and the cost-guard test that pins it — is unchanged. `--no-fail` keeps its exit
+# status out of the deploy, and anything that goes wrong becomes one informational finding
+# rather than an exception.
+class Dash::Dockerfile::Hadolint
+  EXECUTABLE = "hadolint".freeze
+  # hadolint's own levels. `error` is the only one worth a warning next to a deploy; the
+  # rest are style notes that should not compete with a measured finding.
+  SEVERITIES = { "error" => :warn }.freeze
+
+  class << self
+    # No shell: PATH is walked directly, so a directory with a space or a semicolon in it
+    # cannot turn a lookup into a command.
+    def available?
+      ENV["PATH"].to_s.split(::File::PATH_SEPARATOR).any? do |directory|
+        path = ::File.join(directory, EXECUTABLE)
+        ::File.executable?(path) && !::File.directory?(path)
+      end
+    end
+  end
+
+  def initialize(path:, file: path)
+    @path = path
+    @file = file
+  end
+
+  def findings
+    return [] unless self.class.available?
+
+    output, status = Open3.capture2(EXECUTABLE, "--format", "json", "--no-fail", @file)
+    return unavailable("exited #{status.exitstatus}") unless status.success?
+    return [] if output.strip.empty?
+
+    issues = JSON.parse(output)
+    return unparsable("expected a JSON array, got #{issues.class.name.downcase}") unless issues.is_a?(Array)
+
+    issues.map { |issue| finding_for(issue) }
+  # Only JSON.parse raises this, so it is the one error that means "it ran fine, dash
+  # could not read what it printed". Anything else that raises in here is dash's own.
+  rescue JSON::ParserError => e
+    unparsable(e.message.truncate(80))
+  rescue StandardError => e
+    unavailable(e.message)
+  end
+
+  private
+    def finding_for(issue)
+      Dash::Dockerfile::Finding.new \
+        rule: issue["code"],
+        severity: SEVERITIES.fetch(issue["level"], :info),
+        location: "#{@path}:#{issue["line"]}",
+        message: "#{issue["code"]}: #{issue["message"]}",
+        suggestion: nil
+    end
+
+    def unparsable(reason)
+      note "hadolint output could not be parsed (#{reason})"
+    end
+
+    def unavailable(reason)
+      note "hadolint could not run (#{reason})"
+    end
+
+    def note(message)
+      [ Dash::Dockerfile::Finding.new(rule: "hadolint", severity: :info, location: EXECUTABLE,
+        message: message, suggestion: "silence this with report: hadolint: false") ]
+    end
+end

data/lib/dash/dockerfile/instruction.rb

@@ -0,0 +1,58 @@
+require "json"
+
+# One logical Dockerfile instruction: the keyword, its flags, and everything else on the
+# line — continuations joined, heredoc bodies appended, comments dropped.
+#
+# `line` is the first physical line the instruction started on, because that is the line
+# an operator opens their editor at when advice names it.
+class Dash::Dockerfile::Instruction
+  attr_reader :name, :args, :flags, :line
+  attr_accessor :stage
+
+  def initialize(name:, args:, flags: {}, line: 1)
+    @name = name
+    @args = args
+    @flags = flags
+    @line = line
+  end
+
+  # The first value of a flag. Repeated flags (several `--mount`s on one RUN) keep every
+  # value in `flags`; callers that only care whether one is present ask for the first.
+  def flag(key)
+    Array(flags[key]).first
+  end
+
+  def flag?(key)
+    flags.key?(key)
+  end
+
+  def json?
+    args.start_with?("[") && !argv.nil?
+  end
+
+  # The exec form's arguments, or nil when this is the shell form (or malformed JSON,
+  # which BuildKit would reject but which must not take the analyzer down with it).
+  def argv
+    return @argv if defined?(@argv)
+
+    @argv = begin
+      parsed = JSON.parse(args) if args.start_with?("[")
+      parsed if parsed.is_a?(Array) && parsed.all?(String)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+
+  # What the instruction runs, as one string, whichever form it was written in — the
+  # rules match against shell text and should not have to care.
+  def shell_command
+    json? ? argv.join(" ") : args
+  end
+
+  # Collapsed to a single line so it can be compared with what buildx printed for the
+  # matching vertex, and so advice can name it without wrapping the terminal.
+  def to_s
+    [ name, *flags.flat_map { |key, values| values.map { |value| "--#{key}=#{value}" } }, args ]
+      .reject(&:blank?).join(" ").gsub(/\s+/, " ")
+  end
+end