docker-api 1.0.1 → 1.1.0

data/README.md

@@ -51,6 +51,8 @@ Docker.options = { :port => 5422 }
 
 Two things to note here. The first is that this gem uses [excon](http://www.github.com/geemus/excon), so any of the options that are valid for `Excon.new` are alse valid for `Docker.options`. Second, by default Docker runs on port 4243. The gem will assume you want to connnect to port 4243 unless you specify otherwise.
 
+Before doing anything else, ensure you have the correct version of the Docker API. To do this, run `Docker.validate_version!`. If your installed version is not supported, a `Docker::Error::VersionError` is raised.
+
 ## Global calls
 
 All of the following examples require a connection to a Docker server. See the <a href="#starting-up">Starting up</a> section above for more information.

data/lib/docker.rb

@@ -39,12 +39,12 @@ module Docker
 
   # Get the version of Go, Docker, and optionally the Git commit.
   def version
-    connection.json_request(:get, '/version')
+    Util.parse_json(connection.request(:get, '/version'))
   end
 
   # Get more information about the Docker server.
   def info
-    connection.json_request(:get, '/info')
+    Util.parse_json(connection.request(:get, '/info'))
   end
 
   # Login to the Docker registry.
@@ -53,10 +53,20 @@ module Docker
     connection.post(:path => '/auth', :body => @creds)
     true
   end
+
+  # When the correct version of Docker is installed, returns true. Otherwise,
+  # raises a VersionError.
+  def validate_version!
+    Docker.info
+    true
+  rescue Docker::Error::DockerError
+    raise Docker::Error::VersionError, "Expected API Version: #{API_VERSION}"
+  end
 end
 
 require 'docker/version'
 require 'docker/error'
+require 'docker/util'
 require 'docker/connection'
 require 'docker/model'
 require 'docker/container'

data/lib/docker/connection.rb

@@ -5,69 +5,62 @@ class Docker::Connection
 
   attr_reader :url, :options
 
-  # Create a new Connection. By default, the Connection points to localhost at
-  # port 4243, but this can be changed via an options Hash.
-  def initialize(url = 'http://localhost', options = {})
-    unless options.is_a?(Hash)
-      raise Docker::Error::ArgumentError, "Expected a Hash, got: #{options}"
+  # Create a new Connection. This method takes a url (String) and options
+  # (Hash). These are passed to Excon, so any options valid for `Excon.new`
+  # can be passed here.
+  def initialize(url, opts)
+    case
+    when !url.is_a?(String)
+      raise ArgumentError, "Expected a String, got: '#{url}'"
+    when !opts.is_a?(Hash)
+      raise ArgumentError, "Expected a Hash, got: '#{opts}'"
+    else
+      @url, @options = url, opts
     end
-    self.url = url
-    self.options = { :port => 4243 }.merge(options)
   end
 
-  # The actual client that sends HTTP methods to the docker server.
+  # The actual client that sends HTTP methods to the Docker server. This value
+  # is not cached, since doing so may cause socket errors after bad requests.
   def resource
-    @resource ||= Excon.new(self.url, self.options)
+    Excon.new(url, options)
   end
+  private :resource
 
-  # Nil out the connection. This now happens on every request to prevent socket
-  # errors.
-  def reset!
-    @resource = nil
+  # Send a request to the server with the `
+  def request(*args, &block)
+    resource.request(compile_request_params(*args, &block)).body
+  rescue Excon::Errors::BadRequest => ex
+    raise ClientError, ex.message
+  rescue Excon::Errors::InternalServerError => ex
+    raise ServerError, ex.message
   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
-      rescue Excon::Errors::InternalServerError => ex
-        raise ServerError, ex.message
-      end
-    end
-  end
-
-  # Send a request to the server and then parse it into a Hash.
-  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')
-  rescue JSON::ParserError => ex
-    raise UnexpectedResponseError, ex.message
+  # Delegate all HTTP methods to the #request.
+  [:get, :put, :post, :delete].each do |method|
+    define_method(method) { |*args, &block| request(method, *args, &block) }
   end
 
   def to_s
-    "Docker::Connection { :url => #{self.url}, :options => #{self.options} }"
+    "Docker::Connection { :url => #{url}, :options => #{options} }"
   end
 
 private
-  attr_writer :url, :options
-
-  # Given an http_method, path, query, and optional block, returns the
-  # corresponding request parameters.
-  def compile_request_params(http_method, path, query, &block)
+  # Given an HTTP method, path, optional query, extra options, and block,
+  # compiles a request.
+  def compile_request_params(http_method, path, query = nil, opts = nil, &block)
+    query ||= {}
+    opts ||= {}
+    headers = opts.delete(:headers) || {}
     {
-      :method         => http_method,
-      :path           => path,
-      :query          => query,
-      :headers => { 'Content-Type' => 'text/plain',
-                    'User-Agent' => "Docker-Client/0.4.6" },
-      :expects        => (200..204),
-      :idempotent     => http_method == :get,
-      :response_block => block
-    }.reject { |_, v| v.nil? }
+      :method        => http_method,
+      :path          => "/v#{Docker::API_VERSION}#{path}",
+      :query         => query,
+      :headers       => { 'Content-Type' => 'text/plain',
+                          'User-Agent'   => 'Docker-Client/0.4.6'
+                        }.merge(headers),
+      :expects       => (200..204),
+      :idempotent    => http_method == :get,
+      :request_block => block
+    }.merge(opts).reject { |_, v| v.nil? }
   end
 end

