dependabot-docker 0.383.0 → 0.384.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0200408166a023ea4720b018f90dda3232304f7b5f1abec28dd8dbb9bf2b3f0e'
-  data.tar.gz: 99f2b3c7a81588a396ca4fc38b1cb9ce9d5907f455122f7b3285fc84c92afe51
+  metadata.gz: 62ae318b274003dd8cb082364cb06233a54d27c993e96ebd598128b198f280e7
+  data.tar.gz: 3c2c803bab214190b06d60ffe76c4de7781cc81254403a616220d685f1040347
 SHA512:
-  metadata.gz: b4eb568dd7249d487a42415564920512f63d953049334e64ec09171435385b48365e0934c8d392b8d7033d743f33b887fb4de1548e1c25db65e355cd2e9cf798
-  data.tar.gz: 517a96c97e6b74ed9873be9d49cbdf0913204f2111f4191c18a22a9c6c9e37c9665760a70662f84e4c87b65607b710414d871109fd72dc68d64f58f0f56795ea
+  metadata.gz: 91b741842929d3bb485325f0315a71defae699ea33b16e0c4fe7f605dfc3e3caeb4db99c2751ccb170059d3e7a741d6c1cc77483ff79ac0e52c18d16be6b6141
+  data.tar.gz: f3d93ecfb28273c0af1fe959cc830b67121c20ec8010f086865bbcf3191bbff301da0e406b7305a609e946ae6342898a50b815eea776bf782f09512f3dccc585

data/lib/dependabot/docker/update_checker.rb

@@ -60,6 +60,17 @@ module Dependabot
         T::Array[String]
       )
 
+      # Media types returned for single-platform (non manifest-list) images.
+      # Used to cheaply rule out manifest-list comparison via a HEAD request's
+      # negotiated Content-Type, avoiding a full manifest GET for these images.
+      SINGLE_PLATFORM_MANIFEST_TYPES = T.let(
+        [
+          "application/vnd.docker.distribution.manifest.v2+json",
+          "application/vnd.oci.image.manifest.v1+json"
+        ].freeze,
+        T::Array[String]
+      )
+
       # Tolerance window for platform timestamp comparison.
       # Multi-arch CI builds may finish platforms at slightly different times.
       PLATFORM_TIMESTAMP_TOLERANCE_SECONDS = T.let(3 * 60 * 60, Integer)
@@ -141,9 +152,9 @@ module Dependabot
           if tag
             updated_tag = latest_version_from(tag)
             updated_source[:tag] = updated_tag
-            updated_source[:digest] = digest_of(updated_tag) if digest || pin_digests?
+            updated_source[:digest] = resolved_digest_for(tag, updated_tag, digest) if digest || pin_digests?
           elsif digest
-            updated_source[:digest] = digest_of("latest")
+            updated_source[:digest] = digest_within_cooldown?("latest") ? digest : digest_of("latest")
           end
 
           req.merge(source: updated_source)
@@ -206,37 +217,51 @@ module Dependabot
 
       sig { returns(T::Boolean) }
       def digest_up_to_date?
-        digest_requirements.all? do |req|
-          source = req.fetch(:source)
-          source_digest = source.fetch(:digest)
-          source_tag = source[:tag]
-
-          expected_digest =
-            if source_tag
-              latest_tag = latest_tag_from(source_tag)
-
-              # When digest-only updates are suppressed and the tag hasn't changed,
-              # treat the digest as up-to-date to avoid proposing a PR that only
-              # bumps the digest without a corresponding version change.
-              # Only apply to comparable (versioned) tags — non-comparable tags like
-              # "latest" or distro codenames should still get digest updates.
-              if Dependabot::Experiments.enabled?(:docker_digest_only_update_suppression) &&
-                 Tag.new(source_tag).comparable? &&
-                 latest_tag.name == source_tag
-                next true
-              end
-
-              digest_of(latest_tag.name)
-            else
-              updated_digest
-            end
+        digest_requirements.all? { |req| digest_requirement_up_to_date?(req) }
+      end
+
+      sig { params(req: T::Hash[Symbol, T.untyped]).returns(T::Boolean) }
+      def digest_requirement_up_to_date?(req)
+        source = req.fetch(:source)
+        source_digest = source.fetch(:digest)
+        source_tag = source[:tag]
 
-          # If we can't determine an expected digest (for example if the registry does not return digests)
-          # assume it's up to date
-          next true if expected_digest.nil?
+        if source_tag
+          latest_tag = latest_tag_from(source_tag)
+          digest_only_refresh = latest_tag.name == source_tag
 
