docker-api 2.0.0.pre.1

data/lib/docker/error.rb

@@ -0,0 +1,40 @@
+# 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 request returns a 400.
+  class ClientError < DockerError; end
+
+  # Raised when a request returns a 401.
+  class UnauthorizedError < DockerError; end
+
+  # Raised when a request returns a 404.
+  class NotFoundError < DockerError; end
+
+  # Raised when a request returns a 409.
+  class ConflictError < 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
+
+  # Raised when there is an incompatible version of Docker.
+  class VersionError < DockerError; end
+
+  # Raised when a request times out.
+  class TimeoutError < DockerError; end
+
+  # Raised when login fails.
+  class AuthenticationError < DockerError; end
+
+  # Raised when an IO action fails.
+  class IOError < DockerError; end
+end

data/lib/docker/event.rb

@@ -0,0 +1,126 @@
+# This class represents a Docker Event.
+class Docker::Event
+  include Docker::Error
+
+  # Represents the actor object nested within an event
+  class Actor
+    attr_accessor :ID, :Attributes
+
+    def initialize(actor_attributes = {})
+      [:ID, :Attributes].each do |sym|
+        value = actor_attributes[sym]
+        if value.nil?
+          value = actor_attributes[sym.to_s]
+        end
+        send("#{sym}=", value)
+      end
+
+      if self.Attributes.nil?
+        self.Attributes = {}
+      end
+    end
+
+    alias_method :id, :ID
+    alias_method :attributes, :Attributes
+  end
+
+  class << self
+    include Docker::Error
+
+    def stream(opts = {}, conn = Docker.connection, &block)
+      conn.get('/events', opts, :response_block => lambda { |b, r, t|
+        b.each_line do |line|
+          block.call(new_event(line, r, t))
+        end
+      })
+    end
+
+    def since(since, opts = {}, conn = Docker.connection, &block)
+      stream(opts.merge(:since => since), conn, &block)
+    end
+
+    def new_event(body, remaining, total)
+      return if body.nil? || body.empty?
+      json = Docker::Util.parse_json(body)
+      Docker::Event.new(json)
+    end
+  end
+
+  attr_accessor :Type, :Action, :time, :timeNano
+  attr_reader :Actor
+  # Deprecated interface
+  attr_accessor :status, :from
+
+  def initialize(event_attributes = {})
+    [:Type, :Action, :Actor, :time, :timeNano, :status, :from].each do |sym|
+      value = event_attributes[sym]
+      if value.nil?
+        value = event_attributes[sym.to_s]
+      end
+      send("#{sym}=", value)
+    end
+
+    if @Actor.nil?
+      value = event_attributes[:id]
+      if value.nil?
+        value = event_attributes['id']
+      end
+      self.Actor = Actor.new(ID: value)
+    end
+  end
+
+  def ID
+    self.actor.ID
+  end
+
+  def Actor=(actor)
+    return if actor.nil?
+    if actor.is_a? Actor
+      @Actor = actor
+    else
+      @Actor = Actor.new(actor)
+    end
+  end
+
+  alias_method :type, :Type
+  alias_method :action, :Action
+  alias_method :actor, :Actor
+  alias_method :time_nano, :timeNano
+  alias_method :id, :ID
+
+  def to_s
+    if type.nil? && action.nil?
+      to_s_legacy
+    else
+      to_s_actor_style
+    end
+  end
+
+  private
+
+  def to_s_legacy
+    attributes = []
+    attributes << "from=#{from}" unless from.nil?
+
+    unless attributes.empty?
+      attribute_string = "(#{attributes.join(', ')}) "
+    end
+
+    "Docker::Event { #{time} #{status} #{id} #{attribute_string}}"
+  end
+
+  def to_s_actor_style
+    most_accurate_time = time_nano || time
+
+    attributes = []
+    actor.attributes.each do |attribute, value|
+      attributes << "#{attribute}=#{value}"
+    end
+
+    unless attributes.empty?
+      attribute_string = "(#{attributes.join(', ')}) "
+    end
+
+    "Docker::Event { #{most_accurate_time} #{type} #{action} #{actor.id} #{attribute_string}}"
+  end
+end

