dockerapi 0.13.0 → 0.18.0

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

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

@@ -1,32 +1,65 @@
-require "json"
-module Docker
-    module API
-        class System < Docker::API::Base
+##
+# This class represents the Docker API system related endpoints.
+# @see https://docs.docker.com/engine/api/v1.40/#tag/System
+class Docker::API::System < Docker::API::Base
 
-            def auth body = {}
-                @connection.request(method: :post, path: "/auth", headers: { "Content-Type" => "application/json" }, body: body.to_json)
-            end
+    ##
+    # Validate credentials for a registry and, if available, get an identity token for accessing the registry without password.
+    #
+    # Docker API: POST /auth
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/SystemAuth
+    #
+    # @param body [Hash]: Request body to be sent as json.
+    def auth body = {}
+        @connection.request(method: :post, path: "/auth", headers: { "Content-Type" => "application/json" }, body: body.to_json)
+    end
 
-            def events params = {}
-                @connection.request(method: :get, path: build_path("/events", params), response_block: lambda { |chunk, remaining_bytes, total_bytes| puts chunk.inspect } )
-            end
+    ##
+    # Stream real-time events from the server.
+    #
+    # Docker API: GET /events
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/SystemEvents
+    #
+    # @param params [Hash]: Parameters that are appended to the URL.
+    # @param &block: Replace the default output to stdout behavior.
+    def events params = {}, &block
+        @connection.request(method: :get, path: build_path("/events", params), response_block: block_given? ? block : default_streamer )
+    end
 
-            def ping
-                @connection.get("/_ping")
-            end
+    ##
+    # This is a dummy endpoint you can use to test if the server is accessible.
+    #
+    # Docker API: GET /_ping
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/SystemPing
+    def ping
+        @connection.get("/_ping")
+    end
 
-            def info
-                @connection.get("/info")
-            end
+    ##
+    # Get system information.
+    #
+    # Docker API: GET /info
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/SystemInfo
+    def info
+        @connection.get("/info")
+    end
 
-            def version
-                @connection.get("/version")
-            end
+    ##
+    # Return the version of Docker that is running and various information about the system that Docker is running on.
+    #
+    # Docker API: GET /version
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/SystemVersion
+    def version
+        @connection.get("/version")
+    end
 
-            def df
-                @connection.get("/system/df")
-            end
-                        
-        end
+    ##
+    # Get data usage information.
+    #
+    # Docker API: GET /system/df
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/SystemDataUsage
+    def df
+        @connection.get("/system/df")
     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 : 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.13.0"
+    GEM_VERSION = "0.18.0"
 
     API_VERSION = "1.40"