docker_distribution 0.1.0

data/lib/docker_distribution/normalize.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module DockerDistribution
+  class Normalize
+    LEGACY_DEFAULT_DOMAIN = "index.docker.io"
+    DEFAULT_DOMAIN = "docker.io"
+    OFFICIAL_REPO_NAME = "library"
+    DEFAULT_TAG = "latest"
+
+    class << self
+      # ParseNormalizedNamed parses a string into a named reference
+      # transforming a familiar name from Docker UI to a fully
+      # qualified reference. If the value may be an identifier
+      # use ParseAnyReference.
+      def parse_normalized_named(str)
+        raise ParseNormalizedNamedError if Regexp.anchored_identifier_regexp.match?(str)
+
+        domain, remainder = split_docker_domain(str)
+
+        tag_sep = remainder.index(":") || -1
+        remote_name = tag_sep > -1 ? Helpers.to(remainder, tag_sep) : remainder
+        raise ParseNormalizedNamedError if remote_name != remote_name.downcase
+
+        ref = DockerDistribution::Reference.parse("#{domain}/#{remainder}")
+        raise ParseNormalizedNamedError if Helpers.empty?(ref)
+
+        ref
+      end
+
+      # ParseDockerRef normalizes the image reference following the docker convention. This is added
+      # mainly for backward compatibility.
+      # The reference returned can only be either tagged or digested. For reference contains both tag
+      # and digest, the function returns digested reference, e.g. docker.io/library/busybox:latest@
+      # sha256:7cc4b5aefd1d0cadf8d97d4350462ba51c694ebca145b08d7d41b41acc8db5aa will be returned as
+      # docker.io/library/busybox@sha256:7cc4b5aefd1d0cadf8d97d4350462ba51c694ebca145b08d7d41b41acc8db5aa.
+      def parse_docker_ref(ref)
+        named = parse_normalized_named(ref)
+        if Helpers.tagged?(named) && Helpers.canonical?(named)
+          new_named = Reference.with_name(named.name)
+          new_canonical = Reference.with_digest(new_named, named.digest)
+          return new_canonical
+        end
+
+        tag_name_only(named)
+      end
+
+      # splitDockerDomain splits a repository name to domain and remote name string.
+      # If no valid domain is found, the default domain is used. Repository name
+      # needs to be already validated before.
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      def split_docker_domain(name)
+        i = name.index("/") || -1
+
+        start_part = Helpers.to(name, i)
+        end_part = Helpers.from(name, i + 1)
+
+        if (i == -1 || [".", ":"].none? do |sep|
+              start_part.include?(sep)
+            end) && start_part != "localhost" && start_part.downcase == start_part
+          domain = DEFAULT_DOMAIN
+          remainder = name
+        else
+          domain = start_part
+          remainder = end_part
+        end
+
+        domain = DEFAULT_DOMAIN if domain == LEGACY_DEFAULT_DOMAIN
+        remainder = [OFFICIAL_REPO_NAME, remainder].join("/") if domain == DEFAULT_DOMAIN && !remainder.include?("/")
+
+        [domain, remainder]
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+      # familiarizeName returns a shortened version of the name familiar
+      # to to the Docker UI. Familiar names have the default domain
+      # "docker.io" and "library/" repository prefix removed.
+      # For example, "docker.io/library/redis" will have the familiar
+      # name "redis" and "docker.io/dmcgowan/myapp" will be "dmcgowan/myapp".
+      # Returns a familiarized named only reference.
+      def familiarize_name(repo)
+        familiar_repo = Repository.new(repo.domain, repo.path)
+
+        if familiar_repo.domain == DEFAULT_DOMAIN
+          familiar_repo.domain = nil
+          parts = familiar_repo.path.split("/")
+          familiar_repo.path = parts[1] if parts.length == 2 && parts[0] == OFFICIAL_REPO_NAME
+        end
+        familiar_repo
+      end
+
+      # TagNameOnly adds the default tag "latest" to a reference if it only has
+      # a repo name.
+      def tag_name_only(ref)
+        return Reference.with_tag(ref, DEFAULT_TAG) if Helpers.name_only?(ref)
+
+        ref
+      end
+
+      # ParseAnyReference parses a reference string as a possible identifier,
+      # full digest, or familiar name.
+      def parse_any_reference(ref)
+        return DigestReference.new("sha256:#{ref}") if Regexp.anchored_identifier_regexp.match?(ref)
+
+        digest = Digest.parse!(ref)
+        DigestReference.new(digest.digest)
+      rescue DigestError
+        parse_normalized_named(ref)
+      end
+
+      # ParseAnyReferenceWithSet parses a reference string as a possible short
+      # identifier to be matched in a digest set, a full digest, or familiar name.
+      def parse_any_reference_with_set(ref, digest_set)
+        if Regexp.anchored_short_identifier_regexp.match?(ref)
+          dgst = digest_set.lookup!(ref)
+          return DigestReference.new(dgst) if dgst
+        else
+          dgst = Digest.parse!(ref)
+          DigestReference.new(dgst.digest)
+        end
+      rescue DigestError
+        parse_normalized_named(ref)
+      end
+    end
+  end
+end

