dockerapi 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a07cc3ef52a91afb13ab99c130cb6cbed118055aba264df3e0fb0a1ec701ef6d
-  data.tar.gz: d9e6e03672a7a47de2cb0fb840569c45582075be679d21995192247633d58d70
+  metadata.gz: 8207aa413525c868d4e1c0f57cacf38c19348dee819da2aeb63f390d5ac41f28
+  data.tar.gz: 53406674405580c0dcb91c4c32a914ef0de92ce9a9c1132eb7bf046902e5adc8
 SHA512:
-  metadata.gz: 46bbd5e8c6cbb41e13b3830aab5ca8825d37a1c85401dedc33aeba3352657f8410e99c8c321bc5e5d10e9eeac6435769f9b7d7570a8910b7f0d0779a3308381a
-  data.tar.gz: 672a71377c73a0c0a09796d84afebf2cfe03f3a6182626119c3370ab41112249d881152f1dadbe24ba31775475b4463df5d8c42ca2e9f7d6915c080149fab7ab
+  metadata.gz: be5d82c94e72b29d4341330b3c12f4a2007c6e46813cca6eb6cc8ba3f3a0adae2cd8ef00d0020ed1d59bf5bfc12bf6b22f6b3dd96eb5287ee03f02e14f1bb0ce
+  data.tar.gz: f4155422936cd0a4e754d4f32a118662c1d6ace28d788aae51e4d09f09b817519ed7ec0bca9e1955bcb2edc66c5ea111181493e43d398de20e4662d665ac8d2b

data/CHANGELOG.md

@@ -1,6 +1,12 @@
+# 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 that can now receive a block to replace standard output to stdout behavior.
+`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.
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    dockerapi (0.15.0)
+    dockerapi (0.16.0)
       excon (~> 0.76.0)
 
 GEM

data/README.md

@@ -31,6 +31,8 @@ Add this line to your application's Gemfile:
 
 ```ruby
 gem 'dockerapi'
+# or
+gem 'dockerapi', github: 'nu12/dockerapi'
 ```
 
 And then execute:
@@ -547,17 +549,14 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 | Network | Ok | Ok | Ok |
 | System | Ok | Ok | Ok |
 | Exec | Ok | Ok | Ok |
-| Swarm | Ok | Ok | 8/11 |
-| Node | Ok | Ok | 8/11 |
-| Service | Ok | Ok | 8/11 |
-| Task | Ok | Ok | 8/11 |
-| Secret | Ok | Ok | 8/11 |
+| Swarm | Ok | Ok | Ok |
+| Node | Ok | Ok | Ok |
+| Service | Ok | Ok | Ok |
+| Task | Ok | Ok | Ok |
+| Secret | Ok | Ok | Ok |
 | Config | Ok | Ok | 8/14 |
-| Distribution | Ok | Ok | 8/14 |
 | Plugin | Ok | Ok | 8/14 |
 
-Add doc in these files: `base`, `connection`, `error`, `response`, `dockerapi`
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/nu12/dockerapi.

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
     
-
+    ##
+    # Creates 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
 
+    ##
+    # Outputs 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
 
+    ##
+    # Writes file.
+    #
+    # @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,6 +37,13 @@ class Docker::API::Base
         streamer
     end
 
+    ##
+    # Reads file.
+    #
+    # @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 )
@@ -43,24 +51,60 @@ class Docker::API::Base
         response
     end
 
+    ##
+    # Encodes the authentication parameters.
+    #
+    # @param authentication [Hash]: Parameters to be encoded.
+    def auth_encoder(authentication)
+        Base64.urlsafe_encode64(authentication.to_json.to_s).chomp
+    end
+
+    ##
+    # Validates 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
+    ##
+    # Converts 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
 
+    ##
+    # Builds 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
+
+    ##
+    # Sets 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,26 @@
-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
+    ##
+    # Calls an Excon request and returns a Docker::API::Response object.
+    #
+    # @param params [Hash]: Request parameters.
+    def request params
+        Docker::API::Response.new(@connection.request(params).data)
     end
+    
+    ##
+    # Creates 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/error.rb

@@ -1,17 +1,33 @@
 module Docker
     module API
+
+      ##
+      # This class represents a validation error.
       class ValidationError < StandardError
+
+        ##
+        # @params permitted [Array]: permitted values.
+        # @params unpermitted [Array]: unpermitted values.
         def initialize permitted, unpermitted
           super("Unpermitted options found: #{unpermitted.to_s}. Permitted are #{permitted.to_s}")
         end
       end
+
+      ##
+      # This class represents a parameter validation error.
+      class InvalidParameter < Docker::API::ValidationError; end
+
+      ##
+      # This class represents a request body validation error.
+      class InvalidRequestBody < Docker::API::ValidationError; end
+
+      ##
+      # This class represents a generic error.
       class Error < StandardError
         def initialize msg = "Error without specific message"
           super(msg)
         end
       end
-
-      class InvalidParameter < Docker::API::ValidationError; end
-      class InvalidRequestBody < Docker::API::ValidationError; end
+      
     end
   end

data/lib/docker/api/image.rb

@@ -131,7 +131,7 @@ class Docker::API::Image < Docker::API::Base
     # @param authentication [Hash]: Authentication parameters.
     def push name, params = {}, authentication = {}
         raise Docker::API::Error.new("Provide authentication parameters to push an image") unless authentication.keys.size > 0
-        @connection.request(method: :post, path: build_path("/images/#{name}/push", params), headers: { "X-Registry-Auth" => Base64.urlsafe_encode64(authentication.to_json.to_s).chomp } )
+        @connection.request(method: :post, path: build_path("/images/#{name}/push", params), headers: { "X-Registry-Auth" => auth_encoder(authentication) } )
     end
 
     ##
@@ -164,7 +164,7 @@ class Docker::API::Image < Docker::API::Base
             params[:fromSrc] = "-"
             default_reader(path, build_path("/images/create", params))
         else
-            request[:headers] = { "X-Registry-Auth" => Base64.encode64(authentication.to_json.to_s).chomp } if authentication.keys.size > 0
+            request[:headers] = { "X-Registry-Auth" => auth_encoder(authentication) } if authentication.keys.size > 0
             @connection.request(request)
         end
     end
@@ -183,7 +183,7 @@ class Docker::API::Image < Docker::API::Base
         raise Docker::API::Error.new("Expected path or params[:remote]") unless path || params[:remote] 
 
         headers = {"Content-type": "application/x-tar"}
-        headers.merge!({"X-Registry-Config": Base64.urlsafe_encode64(authentication.to_json.to_s).chomp}) if authentication.keys.size > 0
+        headers.merge!({"X-Registry-Config": auth_encoder(authentication) }) if authentication.keys.size > 0
 
         if path == nil and params.has_key? :remote
             response = @connection.request(method: :post, path: build_path("/build", params), headers: headers, response_block: block_given? ? block.call : default_streamer)

data/lib/docker/api/node.rb

@@ -1,34 +1,53 @@
-module Docker
-    module API        
-        class Node < Docker::API::Base
+# This class represents the Docker API endpoints regarding nodes.
+#
+# Nodes are instances of the Engine participating in a swarm. Swarm mode must be enabled for these endpoints to work.
+# @see https://docs.docker.com/engine/api/v1.40/#tag/Node
+class Docker::API::Node < Docker::API::Base
 
-            def list params = {}
-                @connection.get(build_path("/nodes", params))
-            end
-
-            def update name, params = {}, body = {}
-                @connection.request(method: :post, path: build_path("nodes/#{name}/update", params), headers: {"Content-Type": "application/json"}, body: body.to_json)
-            end
-
-            def delete name, params = {}
-                @connection.delete(build_path("/nodes/#{name}", params))
-            end
+    ##
+    # List nodes.
+    #
+    # Docker API: GET /nodes
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/NodeList
+    #
+    # @param params [Hash]: Parameters that are appended to the URL.
+    def list params = {}
+        @connection.get(build_path("/nodes", params))
+    end
 
-            def details name
-                @connection.get("/nodes/#{name}")
-            end
+    ##
+    # Update a node.
+    #
+    # Docker API: POST /nodes/{id}/update
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/NodeUpdate
+    #
+    # @param name [String]: The ID or name of the node.
+    # @param params [Hash]: Parameters that are appended to the URL.
+    # @param body [Hash]: Request body to be sent as json.
+    def update name, params = {}, body = {}
+        @connection.request(method: :post, path: build_path("nodes/#{name}/update", params), headers: {"Content-Type": "application/json"}, body: body.to_json)
+    end
 
-            #################################################
-            # Items in this area to be removed before 1.0.0 #
-            #################################################
-            def inspect *args
-                return super.inspect if args.size == 0
-                warn  "WARNING: #inspect is deprecated and will be removed in the future, please use #details instead."
-                name = args[0]
-                details(name)
-            end
-            #################################################
+    ##
+    # Delete a node.
+    #
+    # Docker API: DELETE /nodes/{id}
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/NodeDelete
+    #
+    # @param name [String]: The ID or name of the node.
+    # @param params [Hash]: Parameters that are appended to the URL.
+    def delete name, params = {}
+        @connection.delete(build_path("/nodes/#{name}", params))
+    end
 
-        end
+    ##
+    # Inspect a node.
+    #
+    # Docker API: GET /nodes/{id}
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/NodeInspect
+    #
+    # @param name [String]: The ID or name of the node.
+    def details name
+        @connection.get("/nodes/#{name}")
     end
 end

data/lib/docker/api/response.rb

@@ -1,25 +1,33 @@
-module Docker
-    module API
-        class Response < Excon::Response
-            attr_reader(:json, :path)
+##
+# Reponse class.
+class Docker::API::Response < Excon::Response
+    attr_reader(:json, :path)
 
-            def initialize data
-                super data
-                @json = parse_json @body
-                @path = @data[:path]
-            end
+    ##
+    # Initialize a new Response object.
+    #
+    # @params data [Object]: Reponse's data.
+    def initialize data
+        super data
+        @json = parse_json @body
+        @path = @data[:path]
+    end
 
-            def success?
-                (200..204).include? @status
-            end
+    ##
+    # Returns true if Response status is in 200..204 range.
+    def success?
+        (200..204).include? @status
+    end
 
-            private
+    private
 
-            def parse_json data
-               return nil unless headers["Content-Type"] == "application/json"
-               return nil if data == ""
-               data.split("\r\n").size > 1 ? data.split("\r\n").map{ |e| eval(e) } : JSON.parse(data)
-            end
-        end
+    ##
+    # Creates a json from Response data attribute.
+    #
+    # @params data [String]: String to be converted in json.
+    def parse_json data
+        return nil unless headers["Content-Type"] == "application/json"
+        return nil if data == ""
+        data.split("\r\n").size > 1 ? data.split("\r\n").map{ |e| eval(e) } : JSON.parse(data)
     end
 end

data/lib/docker/api/secret.rb

@@ -1,14 +1,12 @@
 # This class represents the Docker API endpoints regarding secrets.
 #
-# @see https://docs.docker.com/engine/api/v1.40/#tag/Secret
-#
 # Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.
+# @see https://docs.docker.com/engine/api/v1.40/#tag/Secret
 class Docker::API::Secret < Docker::API::Base
 
     # List secrets
     #
     # Docker API: GET /secrets
-    #
     # @see https://docs.docker.com/engine/api/v1.40/#operation/SecretList
     #
     # @param params [Hash]: Parameters that are appended to the URL.
@@ -19,7 +17,6 @@ class Docker::API::Secret < Docker::API::Base
     # Create a secret
     #
     # Docker API: POST /secrets/create
-    #
     # @see https://docs.docker.com/engine/api/v1.40/#operation/SecretCreate
     #
     # @param body [Hash]: Request body to be sent as json.
@@ -30,7 +27,6 @@ class Docker::API::Secret < Docker::API::Base
     # Inspect a secret
     #
     # Docker API: GET /secrets/{id}
-    #
     # @see https://docs.docker.com/engine/api/v1.40/#operation/SecretInspect
     #
     # @param name [String]: The ID or name of the secret.
@@ -41,13 +37,10 @@ class Docker::API::Secret < Docker::API::Base
     # Update a secret
     #
     # Docker API: POST /secrets/{id}/update
-    #
     # @see https://docs.docker.com/engine/api/v1.40/#operation/SecretUpdate
     #
     # @param name [String]: The ID or name of the secret.
-    #
     # @param params [Hash]: Parameters that are appended to the URL.
-    #
     # @param body [Hash]: Request body to be sent as json.
     def update name, params = {}, body = {}
         @connection.request(method: :post, path: build_path("/secrets/#{name}/update",params), headers: {"Content-Type": "application/json"}, body: body.to_json)
@@ -56,7 +49,6 @@ class Docker::API::Secret < Docker::API::Base
     # Delete a secret
     #
     # Docker API: DELETE /secrets/{id}
-    #
     # @see https://docs.docker.com/engine/api/v1.40/#operation/SecretDelete
     #
     # @param name [String]: The ID or name of the secret.

data/lib/docker/api/service.rb

@@ -1,14 +1,12 @@
 # This class represents the Docker API endpoints regarding services.
 #
-# @see https://docs.docker.com/engine/api/v1.40/#tag/Service
-#
 # Services are the definitions of tasks to run on a swarm. Swarm mode must be enabled for these endpoints to work.
+# @see https://docs.docker.com/engine/api/v1.40/#tag/Service
 class Docker::API::Service < Docker::API::Base
 
     # List services
     #
     # Docker API: GET /services
-    #
     # @see https://docs.docker.com/engine/api/v1.40/#operation/ServiceList
     #
     # @param params [Hash]: Parameters that are appended to the URL.
@@ -19,46 +17,38 @@ class Docker::API::Service < Docker::API::Base
     # Create a service
     #
     # Docker API: POST /services/create
-    #
     # @see https://docs.docker.com/engine/api/v1.40/#operation/ServiceCreate
     #
     # @param body [Hash]: Request body to be sent as json.
-    #
     # @param authentication [Hash]: Authentication parameters.
     def create body = {}, authentication = {}
         headers = {"Content-Type": "application/json"}
-        headers.merge!({"X-Registry-Auth" => Base64.urlsafe_encode64(authentication.to_json.to_s)}) if authentication.keys.size > 0
+        headers.merge!({"X-Registry-Auth" => auth_encoder(authentication) }) if authentication.keys.size > 0
         @connection.request(method: :post, path: "/services/create", headers: headers, body: body.to_json)
     end
 
     # Update a service
     #
     # Docker API: POST /services/{id}/update
-    #
     # @see https://docs.docker.com/engine/api/v1.40/#operation/ServiceUpdate
     #
     # @param name [String]: The ID or name of the service.
-    #
     # @param params [Hash]:  Parameters that are appended to the URL.
-    #
     # @param body [Hash]: Request body to be sent as json.
-    #
     # @param authentication [Hash]:  Authentication parameters.
     def update name, params = {}, body = {}, authentication = {}
         # view https://github.com/docker/swarmkit/issues/1394#issuecomment-240850719
         headers = {"Content-Type": "application/json"}
-        headers.merge!({"X-Registry-Auth" => Base64.urlsafe_encode64(authentication.to_json.to_s)}) if authentication.keys.size > 0
+        headers.merge!({"X-Registry-Auth" => auth_encoder(authentication) }) if authentication.keys.size > 0
         @connection.request(method: :post, path: build_path("/services/#{name}/update", params), headers: headers, body: body.to_json)
     end
 
     # Inspect a service
     #
     # Docker API: GET /services/{id}
-    #
     # @see https://docs.docker.com/engine/api/v1.40/#operation/ServiceInspect
     #
     # @param name [String]: The ID or name of the service.
-    #
     # @param params [Hash]: Parameters that are appended to the URL. 
     def details name, params = {}
         @connection.get(build_path("/services/#{name}", params))
@@ -66,14 +56,10 @@ class Docker::API::Service < Docker::API::Base
 
     # Get stdout and stderr logs from a service. 
     #
-    # Note: This endpoint works only for services with the local, json-file or journald logging drivers.
-    #
     # Docker API: GET /services/{id}/logs
-    #
     # @see https://docs.docker.com/engine/api/v1.40/#operation/ServiceLogs
     #
     # @param name [String]: The ID or name of the service.
-    #
     # @param params [Hash]: Parameters that are appended to the URL. 
     def logs name, params = {}
         @connection.get(build_path("/services/#{name}/logs", params))
@@ -82,7 +68,6 @@ class Docker::API::Service < Docker::API::Base
     # Delete a service
     #
     # Docker API: DELETE /services/{id}
-    #
     # @see https://docs.docker.com/engine/api/v1.40/#operation/ServiceDelete
     #
     # @param name [String]: The ID or name of the service.

data/lib/docker/api/swarm.rb

@@ -1,45 +1,79 @@
-module Docker
-    module API
-        class Swarm < Docker::API::Base
+##
+# This class represents the Docker API endpoints regarding swamrs.
+# @see https://docs.docker.com/engine/api/v1.40/#tag/Swarm
+class Docker::API::Swarm < Docker::API::Base
 
-            def init body = {}
-                @connection.request(method: :post, path: build_path("/swarm/init"), headers: {"Content-Type": "application/json"}, body: body.to_json)
-            end
-
-            def update params = {}, body = {}
-                @connection.request(method: :post, path: build_path("/swarm/update", params), headers: {"Content-Type": "application/json"}, body: body.to_json)
-            end
+    ##
+    # Initialize a new swarm.
+    #
+    # Docker API: POST /swarm/init
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/SwarmInit
+    #
+    # @param body [Hash]: Request body to be sent as json.
+    def init body = {}
+        @connection.request(method: :post, path: build_path("/swarm/init"), headers: {"Content-Type": "application/json"}, body: body.to_json)
+    end
 
-            def details
-                @connection.get("/swarm")
-            end
+    ##
+    # Update a swarm.
+    #
+    # Docker API: POST /swarm/update
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/SwarmUpdate
+    #
+    # @param params [Hash]: Parameters that are appended to the URL.
+    # @param body [Hash]: Request body to be sent as json.
+    def update params = {}, body = {}
+        @connection.request(method: :post, path: build_path("/swarm/update", params), headers: {"Content-Type": "application/json"}, body: body.to_json)
+    end
 
-            def unlock_key
-                @connection.get(build_path("/swarm/unlockkey"))
-            end
+    ##
+    # Inspect swarm.
+    #
+    # Docker API: GET /swarm
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/SwarmInspect
+    def details
+        @connection.get("/swarm")
+    end
 
-            def unlock body = {}
-                @connection.request(method: :post, path: build_path("/swarm/unlock"), headers: {"Content-Type": "application/json"}, body: body.to_json)
-            end
+    ##
+    # Get the unlock key.
+    #
+    # Docker API: GET /swarm/unlockkey
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/SwarmUnlockkey 
+    def unlock_key
+        @connection.get("/swarm/unlockkey")
+    end
 
-            def join body = {}
-                @connection.request(method: :post, path: build_path("/swarm/join"), headers: {"Content-Type": "application/json"}, body: body.to_json)
-            end
+    ##
+    # Unlock a locked manager.
+    #
+    # Docker API: POST /swarm/unlock
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/SwarmUnlock
+    #
+    # @param body [Hash]: Request body to be sent as json.
+    def unlock body = {}
+        @connection.request(method: :post, path: "/swarm/unlock", headers: {"Content-Type": "application/json"}, body: body.to_json)
+    end
 
-            def leave params = {}
-                @connection.post(build_path("/swarm/leave", params))
-            end
+    ##
+    # Join an existing swarm.
+    #
+    # Docker API: POST /swarm/join
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/SwarmJoin
+    #
+    # @param body [Hash]: Request body to be sent as json.
+    def join body = {}
+        @connection.request(method: :post, path: "/swarm/join", headers: {"Content-Type": "application/json"}, body: body.to_json)
+    end
 
-            #################################################
-            # Items in this area to be removed before 1.0.0 #
-            #################################################
-            def inspect
-                caller.each { | el | return super.inspect if el.match(/inspector/) }
-                warn  "WARNING: #inspect is deprecated and will be removed in the future, please use #details instead."
-                details
-            end
-            #################################################
-            
-        end
+    ##
+    # Leave a swarm.
+    #
+    # Docker API: POST /swarm/leave
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/SwarmLeave
+    #
+    # @param params [Hash]: Parameters that are appended to the URL.
+    def leave params = {}
+        @connection.post(build_path("/swarm/leave", params))
     end
 end

data/lib/docker/api/task.rb

@@ -1,14 +1,12 @@
 # This class represents the Docker API endpoints regarding tasks.
 #
-# @see https://docs.docker.com/engine/api/v1.40/#tag/Task
-#
 # A task is a container running on a swarm. It is the atomic scheduling unit of swarm. Swarm mode must be enabled for these endpoints to work.
+# @see https://docs.docker.com/engine/api/v1.40/#tag/Task
 class Docker::API::Task < Docker::API::Base
 
     # List tasks
     #
     # Docker API: GET /tasks
-    #
     # @see https://docs.docker.com/engine/api/v1.40/#operation/TaskList
     #
     # @param params [Hash]: Parameters that are appended to the URL.
@@ -19,7 +17,6 @@ class Docker::API::Task < Docker::API::Base
     # Inspect a task
     #
     # Docker API: GET /tasks/{id}
-    #
     # @see https://docs.docker.com/engine/api/v1.40/#operation/TaskInspect
     #
     # @param name [String]: The ID or name of the task.
@@ -29,16 +26,19 @@ class Docker::API::Task < Docker::API::Base
 
     # Get stdout and stderr logs from a task.
     #
-    # Note: This endpoint works only for services with the local, json-file or journald logging drivers.
-    #
     # Docker API: GET /tasks/{id}/logs
-    #
     # @see https://docs.docker.com/engine/api/v1.40/#operation/TaskLogs
     #
     # @param name (String) : The ID or name of the task.
-    #
     # @param params (Hash) : Parameters that are appended to the URL.
-    def logs name, params = {}
-        @connection.get(build_path("/tasks/#{name}/logs", params))
+    # @param &block: Replace the default output to stdout behavior.
+    def logs name, params = {}, &block
+        path = build_path("/tasks/#{name}/logs", params)
+
+        if [true, 1 ].include? params[:follow]
+            @connection.request(method: :get, path: path , response_block: block_given? ? block.call : default_streamer)
+        else
+            @connection.get(path)
+        end
     end
 end

data/lib/docker/api/version.rb

@@ -1,6 +1,6 @@
 module Docker
   module API
-    GEM_VERSION = "0.15.0"
+    GEM_VERSION = "0.16.0"
 
     API_VERSION = "1.40"
 

data/lib/dockerapi.rb

@@ -25,8 +25,12 @@ require "docker/api/plugin"
 module Docker
   module API
 
+    ##
+    # This variable controls output verbosity.
     PRINT_TO_STDOUT = true
 
+    ##
+    # Valid values for parameter validations.
     VALID_PARAMS = {
       "Docker::API::Image" => {
         "build" => [:dockerfile, :t, :extrahosts, :remote, :q, :nocache, :cachefrom, :pull, :rm, :forcerm, :memory, :memswap, :cpushares, :cpusetcpus, :cpuperiod, :cpuquota, :buildargs, :shmsize, :squash, :labels, :networkmode, :platform, :target, :outputs],
@@ -114,6 +118,8 @@ module Docker
       }
     }
 
+    ##
+    # Valid values for request body validations.
     VALID_BODY = {
       "Docker::API::Image" => {
         "commit" => [:Hostname, :Domainname, :User, :AttachStdin, :AttachStdout, :AttachStderr, :ExposedPorts, :Tty, :OpenStdin, :StdinOnce, :Env, :Cmd, :HealthCheck, :ArgsEscaped, :Image, :Volumes, :WorkingDir, :Entrypoint, :NetworkDisabled, :MacAddress, :OnBuild, :Labels, :StopSignal, :StopTimeout, :Shell]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dockerapi
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Alysson A. Costa
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-08-07 00:00:00.000000000 Z
+date: 2020-08-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: excon