dockerapi 0.12.0 → 0.17.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,46 +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 = {}
-                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", 
-                    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 = {}
-                validate Docker::API::InvalidParameter, [:w, :h], params
-                @connection.post(build_path("/exec/#{name}/resize", params))
-            end
+    ##
+    # Starts 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

@@ -1,152 +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 distribution name
-                @connection.get("/distribution/#{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 : 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" => 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
+    #
+    # @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 : 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" => auth_encoder(authentication) } 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": 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 : 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