docker-api 0.1.0 → 1.0.0

data/README.md

@@ -70,27 +70,16 @@ Docker.authenticate!('username' => 'docker-fan-boi', 'password' => 'i<3docker',
 ```
 
 ## Images
-Just about every method here has a one-to-one mapping with the [Images](http://docs.docker.io/en/latest/api/docker_remote_api_v1.2/#images) section of the API. If an API call accepts query parameters, these can be passed as an Hash to it's corresponding method.
+Just about every method here has a one-to-one mapping with the [Images](http://docs.docker.io/en/latest/api/docker_remote_api_v1.2/#images) section of the API. If an API call accepts query parameters, these can be passed as an Hash to it's corresponding method. Also, note that `Docker::Image.new` is a private method, so you must use `.create`, `.build`, `.build_from_dir`, or `.import` to make an instance.
 
 ```ruby
 require 'docker'
 # => true
 
-# Instantiate a new Image. Note that this does NOT create the Image.
-image = Docker::Image.new
-# => Docker::Image { :id => , :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }
-
-# Test if the Image is created.
-image.created?
-# => false
-
-# Create the Image.
-image.create!('fromRepo' => 'base')
+# Create an Image.
+Docker::Image.create('fromRepo' => 'base')
 # => Docker::Image { :id => ae7ffbcd1, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }
 
-image.created?
-# => true
-
 # Insert a file into an Image. Returns a new Image that contains that file.
 image.insert('path' => '/google', 'url' => 'http://google.com')
 # => Docker::Image { :id => 11ef6c882, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }
@@ -112,25 +101,18 @@ image.history
 image.push
 # => true
 
+# Given a command, create a new Container to run that command in the Image.
+image.run('ls -l')
+# => Docker::Container { id => aaef712eda, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }
+
 # Remove the Image from the server.
 image.remove
 # => true
 
-image.created?
-# => false
-
 # Given a Container's export, creates a new Image.
-image.create_from_file('some-export.tar')
+Docker::Image.import('some-export.tar')
 # => Docker::Image { :id => 66b712aef, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }
 
-# Load all Images on your Docker server.
-Docker::Image.all
-# => [Docker::Image { :id => b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => 8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }]
-
-# Search the Docker registry.
-Docker::Image.search('term' => 'sshd')
-# => [Docker::Image { :id => cespare/sshd, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => johnfuller/sshd, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => dhrp/mongodb-sshd, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => rayang2004/sshd, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => dhrp/sshd, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => toorop/daemontools-sshd, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => toorop/daemontools-sshd-nginx, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => toorop/daemontools-sshd-nginx-php-fpm, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => mbkan/lamp, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => toorop/golang, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => wma55/u1210sshd, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => jdswinbank/sshd, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => vgauthier/sshd, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }]
-
 # Create an Image from a Dockerfile as a String.
 Docker::Image.build("from base\nrun touch /test")
 # => Docker::Image { :id => b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }
@@ -138,29 +120,26 @@ Docker::Image.build("from base\nrun touch /test")
 # Create an Image from a Dockerfile.
 Dockerfile::Image.build_from_dir('.')
 # => Docker::Image { :id => 1266dc19e, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }
+
+# Load all Images on your Docker server.
+Docker::Image.all
+# => [Docker::Image { :id => b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => 8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }]
+
+# Search the Docker registry.
+Docker::Image.search('term' => 'sshd')
+# => [Docker::Image { :id => cespare/sshd, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => johnfuller/sshd, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => dhrp/mongodb-sshd, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => rayang2004/sshd, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => dhrp/sshd, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => toorop/daemontools-sshd, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => toorop/daemontools-sshd-nginx, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => toorop/daemontools-sshd-nginx-php-fpm, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => mbkan/lamp, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => toorop/golang, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => wma55/u1210sshd, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => jdswinbank/sshd, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }, Docker::Image { :id => vgauthier/sshd, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }]
 ```
 
 ## Containers
-Much like the Images, this object also has a one-to-one mapping with the [Containers](http://docs.docker.io/en/latest/api/docker_remote_api_v1.2/#containers) section of the API.
+Much like the Images, this object also has a one-to-one mapping with the [Containers](http://docs.docker.io/en/latest/api/docker_remote_api_v1.2/#containers) section of the API. Also like Images, `.new` is a private method, so you must use `.create` to make an instance.
 
 ```ruby
 require 'docker'
 
-# Instantiate a new Container.
-container = Docker::Container.new
-# => Docker::Container { :id => , :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }
-
-# Test if the has been created.
-container.created?
-# => false
-
-# Create the Container. 
-container.create!('Cmd' => ['ls'], 'Image' => 'base')
+# Create a Container. 
+Docker::Container.create('Cmd' => ['ls'], 'Image' => 'base')
 # => Docker::Container { :id => 492510dd38e4, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }
 
-container.created?
-# => true
-
 # Get more information about the Container.
 container.json
 # => {"Id"=>"492510dd38e4da7703f36dfccd013de672b8250f57f59d1555ced647766b5e82", "Created"=>"2013-06-20T10:46:02.897548-04:00", "Path"=>"ls", "Args"=>[], "Config"=>{"Hostname"=>"492510dd38e4", "User"=>"", "Memory"=>0, "MemorySwap"=>0, "CpuShares"=>0, "AttachStdin"=>false, "AttachStdout"=>false, "AttachStderr"=>false, "PortSpecs"=>nil, "Tty"=>false, "OpenStdin"=>false, "StdinOnce"=>false, "Env"=>nil, "Cmd"=>["ls"], "Dns"=>nil, "Image"=>"base", "Volumes"=>nil, "VolumesFrom"=>""}, "State"=>{"Running"=>false, "Pid"=>0, "ExitCode"=>0, "StartedAt"=>"0001-01-01T00:00:00Z", "Ghost"=>false}, "Image"=>"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", "NetworkSettings"=>{"IpAddress"=>"", "IpPrefixLen"=>0, "Gateway"=>"", "Bridge"=>"", "PortMapping"=>nil}, "SysInitPath"=>"/usr/bin/docker", "ResolvConfPath"=>"/etc/resolv.conf", "Volumes"=>nil}
@@ -197,6 +176,7 @@ container.wait
 # => {'StatusCode'=>0}
 
 # Attach to the Container. Currently, the below options are the only valid ones.
+# By default, :stream and :stdout are set.
 container.attach(:stream => true, :stdout => true, :stderr => true, :logs => true)
 # => "bin\nboot\ndev\netc\nhome\nlib\nlib64\nmedia\nmnt\nopt\nproc\nroot\nrun\nsbin\nselinux\nsrv\nsys\ntmp\nusr\nvar"
 
@@ -211,19 +191,12 @@ Docker::Container.all(:all => true)
 
 ## Connecting to Multiple Servers
 
-By default, each object connects to the connection specified by `Docker.connection`. If you need to connect to multiple servers, you can do so by specifying the connection on `#new` or in the utilizing class method. Examples:
+By default, each object connects to the connection specified by `Docker.connection`. If you need to connect to multiple servers, you can do so by specifying the connection on `#new` or in the utilizing class method. For example:
 
 ```ruby
 require 'docker'
 
-Docker::Container.new(:connection => Docker::Connection.new(:url => 'http://example.com'))
 Docker::Container.all({}, Docker::Connection.new(:url => 'http://example.com'))
-
-Docker::Image.new(:connection => Docker::Connection.new(:url => 'http://example.com'))
-Docker::Image.all({}, Docker::Connection.new(:url => 'http://example.com'))
-Docker::Image.build('from base', Docker::Connection.new(:url => 'http://example.com'))
-Docker::Image.build_from_dir('.', Docker::Connection.new(:url => 'http://example.com'))
-Docker::Image.search({ :term => 'sshd' }, Docker::Connection.new(:url => 'http://example.com'))
 ```
 
 ## Known Issues

data/lib/docker/connection.rb

@@ -20,10 +20,17 @@ class Docker::Connection
     @resource ||= Excon.new(self.url, self.options)
   end
 
+  # Nil out the connection. This now happens on every request to prevent socket
+  # errors.
+  def reset!
+    @resource = nil
+  end
+
   # Delegate all HTTP methods to the resource.
   [:get, :put, :post, :delete, :request].each do |method|
     define_method(method) do |*args, &block|
       begin
+        self.reset!
         self.resource.public_send(method, *args, &block)
       rescue Excon::Errors::BadRequest => ex
         raise ClientError, ex.message
@@ -37,7 +44,7 @@ class Docker::Connection
   def json_request(method, path, query = {}, &block)
     params = compile_request_params(method, path, query, &block)
     body = self.request(params).body
-    JSON.parse(body) unless (body.nil? || body.empty? || (body == 'null'))
+    JSON.parse(body) unless body.nil? || body.empty? || (body == 'null')
   rescue JSON::ParserError => ex
     raise UnexpectedResponseError, ex.message
   end

data/lib/docker/container.rb

@@ -13,30 +13,30 @@ class Docker::Container
       :body    => body.to_json,
       :expects => (200..204)
     )
