dockerapi 0.9.0 → 0.14.0

data/lib/docker/api/exec.rb

@@ -3,13 +3,10 @@ module Docker
         class Exec < Docker::API::Base
 
             def create name, body = {}
-                validate Docker::API::InvalidRequestBody, [:AttachStdin, :AttachStdout, :AttachStderr, :DetachKeys, :Tty, :Env, :Cmd, :Privileged, :User, :WorkingDir], body
                 @connection.request(method: :post, path: "/containers/#{name}/exec", headers: {"Content-Type": "application/json"}, body: body.to_json )
             end
 
             def start name, body = {}
-                validate Docker::API::InvalidRequestBody, [:Detach, :Tty], body
-
                 stream = ""
                 response = @connection.request(method: :post, 
                     path: "/exec/#{name}/start", 
@@ -22,7 +19,6 @@ module Docker
             end
 
             def resize name, params = {}
-                validate Docker::API::InvalidParameter, [:w, :h], params
                 @connection.post(build_path("/exec/#{name}/resize", params))
             end
 

data/lib/docker/api/image.rb

@@ -1,148 +1,205 @@
-require "base64"
-require "json"
-require 'fileutils'
-module Docker
-    module API
-        CommitBody = [: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]
-        BuildParams = [:dockerfile, :t, :extrahosts, :remote, :q, :nocache, :cachefrom, :pull, :rm, :forcerm, :memory, :memswap, :cpushares, :cpusetcpus, :cpuperiod, :cpuquota, :buildargs, :shmsize, :squash, :labels, :networkmode, :platform, :target, :outputs]
-        class Image < Docker::API::Base
-
-            def details name
-                @connection.get(build_path([name, "json"]))
-            end
-
-            def history name
-                @connection.get(build_path([name, "history"]))
-            end
-
-            def list params = {}
-                validate Docker::API::InvalidParameter, [:all, :filters, :digests], params
-                @connection.get(build_path(["json"], params)) 
-            end
-
-            def search params = {}
-                validate Docker::API::InvalidParameter, [:term, :limit, :filters], params
-                @connection.get(build_path(["search"], params)) 
-            end
-
-            def tag name, params = {}
-                validate Docker::API::InvalidParameter, [:repo, :tag], params
-                @connection.post(build_path([name, "tag"], params))
-            end
-
-            def prune params = {}
-                validate Docker::API::InvalidParameter, [:filters], params
-                @connection.post(build_path(["prune"], params))
-            end
-
-            def remove name, params = {}
-                validate Docker::API::InvalidParameter, [:force, :noprune], params
-                @connection.delete(build_path([name], params))
-            end
-
-            def export name, path = "exported_image"
-                file = File.open("/tmp/exported-image", "wb")
-                streamer = lambda do |chunk, remaining_bytes, total_bytes|
-                    file.write(chunk)
-                end
-                response = @connection.request(method: :get, path: build_path([name, "get"]) , response_block: streamer)
-                file.close
-                response.status == 200 ? FileUtils.mv("/tmp/exported-image", File.expand_path(path)) : FileUtils.rm("/tmp/exported-image")
-                response
-            end
-
-            def import path, params = {}
-                validate Docker::API::InvalidParameter, [:quiet], params
-                file = File.open(File.expand_path(path), "r")
-                response = @connection.request(method: :post, path: build_path(["load"], params) , headers: {"Content-Type" => "application/x-tar"}, request_block: lambda { file.read(Excon.defaults[:chunk_size]).to_s} )
-                file.close
-                response
-            end
-
-            def push name, params = {}, authentication = {}
-                validate Docker::API::InvalidParameter, [:tag], params
-
-                if authentication.keys.size > 0
-                    @connection.request(method: :post, path: build_path([name, "push"], params), headers: { "X-Registry-Auth" => Base64.urlsafe_encode64(authentication.to_json.to_s).chomp } )
-                else
-                    raise Docker::API::Error.new("Provide authentication parameters to push an image")
-                end
-            end
-
-            def commit params = {}, body = {}
-                validate Docker::API::InvalidParameter, [:container, :repo, :tag, :comment, :author, :pause, :changes], params
-                validate Docker::API::InvalidRequestBody, Docker::API::CommitBody, body
-                container = Docker::API::Container.new.details(params[:container])
-                return container if [404, 301].include? container.status
-                body = JSON.parse(container.body)["Config"].merge(body)
-                @connection.request(method: :post, path: build_path("/commit", params), headers: {"Content-Type": "application/json"}, body: body.to_json)
-            end
-
-            def create params = {}, authentication = {}
-                validate Docker::API::InvalidParameter, [:fromImage, :fromSrc, :repo, :tag, :message, :platform], params
-                
-                if authentication.keys.size > 0
-                    auth = Docker::API::System.new.auth(authentication)
-                    return auth unless [200, 204].include? auth.status
-                    @connection.request(method: :post, path: build_path(["create"], params), headers: { "X-Registry-Auth" => Base64.encode64(authentication.to_json.to_s).chomp } )
-                elsif params.has_key? :fromSrc
-                    if params[:fromSrc].match(/^(http|https)/)
-                        @connection.request(method: :post, path: build_path(["create"], params))
-                    else
-                        file = File.open(File.expand_path(params[:fromSrc]), "r")
-                        params[:fromSrc] = "-"
-                        response = @connection.request(method: :post, path: build_path(["create"], params) , headers: {"Content-Type" => "application/x-tar"}, request_block: lambda { file.read(Excon.defaults[:chunk_size]).to_s} )
-                        file.close
-                        response
-                    end
-                else
-                    @connection.post(build_path(["create"], params))
-                end
-            end
-
-            def build path, params = {}, authentication = {}
-                raise Docker::API::Error.new("Expected path or params[:remote]") unless path || params[:remote] 
-                validate Docker::API::InvalidParameter, Docker::API::BuildParams, params
-
-                header = {"Content-type": "application/x-tar"}
-                if authentication.keys.size > 0
-                    authentication.each_key do |server|
-                        auth = Docker::API::System.new.auth({username: authentication[server][:username] ,password:authentication[server][:password], serveraddress: server})
-                        return auth unless [200, 204].include? auth.status
-                    end
-                    header.merge!({"X-Registry-Config": Base64.urlsafe_encode64(authentication.to_json.to_s).chomp})
-                end
-
-                begin
-                    file = File.open( File.expand_path( path ) , "r")
-                    response = @connection.request(method: :post, path: build_path("/build", params), headers: header, request_block: lambda { file.read(Excon.defaults[:chunk_size]).to_s})
-                    file.close
-                rescue
-                    response = @connection.request(method: :post, path: build_path("/build", params), headers: header)
-                end
-                response
-            end
-
-            def delete_cache params = {}
-                validate Docker::API::InvalidParameter, [:all, "keep-storage", :filters], params
-                @connection.post(build_path("/build/prune", params))
-            end
-
-            #################################################
-            # Items in this area to be removed before 1.0.0 #
-            #################################################
-            def base_path
-                "/images"
-            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 = args[0]
-                details(name)
-            end
-            #################################################
+##
+# This class represents the Docker API endpoints regarding images.
+# @see https://docs.docker.com/engine/api/v1.40/#tag/Image
+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
+    #
+    # @param name [String]: The ID or name of the image.
+    def details name
+        @connection.get("/images/#{name}/json")
+    end
+
+    ##
+    # 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")
+    end
+
+    ##
+    # Return parent layers of an image.
+    #
+    # Docker API: GET /images/{name}/history
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/ImageHistory
+    #
+    # @param name [String]: The ID or name of the image.
+    def history name
+        @connection.get("/images/#{name}/history")
+    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.
+    #
+    # Docker API: GET /images/json
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/ImageList
+    #
+    # @param params [Hash]: Parameters that are appended to the URL.
+    def list params = {}
+        @connection.get(build_path("/images/json", params)) 
+    end
+
+    ##
+    # Search for an image on Docker Hub.
+    #
+    # Docker API: GET /images/search
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/ImageSearch
+    #
+    # @param params [Hash]: Parameters that are appended to the URL.
+    def search params = {}
+        @connection.get(build_path("/images/search", params)) 
+    end
+
+    ##
+    # 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
+    #
+    # @param name [String]: The ID or name of the image.
+    # @param params [Hash]: Parameters that are appended to the URL.
+    def tag name, params = {}
+        @connection.post(build_path("/images/#{name}/tag", params))
+    end
+
+    ##
+    # Delete unused images.
+    #
+    # Docker API: POST /images/prune
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/ImagePrune
+    #
+    # @param params [Hash]: Parameters that are appended to the URL.
+    def prune params = {}
+        @connection.post(build_path("/images/prune", params))
+    end
+
+    ##
+    # 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
+    #
+    # @param name [String]: The ID or name of the image.
+    # @param params [Hash]: Parameters that are appended to the URL.
+    def remove name, params = {}
+        @connection.delete(build_path("/images/#{name}", params))
+    end
+
+    ##
+    # 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 [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))
+    end
+
+    ##
+    # Import images.
+    #
+    # Docker API: POST /images/load
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/ImageLoad
+    #
+    # @param name [String]: The ID or name of the image.
+    # @param params [Hash]: Parameters that are appended to the URL.
+    def import path, params = {}
+        default_reader(path, build_path("/images/load", params))
+    end
+
+    ##
+    # Push an image to a registry.
+    #
+    # Docker API: POST /images/{name}/push
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/ImagePush
+    #
+    # @param name [String]: The ID or name of the image.
+    # @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 } )
+    end
 
+    ##
+    # Create a new image from a container.
+    #
+    # Docker API: POST /commit
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/ImageCommit
+    #
+    # @param params [Hash]: Parameters that are appended to the URL.
+    # @param body [Hash]: Request body to be sent as json.
+    def commit params = {}, body = {}
+        container = Docker::API::Container.new.details(params[:container])
+        return container if [404, 301].include? container.status
+        @connection.request(method: :post, path: build_path("/commit", params), headers: {"Content-Type": "application/json"}, body: container.json["Config"].merge(body).to_json)
+    end
+
+    ##
+    # 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
+    #
+    # @param params [Hash]: Parameters that are appended to the URL.
+    # @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 }
+        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
+            @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
+    #
+    # @param path [String]: Path to the tar file.
+    # @param params [Hash]: Parameters that are appended to the URL.
+    # @param authentication [Hash]: Authentication parameters.
+    # @param &block: Replace the default output to stdout behavior.
+    def build path, params = {}, authentication = {}, &block
+        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
+
+        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)
+        else
+            default_reader(path, build_path("/build", params), headers)
+        end
+    end
+
+    ##
+    # Delete builder cache.
+    #
+    # Docker API: POST /build/prune
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/BuildPrune
+    #
+    # @param params [Hash]: Parameters that are appended to the URL.
+    def delete_cache params = {}
+        @connection.post(build_path("/build/prune", params))
+    end
 end

