dockerapi 0.12.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a32e488d06a0afd653bb04ab0ad5131fa8e898973128d7a6661f3d3fa4eae53d
-  data.tar.gz: 641ffcc096f798fbfff057fb1eecc7ce97ad9191c2acf49f5e97c90bf5ceddc5
+  metadata.gz: 1965ae78342ecc9d450e4cc8262352405784881e31231d700dd606a15d9b58eb
+  data.tar.gz: bea7418501d8a3c08ea73f6c6970b08afe7358c7a15e790b7d51011bb69cd721
 SHA512:
-  metadata.gz: 6cda72170483e133b467a399d77fbcc7668793726b8f67beb4235c5eaf74e2d91977c9544f93ee7d3f3c4b681004d9415f939d2d521aa70151d3a580fc15fc86
-  data.tar.gz: d45997041c9d706d2c2d0e2c5e3f5ccaedad51d71cb27ba8538898565e6259e30d7ff11ffa60a5dee9ffca3611ed51ddc96ca68af2a5aff490715b4645297c0d
+  metadata.gz: 91a6a4e8f85632f9294a07ae2e4bee24d4ff79543b1f50d240638b98d5e9bcc792193be15fa6003d97c73ec8f4b5126f0fe7294367160fce16f8eebd689b5198
+  data.tar.gz: 8a9a1b6ee4bbe7f10c0ae1396eb51e2cb246a37f490758a0278dfe7b06612870a4c12886caf01b9a575b255decec7faf5f0f4ef9d49e2df76a3cb80e4ca06776

data/CHANGELOG.md