-          source_digest == expected_digest
+          # Digest-only refresh (tag unchanged): respect the cooldown window
+          # so a freshly-pushed digest isn't proposed before it matures. This
+          # covers both comparable and non-comparable tags (e.g. "alpine"),
+          # which the version-tag cooldown (apply_cooldown) never reaches.
+          return true if digest_only_refresh && digest_within_cooldown?(source_tag)
+
+          # When digest-only updates are suppressed and the tag hasn't changed,
+          # treat the digest as up-to-date to avoid proposing a PR that only
+          # bumps the digest without a corresponding version change.
+          # Only apply to comparable (versioned) tags — non-comparable tags like
+          # "latest" or distro codenames should still get digest updates.
+          return true if digest_only_update_suppressed?(source_tag, latest_tag)
+
+          expected_digest = digest_of(latest_tag.name)
+        else
+          digest_only_refresh = true
+          # Pure digest pin (no tag): the proposed digest resolves from the
+          # "latest" tag, so gate it on the same cooldown window.
+          return true if digest_within_cooldown?("latest")
+
+          expected_digest = updated_digest
         end
+
+        # If we can't determine an expected digest (for example if the registry does not return digests)
+        # assume it's up to date
+        return true if expected_digest.nil?
+
+        # Multi-arch no-op: a digest-only refresh whose index digest changed only
+        # because an unconsumed platform was rebuilt should not open a PR.
+        return true if digest_refresh_is_noop?(source, source_digest, expected_digest, digest_only_refresh)
+
+        source_digest == expected_digest
       end
 
       sig { params(version: String).returns(String) }
