dockerapi 0.10.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aeb3c1971c26c62d0737576e5ec79f2abcf536b1148be5272be8f501dfcae852
-  data.tar.gz: 1392073ca52d6fecfc12e642368713c2fa44a9ebbcd7629de5fb54faf9ac7209
+  metadata.gz: a07cc3ef52a91afb13ab99c130cb6cbed118055aba264df3e0fb0a1ec701ef6d
+  data.tar.gz: d9e6e03672a7a47de2cb0fb840569c45582075be679d21995192247633d58d70
 SHA512:
-  metadata.gz: 3b03b8e5ce6d95f19c8dd6d357277a102fcc170b35ac989cd080db27c66efcad63125aaedab1c971a8ed435bed7c7447979d332a1b7f43686a2217907bf21fe8
-  data.tar.gz: 62cd2888ad859834cf949a6189f6e863e1b2f23ce9849fce4a39a1248cfa74efeaff5e0e6220a165d6b7980445a7773dc4bc3f8d4a678fc364a06b205fc07630
+  metadata.gz: 46bbd5e8c6cbb41e13b3830aab5ca8825d37a1c85401dedc33aeba3352657f8410e99c8c321bc5e5d10e9eeac6435769f9b7d7570a8910b7f0d0779a3308381a
+  data.tar.gz: 672a71377c73a0c0a09796d84afebf2cfe03f3a6182626119c3370ab41112249d881152f1dadbe24ba31775475b4463df5d8c42ca2e9f7d6915c080149fab7ab

data/CHANGELOG.md

@@ -1,3 +1,72 @@
+# 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.
+
+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:
+* list
+* details
+* logs
+
+Add `Docker::API::Secret` methods:
+* create
+* update
+* list
+* details
+* delete
+
+Add `Docker::API::Config` methods:
+* create
+* update
+* list
+* details
+* delete
+
+Add `Docker::API::Image` methods:
+* distribution
+
 # 0.10.0
 
 Add `Docker::API::Service` methods:

data/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: .
   specs:
-    dockerapi (0.10.0)
-      excon (~> 0.74.0)
+    dockerapi (0.15.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
 
@@ -20,6 +43,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
@@ -44,6 +73,9 @@ image.list
 # Inspect image
 image.details("image")
 
+# Return image digest and platform information by contacting the registry.
+image.distribution("image")
+
 # History
 image.history("image")
 
@@ -72,13 +104,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
@@ -145,7 +180,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")
@@ -325,12 +363,113 @@ service.details("nginx-service")
 
 # Delete service 
 service.delete("nginx-service")
+```
+
+### Task
+```ruby
+# Connect to local task endpoints
+task = Docker::API::Task.new
+
+# List tasks
+task.list
+
+# View task logs
+task.logs("task-id", stdout: true)
+
+# Inspect service 
+task.details("task-id")
+```
+
+### Secret
+```ruby
+# Connect to local secret endpoints
+secret = Docker::API::Secret.new
+
+# List secrets
+secret.list
+
+# Create a secret
+secret.create({Name: "secret-name", Data: "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg=="})
+
+# Inspect secrets 
+secret.details("secret-name")
+
+# Update a secret (needs version and current Spec)
+version = secret.details( "secret-name" ).json["Version"]["Index"]
+spec = secret.details("secret-name").json["Spec"]
+secret.update("secret-name", {version: version}, spec.merge!({ Data: "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==" }))
+
+# Delete secret
+secret.delete("secret-name")
+```
+
+### Config
+```ruby
+# Connect to local config endpoints
+config = Docker::API::Config.new
+
+# List configs
+config.list
+
+# Create a config
+config.create({Name: "config-name", Data: "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg=="})
+
+# Inspect configs 
+config.details("config-name")
+
+# Update a configs (needs version and current Spec)
+version = config.details( "config-name" ).json["Version"]["Index"]
+spec = config.details("config-name").json["Spec"]
+config.update("config-name", {version: version}, spec.merge!({ Data: "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==" }))
+
+# Delete config
+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
@@ -402,20 +541,22 @@ 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 | 7/17 | 7/17 | 8/28 |
-| Task | 7/17 | 7/17 | 9/4 |
-| Secret | 7/17 | 7/17 | 9/4 |
-| Config | 7/17 | 7/17 | 9/4 |
-| Distribution | 7/17 | 7/17 | 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 | 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`
 
 ## 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,66 @@
-module Docker
-    module API
-        class Base
+class Docker::API::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 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
+        
+        (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)
 
-            def base_path # TODO: this method to be removed?
-                "/"
+            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
+    
+    private
 
-            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
+    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
 
-            ## 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
+    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 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
+    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
 
-        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
+
+    ## 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
+
+    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
+
 end