dockerapi 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 756ada080034328ec7c5e7950d5565e6e7d3612bc92af58d9c8f89558a75f5c5
-  data.tar.gz: cba4ac000ef8e9d4374bc36be4e87dd3c2227b2fa59cc062f24ad7a06de11c52
+  metadata.gz: 4e010cc4d2a5c4aa102ffe7cd9d58e7e4823bf4ba9079f9a622cb021dad8cd0e
+  data.tar.gz: 47163ffb19a35b4a473da7f88f40d5eac418a15638ccc8d91b6b1672a1af09f6
 SHA512:
-  metadata.gz: 0c6c059fa47afc4749dac18c62d61a984c2874b41046c2926d7eb884a7761ea088fef4209deaf71fe5864e5351e8e96a975f29520760ae6559209d323dd4f4b6
-  data.tar.gz: 25bad2ed4c92a2b5551d78e3a12833037623e7f26045a829b587d4136c383d7431ae7a3d17bf6b9ca139c4fcc060cbf07f15a61854a4a43f601455613174f943
+  metadata.gz: b48b06f99c46c936d4458a1908c08fe13f862ce7c63394077f52d8b621b2eb9e0be959682227f9b7ba59946f18b9098f2983a4bf1a781d16218ad66b08c730a3
+  data.tar.gz: ee2cb40d653054ea9bb559b9d39f43dd28556dcc25374033904f5c292403e371176ce1233636209bd5678df06f90436f6214aaafadd255d0b438cc870c318591

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+# 0.8.0
+
+Add Docker::API::Swarm methods:
+* init
+* update
+* inspect
+* unlock_key
+* unlock
+* join
+* leave
+
+Add Docker::API::Node methods:
+* list
+* inspect
+* update
+* delete
+
+Query parameters and request body json can now skip the validation step with `:skip_validation => true` option.
+
 # 0.7.0
 
 Major changes: Docker::API::Connection is now a regular class intead of a Singleton, allowing multiple connections to be stablished within the same program (replacing the connect_to implementation). To leverage this feature, API-related classes must be initialized and may or may not receive a Docker::API::Connection as parameter, or it'll connect to /var/run/docker.sock by default. For this reason, class methods were replaced with instance methods. Documentation will reflect this changes of implementation.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    dockerapi (0.7.0)
+    dockerapi (0.8.0)
       excon (~> 0.74.0)
 
 GEM

data/README.md

