docker-compose 0.0.0

data/lib/docker/compose/mapper.rb

@@ -0,0 +1,159 @@
+# encoding: utf-8
+module Docker::Compose
+  # Uses a Session to discover information about services' IP addresses and
+  # ports as reachable from localhost, then maps URLs and other common network
+  # address formats so they point to the right host and port.
+  #
+  # **NOTE**: this class uses some heuristics to deal with cases where the
+  # Docker client is talking to a remote server because the `DOCKER_HOST`
+  # environment variable is set. In those cases, Mapper tries to determine
+  # the IP address of the exposed services as reachable from localhost;
+  # it generally makes a correct guess, but in certain super-complex networking
+  # scenarios it may guess wrong. Please open a GitHub issue if you find
+  # a situation where Mapper provides a wrong answer.
+  class Mapper
+    # Pattern that matches an "elided" host or port that should be omitted from
+    # output, but is needed to identify a specific container and port.
+    ELIDED          = /^\[.+\]$/.freeze
+
+    # Regexp that can be used with gsub to strip elision marks
+    REMOVE_ELIDED   = /[\[\]]/.freeze
+
+    BadSubstitution = Class.new(StandardError)
+    NoService       = Class.new(RuntimeError)
+
+    # Instantiate a mapper; map some environment variables; yield to caller for
+    # additional processing.
+    #
+    # @param [Hash] env a set of keys/values whose values will be mapped
+    # @param [Session] session
+    # @param [NetInfo] net_info
+    # @yield yields with each substituted (key, value) pair
+    def self.map(env, session:Session.new, net_info:NetInfo.new)
+      mapper = new(session, net_info)
+      env.each_pair do |k, v|
+        begin
+          v = mapper.map(v)
+          yield(k, v)
+        rescue NoService
+          yield(k, nil)
+        end
+      end
+    end
+
+    # Create an instance of Mapper
+    #
+    # @param [Docker::Compose::Session] session
+    # @param [NetInfo] net_info
+    def initialize(session=Session.new, net_info=NetInfo.new)
+      docker_host = ENV['DOCKER_HOST']
+      if docker_host.nil? || docker_host =~ /^(\/|unix|file)/
+        # If DOCKER_HOST is blank, or pointing to a local socket, then we
+        # can trust the address information returned by `docker-compose port`.
+        override_host = nil
+      else
+        # If DOCKER_HOST is present, assume that containers have bound to
+        # whatever IP we reach it at; don't fall victim to docker-compose's
+        # dirty lies!
+        override_host = net_info.docker_routable_ip
+      end
+
+      @session = session
+      @override_host = override_host
+    end
+
+    # Substitute service hostnames and ports that appear in a URL or a
+    # host:port string. If either component of a host:port string is
+    # surrounded by square brackets, "elide" that component, removing it
+    # from the result but using it to find the correct service and port.
+    #
+    # @example map MySQL on local docker host with 3306 published to 13847
+    #   map("tcp://db:3306") # => "tcp://127.0.0.1:13847"
+    #
+    # @example map just the hostname of MySQL on local docker host
+    #   map("db:[3306]") # => "127.0.0.1"
+    #
+    # @example map just the port of MySQL on local docker host
+    #   map("[db]:3306") # => "13847"
+    #
+    # @example map an array of database hosts
+    #   map(["[db1]:3306", "[db2]:3306"])
+    #
+    # @param [String,#map] value a URI, host:port pair, or an array of either
+    #
+    # @return [String,Array] the mapped value with container-names and ports substituted
+    #
+    # @raise [BadSubstitution] if a substitution string can't be parsed
+    # @raise [NoService] if service is not up or does not publish port
+    def map(value)
+      if value.respond_to?(:map)
+        value.map { |e| map_scalar(e) }
+      else
+        map_scalar(value)
+      end
+    end
+
+    # Figure out which host port a given service's port has been published to,
+    # and/or whether that service is running. Cannot distinguish between the
+    # "service not running" case and the "container port not published" case!
+    #
+    # @raise [NoService] if service is not up or does not publish port
+    # @return [Array] (String, Integer) pair of host address and port number
+    def host_and_port(service, port)
+      result = @session.port(service, port.to_s)
+      if result
+        result.chomp!
+      else
+        raise NoService,
+              "Service '#{service}' not running, or does not " \
+              "publish port '#{port}'"
+      end
+
+      host, port = result.split(':')
+      host = @override_host if @override_host
+
+      [host, Integer(port)]
+    end
+
+    # Map a single string, replacing service names with IPs and container ports
+    # with the host ports that they have been mapped to.
+    # @param [String] value
+    # @return [String]
+    def map_scalar(value)
+      uri = begin
+              URI.parse(value)
+            rescue
+              nil
+            end
+      pair = value.split(':')
+
+      if uri && uri.scheme && uri.host
+        # absolute URI with scheme, authority, etc
+        uri.host, uri.port = host_and_port(uri.host, uri.port)
+        return uri.to_s
+      elsif pair.size == 2
+        # "host:port" pair; three sub-cases...
+        if pair.first =~ ELIDED
+          # output only the port
+          service = pair.first.gsub(REMOVE_ELIDED, '')
+          _, port = host_and_port(service, pair.last)
+          return port.to_s
+        elsif pair.last =~ ELIDED
+          # output only the hostname; resolve the port anyway to ensure that
+          # the service is running.
+          service = pair.first
+          port = pair.last.gsub(REMOVE_ELIDED, '')
+          host, = host_and_port(service, port)
+          return host
+        else
+          # output port:hostname pair
+          host, port = host_and_port(pair.first, pair.last)
+          return "#{host}:#{port}"
+        end
+      else
+        fail BadSubstitution, "Can't understand '#{value}'"
+      end
+    end
+    private :map_scalar
+  end
+end