data/lib/docker/container.rb

@@ -3,22 +3,14 @@
 class Docker::Container
   include Docker::Model
 
-  resource_prefix '/containers'
+  set_resource_prefix '/containers'
 
-  create_request do |body|
-    response = self.connection.post(
-      :path    => '/containers/create',
-      :headers => { 'Content-Type' => 'text/plain',
-                    'User-Agent' => "Docker-Client/0.4.6" },
-      :body    => body.to_json,
-      :expects => (200..204)
-    )
-    @id = JSON.parse(response.body)['Id']
+  set_create_request do |body|
+    response = connection.post('/containers/create', nil, :body => body.to_json)
+    @id = Docker::Util.parse_json(response)['Id']
     self
   end
 
-  # Export the Container as a .tgz.
-  get :export
   # Get more information about the Container.
   get :json
   # Wait for the current command to finish executing.
@@ -34,22 +26,22 @@ class Docker::Container
   # Restart the Container
   post :restart
 
+  # Export the Container as a tar.
+  def export(&block)
+    connection.get("/containers/#{id}/export", nil, :response_block => block)
+    true
+  end
+
   # Attach to a container's standard streams / logs.
   def attach(options = {})
     options = { :stream => true, :stdout => true }.merge(options)
-    self.connection.post(
-      :path    => "/containers/#{self.id}/attach",
-      :headers => { 'Content-Type' => 'text/plain',
-                    'User-Agent' => "Docker-Client/0.4.6" },
-      :query   => options,
-      :expects => (200..204)
-    ).body
+    connection.post("/containers/#{id}/attach", options)
   end
 
   # Create an Image from a Container's change.s
   def commit(options = {})
     options.merge!('container' => self.id[0..7])
-    hash = self.connection.json_request(:post, '/commit', options)
+    hash = JSON.parse(connection.request(:post, '/commit', options))
     Docker::Image.send(:new, :id => hash['Id'], :connection => self.connection)
   end
 end

data/lib/docker/error.rb

@@ -16,4 +16,7 @@ module Docker::Error
 
   # Raised when there is an unexpected response code / body.
   class UnexpectedResponseError < DockerError; end
+
+  # Raised when there is an incompatible version of Docker.
+  class VersionError < DockerError; end
 end