data/lib/docker/exec.rb

@@ -0,0 +1,107 @@
+# This class represents a Docker Exec Instance.
+class Docker::Exec
+  include Docker::Base
+
+  # Convert details about the object into a string
+  #
+  # @return [String] String representation of the Exec instance object
+  def to_s
+    "Docker::Exec { :id => #{self.id}, :connection => #{self.connection} }"
+  end
+
+  # Create a new Exec instance in a running container. Please note, this does
+  # NOT execute the instance - you must run #start. Also, each instance is
+  # one-time use only.
+  #
+  # @param options [Hash] Parameters to pass in to the API.
+  # @param conn [Docker::Connection] Connection to Docker Remote API
+  #
+  # @return [Docker::Exec] self
+  def self.create(options = {}, conn = Docker.connection)
+    container = options.delete('Container')
+    resp = conn.post("/containers/#{container}/exec", {},
+      body: MultiJson.dump(options))
+    hash = Docker::Util.parse_json(resp) || {}
+    new(conn, hash)
+  end
+
+  # Get info about the Exec instance
+  #
+  def json
+    Docker::Util.parse_json(connection.get(path_for(:json), {}))
+  end
+
+  # Start the Exec instance. The Exec instance is deleted after this so this
+  # command can only be run once.
+  #
+  # @param options [Hash] Options to dictate behavior of the instance
+  # @option options [Object] :stdin (nil) The object to pass to STDIN.
+  # @option options [TrueClass, FalseClass] :detach (false) Whether to attach
+  #     to STDOUT/STDERR.
+  # @option options [TrueClass, FalseClass] :tty (false) Whether to attach using
+  #     a pseudo-TTY.
+  #
+  # @return [Array, Array, Int] The STDOUT, STDERR and exit code
+  def start!(options = {}, &block)
+
+    # Parse the Options
+    tty = !!options.delete(:tty)
+    detached = !!options.delete(:detach)
+    stdin = options[:stdin]
+    read_timeout = options[:wait]
+
+    # Create API Request Body
+    body = MultiJson.dump(
+      'Tty' => tty,
+      'Detach' => detached
+    )
+    excon_params = { body: body }
+
+    msgs = Docker::Messages.new
+    unless detached
+      if stdin
+        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
+    end
+
+    excon_params[:read_timeout] = read_timeout unless read_timeout.nil?
+
+    connection.post(path_for(:start), nil, excon_params)
+    [msgs.stdout_messages, msgs.stderr_messages, self.json['ExitCode']]
+  end
+
+  # #start! performs the associated action and returns the output.
+  # #start does the same, but rescues from ServerErrors.
+  [:start].each do |method|
+    define_method(method) do |*args|
+      begin; public_send(:"#{method}!", *args); rescue ServerError; self end
+    end
+  end
+
+  # Resize the TTY associated with the Exec instance
+  #
+  # @param query [Hash] API query parameters
+  # @option query [Fixnum] h Height of the TTY
+  # @option query [Fixnum] w Width of the TTY
+  #
+  # @return [Docker::Exec] self
+  def resize(query = {})
+    connection.post(path_for(:resize), query)
+    self
+  end
+
+  # Get the request URI for the given endpoint
+  #
+  # @param endpoint [Symbol] The endpoint to grab
+  # @return [String] The full Remote API endpoint with ID
+  def path_for(endpoint)
+    "/exec/#{self.id}/#{endpoint}"
+  end
+
+  private :path_for
+  private_class_method :new
+end

data/lib/docker/image.rb