data/lib/docker/api/network.rb

@@ -3,17 +3,14 @@ module Docker
         class Network < Docker::API::Base
 
             def list params = {}
-                validate Docker::API::InvalidParameter, [:filters], params
                 @connection.get(build_path("/networks", params))
             end
 
             def details name, params = {}
-                validate Docker::API::InvalidParameter, [:verbose, :scope], params
                 @connection.get(build_path([name], params))
             end
 
             def create body = {}
-                validate Docker::API::InvalidRequestBody, [:Name, :CheckDuplicate, :Driver, :Internal, :Attachable, :Ingress, :IPAM, :EnableIPv6, :Options, :Labels], body
                 @connection.request(method: :post, path: build_path(["create"]), headers: {"Content-Type": "application/json"}, body: body.to_json)
             end
 
@@ -22,17 +19,14 @@ module Docker
             end
 
             def prune params = {}
-                validate Docker::API::InvalidParameter, [:filters], params
                 @connection.post(build_path(["prune"], params))
             end
 
             def connect name, body = {}
-                validate Docker::API::InvalidRequestBody, [:Container, :EndpointConfig], body
                 @connection.request(method: :post, path: build_path([name, "connect"]), headers: {"Content-Type": "application/json"}, body: body.to_json)
             end
 
             def disconnect name, body = {}
