dockerapi 0.11.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09aa5bf2a46df8ad42f1c4833fe7577610af14dde350730787b703e1080fa4c7'
-  data.tar.gz: 0be7a47781bbc7f75824f65b8fea5d7bcbd11deb98451f2b030856391a68d5c1
+  metadata.gz: 8207aa413525c868d4e1c0f57cacf38c19348dee819da2aeb63f390d5ac41f28
+  data.tar.gz: 53406674405580c0dcb91c4c32a914ef0de92ce9a9c1132eb7bf046902e5adc8
 SHA512:
-  metadata.gz: f0573e091c6cbbc6c2fa3411ca6336a328e4677a656f22bd7d4a036064f8c813523c6a686c2e3ec03df2ec194f65c1b69c6d5be5782c1a1fca80460f3c383db9
-  data.tar.gz: 5fa96ad226aad3faa2e3a2836948687adf29079b0495e88ceb42424bbe14d2664cab4a8f59a2a795e2f73c9fe59318504a9c454b4964d1b16a04165023c7e8f8
+  metadata.gz: be5d82c94e72b29d4341330b3c12f4a2007c6e46813cca6eb6cc8ba3f3a0adae2cd8ef00d0020ed1d59bf5bfc12bf6b22f6b3dd96eb5287ee03f02e14f1bb0ce
+  data.tar.gz: f4155422936cd0a4e754d4f32a118662c1d6ace28d788aae51e4d09f09b817519ed7ec0bca9e1955bcb2edc66c5ea111181493e43d398de20e4662d665ac8d2b

data/CHANGELOG.md

@@ -1,3 +1,54 @@
+# 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:
+* list
+* privileges
+* install
+* details
+* remove
+* enable
+* disable
+* upgrade
+* create
+* push
+* configure
+
 # 0.11.0
 
 Add `Docker::API::Task` methods:

data/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: .
   specs:
-    dockerapi (0.11.0)
-      excon (~> 0.74.0)
+    dockerapi (0.16.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,29 @@
 # 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)
+* [Development](#development)
+* [Contributing](#contributing)
+* [License](#license)
 
 ## Installation
 
@@ -8,6 +31,8 @@ Add this line to your application's Gemfile:
 
 ```ruby
 gem 'dockerapi'
+# or
+gem 'dockerapi', github: 'nu12/dockerapi'
 ```
 
 And then execute:
@@ -20,6 +45,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 +106,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 +182,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")
@@ -391,9 +428,50 @@ config.update("config-name", {version: version}, spec.merge!({ Data: "VEhJUyBJUy
 config.delete("config-name")
 ```
 
+### Plugin
+```ruby
+# Connect to local plugin endpoints
+plugin = Docker::API::Plugin.new
+
+# List plugins
+plugin.list
+
+# List plugin's privileges
+plugin.privileges(remote: "plugin-name")
+
+# Install plugin (using defined privileges)
+privileges = plugin.privileges(remote: "plugin-name")
+plugin.install({remote: "plugin-name"}, privileges)
+
+# Upgrade plugin (using defined privileges)
+privileges = plugin.privileges(remote: "plugin-name2")
+plugin.upgrade("plugin-name", {remote: "plugin-name2"}, privileges)
+
+# Enable plugin
+plugin.enable("plugin-name", timeout: 0)
+
+# Disable plugin
+plugin.disable("plugin-name")
+
+# Configure plugin
+plugin.configure("plugin-name", ["DEBUG=1"])
+
+# Inspect plugin
+plugin.details("plugin-name")
+
+# Remove plugin
+plugin.remove("plugin-name")
+
+# Create plugin (tar file must contain rootfs folder and config.json file)
+plugin.create("name", "/path/to/file.tar")
+
+# Push plugin
+plugin.push("name")
+```
+
 ### 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.
+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.
 
 ```ruby
 # Setting different connections
@@ -465,20 +543,19 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 | 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 | 7/24 | 7/24 | 9/4 |
+| Image | Ok | Ok | Ok |
+| Container | Ok | Ok | Ok |
+| Volume | Ok | Ok | Ok |
+| Network | Ok | Ok | Ok |
+| System | Ok | Ok | Ok |
+| Exec | Ok | Ok | Ok |
+| Swarm | Ok | Ok | Ok |
+| Node | Ok | Ok | Ok |
+| Service | Ok | Ok | Ok |
+| Task | Ok | Ok | Ok |
+| Secret | Ok | Ok | Ok |
+| Config | Ok | Ok | 8/14 |
+| Plugin | Ok | Ok | 8/14 |
 
 ## Contributing
 

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.call : 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