docker-api 2.0.0.pre.1

data/lib/docker-api.rb

@@ -0,0 +1 @@
+require 'docker'

data/lib/docker.rb

@@ -0,0 +1,136 @@
+require 'cgi'
+require 'multi_json'
+require 'excon'
+require 'tempfile'
+require 'base64'
+require 'find'
+require 'rubygems/package'
+require 'uri'
+require 'open-uri'
+
+# Add the Hijack middleware at the top of the middleware stack so it can
+# potentially hijack HTTP sockets (when attaching to stdin) before other
+# middlewares try and parse the response.
+require 'excon/middlewares/hijack'
+Excon.defaults[:middlewares].unshift Excon::Middleware::Hijack
+
+Excon.defaults[:middlewares] << Excon::Middleware::RedirectFollower
+
+# The top-level module for this gem. Its purpose is to hold global
+# configuration variables that are used as defaults in other classes.
+module Docker
+  attr_accessor :creds, :logger
+
+  require 'docker/error'
+  require 'docker/connection'
+  require 'docker/base'
+  require 'docker/container'
+  require 'docker/network'
+  require 'docker/event'
+  require 'docker/exec'
+  require 'docker/image'
+  require 'docker/messages_stack'
+  require 'docker/messages'
+  require 'docker/util'
+  require 'docker/version'
+  require 'docker/volume'
+  require 'docker/rake_task' if defined?(Rake::Task)
+
+  def default_socket_url
+    'unix:///var/run/docker.sock'
+  end
+
+  def env_url
+    ENV['DOCKER_URL'] || ENV['DOCKER_HOST']
+  end
+
+  def env_options
+    if cert_path = ENV['DOCKER_CERT_PATH']
+      {
+        client_cert: File.join(cert_path, 'cert.pem'),
+        client_key: File.join(cert_path, 'key.pem'),
+        ssl_ca_file: File.join(cert_path, 'ca.pem'),
+        scheme: 'https'
+      }.merge(ssl_options)
+    else
+      {}
+    end
+  end
+
+  def ssl_options
+    if ENV['DOCKER_SSL_VERIFY'] == 'false'
+      {
+        ssl_verify_peer: false
+      }
+    else
+      {}
+    end
+  end
+
+  def url
+    @url ||= env_url || default_socket_url
+    # docker uses a default notation tcp:// which means tcp://localhost:2375
+    if @url == 'tcp://'
+      @url = 'tcp://localhost:2375'
+    end
+    @url
+  end
+
+  def options
+    @options ||= env_options
+  end
+
+  def url=(new_url)
+    @url = new_url
+    reset_connection!
+  end
+
+  def options=(new_options)
+    @options = env_options.merge(new_options || {})
+    reset_connection!
+  end
+
+  def connection
+    @connection ||= Connection.new(url, options)
+  end
+
+  def reset!
+    @url = nil
+    @options = nil
+    reset_connection!
+  end
+
+  def reset_connection!
+    @connection = nil
+  end
+
+  # Get the version of Go, Docker, and optionally the Git commit.
+  def version(connection = self.connection)
+    Util.parse_json(connection.get('/version'))
+  end
+
+  # Get more information about the Docker server.
+  def info(connection = self.connection)
+    Util.parse_json(connection.get('/info'))
+  end
+
+  # Ping the Docker server.
+  def ping(connection = self.connection)
+    connection.get('/_ping')
+  end
+
+  # Login to the Docker registry.
+  def authenticate!(options = {}, connection = self.connection)
+    creds = MultiJson.dump(options)
+    connection.post('/auth', {}, body: creds)
+    @creds = creds
+    true
+  rescue Docker::Error::ServerError, Docker::Error::UnauthorizedError
+    raise Docker::Error::AuthenticationError
+  end
+
+  module_function :default_socket_url, :env_url, :url, :url=, :env_options,
+                  :options, :options=, :creds, :creds=, :logger, :logger=,
+                  :connection, :reset!, :reset_connection!, :version, :info,
+                  :ping, :authenticate!, :ssl_options
+end

data/lib/docker/base.rb