data/lib/docker_distribution/reference.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity, Naming/MethodParameterName
+module DockerDistribution
+  class Reference
+    MAX_NAME_TOTAL_LENGTH = 255
+    extend ::Forwardable
+    def_delegators :repository, :name, :domain, :path
+
+    attr_accessor :repository, :tag, :digest
+
+    def initialize(repository = nil, tag = nil, digest = nil)
+      @repository = repository
+      @tag = tag
+      @digest = digest
+    end
+
+    def to_s
+      [name, ":", tag, "@", digest].join("")
+    end
+
+    def to_h
+      {
+        repository: name,
+        domain: domain,
+        path: path,
+        tag: tag,
+        digest: digest
+      }
+    end
+
+    def familiar
+      self.class.new(Normalize.familiarize_name(self), tag, digest)
+    end
+
+    #  Parse parses s and returns a syntactically valid Reference.
+    #  If an error was encountered it is returned, along with a nil Reference.
+    #  NOTE: Parse will not handle short digests.
+    def self.parse(s)
+      matches = Regexp.reference_regexp.match(s)
+      if matches.nil?
+        raise NameEmpty if Helpers.empty?(s)
+        raise NameContainsUppercase unless Regexp.reference_regexp.match(s.downcase).nil?
+
+        raise ReferenceInvalidFormat
+      end
+
+      match_results = matches.to_a
+      raise NameTooLong if match_results[1] && match_results[1].length > MAX_NAME_TOTAL_LENGTH
+
+      repo = Repository.new
+      name_match = Regexp.anchored_name_regexp.match(match_results[1])
+      name_match_results = name_match&.to_a
+
+      if name_match_results && name_match_results.length == 3
+        repo.domain = name_match_results[1]
+        repo.path = name_match_results[2]
+      else
+        repo.domain = nil
+        repo.path = name_match_results[1]
+      end
+
+      ref = Reference.new(repo, match_results[2])
+
+      unless Helpers.empty?(match_results[3])
+        digest = Digest.parse!(match_results[3])
+        ref.digest = digest.digest
+      end
+
+      r = get_best_reference_type(ref)
+      raise NameEmpty if r.nil?
+
+      r
+    end
+
+    #  ParseNamed parses s and returns a syntactically valid reference implementing
+    #  the Named interface. The reference must have a name and be in the canonical
+    #  form, otherwise an error is returned.
+    #  If an error was encountered it is returned, along with a nil Reference.
+    #  NOTE: ParseNamed will not handle short digests.
+    def self.parse_named(str)
+      named = Normalize.parse_normalized_named(str)
+      raise NameNotCanonical if named.to_s != str
+
+      named
+    end
+
+    #  WithName returns a named object representing the given string. If the input
+    #  is invalid ErrReferenceInvalidFormat will be returned.
+    def self.with_name(name)
+      raise NameEmpty if Helpers.empty?(name)
+      raise NameTooLong if name.length > MAX_NAME_TOTAL_LENGTH
+
+      match = Regexp.anchored_name_regexp.match(name)
+      raise ReferenceInvalidFormat if match.nil? || match.to_a.length != 3
+
+      match_result = match.to_a
+      Repository.new(match_result[1], match_result[2])
+    end
+
+    #  WithTag combines the name from "name" and the tag from "tag" to form a
+    #  reference incorporating both the name and the tag.
+    def self.with_tag(named, tag)
+      match = Regexp.anchored_tag_regexp.match(tag)
+      raise TagInvalidFormat if match.nil?
+
+      repo = Repository.new
+      if named.is_a?(Repository)
+        repo.domain = named.domain
+        repo.path = named.path
+      else
+        repo.path = named.name
+      end
+
+      return Reference.new(repo, tag, named.digest) if named.is_a?(CanonicalReference)
+
+      TaggedReference.new(repo, tag)
+    end
+
+    #  WithDigest combines the name from "name" and the digest from "digest" to form
+    #  a reference incorporating both the name and the digest.
+    def self.with_digest(named, digest)
+      match = Regexp.anchored_digest_regexp.match(digest)
+      raise DigestInvalidFormat if match.nil?
+
+      repo = Repository.new
+      if named.is_a?(Repository)
+        repo.domain = named.domain
+        repo.path = named.path
+      else
+        repo.path = named.name
+      end
+
+      return Reference.new(repo, named.tag, digest) if named.is_a?(TaggedReference)
+
+      CanonicalReference.new(repo, digest)
+    end
+
+    #  TrimNamed removes any tag or digest from the named reference.
+    def self.trim_named(ref)
+      domain, path = split_hostname(ref)
+      new Repository(domain, path)
+    end
+
+    def self.get_best_reference_type(ref)
+      if Helpers.empty?(ref.name)
+        return DigestReference.new(ref.digest) unless Helpers.empty?(ref.digest)
+
+        return nil
+      end
+
+      if Helpers.empty?(ref.tag)
+        return CanonicalReference.new(ref.repository, ref.digest) unless Helpers.empty?(ref.digest)
+
+        return ref.repository
+      end
+
+      return TaggedReference.new(ref.repository, ref.tag) if Helpers.empty?(ref.digest)
+
+      ref
+    end
+
+    def self.split_domain(name)
+      match = Regexp.anchored_name_regexp.match(name)
+      return [nil, name] if match && match.to_a.length != 3
+
+      match_results = match.to_a
+      [match_results[1], match_results[2]]
+    end
+
+    def self.split_hostname(named)
+      return [named.domain, named.path] if named.is_a?(Repository)
+
+      split_domain(name)
+    end
+  end
+end
+# rubocop:enable all

data/lib/docker_distribution/regexp.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/ClassLength
+module DockerDistribution
+  # Representation of regxexps we will use
+  class Regexp
+    class << self
+      # alphaNumeric defines the alpha numeric atom, typically a
+      # component of names. This only allows lower case characters and digits.
+      def alpha_numeric
+        "[a-z0-9]+"
+      end
+
+      # separator defines the separators allowed to be embedded in name
+      # components. This allow one period, one or two underscore and multiple
+      # dashes. Repeated dashes and underscores are intentionally treated
+      # differently. In order to support valid hostnames as name components,
+      # supporting repeated dash was added. Additionally double underscore is
+      # now allowed as a separator to loosen the restriction for previously
+      # supported names.
+      def separator
+        "(?:[._]|__|[-]*)"
+      end
+
+      # nameComponent restricts registry path component names to start
+      # with at least one letter or number, with following parts able to be
+      # separated by one period, one or two underscore and multiple dashes.
+      def name_component
+        expression(alpha_numeric, optional(repeated(separator, alpha_numeric)))
+      end
+
+      # domainNameComponent restricts the registry domain component of a
+      # repository name to start with a component as defined by DomainRegexp.
+      def domain_name_component
+        "(?:[a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])"
+      end
+
+      # ipv6address are enclosed between square brackets and may be represented
+      # in many ways, see rfc5952. Only IPv6 in compressed or uncompressed format
+      # are allowed, IPv6 zone identifiers (rfc6874) or Special addresses such as
+      # IPv4-Mapped are deliberately excluded.
+      def ipv6address
+        expression(literal("["), "(?:[a-fA-F0-9:]+)", literal("]"))
+      end
+
+      # domainName defines the structure of potential domain components
+      # that may be part of image names. This is purposely a subset of what is
+      # allowed by DNS to ensure backwards compatibility with Docker image
+      # names. This includes IPv4 addresses on decimal format.
+      def domain_name
+        expression(domain_name_component, optional(repeated(literal("."), domain_name_component)))
+      end
+
+      # host defines the structure of potential domains based on the URI
+      # Host subcomponent on rfc3986. It may be a subset of DNS domain name,
+      # or an IPv4 address in decimal format, or an IPv6 address between square
+      # brackets (excluding zone identifiers as defined by rfc6874 or special
+      # addresses such as IPv4-Mapped).
+      def host
+        "(?:#{domain_name}|#{ipv6address})"
+      end
+
+      # allowed by the URI Host subcomponent on rfc3986 to ensure backwards
+      # compatibility with Docker image names.
+      def domain
+        expression(host, optional(literal(":"), "[0-9]+"))
+      end
+
+      # DomainRegexp defines the structure of potential domain components that may be part of image names.
+      # This is purposely a subset of what is allowed by DNS to ensure backwards compatibility with Docker image names.
+      def domain_regexp
+        @domain_regexp ||= ::Regexp.new(domain)
+      end
+
+      def tag
+        "[\\w][\\w.-]{0,127}"
+      end
+
+      # TagRegexp matches valid tag names
+      def tag_regexp
+        ::Regexp.new(tag)
+      end
+
+      def anchored_tag
+        anchored(tag)
+      end
+
+      # anchoredTagRegexp matches valid tag names, anchored at the start and end of the matched string.
+      def anchored_tag_regexp
+        ::Regexp.new(anchored_tag)
+      end
+
+      def digest_pat
+        "[A-Za-z][A-Za-z0-9]*(?:[-_+.][A-Za-z][A-Za-z0-9]*)*[:][[:xdigit:]]{32,}"
+      end
+
+      # DigestRegexp matches valid digests.
+      def digest_regexp
+        ::Regexp.new(digest_pat)
+      end
+
+      def anchored_digest
+        anchored(digest_pat)
+      end
+
+      # anchoredDigestRegexp matches valid digests, anchored at the start and end of the matched string.
+      def anchored_digest_regexp
+        ::Regexp.new(anchored_digest)
+      end
+
+      def name_pat
+        expression(optional(domain, literal("/")), name_component, optional(repeated(literal("/"), name_component)))
+      end
+
+      # NameRegexp is the format for the name component of references. The
+      # regexp has capturing groups for the domain and name part omitting
+      # the separating forward slash from either.
+      def name_regexp
+        ::Regexp.new(name_pat)
+      end
+
+      def anchored_name
+        anchored(optional(capture(domain), literal("/")), capture(name_component, optional(repeated(literal("/"), name_component))))
+      end
+
+      # anchoredNameRegexp is used to parse a name value, capturing the domain and trailing components.
+      def anchored_name_regexp
+        ::Regexp.new(anchored_name)
+      end
+
+      def reference_pat
+        anchored(capture(name_pat), optional(literal(":"), capture(tag)), optional(literal("@"), capture(digest_pat)))
+      end
+
+      # ReferenceRegexp is the full supported format of a reference. The regexp
+      # is anchored and has capturing groups for name, tag, and digest components.
+      def reference_regexp
+        ::Regexp.new(reference_pat)
+      end
+
+      def identifier
+        "([a-f0-9]{64})"
+      end
+
+      # IdentifierRegexp is the format for string identifier used as a content addressable identifier using sha256.
+      # These identifiers are like digests without the algorithm, since sha256 is used.
+      def identifier_regexp
+        ::Regexp.new(identifier)
+      end
+
+      def short_identifier
+        "([a-f0-9]{6,64})"
+      end
+
+      # ShortIdentifierRegexp is the format used to represent a prefix of an identifier.
+      # A prefix may be used to match a sha256 identifier within a list of trusted identifiers.
+      def short_identifier_regexp
+        ::Regexp.new(short_identifier)
+      end
+
+      def anchored_identifier
+        anchored(identifier)
+      end
+
+      # anchoredIdentifierRegexp is used to check or match an # identifier value, anchored at start and end of string.
+      def anchored_identifier_regexp
+        ::Regexp.new(anchored_identifier)
+      end
+
+      def anchored_short_identifier
+        anchored(short_identifier)
+      end
+
+      # anchoredShortIdentifierRegexp is used to check if a value is a possible identifier prefix, anchored at start and end of string.
+      def anchored_short_identifier_regexp
+        ::Regexp.new(anchored_short_identifier)
+      end
+
+      def anchored_encoded_regexp(type)
+        map = {
+          SHA256: ::Regexp.new("^[a-f0-9]{64}$"),
+          SHA384: ::Regexp.new("^[a-f0-9]{96}$"),
+          SHA512: ::Regexp.new("^[a-f0-9]{128}$")
+        }
+        map[type.to_sym]
+      end
+
+      # literal compiles s into a literal regular expression, escaping any regexp reserved characters.
+      def literal(str)
+        re = ::Regexp.new(::Regexp.quote(str))
+        re.source
+      end
+
+      # expression defines a full expression, where each regular expression must follow the previous.
+      def expression(*res)
+        res.join("")
+      end
+
+      # group wraps the regexp in a non-capturing group.
+      def group(*res)
+        "(?:#{expression(*res)})"
+      end
+
+      # optional wraps the expression in a non-capturing group and makes the production optional.
+      def optional(*res)
+        "#{group(expression(*res))}?"
+      end
+
+      # anchored anchors the regular expression by adding start and end delimiters.
+      def anchored(*res)
+        "^#{expression(*res)}$"
+      end
+
+      # repeated wraps the regexp in a non-capturing group to get one or more matches.
+      def repeated(*res)
+        "#{group(expression(*res))}+"
+      end
+
+      # capture wraps the expression in a capturing group.
+      def capture(*res)
+        "(#{expression(*res)})"
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/ClassLength

