dockerapi 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1fce5f833c28f2144c012a8aa5c667bdb520b4bc0423a6407263da6597f7bc1e
-  data.tar.gz: 0f7cb0476f93e1fea20f06567e9fd72f168c987d91dd5eb5bf8a0430c976bc92
+  metadata.gz: f647538a729eaa623b009a4e97713761bc80579073ebfb8b9ab7bfa26b6b6d98
+  data.tar.gz: ce3b40c357d635a47ab8c921b59254ef734c2ec1173da60e58ba1b6f7d325ecf
 SHA512:
-  metadata.gz: d8e21c6f481339361c91f74a4134c1a989007e04c88e1192618275f908be0c2436324b5939571ec4fbfbfe462b6872c13e575cef5026fd78b92250809a21582c
-  data.tar.gz: 3167dad7f68cf3395b26de3baf6a595ba42403f52bacc0ec455394aa9e19dd76cb461517c5b9d4a389e6019508a2438ddef12f5ad78cdf4d632c879369de22b1
+  metadata.gz: f845ea3e89761d9ab726f098d4ef4ca1586c92320616359b182d6f9dc24e7769b53c88a6d17d8257514303226b16fd08a841ced1645be68c19b4d4b31a8a9b4f
+  data.tar.gz: 409819921a1135b593377d8c561d0d5f81013f519e98a547976b1563b4038bff91f5948a5cd00b9f7513026821811b9baa476306915b7b644768232238daf0f4

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+# 0.5.0
+
+Add Docker::API::System methods:
+* auth
+* ping
+* info
+* version
+* events
+* df
+
+Add new response class Docker::API::Response with the following methods:
+* json
+* path
+* success?
+
+Error classes output better error messages.
+
 # 0.4.0
 
 Add Docker::API::Network methods:

data/Gemfile.lock

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

data/README.md

@@ -196,13 +196,64 @@ Docker::API::Network.connect( "my-network", Container: "my-container" )
 Docker::API::Network.disconnect( "my-network", Container: "my-container" )
 ```
 
+### System
+
+```ruby
+# Ping docker api
+Docker::API::System.ping
+
+# Docker components versions
+Docker::API::System.version
+
+# System info
+Docker::API::System.info
+
+# System events (stream)
+Docker::API::System.events(until: Time.now.to_i)
+
+# Data usage information
+Docker::API::System.df
+```
+
 ### Requests
 
 Requests should work as described in [Docker API documentation](https://docs.docker.com/engine/api/v1.40). Check it out to customize your requests.
 
 ### Response
 
-All requests return a Excon::Response object.
+All requests return a response class that inherits from Excon::Response. Available attribute readers and methods include: `status`, `data`, `body`, `headers`, `json`, `path`, `success?`.
+
+```ruby
+response = Docker::API::Image.create(fromImage: "busybox:latest")
+
+response
+=> #<Docker::API::Response:0x000055bb390b35c0 ... >
+
+response.status
+=> 200
+
+response.data
+=> {:body=>"...", :cookies=>[], :host=>nil, :headers=>{ ... }, :path=>"/images/create?fromImage=busybox:latest", :port=>nil, :status=>200, :status_line=>"HTTP/1.1 200 OK\r\n", :reason_phrase=>"OK"}
+
+response.headers
+=> {"Api-Version"=>"1.40", "Content-Type"=>"application/json", "Docker-Experimental"=>"false", "Ostype"=>"linux", "Server"=>"Docker/19.03.11 (linux)", "Date"=>"Mon, 29 Jun 2020 16:10:06 GMT"}
+
+response.body
+=> "{\"status\":\"Pulling from library/busybox\" ... "
+
+response.json
+=> [{:status=>"Pulling from library/busybox", :id=>"latest"}, {:status=>"Pulling fs layer", :progressDetail=>{}, :id=>"76df9210b28c"}, ... , {:status=>"Status: Downloaded newer image for busybox:latest"}]
+
+response.path
+=> "/images/create?fromImage=busybox:latest"
+
+response.success?
+=> true
+```
+
+### Error handling
+
+`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.
 
 ## Development
 
@@ -223,7 +274,7 @@ WIP: Work In Progress
 | Image | Ok | Ok | NS |
 | Volume | Ok | Ok | NS |
 | Network | Ok | Ok | NS |
