dockerapi 0.14.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac123f7f5ed500758fd1bb2a9f214495e71c6848517662eae15b92dfa00387aa
-  data.tar.gz: 270f7a7e14d43f73c402191f11ebf9233aa8b7e2c2e314ac3eeb2875487c5120
+  metadata.gz: 2edd0e23baece7608d646b30f453476e3badd792497234ef2ff91e639e234ac2
+  data.tar.gz: deba1315765257880eec881db91c4e71f286dc43f6e8f9e209b9f5ac551d864d
 SHA512:
-  metadata.gz: 878a7c0a146bc6657909151ff0e866c1b9cc93f1dc57ed6c7d0e91b87063e41496af294d1f1e7318b11b0ba3eaf03823e5e081b664b4c3bdd326d4298aed6c65
-  data.tar.gz: fee3d36fd9de8619fc27c588c1285c9acd6ca20a3a6ce1f9fd2ea67c807c74d90ae1a0b531ec233a227ccfd4655056e0c33e6605fa9a31040f6984ca2e3a6798
+  metadata.gz: aaaceb91eb304a1a9be2de7e5562a0744eab641b066fdc0e7aebe5a9b8b22f5e6d5710676897099190bbb705baa8ba269641d5aaddc53086f145c1f585b30681
+  data.tar.gz: 6e46d59caa6f4069dbd17cd5a784ac71fb119af9b0a846e282ce2ed140c00a564c339a26aa359667079472f41c785eb769ae8bbf1a3924420c6b247aad1ddfec

data/.github/workflows/ruby.yml