data/lib/docker_distribution/repository.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module DockerDistribution
+  class Repository
+    attr_accessor :domain, :path
+
+    def initialize(domain = nil, path = nil)
+      @domain = domain
+      @path = path
+    end
+
+    def name
+      return path if Helpers.empty?(domain)
+
+      [domain, path].join("/")
+    end
+
+    def to_s
+      name
+    end
+
+    def to_h
+      {
+        repository: name,
+        domain: domain,
+        path: path
+      }
+    end
+
+    def familiar
+      Normalize.familiarize_name(self)
+    end
+  end
+end

data/lib/docker_distribution/tagged_reference.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module DockerDistribution
+  class TaggedReference
+    extend ::Forwardable
+    def_delegators :repository, :name, :domain, :path
+
+    attr_accessor :repository, :tag
+
+    def initialize(repository = nil, tag = nil)
+      @repository = repository
+      @tag = tag
+    end
+
+    def to_s
+      [@repository.name, tag].join(":")
+    end
+
+    def to_h
+      {
+        repository: name,
+        domain: domain,
+        path: path,
+        tag: tag
+      }
+    end
+
+    def familiar
+      self.class.new(Normalize.familiarize_name(self), tag)
+    end
+  end
+end

data/lib/docker_distribution/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DockerDistribution
+  VERSION = "0.1.0"
+end

