dockerapi 0.14.0 → 0.19.0

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/exec.rb

@@ -1,42 +1,55 @@
-module Docker
-    module API
-        class Exec < Docker::API::Base
+##
+# This class represents the Docker API exec related endpoints.
+# @see https://docs.docker.com/engine/api/v1.40/#tag/Exec
+class Docker::API::Exec < Docker::API::Base
 
-            def create name, body = {}
-                @connection.request(method: :post, path: "/containers/#{name}/exec", headers: {"Content-Type": "application/json"}, body: body.to_json )
-            end
-
-            def start name, body = {}
-                stream = ""
-                response = @connection.request(method: :post, 
-                    path: "/exec/#{name}/start", 
-                    headers: {"Content-Type": "application/json"},  
-                    body: body.to_json, 
-                    response_block: lambda { |chunk, remaining_bytes, total_bytes| stream += chunk.to_s.encode('UTF-8', invalid: :replace, undef: :replace, replace: '?') }
-                )
-                response.data.merge!({stream: stream})
-                response
-            end
+    ##
+    # Run a command inside a running container.
+    #
+    # Docker API: POST /containers/{id}/exec
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/ContainerExec
+    #
+    # @param name [String]: The ID or name of the container.
+    # @param body [Hash]: Request body to be sent as json.
+    def create name, body = {}
+        @connection.request(method: :post, path: "/containers/#{name}/exec", headers: {"Content-Type": "application/json"}, body: body.to_json )
+    end
 
-            def resize name, params = {}
-                @connection.post(build_path("/exec/#{name}/resize", params))
-            end
+    ##
+    # Start a previously set up exec instance.
+    #
+    # Docker API: POST /exec/{id}/start
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/ExecStart
+    #
+    # @param name [String]: Exec instance ID.
+    # @param body [Hash]: Request body to be sent as json.
+    # @param &block: Replace the default output to stdout behavior.
+    def start name, body = {}, &block
+        @connection.request(method: :post, path: "/exec/#{name}/start", headers: {"Content-Type": "application/json"},  body: body.to_json, 
+            response_block: block_given? ? block : default_streamer )
+    end
 
-            def details name
-                @connection.get("/exec/#{name}/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
-            #################################################
+    ##
+    # Resize the TTY session used by an exec instance.
+    #
+    # Docker API: POST /exec/{id}/resize
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/ExecResize
+    #
+    # @param name [String]: Exec instance ID.
+    # @param body [Hash]: Request body to be sent as json.
+    def resize name, params = {}
+        @connection.post(build_path("/exec/#{name}/resize", params))
+    end
 
-        end
+    ##
+    # Return low-level information about an exec instance.
+    #
+    # Docker API: GET /exec/{id}/json
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/ExecInspect
+    #
+    # @param name [String]: Exec instance ID.
+    def details name
+        @connection.get("/exec/#{name}/json")
     end
+
 end

data/lib/docker/api/image.rb

@@ -21,8 +21,11 @@ class Docker::API::Image < Docker::API::Base
     # @see https://docs.docker.com/engine/api/v1.40/#tag/Distribution
     #
     # @param name [String]: The ID or name of the image.
-    def distribution name
-        @connection.get("/distribution/#{name}/json")
+    # @param authentication [Hash]: Authentication parameters.
+    def distribution name, authentication = {}
+        request = {method: :get, path: "/distribution/#{name}/json"}
+        request[:headers] = {"X-Registry-Auth" => auth_encoder(authentication)} if authentication.any?
+        @connection.request(request)
     end
 
     ##
@@ -37,7 +40,7 @@ class Docker::API::Image < Docker::API::Base
     end
 
     ##
-    # Returns a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.
+    # Return a list of images on the server. Note that it uses a different, smaller representation of an image than inspecting a single image.
     #
     # Docker API: GET /images/json
     # @see https://docs.docker.com/engine/api/v1.40/#operation/ImageList
@@ -105,7 +108,7 @@ class Docker::API::Image < Docker::API::Base
     # @param path [String]: Path to the exported file.
     # @param &block: Replace the default file writing behavior.
     def export name, path, &block
-        @connection.request(method: :get, path: build_path("/images/#{name}/get") , response_block: block_given? ? block.call : default_writer(path))
+        @connection.request(method: :get, path: build_path("/images/#{name}/get") , response_block: block_given? ? block : default_writer(path))
     end
 
     ##
@@ -130,8 +133,8 @@ class Docker::API::Image < Docker::API::Base
     # @param params [Hash]: Parameters that are appended to the URL.
     # @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 } )
+        raise Docker::API::Error.new("Provide authentication parameters to push an image") unless authentication.any?
+        @connection.request(method: :post, path: build_path("/images/#{name}/push", params), headers: { "X-Registry-Auth" => auth_encoder(authentication) } )
     end
 
     ##
@@ -158,13 +161,13 @@ class Docker::API::Image < Docker::API::Base
     # @param authentication [Hash]: Authentication parameters.
     # @param &block: Replace the default output to stdout behavior.
     def create params = {}, authentication = {}, &block
-        request = {method: :post, path: build_path("/images/create", params), response_block: block_given? ? block.call : default_streamer }
+        request = {method: :post, path: build_path("/images/create", params), response_block: block_given? ? block : default_streamer }
         if params.has_key? :fromSrc and !params[:fromSrc].match(/^(http|https)/) # then it's using a tar file
             path = params[:fromSrc]
             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.any?
             @connection.request(request)
         end
     end
@@ -183,10 +186,10 @@ 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.any?
 
         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)