@@ -1,3 +1,43 @@
+# 0.17.0
+
+New block execution introduced in [PR#1](https://github.com/nu12/dockerapi/pull/1).
+
+# 0.16.0
+
+`Docker::API::Task#logs` method can now receive a block to replace standard output to stdout behavior.
+
+Add `auth_encoder` to provide standard implementation for the authentication header where needed.
+
+# 0.15.0
+
+`Docker::API::System#events` and `Docker::API::Exec#start` methods 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.
+
+The following `Docker::API::Container` methods that can now receive a block:
+* logs (output to stdout)
+* attach (output to stdout)
+* stats (output to stdout)
+* export (write file)
+* get_archive (write file)
+
+# 0.13.0
+
+Add default behavior for file read, write and output to stdout. Whenever a method can receive a block, this default behavior can be replaced.
+
+The following `Docker::API::Image` methods that can now receive a block:
+* export (write file)
+* create (output to stdout)
+* build (output to stdout)
+
+Default output to stdout can be supressed by setting `Docker::API::PRINT_TO_STDOUT` to `false`
+
+Method parameters `params` and `body` will be automatically evaluated whenever they are present in the method's signature.
+
 # 0.12.0
 
 Add `Docker::API::Plugin` methods:

data/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: .
   specs:
-    dockerapi (0.12.0)
-      excon (~> 0.74.0)
+    dockerapi (0.17.0)
+      excon (~> 0.76.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     diff-lcs (1.3)
-    excon (0.74.0)
+    excon (0.76.0)
     rake (12.3.3)
     rspec (3.9.0)
       rspec-core (~> 3.9.0)

data/README.md

@@ -1,6 +1,30 @@
 # dockerapi
 
-Interact directly with Docker API from Ruby code.
+Interact with Docker API directly from Ruby code. Comprehensive implementation (all available endpoints), no local Docker installation required, easily manipulated http responses.
+
+* [Installation](#installation)
+* [Usage](#usage)
+  * [Images](#images)
+  * [Containers](#containers)
+  * [Volumes](#volumes)
+  * [Network](#network)
+  * [System](#system)
+  * [Exec](#exec)
+  * [Swarm](#swarm)
+  * [Node](#node)
+  * [Service](#service)
+  * [Task](#task)
+  * [Secret](#secret)
+  * [Config](#config)
+  * [Plugin](#plugin)
+  * [Connection](#connection)
+  * [Requests](#requests)
+  * [Response](#response)
+  * [Error handling](#error-handling)
+  * [Blocks](#blocks)
+* [Development](#development)
+* [Contributing](#contributing)
+* [License](#license)
 
 ## Installation
 
@@ -8,6 +32,8 @@ Add this line to your application's Gemfile:
 
 ```ruby
 gem 'dockerapi'
+# or
+gem 'dockerapi', github: 'nu12/dockerapi'
 ```
 
 And then execute:
@@ -20,6 +46,12 @@ Or install it yourself as:
 
 ## Usage
 
+The following section will bring you up to speed in order to use most this gem resources with pratical examples. 
+
+If you need more information about the different Docker API endpoints, please see the [Docker API documentation](https://docs.docker.com/engine/api/v1.40/). 
+
+For a more detailed and comprehensive documentation about this gem's API, please see the [documentation page](https://rubydoc.info/gems/dockerapi).
+
 ### Images
 
 ```ruby
@@ -75,13 +107,16 @@ image.prune(filters: {dangling: {"false": true}})
 image.commit(container: container, repo: "my/image", tag: "latest", comment: "Comment from commit", author: "dockerapi", pause: false )
 
 # Build image from a local tar file
-image.build("/path/to/file.tar")
+image.build("/path/to/file.tar", {t: "tag"})
+
+# Build image using private repository
+image.build("/path/to/file.tar", {t: "tag"}, {"https://index.docker.io/v1/" => {username: "janedoe", password: "janedoe"}})
 
 # Build image from a remote tar file
-image.build(nil, remote: "https://url.to/file.tar")
+image.build(nil, {remote: "https://url.to/file.tar", t: "tag"})
 
 # Build image from a remote Dockerfile
-image.build(nil, remote: "https://url.to/Dockerfile")
+image.build(nil, {remote: "https://url.to/Dockerfile", t: "tag"})
 
 # Delete builder cache
 image.delete_cache
@@ -148,7 +183,10 @@ container.stats("nginx", stream: true)
 container.export("nginx", "~/exported_container")
 
 # Get files from container
-container.archive("nginx", "~/html.tar", path: "/usr/share/nginx/html/")
+container.get_archive("nginx", "~/html.tar", path: "/usr/share/nginx/html/")
+
+# Send files to container
+container.put_archive("nginx", "~/html.tar", path: "/usr/share/nginx/html/")
 
 # Stop container
 container.stop("nginx")
@@ -496,31 +534,38 @@ response.success?
 
 To completely skip the validation process, add `:skip_validation => true` in the hash to be validated.
 
+### Blocks
+
+Some methods can receive a block to alter the default execution:
+* Docker::API::Container#logs
+* Docker::API::Container#attach
+* Docker::API::Container#stats
+* Docker::API::Container#export
+* Docker::API::Container#get_archive
+* Docker::API::Image#create
+* Docker::API::Image#build
+* Docker::API::Image#export
+* Docker::API::System#event
+* Docker::API::Exec#start
+* Docker::API::Task#logs
+
+Example:
+```ruby
+=> image = Docker::API::Image.new
+
+=> image.create(fromImage: "nginx:alpine") do | chunk, bytes_remaining, bytes_total | 
+        p chunk.to_s 
+    end
+```
+
+The default blocks can be found in `Docker::API::Base`.
+
 ## 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.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-### Road to 1.0.0
-
-| Class | Tests | Implementation | Refactoring |
-|---|---|---|---|
-| Image | Ok | Ok | 8/7 |
-| Container | Ok | Ok | 8/14 |
-| Volume | Ok | Ok | 8/21 |
-| Network | Ok | Ok | 8/21 |
-| System | Ok | Ok | 8/21 |
-| Exec | Ok | Ok | 8/21 |
-| Swarm | Ok | Ok | 8/28 |
-| Node | Ok | Ok | 8/28 |
-| Service | Ok | Ok | 8/28 |
-| Task | Ok | Ok | 9/4 |
-| Secret | Ok | Ok | 9/4 |
-| Config | Ok | Ok | 9/4 |
-| Distribution | Ok | Ok | 9/4 |
-| Plugin | Ok | 7/24 | 9/4 |
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/nu12/dockerapi.

data/dockerapi.gemspec

@@ -6,8 +6,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Alysson A. Costa"]
   spec.email         = ["alysson.avila.costa@gmail.com"]
 
-  spec.summary       = "Interact directly with Docker API from Ruby code."
-  spec.description   = "Interact directly with Docker API from Ruby code."
+  spec.summary       = "Interact with Docker API from Ruby code."
+  spec.description   = "Interact with Docker API directly from Ruby code. Comprehensive implementation (all available endpoints), no local Docker installation required, easily manipulated http responses."
   spec.homepage      = "https://github.com/nu12/dockerapi"
   spec.license       = "MIT"
   spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
@@ -15,6 +15,7 @@ Gem::Specification.new do |spec|
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/nu12/dockerapi.git"
   spec.metadata["changelog_uri"] = "https://github.com/nu12/dockerapi/blob/master/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://www.rubydoc.info/gems/dockerapi"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -25,5 +26,5 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency("excon", "~> 0.74.0")
+  spec.add_dependency("excon", "~> 0.76.0")
 end

data/lib/docker/api/base.rb

@@ -1,38 +1,110 @@
-module Docker
-    module API
-        class Base
+##
+# Base class to provide general methods, helpers and implementations accross classes.
+class Docker::API::Base
+    
+    ##
+    # Creates new object and sets the validation to happen automatically when method parameters include "params" or "body".
+    #
+    # @param connection [Docker::API::Connection]: Connection to be used.
+    def initialize connection = nil
+        raise Docker::API::Error.new("Expected connection to be a Docker::API::Connection class") if connection != nil && !connection.is_a?(Docker::API::Connection)
+        @connection = connection || Docker::API::Connection.new
+        set_automated_validation
+    end
+    
+    private
 
-            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
+    ##
+    # Outputs to stdout.
+    def default_streamer
+        streamer = lambda do |chunk, remaining_bytes, total_bytes|
+            p chunk.to_s.encode('UTF-8', invalid: :replace, undef: :replace, replace: '?') if Docker::API::PRINT_TO_STDOUT
+        end
+        streamer
+    end
 
-            def base_path # TODO: this method to be removed?
-                "/"
-            end
+    ##
+    # Writes file.
+    #
+    # @param path [String]: Path to the file to be writen.
+    def default_writer path
+        streamer = lambda do |chunk, remaining_bytes, total_bytes|
+            return if "#{chunk}".match(/(No such image)/)
+            file = File.open(File.expand_path(path), "wb+")
+            file.write(chunk)
+            file.close
+        end
+        streamer
+    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
+    ##
+    # Reads file.
+    #
+    # @param path [String]: Path to the file to be read.
+    # @param url [String]: Endpoint URL where the file is going to be sent.
+    # @param header [Hash]: Header of the request.
+    # @param &block: Replace the default output to stdout behavior.
+    def default_reader path, url, header = {"Content-Type" => "application/x-tar"}, &block
+        file = File.open(File.expand_path(path), "r")
+        response = @connection.request(method: :post, path: url , headers: header, request_block: lambda { file.read(Excon.defaults[:chunk_size]).to_s}, response_block: block_given? ? block : default_streamer )
+        file.close
+        response
+    end
 
-            ## Converts Ruby Hash into query parameters
-            ## In general, the format is key=value
-            ## If value is another Hash, it should keep a json syntax {key:value}
-            def hash_to_params h
-                p = []
-                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
+    ##
+    # Encodes the authentication parameters.
+    #
+    # @param authentication [Hash]: Parameters to be encoded.
+    def auth_encoder(authentication)
+        Base64.urlsafe_encode64(authentication.to_json.to_s).chomp
+    end
 
-            def build_path path, params = {}
-                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
+    ##
+    # Validates a Hash object comparing its keys with a given Array of permitted values. Raise an error if the validation fail.
+    #
+    # @param error [Error]: Error to be raised of the validation fail.
+    # @param permitted [Array]: List of permitted keys.
+    # @param params [Hash]: Hash object to be validated.
+    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
+
+    ##
+    # Converts Ruby Hash into URL query parameters.
+    #
+    # In general, query parameters' format is "key=value", but if "value" is another Hash, it should change to a json syntax {key:value}.
+    #
+    # @param hash [Hash]: Hash object to be converted in a query parameter-like string.
+    def hash_to_params hash
+        p = []
+        hash.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
 
+    ##
+    # Builds an URL string using the base path and a set of parameters.
+    #
+    # @param path [String]: Base URL string.
+    # @param hash [Hash]: Hash object to be appended to the URL as query parameters.
+    def build_path path, params = {}
+        params.size > 0 ? [path, hash_to_params(params)].join("?") : path
+    end
+
+    ##
+    # Sets the validation to happen automatically when method parameters include "params" or "body".
+    def set_automated_validation
+        (self.methods - Object.methods).each do |method|
+            params_index = method(method).parameters.map{|ar| ar[1]}.index(:params)
+            body_index = method(method).parameters.map{|ar| ar[1]}.index(:body)
+
+            define_singleton_method(method) do |*args, &block|
+                validate Docker::API::InvalidParameter, Docker::API::VALID_PARAMS["#{self.class.name}"]["#{method}"], (args[params_index] || {}) if params_index
+                validate Docker::API::InvalidRequestBody, Docker::API::VALID_BODY["#{self.class.name}"]["#{method}"], (args[body_index] || {}) if body_index
+                super(*args,&block)
+            end
         end
     end
+
 end

data/lib/docker/api/config.rb

@@ -13,7 +13,6 @@ class Docker::API::Config < Docker::API::Base
     #
     # @param params [Hash]: Parameters that are appended to the URL.
     def list params = {}
-        validate Docker::API::InvalidParameter, [:filters], params
         @connection.get(build_path("/configs",params))
     end
 
@@ -25,7 +24,6 @@ class Docker::API::Config < Docker::API::Base
     #
     # @param body [Hash]: Request body to be sent as json.
     def create body = {}
-        validate Docker::API::InvalidRequestBody, [:Name, :Labels, :Data, :Templating], body
         @connection.request(method: :post, path: "/configs/create", headers: {"Content-Type": "application/json"}, body: body.to_json)
     end
 
@@ -52,8 +50,6 @@ class Docker::API::Config < Docker::API::Base
     #
     # @param body [Hash]: Request body to be sent as json.
     def update name, params = {}, body = {}
-        validate Docker::API::InvalidParameter, [:version], params
-        validate Docker::API::InvalidRequestBody, [:Name, :Labels, :Data, :Driver, :Templating], body
         @connection.request(method: :post, path: build_path("/configs/#{name}/update",params), headers: {"Content-Type": "application/json"}, body: body.to_json)
     end
 

data/lib/docker/api/connection.rb

@@ -1,20 +1,26 @@
-module Docker
-    module API
-        class Connection
-            [:get, :post, :head, :delete, :put].each do | method |
-                define_method(method) { | path | self.request(method: method, path: path) }
-            end
-
-            def request params
-                Docker::API::Response.new(@connection.request(params).data)
-            end
-            
-            def initialize url = nil, params = nil
-                url ||= 'unix:///'
-                params ||= url == 'unix:///' ? {socket: '/var/run/docker.sock'} : {}
-                @connection = Excon.new(url, params)
-            end
+##
+# Connection class.
+class Docker::API::Connection
+    [:get, :post, :head, :delete, :put].each do | method |
+        define_method(method) { | path | self.request(method: method, path: path) }
+    end
 
-        end
+    ##
+    # Calls an Excon request and returns a Docker::API::Response object.
+    #
+    # @param params [Hash]: Request parameters.
+    def request params
+        Docker::API::Response.new(@connection.request(params).data)
     end
+    
+    ##
+    # Creates an Excon connection.
+    #
+    # @param url [String]: URL for the connection.
+    # @param params [String]: Additional parameters.
+    def initialize url = nil, params = nil
+        return @connection = Excon.new('unix:///', {socket: '/var/run/docker.sock'}) unless url
+        @connection = Excon.new(url, params || {})
+    end
+
 end