dockerapi 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac123f7f5ed500758fd1bb2a9f214495e71c6848517662eae15b92dfa00387aa
-  data.tar.gz: 270f7a7e14d43f73c402191f11ebf9233aa8b7e2c2e314ac3eeb2875487c5120
+  metadata.gz: a07cc3ef52a91afb13ab99c130cb6cbed118055aba264df3e0fb0a1ec701ef6d
+  data.tar.gz: d9e6e03672a7a47de2cb0fb840569c45582075be679d21995192247633d58d70
 SHA512:
-  metadata.gz: 878a7c0a146bc6657909151ff0e866c1b9cc93f1dc57ed6c7d0e91b87063e41496af294d1f1e7318b11b0ba3eaf03823e5e081b664b4c3bdd326d4298aed6c65
-  data.tar.gz: fee3d36fd9de8619fc27c588c1285c9acd6ca20a3a6ce1f9fd2ea67c807c74d90ae1a0b531ec233a227ccfd4655056e0c33e6605fa9a31040f6984ca2e3a6798
+  metadata.gz: 46bbd5e8c6cbb41e13b3830aab5ca8825d37a1c85401dedc33aeba3352657f8410e99c8c321bc5e5d10e9eeac6435769f9b7d7570a8910b7f0d0779a3308381a
+  data.tar.gz: 672a71377c73a0c0a09796d84afebf2cfe03f3a6182626119c3370ab41112249d881152f1dadbe24ba31775475b4463df5d8c42ca2e9f7d6915c080149fab7ab

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+# 0.15.0
+
+`Docker::API::System#events` and `Docker::API::Exec#start` methods that can now receive a block to replace standard output to stdout behavior.
+
+General refactoring and API documentation.
+
 # 0.14.0
 
 Method `Docker::API::Container#archive` is splitted in `#get_archive` and `#put_archive` as per Docker API documentation.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    dockerapi (0.14.0)
+    dockerapi (0.15.0)
       excon (~> 0.76.0)
 
 GEM

data/README.md

@@ -543,18 +543,18 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 |---|---|---|---|
 | Image | Ok | Ok | Ok |
 | Container | Ok | Ok | Ok |
-| Volume | Ok | Ok | 8/14 |
-| Network | Ok | Ok | 8/14 |
-| System | Ok | Ok | 8/14 |
-| Exec | Ok | Ok | 8/14 |
-| Swarm | Ok | Ok | 8/21 |
-| Node | Ok | Ok | 8/21 |
-| Service | Ok | Ok | 8/21 |
-| Task | Ok | Ok | 8/28 |
-| Secret | Ok | Ok | 8/28 |
-| Config | Ok | Ok | 8/28 |
-| Distribution | Ok | Ok | 8/28 |
-| Plugin | Ok | Ok | 8/28 |
+| Volume | Ok | Ok | Ok |
+| Network | Ok | Ok | Ok |
+| System | Ok | Ok | Ok |
+| Exec | Ok | Ok | Ok |
+| Swarm | Ok | Ok | 8/11 |
+| Node | Ok | Ok | 8/11 |
+| Service | Ok | Ok | 8/11 |
+| Task | Ok | Ok | 8/11 |
+| Secret | Ok | Ok | 8/11 |
+| Config | Ok | Ok | 8/14 |
+| Distribution | Ok | Ok | 8/14 |
+| Plugin | Ok | Ok | 8/14 |
 
 Add doc in these files: `base`, `connection`, `error`, `response`, `dockerapi`
 

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
+    ##
+    # 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.call : 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/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/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.call : 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
+    ##
+    # Returns 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/version.rb

@@ -1,6 +1,6 @@
 module Docker
   module API
-    GEM_VERSION = "0.14.0"
+    GEM_VERSION = "0.15.0"
 
     API_VERSION = "1.40"
 

data/lib/docker/api/volume.rb

@@ -1,42 +1,61 @@
-module Docker
-    module API
-        class Volume < Docker::API::Base
-
-            def list params = {}
-                @connection.get(build_path("/volumes", params))
-            end
-
-            def details name
-                @connection.get(build_path([name]))
-            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, params = {}
-                @connection.delete(build_path([name]))
-            end
+##
+# This class represents the Docker API endpoints regarding volumes.
+# @see https://docs.docker.com/engine/api/v1.40/#tag/Volume
+class Docker::API::Volume < Docker::API::Base
+
+    ##
+    # List volumes.
+    #
+    # Docker API: GET
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/VolumeList
+    #
+    # @param params [Hash]: Parameters that are appended to the URL.
+    def list params = {}
+        @connection.get(build_path("/volumes", params))
+    end
 
-            def prune params = {}
-                @connection.post(build_path(["prune"], params))
-            end
+    ##
+    # Inspect a volume.
+    #
+    # Docker API: GET /volumes/{name}
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/VolumeInspect
+    #
+    # @param name [String]: The ID or name of the volume.
+    def details name
+        @connection.get("/volumes/#{name}")
+    end
 
-            #################################################
-            # Items in this area to be removed before 1.0.0 #
-            #################################################
-            def base_path
-                "/volumes"
-            end
+    ##
+    # Create a volume.
+    #
+    # Docker API: POST /volumes/create
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/VolumeCreate
+    #
+    # @param body [Hash]: Request body to be sent as json.
+    def create body = {}
+        @connection.request(method: :post, path: "/volumes/create", headers: {"Content-Type": "application/json"}, body: body.to_json)
+    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]
-                @connection.get(build_path([name]))
-            end
-            #################################################
+    ##
+    # Remove a volume.
+    #
+    # Docker API: DELETE /volumes/{name}
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/VolumeDelete
+    #
+    # @param name [String]: The ID or name of the volume.
+    # @param params [Hash]: Parameters that are appended to the URL.
+    def remove name, params = {}
+        @connection.delete(build_path("/volumes/#{name}",params))
+    end
 
-        end
+    ##
+    # Delete unused volumes.
+    #
+    # Docker API: POST /volumes/prune
+    # @see https://docs.docker.com/engine/api/v1.40/#operation/VolumePrune
+    #
+    # @param params [Hash]: Parameters that are appended to the URL.
+    def prune params = {}
+        @connection.post(build_path("/volumes/prune", params))
     end
-end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dockerapi
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.0
 platform: ruby
 authors:
 - Alysson A. Costa
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-08-05 00:00:00.000000000 Z
+date: 2020-08-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: excon