docker_registry2 1.6.2 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e35187dcf21e13516ef819f08d95f23f1f398ac8f17b5737dfb829b33d89c431
-  data.tar.gz: b5ab54fb96709a4de8c1a32d1c2323bb3b7310b38eaba7978cbfa413b7e64751
+  metadata.gz: 6878db7e5b30918ddcb5417f6092ae01a35ca6037c9d0203217450198fe831d0
+  data.tar.gz: 207bc12bacd847a6573b322cdee58c3fe33bb85db1c831458cca7e942f8232bd
 SHA512:
-  metadata.gz: d57a17a464cdec565613284bd1168c83ee4e58d23dcb7b3773696f5659c9913d368b1592ad50a4e8778045cde6c36e88185d935ceadabdc86b4c2e34cbc3a6e0
-  data.tar.gz: 1fbca82a8c84baac59370e7a68dc97211127e15a3b572a657b82dee16746685d166f80470cb40def9a04a1d8b35c688013b7e6e085bd565b8d7b4ae9a4a51a70
+  metadata.gz: fe5ef7fec4e79b5290bafce6837738410e41c0dd50bdeab49ce373bc256338ca0c6300d28417e13cf686d813e71b1ff44315afb80196f19dd84f7b4b870e7008
+  data.tar.gz: aad38ab842512d57ed2816f3823d2fb77ab8cbf56ef48c29df476d630881dadaf8de0c71fd543a5c0d5ddf4625baadc38f4a2b860f39d712650d2ba574153d81

data/README.md

