dockerapi 0.13.0 → 0.18.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

@@ -5,6 +5,7 @@ class Docker::API::Image < Docker::API::Base
 
     ##
     # Return low-level information about an image.
+    #
     # Docker API: GET /images/{name}/json
     # @see https://docs.docker.com/engine/api/v1.40/#operation/ImageInspect
     #
@@ -15,16 +16,21 @@ class Docker::API::Image < Docker::API::Base
 
     ##
     # Return image digest and platform information by contacting the registry.
+    #
     # Docker API: GET /distribution/{name}/json
     # @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
 
     ##
     # Return parent layers of an image.
+    #
     # Docker API: GET /images/{name}/history
     # @see https://docs.docker.com/engine/api/v1.40/#operation/ImageHistory
     #
@@ -34,7 +40,8 @@ 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
     #
@@ -45,6 +52,7 @@ class Docker::API::Image < Docker::API::Base
 
     ##
     # Search for an image on Docker Hub.
+    #
     # Docker API: GET /images/search
     # @see https://docs.docker.com/engine/api/v1.40/#operation/ImageSearch
     #
@@ -55,6 +63,7 @@ class Docker::API::Image < Docker::API::Base
 
     ##
     # Tag an image so that it becomes part of a repository.
+    #
     # Docker API: POST /images/{name}/tag
     # @see https://docs.docker.com/engine/api/v1.40/#operation/ImageTag
     #
@@ -66,6 +75,7 @@ class Docker::API::Image < Docker::API::Base
 
     ##
     # Delete unused images.
+    #
     # Docker API: POST /images/prune
     # @see https://docs.docker.com/engine/api/v1.40/#operation/ImagePrune
     #
@@ -76,7 +86,9 @@ class Docker::API::Image < Docker::API::Base
 
     ##
     # Remove an image, along with any untagged parent images that were referenced by that image.
+    #
     # Images can't be removed if they have descendant images, are being used by a running container or are being used by a build.
+    #
     # Docker API: DELETE /images/{name}
     # @see https://docs.docker.com/engine/api/v1.40/#operation/ImageDelete
     #
@@ -88,19 +100,20 @@ class Docker::API::Image < Docker::API::Base
 
     ##
     # Export an image.
+    #
     # Docker API: GET /images/{name}/get
     # @see https://docs.docker.com/engine/api/v1.40/#operation/ImageGet
     #
     # @param name [String]: The ID or name of the image.
-    # @param path [Hash]: Parameters that are appended to the URL.
-    # @param block [Hash]: Request body to be sent as json.
-    # @block: Replace the default file writing method.
-    def export name, path = "exported_image", &block
-        @connection.request(method: :get, path: build_path("/images/#{name}/get") , response_block: block_given? ? block.call : default_writer(path))
+    # @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 : default_writer(path))
     end
 
     ##
     # Import images.
+    #
     # Docker API: POST /images/load
     # @see https://docs.docker.com/engine/api/v1.40/#operation/ImageLoad
     #
@@ -112,6 +125,7 @@ class Docker::API::Image < Docker::API::Base
 
     ##
     # Push an image to a registry.
+    #
     # Docker API: POST /images/{name}/push
     # @see https://docs.docker.com/engine/api/v1.40/#operation/ImagePush
     #
@@ -119,12 +133,13 @@ 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
 
     ##
     # Create a new image from a container.
+    #
     # Docker API: POST /commit
     # @see https://docs.docker.com/engine/api/v1.40/#operation/ImageCommit
     #
@@ -138,6 +153,7 @@ class Docker::API::Image < Docker::API::Base
 
     ##
     # Create an image by either pulling it from a registry or importing it.
+    #
     # Docker API: POST /images/create
     # @see https://docs.docker.com/engine/api/v1.40/#operation/ImageCreate
     #
@@ -145,19 +161,20 @@ 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
 
     ##
     # Build an image from a tar archive with a Dockerfile in it.
+    #
     # Docker API: POST /build
     # @see https://docs.docker.com/engine/api/v1.40/#operation/ImageBuild
     #
@@ -169,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
@@ -180,6 +197,7 @@ class Docker::API::Image < Docker::API::Base
 
     ##
     # Delete builder cache.
+    #
     # Docker API: POST /build/prune
     # @see https://docs.docker.com/engine/api/v1.40/#operation/BuildPrune
     #

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