+            response = @connection.request(method: :post, path: build_path("/build", params), headers: headers, response_block: block_given? ? block : default_streamer)
         else
             default_reader(path, build_path("/build", params), headers)
         end

data/lib/docker/api/network.rb

@@ -1,50 +1,86 @@
-module Docker
-    module API        
-        class Network < Docker::API::Base
-
-            def list params = {}
-                @connection.get(build_path("/networks", params))
-            end
-
-            def details name, params = {}
-                @connection.get(build_path([name], params))
-            end
-
-            def create body = {}
-                @connection.request(method: :post, path: build_path(["create"]), headers: {"Content-Type": "application/json"}, body: body.to_json)
-            end
-
-            def remove name
-                @connection.delete(build_path([name]))
-            end
-
-            def prune params = {}
-                @connection.post(build_path(["prune"], params))
-            end
-
-            def connect name, body = {}
-                @connection.request(method: :post, path: build_path([name, "connect"]), headers: {"Content-Type": "application/json"}, body: body.to_json)
-            end
-
-            def disconnect name, body = {}
-                @connection.request(method: :post, path: build_path([name, "disconnect"]), headers: {"Content-Type": "application/json"}, body: body.to_json)
-            end
-
-            #################################################
-            # Items in this area to be removed before 1.0.0 #
-            #################################################
-            def base_path
-                "/networks"
-            end
-
-            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, params = args[0], args[1] || {}
-                details(name, params)
-            end
-            #################################################
-
-        end
+##
+# This class represents the Docker API endpoints regarding networks.
+# @see https://docs.docker.com/engine/api/v1.40/#tag/Network
+class Docker::API::Network < Docker::API::Base
+
+    ##
+    # List networks.
+    #
+    # Docker API: GET /networks
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/NetworkList
+    #
+    # @param params [Hash]: Parameters that are appended to the URL.
+    def list params = {}
+        @connection.get(build_path("/networks", params))
+    end
+
+    ##
+    # Inspect a network.
+    #
+    # Docker API: GET /networks/{id}
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/NetworkInspect
+    #
+    # @param name [String]: The ID or name of the network.
+    # @param params [Hash]: Parameters that are appended to the URL.
+    def details name, params = {}
+        @connection.get(build_path("/networks/#{name}", params))
+    end
+
+    ##
+    # Create a network.
+    #
+    # Docker API: POST /networks/create
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/NetworkCreate
+    #
+    # @param body [Hash]: Request body to be sent as json.
+    def create body = {}
+        @connection.request(method: :post, path: "/networks/create", headers: {"Content-Type": "application/json"}, body: body.to_json)
+    end
+
+    ##
+    # Remove a network.
+    #
+    # Docker API: DELETE /networks/{id}
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/NetworkDelete
+    #
+    # @param name [String]: The ID or name of the network.
+    def remove name
+        @connection.delete("/networks/#{name}")
     end
+
+    ##
+    # Delete unused networks.
+    #
+    # Docker API: POST /networks/prune
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/NetworkPrune
+    #
+    # @param params [Hash]: Parameters that are appended to the URL.
+    def prune params = {}
+        @connection.post(build_path("/networks/prune", params))
+    end
+
+    ##
+    # Connect a container to a network.
+    #
+    # Docker API: POST /networks/{id}/connect
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/NetworkConnect
+    #
+    # @param name [String]: The ID or name of the network.
+    # @param body [Hash]: Request body to be sent as json.
+    def connect name, body = {}
+        @connection.request(method: :post, path: "/networks/#{name}/connect", headers: {"Content-Type": "application/json"}, body: body.to_json)
+    end
+
+    ##
+    # Disconnect a container from a network.
+    #
+    # Docker API: POST /networks/{id}/disconnect
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/NetworkDisconnect
+    #
+    # @param name [String]: The ID or name of the network.
+    # @param body [Hash]: Request body to be sent as json.
+    def disconnect name, body = {}
+        @connection.request(method: :post, path: "/networks/#{name}/disconnect", headers: {"Content-Type": "application/json"}, body: body.to_json)
+    end
+
 end

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
+    ##
+    # Return 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
+    ##
+    # Create 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