docker-api 0.0.2

data/.gitignore

@@ -0,0 +1,3 @@
+.DS_Store
+*.swp
+Gemfile.lock

data/Gemfile

@@ -0,0 +1,3 @@
+source 'http://rubygems.org'
+
+gemspec

data/README.md

@@ -0,0 +1,215 @@
+docker-api
+==========
+
+This gem provides an object-oriented interface to the [Docker Remote API](http://docs.docker.io/en/latest/api/docker_remote_api_v1.2/). Every method listed there is implemented, with the exception of attaching to the STDIN of a Container. At the time of this writing, docker-api is meant to interface with Docker version 0.4.0.
+
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'docker-api'
+```
+
+And then run:
+
+```shell
+$ bundle install
+```
+
+Alternatively, if you wish to just use the gem in a script, you can run:
+
+```shell
+$ gem install docker-api
+```
+
+Finally, just add `require 'docker'` to the top of the file using this gem.
+
+Usage
+-----
+
+docker-api is designed to be very lightweight. Almost no state is cached (aside from id's which are immutable) to ensure that each method call's information is up to date. As such, just about every extrenal method represents an API call.
+
+## Starting up
+
+Follow the [installation instructions](http://www.docker.io/gettingstarted/), and then run:
+
+```shell
+$ sudo docker -d
+```
+
+This will daemonize Docker so that it can be used for the remote API calls.
+
+If you're running Docker locally, there is no setup to do in Ruby. If you're not, you'll have to point the gem to your server. For example:
+
+```ruby
+Docker.url = 'http://example.com'
+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.
+
+## 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.
+
+```ruby
+require 'docker'
+# => true
+
+Docker.version
+# => { 'Version' => '0.4.0', 'GoVersion' => 'go1.0.3' }
+
+Docker.info
+# => { "Debug" => false, "Containers" => 187, "Images" => 196, "NFd" => 10, "NGoroutines" => 9, "MemoryLimit" => true }
+
+Docker.authenticate!('username' => 'docker-fan-boi', 'password' => 'i<3docker', 'email' => 'dockerboy22@aol.com')
+# => true
+```
+
+## 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.
+
+```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', 'fromSrc' => '-')
+# => Docker::Image { :id => ae7ffbcd1, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }
+
+image.created?
+# => true
+
+# Insert a file into an Image.
+image.insert('path' => '/usr', 'url' => '/home/user/.vimrc')
+# => { 'Id' => '' }
+
+# Tag an Image.
+image.tag('repo' => 'base2', 'force' => true)
+# => nil
+
+# Get more information about the Image.
+image.json
+# => {"id"=>"67859327bf22ef8b5b9b4a6781f72b2015acd894fa03ce07e0db7af170ba468c", "comment"=>"Imported from -", "created"=>"2013-06-19T18:42:58.287944526-04:00", "container_config"=>{"Hostname"=>"", "User"=>"", "Memory"=>0, "MemorySwap"=>0, "CpuShares"=>0, "AttachStdin"=>false, "AttachStdout"=>false, "AttachStderr"=>false, "PortSpecs"=>nil, "Tty"=>false, "OpenStdin"=>false, "StdinOnce"=>false, "Env"=>nil, "Cmd"=>nil, "Dns"=>nil, "Image"=>"", "Volumes"=>nil, "VolumesFrom"=>""}, "docker_version"=>"0.4.0", "architecture"=>"x86_64"}
+
+# View the history of the Image.
+image.history
+# => [{"Id"=>"67859327bf22", "Created"=>1371681778}]
+
+# Remove the Image from the server.
+image.remove
+# => true
+
+image.created?
+# => false
+
+# 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.
+Docker::Image.build("from base\nrun touch /test")
+# => Docker::Image { :id => b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc, :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.
+
+```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')
+# => 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}
+
+# Start running the Container.
+container.start
+# => nil
+
+# Stop running the Container.
+container.stop
+# => nil
+
+# Restart the Container.
+container.restart
+# => nil
+
+# Kill the command running in the Container.
+container.kill
+# => nil
+
+# Export a Container. Since an export is typically at least 300M, chunks of the
+# export are yielded instead of just returning the whole thing.
+File.open('export.tar.gz', 'w') do |f|
+  container.export { |chunk| file.write(chunk) }
+end
+# => nil
+
+# Inspect a Container's changes to the file system.
+container.changes
+# => [{'Path'=>'/dev', 'Kind'=>0}, {'Path'=>'/dev/kmsg', 'Kind'=>1}]
+
+# Wait for the current command to finish executing.
+container.wait
+# => {'StatusCode'=>0}
+
+# Attach to the Container. Currently, the below options are the only valid ones.
+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"
+
+# Create an Image from a Container's changes.
+container.commit
+# => Docker::Image { :id => eaeb8d00efdf, :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }
+
+# Request all of the Containers. By default, will only return the running Containers.
+Docker::Container.all(:all => true)
+# => [Docker::Container { :id => , :connection => Docker::Connection { :url => http://localhost, :options => {:port=>4243} } }]
+```
+
+## 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:
+
+```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({ :term => 'sshd' }, Docker::Connection.new(:url => 'http://example.com'))
+```
+
+## Known Issues
+- `Docker::Container#attach` cannot attach to STDIN

data/Rakefile

@@ -0,0 +1,16 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), 'lib'))
+
+require 'rake'
+require 'docker'
+require 'rspec/core/rake_task'
+require 'cane/rake_task'
+
+task :default => [:spec, :quality]
+
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = 'spec/**/*_spec.rb'
+end
+
+Cane::RakeTask.new(:quality) do |cane|
+  cane.canefile = '.cane'
+end