@@ -0,0 +1,356 @@
+# This class represents a Docker Image.
+class Docker::Image
+  include Docker::Base
+
+  # 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. If the image has an embedded config, no command is
+  # necessary, but it will fail with 500 if no config is saved with the image
+  def run(cmd = nil, options = {})
+    opts = {'Image' => self.id}.merge(options)
+    opts["Cmd"] = cmd.is_a?(String) ? cmd.split(/\s+/) : cmd
+    begin
+      Docker::Container.create(opts, connection)
+                       .tap(&:start!)
+    rescue ServerError, ClientError => ex
+      if cmd
+        raise ex
+      else
+        raise ex, "No command specified."
+      end
+    end
+  end
+
+  # Push the Image to the Docker registry.
+  def push(creds = nil, options = {}, &block)
+    repo_tag = options.delete(:repo_tag) || ensure_repo_tags.first
+    raise ArgumentError, "Image is untagged" if repo_tag.nil?
+    repo, tag = Docker::Util.parse_repo_tag(repo_tag)
+    raise ArgumentError, "Image does not have a name to push." if repo.nil?
+
+    body = ""
+    credentials = creds || Docker.creds || {}
+    headers = Docker::Util.build_auth_header(credentials)
+    opts = {:tag => tag}.merge(options)
+    connection.post("/images/#{repo}/push", opts, :headers => headers,
+                    :response_block => self.class.response_block(body, &block))
+    self
+  end
+
+  # Tag the Image.
+  def tag(opts = {})
+    self.info['RepoTags'] ||= []
+    connection.post(path_for(:tag), opts)
+    repo = opts['repo'] || opts[:repo]
+    tag = opts['tag'] || opts[:tag] || 'latest'
+    self.info['RepoTags'] << "#{repo}:#{tag}"
+  end
+
+  # Given a path of a local file and the path it should be inserted, creates
+  # a new Image that has that file.
+  def insert_local(opts = {})
+    local_paths = opts.delete('localPath')
+    output_path = opts.delete('outputPath')
+
+    local_paths = [ local_paths ] unless local_paths.is_a?(Array)
+
+    file_hash = Docker::Util.file_hash_from_paths(local_paths)
+
+    file_hash['Dockerfile'] = dockerfile_for(file_hash, output_path)
+
+    tar = Docker::Util.create_tar(file_hash)
+    body = connection.post('/build', opts, :body => tar)
+    self.class.send(:new, connection, 'id' => Docker::Util.extract_id(body))
+  end
+
+  # Remove the Image from the server.
+  def remove(opts = {})
+    name = opts.delete(:name) || self.id
+    connection.delete("/images/#{name}", opts)
+  end
+  alias_method :delete, :remove
+
+  # Return a String representation of the Image.
+  def to_s
+    "Docker::Image { :id => #{self.id}, :info => #{self.info.inspect}, "\
+      ":connection => #{self.connection} }"
+  end
+
+  # #json returns extra information about an Image, #history returns its
+  # history.
+  [:json, :history].each do |method|
+    define_method(method) do |opts = {}|
+      Docker::Util.parse_json(connection.get(path_for(method), opts))
+    end
+  end
+
+  # Save the image as a tarball
+  def save(filename = nil)
+    self.class.save(self.id, filename, connection)
+  end
+
+  # Save the image as a tarball to an IO object.
+  def save_stream(opts = {}, &block)
+    self.class.save_stream(self.id, opts, connection, &block)
+  end
+
+  # Update the @info hash, which is the only mutable state in this object.
+  def refresh!
+    img = Docker::Image.all({:all => true}, connection).find { |image|
+      image.id.start_with?(self.id) || self.id.start_with?(image.id)
+    }
+    info.merge!(self.json)
+    img && info.merge!(img.info)
+    self
+  end
+
+  class << self
+
+    # Create a new Image.
+    def create(opts = {}, creds = nil, conn = Docker.connection, &block)
+      credentials = creds.nil? ? Docker.creds : MultiJson.dump(creds)
+      headers = credentials && Docker::Util.build_auth_header(credentials) || {}
+      body = ''
+      conn.post(
+        '/images/create',
+        opts,
+        :headers => headers,
+        :response_block => response_block(body, &block)
+        )
+      # NOTE: see associated tests for why we're looking at image#end_with?
+      image = opts['fromImage'] || opts[:fromImage]
+      tag = opts['tag'] || opts[:tag]
+      image = "#{image}:#{tag}" if tag && !image.end_with?(":#{tag}")
+      get(image, {}, conn)
+    end
+
+    # Return a specific image.
+    def get(id, opts = {}, conn = Docker.connection)
+      image_json = conn.get("/images/#{id}/json", opts)
+      hash = Docker::Util.parse_json(image_json) || {}
+      new(conn, hash)
+    end
+
+    # Delete a specific image
+    def remove(id, opts = {}, conn = Docker.connection)
+      conn.delete("/images/#{id}", opts)
+    end
+    alias_method :delete, :remove
+
+    # Prune images
+    def prune(conn = Docker.connection)
+      conn.post("/images/prune", {})
+    end
+
+
+    # Save the raw binary representation or one or more Docker images
+    #
+    # @param names [String, Array#String] The image(s) you wish to save
+    # @param filename [String] The file to export the data to.
+    # @param conn [Docker::Connection] The Docker connection to use
+    #
+    # @return [NilClass, String] If filename is nil, return the string
+    # representation of the binary data. If the filename is not nil, then
+    # return nil.
+    def save(names, filename = nil, conn = Docker.connection)
+      if filename
+        File.open(filename, 'wb') do |file|
+          save_stream(names, {}, conn, &response_block_for_save(file))
+        end
+        nil
+      else
+        string = ''
+        save_stream(names, {}, conn, &response_block_for_save(string))
+        string
+      end
+    end
+
+    # Stream the contents of Docker image(s) to a block.
+    #
+    # @param names [String, Array#String] The image(s) you wish to save
+    # @param conn [Docker::Connection] The Docker connection to use
+    # @yield chunk [String] a chunk of the Docker image(s).
+    def save_stream(names, opts = {}, conn = Docker.connection, &block)
+      # By using compare_by_identity we can create a Hash that has
+      # the same key multiple times.
+      query = {}.tap(&:compare_by_identity)
+      Array(names).each { |name| query['names'.dup] = name }
+      conn.get(
+        '/images/get',
+        query,
+        opts.merge(:response_block => block)
+      )
+      nil
+    end
+
+    # Load a tar Image
+    def load(tar, opts = {}, conn = Docker.connection, creds = nil, &block)
+       headers = build_headers(creds)
+       io = tar.is_a?(String) ? File.open(tar, 'rb') : tar
+       body = ""
+       conn.post(
+         '/images/load',
+         opts,
+         :headers => headers,
+         :response_block => response_block(body, &block)
+       ) { io.read(Excon.defaults[:chunk_size]).to_s }
+    end
+
+    # Check if an image exists.
+    def exist?(id, opts = {}, conn = Docker.connection)
+      get(id, opts, conn)
+      true
+    rescue Docker::Error::NotFoundError
+      false
+    end
+
+    # Return every Image.
+    def all(opts = {}, conn = Docker.connection)
+      hashes = Docker::Util.parse_json(conn.get('/images/json', opts)) || []
+      hashes.map { |hash| new(conn, hash) }
+    end
+
+    # Given a query like `{ :term => 'sshd' }`, queries the Docker Registry for
+    # a corresponding Image.
+    def search(query = {}, connection = Docker.connection, creds = nil)
+      credentials = creds.nil? ? Docker.creds : creds.to_json
+      headers = credentials && Docker::Util.build_auth_header(credentials) || {}
+      body = connection.get(
+        '/images/search',
+        query,
+        :headers => headers,
+      )
+      hashes = Docker::Util.parse_json(body) || []
+      hashes.map { |hash| new(connection, 'id' => hash['name']) }
+    end
+
+    # Import an Image from the output of Docker::Container#export. The first
+    # argument may either be a File or URI.
+    def import(imp, opts = {}, conn = Docker.connection)
+      open(imp) do |io|
+        import_stream(opts, conn) do
+          io.read(Excon.defaults[:chunk_size]).to_s
+        end
+      end
+    rescue StandardError
+      raise Docker::Error::IOError, "Could not import '#{imp}'"
+    end
+
+    def import_stream(options = {}, connection = Docker.connection, &block)
+      body = connection.post(
+        '/images/create',
+         options.merge('fromSrc' => '-'),
+         :headers => { 'Content-Type' => 'application/tar',
+                       'Transfer-Encoding' => 'chunked' },
+         &block
+      )
+      new(connection, 'id'=> Docker::Util.parse_json(body)['status'])
+    end
+
+    # Given a Dockerfile as a string, builds an Image.
+    def build(commands, opts = {}, connection = Docker.connection, &block)
+      body = ""
+      connection.post(
+        '/build', opts,
+        :body => Docker::Util.create_tar('Dockerfile' => commands),
+        :response_block => response_block(body, &block)
+      )
+      new(connection, 'id' => Docker::Util.extract_id(body))
+    rescue Docker::Error::ServerError
+      raise Docker::Error::UnexpectedResponseError
+    end
+
+    # Given File like object containing a tar file, builds an Image.
+    #
+    # If a block is passed, chunks of output produced by Docker will be passed
+    # to that block.
+    def build_from_tar(tar, opts = {}, connection = Docker.connection,
+                       creds = nil, &block)
+
+      headers = build_headers(creds)
+
+      # The response_block passed to Excon will build up this body variable.
+      body = ""
+      connection.post(
+        '/build', opts,
+        :headers => headers,
+        :response_block => response_block(body, &block)
+      ) { tar.read(Excon.defaults[:chunk_size]).to_s }
+
+      new(connection,
+          'id' => Docker::Util.extract_id(body),
+          :headers => headers)
+    end
+
+    # Given a directory that contains a Dockerfile, builds an Image.
+    #
+    # If a block is passed, chunks of output produced by Docker will be passed
+    # to that block.
+    def build_from_dir(dir, opts = {}, connection = Docker.connection,
+                       creds = nil, &block)
+
+      tar = Docker::Util.create_dir_tar(dir)
+      build_from_tar tar, opts, connection, creds, &block
+    ensure
+      unless tar.nil?
+        tar.close
+        FileUtils.rm(tar.path, force: true)
+      end
+    end
+  end
+
+  private
+
+  # A method to build the config header and merge it into the
+  # headers sent by build_from_dir.
+  def self.build_headers(creds=nil)
+    credentials = creds || Docker.creds || {}
+    config_header = Docker::Util.build_config_header(credentials)
+
+    headers = { 'Content-Type'      => 'application/tar',
+                'Transfer-Encoding' => 'chunked' }
+    headers = headers.merge(config_header) if config_header
+    headers
+  end
+
+  # Convenience method to return the path for a particular resource.
+  def path_for(resource)
+    "/images/#{self.id}/#{resource}"
+  end
+
+
+  # Convience method to get the Dockerfile for a file hash and a path to
+  # output to.
+  def dockerfile_for(file_hash, output_path)
+    dockerfile = "from #{self.id}\n"
+
+    file_hash.keys.each do |basename|
+      dockerfile << "add #{basename} #{output_path}\n"
+    end
+
+    dockerfile
+  end
+
+  def ensure_repo_tags
+    refresh! unless info.has_key?('RepoTags')
+    info['RepoTags']
+  end
+
+  # Generates the block to be passed as a reponse block to Excon. The returned
+  # lambda will append Docker output to the first argument, and yield output to
+  # the passed block, if a block is given.
+  def self.response_block(body)
+    lambda do |chunk, remaining, total|
+      body << chunk
+      yield chunk if block_given?
+    end
+  end
+
+  # Generates the block to be passed in to the save request. This lambda will
+  # append the streaming data to the file provided.
+  def self.response_block_for_save(file)
+    lambda do |chunk, remianing, total|
+      file << chunk
+    end
+  end
+end