data/lib/docker/image.rb

@@ -3,16 +3,11 @@ class Docker::Image
   include Docker::Model
   include Docker::Error
 
-  resource_prefix '/images'
+  set_resource_prefix '/images'
 
-  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
-    @id = JSON.parse(body)['status'] rescue nil
+  set_create_request do |options|
+    body = connection.post('/images/create', options)
+    @id = Docker::Util.parse_json(body)['status'] rescue nil
     @id ||= options['fromImage']
     @id ||= "#{options['repo']}/#{options['tag']}"
     self
@@ -30,33 +25,19 @@ class Docker::Image
   # 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)
+    Docker::Container.create({ 'Image' => self.id, 'Cmd' => cmd }, connection)
                      .tap(&:start)
   end
 
   # Push the Image to the Docker registry.
   def push(options = {})
-    self.connection.post(
-      :path    => "/images/#{self.id}/push",
-      :headers => { 'Content-Type' => 'text/plain',
-                    'User-Agent' => 'Docker-Client/0.4.6' },
-      :query   => options,
-      :body    => Docker.creds,
-      :expects => (200..204)
-    )
+    connection.post("/images/#{self.id}/push", options, :body => Docker.creds)
     true
   end
 
   # Insert a file into the Image, returns a new Image that has that file.
   def insert(query = {})
-    body = self.connection.post(
-      :path    => "/images/#{self.id}/insert",
-      :headers => { 'Content-Type' => 'text/plain',
-                    'User-Agent' => "Docker-Client/0.4.6" },
-      :query   => query,
-      :expects => (200..204)
-    ).body
+    body = connection.post("/images/#{self.id}/insert", query)
     if (id = body.match(/{"Id":"([a-f0-9]+)"}\z/)).nil? || id[1].empty?
       raise UnexpectedResponseError, "Could not find Id in '#{body}'"
     else
@@ -66,7 +47,7 @@ class Docker::Image
 
   # Remove the Image from the server.
   def remove
-    self.connection.json_request(:delete, "/images/#{self.id}", nil)
+    connection.request(:delete, "/images/#{self.id}", nil)
   end
 
   class << self
@@ -75,7 +56,8 @@ class Docker::Image
     # Given a query like `{ :term => 'sshd' }`, queries the Docker Registry for
     # a corresponiding Image.
     def search(query = {}, connection = Docker.connection)
-      hashes = connection.json_request(:get, '/images/search', query) || []
+      body = connection.request(:get, '/images/search', query)
+      hashes = Docker::Util.parse_json(body) || []
       hashes.map { |hash| new(:id => hash['Name'], :connection => connection) }
     end
 
@@ -83,24 +65,18 @@ class Docker::Image
     def import(file, options = {}, connection = Docker.connection)
       File.open(file, 'r') do |io|
         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)
+          '/images/create',
+           options.merge('fromSrc' => '-'),
+           :headers => { 'Transfer-Encoding' => 'chunked' }
+        ) { io.read(Excon.defaults[:chunk_size]).to_s }
+        new(:id => Docker::Util.parse_json(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 => '/build',
-        :body => create_tar(commands),
-        :expects => (200..204)
-      ).body
+      body = connection.post('/build', {}, :body => create_tar(commands))
       new(:id => extract_id(body), :connection => connection)
     end
 
@@ -108,12 +84,10 @@ class Docker::Image
     def build_from_dir(dir, connection = Docker.connection)
       tar = create_dir_tar(dir)
       body = connection.post(
-        :path          => '/build',
-        :headers       => { 'Content-Type'      => 'application/tar',
-                            'Transfer-Encoding' => 'chunked' },
-        :request_block => proc { tar.read(Excon.defaults[:chunk_size]).to_s },
-        :expects       => (200..204),
-      ).body
+        '/build', {},
+        :headers => { 'Content-Type'      => 'application/tar',
+                      'Transfer-Encoding' => 'chunked' }
+      ) { tar.read(Excon.defaults[:chunk_size]).to_s }
       new(:id => extract_id(body), :connection => connection)
     ensure
       tar.close

