minestrone 0.0.1

data/lib/minestrone/command.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require 'benchmark'
+require 'minestrone/errors'
+require 'minestrone/processable'
+
+module Minestrone
+
+  #
+  # This class encapsulates a single command to be executed on a remote machine.
+  #
+
+  class Command
+    include Processable
+
+    attr_reader :command, :session, :options, :callback, :channel
+
+    def self.process(command, session, options = {}, &block)
+      new(command, session, options, &block).process!
+    end
+
+    # Instantiates a new command object. The +command+ must be a string
+    # containing the command to execute. +session+ is a Net::SSH session
+    # instance, and +options+ must be a hash containing any of the following keys:
+    #
+    # * +logger+: (optional), a Minestrone::Logger instance
+    # * +data+: (optional), a string to be sent to the command via it's stdin
+    # * +env+: (optional), a string or hash to be interpreted as environment
+    #   variables that should be defined for this command invocation.
+
+    def initialize(command, session, options = {}, &block)
+      @command = command.strip.gsub(/\r?\n/, "\\\n")
+      @session = session
+      @options = options
+      @callback = block || Minestrone::Configuration.default_io_proc
+    end
+
+    # Processes the command. If the command fails (non-zero return code), this
+    # will raise a Minestrone::CommandError.
+
+    def process!
+      elapsed = Benchmark.realtime do
+        open_channel(session)
+
+        loop do
+          break unless process_iteration { !channel[:closed] }
+        end
+      end
+
+      logger.trace "command finished in #{(elapsed * 1000).round}ms" if logger
+
+      if channel[:status] != 0
+        message = "#{channel[:command].inspect} on #{channel[:server]}"
+        error = CommandError.new("failed: #{message}")
+        error.host = channel[:server]
+        raise error
+      end
+
+      self
+    end
+
+    # Force the command to stop processing, by closing the open channel
+    # associated with this command.
+
+    def stop!
+      channel.close if channel && !channel[:closed]
+    end
+
+
+    private
+
+    def logger
+      options[:logger]
+    end
+
+    def open_channel(session)
+      server = session.xserver
+      opened = nil
+
+      returned = session.open_channel do |channel|
+        opened = channel
+        channel[:server] = server
+        channel[:host] = server.host
+        channel[:options] = options
+        channel[:callback] = callback
+
+        request_pty_if_necessary(channel) do |ch, success|
+          if success
+            logger.trace "executing command", ch[:server] if logger
+            cmd = replace_placeholders(command, ch)
+
+            if options[:shell] == false
+              shell = nil
+            else
+              shell = "#{options[:shell] || "sh"} -c"
+              cmd = cmd.gsub(/'/) { |m| "'\\''" }
+              cmd = "'#{cmd}'"
+            end
+
+            command_line = [environment, shell, cmd].compact.join(" ")
+            ch[:command] = command_line
+
+            ch.exec(command_line)
+            ch.send_data(options[:data]) if options[:data]
+            ch.eof! if options[:eof]
+          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
+
+        channel.on_data do |ch, data|
+          ch[:callback][ch, :out, data]
+        end
+
+        channel.on_extended_data do |ch, type, data|
+          ch[:callback][ch, :err, data]
+        end
+
+        channel.on_request("exit-status") do |ch, data|
+          ch[:status] = data.read_long
+        end
+
+        channel.on_request("exit-signal") do |ch, data|
+          if logger
+            exit_signal = data.read_string
+            logger.important "command received signal #{exit_signal}", ch[:server]
+          end
+        end
+
+        channel.on_close do |ch|
+          ch[:closed] = true
+        end
+      end
+
+      @channel = returned || opened
+    end
+
+    def request_pty_if_necessary(channel)
+      if options[:pty]
+        channel.request_pty do |ch, success|
+          yield ch, success
+        end
+      else
+        yield channel, true
+      end
+    end
+
+    def replace_placeholders(command, channel)
+      command.gsub(/\$CAPISTRANO:HOST\$/, channel[:host])
+    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".dup) do |string, (name, value)|
+          value = value.to_s.gsub(/[ "]/) { |m| "\\#{m}" }
+          string << " #{name}=#{value}"
+        end
+      end
+    end
+  end
+end

data/lib/minestrone/configuration/actions/file_transfer.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'minestrone/transfer'
+
+module Minestrone
+  class Configuration
+    module Actions
+      module FileTransfer
+
+        # Store the given data at the given location on the configured server.
+        # If <tt>:mode</tt> is specified it is used to set the mode on the file.
+
+        def put(data, path, options = {})
+          opts = options.dup
+          upload(StringIO.new(data), path, opts)
+        end
+
+        # Get file remote_path from the configured server and transfer it to
+        # local machine as path.
+        #
+        # get "#{deploy_to}/current/log/production.log", "log/production.log.web"
+
+        def get(remote_path, path, options = {}, &block)
+          download(remote_path, path, options, &block)
+        end
+
+        def upload(from, to, options = {}, &block)
+          mode = options.delete(:mode)
+          transfer(:up, from, to, options, &block)
+
+          if mode
+            mode = mode.is_a?(Numeric) ? mode.to_s(8) : mode.to_s
+            run "chmod #{mode} #{to}", options
+          end
+        end
+
+        def download(from, to, options = {}, &block)
+          transfer(:down, from, to, options, &block)
+        end
+
+        def transfer(direction, from, to, options = {}, &block)
+          if dry_run
+            return logger.debug "transfering: #{[direction, from, to] * ', '}"
+          end
+
+          execute_on_server do
+            Transfer.process(direction, from, to, session, options.merge(:logger => logger), &block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/minestrone/configuration/actions/inspect.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'minestrone/errors'
+
+module Minestrone
+  class Configuration
+    module Actions
+      module Inspect
+
+        # Streams the result of the command from the configured server.
+        # The command is invoked via #invoke_command.
+        #
+        # Usage:
+        #
+        #   desc "Run a tail on multiple log files at the same time"
+        #   task :tail_fcgi do
+        #     stream "tail -f #{shared_path}/log/fastcgi.crash.log"
+        #   end
+
+        def stream(command, options = {})
+          invoke_command(command, options.merge(:eof => !command.include?(sudo))) do |ch, stream, out|
+            puts out if stream == :out
+            warn "[err :: #{ch[:server]}] #{out}" if stream == :err
+          end
+        end
+
+        # Executes the given command on the first server targetted by the
+        # current task, collects it's stdout into a string, and returns the
+        # string. The command is invoked via #invoke_command.
+
+        def capture(command, options = {})
+          output = "".dup
+
+          invoke_command(command, options.merge(:once => true, :eof => !command.include?(sudo))) do |ch, stream, data|
+            case stream
+            when :out then output << data
+            when :err then warn "[err :: #{ch[:server]}] #{data}"
+            end
+          end
+
+          output
+        end
+      end
+    end
+  end
+end

data/lib/minestrone/configuration/actions/invocation.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require 'minestrone/command'
+
+module Minestrone
+  class Configuration
+    module Actions
+      module Invocation
+        def self.included(base) #:nodoc:
+          base.extend(ClassMethods)
+
+          base.default_io_proc = Proc.new do |ch, stream, out|
+            level = (stream == :err) ? :important : :info
+            ch[:options][:logger].send(level, out, "#{stream} :: #{ch[:server]}")
+          end
+        end
+
+        module ClassMethods
+          attr_accessor :default_io_proc
+        end
+
+        def initialize_invocation #:nodoc:
+          set :default_environment, {}
+          set :default_run_options, {}
+        end
+
+        # Invokes the given command. If a +via+ key is given, it will be used
+        # to determine what method to use to invoke the command. It defaults
+        # to :run, but may be :sudo, or any other method that conforms to the
+        # same interface as run and sudo.
+
+        def invoke_command(cmd, options = {}, &block)
+          options = options.dup
+          via = options.delete(:via) || :run
+          send(via, cmd, options, &block)
+        end
+
+        # Execute the given command on the configured server. If a block is
+        # given, it is invoked for all output
+        # generated by the command, and should accept three parameters: the SSH
+        # channel (which may be used to send data back to the remote process),
+        # the stream identifier (<tt>:err</tt> for stderr, and <tt>:out</tt> for
+        # stdout), and the data that was received.
+        #
+        # The +options+ hash may include any of the following keys:
+        #
+        # * :shell - says which shell should be used to invoke commands. This
+        #   defaults to "sh". Setting this to false causes Minestrone to invoke
+        #   the commands directly, without wrapping them in a shell invocation.
+        # * :data - if not nil (the default), this should be a string that will
+        #   be passed to the command's stdin stream.
+        # * :pty - if true, a pseudo-tty will be allocated for each command. The
+        #   default is false. Note that there are benefits and drawbacks both ways.
+        #   Empirically, it appears that if a pty is allocated, the SSH server daemon
+        #   will _not_ read user shell start-up scripts (e.g. bashrc, etc.). However,
+        #   if a pty is _not_ allocated, some commands will refuse to run in
+        #   interactive mode and will not prompt for (e.g.) passwords.
+        # * :env - a hash of environment variable mappings that should be made
+        #   available to the command. The keys should be environment variable names,
+        #   and the values should be their corresponding values. The default is
+        #   empty, but may be modified by changing the +default_environment+
+        #   Minestrone variable.
+        # * :eof - if true, the standard input stream will be closed after sending
+        #   any data specified in the :data option. If false, the input stream is
+        #   left open. The default is to close the input stream only if no block is
+        #   passed.
+        #
+        # Note that if you set these keys in the +default_run_options+ Minestrone
+        # variable, they will apply for all invocations of #run and
+        # #invoke_command.
+
+        def run(cmd, options = {}, &block)
+          if options[:eof].nil? && !cmd.include?(sudo)
+            options = options.merge(:eof => !block_given?)
+          end
+
+          block ||= self.class.default_io_proc
+          options = add_default_command_options(options)
+
+          if cmd.nil? || cmd.empty?
+            raise ArgumentError, "attempt to execute without specifying a command"
+          end
+
+          logger.debug "executing #{cmd.inspect}" unless options[:silent]
+
+          return if dry_run || (debug && continue_execution(cmd) == false)
+
+          block = sudo_behavior_callback(block) if cmd.include?(sudo)
+
+          execute_on_server do
+            Command.process(cmd, session, options.merge(:logger => logger, :configuration => self), &block)
+          end
+        end
+
+        # Returns the command string used by minestrone to invoke a comamnd via
+        # sudo.
+        #
+        #   run "#{sudo :as => 'bob'} mkdir /path/to/dir"
+        #
+        # It can also be invoked like #run, but executing the command via sudo.
+        # If sudo requires a password, set the <tt>:password</tt> variable or
+        # pass <tt>-p</tt> to prompt for it before running.
+        #
+        #   sudo "mkdir /path/to/dir"
+        #
+        # Also, this method understands a <tt>:sudo</tt> configuration variable,
+        # which (if specified) will be used as the full path to the sudo
+        # executable on the remote machine:
+        #
+        #   set :sudo, "/opt/local/bin/sudo"
+        #
+        # If you know what you're doing, you can also set <tt>:sudo_prompt</tt>,
+        # which tells minestrone which prompt sudo should use when asking for
+        # a password. (This is so that minestrone knows what prompt to look for
+        # in the output.) If you set :sudo_prompt to an empty string, Minestrone
+        # will not send a preferred prompt.
+
+        def sudo(*parameters, &block)
+          options = parameters.last.is_a?(Hash) ? parameters.pop.dup : {}
+          command = parameters.first
+          user = options[:as] && "-u #{options.delete(:as)}"
+
+          sudo_prompt_option = "-p '#{sudo_prompt}'" unless sudo_prompt.empty?
+          sudo_command = [fetch(:sudo, "sudo"), sudo_prompt_option, user].compact.join(" ")
+
+          if command
+            command = sudo_command + " " + command
+            run(command, options, &block)
+          else
+            return sudo_command
+          end
+        end
+
+        # Returns a Proc object that defines the behavior of the sudo
+        # callback. The returned Proc will defer to the +fallback+ argument
+        # (which should also be a Proc) for any output it does not
+        # explicitly handle.
+
+        def sudo_behavior_callback(fallback) #:nodoc:
+          # in order to prevent _each host_ from prompting when the password
+          # was wrong, let's track which host prompted first and only allow
+          # subsequent prompts from that host.
+          prompt_host = nil
+
+          Proc.new do |ch, stream, out|
+            if out.to_s =~ /^Sorry, try again/
+              if prompt_host.nil? || prompt_host == ch[:server]
+                prompt_host = ch[:server]
+                logger.important out, "#{stream} :: #{ch[:server]}"
+                reset! :password
+              end
+            end
+
+            if out.to_s =~ /^#{Regexp.escape(sudo_prompt)}/
+              ch.send_data "#{self[:password]}\n"
+            elsif fallback
+              fallback.call(ch, stream, out)
+            end
+          end
+        end
+
+        # Merges the various default command options into the options hash and
+        # returns the result. The default command options that are understand
+        # are:
+        #
+        # * :default_environment: If the :env key already exists, the :env
+        #   key is merged into default_environment and then added back into
+        #   options.
+        # * :default_shell: if the :shell key already exists, it will be used.
+        #   Otherwise, if the :default_shell key exists in the configuration,
+        #   it will be used. Otherwise, no :shell key is added.
+
+        def add_default_command_options(options)
+          defaults = self[:default_run_options]
+          options = defaults.merge(options)
+
+          env = self[:default_environment]
+          env = env.merge(options[:env]) if options[:env]
+          options[:env] = env unless env.empty?
+
+          shell = options[:shell] || self[:default_shell]
+          options[:shell] = shell unless shell.nil?
+
+          options
+        end
+
+        # Returns the prompt text to use with sudo
+        def sudo_prompt
+          fetch(:sudo_prompt, "sudo password: ")
+        end
+
+        def continue_execution(command)
+          case Minestrone::CLI.debug_prompt(command.inspect)
+          when "y" then true
+          when "n" then false
+          when "a" then exit(-1)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/minestrone/configuration/alias_task.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Minestrone
+  class Configuration
+    module AliasTask
+
+      # Attempts to find the task at the given fully-qualified path, and
+      # alias it. If arguments don't have correct task names, an ArgumentError
+      # will be raised. If no such task exists, a Minestrone::NoSuchTaskError
+      # will be raised.
+      #
+      # Usage:
+      #
+      #   alias_task :original_deploy, :deploy
+
+      def alias_task(new_name, old_name)
+        if !new_name.respond_to?(:to_sym) || !old_name.respond_to?(:to_sym)
+          raise ArgumentError, "expected a valid task name"
+        end
+
+        original_task = find_task(old_name) or raise NoSuchTaskError, "the task `#{old_name}' does not exist"
+        task = original_task.dup # Duplicate task to avoid modify original task
+        task.name = new_name
+
+        define_task(task)
+      end
+    end
+  end
+end

data/lib/minestrone/configuration/callbacks.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require 'minestrone/callback'
+
+module Minestrone
+  class Configuration
+    module Callbacks
+      def self.included(base) #:nodoc:
+        base.send :alias_method, :invoke_task_directly_without_callbacks, :invoke_task_directly
+        base.send :alias_method, :invoke_task_directly, :invoke_task_directly_with_callbacks
+      end
+
+      # The hash of callbacks that have been registered for this configuration
+      attr_reader :callbacks
+
+      def initialize_callbacks #:nodoc:
+        @callbacks = {}
+      end
+
+      def invoke_task_directly_with_callbacks(task) #:nodoc:
+        trigger :before, task
+        result = invoke_task_directly_without_callbacks(task)
+        trigger :after, task
+
+        return result
+      end
+
+      # Defines a callback to be invoked before the given task. You must
+      # specify the fully-qualified task name, both for the primary task, and
+      # for the task(s) to be executed before. Alternatively, you can pass a
+      # block to be executed before the given task.
+      #
+      #   before "deploy:update_code", :record_difference
+      #   before :deploy, "custom:log_deploy"
+      #   before :deploy, :this, "then:this", "and:then:this"
+      #   before :some_task do
+      #     puts "an anonymous hook!"
+      #   end
+      #
+      # This just provides a convenient interface to the more general #on method.
+
+      def before(task_name, *args, &block)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        args << options.merge(:only => task_name)
+
+        on :before, *args, &block
+      end
+
+      # Defines a callback to be invoked after the given task. You must
+      # specify the fully-qualified task name, both for the primary task, and
+      # for the task(s) to be executed after. Alternatively, you can pass a
+      # block to be executed after the given task.
+      #
+      #   after "deploy:update_code", :log_difference
+      #   after :deploy, "custom:announce"
+      #   after :deploy, :this, "then:this", "and:then:this"
+      #   after :some_task do
+      #     puts "an anonymous hook!"
+      #   end
+      #
+      # This just provides a convenient interface to the more general #on method.
+
+      def after(task_name, *args, &block)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        args << options.merge(:only => task_name)
+
+        on :after, *args, &block
+      end
+
+      # Defines one or more callbacks to be invoked in response to some event.
+      # Minestrone currently understands the following events:
+      #
+      # * :before, triggered before a task is invoked
+      # * :after, triggered after a task is invoked
+      # * :start, triggered before a top-level task is invoked via the command-line
+      # * :finish, triggered when a top-level task completes
+      # * :load, triggered after all recipes have loaded
+      # * :exit, triggered after all tasks have completed
+      #
+      # Specify the (fully-qualified) task names that you want invoked in
+      # response to the event. Alternatively, you can specify a block to invoke
+      # when the event is triggered. You can also pass a hash of options as the
+      # last parameter, which may include either of two keys:
+      #
+      # * :only, should specify an array of task names. Restricts this callback
+      #   so that it will only fire when the event applies to those tasks.
+      # * :except, should specify an array of task names. Restricts this callback
+      #   so that it will never fire when the event applies to those tasks.
+      #
+      # Usage:
+      #
+      #  on :before, "some:hook", "another:hook", :only => "deploy:update"
+      #  on :after, "some:hook", :except => "deploy:create_symlink"
+      #  on :before, "global:hook"
+      #  on :after, :only => :deploy do
+      #    puts "after deploy here"
+      #  end
+
+      def on(event, *args, &block)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        callbacks[event] ||= []
+
+        if args.empty? && block.nil?
+          raise ArgumentError, "please specify either a task name or a block to invoke"
+        elsif args.any? && block
+          raise ArgumentError, "please specify only a task name or a block, but not both"
+        elsif block
+          callbacks[event] << ProcCallback.new(block, options)
+        else
+          callbacks[event].concat(args.map { |name| TaskCallback.new(self, name, options) })
+        end
+      end
+
+      # Trigger the named event for the named task. All associated callbacks
+      # will be fired, in the order they were defined.
+
+      def trigger(event, task = nil)
+        pending = Array(callbacks[event]).select { |c| c.applies_to?(task) }
+
+        if pending.any?
+          msg = "triggering #{event} callbacks"
+          msg << " for `#{task.fully_qualified_name}'" if task
+          logger.trace(msg)
+          pending.each { |callback| callback.call }
+        end
+      end
+    end
+  end
+end