data/lib/docker_distribution.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Grammar
+#
+# reference                       := name [ ":" tag ] [ "@" digest ]
+#	name                            := [domain '/'] path-component ['/' path-component]*
+#	domain                          := host [':' port-number]
+#	host                            := domain-name | IPv4address | \[ IPv6address \]	; rfc3986 appendix-A
+#	domain-name                     := domain-component ['.' domain-component]*
+#	domain-component                := /([a-zA-Z0-9]|[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9])/
+#	port-number                     := /[0-9]+/
+#	path-component                  := alpha-numeric [separator alpha-numeric]*
+# 	alpha-numeric                   := /[a-z0-9]+/
+#	separator                       := /[_.]|__|[-]*/
+#
+#	tag                             := /[\w][\w.-]{0,127}/
+#
+#	digest                          := digest-algorithm ":" digest-hex
+#	digest-algorithm                := digest-algorithm-component [ digest-algorithm-separator digest-algorithm-component ]*
+#	digest-algorithm-separator      := /[+.-_]/
+#	digest-algorithm-component      := /[A-Za-z][A-Za-z0-9]*/
+#	digest-hex                      := /[0-9a-fA-F]{32,}/ ; At least 128 bit digest value
+#
+#	identifier                      := /[a-f0-9]{64}/
+#	short-identifier                := /[a-f0-9]{6,64}/
+
+require "forwardable"
+
+require_relative "docker_distribution/version"
+require_relative "docker_distribution/errors"
+require_relative "docker_distribution/helpers"
+
+require_relative "docker_distribution/digest"
+require_relative "docker_distribution/digest_set"
+
+require_relative "docker_distribution/regexp"
+require_relative "docker_distribution/repository"
+require_relative "docker_distribution/reference"
+require_relative "docker_distribution/tagged_reference"
+require_relative "docker_distribution/canonical_reference"
+require_relative "docker_distribution/digest_reference"
+require_relative "docker_distribution/normalize"
+
+# Package reference provides a general type to represent any way of referencing images within the registry.
+# Its main purpose is to abstract tags and digests (content-addressable hash).
+module DockerDistribution
+end

data/sig/docker_distribution.rbs

@@ -0,0 +1,4 @@
+module DockerDistribution
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end