docker-api 0.0.2

data/lib/docker/error.rb

@@ -0,0 +1,23 @@
+# This module holds the Errors for the gem.
+module Docker::Error
+
+  # The default error. It's never actually raised, but can be used to catch all
+  # gem-specific errors that are thrown as they all subclass from this.
+  class DockerError < StandardError; end
+
+  # 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
+
+  # Raised when a request returns a 500.
+  class ServerError < DockerError; end
+
+  # Raised when there is an unexpected response code / body.
+  class UnexpectedResponseError < DockerError; end
+end

data/lib/docker/image.rb

@@ -0,0 +1,73 @@
+# This class represents a Docker Image.
+class Docker::Image
+  include Docker::Model
+  resource_prefix '/images'
+
+  create_request do |options|
+    body = self.connection.post(
+      :path    => '/images/create',
+      :headers => { 'Content-Type' => 'application/x-www-form-urlencoded' },
+      :body    => hash_to_params(options),
+      :expects => (200..204)
+    ).body
+    self.id = JSON.parse(body)['status']
+    self
+  end
+
+  # Tag the Image.
+  docker_request :tag, :post
+  # Get more information about the Image.
+  docker_request :json, :get
+  # Push the Image to the Docker registry.
+  docker_request :push, :post
+  # Insert a file into the Image.
+  docker_request :insert, :post
+  # Get the history of the Image.
+  docker_request :history, :get
+
+  # Remove the Image from the server.
+  def remove
+    ensure_created!
+    self.connection.json_request(:delete, "/images/#{self.id}", nil)
+    self.id = nil
+    true
+  end
+
+  # Create a query string from a Hash.
+  def hash_to_params(hash)
+    hash.map { |k, v| "#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}" }.join('&')
+  end
+  private :hash_to_params
+
+  class << self
+    include Docker::Error
+    include Docker::Multipart
+
+    # 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) || []
+      hashes.map { |hash| new(:id => hash['Name'], :connection => connection) }
+    end
+
+    # Given a Dockerfile as a string, builds an Image.
+    def build(commands, connection = Docker.connection)
+      body = multipart_request(
+        '/build',
+        'Dockerfile',
+        StringIO.new("#{commands}\n"),
+        connection
+      )
+      new(:id => extract_id(body), :connection => connection)
+    end
+
+  private
+    def extract_id(body)
+      if match = body.lines.to_a[-1].match(/^===> ([a-f0-9]+)$/)
+        match[1]
+      else
+        raise UnexpectedResponseError, "Couldn't find id: #{body}"
+      end
+    end
+  end
+end

data/lib/docker/model.rb

@@ -0,0 +1,88 @@
+# 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
+  attr_reader :id, :connection
+
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  # Creates a new Model with the specified id and Connection. If a Connection
+  # is specified and it is not a Docker::Connection, a
+  # 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 = {})
+    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'
+    else
+      instance_exec(options, &self.class.create_request)
+    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
+    # Define the Model's prefix for all requests.
+    def resource_prefix(val = nil)
+      val.nil? ? @resource_prefix : (@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)
+    end
+
+    # Define a method named `action` that sends an http `method` request to the
+    # Docker Server.
+    def docker_request(action, method, &outer_block)
+      define_method(action) do |query = nil, &block|
+        ensure_created!
+        path = "#{self.class.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
+
+    # Retrieve every Instance of a model for the given server.
+    def all(options = {}, connection = Docker.connection)
+      path = "#{self.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

data/lib/docker/multipart.rb

@@ -0,0 +1,30 @@
+# This Mixin provides the ability to do multipart post requests.
+module Docker::Multipart
+  include Docker::Error
+
+  # Given a path, resource name, io, and Connection sends a multipart request.
+  def multipart_request(path, name, io, connection)
+    host, port = host_and_port(connection)
+    res = Net::HTTP.start(host, port) { |http|
+      req = build_multipart_post(path, io, 'application/octet-stream', name)
+      http.request(req)
+    }
+    if (200..204).include?(res.code.to_i)
+      res.body
+    else
+      raise UnexpectedResponseError, "Got status #{res.code}"
+    end
+  end
+
+private
+  # Return the host and port from a Connection.
+  def host_and_port(connection)
+    [URI.parse(connection.url).host, connection.options[:port]]
+  end
+
+  # Build the multipart post request.
+  def build_multipart_post(path, inner_io, content_type, file_name)
+    io = UploadIO.new(inner_io, content_type, file_name)
+    Net::HTTP::Post::Multipart.new(path, file_name => io)
+  end
+end