@@ -0,0 +1,25 @@
+# This class is a base class for Docker Container and Image.
+# It is implementing accessor methods for the models attributes.
+module Docker::Base
+  include Docker::Error
+
+  attr_accessor :connection, :info
+  attr_reader :id
+
+  # The private new method accepts a connection and a hash of options that must include an id.
+  def initialize(connection, hash={})
+    unless connection.is_a?(Docker::Connection)
+      raise ArgumentError, "Expected a Docker::Connection, got: #{connection}."
+    end
+    normalize_hash(hash)
+    @connection, @info, @id = connection, hash, hash['id']
+    raise ArgumentError, "Must have id, got: #{hash}" unless @id
+  end
+
+  # The docker-api will some time return "ID" other times it will return "Id"
+  # and other times it will return "id". This method normalize it to "id"
+  # The volumes endpoint returns Name instead of ID, added in the normalize function
+  def normalize_hash(hash)
+    hash["id"] ||= hash.delete("ID") || hash.delete("Id")
+  end
+end

data/lib/docker/connection.rb

@@ -0,0 +1,93 @@
+# 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. 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
+      uri = URI.parse(url)
+      if uri.scheme == "unix"
+        @url, @options = 'unix:///', {:socket => uri.path}.merge(opts)
+      elsif uri.scheme =~ /^(https?|tcp)$/
+        @url, @options = url, opts
+      else
+        @url, @options = "http://#{uri}", opts
+      end
+    end
+  end
+
+  # 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
+    Excon.new(url, options)
+  end
+  private :resource
+
+  # Send a request to the server with the `
+  def request(*args, &block)
+    request = compile_request_params(*args, &block)
+    log_request(request)
+    resource.request(request).body
+  rescue Excon::Errors::BadRequest => ex
+    raise ClientError, ex.response.body
+  rescue Excon::Errors::Unauthorized => ex
+    raise UnauthorizedError, ex.response.body
+  rescue Excon::Errors::NotFound => ex
+    raise NotFoundError, ex.response.body
+  rescue Excon::Errors::Conflict => ex
+    raise ConflictError, ex.response.body
+  rescue Excon::Errors::InternalServerError => ex
+    raise ServerError, ex.response.body
+  rescue Excon::Errors::Timeout => ex
+    raise TimeoutError, ex.message
+  end
+
+  def log_request(request)
+    if Docker.logger
+      Docker.logger.debug(
+        [request[:method], request[:path], request[:query], request[:body]]
+      )
+    end
+  end
+
+  # 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 => #{url}, :options => #{options} }"
+  end
+
+private
+  # 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) || {}
+    content_type = opts[:body].nil? ?  'text/plain' : 'application/json'
+    user_agent = "Swipely/Docker-API #{Docker::VERSION}"
+    {
+      :method        => http_method,
+      :path          => path,
+      :query         => query,
+      :headers       => { 'Content-Type' => content_type,
+                          'User-Agent'   => user_agent,
+                        }.merge(headers),
+      :expects       => (200..204).to_a << 301 << 304,
+      :idempotent    => http_method == :get,
+      :request_block => block,
+    }.merge(opts).reject { |_, v| v.nil? }
+  end
+end

data/lib/docker/container.rb

