dockerapi 0.13.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0dac991f7f237b1df6314bae40e54a5f44175186bbbb6756184c65862bb9f652
-  data.tar.gz: 604ea213a309219a91b6923e89e8003eb030fff51d22104e8c689872264ebd59
+  metadata.gz: 4117775ffcd9a7ba657bbea943fd20e52de1907fcf3174850a48b8ede27a7acf
+  data.tar.gz: 6d7a725d087401b8d1a2806e6deee5066ed6ad3bc8f195ffcda1321b3fc2252b
 SHA512:
-  metadata.gz: d5f2eb58e059da1f60de416b07902e538ad707ec1a95a4efb665073d3b54a3ab74ea101144f9cea51effd50610ece9e0011061c653d848855885399bcb6b1cdd
-  data.tar.gz: 98e253a61bd7c2ff36df30f9e3557d4c502e10e206c7b5a32d2969e9ec996151741a5bda5a46ef32426905236228caaba57485250a7f7561fb98cd2181052b86
+  metadata.gz: 158707ec44efb0d7ac3123e988c670af94cd9ad054bf47dfbf6d75c2ffd516f87f85296f9732a98213913e1b827dc3de582fff7fabc25f4c359c50f704b6f1ea
+  data.tar.gz: 62b262e3d7fcffaaa1cec28f6dd9246619abfecfcd88b85fd90e2f18fc46806135fc17c149dc26e5a5687b4e426b5a98ad60e87b8763af4949f096280d3b229c

data/.github/workflows/ruby.yml

@@ -0,0 +1,35 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Ruby
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+    # uses: ruby/setup-ruby@v1
+      uses: ruby/setup-ruby@21351ecc0a7c196081abca5dc55b08f085efe09a
+      with:
+        ruby-version: 2.6
+    - name: Install Docker
+      run: curl https://get.docker.com | sh
+    - name: Install dependencies
+      run: bin/setup && sudo bin/setup
+    - name: Run tests
+      run: rake spec

data/.gitignore

@@ -9,3 +9,7 @@
 
 # rspec failure tracking
 .rspec_status
+
+resources/registry_authentication/*.key
+resources/registry_authentication/*.crt
+resources/registry_authentication/htpasswd

data/CHANGELOG.md

@@ -1,3 +1,38 @@
+# 0.18.0
+
+Method `Docker::API::Image#distribution` now accepts authentication parameters. Feature introduced in [PR#3](https://github.com/nu12/dockerapi/pull/3)
+
+Contributors: @zarqman
+
+# 0.17.0
+
+New block execution introduced in [PR#1](https://github.com/nu12/dockerapi/pull/1).
+
+Contributors: @zarqman
+
+# 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.

data/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: .
   specs:
-    dockerapi (0.13.0)
-      excon (~> 0.74.0)
+    dockerapi (0.18.0)
+      excon (~> 0.76)
 
 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
@@ -46,6 +78,7 @@ image.details("image")
 
 # Return image digest and platform information by contacting the registry.
 image.distribution("image")
+image.distribution("image", {username: "janedoe", password: "password"}) # private repository
 
 # History
 image.history("image")
@@ -62,7 +95,7 @@ image.tag("current:tag", repo: "new", tag: "tag")
 # Push image
 image.push("repo:tag") # to dockerhub
 image.push("localhost:5000/repo:tag") # to local registry
-image.push("private/repo", {tag: "tag"}, {username: "janedoe", password: "password"} # to private repository
+image.push("private/repo", {tag: "tag"}, {username: "janedoe", password: "password"}) # to private repository
 
 # Remove image
 image.remove("image")
@@ -151,7 +184,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")
@@ -499,32 +535,46 @@ 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 | Ok |
-| 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 | Ok | 9/4 |
-
-Add doc in these files: `base`, `connection`, `error`, `response`, `dockerapi`
+### Release nre version
+
+* Update CHANGELOG.
+* Update README as needed.
+* Update version.
+* Run tests.
+* Commit changes.
+* Release / push version to Rubygems & Github.
 
 ## Contributing
 

data/bin/setup

@@ -18,5 +18,13 @@ then
 else
     echo "Running bundle install"
     bundle install
+
+    echo "Creating self-signed certificate to use in tests"
+    openssl req -newkey rsa:2048 -nodes -keyout resources/registry_authentication/registry_auth.key -x509 -days 365 -out resources/registry_authentication/registry_auth.crt -subj "/C=CL/ST=Santiago/L=Santiago/O=dockerapi/OU=dockerapi/CN=dockerapi"
+
+    echo "Creating htpasswd file to use in tests"
+    docker run --rm --entrypoint htpasswd registry:2.7.0 -Bbn janedoe password > resources/registry_authentication/htpasswd
+    docker image rm registry:2.7.0
     echo "Run this script as root for further configurations"
-fi
+fi
+

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,15 +15,16 @@ 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.
   spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|resources)/}) }.append("doc")
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|resources)/}) }
   end
   spec.bindir        = "exe"
   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")
 end

data/lib/docker/api/base.rb

@@ -1,24 +1,21 @@
+##
+# Base class to provide general methods, helpers and implementations accross classes.
 class Docker::API::Base
     
-
+    ##
+    # Create 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
-        
-        (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
+        set_automated_validation
     end
     
     private
 
+    ##
+    # Output 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
@@ -26,6 +23,10 @@ class Docker::API::Base
         streamer
     end
 
+    ##
+    # Write file to disk.
+    #
+    # @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)/)
@@ -36,31 +37,74 @@ class Docker::API::Base
         streamer
     end
 
+    ##
+    # Read file from disk.
+    #
+    # @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 )
+        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
 
+    ##
+    # Encode authentication parameters.
+    #
+    # @param authentication [Hash]: Parameters to be encoded.
+    def auth_encoder(authentication)
+        Base64.urlsafe_encode64(authentication.to_json.to_s).chomp
+    end
+
+    ##
+    # Validate 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 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
+    ##
+    # Convert 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 = []
-        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}") }
+        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
 
+    ##
+    # Build 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 = {}
-        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
+        params.size > 0 ? [path, hash_to_params(params)].join("?") : path
+    end
+
+    ##
+    # Set 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/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
+    ##
+    # Call 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
+    
+    ##
+    # Create 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