docker_registry2 1.6.0 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 81a59b8010136692df1083c6a952f8cd1daaa731
-  data.tar.gz: 25f140d4340f8fc8c6c90a3fb9aab39179c1433a
+  metadata.gz: bf424b2e5e3bfbadd28cafdf008e134209cf2c2e
+  data.tar.gz: 66e95afc5c4e76d1122d72c1ee6b6d5a828adfce
 SHA512:
-  metadata.gz: e8d4477daf7c4aa1e03cf4101ca1f6d4e0b3841a34f925461e0af93bdacc34cdde4ee4c0968e6f6d6800f2b2164e3a0d7d6ae736e43e0eeb3d04f289c23eed73
-  data.tar.gz: ea63c5390cfd87e0746cc2f27acfc640602fe91bf75af982f5db2361c1a36b4ea8706e0ed4ed8da0ed3f4b1ab53a3c8777a7c47312a7925c0dd25ac0d93dfe2d
+  metadata.gz: 3105398ddc358110e1b38b5c6ce432b65fc4f8dd3c7a1bbfb44bbf5b7d15d597464821c1733dfaa19fdee157e54ee666a9cb3302565f554e73e87d0669796fc9
+  data.tar.gz: 7c9f6d4a74331433957993a54daa4fb189b813e2a2919c940bbd73aa476336026c2a7879100d55bdb5ea44fc4d3457a17f51889439e353bdb5da04624f79a163

data/README.md

@@ -117,17 +117,25 @@ The following exceptions are thrown:
 
 #### tags
 ````ruby
-results = reg.tags("mylibs",withHashes)
+results = reg.tags("mylibs",count=nil,last="",withHashes=false)
 ````
 
-Returns all known tags for the repository precisely named `"mylibs"`. If `withHashes` is present and set to `true`, also will return all of the hashes for each tag. See below. Note that retrieving the hashes is an expensive operations, as it requires a separate `HEAD` for each tag. This is why the default is `false`.
+Returns all known tags for the repository precisely named `"mylibs"`.
+
+Arguments:
+
+* `repository`: name of the repository to return, e.g. "mylibs" above. Relative to the registry to which you connected. REQUIRED.
+* `count`: how many records to return, if the registry supports pagination. Default is not to limit. The behaviour changes by registry implementation. See the section on pagination below. OPTIONAL.
+* `last`: the last record returned, if using pagination. See the section on pagination below. OPTIONAL.
+* `withHashes`: return the hash of the manifest for each tag. Note that retrieving the hashes is an expensive operations, as it requires a separate `HEAD` for each tag. This is why the default is `false`. OPTIONAL.
 
 Returns an object with the following key value pairs:
  array of objects, each of which has the following key/value pairs:
 
-* `name`: full name of repository, e.g. `redis` or `user/redis`
-* `tags`: array of strings, each of which is a tag for ths given repository
+* `name`: full name of repository, e.g. `redis` or `user/redis`.
+* `tags`: array of strings, each of which is a tag for ths given repository.
 * `hashes`: object, keys of which are the tag name, and values of which are the hash. Only provided if `withHashes` is true.
+* `last`: the last entry returned, to be used for pagination, only returned if the results have been paginated by the server.
 
 Other fields may be added later. Do *not* assume those are the only fields.
 
@@ -157,8 +165,60 @@ 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
 
+##### pagination
+
+Some regstries support pagination for tags per [this standard](https://docs.docker.com/registry/spec/api/#listing-image-tags). If the registry supports pagination, you have several options:
+
+* Ignore it, and simply get back whatever the max number o tags the registry returns in whatever order. In many cases, this will work. `tags("repo")`
+* Set an arbitrarily high number. Note that this may not work, as the registry may implement a limit below your cap. `tags("repo", 5000)`
+* Work with pagination.
+
+To work with pagination, after each result set, you keep getting a new result set until there are no more. In this case, with each request, the `tags()` results will tell you what the key of the last one was returned. You pass that into the next call, so it knows where to start for the next set of results. You also can choose to limit the `count`, or just accept whatever default the registry has set.
+
+For example, let us assume that the registry has 26 tags, from `"a"` to `"z"`, and that it returns 3 tags with each call by default. Your first call:
+
+```ruby
+res = tags("repo")
+# or, to limit to 3 explicilty
+res = tags("repo")
+```
+
+Your results will be:
+
+```ruby
+{
+        "name" => "repo",
+        "tags" => ["a","b","c"],
+	"last" => "c"
+}
+```
 
+Note that it returned 3, either because that was the registry default or you explicitly limited to 3 results. It also told you that the last tag was `"c"`. You now can pass that on to the next request.
 
+```ruby
+res = tags("repo",nil,"c")
+# or, to limit to 3 explicitly
+res = tags("repo",3,"c")
+```
+
+The results will be:
+
+```ruby
+{
+        "name" => "repo",
+        "tags" => ["d","e","f"]
+        "last" => "f"
+}
+```
+
+Repeat until you have all of the results. The last one has no more pagination, and so the results will be without a `"last"` field:
+
+```ruby
+{
+        "name" => "repo",
+        "tags" => ["x","y","z"]
+}
+```
 
 
 #### manifest

data/lib/registry/registry.rb

@@ -49,15 +49,21 @@ class DockerRegistry2::Registry
     return repos
   end
 
-  def tags(repo,count=100,last="",withHashes = false)
+  def tags(repo,count=nil,last="",withHashes = false)
     #create query params
     params = []
     if last != ""
       params.push(["last",last])
     end
-    params.push(["n",count])
+    if count != nil
+      params.push(["n",count])
+    end
 
-    response = doget "/v2/#{repo}/tags/list?#{URI.encode_www_form(params)}"
+    query_vars = ""
+    if params.length > 0
+      query_vars = "?#{URI.encode_www_form(params)}"
+    end
+    response = doget "/v2/#{repo}/tags/list#{query_vars}"
     # parse the response
     resp = JSON.parse response
     # parse out next page link if necessary

data/lib/registry/version.rb

@@ -1,3 +1,3 @@
 module DockerRegistry2
-  VERSION = '1.6.0'
+  VERSION = '1.6.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docker_registry2
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.6.1
 platform: ruby
 authors:
 - Avi Deitcher https://github.com/deitch
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-06-27 00:00:00.000000000 Z
+date: 2019-06-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler