docker-api 1.15.0 → 1.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 026147324341d46ecc633b106fa941316435e612
-  data.tar.gz: c9022722fa623436a9a7f5b5ece2383c946eb21d
+  metadata.gz: d13e05e91b0dbfbae522e12e17e7a6785347f5b7
+  data.tar.gz: 83e0f7511f3e284747d4cabbbb3a69cf701ed5d4
 SHA512:
-  metadata.gz: 0361890e0d8bd23b86c4b1cc362a4f7d5f327222ea0261c8a1159daaa331f5b7b90d5a93e8142558fd2e514b5d22ff7481fa80b60fc6fb64a55c6868e6bff1b6
-  data.tar.gz: 4d22cb2d2fb45120b9a7485e4be4e8a35b56085287c397ae624be1d6c6036acfe4cbb57879afa096fa8089d3e03524f54542841c9ae626087611086fee07a57f
+  metadata.gz: a8f18cbb168d6808180a9adac203a94b37bf82d9bbb43bf9fe9c63fd9dba4b7baab4756cee3a3d9eb30e9cbf0c9a178d6d8506faca9d32656620f162bb5f6571
+  data.tar.gz: dd860931831eceadb0bae490710edbc6f52189c918999b0edb41b2d3c88961a53359bf597eee953869745730279e8d68ec6fa146a3eca06f1395e8e58d26ccda

data/README.md

@@ -286,6 +286,32 @@ container.commit
 container.run('pwd', 10)
 # => Docker::Image { :id => 4427be4199ac, :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } }
 
+# Run an Exec instance inside the container and capture its output
+container.exec('date')
+# => [["Wed Nov 26 11:10:30 CST 2014\n"], []]
+
+# Launch an Exec instance without capturing its output
+container.exec('./my_service', detach: true)
+# => Docker::Exec { :id => be4eaeb8d28a, :connection => Docker::Connection { :url => tcp://localhost, :options => {:port=>2375} } }
+
+# Parse the output of an Exec instance
+container.exec('find / -name *') { |stream, chunk| puts "#{stream}: #{chunk}" }
+stderr: 2013/10/30 17:16:24 Unable to locate find / -name *
+# => [[], ["2013/10/30 17:16:24 Unable to locate find / -name *\n"]]
+
+# Run an Exec instance by grab only the STDOUT output
+container.exec('date', stderr: false)
+# => [["Wed Nov 26 11:10:30 CST 2014\n"], []]
+
+# Pass input to an Exec instance command via Stdin
+container.exec('cat', stdin: StringIO.new("foo\nbar\n"))
+# => [["foo\nbar\n"], []]
+
+# Get the raw stream of data from an Exec instance
+command = ["bash", "-c", "if [ -t 1 ]; then echo -n \"I'm a TTY!\"; fi"]
+container.exec(command, tty: true)
+# => [["I'm a TTY!"], []]
+
 # Delete a Container.
 container.delete(:force => true)
 # => nil
@@ -340,4 +366,3 @@ License
 -----
 
 This program is licensed under the MIT license. See LICENSE for details.
-

data/Rakefile

@@ -15,6 +15,43 @@ Cane::RakeTask.new(:quality) do |cane|
   cane.canefile = '.cane'
 end
 
+dir = File.expand_path(File.dirname(__FILE__))
+namespace :vcr do
+  desc 'Run the full test suite from scratch'
+  task :spec => [:unpack, :record]
+
+  desc 'Download the necessary base images'
+  task :unpack do
+    %w( registry busybox tianon/true scratch ).each do |image|
+      system "docker pull #{image}"
+    end
+  end
+
+  desc 'Run spec tests and record VCR cassettes'
+  task :record do
+    begin
+      FileUtils.remove_dir("#{dir}/spec/vcr", true)
+      registry = Docker::Container.create(
+        'name' => 'registry',
+        'Image' => 'registry',
+        'Env' => ["GUNICORN_OPTS=[--preload]"],
+        'ExposedPorts' => {
+          '5000/tcp' => {}
+        },
+        'HostConfig' => {
+          'PortBindings' => { '5000/tcp' => [{ 'HostPort' => '5000' }] }
+        }
+      )
+      registry.start
+      Rake::Task["spec"].invoke
+    rescue
+      # nothing
+    ensure
+      registry.kill!.remove
+    end
+  end
+end
+
 desc 'Pull an Ubuntu image'
 image 'ubuntu:13.10' do
   puts "Pulling ubuntu:13.10"