@@ -249,6 +249,56 @@ print response.data[:stream]
 exe.inspect(id)
 ```
 
+### Swarm
+```ruby
+# Connect to local swarm endpoints
+swarm = Docker::API::Swarm.new
+
+# Init swarm
+swarm.init({AdvertiseAddr: "local-ip-address:2377", ListenAddr: "0.0.0.0:4567"})
+
+# Inspect swarm
+swarm.inspect
+
+# Update swarm
+swarm.update(version, {rotateWorkerToken: true})
+swarm.update(version, {rotateManagerToken: true})
+swarm.update(version, {rotateManagerUnlockKey: true})
+swarm.update(version, {EncryptionConfig: { AutoLockManagers: true }})
+
+# Get unlock key
+swarm.unlock_key
+
+# Unlock swarm
+swarm.unlock(UnlockKey: "key-value")
+
+# Join an existing swarm
+swarm.join(RemoteAddrs: ["remote-manager-address:2377"], JoinToken: "Join-Token-Here")
+
+# Leave a swarm
+swarm.leave(force: true)
+```
+
+### Node
+```ruby
+# Connect to local node endpoints
+node = Docker::API::Node.new
+
+# List nodes
+node.list
+
+# Inspect node
+node.inspect("node-id")
+
+# Update node (version, Role and Availability must be present)
+node.update("node-id", {version: "version"}, {Role: "worker", Availability: "pause" })
+node.update("node-id", {version: "version"}, {Role: "worker", Availability: "active" })
+node.update("node-id", {version: "version"}, {Role: "manager", Availability: "active" })
+
+# Delete node
+node.delete("node-id")
+```
+
 ### Connection
 
 By default Docker::API::Connection will connect to local Docker socket at `/var/run/docker.sock`. See examples below to use a different path or connect to a remote address.
@@ -311,6 +361,8 @@ response.success?
 
 `Docker::API::InvalidParameter` and `Docker::API::InvalidRequestBody` may be raised when an invalid option is passed as argument (ie: an option not described in Docker API documentation for request query parameters nor request body (json) parameters). Even if no errors were raised, consider validating the status code and/or message of the response to check if the Docker daemon has fulfilled the operation properly.
 
+To completely skip the validation process, add `:skip_validation => true` in the hash to be validated.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -319,28 +371,19 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ### Road to 1.0.0
 
-NS: Not Started
-
-WIP: Work In Progress
-
-
 | Class | Tests | Implementation | Refactoring |
 |---|---|---|---|
-| Container | Ok | Ok | NS |
-| Image | Ok | Ok | NS |
-| Volume | Ok | Ok | NS |
-| Network | Ok | Ok | NS |
-| System | Ok | Ok | NS |
-| Exec | Ok | Ok | NS |
-| Swarm | NS | NS | NS |
-| Node | NS | NS | NS |
-| Service | NS | NS | NS |
-| Task | NS | NS | NS |
-| Secret | NS | NS | NS |
-
-Misc: 
-* ~~Improve response object~~
-* ~~Improve error objects~~
+| Container | Ok | Ok | 7/24 |
+| Image | Ok | Ok | 7/31 |
+| Volume | Ok | Ok | 8/7 |
+| Network | Ok | Ok | 8/7 |
+| System | Ok | Ok | 8/7 |
+| Exec | Ok | Ok | 8/7 |
+| Swarm | Ok | Ok | 8/14 |
+| Node | Ok | Ok | 8/14 |
+| Service | 7/17 | 7/17 | 8/14 |
+| Task | 7/17 | 7/17 | 8/14 |
+| Secret | 7/17 | 7/17 | 8/14 |
 
 ## Contributing
 

data/lib/docker/api/base.rb

@@ -3,16 +3,18 @@ module Docker
         class Base
 
             def initialize connection = nil
+                raise Docker::API::Error.new("Expect connection to be a Docker::API::Connection class") if connection != nil && !connection.is_a?(Docker::API::Connection)
                 @connection = connection || Docker::API::Connection.new
             end
             
             private
 
-            def base_path
+            def base_path # TODO: this method to be removed?
                 "/"
             end
 
             def validate error, permitted, params
+                return if params[:skip_validation]
                 unpermitted = params.keys.map(&:to_s) - permitted.map(&:to_s)
                 raise error.new(permitted, unpermitted) if unpermitted.size > 0
             end
@@ -22,12 +24,12 @@ module Docker
             ## If value is another Hash, it should keep a json syntax {key:value}
             def hash_to_params h
                 p = []
-                h.each { |k,v| p.push( v.is_a?(Hash) ? "#{k}=#{v.to_json}" : "#{k}=#{v}") }
+                h.delete_if{ | k, v | k.to_s == "skip_validation" }.each { |k,v| p.push( v.is_a?(Hash) ? "#{k}=#{v.to_json}" : "#{k}=#{v}") }
                 p.join("&").gsub(" ","")
             end
 
             def build_path path, params = {}
-                p = path.is_a?(Array) ? ([base_path] << path).join("/") : path
+                p = path.is_a?(Array) ? ([base_path] << path).join("/") : path # TODO: this line to be removed?
                 params.size > 0 ? [p, hash_to_params(params)].join("?") : p
             end
 

data/lib/docker/api/node.rb

@@ -0,0 +1,26 @@
+module Docker
+    module API        
+        class Node < Docker::API::Base
+            
+            def list params = {}
+                validate Docker::API::InvalidParameter, [:filters], params
+                @connection.get(build_path("/nodes", params))
+            end
+
+            def inspect name
+                @connection.get("/nodes/#{name}")
+            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
+        end
+    end
+end

data/lib/docker/api/swarm.rb

@@ -0,0 +1,40 @@
+module Docker
+    module API
+        class Swarm < Docker::API::Base
+
+            def init body = {}
+                validate Docker::API::InvalidRequestBody, [:ListenAddr, :AdvertiseAddr, :DataPathAddr, :DataPathPort, :DefaultAddrPool, :ForceNewCluster, :SubnetSize, :Spec], body
+                @connection.request(method: :post, path: build_path("/swarm/init"), headers: {"Content-Type": "application/json"}, body: body.to_json)
+            end
+
+            def update params = {}, body = {}
+                validate Docker::API::InvalidParameter, [:version, :rotateWorkerToken, :rotateManagerToken, :rotateManagerUnlockKey], params
+                validate Docker::API::InvalidRequestBody, [:Name, :Labels, :Orchestration, :Raft, :Dispatcher, :CAConfig, :EncryptionConfig, :TaskDefaults], body
+                @connection.request(method: :post, path: build_path("/swarm/update", params), headers: {"Content-Type": "application/json"}, body: body.to_json)
+            end
+
+            def inspect
+                @connection.get("/swarm")
+            end
+
+            def unlock_key
+                @connection.get(build_path("/swarm/unlockkey"))
+            end
+
+            def unlock body = {}
+                validate Docker::API::InvalidRequestBody, [:UnlockKey], body
+                @connection.request(method: :post, path: build_path("/swarm/unlock"), headers: {"Content-Type": "application/json"}, body: body.to_json)
+            end
+
+            def join body = {}
+                validate Docker::API::InvalidRequestBody, [:ListenAddr, :AdvertiseAddr, :DataPathAddr, :RemoteAddrs, :JoinToken], body
+                @connection.request(method: :post, path: build_path("/swarm/join"), headers: {"Content-Type": "application/json"}, body: body.to_json)
+            end
+
+            def leave params = {}
+                validate Docker::API::InvalidParameter, [:force], params
+                @connection.post(build_path("/swarm/leave", params))
+            end
+        end
+    end
+end

data/lib/docker/api/version.rb

@@ -1,6 +1,6 @@
 module Docker
   module API
-    GEM_VERSION = "0.7.0"
+    GEM_VERSION = "0.8.0"
 
     API_VERSION = "1.40"
 

data/lib/dockerapi.rb

@@ -12,6 +12,8 @@ require "docker/api/volume"
 require "docker/api/network"
 require "docker/api/exec"
 require "docker/api/system"
+require "docker/api/swarm"
+require "docker/api/node"
 
 module Docker
   module API

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dockerapi
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Alysson A. Costa
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-07-05 00:00:00.000000000 Z
+date: 2020-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: excon
@@ -50,7 +50,9 @@ files:
 - lib/docker/api/exec.rb
 - lib/docker/api/image.rb
 - lib/docker/api/network.rb
+- lib/docker/api/node.rb
 - lib/docker/api/response.rb
+- lib/docker/api/swarm.rb
 - lib/docker/api/system.rb
 - lib/docker/api/version.rb
 - lib/docker/api/volume.rb