-                validate Docker::API::InvalidRequestBody, [:Container, :Force], body
                 @connection.request(method: :post, path: build_path([name, "disconnect"]), headers: {"Content-Type": "application/json"}, body: body.to_json)
             end
 

data/lib/docker/api/node.rb

@@ -3,18 +3,14 @@ module Docker
         class Node < Docker::API::Base
 
             def list params = {}
-                validate Docker::API::InvalidParameter, [:filters], params
                 @connection.get(build_path("/nodes", params))
             end
 
             def update name, params = {}, body = {}
-                validate Docker::API::InvalidParameter, [:version], params
-                validate Docker::API::InvalidRequestBody, [:Name, :Labels, :Role, :Availability], 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 = {}
-                validate Docker::API::InvalidParameter, [:force], params
                 @connection.delete(build_path("/nodes/#{name}", params))
             end
 

data/lib/docker/api/plugin.rb

@@ -0,0 +1,160 @@
+# This class represents the Docker API endpoints regarding plugins.
+#
+# @see https://docs.docker.com/engine/api/v1.40/#tag/Plugin
+class Docker::API::Plugin < Docker::API::Base
+
+    # List plugins
+    #
+    # Docker API: GET /plugins
+    #
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/PluginList
+    #
+    # @param params [Hash]: Parameters that are appended to the URL.
+    def list params = {}
+        @connection.get(build_path("/plugins", params))
+    end
+
+    # Get plugin privileges
+    #
+    # Docker API: GET /plugins/privileges
+    #
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/GetPluginPrivileges
+    #
+    # @param params [Hash]: Parameters that are appended to the URL.
+    def privileges params = {}
+        @connection.get(build_path("/plugins/privileges", params))
+    end
+
+    # Install a plugin
+    #
+    # Pulls and installs a plugin. After the plugin is installed, it can be enabled using the POST /plugins/{name}/enable endpoint.
+    #
+    # Docker API: POST /plugins/pull
+    #
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/PluginPull
+    #
+    # @param params [Hash]: Parameters that are appended to the URL.
+    #
+    # @param privileges [Array]: Plugin privileges to be sent as json in request body.
+    #
+    # @param authentication [Hash]: Authentication parameters.
+    def install params = {}, privileges = [], authentication = {}
+        headers = {"Content-Type": "application/json"}
+        headers.merge!({"X-Registry-Auth" => Base64.urlsafe_encode64(authentication.to_json.to_s)}) if authentication.keys.size > 0
+        @connection.request(method: :post, path: build_path("/plugins/pull", params), headers: headers, body: privileges.to_json )
+    end
+
+    # Inspect a plugin
+    #
+    # Docker API: GET /plugins/{name}/json
+    #
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/PluginInspect
+    #
+    # @param name [String]: The ID or name of the plugin.
+    def details name 
+        @connection.get("/plugins/#{name}/json")
+    end
+
+    # Remove a plugin
+    #
+    # Docker API: DELETE /plugins/{name}
+    #
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/PluginDelete
+    #
+    # @param name [String]: The ID or name of the plugin.
+    #
+    # @param params [Hash]: Parameters that are appended to the URL.
+    def remove name, params = {}
+        @connection.delete(build_path("/plugins/#{name}",params))
+    end
+
+    # Enable a plugin
+    #
+    # Docker API: POST /plugins/{name}/enable
+    #
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/PluginEnable
+    #
+    # @param name [String]: The ID or name of the plugin.
+    #
+    # @param params [Hash]: Parameters that are appended to the URL.
+    def enable name, params = {}
+        @connection.post(build_path("/plugins/#{name}/enable", params))
+    end
+
+    # Disable a plugin
+    #
+    # Docker API: POST /plugins/{name}/disable
+    #
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/PluginDisable
+    #
+    # @param name [String]: The ID or name of the plugin.
+    def disable name
+        @connection.post("/plugins/#{name}/disable")
+    end
+
+    # Upgrade a plugin
+    #
+    # Docker API: POST /plugins/{name}/upgrade
+    #
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/PluginUpgrade
+    #
+    # @param name [String]: The ID or name of the plugin.
+    #
+    # @param params [Hash]: Parameters that are appended to the URL.
+    #
+    # @param privileges [Array]: Plugin privileges to be sent as json in request body.
+    #
+    # @param authentication [Hash]: Authentication parameters.
+    def upgrade name, params = {}, privileges = [], authentication = {}
+        headers = {"Content-Type": "application/json"}
+        headers.merge!({"X-Registry-Auth" => Base64.urlsafe_encode64(authentication.to_json.to_s)}) if authentication.keys.size > 0
+        @connection.request(method: :post, path: build_path("/plugins/#{name}/upgrade", params), headers: headers, body: privileges.to_json )
+    end
+
+    # Create a plugin
+    #
+    # Docker API: POST /plugins/create
+    #
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/PluginCreate
+    #
+    # @param name [String]: The ID or name of the plugin.
+    #
+    # @param path [String]: Path to tar file that contains rootfs folder and config.json file.
+    def create name, path
+        file = File.open( File.expand_path( path ) , "r")
+        response = @connection.request(method: :post, path: "/plugins/create?name=#{name}", body: file.read.to_s )
+        file.close        
+        response
+    end
+
+    # Push a plugin to the registry.
+    #
+    # Docker API: POST /plugins/{name}/push
+    #
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/PluginPush
+    #
+    # @param name [String]: The ID or name of the plugin.
+    #
+    # @param authentication [Hash]: Authentication parameters.
+    def push name, authentication = {}
+        if authentication.keys.size > 0
+            @connection.request(method: :post, path: "/plugins/#{name}/push", headers: {"X-Registry-Auth" => Base64.urlsafe_encode64(authentication.to_json.to_s)})
+        else
+            @connection.post("/plugins/#{name}/push")
+        end
+    end
+
+    # Configure a plugin
+    #
+    # Docker API: POST /plugins/{name}/set
+    #
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/PluginSet
+    #
+    # @param name [String]: The ID or name of the plugin.
+    #
+    # @param config [Array]: Plugin configuration to be sent as json in request body.
+    def configure name, config
+        @connection.request(method: :post, path: "/plugins/#{name}/set", headers: {"Content-Type": "application/json"}, body:config.to_json)
+    end
+
+end