docker-compose 0.0.0 → 0.1.0

data/lib/docker/compose/rake_tasks.rb

@@ -1,14 +1,8 @@
-# encoding: utf-8
-require 'json'
 require 'rake/tasklib'
-require 'shellwords'
 
 # In case this file is required directly
 require 'docker/compose'
 
-# Only used here, so only required here
-require 'docker/compose/shell_printer'
-
 module Docker::Compose
   class RakeTasks < Rake::TaskLib
     # Set the directory in which docker-compose commands will be run. Default
@@ -17,155 +11,148 @@ module Docker::Compose
     # @return [String]
     attr_accessor :dir
 
-    # Set the project name. Default is not to pass a custom name.
-    # @return [String]
-    attr_accessor :project_name
-
     # Set the name of the docker-compose file. Default is`docker-compose.yml`.
     # @return [String]
     attr_accessor :file
 
-    # Provide a mapping of environment variables that should be set in
-    # _host_ processes, e.g. when running docker:compose:env or
-    # docker:compose:host.
-    #
+    # Provide a mapping of environment variables that should be set in the
+    # _host_ shell for docker:compose:env or docker:compose:server.
     # The values of the environment variables can refer to names of services
-    # and ports defined in the docker-compose file, and this gem will substitute
-    # the actual IP and port that the containers are reachable on. This allows
-    # commands invoked via "docker:compose:host" to reach services running
-    # inside containers.
+    # and ports defined in the docker-compose file, and this gem will query
+    # docker-compose to find out which host IP and port the services are
+    # reachable on. This allows components running on the host to connect to
+    # services running inside containers.
     #
     # @see Docker::Compose::Mapper for information about the substitution syntax
-    attr_accessor :host_env
-
-    # Extra environment variables to set before invoking host processes. These
-    # are set _in addition_ to server_env, but are not substituted in any way
-    # and must not contain any service information.
+    attr_accessor :env
+
+    # Extra environment variables that should be set before invoking the command
+    # specified for docker:compose:server. These are set _in addition_ to env
+    # (and should be disjoint from env), and do not necessarily need to map the
+    # location of a container; they can be simple extra env values that are
+    # useful to change the server's behavior when it runs in cooperation
+    # with containers.
     #
-    # Extra host env should be disjoint from host_env; if there is overlap
-    # between the two, then extra_host_env will "win."
-    attr_accessor :extra_host_env
+    # If there is overlap between env and server_env, then keys of server_env
+    # will "win"; they are set last.
+    attr_accessor :server_env
 
-    # Services to bring up with `docker-compose up` before running any hosted
-    # command. This is useful if your `docker-compose.yml` contains a service
-    # definition for the app you will be hosting; if you host the app, you
-    # want to specify all of the _other_ services, but not the app itself, since
-    # that will run on the host.
-    attr_accessor :host_services
-
-    # Namespace to define the rake tasks under. Defaults to "docker:compose'.
-    attr_accessor :rake_namespace
+    # Command to exec on the _host_ when someone invokes docker:compose:server.
+    # This is used to start up all containers and then run a server that
+    # depends on them and is properly linked to them.
+    attr_accessor :server
 
     # Construct Rake wrapper tasks for docker-compose. If a block is given,
     # yield self to the block before defining any tasks so their behavior
-    # can be configured by calling #server_env=, #file= and so forth.
+    # can be configured by calling #env=, #file= and so forth.
     def initialize
       self.dir = Rake.application.original_dir
-      self.project_name = nil
       self.file = 'docker-compose.yml'
-      self.host_env = {}
-      self.extra_host_env = {}
-      self.rake_namespace = 'docker:compose'
+      self.env = {}
+      self.server_env = {}
       yield self if block_given?
 
-      @shell = Backticks::Runner.new
-      @session = Docker::Compose::Session.new(@shell, dir: dir, project_name: project_name, file: file)
+      @shell = Docker::Compose::Shell.new
+      @session = Docker::Compose::Session.new(@shell, dir:dir, file:file)
       @net_info = Docker::Compose::NetInfo.new
-      @shell_printer = Docker::Compose::ShellPrinter.new
-
-      @shell.interactive = true
 
       define
     end
 