data/lib/docker/model.rb

@@ -9,7 +9,7 @@ module Docker::Model
     base.class_eval do
       extend ClassMethods
       private_class_method :new, :request, :get, :put, :post, :delete,
-                           :create_request, :resource_prefix
+                           :set_create_request, :set_resource_prefix
     end
   end
 
@@ -17,12 +17,10 @@ module Docker::Model
   # is specified and it is not a Docker::Connection, a
   # Docker::Error::ArgumentError is raised.
   def initialize(options = {})
-    options[:connection] ||= Docker.connection
-    if !options[:connection].is_a?(Docker::Connection)
-      raise ArgumentError, 'Expected a Docker::Connection.'
+    if (options[:connection] ||= Docker.connection).is_a?(Docker::Connection)
+      @id, @connection = options[:id], options[:connection]
     else
-      @id = options[:id]
-      @connection = options[:connection]
+      raise ArgumentError, 'Expected a Docker::Connection.'
     end
   end
 
@@ -33,24 +31,29 @@ module Docker::Model
   # This defines the DSL for the including Classes.
   module ClassMethods
     include Docker::Error
+    attr_reader :resource_prefix, :create_request
 
     # Define the Model's prefix for all requests.
-    def resource_prefix(val = nil)
-      val.nil? ? @resource_prefix : (@resource_prefix = val)
+    def set_resource_prefix(val)
+      @resource_prefix = val
     end
 
     # Define how the Model should send a create request to the server.
-    def create_request(&block)
-      block.nil? ? @create_request : (@create_request = block)
+    def set_create_request(&block)
+      @create_request = block
     end
 
     # Define a method named `action` that sends an http `method` request to the
     # Docker Server.
     def request(method, action, opts = {}, &outer_block)
       define_method(action) do |query = nil, &block|
-        path = opts[:path]
-        path ||= "#{self.class.send(:resource_prefix)}/#{self.id}/#{action}"
-        body = self.connection.json_request(method, path, query, &block)
+        new_opts = {
+          :path => "#{self.class.resource_prefix}/#{self.id}/#{action}",
+          :json => true
+        }.merge(opts)
+        body = connection.request(method, new_opts[:path], query,
+                                  new_opts[:excon], &block)
+        body = Docker::Util.parse_json(body) if new_opts[:json]
         outer_block.nil? ? body : instance_exec(body, &outer_block)
       end
     end
@@ -71,7 +74,7 @@ module Docker::Model
     # Retrieve every Instance of a model for the given server.
     def all(options = {}, connection = Docker.connection)
       path = "#{resource_prefix}/json"
-      hashes = connection.json_request(:get, path, options) || []
+      hashes = Docker::Util.parse_json(connection.get(path, options)) || []
       hashes.map { |hash| new(:id => hash['Id'], :connection => connection) }
     end
   end

data/lib/docker/util.rb

@@ -0,0 +1,12 @@
+# This module holds shared logic that doesn't really belong anywhere else in the
+# gem.
+module Docker::Util
+  extend self
+  include Docker::Error
+
+  def parse_json(body)
+    JSON.parse(body) unless body.nil? || body.empty? || (body == 'null')
+  rescue JSON::ParserError => ex
+    raise UnexpectedResponseError, ex.message
+  end
+end

data/lib/docker/version.rb

@@ -1,3 +1,7 @@
 module Docker
-  VERSION = '1.0.1'
+  # The version of the docker-api gem.
+  VERSION = '1.1.0'
+
+  # The version of the compatible Docker remote API.
+  API_VERSION = '1.3'
 end

data/spec/docker/connection_spec.rb

@@ -1,38 +1,34 @@
 require 'spec_helper'
 
 describe Docker::Connection do
