docker 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8a5fe14311f0acab32460ca8923bab196447407f
-  data.tar.gz: 0b41e3f8300a3378bd4523d1b9f1a030229c6555
+  metadata.gz: 41a18cd99670f903bc99f7277cb27afdf00025c0
+  data.tar.gz: 6d4313cd3012dd54a76eff1b5e6cd67f93ccc829
 SHA512:
-  metadata.gz: c1f63091d8bf8a553084f77e009ce5669660407856cc6ce051549d908d94f26cc95f94c4afdced54670e759042d74971ee00e7dddcb417886976f9ed4efd6800
-  data.tar.gz: c7f76f824a1b2e6e548e94f483edbe6097b478c8960cbb1494f4c1340f9b4849eca9bebad08341bf9864e3e0175764888cb443d6e9b738206cbebb0cc33829dd
+  metadata.gz: c3bfbdb9b4f2846910d5e3315b71fef671ead204a15e28871a01a1617c7bdabf3811e0444bb32466f2947b9948ad4de4d82f7bba8deea390ad95cdbb460011f9
+  data.tar.gz: caa31e851fa10c4d2b6b913087d1350861266fe0aacbb5b705ba2826ebc2f5e3f3c487bae8e0a9701186657888494ba554231c842d9d88225aebc23386b25a2a

data/README.md

@@ -29,7 +29,7 @@ Or install it yourself as:
 
 ## Usage
 
-### Invoking from Ruby code
+Instantiate a `Docker::Session` and call its methods to invoke Docker commands. 
 
 ```ruby
 require 'docker'
@@ -40,7 +40,7 @@ docker = Docker.new
 
 docker.version
 
-docker.run(t:true, i:true, 'busybox', '/bin/sh')
+docker.run('busybox', '/bin/sh', interactive:true, tty:true)
 ```
 
 ## Development

data/docker.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["xeger@xeger.net"]
 
   spec.summary       = %q{Docker CLI wrapper.}