-    def define
-      namespace rake_namespace do
-        desc 'Print bash exports with IP/ports of running services'
-        task :env do
-          @shell.interactive = false # suppress useless 'port' output
-
-          tty = STDOUT.tty?
-          tlt = Rake.application.top_level_tasks.include?(task_name('env'))
-
-          # user invoked this task directly; print some helpful tips on
-          # how we intend it to be used.
-          print_usage if tty && tlt
+    private def define
+      namespace :docker do
+        namespace :compose do
+          desc 'Print bash exports with IP/ports of running services'
+          task :env do
+            @shell.interactive = false # suppress useless 'port' output
+
+            if Rake.application.top_level_tasks.include? 'docker:compose:env'
+              # This task is being run as top-level; print some bash export
+              # statements or usage information depending on whether STDOUT
+              # is a tty.
+              if STDOUT.tty?
+                print_usage
+              else
+                export_env(print:true)
+              end
+            else
+              # This task is a dependency of something else; just export the
+              # environment variables for use in-process by other Rake tasks.
+              export_env(print:false)
+            end
+          end
 
-          export_env(print: tlt)
+          desc 'Launch services needed to run this application'
+          task :up do
+            @shell.interactive = true # let user see what's happening
+            @session.up(detached:true)
+          end
 
-          @shell.interactive = true
-        end
+          desc 'Tail logs of all running services'
+          task :logs do
+            @session.logs
+          end
 
-        desc 'Run command on host, linked to services in containers'
-        task :host, [:command] => [task_name('env')] do |_task, args|
-          if host_services
-            @session.up(*host_services, detached: true)
-          else
-            @session.up(detached: true)
+          desc 'Stop services needed to run this application'
+          task :stop do
+            @session.stop
           end
 
-          exec(args[:command])
+          desc 'Run application on the host, linked to services in containers'
+          task :server => ['docker:compose:up', 'docker:compose:env'] do
+            exec(self.server)
+          end
         end
       end
     end
-    private :define
 
     # Substitute and set environment variables that point to network ports
     # published by docker-compose services. Optionally also print bash export
     # statements so this information can be made available to a user's shell.
-    def export_env(print:)
-      Docker::Compose::Mapper.map(host_env,
-                                  session: @session,
-                                  net_info: @net_info) do |k, v|
-        ENV[k] = serialize_for_env(v)
-        print_env(k, ENV[k]) if print
+    private def export_env(print:)
+      # First, do env substitutions in strict mode; don't catch BadSubstitution
+      # so the caller knows when he has a bogus value
+      mapper = Docker::Compose::Mapper.new(@session,
+                                           @net_info.docker_routable_ip)
+      self.env.each_pair do |k, v|
+        begin
+          v = mapper.map(v)
+          ENV[k] = v
+          print_env(k, v) if print
+        rescue Docker::Compose::Mapper::NoService
+          ENV[k] = nil
+          print_env(k, nil) if print
+        end
       end
 
-      extra_host_env.each do |k, v|
-        ENV[k] = serialize_for_env(v)
-        print_env(k, ENV[k]) if print
+      # Next, do server substitutions in non-strict mode since server_env
+      # can contain arbitrary values.
+      mapper = Docker::Compose::Mapper.new(@session,
+                                           @net_info.docker_routable_ip,
+                                           strict:false)
+      self.server_env.each_pair do |k, v|
+        v = mapper.map(v)
+        ENV[k] = v
+        print_env(k, v) if print
       end
     end
-    private :export_env
-
-    # Transform a Ruby value into a String that can be stored in the
-    # environment. This accepts nil, String, or Array and returns nil, String
-    # or JSON-serialized Array.
-    def serialize_for_env(v)
-      case v
-      when String
-        v
-      when NilClass
-        nil
-      when Array
-        JSON.dump(v)
-      else
-        fail ArgumentError, "Can't represent a #{v.class} in the environment"
-      end
-    end
-    private :serialize_for_env
 
-    # Print an export or unset statement suitable for user's shell
-    def print_env(k, v)
+    # Print a bash export or unset statement
+    private def print_env(k, v)
       if v
-        puts @shell_printer.export(k, v)
+        puts format('export %s=%s', k, v)
       else
-        puts @shell_printer.unset(k)
+        puts format('unset %s # service not running', k)
       end
     end
-    private :print_env
-
-    def print_usage
-      command = "rake #{task_name('env')}"
-      command = 'bundle exec ' + command if defined?(Bundler)
-      puts @shell_printer.comment('To export these variables to your shell, run:')
-      puts @shell_printer.comment(@shell_printer.eval_output(command))
-    end
-    private :print_usage
 
-    def task_name(task)
-      [rake_namespace, task].join(':')
+    private def print_usage
+      be = 'bundle exec ' if defined?(Bundler)
+      puts "# To export container network locations to your environment:"
+      puts %Q{eval "$(#{be}rake docker:compose:env)"}
+      puts
+      puts '# To learn which environment variables we will export:'
+      puts %Q{echo "$(#{be}rake docker:compose:env)"}
     end