+  subject { described_class.new('http://localhost', :port => 4243) }
+
   describe '#initialize' do
-    subject { described_class }
+    let(:url) { 'http://localhost' }
+    let(:options) { { :port => 4243 } }
+    subject { described_class.new(url, options) }
 
-    context 'with no arguments' do
-      it 'defaults to port 4243' do
-        subject.new.options.should == { :port => 4243 }
-      end
+    context 'when the first argument is not a String' do
+      let(:url) { :lol_not_a_string }
 
-      it 'defaults to \'http://localhost\' for the url' do
-        subject.new.url.should == 'http://localhost'
+      it 'raises an error' do
+        expect { subject }.to raise_error(Docker::Error::ArgumentError)
       end
     end
 
-    context 'with an argument' do
-      context 'when the second argument is not a Hash' do
-        it 'raises a Docker::Error::ArgumentError' do
-          expect { subject.new('http://localhost', :lol) }
-              .to raise_error Docker::Error::ArgumentError
-        end
-      end
-
-      context 'when the argument is a Hash' do
-        let(:url) { 'google.com' }
-        let(:port) { 80 }
-        let(:options) { { :port => port } }
+    context 'when the first argument is a String' do
+      context 'but the second argument is not a Hash' do
+        let(:options) { :lol_not_a_hash }
 
-        it 'sets the specified url' do
-          subject.new(url, options).url.should == url
+        it 'raises an error' do
+          expect { subject }.to raise_error(Docker::Error::ArgumentError)
         end
+      end
 
-        it 'sets the specified port' do
-          subject.new(url, options).options[:port].should == port
+      context 'and the second argument is a Hash' do
+        it 'sets the url and options' do
+          subject.url.should == url
+          subject.options.should == options
         end
       end
     end
@@ -42,12 +38,42 @@ describe Docker::Connection do
     its(:resource) { should be_a Excon::Connection }
   end
 
+  describe '#request' do
+    let(:method) { :get }
+    let(:path) { '/test' }
+    let(:query) { { :all => true } }
+    let(:options) { { :expects => 201, :lol => true } }
+    let(:body) { rand(10000000) }
+    let(:resource) { mock(:resource) }
+    let(:response) { mock(:response, :body => body) }
+    let(:expected_hash) {
+      {
+        :method  => method,
+        :path    => "/v#{Docker::API_VERSION}#{path}",
+        :query   => query,
+        :headers => { 'Content-Type' => 'text/plain',
+                      'User-Agent'   => 'Docker-Client/0.4.6' },
+        :expects => 201,
+        :idempotent => true,
+        :lol => true
+      }
+    }
+
+    before do
+      subject.stub(:resource).and_return(resource)
+      resource.should_receive(:request).with(expected_hash).and_return(response)
+    end
+
+    it 'sends #request to #resource with the compiled params' do
+      subject.request(method, path, query, options).should == body
+    end
+  end
+
   [:get, :put, :post, :delete].each do |method|
     describe "##{method}" do
-      it 'is delegated to #resource' do
-        subject.should_receive(:reset!)
-        subject.stub_chain(:resource, :public_send).and_return(:lol)
-        subject.public_send(method).should == :lol
+      it 'is delegated to #request' do
+        subject.should_receive(:request).with(method)
+        subject.public_send(method)
       end
     end
   end
@@ -56,12 +82,12 @@ describe Docker::Connection do
     let(:url) { 'google.com' }
     let(:port) { 4000 }
     let(:options) { { :port => port } }
-    let(:expected_string) do
+    let(:expected_string) {
       "Docker::Connection { :url => #{url}, :options => #{options} }"
-    end
+    }
     subject { described_class.new(url, options) }
 
-    it 'returns a pretty printed version with the url and port' do
+    it 'returns a pretty version with the url and port' do
       subject.to_s.should == expected_string
     end
   end