data/lib/docker/version.rb

@@ -0,0 +1,3 @@
+module Docker
+  VERSION = "0.0.2"
+end

data/spec/docker/connection_spec.rb

@@ -0,0 +1,67 @@
+require 'spec_helper'
+
+describe Docker::Connection do
+  describe '#initialize' do
+    subject { described_class }
+
+    context 'with no arguments' do
+      it 'defaults to port 4243' do
+        subject.new.options.should == { :port => 4243 }
+      end
+
+      it 'defaults to \'http://localhost\' for the url' do
+        subject.new.url.should == 'http://localhost'
+      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 } }
+
+        it 'sets the specified url' do
+          subject.new(url, options).url.should == url
+        end
+
+        it 'sets the specified port' do
+          subject.new(url, options).options[:port].should == port
+        end
+      end
+    end
+  end
+
+  describe '#resource' do
+    its(:resource) { should be_a Excon::Connection }
+  end
+
+  [:get, :put, :post, :delete].each do |method|
+    describe "##{method}" do
+      it 'is delegated to #resource' do
+        subject.resource.should_receive(method)
+        subject.public_send(method)
+      end
+    end
+  end
+
+  describe '#to_s' do
+    let(:url) { 'google.com' }
+    let(:port) { 4000 }
+    let(:options) { { :port => port } }
+    let(:expected_string) do
+      "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
+      subject.to_s.should == expected_string
+    end
+  end
+end

data/spec/docker/container_spec.rb