data/TESTING.md

@@ -0,0 +1,61 @@
+# Prerequisites
+To develop on this gem, you must the following installed:
+* a sane Ruby 1.9+ environment with `bundler`
+```shell
+$ gem install bundler
+```
+* Docker v1.3.1 or greater
+
+
+
+# Getting Started
+1. Clone the git repository from Github:
+```shell
+$ git clone git@github.com:swipely/docker-api.git
+```
+2. Install the dependencies using Bundler
+```shell
+$ bundle install
+```
+3. Create a branch for your changes
+```shell
+$ git checkout -b my_bug_fix
+```
+4. Make any changes
+5. Write tests to support those changes.  
+6. Run the tests:
+  * `bundle exec rake vcr:test`
+7. Assuming the tests pass, open a Pull Request on Github.
+
+# Using Rakefile Commands
+This repository comes with five Rake commands to assist in your testing of the code.
+
+## `rake spec`
+This command will run Rspec tests normally on your local system. Be careful that VCR will behave "weirdly" if you currently have the Docker daemon running.
+
+## `rake quality`
+This command runs a code quality threshold checker to hinder bad code.
+
+## `rake vcr`
+This gem uses [VCR](https://relishapp.com/vcr/vcr) to record and replay HTTP requests made to the Docker API. The `vcr` namespace is used to record and replay spec tests inside of a Docker container. This will allow each developer to run and rerecord VCR cassettes in a consistent environment.
+
+### Setting Up Environment Variables
+Certain Rspec tests will require your credentials to the Docker Hub. If you do not have a Docker Hub account, you can sign up for one [here](https://hub.docker.com/account/signup/). To avoid hard-coding credentials into the code the test suite leverages three Environment Variables: `DOCKER_API_USER`, `DOCKER_API_PASS`, and `DOCKER_API_EMAIL`. You will need to configure your work environment (shell profile, IDE, etc) with these values in order to successfully re-record VCR cassettes.
+
+```shell
+export DOCKER_API_USER='your_docker_hub_user'
+export DOCKER_API_PASS='your_docker_hub_password'
+export DOCKER_API_EMAIL='your_docker_hub_email_address'
+```
+
+### `rake vcr:spec`
+This command will download the necessary Docker images and then run the Rspec tests while recording your VCR cassettes.
+
+### `rake vcr:unpack`
+This command will download the necessary Docker image.
+
+### `rake vcr:record`
+This is the command you will use to record a new set of VCR cassettes. This command runs the following procedures:
+1. Delete the existing `spec/vcr` directory.
+2. Launch a temporary local Docker registry
+3. Record new VCR cassettes by running the Rspec test suite against a live Docker daemon.

data/lib/docker.rb

@@ -24,6 +24,7 @@ module Docker
   require 'docker/base'
   require 'docker/container'
   require 'docker/event'
+  require 'docker/exec'
   require 'docker/image'
   require 'docker/messages'
   require 'docker/util'
@@ -78,6 +79,12 @@ module Docker
     @connection ||= Connection.new(url, options)
   end
 
+  def reset!
+    @url = nil
+    @options = nil
+    reset_connection!
+  end
+
   def reset_connection!
     @connection = nil
   end
@@ -113,6 +120,6 @@ module Docker
 
   module_function :default_socket_url, :env_url, :url, :url=, :env_options,
                   :options, :options=, :creds, :creds=, :logger, :logger=,
-                  :connection, :reset_connection!, :version, :info,
+                  :connection, :reset!, :reset_connection!, :version, :info,
                   :authenticate!, :validate_version!
 end

data/lib/docker/container.rb

@@ -32,6 +32,44 @@ class Docker::Container
     end
   end
 
+  # Create an Exec instance inside the container
+  #
+  # @param command [String, Array] The command to run inside the Exec instance
+  # @param options [Hash] The options to pass to Docker::Exec
+  #
+  # @return [Docker::Exec] The Exec instance
+  def exec(command, opts = {}, &block)
+    # Establish values
+    tty = opts.delete(:tty) || false
+    detach = opts.delete(:detach) || false
+    stdin = opts.delete(:stdin)
+    stdout = opts.delete(:stdout) || !detach
+    stderr = opts.delete(:stderr) || !detach
+
+    # Create Exec Instance
+    instance = Docker::Exec.create(
+      'Container' => self.id,
+      'AttachStdin' => !!stdin,
+      'AttachStdout' => stdout,
+      'AttachStderr' => stderr,
+      'Tty' => tty,
+      'Cmd' => command
+    )
+
+    start_opts = {
+      :tty => tty,
+      :stdin => stdin,
+      :detach => detach
+    }
+
+    if detach
+      instance.start!(start_opts)
+      return instance
+    else
+      instance.start!(start_opts, &block)
+    end
+  end
+
   # Export the Container as a tar.
   def export(&block)
     connection.get(path_for(:export), {}, :response_block => block)
@@ -55,9 +93,10 @@ class Docker::Container
       # If attaching to stdin, we must hijack the underlying TCP connection
       # so we can stream stdin to the remote Docker process
       opts[:stdin] = true
-      excon_params[:hijack_block] = hijack_for(stdin, block, msgs, tty)
+      excon_params[:hijack_block] = Docker::Util.hijack_for(stdin, block,
+        msgs, tty)
     else
-      excon_params[:response_block] = attach_for(block, msgs, tty)
+      excon_params[:response_block] = Docker::Util.attach_for(block, msgs, tty)
     end
 
     connection.post(
@@ -101,10 +140,10 @@ class Docker::Container
 
   def streaming_logs(opts = {}, &block)
     msgs = Docker::Messages.new
-    excon_params = { response_block: attach_for(block, msgs, false) }
+    excon_params = {response_block: Docker::Util.attach_for(block, msgs, false)}
 
     connection.get(path_for(:logs), opts, excon_params)
-    msgs.all_messages.join("\n")
+    msgs.all_messages.join
   end
 
   def start!(opts = {})
@@ -201,81 +240,6 @@ class Docker::Container
     "/containers/#{self.id}/#{resource}"
   end
 
-  def hijack_for(stdin, block, msg_stack, tty)
-    attach_block = attach_for(block, msg_stack, tty)
-
-    lambda do |socket|
-      debug "hijack: hijacking the HTTP socket"
-      threads = []
-
-      debug "hijack: starting stdin copy thread"
-      threads << Thread.start do
-        debug "hijack: copying stdin => socket"
-        IO.copy_stream stdin, socket
-
-        debug "hijack: closing write end of hijacked socket"
-        socket.close_write
-      end
-
-      debug "hijack: starting hijacked socket read thread"
-      threads << Thread.start do
-        debug "hijack: reading from hijacked socket"
-
-        begin
-          while chunk = socket.readpartial(512)
-            debug "hijack: got #{chunk.bytesize} bytes from hijacked socket"
-            attach_block.call chunk, nil, nil
-          end
-        rescue EOFError
-        end
-
-        debug "hijack: killing stdin copy thread"
-        threads.first.kill
-      end
-
-      threads.each(&:join)
-    end
-  end
-
-  # Method that takes chunks and calls the attached block for each mux'd message
-  def attach_for(block, msg_stack, tty)
-    # If TTY is enabled expect raw data and append to stdout
-    if tty
-      attach_for_tty(block, msg_stack)
-    else
-      attach_for_multiplex(block, msg_stack)
-    end
-  end
-
-  def attach_for_tty(block, msg_stack)
-    return lambda do |c,r,t|
-      msg_stack.stdout_messages << c
-      msg_stack.all_messages << c
-      block.call c if block
-    end
-  end
-
-  def attach_for_multiplex(block, msg_stack)
-    messages = Docker::Messages.new
-    lambda do |c,r,t|
-      messages = messages.decipher_messages(c)
-      msg_stack.append(messages)
-
-      unless block.nil?
-        messages.stdout_messages.each do |msg|
-          block.call(:stdout, msg)
-        end
-        messages.stderr_messages.each do |msg|
-          block.call(:stderr, msg)
-        end
-      end
-    end
-  end
-
-  def debug(msg)
-    Docker.logger.debug(msg) if Docker.logger
-  end
-
-  private :path_for, :attach_for, :attach_for_tty, :attach_for_multiplex, :debug
+  private :path_for
   private_class_method :new
 end

data/lib/docker/exec.rb

@@ -0,0 +1,98 @@
+# This class represents a Docker Exec Instance.
+class Docker::Exec
+  include Docker::Base
+
+  # Convert details about the object into a string
+  #
+  # @return [String] String representation of the Exec instance object
+  def to_s
+    "Docker::Exec { :id => #{self.id}, :connection => #{self.connection} }"
+  end
+
+  # Create a new Exec instance in a running container. Please note, this does
+  # NOT execute the instance - you must run #start. Also, each instance is
+  # one-time use only.
+  #
+  # @param options [Hash] Parameters to pass in to the API.
+  # @param conn [Docker::Connection] Connection to Docker Remote API
+  #
+  # @return [Docker::Exec] self
+  def self.create(options = {}, conn = Docker.connection)
+    container = options.delete('Container')
+    resp = conn.post("/containers/#{container}/exec", {},
+      :body => options.to_json)
+    hash = Docker::Util.parse_json(resp) || {}
+    new(conn, hash)
+  end
+
+  # Start the Exec instance. The Exec instance is deleted after this so this
+  # command can only be run once.
+  #
+  # @param options [Hash] Options to dictate behavior of the instance
+  # @option options [Object] :stdin (nil) The object to pass to STDIN.
+  # @option options [TrueClass, FalseClass] :detach (false) Whether to attach
+  #     to STDOUT/STDERR.
+  # @option options [TrueClass, FalseClass] :tty (false) Whether to attach using
+  #     a pseudo-TTY.
+  #
+  # @return [Array, Array] The STDOUT and STDERR responses
+  def start!(options = {}, &block)
+
+    # Parse the Options
+    tty = !!options.delete(:tty)
+    detached = !!options.delete(:detach)
+    stdin = options[:stdin]
+
+    # Create API Request Body
+    body = {
+      "Tty" => tty,
+      "Detach" => detached
+    }
+    excon_params = { :body => body.to_json }
+
+    msgs = Docker::Messages.new
+    unless detached
+      if stdin
+        excon_params[:hijack_block] = Docker::Util.hijack_for(stdin, block,
+          msgs, tty)
+      else
+        excon_params[:response_block] = Docker::Util.attach_for(block,
+          msgs, tty)
+      end
+    end
+
+    connection.post(path_for(:start), nil, excon_params)
+    [msgs.stdout_messages, msgs.stderr_messages]
+  end
+
+  # #start! performs the associated action and returns the output.
+  # #start does the same, but rescues from ServerErrors.
+  [:start].each do |method|
+    define_method(method) do |*args|
+      begin; public_send(:"#{method}!", *args); rescue ServerError; self end
+    end
+  end
+
+  # Resize the TTY associated with the Exec instance
+  #
+  # @param query [Hash] API query parameters
+  # @option query [Fixnum] h Height of the TTY
+  # @option query [Fixnum] w Width of the TTY
+  #
+  # @return [Docker::Exec] self
+  def resize(query = {})
+    connection.post(path_for(:resize), query)
+    self
+  end
+
+  # Get the request URI for the given endpoint
+  #
+  # @param endpoint [Symbol] The endpoint to grab
+  # @return [String] The full Remote API endpoint with ID
+  def path_for(endpoint)
+    "/exec/#{self.id}/#{endpoint}"
+  end
+
+  private :path_for
+  private_class_method :new
+end

data/lib/docker/image.rb

@@ -23,7 +23,7 @@ class Docker::Image
 
   # Push the Image to the Docker registry.
   def push(creds = nil, options = {})
-    repo_tag = info['RepoTags'].first
+    repo_tag = options.delete(:repo_tag) || info['RepoTags'].first
     raise ArgumentError "Image is untagged" if repo_tag.nil?
     repo, tag = Docker::Util.parse_repo_tag(repo_tag)
     raise ArgumentError, "Image does not have a name to push." if repo.nil?
@@ -63,7 +63,8 @@ class Docker::Image
 
   # Remove the Image from the server.
   def remove(opts = {})
-    connection.delete("/images/#{self.id}", opts)
+    name = opts.delete(:name) || self.id
+    connection.delete("/images/#{name}", opts)
   end
   alias_method :delete, :remove
 
@@ -211,7 +212,7 @@ end
 
   # A method to build the config header and merge it into the
   # headers sent by build_from_dir.
-  def self.build_headers(creds)
+  def self.build_headers(creds=nil)
     credentials = creds || Docker.creds || {}
     config_header = Docker::Util.build_config_header(credentials)