data/lib/docker/compose/net_info.rb

@@ -0,0 +1,89 @@
+# encoding: utf-8
+module Docker::Compose
+  # Utility that gathers information about the relationship between the host
+  # on which the Ruby VM is running and the docker host, then makes an
+  # guess about the mutually routable IP addresses of each.
+  #
+  # This information can be used to tell containers how to connect to ports on
+  # the local host, or conversely to tell the local host how to connect to ports
+  # published by containers running on the docker host.
+  #
+  # The heuristic works for most cases encountered in the wild, including:
+  #   - DOCKER_HOST is unset (assume daemon listening on 127.0.0.1)
+  #   - DOCKER_HOST points to a socket (assume 127.0.0.1)
+  #   - DOCKER_HOST points to a tcp, http or https address
+  class NetInfo
+    # Determine IP addresses of the local host's network interfaces.
+    #
+    # @return [Array] list of String dotted-quad IPv4 addresses
+    def self.ipv4_interfaces
+      Socket.getifaddrs
+        .map { |i| i.addr.ip_address if i.addr && i.addr.ipv4? }.compact
+    end
+
+    # Create a new instance of this class.
+    # @param [String] docker_host a URI pointing to the docker host
+    # @param [Array] list of String dotted-quad IPv4 addresses of local host
+    def initialize(docker_host = ENV['DOCKER_HOST'],
+                   my_ips = self.class.ipv4_interfaces)
+      docker_host ||= 'unix:/var/run/docker.sock'
+      @docker_url = URI.parse(docker_host)
+      @my_ips = my_ips
+    end
+
+    # Examine local host's network interfaces; figure out which one is most
+    # likely to share a route with the given IP address. If no IP address
+    # is specified, figure out which IP the Docker daemon is reachable on
+    # and use that as the target IP.
+    #
+    # @param [String] target_ip IPv4 address of target
+    #
+    # @return [String] IPv4 address of host machine that _may_ be reachable from
+    #   Docker machine
+    def host_routable_ip(target_ip = docker_routable_ip)
+      best_match  = ''
+      best_prefix = 0
+
+      target_cps = target_ip.codepoints
+
+      @my_ips.each do |my_ip|
+        ip_cps = my_ip.codepoints
+        prefix = 0
+        ip_cps.each_with_index do |cp, i|
+          break unless target_cps[i] == cp
+          prefix = i
+        end
+
+        if prefix > best_prefix
+          best_match = my_ip
+          best_prefix = prefix
+        end
+      end
+
+      best_match
+    end
+
+    # Figure out the likely IP address of the host pointed to by
+    # self.docker_url.
+    #
+    # @return [String] host-reachable IPv4 address of docker host
+    def docker_routable_ip
+      case @docker_url.scheme
+      when 'tcp', 'http', 'https'
+        docker_dns = @docker_url.host
+        docker_port = @docker_url.port || 2376
+      else
+        # Cheap trick: for unix, file or other protocols, assume docker ports
+        # are proxied to localhost in addition to other interfaces
+        docker_dns = 'localhost'
+        docker_port = 2376
+      end
+
+      addr = Addrinfo.getaddrinfo(
+        docker_dns, docker_port,
+        Socket::AF_INET, Socket::SOCK_STREAM).first
+
+      addr && addr.ip_address
+    end
+  end
+end

data/lib/docker/compose/rake_tasks.rb

@@ -0,0 +1,171 @@
+# 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
+    # is the directory in which Rakefile is located.
+    #
+    # @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.
+    #
+    # 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.
+    #
+    # @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.
+    #
+    # 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
+
+    # 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
+
+    # 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.
+    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'
+      yield self if block_given?
+
+      @shell = Backticks::Runner.new
+      @session = Docker::Compose::Session.new(@shell, dir: dir, project_name: project_name, 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
+
+          export_env(print: tlt)
+
+          @shell.interactive = true
+        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)
+          end
+
+          exec(args[:command])
+        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
+      end
+
+      extra_host_env.each do |k, v|
+        ENV[k] = serialize_for_env(v)
+        print_env(k, ENV[k]) 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)
+      if v
+        puts @shell_printer.export(k, v)
+      else
+        puts @shell_printer.unset(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(':')
+    end
+    private :task_name
+  end
+end