-  spec.description   = %q{Provides an OOP interface to docker without relying on its HTTP API.}
+  spec.description   = %q{Provides an OOP interface to docker's command-line interface without relying on its HTTP API.}
   spec.homepage      = "https://github.com/xeger/docker"
   spec.license       = "MIT"
 

data/lib/docker.rb

@@ -1,5 +1,7 @@
 require_relative 'docker/version'
 require_relative 'docker/error'
+require_relative 'docker/asset'
+require_relative 'docker/container'
 require_relative 'docker/session'
 
 module Docker

data/lib/docker/asset.rb

@@ -0,0 +1,27 @@
+module Docker
+  # Base class for containers, images and other Docker assets.
+  class Asset
+    def initialize(json, session:nil)
+      json = JSON.load(json) if json.is_a?(String)
+      @json = json
+      @session = session
+    end
+
+    def inspect
+      %Q{#<#{self.class.name}:#{self.name}>}
+    end
+
+    # @return [String] human-readable name of container, image or volume
+    def name
+      @json['Name']
+    end
+
+    def to_h
+      @json
+    end
+
+    def to_s
+      self.inspect
+    end
+  end
+end

data/lib/docker/container.rb

@@ -0,0 +1,54 @@
+module Docker
+  # Object that represents a Docker container, its information and operations.
+  class Container < Asset
+    # @return [String] unique SHA256 container hash
+    def id
+      @json['Id']
+    end
+
+    # @return [String] human-readable name of container ()minus initial /)
+    def name
+      super.sub(/^\//, '')
+    end
+
+    # @return [String] SHA256 hash of image the container is derived from
+    def image
+      @json['Image']
+    end
+
+    # @return [String] running, exited, etc
+    def status
+      @json['State']['Status']
+    end
+
+    # @return [Integer] master process PID
+    def pid
+      @json['State']['Pid']
+    end
+
+    # @return [Integer] master process exit code
+    def exit_code
+      @json['State']['ExitCode']
+    end
+
+    def kill
+      raise Error, "Disconnected from session" unless @session
+      @session.kill(id)
+    end
+
+    def rm
+      raise Error, "Disconnected from session" unless @session
+      @session.rm(id)
+    end
+
+    def start
+      raise Error, "Disconnected from session" unless @session
+      @session.start(id)
+    end
+
+    def stop
+      raise Error, "Disconnected from session" unless @session
+      @session.stop(id)
+    end
+  end
+end

data/lib/docker/session.rb

@@ -1,4 +1,5 @@
 require 'backticks'
+require 'json'
 
 module Docker
   # A Ruby OOP interface to a docker session. A session is bound to
@@ -19,19 +20,51 @@ module Docker
     # @return [#command]
     attr_reader :shell
 
-    def initialize(shell=Backticks::Runner.new(interactive:true), host:ENV['DOCKER_HOST'])
+    # Hint that we are able to parse ps output
+    PS_HEADER = /ID\s+IMAGE\s+COMMAND\s+CREATED\s+STATUS\s+PORTS\s+NAMES$/
+
+    def initialize(shell=Backticks::Runner.new, host:ENV['DOCKER_HOST'])
       @host = host
       @shell = shell
     end
 
+    # Get detailed information about a container(s).
+    #
+    # @return [Container,Array] one container if one was asked about; a list of containers otherwise
+    # @param [Array,String] container ID/name or list of IDs/names
+    def inspect(container_s)
+      containers = container_s
+      containers = [containers] unless container_s.is_a?(Array)
+      out = run!('inspect', containers)
+      result = JSON.parse(out).map { |c| Container.new(c, session:self)}
+      if container_s.is_a?(Array)
+        result
+      else
+        result.first
+      end
+    end
+
     # Kill a running container.
     #
-    # @param [String] container id or name of container to kill
+    # @param [String] container id or name of container
     # @param [String] signal Unix signal to send: KILL, TERM, QUIT, HUP, etc
     def kill(container, signal:nil)
       run!('kill', {signal:signal}, container)
     end
 
+    # List containers. This actually does a `ps` followed by a very large
+    # `inspect`, so it's expensive but super detailed.
+    #
+    # @param
+    # @return [Array] list of Docker::Container objects
+    def ps(all:false, before:nil, latest:false, since:nil)
+      out = run!('ps', all:all,before:before,latest:latest,since:since)
+      lines = out.split(/[\n\r]+/)
+      header = lines.shift
+      ids = lines.map { |line| line.split(/\s+/).first }
+      inspect(ids)
+    end
+
     # Run a command in a new container.
     #
     # @example open a busybox shell
@@ -104,6 +137,32 @@ module Docker
       run!('run', *cmd).strip
     end
 
+    # Remove a container.
+    #
+    # @param [String] container id or name of container
+    # @param [Boolean] force remove the container even if it's in use
+    # @param [Boolean] volumes remove associated data volumes
+    def rm(container, force:false, volumes:false)
+      run!('rm', {force:force,volumes:volumes},container).strip
+    end
+
+    # Stop a running container.
+    #
+    # @param [String] container id or name of container
+    # @param [Integer] time seconds to wait for stop before killing it
+    def stop(container, time:nil)
+      run!('stop', {time:time}, container).strip
+    end
+
+    # Start a stopped container.
+    #
+    # @param [String] container id or name of container
+    # @param [Boolean] attach attach STDOUT/STDERR and forward signals
+    # @param [Boolean] interactive attach container's STDIN
+    def start(container, attach:false, interactive:false)
+      run!('start', {attach:attach,interactive:interactive}, container).strip
+    end
+
     # Provide version information about the Docker client and server.
     #
     # @return [Hash] dictionary of strings describing version/build info
@@ -138,6 +197,7 @@ module Docker
     # @return [String] output of the command
     # @raise [RuntimeError] if command fails
     def run!(*args)
+      # STDERR.puts "+ " + (['docker'] + args).inspect
       cmd = @shell.run('docker', *args).join
       status, out, err = cmd.status, cmd.captured_output, cmd.captured_error
       status.success? || raise(Error.new(args.first, status, err))

data/lib/docker/version.rb

@@ -1,3 +1,3 @@
 module Docker
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: docker
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Tony Spataro
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-01-03 00:00:00.000000000 Z
+date: 2016-01-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: backticks
@@ -66,7 +66,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Provides an OOP interface to docker without relying on its HTTP API.
+description: Provides an OOP interface to docker's command-line interface without
+  relying on its HTTP API.
 email:
 - xeger@xeger.net
 executables: []
@@ -86,6 +87,8 @@ files:
 - bin/setup
 - docker.gemspec
 - lib/docker.rb
+- lib/docker/asset.rb
+- lib/docker/container.rb
 - lib/docker/error.rb
 - lib/docker/session.rb
 - lib/docker/version.rb