docker_distribution 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc6f4c883560213fd738e4f724ec846985b89a54daeae499d302320ad17e91c1
-  data.tar.gz: 6a1cb6d5549de71c1882db7752df770f79acbe733a9416a2e956e4b74cb98998
+  metadata.gz: df29a563df5c3905dee99b74d6b1dfef79175c73a27ad016e553391cfa026ed7
+  data.tar.gz: c4bcaf72d7525f20042b5cc91a22e6f8ac18692cd31f7744dfca6d0012929201
 SHA512:
-  metadata.gz: 8bfe97167c18b19eca3abe3245bf864ce1f1ae745e4df99f63e5bb0d1b45db6f14ee6ec3519c8566a343c1f3f9e3737867b146842464db093eaa915f20779ccb
-  data.tar.gz: 43706fbd4f9afead0036f4b3871f41e817b79824b7295a489e61bda5c0e0038d5bbe94c8ad633b536b41b88a8ab55876912515b45b7402444d716d98b7951fc8
+  metadata.gz: 6ab3c059d0149abaf42364f194b37923e33316fae3e5395991f8ecf9a462ac69245387cea1dcbafa58ad043e05202cca32cea3e580e67f1476a1b67b6fae6d3c
+  data.tar.gz: dce9c44d2c73b1b5982d1909de563227c21f8e2d499916f3d29cfb28d6c8a0796c189107131601ae7d0a6217d5bb4a0294266d9b3cce160ac917cd1e2b77d6b0

data/README.md