data/docker-api.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/docker/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Swipely, Inc."]
+  gem.email         = %w{tomhulihan@swipely.com bright@swipely.com}
+  gem.description   = %q{A simple REST client for the Docker Remote API}
+  gem.summary       = %q{A simple REST client for the Docker Remote API}
+  gem.homepage      = 'https://github.com/swipely/docker-api'
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "docker-api"
+  gem.require_paths = %w{lib}
+  gem.version       = Docker::VERSION
+  gem.add_dependency 'excon', '>= 0.22.0'
+  gem.add_dependency 'json'
+  gem.add_dependency 'i18n'
+  gem.add_dependency 'multipart-post'
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'cane'
+  gem.add_development_dependency 'pry'
+  gem.add_development_dependency 'webmock', '>= 1.11.0'
+  gem.add_development_dependency 'vcr', '>= 2.4.0'
+end

data/lib/docker.rb

@@ -0,0 +1,60 @@
+require 'cgi'
+require 'json'
+require 'excon'
+require 'net/http/post/multipart'
+
+# The top-level module for this gem. It's purpose is to hold global
+# configuration variables that are used as defaults in other classes.
+module Docker
+  class << self
+    def url
+      @url ||= 'http://localhost'
+    end
+
+    def options
+      @options ||= { :port => 4243 }
+    end
+
+    def url=(new_url)
+      @url = new_url
+      reset_connection!
+    end
+
+    def options=(new_options)
+      @options = { :port => 4243 }.merge(new_options)
+      reset_connection!
+    end
+
+    def connection
+      @connection ||= Connection.new(url, options)
+    end
+
+    def reset_connection!
+      @connection = nil
+    end
+
+    # Get the version of Go, Docker, and optionally the Git commit.
+    def version
+      connection.json_request(:get, '/version')
+    end
+
+    # Get more information about the Docker server.
+    def info
+      connection.json_request(:get, '/info')
+    end
+
+    # Login to the Docker registry.
+    def authenticate!(options = {})
+      connection.post(:path => '/auth', :body => options)
+      true
+    end
+  end
+end
+
+require 'docker/version'
+require 'docker/error'
+require 'docker/connection'
+require 'docker/model'
+require 'docker/multipart'
+require 'docker/container'
+require 'docker/image'

data/lib/docker/connection.rb

@@ -0,0 +1,65 @@
+# This class represents a Connection to a Docker server. The Connection is
+# immutable in that once the url and options is set they cannot be changed.
+class Docker::Connection
+  include Docker::Error
+
+  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}"
+    end
+    self.url = url
+    self.options = { :port => 4243 }.merge(options)
+  end
+
+  # The actual client that sends HTTP methods to the docker server.
+  def resource
+    @resource ||= Excon.new(self.url, self.options)
+  end
+
+  # Delegate all HTTP methods to the resource.
+  [:get, :put, :post, :delete, :request].each do |method|
+    define_method(method) do |*args, &block|
+      begin
+        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
+  end
+
+  def to_s
+    "Docker::Connection { :url => #{self.url}, :options => #{self.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)
+    {
+      :method         => http_method,
+      :path           => path,
+      :query          => query,
+      :headers        => { 'Content-Type' => 'application/json' },
+      :expects        => (200..204),
+      :idempotent     => http_method == :get,
+      :response_block => block
+    }.reject { |_, v| v.nil? }
+  end
+end

data/lib/docker/container.rb

@@ -0,0 +1,54 @@
+# This class represents a Docker Container. It's important to note that nothing
+# is cached so that the information is always up to date.
+class Docker::Container
+  include Docker::Model
+
+  resource_prefix '/containers'
+
+  create_request do |body|
+    response = self.connection.post(
+      :path    => '/containers/create',
+      :headers => { 'Content-Type' => 'application/json' },
+      :body    => body.to_json,
+      :expects => (200..204)
+    )
+    self.id = JSON.parse(response.body)['Id']
+    self
+  end
+
+  # Export the Container as a .tgz.
+  docker_request :export, :get
+  # Get more information about the Container.
+  docker_request :json, :get
+  # Wait for the current command to finish executing.
+  docker_request :wait, :post
+  # Start the Container.
+  docker_request :start, :post
+  # Inspect the Container's changes to the filesysetem
+  docker_request :changes, :get
+  # Stop the Container.
+  docker_request :stop, :post
+  # Kill the Container.
+  docker_request :kill, :post
+  # Restart the Container
+  docker_request :restart, :post
+
+  # Attach to a container's standard streams / logs.
+  def attach(options = {})
+    ensure_created!
+    self.connection.request(
+      :method  => :post,
+      :path    => "/containers/#{self.id}/attach",
+      :query   => options,
+      :expects => (200..204)
+    ).body
+  end
+
+  # 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)
+  end
+end