@@ -0,0 +1,529 @@
+require 'spec_helper'
+
+# WARNING if you're re-recording any of these VCRs, you must be running the
+# Docker daemon and have the base Image pulled.
+describe Docker::Container do
+  describe '#initialize' do
+    subject { described_class }
+
+    context 'with no argument' do
+      let(:container) { subject.new }
+
+      it 'sets the id to nil' do
+        container.id.should be_nil
+      end
+
+      it 'keeps the default Connection' do
+        container.connection.should == Docker.connection
+      end
+    end
+
+    context 'with an argument' do
+      let(:id) { 'a7c2ee4' }
+      let(:container) { subject.new(:id => id) }
+
+      it 'sets the id to the argument' do
+        container.id.should == id
+      end
+
+      it 'keeps the default Connection' do
+        container.connection.should == Docker.connection
+      end
+    end
+
+    context 'with two arguments' do
+      context 'when the second argument is not a Docker::Connection' do
+        let(:id) { 'abc123f' }
+        let(:connection) { :not_a_connection }
+        let(:container) { subject.new(:id => id, :connection => connection) }
+
+        it 'raises an error' do
+          expect { container }.to raise_error(Docker::Error::ArgumentError)
+        end
+      end
+
+      context 'when the second argument is a Docker::Connection' do
+        let(:id) { 'cb3f14a' }
+        let(:connection) { Docker::Connection.new }
+        let(:container) { subject.new(:id => id, :connection => connection) }
+
+        it 'initializes the Container' do
+          container.id.should == id
+          container.connection.should == connection
+        end
+      end
+    end
+  end
+
+  describe '#to_s' do
+    let(:id) { 'bf119e2' }
+    let(:connection) { Docker::Connection.new }
+    let(:expected_string) do
+      "Docker::Container { :id => #{id}, :connection => #{connection} }"
+    end
+    subject { described_class.new(:id => id, :connection => connection)  }
+
+    its(:to_s) { should == expected_string }
+  end
+
+  describe '#created?' do
+    context 'when the id is nil' do
+      its(:created?) { should be_false }
+    end
+
+    context 'when the id is present' do
+      subject { described_class.new(:id => 'a732ebf') }
+
+      its(:created?) { should be_true }
+    end
+  end
+
+  describe '#create!' do
+    context 'when the Container has already been created' do
+      subject { described_class.new(:id => '5e88b2a') }
+
+      it 'raises an error' do
+        expect { subject.create! }
+            .to raise_error(Docker::Error::StateError)
+      end
+    end
+
+    context 'when the body is not a Hash' do
+      it 'raises an error' do
+        expect { subject.create!(:not_a_hash) }
+            .to raise_error(Docker::Error::ArgumentError)
+      end
+    end
+
+    context 'when the Container does not yet exist and the body is a Hash' do
+      context 'when the HTTP request does not return a 200' do
+        before { Excon.stub({ :method => :post }, { :status => 400 }) }
+        after { Excon.stubs.shift }
+
+        it 'raises an error' do
+          expect { subject.create! }.to raise_error(Docker::Error::ClientError)
+        end
+      end
+
+      context 'when the HTTP request returns a 200' do
+        let(:options) do
+          {
+            "Hostname"     => "",
+            "User"         => "",
+            "Memory"       => 0,
+            "MemorySwap"   => 0,
+            "AttachStdin"  => false,
+            "AttachStdout" => false,
+            "AttachStderr" => false,
+            "PortSpecs"    => nil,
+            "Tty"          => false,
+            "OpenStdin"    => false,
+            "StdinOnce"    => false,
+            "Env"          => nil,
+            "Cmd"          => ["date"],
+            "Dns"          => nil,
+            "Image"        => "base",
+            "Volumes"      => {},
+            "VolumesFrom"  => ""
+          }
+        end
+
+        it 'sets the id', :vcr do
+          expect { subject.create!(options) }
+              .to change { subject.id }
+              .from(nil)
+        end
+      end
+    end
+  end
+
+  describe '#json' do
+    context 'when the Container has not been created' do
+      it 'raises an error' do
+        expect { subject.json }.to raise_error Docker::Error::StateError
+      end
+    end
+
+    context 'when the Container has been created' do
+      context 'when the HTTP response status is not 200' do
+        before do
+          subject.stub(:created?).and_return(true)
+          Excon.stub({ :method => :get }, { :status => 500 })
+        end
+        after { Excon.stubs.shift }
+
+        it 'raises an error' do
+          expect { subject.json }
+              .to raise_error(Docker::Error::ServerError)
+        end
+      end
+
+      context 'when the HTTP response status is 200' do
+        let(:description) { subject.json }
+        before { subject.create!('Cmd' => ['ls'], 'Image' => 'base') }
+
+        it 'returns the description as a Hash', :vcr do
+          description.should be_a(Hash)
+          description['Id'].should start_with(subject.id)
+        end
+      end
+    end
+  end
+
+  describe '#changes' do
+    context 'when the Container has not been created' do
+      it 'raises an error' do
+        expect { subject.changes }
+            .to raise_error Docker::Error::StateError
+      end
+    end
+
+    context 'when the Container has been created' do
+      context 'when the HTTP response status is not 200' do
+        before do
+          subject.stub(:created?).and_return(true)
+          Excon.stub({ :method => :get }, { :status => 500 })
+        end
+        after { Excon.stubs.shift }
+
+        it 'raises an error' do
+          expect { subject.changes }
+              .to raise_error(Docker::Error::ServerError)
+        end
+      end
+
+      context 'when the HTTP response status is 200' do
+        let(:changes) { subject.changes }
+        before do
+          subject.create!('Cmd' => ['ls'], 'Image' => 'base')
+          subject.start
+          subject.wait
+        end
+
+        it 'returns the changes as an array', :vcr do
+          changes.should be_a Array
+          changes.should be_all { |change| change.is_a?(Hash) }
+          changes.length.should_not be_zero
+        end
+      end
+    end
+  end
+
+  describe '#export' do
+    context 'when the Container has not been created' do
+      it 'raises an error' do
+        expect { subject.export { } }
+            .to raise_error Docker::Error::StateError
+      end
+    end
+
+    context 'when the Container has been created' do
+      context 'when the HTTP response status is not 200' do
+        before do
+          subject.stub(:created?).and_return(true)
+          Excon.stub({ :method => :get }, { :status => 500 })
+        end
+        after { Excon.stubs.shift }
+
+        it 'raises an error' do
+          expect { subject.export { } }
+              .to raise_error(Docker::Error::ServerError)
+        end
+      end
+
+      context 'when the HTTP response status is 200' do
+        before do
+          subject.create!('Cmd' => %w[rm -rf / --no-preserve-root],
+                          'Image' => 'base')
+          subject.start
+        end
+
+        it 'yields each chunk', :vcr do
+          first = nil
+          subject.export do |chunk|
+            first = chunk
+            break
+          end
+          first[257..262].should == "ustar\000" # Make sure the export is a tar.
+        end
+      end
+    end
+  end
+
+  describe '#attach' do
+    context 'when the Container has not been created' do
+      it 'raises an error' do
+        expect { subject.attach { } }
+            .to raise_error Docker::Error::StateError
+      end
+    end
+
+    context 'when the Container has been created' do
+      context 'when the HTTP response status is not 200' do
+        before do
+          subject.stub(:created?).and_return(true)
+          Excon.stub({ :method => :post }, { :status => 500 })
+        end
+        after { Excon.stubs.shift }
+
+        it 'raises an error' do
+          expect { subject.attach { } }
+              .to raise_error(Docker::Error::ServerError)
+        end
+      end
+
+      context 'when the HTTP response status is 200' do
+        before { subject.create!('Cmd' => %w[uname -r], 'Image' => 'base') }
+
+        it 'yields each chunk', :vcr do
+          subject.tap(&:start).attach { |chunk|
+            chunk.should == "3.8.0-25-generic\n"
+          }
+        end
+      end
+    end
+  end
+
+  describe '#start' do
+    context 'when the Container has not been created' do
+      it 'raises an error' do
+        expect { subject.start }.to raise_error Docker::Error::StateError
+      end
+    end
+
+    context 'when the Container has been created' do
+      context 'when the HTTP response status is not 200' do
+        before do
+          subject.stub(:created?).and_return(true)
+          Excon.stub({ :method => :post }, { :status => 500 })
+        end
+        after { Excon.stubs.shift }
+
+        it 'raises an error' do
+          expect { subject.start }
+              .to raise_error(Docker::Error::ServerError)
+        end
+      end
+
+      context 'when the HTTP response status is 200' do
+        before { subject.create!('Cmd' => ['/usr/bin/sleep 10'],
+                                 'Image' => 'base') }
+
+        it 'starts the container', :vcr do
+          subject.start
+          described_class.all.map(&:id).should be_any { |id|
+            id.start_with?(subject.id)
+          }
+        end
+      end
+    end
+  end
+
+  describe '#stop' do
+    context 'when the Container has not been created' do
+      it 'raises an error' do
+        expect { subject.stop }.to raise_error Docker::Error::StateError
+      end
+    end
+
+    context 'when the Container has been created' do
+      context 'when the HTTP response status is not 204' do
+        before do
+          subject.stub(:created?).and_return(true)
+          Excon.stub({ :method => :post }, { :status => 500 })
+        end
+        after { Excon.stubs.shift }
+
+        it 'raises an error' do
+          expect { subject.stop }
+              .to raise_error(Docker::Error::ServerError)
+        end
+      end
+
+      context 'when the HTTP response status is 204' do
+        before { subject.create!('Cmd' => ['ls'], 'Image' => 'base') }
+
+        it 'stops the container', :vcr do
+          subject.tap(&:start).stop
+          described_class.all(:all => true).map(&:id).should be_any { |id|
+            id.start_with?(subject.id)
+          }
+          described_class.all.map(&:id).should be_none { |id|
+            id.start_with?(subject.id)
+          }
+        end
+      end
+    end
+  end
+
+  describe '#kill' do
+    context 'when the Container has not been created' do
+      it 'raises an error' do
+        expect { subject.kill }.to raise_error Docker::Error::StateError
+      end
+    end
+
+    context 'when the Container has been created' do
+      context 'when the HTTP response status is not 204' do
+        before do
+          subject.stub(:created?).and_return(true)
+          Excon.stub({ :method => :post }, { :status => 500 })
+        end
+        after { Excon.stubs.shift }
+
+        it 'raises an error' do
+          expect { subject.kill }
+              .to raise_error(Docker::Error::ServerError)
+        end
+      end
+
+      context 'when the HTTP response status is 204' do
+        before { subject.create!('Cmd' => ['ls'], 'Image' => 'base') }
+
+        it 'kills the container', :vcr do
+          subject.kill
+          described_class.all.map(&:id).should be_none { |id|
+            id.start_with?(subject.id)
+          }
+          described_class.all(:all => true).map(&:id).should be_any { |id|
+            id.start_with?(subject.id)
+          }
+        end
+      end
+    end
+  end
+
+  describe '#restart' do
+    context 'when the Container has not been created' do
+      it 'raises an error' do
+        expect { subject.restart }.to raise_error Docker::Error::StateError
+      end
+    end
+
+    context 'when the Container has been created' do
+      context 'when the HTTP response status is not 204' do
+        before do
+          subject.stub(:created?).and_return(true)
+          Excon.stub({ :method => :post }, { :status => 500 })
+        end
+        after { Excon.stubs.shift }
+
+        it 'raises an error' do
+          expect { subject.restart }
+              .to raise_error(Docker::Error::ServerError)
+        end
+      end
+
+      context 'when the HTTP response status is 204' do
+        before { subject.create!('Cmd' => ['/usr/bin/sleep 50'],
+                                 'Image' => 'base') }
+
+        it 'restarts the container', :vcr do
+          subject.start
+          described_class.all.map(&:id).should be_any { |id|
+            id.start_with?(subject.id)
+          }
+          subject.stop
+          described_class.all.map(&:id).should be_none { |id|
+            id.start_with?(subject.id)
+          }
+          subject.restart
+          described_class.all.map(&:id).should be_any { |id|
+            id.start_with?(subject.id)
+          }
+        end
+      end
+    end
+  end
+
+  describe '#wait' do
+    context 'when the Container has not been created' do
+      it 'raises an error' do
+        expect { subject.wait }.to raise_error Docker::Error::StateError
+      end
+    end
+
+    context 'when the Container has been created' do
+      context 'when the HTTP response status is not 200' do
+        before do
+          subject.stub(:created?).and_return(true)
+          Excon.stub({ :method => :post }, { :status => 500 })
+        end
+        after { Excon.stubs.shift }
+
+        it 'raises an error' do
+          expect { subject.wait }
+              .to raise_error(Docker::Error::ServerError)
+        end
+      end
+
+      context 'when the HTTP response status is 200' do
+        before { subject.create!('Cmd' => %w[tar nonsense],
+                                 'Image' => 'base') }
+
+        it 'waits for the command to finish', :vcr do
+          subject.start
+          subject.wait['StatusCode'].should == 64
+        end
+      end
+    end
+  end
+
+  describe '#commit' do
+    context 'when the Container has not been created' do
+      it 'raises an error' do
+        expect { subject.commit }.to raise_error Docker::Error::StateError
+      end
+    end
+
+    context 'when the Container has been created' do
+      context 'when the HTTP response status is not 200' do
+        before do
+          subject.stub(:id).and_return('abc')
+          Excon.stub({ :method => :post }, { :status => 500 })
+        end
+        after { Excon.stubs.shift }
+
+        it 'raises an error' do
+          expect { subject.commit }
+              .to raise_error(Docker::Error::ServerError)
+        end
+      end
+
+      context 'when the HTTP response status is 200' do
+        let(:image) { subject.commit }
+        before { subject.create!('Cmd' => %w[ls], 'Image' => 'base') }
+
+        it 'creates a new Image from the  Container\'s changes', :vcr do
+          subject.start
+          image.should be_a Docker::Image
+          image.id.should_not be_nil
+        end
+      end
+    end
+  end
+
+  describe '.all' do
+    subject { described_class }
+
+    context 'when the HTTP response is not a 200' do
+      before { Excon.stub({ :method => :get }, { :status => 500 }) }
+      after { Excon.stubs.shift }
+
+      it 'raises an error' do
+        expect { subject.all }
+            .to raise_error(Docker::Error::ServerError)
+      end
+    end
+
+    context 'when the HTTP response is a 200' do
+      it 'materializes each Container into a Docker::Container', :vcr do
+        subject.new.create!('Cmd' => ['ls'], 'Image' => 'base')
+        subject.all(:all => true).should be_all { |container|
+          container.is_a?(Docker::Container)
+        }
+        subject.all(:all => true).length.should_not be_zero
+      end
+    end
+  end
+end