capissh 0.0.1

data/LICENSE

@@ -0,0 +1,18 @@
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,37 @@
+# Capissh?
+
+An extraction of Capistrano's parallel SSH command execution, capiche?
+
+![Don Vito Corleone](http://i.imgur.com/hAcWI.jpg)
+
+
+## About
+
+Capissh executes commands (and soon transfers) on remote servers in parallel.
+
+Capissh will maintain open connections with servers it has seen when is is
+sensible to do so. When the batch size is not restricted, Capissh will maintain
+all connections, which greatly reduces connection overhead. Sets of commands
+are run in parallel on all servers within the batch.
+
+## Example
+
+The interface is intentionally simple. A Capissh::Configuration object will
+maintain the open sessions, which will be matched up with servers for each
+command invocation.
+
+    require 'capissh'
+
+    servers = ['user@host.com', 'user@example.com']
+    capissh = Capissh.new
+    capissh.run servers, 'date'
+    capissh.run servers, 'uname -a'
+    capissh.sudo servers, 'ls /root'
+
+## Thank You
+
+Huge thank you to Jamis Buck and all the other Capistrano contributors for
+creating and maintaining this gem. Without them, this library would not exist,
+and ruby deployment wouldn't be at the level it is today.
+
+Most of this code is directly extracted from capistrano without modification.

data/lib/capissh.rb

@@ -0,0 +1,43 @@
+# NOTES
+#
+# Parts
+#
+# * Server definition - Some object that can be executed on to connect to a server
+# * Server collection - A collection of servers on which to execute
+# * Command - What to run on the servers
+# * Command Tree - What to run in parallel
+#
+# SSH Related stuff
+# * Connection - A connection to a server definition that is held for reuse
+# * Connection pool - All the connections so persistent connections can be found
+# * Connection factory - Creates a persistent connection from a server definition
+#
+# Set of servers
+# Command
+# Run this command on this set of servers...
+# Using this connector (or the default ssh connector)
+#
+# State to be kept somewhere:
+#   servers with sessions
+# * set of sessions (if sessions are being persisted, with max hosts set, this could be a subset that gets blown away)
+# * set of servers, connected to sessions (this needs to be filterable by the user)
+#   these are both 1 to 1
+#   need to sort, constrain, etc
+# * Capissh init options
+#
+#
+# connector receives a server (set of servers?) and a command (command tree?)
+#   functionality: to interogate servers and figure out which command should
+#   run on each server and then hand out the command to the appropriate server.
+#   connector steps through servers (or command tree) and yields the command to each server
+# Yielding expects each server to run the command given (or maybe it just has the
+# chance to modify the command?)
+#
+
+require 'capissh/configuration'
+
+module Capissh
+  def self.new(*args)
+    Capissh::Configuration.new(*args)
+  end
+end

data/lib/capissh/command.rb

@@ -0,0 +1,197 @@
+require 'benchmark'
+require 'capissh/errors'
+require 'capissh/processable'
+require 'capissh/command/tree'
+
+module Capissh
+
+  # This class encapsulates a single command to be executed on a set of remote
+  # machines, in parallel.
+  class Command
+    include Processable
+
+    attr_reader :tree, :sessions, :options
+
+    class << self
+      attr_accessor :default_io_proc
+
+      def process_tree(tree, sessions, options={})
+        new(tree, sessions, options).process!
+      end
+      alias process process_tree
+
+      # Convenience method to process a command given as a string
+      # rather than a Command::Tree.
+      def process_string(string, sessions, options={}, &block)
+        tree = Tree.twig(nil, string, &block)
+        process_tree(tree, sessions, options)
+      end
+    end
+
+    self.default_io_proc = Proc.new do |ch, stream, out|
+      if ch[:logger]
+        level = stream == :err ? :important : :info
+        ch[:logger].send(level, out, "#{stream} :: #{ch[:server]}")
+      end
+    end
+
+    # Instantiates a new command object. The +command+ must be a string
+    # containing the command to execute. +sessions+ is an array of Net::SSH
+    # session instances, and +options+ must be a hash containing any of the
+    # following keys:
+    #
+    # * +shell+: (optional), the shell (eg. 'bash') or false. Default: 'sh'
+    # * +logger+: (optional), a Capissh::Logger instance
+    # * +data+: (optional), a string to be sent to the command via it's stdin
+    # * +eof+: (optional), close stdin after sending data
+    # * +env+: (optional), a string or hash to be interpreted as environment
+    #   variables that should be defined for this command invocation.
+    # * +pty+: (optional), execute the command in a pty
+    def initialize(tree, sessions, options={})
+      @tree = tree
+      @options = options
+      @sessions = sessions
+      @channels = open_channels
+    end
+
+    # Processes the command in parallel on all specified hosts. If the command
+    # fails (non-zero return code) on any of the hosts, this will raise a
+    # Capissh::CommandError.
+    def process!
+      elapsed = Benchmark.realtime do
+        loop do
+          break unless process_iteration { active? }
+        end
+      end
+
+      logger.trace "command finished in #{(elapsed * 1000).round}ms" if logger
+
+      failed = @channels.select { |ch| ch[:status] != 0 }
+      if failed.any?
+        commands = failed.inject({}) do |map, ch|
+          map[ch[:command]] ||= []
+          map[ch[:command]] << ch[:server]
+          map
+        end
+        message = commands.map { |command, list| "#{command.inspect} on #{list.join(',')}" }.join("; ")
+        error = CommandError.new("failed: #{message}")
+        error.hosts = commands.values.flatten
+        raise error
+      end
+
+      self
+    end
+
+    def active?
+      @channels.any? { |ch| !ch[:closed] }
+    end
+
+    # Force the command to stop processing, by closing all open channels
+    # associated with this command.
+    def stop!
+      @channels.each do |ch|
+        ch.close unless ch[:closed]
+      end
+    end
+
+    private
+
+      def logger
+        options[:logger]
+      end
+
+      def open_channels
+        sessions.map do |session|
+          server = session.xserver
+          @tree.base_command_and_callback(server).map do |base_command, io_proc|
+            session.open_channel do |channel|
+              channel[:server] = server
+              channel[:options] = options
+              channel[:logger] = logger
+              channel[:base_command] = base_command
+              channel[:io_proc] = io_proc
+
+              request_pty_if_necessary(channel) do |ch|
+                logger.trace "executing command", ch[:server] if logger
+
+                command_line = compose_command(channel[:base_command], channel[:server])
+                channel[:command] = command_line
+
+                ch.exec(command_line)
+                ch.send_data(options[:data]) if options[:data]
+                ch.eof! if options[:eof]
+              end
+
+              channel.on_data do |ch, data|
+                ch[:io_proc].call(ch, :out, data)
+              end
+
+              channel.on_extended_data do |ch, type, data|
+                ch[:io_proc].call(ch, :err, data)
+              end
+
+              channel.on_request("exit-status") do |ch, data|
+                ch[:status] = data.read_long
+              end
+
+              channel.on_close do |ch|
+                ch[:closed] = true
+              end
+            end
+          end
+        end.flatten
+      end
+
+      def request_pty_if_necessary(channel)
+        if options[:pty]
+          channel.request_pty do |ch, success|
+            if success
+              yield ch
+            else
+              # just log it, don't actually raise an exception, since the
+              # process method will see that the status is not zero and will
+              # raise an exception then.
+              logger.important "could not open channel", ch[:server] if logger
+              ch.close
+            end
+          end
+        else
+          yield channel
+        end
+      end
+
+      def compose_command(command, server)
+        command = command.strip.gsub(/\r?\n/, "\\\n")
+
+        if options[:shell] == false
+          shell = nil
+        else
+          shell = "#{options[:shell] || "sh"} -c"
+          command = command.gsub(/'/) { |m| "'\\''" }
+          command = "'#{command}'"
+        end
+
+        [environment, shell, command].compact.join(" ")
+      end
+
+      # prepare a space-separated sequence of variables assignments
+      # intended to be prepended to a command, so the shell sets
+      # the environment before running the command.
+      # i.e.: options[:env] = {'PATH' => '/opt/ruby/bin:$PATH',
+      #                        'TEST' => '( "quoted" )'}
+      # environment returns:
+      # "env TEST=(\ \"quoted\"\ ) PATH=/opt/ruby/bin:$PATH"
+      def environment
+        return if options[:env].nil? || options[:env].empty?
+        @environment ||=
+          if String === options[:env]
+            "env #{options[:env]}"
+          else
+            options[:env].inject("env") do |string, (name, value)|
+              value = value.to_s.gsub(/[ "]/) { |m| "\\#{m}" }
+              string << " #{name}=#{value}"
+            end
+          end
+      end
+  end
+end

data/lib/capissh/command/tree.rb

@@ -0,0 +1,138 @@
+module Capissh
+  class Command
+    class Tree
+      attr_reader :configuration
+      attr_reader :branches
+      attr_reader :fallback
+
+      include Enumerable
+
+      class Branch
+        attr_accessor :command, :callback
+        attr_reader :options
+
+        def initialize(command, options, callback)
+          @command = command.strip.gsub(/\r?\n/, "\\\n")
+          @callback = callback || Capissh::Command.default_io_proc
+          @options = options
+          @skip = false
+        end
+
+        def last?
+          options[:last]
+        end
+
+        def skip?
+          @skip
+        end
+
+        def skip!
+          @skip = true
+        end
+
+        def match(server)
+          true
+        end
+
+        def to_s
+          command.inspect
+        end
+      end
+
+      class ConditionBranch < Branch
+        attr_accessor :configuration
+        attr_accessor :condition
+
+        class Evaluator
+          attr_reader :configuration, :condition, :server
+
+          def initialize(config, condition, server)
+            @configuration = config
+            @condition = condition
+            @server = server
+          end
+
+          def in?(role)
+            configuration.roles[role].include?(server)
+          end
+
+          def result
+            eval(condition, binding)
+          end
+
+          def method_missing(sym, *args, &block)
+            if server.respond_to?(sym)
+              server.send(sym, *args, &block)
+            elsif configuration.respond_to?(sym)
+              configuration.send(sym, *args, &block)
+            else
+              super
+            end
+          end
+        end
+
+        def initialize(configuration, condition, command, options, callback)
+          @configuration = configuration
+          @condition = condition
+          super(command, options, callback)
+        end
+
+        def match(server)
+          Evaluator.new(configuration, condition, server).result
+        end
+
+        def to_s
+          "#{condition.inspect} :: #{command.inspect}"
+        end
+      end
+
+      # A tree with only one branch.
+      def self.twig(config, command, &block)
+        new(config) { |t| t.else(command, &block) }
+      end
+
+      def initialize(config)
+        @configuration = config
+        @branches = []
+        yield self if block_given?
+      end
+
+      def when(condition, command, options={}, &block)
+        branches << ConditionBranch.new(configuration, condition, command, options, block)
+      end
+
+      def else(command, &block)
+        @fallback = Branch.new(command, {}, block)
+      end
+
+      def branches_for(server)
+        seen_last = false
+        matches = branches.select do |branch|
+          success = !seen_last && !branch.skip? && branch.match(server)
+          seen_last = success && branch.last?
+          success
+        end
+
+        matches << fallback if matches.empty? && fallback
+
+        return matches
+      end
+
+      def base_command_and_callback(server)
+        branches_for(server).map do |branch|
+          command = branch.command
+          if configuration
+            command = configuration.placeholder_callback.call(command, server)
+          end
+          [command, branch.callback]
+        end
+      end
+
+      def each
+        branches.each { |branch| yield branch }
+        yield fallback if fallback
+        return self
+      end
+    end
+  end
+end

data/lib/capissh/configuration.rb

@@ -0,0 +1,65 @@
+require 'capissh/logger'
+require 'capissh/command'
+require 'capissh/connection_manager'
+require 'capissh/invocation'
+require 'capissh/file_transfers'
+require 'forwardable'
+
+module Capissh
+  # Represents a specific Capissh configuration.
+  class Configuration
+    extend Forwardable
+
+    class << self
+      attr_accessor :default_placeholder_callback
+    end
+
+    self.default_placeholder_callback = proc do |command, server|
+      command.gsub(/\$CAPISSH:HOST\$/, server.host)
+    end
+
+    attr_reader :logger, :options
+
+    def initialize(options={})
+      @options = options.dup
+      @logger = Capissh::Logger.new(@options)
+      @options[:default_environment] ||= {}
+      @options[:default_run_options] ||= {}
+      @options[:default_shell] ||= nil
+    end
+
+    def set(key, value)
+      @options[key.to_sym] = value
+    end
+
+    def fetch(key, *args, &block)
+      @options.fetch(key.to_sym, *args, &block)
+    end
+
+    def debug
+      fetch :debug, false
+    end
+
+    def dry_run
+      fetch :dry_run, false
+    end
+
+    def placeholder_callback
+      fetch :placeholder_callback, self.class.default_placeholder_callback
+    end
+
+    def connection_manager
+      @connection_manager ||= ConnectionManager.new(@options.merge(:logger => logger))
+    end
+
+    def file_transfers
+      @file_transfers ||= FileTransfers.new(self, connection_manager, :logger => logger)
+    end
+    def_delegators :file_transfers, :put, :get, :upload, :download, :transfer
+
+    def invocation
+      @invocation ||= Invocation.new(self, connection_manager, :logger => logger)
+    end
+    def_delegators :invocation, :parallel, :invoke_command, :run, :sudo, :sudo_command
+  end
+end