-    private :task_name
   end
 end

data/lib/docker/compose/session.rb

@@ -1,6 +1,4 @@
-# encoding: utf-8
-require 'backticks'
-require 'yaml'
+require 'docker/compose/future/session'
 
 module Docker::Compose
   # A Ruby OOP interface to a docker-compose session. A session is bound to
@@ -15,220 +13,69 @@ module Docker::Compose
   # allowed by the docker-compose CLI, and that options are sometimes renamed
   # for clarity, e.g. the "-d" flag always becomes the "detached:" kwarg.
   class Session
-    # A Regex that matches all ANSI escape sequences.
-    ANSI = /\033\[([0-9];?)+[a-z]/
-
-    # Working directory (determines compose project name); default is Dir.pwd
-    attr_reader :dir
-
-    # Project name; default is not to pass a custom name
-    attr_reader :project_name
-
-    # Project file; default is 'docker-compose.yml'
-    attr_reader :file
-
-    # Reference to the last executed command.
-    attr_reader :last_command
-
-    def initialize(shell = Backticks::Runner.new(buffered: [:stderr], interactive: true),
-                   dir: Dir.pwd, project_name: nil, file: 'docker-compose.yml')
+    def initialize(shell=Docker::Compose::Shell.new,
+                   dir:Dir.pwd, file:'docker-compose.yml')
       @shell = shell
-      @project_name = project_name
       @dir = dir
       @file = file
-      @last_command = nil
-    end
-
-    # Validate docker-compose file and return it as Hash
-    # @return [Hash] the docker-compose config file
-    # @raise [Error] if command fails
-    def config(*args)
-      config = strip_ansi(run!('config', *args))
-      YAML.load(config)
     end
 
     # Monitor the logs of one or more containers.
     # @param [Array] services list of String service names to show logs for
     # @return [true] always returns true
-    # @raise [Error] if command fails
+    # @raise [RuntimeError] if command fails
     def logs(*services)
       run!('logs', services)
       true
     end
 
-    def ps(*services)
-      inter = @shell.interactive
-      @shell.interactive = false
-
-      lines = strip_ansi(run!('ps', {q: true}, services)).split(/[\r\n]+/)
-      containers = Collection.new
-
-      lines.each do |id|
-        containers << docker_ps(strip_ansi(id))
-      end
-
-      containers
-    ensure
-      @shell.interactive = inter
-    end
-
-    # Idempotently up the given services in the project.
+    # Idempotently run services in the project,
     # @param [Array] services list of String service names to run
     # @param [Boolean] detached if true, to start services in the background;
     #   otherwise, monitor logs in the foreground and shutdown on Ctrl+C
-    # @param [Integer] timeout how long to wait for each service to start
-    # @param [Boolean] build if true, build images before starting containers
-    # @param [Boolean] no_build if true, don't build images, even if they're
-    #   missing
+    # @param [Integer] timeout how long to wait for each service to stostart
+    # @param [Boolean] no_build if true, to skip building images for services
+    #   that have a `build:` instruction in the docker-compose file
     # @param [Boolean] no_deps if true, just run specified services without
     #   running the services that they depend on
     # @return [true] always returns true
-    # @raise [Error] if command fails
+    # @raise [RuntimeError] if command fails
     def up(*services,
-           abort_on_container_exit: false,
-           detached: false, timeout: 10, build: false,
-           exit_code_from: nil,
-           no_build: false, no_deps: false, no_start: false)
-      o = opts(
-               abort_on_container_exit: [abort_on_container_exit, false],
-               d: [detached, false],
-               timeout: [timeout, 10],
-               build: [build, false],
-               exit_code_from: [exit_code_from, nil],
-               no_build: [no_build, false],
-               no_deps: [no_deps, false],
-               no_start: [no_start, false]
-      )
-      run!('up', o, services)
+           detached:false, timeout:10, no_build:false, no_deps:false)
+      run!('up',
+           {d:detached, timeout:timeout, no_build:no_build, no_deps:no_deps},
+           services)
       true
     end
 