@@ -0,0 +1,67 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Ruby
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+    # uses: ruby/setup-ruby@v1
+      uses: ruby/setup-ruby@21351ecc0a7c196081abca5dc55b08f085efe09a
+      with:
+        ruby-version: 2.6
+    - name: Install Docker
+      run: curl https://get.docker.com | sh
+    - name: Install dependencies
+      run: |
+        bin/setup 
+        sudo bin/setup
+    - name: Test misc
+      run: rspec spec/misc/*.rb
+    - name: Test Image
+      run: rspec spec/endpoints/image_spec.rb:1
+    - name: Test Image authentication
+      run: rspec spec/endpoints/image_spec.rb:194
+      continue-on-error: true
+    - name: Test Container
+      run: rspec spec/endpoints/container_spec.rb
+    - name: Test Volume
+      run: rspec spec/endpoints/volume_spec.rb
+    - name: Test Network
+      run: rspec spec/endpoints/network_spec.rb
+    - name: Test System
+      run: rspec spec/endpoints/system_spec.rb
+    - name: Test Exec
+      run: rspec spec/endpoints/exec_spec.rb
+    - name: Test Swarm
+      run: rspec spec/endpoints/swarm_spec.rb
+    - name: Test Node
+      run: rspec spec/endpoints/node_spec.rb
+    - name: Test Service
+      run: rspec spec/endpoints/service_spec.rb
+    - name: Test Task
+      run: rspec spec/endpoints/task_spec.rb
+    - name: Test Secret
+      run: rspec spec/endpoints/secret_spec.rb
+    - name: Test Config
+      run: rspec spec/endpoints/config_spec.rb
+    - name: Test Plugin
+      run: rspec spec/endpoints/plugin_spec.rb
+  

data/.gitignore

@@ -9,3 +9,7 @@
 
 # rspec failure tracking
 .rspec_status
+
+resources/registry_authentication/*.key
+resources/registry_authentication/*.crt
+resources/registry_authentication/htpasswd

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+# 0.18.0
+
+Method `Docker::API::Image#distribution` now accepts authentication parameters. Feature introduced in [PR#3](https://github.com/nu12/dockerapi/pull/3)
+
+Contributors: @zarqman
+
+# 0.17.0
+
+New block execution introduced in [PR#1](https://github.com/nu12/dockerapi/pull/1).
+
+Contributors: @zarqman
+
+# 0.16.0
+
+`Docker::API::Task#logs` method can now receive a block to replace standard output to stdout behavior.
+
+Add `auth_encoder` to provide standard implementation for the authentication header where needed.
+
+# 0.15.0
+
+`Docker::API::System#events` and `Docker::API::Exec#start` methods can now receive a block to replace standard output to stdout behavior.
+
+General refactoring and API documentation.
+
 # 0.14.0
 
 Method `Docker::API::Container#archive` is splitted in `#get_archive` and `#put_archive` as per Docker API documentation.

data/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: .
   specs:
-    dockerapi (0.14.0)
-      excon (~> 0.76.0)
+    dockerapi (0.19.0)
+      excon (~> 0.79)
 
 GEM
   remote: https://rubygems.org/
   specs:
     diff-lcs (1.3)
-    excon (0.76.0)
+    excon (0.79.0)
     rake (12.3.3)
     rspec (3.9.0)
       rspec-core (~> 3.9.0)

data/README.md

@@ -21,6 +21,7 @@ Interact with Docker API directly from Ruby code. Comprehensive implementation (
   * [Requests](#requests)
   * [Response](#response)
   * [Error handling](#error-handling)
+  * [Blocks](#blocks)
 * [Development](#development)
 * [Contributing](#contributing)
 * [License](#license)
@@ -31,6 +32,8 @@ Add this line to your application's Gemfile:
 
 ```ruby
 gem 'dockerapi'
+# or
+gem 'dockerapi', github: 'nu12/dockerapi'
 ```
 
 And then execute:
@@ -75,6 +78,7 @@ image.details("image")
 
 # Return image digest and platform information by contacting the registry.
 image.distribution("image")
+image.distribution("image", {username: "janedoe", password: "password"}) # private repository
 
 # History
 image.history("image")
@@ -91,7 +95,7 @@ image.tag("current:tag", repo: "new", tag: "tag")
 # Push image
 image.push("repo:tag") # to dockerhub
 image.push("localhost:5000/repo:tag") # to local registry
-image.push("private/repo", {tag: "tag"}, {username: "janedoe", password: "password"} # to private repository
+image.push("private/repo", {tag: "tag"}, {username: "janedoe", password: "password"}) # to private repository
 
 # Remove image
 image.remove("image")
@@ -531,32 +535,46 @@ response.success?
 
 To completely skip the validation process, add `:skip_validation => true` in the hash to be validated.
 
+### Blocks
+
+Some methods can receive a block to alter the default execution:
+* Docker::API::Container#logs
+* Docker::API::Container#attach
+* Docker::API::Container#stats
+* Docker::API::Container#export
+* Docker::API::Container#get_archive
+* Docker::API::Image#create
+* Docker::API::Image#build
+* Docker::API::Image#export
+* Docker::API::System#event
+* Docker::API::Exec#start
+* Docker::API::Task#logs
+
+Example:
+```ruby
+=> image = Docker::API::Image.new
+
+=> image.create(fromImage: "nginx:alpine") do | chunk, bytes_remaining, bytes_total | 
+        p chunk.to_s 
+    end
+```
+
+The default blocks can be found in `Docker::API::Base`.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-### Road to 1.0.0
-
-| Class | Tests | Implementation | Refactoring |
-|---|---|---|---|
-| Image | Ok | Ok | Ok |
-| Container | Ok | Ok | Ok |
-| Volume | Ok | Ok | 8/14 |
-| Network | Ok | Ok | 8/14 |
-| System | Ok | Ok | 8/14 |
-| Exec | Ok | Ok | 8/14 |
-| Swarm | Ok | Ok | 8/21 |
-| Node | Ok | Ok | 8/21 |
-| Service | Ok | Ok | 8/21 |
-| Task | Ok | Ok | 8/28 |
-| Secret | Ok | Ok | 8/28 |
-| Config | Ok | Ok | 8/28 |
-| Distribution | Ok | Ok | 8/28 |
-| Plugin | Ok | Ok | 8/28 |
-
-Add doc in these files: `base`, `connection`, `error`, `response`, `dockerapi`
+### Release new version
+
+* Update CHANGELOG.
+* Update README as needed.
+* Update version.
+* Run tests.
+* Commit changes.
+* Release / push version to Rubygems & Github.
 
 ## Contributing
 

data/bin/setup

@@ -18,5 +18,13 @@ then
 else
     echo "Running bundle install"
     bundle install
+
+    echo "Creating self-signed certificate to use in tests"
+    openssl req -newkey rsa:2048 -nodes -keyout resources/registry_authentication/registry_auth.key -x509 -days 365 -out resources/registry_authentication/registry_auth.crt -subj "/C=CL/ST=Santiago/L=Santiago/O=dockerapi/OU=dockerapi/CN=localhost"
+
+    echo "Creating htpasswd file to use in tests"
+    docker run --rm --entrypoint htpasswd registry:2.7.0 -Bbn janedoe password > resources/registry_authentication/htpasswd
+    docker image rm registry:2.7.0
     echo "Run this script as root for further configurations"
-fi
+fi
+

data/dockerapi.gemspec

@@ -26,5 +26,5 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency("excon", "~> 0.76.0")
+  spec.add_dependency("excon", "~> 0.79")
 end

data/lib/docker/api/base.rb

@@ -1,24 +1,21 @@
+##
+# Base class to provide general methods, helpers and implementations accross classes.
 class Docker::API::Base
     
-
+    ##
+    # Create new object and sets the validation to happen automatically when method parameters include "params" or "body".
+    #
+    # @param connection [Docker::API::Connection]: Connection to be used.
     def initialize connection = nil
         raise Docker::API::Error.new("Expected connection to be a Docker::API::Connection class") if connection != nil && !connection.is_a?(Docker::API::Connection)
         @connection = connection || Docker::API::Connection.new
-        
-        (self.methods - Object.methods).each do |method|
-            params_index = method(method).parameters.map{|ar| ar[1]}.index(:params)
-            body_index = method(method).parameters.map{|ar| ar[1]}.index(:body)
-
-            define_singleton_method(method) do |*args, &block|
-                validate Docker::API::InvalidParameter, Docker::API::VALID_PARAMS["#{self.class.name}"]["#{method}"], (args[params_index] || {}) if params_index
-                validate Docker::API::InvalidRequestBody, Docker::API::VALID_BODY["#{self.class.name}"]["#{method}"], (args[body_index] || {}) if body_index
-                super(*args,&block)
-            end
-        end
+        set_automated_validation
     end
     
     private
 
+    ##
+    # Output to stdout.
     def default_streamer
         streamer = lambda do |chunk, remaining_bytes, total_bytes|
             p chunk.to_s.encode('UTF-8', invalid: :replace, undef: :replace, replace: '?') if Docker::API::PRINT_TO_STDOUT
@@ -26,6 +23,10 @@ class Docker::API::Base
         streamer
     end
 
+    ##
+    # Write file to disk.
+    #
+    # @param path [String]: Path to the file to be writen.
     def default_writer path
         streamer = lambda do |chunk, remaining_bytes, total_bytes|
             return if "#{chunk}".match(/(No such image)/)
@@ -36,31 +37,74 @@ class Docker::API::Base
         streamer
     end
 
+    ##
+    # Read file from disk.
+    #
+    # @param path [String]: Path to the file to be read.
+    # @param url [String]: Endpoint URL where the file is going to be sent.
+    # @param header [Hash]: Header of the request.
+    # @param &block: Replace the default output to stdout behavior.
     def default_reader path, url, header = {"Content-Type" => "application/x-tar"}, &block
         file = File.open(File.expand_path(path), "r")
-        response = @connection.request(method: :post, path: url , headers: header, request_block: lambda { file.read(Excon.defaults[:chunk_size]).to_s}, response_block: block_given? ? block.call : default_streamer )
+        response = @connection.request(method: :post, path: url , headers: header, request_block: lambda { file.read(Excon.defaults[:chunk_size]).to_s}, response_block: block_given? ? block : default_streamer )
         file.close
         response
     end
 
+    ##
+    # Encode authentication parameters.
+    #
+    # @param authentication [Hash]: Parameters to be encoded.
+    def auth_encoder(authentication)
+        Base64.urlsafe_encode64(authentication.to_json.to_s).chomp
+    end
+
+    ##
+    # Validate a Hash object comparing its keys with a given Array of permitted values. Raise an error if the validation fail.
+    #
+    # @param error [Error]: Error to be raised of the validation fail.
+    # @param permitted [Array]: List of permitted keys.
+    # @param params [Hash]: Hash object to be validated.
     def validate error, permitted, params
         return if params[:skip_validation]
         unpermitted = params.keys.map(&:to_s) - permitted.map(&:to_s)
         raise error.new(permitted, unpermitted) if unpermitted.size > 0
     end
 
-    ## Converts Ruby Hash into query parameters
-    ## In general, the format is key=value
-    ## If value is another Hash, it should keep a json syntax {key:value}
-    def hash_to_params h
+    ##
+    # Convert Ruby Hash into URL query parameters.
+    #
+    # In general, query parameters' format is "key=value", but if "value" is another Hash, it should change to a json syntax {key:value}.
+    #
+    # @param hash [Hash]: Hash object to be converted in a query parameter-like string.
+    def hash_to_params hash
         p = []
-        h.delete_if{ | k, v | k.to_s == "skip_validation" }.each { |k,v| p.push( v.is_a?(Hash) ? "#{k}=#{v.to_json}" : "#{k}=#{v}") }
+        hash.delete_if{ | k, v | k.to_s == "skip_validation" }.each { |k,v| p.push( v.is_a?(Hash) ? "#{k}=#{v.to_json}" : "#{k}=#{v}") }
         p.join("&").gsub(" ","")
     end
 
+    ##
+    # Build an URL string using the base path and a set of parameters.
+    #
+    # @param path [String]: Base URL string.
+    # @param hash [Hash]: Hash object to be appended to the URL as query parameters.
     def build_path path, params = {}
-        p = path.is_a?(Array) ? ([base_path] << path).join("/") : path # TODO: this line to be removed?
-        params.size > 0 ? [p, hash_to_params(params)].join("?") : p
+        params.size > 0 ? [path, hash_to_params(params)].join("?") : path
+    end
+
+    ##
+    # Set the validation to happen automatically when method parameters include "params" or "body".
+    def set_automated_validation
+        (self.methods - Object.methods).each do |method|
+            params_index = method(method).parameters.map{|ar| ar[1]}.index(:params)
+            body_index = method(method).parameters.map{|ar| ar[1]}.index(:body)
+
+            define_singleton_method(method) do |*args, &block|
+                validate Docker::API::InvalidParameter, Docker::API::VALID_PARAMS["#{self.class.name}"]["#{method}"], (args[params_index] || {}) if params_index
+                validate Docker::API::InvalidRequestBody, Docker::API::VALID_BODY["#{self.class.name}"]["#{method}"], (args[body_index] || {}) if body_index
+                super(*args,&block)
+            end
+        end
     end
 
 end

data/lib/docker/api/connection.rb

@@ -1,20 +1,28 @@
-module Docker
-    module API
-        class Connection
-            [:get, :post, :head, :delete, :put].each do | method |
-                define_method(method) { | path | self.request(method: method, path: path) }
-            end
-
-            def request params
-                Docker::API::Response.new(@connection.request(params).data)
-            end
-            
-            def initialize url = nil, params = nil
-                url ||= 'unix:///'
-                params ||= url == 'unix:///' ? {socket: '/var/run/docker.sock'} : {}
-                @connection = Excon.new(url, params)
-            end
+##
+# Connection class.
+class Docker::API::Connection
+    [:get, :post, :head, :delete, :put].each do | method |
+        define_method(method) { | path | self.request(method: method, path: path) }
+    end
 
-        end
+    ##
+    # Call an Excon request and returns a Docker::API::Response object.
+    #
+    # @param params [Hash]: Request parameters.
+    def request params
+        response = Docker::API::Response.new(@connection.request(params).data)
+        p response if Docker::API::PRINT_RESPONSE_TO_STDOUT 
+        response
     end
+    
+    ##
+    # Create an Excon connection.
+    #
+    # @param url [String]: URL for the connection.
+    # @param params [String]: Additional parameters.
+    def initialize url = nil, params = nil
+        return @connection = Excon.new('unix:///', {socket: '/var/run/docker.sock'}) unless url
+        @connection = Excon.new(url, params || {})
+    end
+
 end

data/lib/docker/api/container.rb

@@ -4,7 +4,7 @@
 class Docker::API::Container < Docker::API::Base
 
     ##
-    # Returns a list of containers.
+    # Return a list of containers.
     #
     # Docker API: GET /containers/json
     # @see https://docs.docker.com/engine/api/v1.40/#operation/ContainerList
@@ -204,7 +204,7 @@ class Docker::API::Container < Docker::API::Base
         path = build_path("/containers/#{name}/logs", params)
 
         if [true, 1 ].include? params[:follow]
-            @connection.request(method: :get, path: path , response_block: block_given? ? block.call : default_streamer)
+            @connection.request(method: :get, path: path , response_block: block_given? ? block : default_streamer)
         else
             @connection.get(path)
         end
@@ -220,7 +220,7 @@ class Docker::API::Container < Docker::API::Base
     # @param params [Hash]: Parameters that are appended to the URL.
     # @param &block: Replace the default output to stdout behavior.
     def attach name, params = {}, &block
-        @connection.request(method: :post, path: build_path("/containers/#{name}/attach", params) , response_block: block_given? ? block.call : default_streamer)
+        @connection.request(method: :post, path: build_path("/containers/#{name}/attach", params) , response_block: block_given? ? block : default_streamer)
     end
 
     ##
@@ -247,7 +247,7 @@ class Docker::API::Container < Docker::API::Base
     def stats name, params = {}, &block
         path = build_path("/containers/#{name}/stats", params)
         if [true, 1 ].include? params[:stream]
-            @connection.request(method: :get, path: path , response_block: block_given? ? block.call : default_streamer)
+            @connection.request(method: :get, path: path , response_block: block_given? ? block : default_streamer)
         else
             @connection.get(path)
         end
@@ -265,7 +265,7 @@ class Docker::API::Container < Docker::API::Base
     def export name, path, &block
         response = self.details(name)
         return response unless response.status == 200
-        @connection.request(method: :get, path: "/containers/#{name}/export" , response_block: block_given? ? block.call : default_writer(path))
+        @connection.request(method: :get, path: "/containers/#{name}/export" , response_block: block_given? ? block : default_writer(path))
     end
 
     ##
@@ -285,7 +285,7 @@ class Docker::API::Container < Docker::API::Base
         return response unless response.status == 200 
         
         file = File.open( File.expand_path( path ) , "wb")
-        response = @connection.request(method: :get, path: build_path("/containers/#{name}/archive", params) , response_block: block_given? ? block.call : lambda { |chunk, remaining_bytes, total_bytes| file.write(chunk) })
+        response = @connection.request(method: :get, path: build_path("/containers/#{name}/archive", params) , response_block: block_given? ? block : lambda { |chunk, remaining_bytes, total_bytes| file.write(chunk) })
         file.close
         response
     end