-| System | NS | NS | NS |
+| System | Ok | Ok | NS |
 | Exec | NS | NS | NS |
 | Swarm | NS | NS | NS |
 | Node | NS | NS | NS |
@@ -232,8 +283,8 @@ WIP: Work In Progress
 | Secret | NS | NS | NS |
 
 Misc: 
-* Improve response object
-* Improve error objects
+* ~~Improve response object~~
+* ~~Improve error objects~~
 
 ## Contributing
 

data/lib/docker/api/base.rb

@@ -12,9 +12,9 @@ module Docker
                 Docker::API::Connection.instance
             end
 
-            def self.validate error, permitted_keys, params
-                not_permitted = params.keys.map(&:to_s) - permitted_keys.map(&:to_s)
-                raise error if not_permitted.size > 0
+            def self.validate error, permitted, params
+                unpermitted = params.keys.map(&:to_s) - permitted.map(&:to_s)
+                raise error.new(permitted, unpermitted) if unpermitted.size > 0
             end
 
             ## Converts Ruby Hash into query parameters

data/lib/docker/api/connection.rb

@@ -1,6 +1,4 @@
-require "excon"
 require "singleton"
-require "json"
 module Docker
     module API
         class Connection
@@ -15,7 +13,7 @@ module Docker
             end
 
             def request params
-                @connection.request(params)
+                Docker::API::Response.new(@connection.request(params).data)
             end
             
             private

data/lib/docker/api/error.rb

@@ -1,6 +1,17 @@
 module Docker
     module API
-      class InvalidParameter < StandardError; end
-      class InvalidRequestBody < StandardError; end
+      class ValidationError < StandardError
+        def initialize permitted, unpermitted
+          super("Unpermitted options found: #{unpermitted.to_s}. Permitted are #{permitted.to_s}")
+        end
+      end
+      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/image.rb

@@ -107,7 +107,7 @@ module Docker
             end
 
             def self.build path, params = {}, authentication = {}
-                raise Docker::API::InvalidRequestBody unless path || params[:remote] 
+                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"}

data/lib/docker/api/response.rb

@@ -0,0 +1,25 @@
+module Docker
+    module API
+        class Response < Excon::Response
+            attr_reader(:json, :path)
+
+            def initialize data
+                super data
+                @json = parse_json @body
+                @path = @data[:path]
+            end
+
+            def success?
+                (200..204).include? @status
+            end
+
+            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
+    end
+end

data/lib/docker/api/system.rb

@@ -7,6 +7,27 @@ module Docker
                 validate Docker::API::InvalidRequestBody, [:username, :password, :email, :serveraddress, :identitytoken], body
                 connection.request(method: :post, path: "/auth", headers: { "Content-Type" => "application/json" }, body: body.to_json)
             end
+
+            def self.events params = {}
+                validate Docker::API::InvalidParameter, [:since, :until, :filters], params
+                connection.request(method: :get, path: build_path("/events", params), response_block: lambda { |chunk, remaining_bytes, total_bytes| puts chunk.inspect } )
+            end
+
+            def self.ping
+                connection.get("/_ping")
+            end
+
+            def self.info
+                connection.get("/info")
+            end
+
+            def self.version
+                connection.get("/version")
+            end
+
+            def self.df
+                connection.get("/system/df")
+            end
         end
     end
 end

data/lib/docker/api/version.rb

@@ -1,6 +1,6 @@
 module Docker
   module API
-    GEM_VERSION = "0.4.0"
+    GEM_VERSION = "0.5.0"
 
     API_VERSION = "1.40"
 

data/lib/dockerapi.rb

@@ -1,7 +1,10 @@
-require "docker/api/version"
+require "excon"
+require "json"
 
+require "docker/api/version"
 require "docker/api/error"
 require "docker/api/connection"
+require "docker/api/response"
 require "docker/api/base"
 require "docker/api/container"
 require "docker/api/image"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dockerapi
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Alysson A. Costa
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-06-28 00:00:00.000000000 Z
+date: 2020-06-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: excon
@@ -49,6 +49,7 @@ files:
 - lib/docker/api/error.rb
 - lib/docker/api/image.rb
 - lib/docker/api/network.rb
+- lib/docker/api/response.rb
 - lib/docker/api/system.rb
 - lib/docker/api/version.rb
 - lib/docker/api/volume.rb