@@ -55,6 +55,13 @@ opts = { open_timeout: 2, read_timeout: 5 }
 reg = DockerRegistry2.connect("https://my.registy.corp.com", opts)
 ```
 
+Your may pass extra options for RestClient::Request.execute through `http_options` :
+
+```ruby
+opts = { http_options: { proxy: 'http://proxy.example.com:8080/' } }
+reg = DockerRegistry2.connect("https://my.registy.corp.com", opts)
+```
+
 You can connect anonymously or with credentials:
 
 #### Anonymous
@@ -222,13 +229,13 @@ Repeat until you have all of the results. The last one has no more pagination, a
 
 
 #### manifest
+
 ````ruby
 manifest = reg.manifest("namespace/repo","2.5.6")
 ````
 
 Returns the manifest for the given tag of the given repository. For the format and syntax of the manifest, see the [registry API](https://github.com/docker/distribution/blob/master/docs/spec/api.md) and the [manifest issue](https://github.com/docker/docker/issues/8093).
 
-
 If the given repository and/or tag is not found, return an empty object `{}`.
 
 The following exceptions are thrown:
@@ -236,6 +243,61 @@ The following exceptions are thrown:
 * `RegistryAuthenticationException`: username and password are invalid
 * `RegistryAuthorizationException`: registry does not support tags using the given credentials, probably because the repository is private and the credentials provided do not have access
 
+The manifest, of course, is requested via http `GET`. While the returned manifest is an object parsed from the JSON of the manifest _body_, sometimes the http _headers_ are valuable as well. Thus the returned manifest object has a method `headers`, which returns the http headers from the request.
+
+```ruby
+manifest = reg.manifest("namespace/repo","2.5.6")
+manifest.headers
+```
+
+#### blob
+
+````ruby
+> blob_digest = "sha256:87fbbe5ed7a499baa6603cd81502cfe0f26d0e9fe8b2feca8bc4ab04cd87c01e"
+> blob = reg.blob("namespace/repo", blob_digest, '/path/to/blob')
+````
+
+Returns the blob for the given digest in given repository. Blobs can vary in size, so a file path may be passed to stream the data. This is the recommended approach for downloading layer blobs due to their large size. For the format and syntax of the blob, see the [registry API](https://docs.docker.com/registry/spec/api/#blob) 
+
+The following exceptions are thrown:
+
+* `RegistryAuthenticationException`: username and password are invalid
+* `RegistryAuthorizationException`: registry does not support tags using the given 
+* `NotFound`: Either the repo or blob cannot be found
+
+
+Alternatively, if omitted the raw blob will be returned:
+````ruby
+> blob = reg.blob("namespace/repo", "sha256:437f2acdb882407ad515c936c6f1cd9adbbb1340c8b271797723464c6ac71f9b")
+> blob.headers
+=> {:date=>"Sun, 01 Dec 2019 15:48:57 GMT", :content_type=>"application/octet-stream", :content_length=>"7016", :connection=>"keep-alive", :set_cookie=>["__cfduid=d7b1e0e004daa8e1ffd2c8c80c70959e51575215337; expires=Tue, 31-Dec-19 15:48:57 GMT; path=/; domain=.production.cloudflare.docker.com; HttpOnly; Secure"], :cf_ray=>"53e6355468b3e593-MAN", :cf_cache_status=>"HIT", :cache_control=>"public, max-age=14400", :accept_ranges=>"bytes", :age=>"990327", :etag=>"\"574739ff4eca4fe0b24bcac899909659\"", :expires=>"Sun, 01 Dec 2019 19:48:57 GMT", :last_modified=>"Wed, 20 Nov 2019 01:18:29 GMT", :vary=>"Accept-Encoding", :expect_ct=>"max-age=604800, report-uri=\"https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct\"", :x_amz_id_2=>"nL/phq2BUYjsGIwrSHh8QMqsnGNbjDlDjFjunI7qOqpnfR/3WAbVnKcobw4d23+nAx3lAED6Vbw=", :x_amz_request_id=>"E6B231599CAE0074", :x_amz_version_id=>"hTvrmlz_ARV25b0tY5NVrEJNlv7._2J3", :server=>"cloudflare"}
+> blob.body
+=> "<raw body>"
+````
+
+The mediaType on the manifest paired with the digest determines the blob format, so in the case of an image blob (`application/vnd.docker.distribution.manifest.v2+json`) the body can be deserialized from JSON
+
+```ruby
+> manifest = reg.manifest "library/nginx", "1.17.6-alpine"
+=> {"schemaVersion"=>2, "mediaType"=>"application/vnd.docker.distribution.manifest.v2+json", "config"=>{"mediaType"=>"application/vnd.docker.container.image.v1+json", "size"=>7016, "digest"=>"sha256:a624d888d69ffdc185ed3b9c9c0645e8eaaac843ce59e89f1fbe45b0581e4ef6"}, "layers"=>[{"mediaType"=>"application/vnd.docker.image.rootfs.diff.tar.gzip", "size"=>2787134, "digest"=>"sha256:89d9c30c1d48bac627e5c6cb0d1ed1eec28e7dbdfbcc04712e4c79c0f83faf17"}, {"mediaType"=>"application/vnd.docker.image.rootfs.diff.tar.gzip", "size"=>5984561, "digest"=>"sha256:24f1c4f0b2f40c236ec9c306bd841778f30db9e6e7f067512732147ae7c11b07"}]}
+> image_digest = manifest['config']['digest']
+=> "sha256:a624d888d69ffdc185ed3b9c9c0645e8eaaac843ce59e89f1fbe45b0581e4ef6"
+> raw_blob = reg.blob "library/nginx", image_digest
+=> #<DockerRegistry2::Blob:0x007fd9bf8f2e10 ...>
+> image_blob = JSON.parse(raw_blob.body)
+=> {...}
+> image_blob['architecture']
+=> "amd64"
+> image_blob['os']
+=> "linux"
+> image_blob['docker_version']
+=> "18.06.1-ce"
+> image_blob['created']
+=> "2019-11-20T01:16:50.939316846Z"
+> image_blob['config']['Labels']
+=> {"maintainer"=>"NGINX Docker Maintainers <docker-maint@nginx.com>"}
+```
+
 #### digest
 ````ruby
 digest = reg.digest("namespace/repo", "2.5.6")

data/lib/docker_registry2.rb

@@ -1,6 +1,8 @@
 require File.dirname(__FILE__) + '/registry/version'
 require File.dirname(__FILE__) + '/registry/registry'
 require File.dirname(__FILE__) + '/registry/exceptions'
+require File.dirname(__FILE__) + '/registry/manifest'
+require File.dirname(__FILE__) + '/registry/blob'
 
 
 module DockerRegistry2

data/lib/registry/blob.rb

@@ -0,0 +1,10 @@
+module DockerRegistry2
+  class Blob
+    attr_reader :body, :headers
+    
+    def initialize(headers, body)
+      @headers = headers
+      @body = body
+    end
+  end
+end

data/lib/registry/manifest.rb

@@ -0,0 +1,9 @@
+module DockerRegistry2
+
+  class Manifest < Hash
+    attr_accessor :body, :headers
+    def initialize
+      super
+    end
+  end
+end

data/lib/registry/registry.rb

@@ -7,15 +7,19 @@ class DockerRegistry2::Registry
   # @param [Hash] options Client options
   # @option options [#to_s] :user User name for basic authentication
   # @option options [#to_s] :password Password for basic authentication
-  # @option options [#to_s] :open_timeout Time to wait for a connection with a registry
-  # @option options [#to_s] :read_timeout Time to wait for data from a registry
+  # @option options [#to_s] :open_timeout Time to wait for a connection with a registry.
+  #                                       It is ignored if http_options[:open_timeout] is also specified.
+  # @option options [#to_s] :read_timeout Time to wait for data from a registry.
+  #                                       It is ignored if http_options[:read_timeout] is also specified.
+  # @option options [Hash] :http_options Extra options for RestClient::Request.execute.
   def initialize(uri, options = {})
     @uri = URI.parse(uri)
     @base_uri = "#{@uri.scheme}://#{@uri.host}:#{@uri.port}"
     @user = options[:user]
     @password = options[:password]
-    @open_timeout = options[:open_timeout] || 2
-    @read_timeout = options[:read_timeout] || 5
+    @http_options = options[:http_options] || {}
+    @http_options[:open_timeout] ||= options[:open_timeout] || 2
+    @http_options[:read_timeout] ||= options[:read_timeout] || 5
   end
 
   def doget(url)
@@ -35,7 +39,7 @@ class DockerRegistry2::Registry
   end
 
   def ping
-    response = doget '/v2/'
+    doget '/v2/'
   end
 
   def search(query = '')
@@ -49,33 +53,27 @@ class DockerRegistry2::Registry
     return repos
   end
 
-  def tags(repo,count=nil,last="",withHashes = false)
+  def tags(repo,count=nil,last="",withHashes = false, auto_paginate: false)
     #create query params
     params = []
-    if last != ""
-      params.push(["last",last])
-    end
-    if count != nil
-      params.push(["n",count])
-    end
+    params.push(["last",last]) if last && last != ""
+    params.push(["n",count]) unless count.nil?
 
     query_vars = ""
-    if params.length > 0
-      query_vars = "?#{URI.encode_www_form(params)}"
-    end
+    query_vars = "?#{URI.encode_www_form(params)}" if params.length > 0
+
     response = doget "/v2/#{repo}/tags/list#{query_vars}"
     # parse the response
     resp = JSON.parse response
     # parse out next page link if necessary
-    if response.headers[:link]
-      resp["last"] = last(response.headers[:link])
-    end
+    resp["last"] = last(response.headers[:link]) if response.headers[:link]
+
     # do we include the hashes?
-    if withHashes then
+    if withHashes
       useGet = false
       resp["hashes"] = {}
-      resp["tags"].each {|tag|
-        if useGet then
+      resp["tags"].each do |tag|
+        if useGet
           head = doget "/v2/#{repo}/manifests/#{tag}"
         else
           begin
@@ -87,14 +85,44 @@ class DockerRegistry2::Registry
           end
         end
         resp["hashes"][tag] = head.headers[:docker_content_digest]
-      }
+      end
+    end
+
+    return resp unless auto_paginate
+
+    while (last_tag = resp.delete("last"))
+      additional_tags = tags(repo, count, last_tag, withHashes)
+      resp["last"] = additional_tags["last"]
+      resp["tags"] += additional_tags["tags"]
+      resp["tags"] = resp["tags"].uniq
+      resp["hashes"].merge!(additional_tags["hashes"]) if withHashes
     end
+
     resp
   end
 
   def manifest(repo,tag)
     # first get the manifest
-    JSON.parse doget "/v2/#{repo}/manifests/#{tag}"
+    response = doget "/v2/#{repo}/manifests/#{tag}"
+    parsed = JSON.parse response.body
+    manifest = DockerRegistry2::Manifest[parsed]
+    manifest.body = response.body
+    manifest.headers = response.headers
+    manifest
+  end
+
+  def blob(repo, digest, outpath=nil)
+    blob_url = "/v2/#{repo}/blobs/#{digest}"
+    if outpath.nil? 
+      response = doget(blob_url)
+      DockerRegistry2::Blob.new(response.headers, response.body)
+    else
+      File.open(outpath, 'w') do |fd|
+        doreq('get', blob_url, fd)
+      end 
+
+      outpath
+    end
   end
 
   def digest(repo, tag)
@@ -138,11 +166,7 @@ class DockerRegistry2::Registry
       next if File.file? layer_file
       # download layer
       # puts "getting layer (v2) #{layer['digest']}"
-      File.open(layer_file, 'w') do |fd|
-        doreq('get',
-              "/v2/#{repo}/blobs/#{layer['digest']}",
-              fd)
-      end
+      blob(repo, layer['digest'], layer_file)
       layer_file
     end
   end
@@ -159,11 +183,7 @@ class DockerRegistry2::Registry
       next if File.file? layer_file
       # download layer
       # puts "getting layer (v1) #{layer['blobSum']}"
-      File.open(layer_file, 'w') do |fd|
-        doreq('get',
-              "/v2/#{repo}/blobs/#{layer['blobSum']}",
-              fd)
-      end
+      blob(repo, layer['blobSum'], layer_file)
       # return layer file
       layer_file
     end
@@ -228,15 +248,13 @@ class DockerRegistry2::Registry
             stream.write chunk
           end
         }
-        response = RestClient::Request.execute(
+        response = RestClient::Request.execute(@http_options.merge(
           method: type,
           url: @base_uri+url,
           headers: headers(payload: payload),
           block_response: block,
-          open_timeout: @open_timeout,
-          read_timeout: @read_timeout,
           payload: payload
-        )
+        ))
       rescue SocketError
         raise DockerRegistry2::RegistryUnknownException
       rescue RestClient::NotFound => error
@@ -263,17 +281,15 @@ class DockerRegistry2::Registry
             stream.write chunk
           end
         }
-        response = RestClient::Request.execute(
+        response = RestClient::Request.execute(@http_options.merge(
           method: type,
           url: @base_uri+url,
           user: @user,
           password: @password,
           headers: headers(payload: payload),
           block_response: block,
-          open_timeout: @open_timeout,
-          read_timeout: @read_timeout,
           payload: payload
-        )
+        ))
       rescue SocketError
         raise DockerRegistry2::RegistryUnknownException
       rescue RestClient::Unauthorized
@@ -294,15 +310,13 @@ class DockerRegistry2::Registry
             stream.write chunk
           end
         }
-        response = RestClient::Request.execute(
+        response = RestClient::Request.execute(@http_options.merge(
           method: type,
           url: @base_uri+url,
           headers: headers(payload: payload, bearer_token: token),
           block_response: block,
-          open_timeout: @open_timeout,
-          read_timeout: @read_timeout,
           payload: payload
-        )
+        ))
       rescue SocketError
         raise DockerRegistry2::RegistryUnknownException
       rescue RestClient::Unauthorized
@@ -326,14 +340,12 @@ class DockerRegistry2::Registry
       # authenticate against the realm
       uri = URI.parse(target[:realm])
       begin
-        response = RestClient::Request.execute(
+        response = RestClient::Request.execute(@http_options.merge(
           method: :get,
           url: uri.to_s, headers: {params: target[:params]},
           user: @user,
           password: @password,
-          open_timeout: @open_timeout,
-          read_timeout: @read_timeout
-        )
+        ))
       rescue RestClient::Unauthorized, RestClient::Forbidden
         # bad authentication
         raise DockerRegistry2::RegistryAuthenticationException
@@ -362,7 +374,7 @@ class DockerRegistry2::Registry
     def headers(payload: nil, bearer_token: nil)
       headers={}
       headers['Authorization']="Bearer #{bearer_token}" unless bearer_token.nil?
-      headers['Accept']='application/vnd.docker.distribution.manifest.v2+json' if payload.nil?
+      headers['Accept']='application/vnd.docker.distribution.manifest.v2+json, application/json' if payload.nil?
       headers['Content-Type']='application/vnd.docker.distribution.manifest.v2+json' unless payload.nil?
 
       headers

data/lib/registry/version.rb

@@ -1,3 +1,3 @@
 module DockerRegistry2
-  VERSION = '1.6.2'
+  VERSION = '1.10.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docker_registry2
 version: !ruby/object:Gem::Version
-  version: 1.6.2
+  version: 1.10.0
 platform: ruby
 authors:
 - Avi Deitcher https://github.com/deitch
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-06-28 00:00:00.000000000 Z
+date: 2020-11-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -78,7 +78,9 @@ files:
 - README.md
 - docker_registry2.gemspec
 - lib/docker_registry2.rb
+- lib/registry/blob.rb
 - lib/registry/exceptions.rb
+- lib/registry/manifest.rb
 - lib/registry/registry.rb
 - lib/registry/version.rb
 homepage: https://github.com/deitch/docker_registry2
@@ -100,8 +102,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.3
+rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
 summary: Docker v2 registry HTTP API client