-    # Idempotently scales the number of containers for given services in the project.
-    # @param [Hash] container_count per service, e.g. {web: 2, worker: 3}
-    # @param [Integer] timeout how long to wait for each service to scale
-    def scale(container_count, timeout: 10)
-      args = container_count.map {|service, count| "#{service}=#{count}"}
-      o = opts(timeout: [timeout, 10])
-      run!('scale', o, *args)
-    end
-
-    # Take the stack down
-    def down(remove_volumes: false)
-      run!('down', opts(v: [!!remove_volumes, false]))
-    end
-
-    # Pull images of services
-    # @param [Array] services list of String service names to pull
-    def pull(*services)
-      run!('pull', *services)
-    end
-
-    def rm(*services, force: false, volumes: false)
-      o = opts(f: [force, false], v: [volumes, false])
-      run!('rm', o, services)
-    end
-
-    # Idempotently run an arbitrary command with a service container.
-    # @param [String] service name to run
-    # @param [String] cmd command statement to run
-    # @param [Boolean] detached if true, to start services in the background;
-    #   otherwise, monitor logs in the foreground and shutdown on Ctrl+C
-    # @param [Boolean] no_deps if true, just run specified services without
-    #   running the services that they depend on
-    # @param [Array] env a list of environment variables (see: -e flag)
-    # @param [Array] volumes a list of volumes to bind mount (see: -v flag)
-    # @param [Boolean] rm remove the container when done
-    # @param [Boolean] no_tty disable pseudo-tty allocation (see: -T flag)
-    # @param [String] user run as specified username or uid (see: -u flag)
-    # @raise [Error] if command fails
-    def run(service, *cmd, detached: false, no_deps: false, volumes: [], env: [], rm: false, no_tty: false, user: nil, service_ports: false)
-      o = opts(d: [detached, false], no_deps: [no_deps, false], rm: [rm, false], T: [no_tty, false], u: [user, nil], service_ports: [service_ports, false])
-      env_params = env.map { |v| { e: v } }
-      volume_params = volumes.map { |v| { v: v } }
-      run!('run', o, *env_params, *volume_params, service, cmd)
-    end
-
-    def restart(*services, timeout:10)
-      o = opts(timeout: [timeout, 10])
-      run!('restart', o, *services)
-    end
-
-    # Pause running services.
-    # @param [Array] services list of String service names to run
-    def pause(*services)
-      run!('pause', *services)
-    end
-
-    # Unpause running services.
-    # @param [Array] services list of String service names to run
-    def unpause(*services)
-      run!('unpause', *services)
-    end
-
     # Stop running services.
     # @param [Array] services list of String service names to stop
     # @param [Integer] timeout how long to wait for each service to stop
-    # @raise [Error] if command fails
-    def stop(*services, timeout: 10)
-      o = opts(timeout: [timeout, 10])
-      run!('stop', o, services)
-    end
-
-    # Forcibly stop running services.
-    # @param [Array] services list of String service names to stop
-    # @param [String] name of murderous signal to use, default is 'KILL'
-    # @see Signal.list for a list of acceptable signal names
-    def kill(*services, signal: 'KILL')
-      o = opts(signal: [signal, 'KILL'])
-      run!('kill', o, services)
+    def stop(*services, timeout:10)
+      run!('stop', {timeout:timeout}, services)
     end
 
-    # Figure out which interface(s) and port a given service port has been published to.
-    #
-    # **NOTE**: if Docker Compose is communicating with a remote Docker host, this method
-    # returns IP addresses from the point of view of *that* host and its interfaces. If
-    # you need to know the address as reachable from localhost, you probably want to use
-    # `Mapper`.
-    #
-    # @see Docker::Compose::Mapper
-    #
+    # Figure out which host a port a given service port has been published to.
     # @param [String] service name of service from docker-compose.yml
     # @param [Integer] port number of port
     # @param [String] protocol 'tcp' or 'udp'
     # @param [Integer] index of container (if multiple instances running)
-    # @return [String,nil] an ip:port pair such as "0.0.0.0:32176" or nil if the service is not running
-    # @raise [Error] if command fails
-    def port(service, port, protocol: 'tcp', index: 1)
-      inter = @shell.interactive
-      @shell.interactive = false
-
-      o = opts(protocol: [protocol, 'tcp'], index: [index, 1])
-      s = strip_ansi(run!('port', o, service, port).strip)
-      (!s.empty? && s) || nil
-    rescue Error => e
-      # Deal with docker-compose v1.11+
-      if e.detail =~ /No container found/i
-        nil
-      else
-        raise
-      end
-    ensure
-      @shell.interactive = inter
+    def port(service, port, protocol:'tcp', index:1)
+      run!('port', {protocol:protocol, index:index}, service, port)
     end
 
     # Determine the installed version of docker-compose.
     # @param [Boolean] short whether to return terse version information
     # @return [String, Hash] if short==true, returns a version string;