@@ -0,0 +1,360 @@
+# 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::Base
+
+  # Update the @info hash, which is the only mutable state in this object.
+  #   e.g. if you would like a live status from the #info hash, call #refresh! first.
+  def refresh!
+    other = Docker::Container.all({all: true}, connection).find { |c|
+      c.id.start_with?(self.id) || self.id.start_with?(c.id)
+    }
+
+    info.merge!(self.json)
+    other && info.merge!(other.info) { |key, info_value, other_value| info_value }
+    self
+  end
+
+  # Return a List of Hashes that represents the top running processes.
+  def top(opts = {})
+    format = opts.delete(:format) { :array }
+    resp = Docker::Util.parse_json(connection.get(path_for(:top), opts))
+    if resp['Processes'].nil?
+      format == :array ? [] : {}
+    else
+      format == :array ? resp['Processes'].map { |ary| Hash[resp['Titles'].zip(ary)] } : resp
+    end
+  end
+
+  # Wait for the current command to finish executing. Default wait time is
+  # `Excon.options[:read_timeout]`.
+  def wait(time = nil)
+    excon_params = { :read_timeout => time }
+    resp = connection.post(path_for(:wait), nil, excon_params)
+    Docker::Util.parse_json(resp)
+  end
+
+  # Given a command and an optional number of seconds to wait for the currently
+  # executing command, creates a new Container to run the specified command. If
+  # the command that is currently executing does not return a 0 status code, an
+  # UnexpectedResponseError is raised.
+  def run(cmd, time = 1000)
+    if (code = tap(&:start).wait(time)['StatusCode']).zero?
+      commit.run(cmd)
+    else
+      raise UnexpectedResponseError, "Command returned status code #{code}."
+    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, options = {}, &block)
+    # Establish values
+    tty = options.delete(:tty) || false
+    detach = options.delete(:detach) || false
+    user = options.delete(:user)
+    stdin = options.delete(:stdin)
+    stdout = options.delete(:stdout) || !detach
+    stderr = options.delete(:stderr) || !detach
+    wait = options.delete(:wait)
+
+    opts = {
+      'Container' => self.id,
+      'User' => user,
+      'AttachStdin' => !!stdin,
+      'AttachStdout' => stdout,
+      'AttachStderr' => stderr,
+      'Tty' => tty,
+      'Cmd' => command
+    }.merge(options)
+
+    # Create Exec Instance
+    instance = Docker::Exec.create(
+      opts,
+      self.connection
+    )
+
+    start_opts = {
+      :tty => tty,
+      :stdin => stdin,
+      :detach => detach,
+      :wait => wait
+    }
+
+    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)
+    self
+  end
+
+  # Attach to a container's standard streams / logs.
+  def attach(options = {}, excon_params = {}, &block)
+    stdin = options.delete(:stdin)
+    tty   = options.delete(:tty)
+
+    opts = {
+      :stream => true, :stdout => true, :stderr => true
+    }.merge(options)
+    # Creates list to store stdout and stderr messages
+    msgs = Docker::Messages.new
+
+    if stdin
+      # 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] = Docker::Util.hijack_for(stdin, block,
+        msgs, tty)
+    else
+      excon_params[:response_block] = Docker::Util.attach_for(block, msgs, tty)
+    end
+
+    connection.post(
+      path_for(:attach),
+      opts,
+      excon_params
+    )
+    [msgs.stdout_messages, msgs.stderr_messages]
+  end
+
+  # Create an Image from a Container's change.s
+  def commit(options = {})
+    options.merge!('container' => self.id[0..7])
+    # [code](https://github.com/dotcloud/docker/blob/v0.6.3/commands.go#L1115)
+    # Based on the link, the config passed as run, needs to be passed as the
+    # body of the post so capture it, remove from the options, and pass it via
+    # the post body
+    config = MultiJson.dump(options.delete('run'))
+    hash = Docker::Util.parse_json(
+      connection.post('/commit', options, body: config)
+    )
+    Docker::Image.send(:new, self.connection, hash)
+  end
+
+  # Return a String representation of the Container.
+  def to_s
+    "Docker::Container { :id => #{self.id}, :connection => #{self.connection} }"
+  end
+
+  # #json returns information about the Container, #changes returns a list of
+  # the changes the Container has made to the filesystem.
+  [:json, :changes].each do |method|
+    define_method(method) do |opts = {}|
+      Docker::Util.parse_json(connection.get(path_for(method), opts))
+    end
+  end
+
+  def logs(opts = {})
+    connection.get(path_for(:logs), opts)
+  end
+
+  def stats(options = {})
+    if block_given?
+      options[:read_timeout] ||= 10
+      options[:idempotent] ||= false
+      parser = lambda do |chunk, remaining_bytes, total_bytes|
+        yield Docker::Util.parse_json(chunk)
+      end
+      begin
+        connection.get(path_for(:stats), nil, {response_block: parser}.merge(options))
+      rescue Docker::Error::TimeoutError
+        # If the container stops, the docker daemon will hold the connection
+        # open forever, but stop sending events.
+        # So this Timeout indicates the stream is over.
+      end
+    else
+      Docker::Util.parse_json(connection.get(path_for(:stats), {stream: 0}.merge(options)))
+    end
+  end
+
+  def rename(new_name)
+    query = {}
+    query['name'] = new_name
+    connection.post(path_for(:rename), query)
+  end
+
+  def update(opts)
+    connection.post(path_for(:update), {}, body: MultiJson.dump(opts))
+  end
+
+  def streaming_logs(opts = {}, &block)
+    stack_size = opts.delete('stack_size') || opts.delete(:stack_size) || -1
+    tty = opts.delete('tty') || opts.delete(:tty) || false
+    msgs = Docker::MessagesStack.new(stack_size)
+    excon_params = {response_block: Docker::Util.attach_for(block, msgs, tty), idempotent: false}
+
+    connection.get(path_for(:logs), opts, excon_params)
+    msgs.messages.join
+  end
+
+  def start!(opts = {})
+    connection.post(path_for(:start), {}, body: MultiJson.dump(opts))
+    self
+  end
+
+  def kill!(opts = {})
+    connection.post(path_for(:kill), opts)
+    self
+  end
+
+  # #start! and #kill! both perform the associated action and
+  # return the Container. #start and #kill do the same,
+  # but rescue from ServerErrors.
+  [:start, :kill].each do |method|
+    define_method(method) do |*args|
+      begin; public_send(:"#{method}!", *args); rescue ServerError; self end
+    end
+  end
+
+  # #stop! and #restart! both perform the associated action and
+  # return the Container. #stop and #restart do the same,
+  # but rescue from ServerErrors.
+  [:stop, :restart].each do |method|
+    define_method(:"#{method}!") do |opts = {}|
+      timeout = opts.delete('timeout')
+      query = {}
+      request_options = {
+        :body => MultiJson.dump(opts)
+      }
+      if timeout
+        query['t'] = timeout
+        # Ensure request does not timeout before Docker timeout
+        request_options.merge!(
+          read_timeout: timeout.to_i + 5,
+          write_timeout: timeout.to_i + 5
+        )
+      end
+      connection.post(path_for(method), query, request_options)
+      self
+    end
+
+    define_method(method) do |*args|
+      begin; public_send(:"#{method}!", *args); rescue ServerError; self end
+    end
+  end
+
+  # remove container
+  def remove(options = {})
+    connection.delete("/containers/#{self.id}", options)
+    nil
+  end
+  alias_method :delete, :remove
+
+  # pause and unpause containers
+  # #pause! and #unpause! both perform the associated action and
+  # return the Container. #pause and #unpause do the same,
+  # but rescue from ServerErrors.
+  [:pause, :unpause].each do |method|
+    define_method(:"#{method}!") do
+      connection.post path_for(method)
+      self
+    end
+
+    define_method(method) do
+      begin; public_send(:"#{method}!"); rescue ServerError; self; end
+    end
+  end
+
+  def archive_out(path, &block)
+    connection.get(
+      path_for(:archive),
+      { 'path' => path },
+      :response_block => block
+    )
+    self
+  end
+
+  def archive_in(inputs, output_path, opts = {})
+    file_hash = Docker::Util.file_hash_from_paths([*inputs])
+    tar = StringIO.new(Docker::Util.create_tar(file_hash))
+    archive_in_stream(output_path, opts) do
+      tar.read(Excon.defaults[:chunk_size]).to_s
+    end
+  end
+
+  def archive_in_stream(output_path, opts = {}, &block)
+    overwrite = opts[:overwrite] || opts['overwrite'] || false
+
+    connection.put(
+      path_for(:archive),
+      { 'path' => output_path, 'noOverwriteDirNonDir' => !overwrite },
+      :headers => {
+        'Content-Type' => 'application/x-tar'
+      },
+      &block
+    )
+    self
+  end
+
+  def read_file(path)
+    content = StringIO.new
+    archive_out(path) do |chunk|
+      content.write chunk
+    end
+
+    content.rewind
+
+    Gem::Package::TarReader.new(content) do |tar|
+      tar.each do |tarfile|
+        return tarfile.read
+      end
+    end
+  end
+
+  def store_file(path, file_content)
+    output_io = StringIO.new(
+      Docker::Util.create_tar(
+        path => file_content
+      )
+    )
+
+    archive_in_stream("/", overwrite: true) { output_io.read }
+  end
+
+  # Create a new Container.
+  def self.create(opts = {}, conn = Docker.connection)
+    query = opts.select {|key| ['name', :name].include?(key) }
+    clean_opts = opts.reject {|key| ['name', :name].include?(key) }
+    resp = conn.post('/containers/create', query, :body => MultiJson.dump(clean_opts))
+    hash = Docker::Util.parse_json(resp) || {}
+    new(conn, hash)
+  end
+
+  # Return the container with specified ID
+  def self.get(id, opts = {}, conn = Docker.connection)
+    container_json = conn.get("/containers/#{id}/json", opts)
+    hash = Docker::Util.parse_json(container_json) || {}
+    new(conn, hash)
+  end
+
+  # Return all of the Containers.
+  def self.all(opts = {}, conn = Docker.connection)
+    hashes = Docker::Util.parse_json(conn.get('/containers/json', opts)) || []
+    hashes.map { |hash| new(conn, hash) }
+  end
+
+  # Prune images
+  def self.prune(conn = Docker.connection)
+    conn.post("/containers/prune", {})
+    nil
+  end
+
+  # Convenience method to return the path for a particular resource.
+  def path_for(resource)
+    "/containers/#{self.id}/#{resource}"
+  end
+
+  private :path_for
+  private_class_method :new
+end