@@ -0,0 +1,108 @@
+# DockerDistribution
+
+Implementation of OCI Distribution Specification on Ruby. Implementation copied from Golang version which used in Docker Cli and Kubectl Cli.
+
+[OCI Distribution Specification](https://github.com/opencontainers/distribution-spec)
+
+[Golang implementation](https://github.com/docker/distribution/tree/main/reference)
+
+
+## Installation
+
+```
+gem install docker_distribution
+```
+
+## Usage
+
+### Reference
+* Add description from implementation comments
+```
+DockerDistribution::Reference.parse(image_name)
+DockerDistribution::Reference.parse_named(str)
+DockerDistribution::Reference.with_name(name)
+DockerDistribution::Reference.with_tag(named, tag)
+DockerDistribution::Reference.with_digest(named, digest)
+DockerDistribution::Reference.split_domain(name)
+DockerDistribution::Reference.split_hostname(named)
+```
+
+### Normalize
+* Add description from implementation comments
+```
+DockerDistribution::Normalize.parse_normalized_named(str)
+DockerDistribution::Normalize.parse_docker_ref(ref)
+DockerDistribution::Normalize.split_docker_domain(name)
+DockerDistribution::Normalize.familiarize_name(repo)
+DockerDistribution::Normalize.tag_name_only(ref)
+DockerDistribution::Normalize.parse_any_reference(ref)
+DockerDistribution::Normalize.parse_any_reference_with_set(ref, digest_set)
+```
+
+### Regexp
+* Add description from implementation comments
+```
+DockerDistribution::Regexp.alpha_numeric
+DockerDistribution::Regexp.separator
+DockerDistribution::Regexp.name_component
+DockerDistribution::Regexp.domain_name_component
+DockerDistribution::Regexp.ipv6address
+DockerDistribution::Regexp.domain_name
+DockerDistribution::Regexp.host
+DockerDistribution::Regexp.domain
+DockerDistribution::Regexp.domain_regexp
+DockerDistribution::Regexp.tag
+DockerDistribution::Regexp.tag_regexp
+DockerDistribution::Regexp.anchored_tag
+DockerDistribution::Regexp.anchored_tag_regexp
+DockerDistribution::Regexp.digest_pat
+DockerDistribution::Regexp.digest_regexp
+DockerDistribution::Regexp.anchored_digest
+DockerDistribution::Regexp.anchored_digest_regexp
+DockerDistribution::Regexp.name_pat
+DockerDistribution::Regexp.name_regexp
+DockerDistribution::Regexp.anchored_name
+DockerDistribution::Regexp.anchored_name_regexp
+DockerDistribution::Regexp.reference_pat
+DockerDistribution::Regexp.reference_regexp
+DockerDistribution::Regexp.identifier
+DockerDistribution::Regexp.identifier_regexp
+DockerDistribution::Regexp.short_identifier
+DockerDistribution::Regexp.short_identifier_regexp
+DockerDistribution::Regexp.anchored_identifier
+DockerDistribution::Regexp.anchored_identifier_regexp
+DockerDistribution::Regexp.anchored_short_identifier
+DockerDistribution::Regexp.anchored_short_identifier_regexp
+```
+
+### Digest
+* Add description from implementation comments
+```
+DockerDistribution::Digest.parse(digest_string)
+```
+
+## Examples
+...
+
+More examples in tests
+
+## Development
+```
+docker-compose build gem
+docker-compose run --rm gem bash
+bundle install
+...
+make test
+make lint
+```
+
+## Release
+1. [Read this](https://guides.rubygems.org/publishing/)
+2. Make sure you logged in into Rubygems
+3. Update version accoring [semver](https://semver.org/)
+4. `gem build docker_distribution.gemspec`
+5. `gem push docker_distribution-[version].gem`
+
+## Todo
+- Finish readme description / examples / installation guide / development guide / examples / ruby version support
+- Add correct workflow in github to run tests and linters in docker env

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/docker_distribution/canonical_reference.rb

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

data/lib/docker_distribution/digest.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module DockerDistribution
+  class Digest
+    DEFAULT_ALGORITHM = "sha256"
+    attr_accessor :digest_string, :encoded, :algorithm_type
+
+    #  Parse parses digest_string and returns the validated digest object. An error will
+    #  be raised if the format is invalid.
+    def self.parse!(digest_string)
+      dgst = new(digest_string)
+      dgst.validate!
+      dgst
+    end
+
+    def initialize(digest_string)
+      @digest_string = digest_string
+      @algorithm_type, @encoded = digest_string.index(":") ? digest_string.split(":") : [DEFAULT_ALGORITHM, digest_string]
+    end
+
+    def digest
+      [algorithm_type, encoded].compact.join(":")
+    end
+
+    def to_s
+      digest
+    end
+
+    # rubocop:disable Metrics/AbcSize
+    def validate!
+      index = digest_string.index(":")
+      raise DigestInvalidFormat if index.nil? || index + 1 == digest_string.length
+
+      raise DigestInvalidLength if algorithm.block_length != encoded.length
+
+      return true if Regexp.anchored_encoded_regexp(algorithm_type.upcase).match?(encoded)
+
+      raise DigestInvalidFormat
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    def algorithm
+      send(:Digest, algorithm_type.upcase).new
+    rescue NameError, LoadError
+      raise DigestUnsupported
+    end
+  end
+end

data/lib/docker_distribution/digest_reference.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module DockerDistribution
+  class DigestReference
+    attr_accessor :digest
+
+    def initialize(digest)
+      @digest = digest
+    end
+
+    def to_s
+      digest
+    end
+
+    def to_h
+      { digest: digest }
+    end
+  end
+end

data/lib/docker_distribution/digest_set.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module DockerDistribution
+  class DigestSet
+    attr_writer :entries
+
+    def initialize(digest_strings)
+      @entries = digest_strings.map { |digest_string| Digest.new(digest_string) }
+    end
+
+    def entries
+      @entries ||= []
+    end
+
+    def add(digest_string)
+      @entries << Digest.new(digest_string)
+    end
+
+    def lookup!(digest_string)
+      raise DigestNotFound if entries.length.zero?
+
+      search_func, encoded, alg = parse!(digest_string)
+
+      entry = search(search_func, encoded, alg)
+      entry.digest
+    end
+
+    private
+
+    # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+    def parse!(digest_string)
+      dgst = Digest.parse!(digest_string)
+      alg = dgst.algorithm_type
+      encoded = dgst.encoded
+      search_func = lambda do |i|
+        return entries[i].algorithm_type >= dgst.algorithm_type if entries[i].encoded == encoded
+
+        entries[i].encoded >= encoded
+      end
+      [search_func, encoded, alg]
+    rescue DigestInvalidFormat
+      alg = Digest::DEFAULT_ALGORITHM
+      encoded = digest_string
+      search_func = lambda do |i|
+        entries[i].encoded >= digest_string
+      end
+      [search_func, encoded, alg]
+    end
+    # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
+
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    def search(search_func, encoded, alg)
+      idx = entries.each_with_index.filter_map { |_el, i| i if search_func.call(i) }.first || entries.length
+      raise DigestNotFound if idx == entries.length || !check_short_match(entries[idx].algorithm_type, entries[idx].encoded, alg.to_s,
+                                                                          encoded)
+      return entries[idx] if entries[idx].algorithm_type == alg && entries[idx].encoded == encoded
+
+      raise DigestAmbiguous if idx + 1 < entries.length && check_short_match(entries[idx + 1].algorithm_type, entries[idx + 1].encoded,
+                                                                             alg.to_s, encoded)
+
+      entries[idx]
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+    # rubocop:disable Metrics/CyclomaticComplexity
+    def check_short_match(alg, encoded, short_alg, short_encoded)
+      if encoded.length == short_encoded.length
+        return false if encoded != short_encoded
+
+        return false if short_alg.length.positive? && alg != short_alg
+      end
+
+      return false unless encoded.start_with?(short_encoded)
+
+      return false if short_alg.length.positive? && alg != short_alg
+
+      true
+    end
+    # rubocop:enable Metrics/CyclomaticComplexity
+  end
+end

data/lib/docker_distribution/errors.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module DockerDistribution
+  # NameEmpty is raised for empty, invalid repository names.
+  class NameEmpty < StandardError; end
+  # ReferenceInvalidFormat represents an error while trying to parse a string as a reference.
+  class ReferenceInvalidFormat < StandardError; end
+  # TagInvalidFormat represents an error while trying to parse a string as a tag.
+  class TagInvalidFormat < StandardError; end
+  # DigestError raised when something wrong with Digest
+  class DigestError < StandardError; end
+  # DigestInvalidLength raised when digest has invalid length.
+  class DigestInvalidLength < DigestError; end
+  # DigestInvalidFormat raised when digest format invalid.
+  class DigestInvalidFormat < DigestError; end
+  # DigestUnsupported raised when the digest algorithm is unsupported.
+  class DigestUnsupported < DigestError; end
+  # DigestNotFound raised when the digest set not found
+  class DigestNotFound < DigestError; end
+  # DigestAmbiguous raised when the digest set has two same digests
+  class DigestAmbiguous < DigestError; end
+  #  NameContainsUppercase is raised for invalid repository names that contain uppercase characters.
+  class NameContainsUppercase < StandardError; end
+  # NameTooLong is raised when a repository name is longer than 255 symbols.
+  class NameTooLong < StandardError; end
+  # NameNotCanonical is raised when a name is not canonical.
+  class NameNotCanonical < StandardError; end
+  # # ParseNormalizedNamedError is raised when a parse normalized error failed
+  class ParseNormalizedNamedError < StandardError; end
+end

data/lib/docker_distribution/helpers.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module DockerDistribution
+  class Helpers
+    class << self
+      def familiar_name(named)
+        return named.familiar.name if named.respond_to?(:familiar)
+
+        named.name
+      end
+
+      def familiar_string(named)
+        return named.familiar.to_s if named.respond_to?(:familiar)
+
+        named.to_s
+      end
+
+      def familiar_match(pattern, ref)
+        string_match = File.fnmatch(pattern, familiar_string(ref), File::FNM_PATHNAME)
+        name_match = File.fnmatch(pattern, familiar_name(ref), File::FNM_PATHNAME)
+
+        string_match || name_match
+      end
+
+      def tagged?(ref)
+        ref.respond_to?(:tag)
+      end
+
+      def canonical?(ref)
+        ref.respond_to?(:digest)
+      end
+
+      def named?(ref)
+        ref.respond_to?(:name)
+      end
+
+      def familiar?(ref)
+        ref.respond_to?(:familiar)
+      end
+
+      def name_only?(ref)
+        named?(ref) && !tagged?(ref) && !canonical?(ref)
+      end
+
+      def normalized_named?(ref)
+        named?(ref) && familiar?(ref)
+      end
+
+      def from(str, index)
+        str[index..]
+      end
+
+      def to(str, index)
+        str[0...index]
+      end
+
+      def empty?(object)
+        object == "" || object.nil?
+      end
+    end
+  end
+end

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, 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, 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, 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, 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 zero or more matches.
+      def repeated(*res)
+        group("#{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.2"
+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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docker_distribution
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Artem Petrov
@@ -44,7 +44,22 @@ email:
 executables: []
 extensions: []
 extra_rdoc_files: []
-files: []
+files:
+- README.md
+- Rakefile
+- lib/docker_distribution.rb
+- lib/docker_distribution/canonical_reference.rb
+- lib/docker_distribution/digest.rb
+- lib/docker_distribution/digest_reference.rb
+- lib/docker_distribution/digest_set.rb
+- lib/docker_distribution/errors.rb
+- lib/docker_distribution/helpers.rb
+- lib/docker_distribution/normalize.rb
+- lib/docker_distribution/reference.rb
+- lib/docker_distribution/regexp.rb
+- lib/docker_distribution/repository.rb
+- lib/docker_distribution/tagged_reference.rb
+- lib/docker_distribution/version.rb
 homepage: https://github.com/artempartos/docker_distribution
 licenses:
 - MIT