@@ -446,7 +471,7 @@ module Dependabot
         published_date = last_modified ? Time.parse(last_modified) : nil
 
         Dependabot::Package::PackageRelease.new(
-          version: Docker::Version.new(tag.name),
+          version: release_version_for(tag),
           released_at: published_date,
           latest: false,
           yanked: false,
@@ -932,6 +957,130 @@ module Dependabot
         Dependabot::UpdateCheckers::CooldownCalculation.within_cooldown_window?(release_date, days)
       end
 
+      # Builds the PackageRelease version for a tag. Non-comparable tags (e.g.
+      # "alpine") have no semver, so Docker::Version.new would raise. The version
+      # is only consumed by semver-aware version-tag cooldown; the digest cooldown
+      # path relies solely on the release date, so a sentinel keeps PackageRelease
+      # construction safe for non-comparable tags.
+      sig { params(tag: Dependabot::Docker::Tag).returns(Dependabot::Version) }
+      def release_version_for(tag)
+        Docker::Version.new(tag.name)
+      rescue ArgumentError, TypeError
+        Dependabot::Version.new("0")
+      end
+
+      # Whether the digest currently served for the given tag was published too
+      # recently to satisfy the configured cooldown window. Digest-only refreshes
+      # don't change the version string, so the default cooldown window applies
+      # (semver-specific windows require a version delta, and the tag may be
+      # non-comparable like "alpine"). Fails open (returns false) when the
+      # publication date can't be determined, so a missing Last-Modified header
+      # never permanently blocks an update.
+      sig { params(tag_name: String).returns(T::Boolean) }
+      def digest_within_cooldown?(tag_name)
+        return false if should_skip_cooldown?
+
+        cooldown = @update_cooldown
+        return false unless cooldown
+
+        released_at = publication_detail(Tag.new(tag_name))&.released_at
+        return false unless released_at
+
+        Dependabot::UpdateCheckers::CooldownCalculation.within_cooldown_window?(
+          released_at, cooldown.default_days
+        )
+      end
+
+      # Resolves the digest to write for a tag during a requirement update.
+      # Keeps the existing digest for a digest-only refresh that's still within
+      # the cooldown window; otherwise resolves the latest digest for the tag.
+      sig do
+        params(
+          current_tag: String,
+          updated_tag: String,
+          current_digest: T.nilable(String)
+        ).returns(T.nilable(String))
+      end
+      def resolved_digest_for(current_tag, updated_tag, current_digest)
+        # Keep the existing digest for a digest-only refresh that's still within
+        # the cooldown window; otherwise resolve the latest digest for the tag.
+        return current_digest if current_digest && updated_tag == current_tag &&
+                                 digest_within_cooldown?(updated_tag)
+
+        digest_of(updated_tag)
+      end
+
+      # Whether a digest-only update for an unchanged comparable tag is suppressed
+      # by the docker_digest_only_update_suppression experiment. Non-comparable
+      # tags like "latest" or distro codenames are excluded so they still update.
+      sig do
+        params(source_tag: String, latest_tag: Dependabot::Docker::Tag).returns(T::Boolean)
+      end
+      def digest_only_update_suppressed?(source_tag, latest_tag)
+        Dependabot::Experiments.enabled?(:docker_digest_only_update_suppression) &&
+          Tag.new(source_tag).comparable? &&
+          latest_tag.name == source_tag
+      end
+
+      # Whether a digest-only refresh is a no-op for the platform(s) the user
+      # actually consumes. Only applies when the tag is unchanged and the index
+      # digest moved; otherwise this is a genuine version/digest change.
+      sig do
+        params(
+          source: T::Hash[Symbol, T.untyped],
+          current_digest: String,
+          expected_digest: String,
+          digest_only_refresh: T::Boolean
+        ).returns(T::Boolean)
+      end
+      def digest_refresh_is_noop?(source, current_digest, expected_digest, digest_only_refresh)
+        digest_only_refresh &&
+          current_digest != expected_digest &&
+          multiarch_noop?(source, current_digest, expected_digest)
+      end
+
+      # Compares the per-platform manifest digests of the currently-pinned index
+      # against the candidate index. When the Dockerfile pins `--platform`, only
+      # that platform is compared; otherwise every platform must be identical.
+      # Fails open (returns false) whenever a confident comparison isn't possible.
+      sig do
+        params(
+          source: T::Hash[Symbol, T.untyped],
+          current_digest: String,
+          candidate_digest: String
+        ).returns(T::Boolean)
+      end
+      def multiarch_noop?(source, current_digest, candidate_digest)
+        current = platform_digests("sha256:#{current_digest}")
+        candidate = platform_digests("sha256:#{candidate_digest}")
+
+        # Either reference is single-platform or couldn't be fetched: can't prove a no-op.
+        return false if current.nil? || candidate.nil?
+
+        pinned = pinned_platform_key(source[:platform])
+        if pinned
+          current_platform = current[pinned]
+          candidate_platform = candidate[pinned]
+          return false if current_platform.nil? || candidate_platform.nil?
+
+          current_platform == candidate_platform
+        else
+          # No platform pin: only a no-op if nothing changed for any platform.
+          current == candidate
+        end
+      end
+
+      # Normalizes a Dockerfile `--platform` value into a manifest platform key
+      # (e.g. "linux/amd64", "linux/arm64/v8"). Returns nil for build-arg
+      # placeholders like `$BUILDPLATFORM` so we fall back to the strict check.
+      sig { params(platform: T.nilable(String)).returns(T.nilable(String)) }
+      def pinned_platform_key(platform)
+        return nil if platform.nil?
+        return nil unless platform.match?(%r{\A[a-z0-9]+/[a-z0-9]+(?:/[a-z0-9]+)?\z})
+
+        platform
+      end
+
       # Fetches the "created" timestamp from the image config blob for a given tag.
       # This represents the actual build time, which is more reliable than semver
       # for determining which image is truly newer.
@@ -1122,6 +1271,10 @@ module Dependabot
       # with matching per-platform manifest digests. For single-platform images this
       # returns false (empty digest map), so this check is effectively a no-op and
       # we fall back to the existing semver/precision selection logic.
+      #
+      # Single-platform current tags are ruled out up front with a cheap HEAD
+      # request, so the default path doesn't pay for a full manifest GET that
+      # would only ever return an empty digest map.
       sig do
         params(
           candidate_tag: Dependabot::Docker::Tag,
@@ -1129,6 +1282,12 @@ module Dependabot
         ).returns(T::Boolean)
       end
       def same_image_contents?(candidate_tag, current_tag)
+        # Only manifest lists can match here, so confirm the current tag is
+        # multi-arch with a cheap HEAD request before paying for the full
+        # manifest GET that fetch_platform_digests performs. Single-platform
+        # images (the default path) short-circuit without an extra manifest GET.
+        return false if single_platform_image?(current_tag.name)
+
         current_digests = fetch_platform_digests(current_tag.name)
         return false if current_digests.empty?
 
@@ -1141,6 +1300,74 @@ module Dependabot
         current_digests == candidate_digests
       end
 
+      # Returns true when a tag points at a single-platform image rather than a
+      # multi-arch manifest list. Uses a HEAD request — the registry reports the
+      # negotiated media type in the Content-Type header — so we avoid the more
+      # expensive full-manifest GET that fetch_platform_digests performs.
+      #
+      # Reuses a manifest list already fetched for the tag when available, and
+      # only treats positively recognised single-platform media types as
+      # single-platform. An ambiguous, missing or errored response returns false
+      # so the caller falls back to the per-platform comparison rather than risk
+      # skipping a real manifest list.
+      sig { params(tag_name: String).returns(T::Boolean) }
+      def single_platform_image?(tag_name)
+        return manifest_list_cache[tag_name].nil? if manifest_list_cache.key?(tag_name)
+        return T.must(single_platform_cache[tag_name]) if single_platform_cache.key?(tag_name)
+
+        single_platform_cache[tag_name] = fetch_single_platform_flag(tag_name)
+      end
+
+      sig { params(tag_name: String).returns(T::Boolean) }
+      def fetch_single_platform_flag(tag_name)
+        response = with_retries(max_attempts: 3, errors: transient_docker_errors) do
+          docker_registry_client.dohead("v2/#{docker_repo_name}/manifests/#{tag_name}")
+        end
+
+        media_type = response.headers[:content_type]&.split(";")&.first&.strip
+        SINGLE_PLATFORM_MANIFEST_TYPES.include?(media_type)
+      rescue DockerRegistry2::Exception => e
+        Dependabot.logger.info(
+          "Failed to determine manifest media type for #{docker_repo_name}:#{tag_name}, " \
+          "falling back to per-platform comparison: #{e.class} - #{e.message}"
+        )
+        false
+      end
+
+      # Fetches a tag's manifest list (multi-arch image index) and returns the
+      # array of per-platform manifest entries, or nil for single-platform images
+      # (not a manifest list). Cached so the platform-inspection methods below
+      # share a single registry GET per tag.
+      sig { params(tag_name: String).returns(T.nilable(T::Array[T::Hash[String, T.untyped]])) }
+      def fetch_manifest_list(tag_name)
+        return manifest_list_cache[tag_name] if manifest_list_cache.key?(tag_name)
+
+        manifest_list_cache[tag_name] = fetch_manifest_list_from_registry(tag_name)
+      rescue DockerRegistry2::Exception, JSON::ParserError => e
+        # Do NOT cache fetch failures. A cached nil is reserved for "definitely
+        # not a manifest list" (single-platform), which single_platform_image?
+        # relies on. Caching a transient error as nil would misclassify the tag
+        # as single-platform and permanently short-circuit same-content
+        # suppression, even if a later manifest fetch would succeed. Returning
+        # nil without caching lets a subsequent call retry.
+        Dependabot.logger.info(
+          "Failed to fetch manifest list for #{docker_repo_name}:#{tag_name}: #{e.message}"
+        )
+        nil
+      end
+
+      sig { params(tag_name: String).returns(T.nilable(T::Array[T::Hash[String, T.untyped]])) }
+      def fetch_manifest_list_from_registry(tag_name)
+        manifest = with_retries(max_attempts: 3, errors: transient_docker_errors) do
+          docker_registry_client.manifest(docker_repo_name, tag_name)
+        end
+
+        media_type = manifest["mediaType"] || manifest[:mediaType]
+        return nil unless MANIFEST_LIST_TYPES.include?(media_type)
+
+        manifest["manifests"] || manifest[:manifests] || []
+      end
+
       # Fetches a map of platform key (e.g. "linux/amd64") to platform manifest
       # digest for a tag's manifest list. Returns an empty hash for single-platform
       # images or when the manifest can't be fetched.
@@ -1162,14 +1389,9 @@ module Dependabot
 
       sig { params(tag_name: String).returns(T::Hash[String, String]) }
       def fetch_platform_digests_from_registry(tag_name)
-        manifest = with_retries(max_attempts: 3, errors: transient_docker_errors) do
-          docker_registry_client.manifest(docker_repo_name, tag_name)
-        end
-
-        media_type = manifest["mediaType"] || manifest[:mediaType]
-        return {} unless MANIFEST_LIST_TYPES.include?(media_type)
+        manifests = fetch_manifest_list(tag_name)
+        return {} unless manifests
 
-        manifests = manifest["manifests"] || manifest[:manifests] || []
         collect_platform_digests(manifests)
       end
 
@@ -1210,19 +1432,26 @@ module Dependabot
 
       sig { params(tag_name: String).returns(T.nilable(T::Array[T::Hash[String, T.untyped]])) }
       def fetch_manifest_platforms_from_registry(tag_name)
-        manifest = with_retries(max_attempts: 3, errors: transient_docker_errors) do
-          docker_registry_client.manifest(docker_repo_name, tag_name)
-        end
-
-        media_type = manifest["mediaType"] || manifest[:mediaType]
-        return nil unless MANIFEST_LIST_TYPES.include?(media_type)
-
-        manifests = manifest["manifests"] || manifest[:manifests] || []
+        manifests = fetch_manifest_list(tag_name)
+        return nil unless manifests
 
         # Filter to actual image manifests (exclude attestations/signatures)
         manifests.filter_map { |m| extract_platform(m) }
       end
 
+      # Maps each platform in a manifest list to its per-platform manifest digest,
+      # e.g. { "linux/amd64" => "sha256:…", "linux/arm64/v8" => "sha256:…" }.
+      # Accepts a tag name or a digest reference (e.g. "sha256:…"). Returns nil
+      # for single-platform images or when the manifest can't be fetched, so
+      # callers fail open rather than treat an unknown image as a no-op.
+      sig { params(reference: String).returns(T.nilable(T::Hash[String, String])) }
+      def platform_digests(reference)
+        digests = fetch_platform_digests(reference)
+        return nil if digests.empty?
+
+        digests
+      end
+
       sig { params(manifest_entry: T.untyped).returns(T.nilable(T::Hash[String, T.untyped])) }
       def extract_platform(manifest_entry)
         platform = manifest_entry["platform"] || manifest_entry[:platform]
@@ -1267,14 +1496,9 @@ module Dependabot
 
       sig { params(tag_name: String).returns(T::Hash[String, T.nilable(Time)]) }
       def fetch_all_platform_timestamps_from_registry(tag_name)
-        manifest = with_retries(max_attempts: 3, errors: transient_docker_errors) do
-          docker_registry_client.manifest(docker_repo_name, tag_name)
-        end
-
-        media_type = manifest["mediaType"] || manifest[:mediaType]
-        return {} unless MANIFEST_LIST_TYPES.include?(media_type)
+        manifests = fetch_manifest_list(tag_name)
+        return {} unless manifests
 
-        manifests = manifest["manifests"] || manifest[:manifests] || []
         collect_platform_timestamps(manifests)
       end
 
@@ -1309,6 +1533,22 @@ module Dependabot
         parse_created_from_config_blob(config_digest)
       end
 
+      sig { returns(T::Hash[String, T.nilable(T::Array[T::Hash[String, T.untyped]])]) }
+      def manifest_list_cache
+        @manifest_list_cache ||= T.let(
+          {},
+          T.nilable(T::Hash[String, T.nilable(T::Array[T::Hash[String, T.untyped]])])
+        )
+      end
+
+      sig { returns(T::Hash[String, T::Boolean]) }
+      def single_platform_cache
+        @single_platform_cache ||= T.let(
+          {},
+          T.nilable(T::Hash[String, T::Boolean])
+        )
+      end
+
       sig { returns(T::Hash[String, T.nilable(T::Array[T::Hash[String, T.untyped]])]) }
       def manifest_platforms_cache
         @manifest_platforms_cache ||= T.let(

data/lib/dependabot/shared/shared_file_parser.rb

@@ -43,6 +43,7 @@ module Dependabot
         source[:registry] = parsed_line.fetch("registry") if parsed_line.fetch("registry")
         source[:tag] = parsed_line.fetch("tag") if parsed_line.fetch("tag")
         source[:digest] = parsed_line.fetch("digest") if parsed_line.fetch("digest")
+        source[:platform] = parsed_line["platform"] if parsed_line["platform"]
 
         source
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dependabot-docker
 version: !ruby/object:Gem::Version
-  version: 0.383.0
+  version: 0.384.0
 platform: ruby
 authors:
 - Dependabot
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.383.0
+        version: 0.384.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.383.0
+        version: 0.384.0
 - !ruby/object:Gem::Dependency
   name: debug
   requirement: !ruby/object:Gem::Requirement
@@ -266,7 +266,7 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/dependabot/dependabot-core/issues
-  changelog_uri: https://github.com/dependabot/dependabot-core/releases/tag/v0.383.0
+  changelog_uri: https://github.com/dependabot/dependabot-core/releases/tag/v0.384.0
 rdoc_options: []
 require_paths:
 - lib
@@ -281,7 +281,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: 3.3.0
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.14
 specification_version: 4
 summary: Provides Dependabot support for Docker
 test_files: []