-    #   otherwise, returns a Hash of component-name strings to version strings
-    # @raise [Error] if command fails
-    def version(short: false)
-      o = opts(short: [short, false])
-      result = run!('version', o, file: false, dir: false)
+    #   otherwise, returns a Hash of component names to version strings
+    # @raise [RuntimeError] if command fails
+    def version(short:false)
+      result = run!('version', short:short, file:false, dir:false)
 
       if short
         result.strip
       else
-        lines = result.split(/[\r\n]+/)
+        lines = result.split("\n")
         lines.inject({}) do |h, line|
           kv = line.split(/: +/, 2)
           h[kv.first] = kv.last
@@ -237,118 +84,30 @@ module Docker::Compose
       end
     end
 
-    def build(*services, force_rm: false, no_cache: false, pull: false)
-      o = opts(force_rm: [force_rm, false],
-               no_cache: [no_cache, false],
-               pull: [pull, false])
-      result = run!('build', o, services)
-    end
-
     # Run a docker-compose command without validating that the CLI parameters
     # make sense. Prepend project and file options if suitable.
     #
     # @see Docker::Compose::Shell#command
     #
-    # @param [Array] args command-line arguments in the format accepted by
-    #   Backticks::Runner#command
+    # @param [Array] cmd subcommand words and options in the format accepted by
+    #   Shell#command
     # @return [String] output of the command
-    # @raise [Error] if command fails
-    def run!(*args)
-      project_name_args = if @project_name
-        [{ project_name: @project_name }]
-      else
-        []
-      end
-      file_args = case @file
-      when 'docker-compose.yml'
-        []
-      when Array
-        # backticks sugar can't handle array values; build a list of hashes
-        # IMPORTANT: preserve the order of the files so overrides work correctly
-        file_args = @file.map { |filepath| { :file => filepath } }
-      else
-        # a single String (or Pathname, etc); use normal sugar to add it
-        [{ file: @file.to_s }]
+    # @raise [RuntimeError] if command fails
+    def run!(*cmd)
+      project_opts = {
+        file: @file
+      }
+
+      Dir.chdir(@dir) do
+        result, output =
+          @shell.command('docker-compose', project_opts, *cmd)
+        (result == 0) || raise(RuntimeError,
+                               "#{cmd.first} failed with status #{result}")
+        output
       end
-
-      @shell.chdir = dir
-      @last_command = @shell.run('docker-compose', *project_name_args, *file_args, *args).join
-      status = @last_command.status
-      out = @last_command.captured_output
-      err = @last_command.captured_error
-      status.success? || fail(Error.new(args.first, status, out+err))
-      out
-    end
-
-    private
-
-    def docker_ps(id)
-      cmd = @shell.run('docker', 'ps', a: true, f: "id=#{id}", no_trunc: true, format: Container::PS_FMT).join
-      status, out, err = cmd.status, cmd.captured_output, cmd.captured_error
-      raise Error.new('docker ps', status, out+err) unless status.success?
-      lines = out.split(/[\r\n]+/)
-      return nil if lines.empty?
-      l = strip_ansi(lines.shift)
-      m = parse(l)
-      raise Error.new('docker ps', status, "Cannot parse output: '#{l}'") unless m
-      raise Error.new('docker ps', status, "Cannot parse output: '#{l}'") unless m.size == 7
-      return Container.new(*m)
-    end
-
-    # strip default-valued options. the value of each kw should be a pair:
-    #  [0] is present value
-    #  [1] is default value
-    def opts(**kws)
-      res = {}
-      kws.each_pair do |kw, v|
-        res[kw] = v[0] unless v[0] == v[1]
-      end
-      res
-    end
-
-    # strip all ANSI escape sequences from str
-    def strip_ansi(str)
-      str.gsub(ANSI, '')
     end
 
-    # Parse a string that consists of a sequence of values enclosed within parentheses.
-    # Ignore any bytes that are outside of parentheses. Values may include nested parentheses.
-    #
-    # @param [String] str e.g. "(foo) ((bar)) ... (baz)"
-    # @return [Array] e.g. ["foo", "bar", "baz"]
-    def parse(str)
-      fields = []
-      nest = 0
-      field = ''
-      str.each_char do |ch|
-        got = false
-        if nest == 0
-          if ch == '('
-            nest += 1
-          end
-        else
-          if ch == '('
-            nest += 1
-            field << ch
-          elsif ch == ')'
-            nest -= 1
-            if nest == 0
-              got = true
-            else
-              field << ch
-            end
-          else
-            field << ch
-          end
-        end
-
-        if got
-          fields << field
-          field = ''
-        end
-      end
-
-      fields
-    end
+    # Simulate behaviors from Docker 1.5
+    include Docker::Compose::Future::Session
   end
 end