-    self.id = JSON.parse(response.body)['Id']
+    @id = JSON.parse(response.body)['Id']
     self
   end
 
   # Export the Container as a .tgz.
-  docker_request :export, :get
+  get :export
   # Get more information about the Container.
-  docker_request :json, :get
+  get :json
   # Wait for the current command to finish executing.
-  docker_request :wait, :post
+  post :wait
   # Start the Container.
-  docker_request :start, :post
+  post :start
   # Inspect the Container's changes to the filesysetem
-  docker_request :changes, :get
+  get :changes
   # Stop the Container.
-  docker_request :stop, :post
+  post :stop
   # Kill the Container.
-  docker_request :kill, :post
+  post :kill
   # Restart the Container
-  docker_request :restart, :post
+  post :restart
 
   # Attach to a container's standard streams / logs.
   def attach(options = {})
-    ensure_created!
+    options = { :stream => true, :stdout => true }.merge(options)
     self.connection.post(
       :path    => "/containers/#{self.id}/attach",
       :headers => { 'Content-Type' => 'text/plain',
@@ -48,9 +48,8 @@ class Docker::Container
 
   # Create an Image from a Container's change.s
   def commit(options = {})
-    ensure_created!
     options.merge!('container' => self.id[0..7])
     hash = self.connection.json_request(:post, '/commit', options)
-    Docker::Image.new(:id => hash['Id'], :connection => self.connection)
+    Docker::Image.send(:new, :id => hash['Id'], :connection => self.connection)
   end
 end

data/lib/docker/error.rb

@@ -8,10 +8,6 @@ module Docker::Error
   # Raised when invalid arguments are passed to a method.
   class ArgumentError < DockerError; end
 
-  # Raised when a method requires a Model to be in a certain state (typically
-  # created or not created), but the Model is not in that state.
-  class StateError < DockerError; end
-
   # Raised when a request returns a 400.
   class ClientError < DockerError; end
 

data/lib/docker/image.rb

@@ -5,13 +5,13 @@ class Docker::Image
 
   resource_prefix '/images'
 
-  create_request do |options, excon_options|
-    body = self.connection.post(excon_options.merge(
-      :path    => '/v1.3/images/create',
+  create_request do |options|
+    body = self.connection.post(
+      :path    => '/images/create',
       :headers => { 'User-Agent' => 'Docker-Client/0.4.6' },
       :query   => options,
       :expects => (200..204)
-    )).body
+    ).body
     @id = JSON.parse(body)['status'] rescue nil
     @id ||= options['fromImage']
     @id ||= "#{options['repo']}/#{options['tag']}"
@@ -19,15 +19,24 @@ class Docker::Image
   end
 
   # Tag the Image.
-  docker_request :tag, :post
+  post :tag
   # Get more information about the Image.
-  docker_request :json, :get
+  get :json
   # Get the history of the Image.
-  docker_request :history, :get
+  get :history
+
+  # Given a command and optional list of streams to attach to, run a command on
+  # an Image. This will not modify the Image, but rather create a new Container
+  # to run the Image.
+  def run(cmd)
+    cmd = cmd.split(/\s+/) if cmd.is_a?(String)
+    Docker::Container.create({ 'Image' => self.id, 'Cmd' => cmd },
+                             self.connection)
+                     .tap(&:start)
+  end
 
   # Push the Image to the Docker registry.
   def push(options = {})
-    ensure_created!
     self.connection.post(
       :path    => "/images/#{self.id}/push",
       :headers => { 'Content-Type' => 'text/plain',
@@ -41,7 +50,6 @@ class Docker::Image
 
   # Insert a file into the Image, returns a new Image that has that file.
   def insert(query = {})
-    ensure_created!
     body = self.connection.post(
       :path    => "/images/#{self.id}/insert",
       :headers => { 'Content-Type' => 'text/plain',
@@ -52,16 +60,13 @@ class Docker::Image
     if (id = body.match(/{"Id":"([a-f0-9]+)"}\z/)).nil? || id[1].empty?
       raise UnexpectedResponseError, "Could not find Id in '#{body}'"
     else
-      Docker::Image.new(:id => id[1], :connection => self.connection)
+      self.class.send(:new, :id => id[1], :connection => self.connection)
     end
   end
 
   # Remove the Image from the server.
   def remove
-    ensure_created!
     self.connection.json_request(:delete, "/images/#{self.id}", nil)
-    self.id = nil
-    true
   end
 
   class << self
@@ -74,46 +79,51 @@ class Docker::Image
       hashes.map { |hash| new(:id => hash['Name'], :connection => connection) }
     end
 
+    # Import an Image from the output of Docker::Container#export.
     def import(file, options = {}, connection = Docker.connection)
       File.open(file, 'r') do |io|
-        read_chunked = proc { io.read(Excon.defaults[:chunk_size]).to_s }
-        self.new(:connection => connection)
-            .create!(options.merge('fromSrc' => '-'),
-                     :request_block => read_chunked)
+        body = connection.post(
+          :path          => '/images/create',
+          :headers       => { 'User-Agent' => 'Docker-Client/0.4.6',
+                              'Transfer-Encoding' => 'chunked' },
+          :query         => options.merge('fromSrc' => '-'),
+          :request_block => proc { io.read(Excon.defaults[:chunk_size]).to_s },
+          :expects       => (200..204)
+        ).body
+        new(:id => JSON.parse(body)['status'], :connection => connection)
       end
     end
 
     # Given a Dockerfile as a string, builds an Image.
     def build(commands, connection = Docker.connection)
       body = connection.post(
-        :path => '/v1.3/build',
+        :path => '/build',
         :body => create_tar(commands),
         :expects => (200..204)
       ).body
       new(:id => extract_id(body), :connection => connection)
     end
 
+    # Given a directory that contains a Dockerfile, builds an Image.
     def build_from_dir(dir, connection = Docker.connection)
-      cwd = FileUtils.pwd
-      FileUtils.cd(dir)
-      tar = create_dir_tar('.')
+      tar = create_dir_tar(dir)
       body = connection.post(
-        :path => '/v1.3/build',
-        :headers => { 'Content-Type' => 'application/tar',
-                      'Transfer-Encoding' => 'chunked' },
+        :path          => '/build',
+        :headers       => { 'Content-Type'      => 'application/tar',
+                            'Transfer-Encoding' => 'chunked' },
         :request_block => proc { tar.read(Excon.defaults[:chunk_size]).to_s },
-        :expects => (200..204),
+        :expects       => (200..204),
       ).body
       new(:id => extract_id(body), :connection => connection)
     ensure
       tar.close
-      FileUtils.cd(cwd)
     end
 
   private
     def extract_id(body)
-      if match = body.lines.to_a[-1].match(/^Successfully built ([a-f0-9]+)$/)
-        match[1]
+      line = body.lines.to_a[-1]
+      if (id = line.match(/^Successfully built ([a-f0-9]+)$/)) && !id[1].empty?
+        id[1]
       else
         raise UnexpectedResponseError, "Couldn't find id: #{body}"
       end
@@ -129,16 +139,20 @@ class Docker::Image
       file = File.new('Dockerfile', 'w')
       file.write(input)
       file.close
-      Archive::Tar::Minitar.pack_file("#{path}/Dockerfile", tar)
+      Archive::Tar::Minitar.pack_file("Dockerfile", tar)
       FileUtils.cd(cwd)
       FileUtils.rm_rf(path)
       string.tap(&:rewind)
     end
 
     def create_dir_tar(directory)
+      cwd = FileUtils.pwd
       tempfile = File.new('/tmp/out', 'w')
-      Archive::Tar::Minitar.pack(directory, tempfile)
+      FileUtils.cd(directory)
+      Archive::Tar::Minitar.pack('.', tempfile)
       File.new('/tmp/out', 'r')
+    ensure
+      FileUtils.cd(cwd)
     end
   end
 end

data/lib/docker/model.rb

@@ -1,10 +1,16 @@
 # This module is intended to be used as a Mixin for all objects exposed by the
 # Remote API. Currently, these are limited to Containers and Images.
 module Docker::Model
+  include Docker::Error
+
   attr_reader :id, :connection
 
   def self.included(base)
-    base.extend(ClassMethods)
+    base.class_eval do
+      extend ClassMethods
+      private_class_method :new, :request, :get, :put, :post, :delete,
+                           :create_request, :resource_prefix
+    end
   end
 
   # Creates a new Model with the specified id and Connection. If a Connection
@@ -12,39 +18,22 @@ module Docker::Model
   # Docker::Error::ArgumentError is raised.
   def initialize(options = {})
     options[:connection] ||= Docker.connection
-    unless options[:connection].is_a?(Docker::Connection)
-      raise Docker::Error::ArgumentError, "Expected a Docker::Connection."
-    end
-    self.id = options[:id]
-    self.connection = options[:connection]
-  end
-
-  # Create a Model with the specified body. Raises A Docker::Error::StateError
-  # if the model already exists, and a Docker::Error::ArgumentError if the
-  # argument is not a Hash. Otherwise, instances exec the Class's
-  # #create_request method with the single argument.
-  def create!(options = {}, excon_options = {})
-    case
-    when self.created?
-      raise Docker::Error::StateError, "This #{self.class.name} already exists!"
-    when !options.is_a?(Hash)
-      raise Docker::Error::ArgumentError, 'Expected a Hash'
+    if !options[:connection].is_a?(Docker::Connection)
+      raise ArgumentError, 'Expected a Docker::Connection.'
     else
-      instance_exec(options, excon_options, &self.class.create_request)
+      @id = options[:id]
+      @connection = options[:connection]
     end
   end
 
-  # Returns true if the Container has been created, false otherwise.
-  def created?
-    !!self.id
-  end
-
   def to_s
     "#{self.class.name} { :id => #{id}, :connection => #{connection} }"
   end
 
   # This defines the DSL for the including Classes.
   module ClassMethods
+    include Docker::Error
+
     # Define the Model's prefix for all requests.
     def resource_prefix(val = nil)
       val.nil? ? @resource_prefix : (@resource_prefix = val)
@@ -57,32 +46,33 @@ module Docker::Model
 
     # Define a method named `action` that sends an http `method` request to the
     # Docker Server.
-    def docker_request(action, method, &outer_block)
+    def request(method, action, opts = {}, &outer_block)
       define_method(action) do |query = nil, &block|
-        ensure_created!
-        path = "#{self.class.resource_prefix}/#{self.id}/#{action}"
+        path = opts[:path]
+        path ||= "#{self.class.send(:resource_prefix)}/#{self.id}/#{action}"
         body = self.connection.json_request(method, path, query, &block)
         outer_block.nil? ? body : instance_exec(body, &outer_block)
       end
     end
 
+    [:get, :put, :post, :delete].each do |method|
+      define_method(method) { |*args, &block| request(method, *args, &block) }
+    end
+
+    # Create a Model with the specified body. Raises a
+    # Docker::Error::ArgumentError if the argument is not a Hash. Otherwise,
+    # instances execs the Class's #create_request method with the single
+    # argument.
+    def create(opts = {}, conn = Docker.connection)
+      raise Docker::Error::ArgumentError, 'Expected a Hash' if !opts.is_a?(Hash)
+      new(:connection => conn).instance_exec(opts, &create_request)
+    end
+
     # Retrieve every Instance of a model for the given server.
     def all(options = {}, connection = Docker.connection)
-      path = "#{self.resource_prefix}/json"
+      path = "#{resource_prefix}/json"
       hashes = connection.json_request(:get, path, options) || []
       hashes.map { |hash| new(:id => hash['Id'], :connection => connection) }
     end
-
-  private
-  end
-
-private
-  attr_writer :id, :connection
-
-  # Raises an error unless the Model is created.
-  def ensure_created!
-    unless created?
-      raise Docker::Error::StateError, "This #{self.class.name} is not created."
-    end
   end
 end