shells 0.1.23 → 0.2.0

data/lib/shells/shell_base/regex_escape.rb

@@ -0,0 +1,23 @@
+module Shells
+  class ShellBase
+    private
+
+    def regex_escape(text)
+      text
+          .gsub('\\', '\\\\')
+          .gsub('[', '\\[')
+          .gsub(']', '\\]')
+          .gsub('(', '\\(')
+          .gsub(')', '\\)')
+          .gsub('.', '\\.')
+          .gsub('*', '\\*')
+          .gsub('+', '\\+')
+          .gsub('?', '\\?')
+          .gsub('{', '\\{')
+          .gsub('}', '\\}')
+          .gsub('$', '\\$')
+          .gsub('^', '\\^')
+    end
+
+  end
+end

data/lib/shells/shell_base/run.rb

@@ -0,0 +1,188 @@
+module Shells
+  class ShellBase
+
+    attr_accessor :run_flag
+    private :run_flag, :run_flag=
+
+    add_hook :on_init do |sh|
+      sh.instance_eval do
+        self.run_flag = false
+      end
+    end
+
+    ##
+    # Is the shell currently running?
+    def running?
+      run_flag
+    end
+
+    # the thread used to run the session.
+    attr_accessor :session_thread
+    private :session_thread, :session_thread=
+
+    # track exceptions raised during session execution.
+    attr_accessor :session_exception
+    private :session_exception, :session_exception=
+
+    ##
+    # Set to true to ignore IO errors.
+    attr_accessor :ignore_io_error
+    protected :ignore_io_error, :ignore_io_error=
+
+    add_hook :on_before_run do |sh|
+      sh.instance_eval do
+        self.session_exception = nil
+        self.ignore_io_error = false
+      end
+    end
+
+    add_hook :on_after_run do |sh|
+      sh.instance_eval do
+        if session_thread&.status
+          session_thread.exit
+        end
+        self.session_thread = nil
+        self.ignore_io_error = false
+      end
+    end
+
+    ##
+    # Runs a shell session.
+    #
+    # The block provided will be run asynchronously with the shell.
+    #
+    # Returns the shell instance.
+    def run(&block)
+      sync do
+        raise Shells::AlreadyRunning if running?
+        self.run_flag = true
+      end
+
+      begin
+        run_hook :on_before_run
+
+        debug 'Connecting...'
+        connect
+
+        debug 'Starting output buffering...'
+        buffer_output
+
+        debug 'Starting session thread...'
+        self.session_thread = Thread.start(self) do |sh|
+          begin
+            begin
+              debug 'Executing setup...'
+              sh.instance_eval { setup }
+              debug 'Executing block...'
+              block.call sh
+            ensure
+              debug 'Executing teardown...'
+              sh.instance_eval { teardown }
+            end
+          rescue Shells::QuitNow
+            # just exit the session.
+          rescue =>e
+            # if the exception is handled by the hook no further processing is required, otherwise we store the exception
+            # to propagate it in the main thread.
+            unless sh.run_hook(:on_exception, e) == :break
+              sh.sync { sh.instance_eval { self.session_exception = e } }
+            end
+          end
+        end
+
+        # process the input buffer while the thread is alive and the shell is active.
+        debug 'Entering IO loop...'
+        io_loop do
+          if active?
+            begin
+              if session_thread.status    # not dead
+                # process input from the session.
+                unless wait_for_output
+                  inp = next_input
+                  if inp
+                    send_data inp
+                    self.wait_for_output = (options[:unbuffered_input] == :echo)
+                  end
+                end
+
+                # continue running the IO loop
+                true
+              elsif session_exception
+                # propagate the exception.
+                raise session_exception.class, session_exception.message, session_exception.backtrace
+              else
+                # the thread has exited, but no exception exists.
+                # regardless, the IO loop should now exit.
+                false
+              end
+            rescue IOError
+              if ignore_io_error
+                # we were (sort of) expecting the IO error, so just tell the IO loop to exit.
+                false
+              else
+                raise
+              end
+            end
+          else
+            # the shell session is no longer active, tell the IO loop to exit.
+            false
+          end
+        end
+      rescue
+        # when an error occurs, try to disconnect, but ignore any further errors.
+        begin
+          debug 'Disconnecting...'
+          disconnect
+        rescue
+          # ignore
+        end
+        raise
+      else
+        # when no error occurs, try to disconnect and propagate any errors (unless we are ignoring IO errors).
+        begin
+          debug 'Disconnecting...'
+          disconnect
+        rescue IOError
+          raise unless ignore_io_error
+        end
+      ensure
+        # cleanup
+        run_hook :on_after_run
+        self.run_flag = false
+      end
+
+      self
+    end
+
+    protected
+
+    ##
+    # Adds code to be run when an exception occurs.
+    #
+    # This code will receive the shell as the first argument and the exception as the second.
+    # If it handles the exception it should return :break.
+    #
+    #   on_exception do |shell, ex|
+    #     if ex.is_a?(MyExceptionType)
+    #       ...
+    #       :break
+    #     else
+    #       false
+    #     end
+    #   end
+    #
+    # You can also pass the name of a static method.
+    #
+    #   def self.some_exception_handler(shell, ex)
+    #     ...
+    #   end
+    #
+    #   on_exception :some_exception_handler
+    #
+    def self.on_exception(proc = nil, &block)
+      add_hook :on_exception, proc, &block
+    end
+
+
+  end
+end

data/lib/shells/shell_base/sync.rb

@@ -0,0 +1,24 @@
+module Shells
+  class ShellBase
+
+    attr_accessor :thread_lock
+    private :thread_lock, :thread_lock=
+
+    add_hook :on_init do |sh|
+      puts 'Initializing...'
+      sh.instance_eval do
+        self.thread_lock = Mutex.new
+      end
+    end
+
+    protected
+
+    ##
+    # Synchronizes actions between shell threads.
+    def sync(&block)
+      thread_lock.synchronize &block
+    end
+
+
+  end
+end

data/lib/shells/ssh_bash_shell.rb

@@ -0,0 +1,71 @@
+require 'shells/ssh_shell'
+require 'shells/bash_common'
+
+module Shells
+  ##
+  # Executes a Bash session with an SSH host.
+  #
+  # The default setup of this class should work well with any bash-like shell.
+  #
+  # Valid options:
+  # +host+::
+  #     The name or IP address of the host to connect to.  Defaults to 'localhost'.
+  # +port+::
+  #     The port on the host to connect to.  Defaults to 22.
+  # +user+::
+  #     The user to login with.  This option is required.
+  # +password+::
+  #     The password to login with.
+  #     If our public key is an authorized key on the host, the password is ignored for connection.
+  #     The #sudo_exec method for bash-like shells will also use this password for elevation.
+  # +prompt+::
+  #     The prompt used to determine when processes finish execution.
+  #     Defaults to '~~#', but if that doesn't work for some reason because it is valid output from one or more
+  #     commands, you can change it to something else.  It must be unique and cannot contain certain characters.
+  #     The characters you should avoid are !, $, \, /, ", and ' because no attempt is made to escape them and the
+  #     resulting prompt can very easily become something else entirely.  If they are provided, they will be
+  #     replaced to protect the shell from getting stuck.
+  # +quit+::
+  #     If set, this defines the command to execute when quitting the session.
+  #     The default is "exit" which will probably work most of the time.
+  # +retrieve_exit_code+::
+  #     If set to a non-false value, then the default behavior will be to retrieve the exit code from the shell after
+  #     executing a command.  If set to a false or nil value, the default behavior will be to ignore the exit code
+  #     from the shell.  When retrieved, the exit code is stored in the +last_exit_code+ property.
+  #     This option can be overridden by providing an alternate value to the +exec+ method on a case-by-case basis.
+  # +on_non_zero_exit_code+::
+  #     If set to :ignore (the default) then non-zero exit codes will not cause errors.  You will still be able to check
+  #     the +last_exit_code+ property to determine if the command was successful.
+  #     If set to :raise then non-zero exit codes will cause a Shells::NonZeroExitCode to be raised when a command exits
+  #     with a non-zero return value.
+  #     This option only comes into play when +retrieve_exit_code+ is set to a non-false value.
+  #     This option can be overridden by providing an alternate value to the +exec+ method on a case-by-case basis.
+  # +silence_timeout+::
+  #     When a command is executing, this is the maximum amount of time to wait for any feedback from the shell.
+  #     If set to 0 (or less) there is no timeout.
+  #     Unlike +command_timeout+ this value resets every time we receive feedback.
+  #     This option can be overridden by providing an alternate value to the +exec+ method on a case-by-case basis.
+  # +command_timeout+::
+  #     When a command is executing, this is the maximum amount of time to wait for the command to finish.
+  #     If set to 0 (or less) there is no timeout.
+  #     Unlike +silence_timeout+ this value does not reset when we receive feedback.
+  #     This option can be overridden by providing an alternate value to the +exec+ method on a case-by-case basis.
+  # +connect_timeout+::
+  #     This is the maximum amount of time to wait for the initial connection to the SSH shell.
+  #
+  #   Shells::SshBashShell.new(
+  #       host: '10.10.10.10',
+  #       user: 'somebody',
+  #       password: 'super-secret'
+  #   ) do |shell|
+  #     shell.exec('cd /usr/local/bin')
+  #     user_bin_files = shell.exec('ls -A1').split("\n")
+  #     @app_is_installed = user_bin_files.include?('my_app')
+  #   end
+  #
+  class SshBashShell < SshShell
+
+    include BashCommon
+
+  end
+end

data/lib/shells/{pf_sense_ssh_session.rb → ssh_pf_sense_shell.rb}

@@ -1,4 +1,4 @@
-require 'shells/ssh_session'
+require 'shells/ssh_bash_shell'
 require 'shells/pf_sense_common'
 
 module Shells
@@ -29,25 +29,27 @@ module Shells
   # +connect_timeout+::
   #     This is the maximum amount of time to wait for the initial connection to the SSH shell.
   #
-  #   Shells::PfSenseSshSession.new(
+  #   Shells::SshPfSenseShell.new(
   #       host: '10.10.10.10',
   #       user: 'somebody',
   #       password: 'super-secret'
   #   ) do |shell|
-  #     cfg = shell.get_config_section("aliases")
-  #     cfg["alias"] ||= []
-  #     cfg["alias"] << {
-  #         :name => "MY_NETWORK",
-  #         :type => "network",
-  #         :address => "192.168.1.0/24",
-  #         :descr => "My home network",
-  #         :details => "Created #{Time.now.to_s}"
-  #     }
-  #     shell.set_config_section("aliases", cfg, "Add home network")
-  #     shell.apply_filter_config
+  #     shell.pf_shell do |shell|
+  #       cfg = shell.get_config_section("aliases")
+  #       cfg["alias"] ||= []
+  #       cfg["alias"] << {
+  #           :name => "MY_NETWORK",
+  #           :type => "network",
+  #           :address => "192.168.1.0/24",
+  #           :descr => "My home network",
+  #           :details => "Created #{Time.now.to_s}"
+  #       }
+  #       shell.set_config_section("aliases", cfg, "Add home network")
+  #       shell.apply_filter_config
+  #     end
   #   end
   #
-  class PfSenseSshSession < SshSession
+  class SshPfSenseShell < SshBashShell
 
     include PfSenseCommon
 

data/lib/shells/ssh_shell.rb

@@ -0,0 +1,215 @@
+require 'net/ssh'
+require 'shells/shell_base'
+
+module Shells
+  ##
+  # Executes an SSH session with a host.
+  #
+  # Valid options:
+  # +host+::
+  #     The name or IP address of the host to connect to.  Defaults to 'localhost'.
+  # +port+::
+  #     The port on the host to connect to.  Defaults to 22.
+  # +user+::
+  #     The user to login with.  This option is required.
+  # +password+::
+  #     The password to login with.
+  #     If our public key is an authorized key on the host, the password is ignored for connection.
+  #     The #sudo_exec method for bash-like shells will also use this password for elevation.
+  # +prompt+::
+  #     The prompt used to determine when processes finish execution.
+  # +shell+::
+  #     If set to :shell, then the default shell is executed.  This is the default value.
+  #     If set to :none, then no shell is executed, but a PTY is still created.
+  #     If set to :no_pty, then no shell is executed and no PTY is created.
+  #     If set to anything else, it is assumed to be the executable path to the shell you want to run.
+  # +quit+::
+  #     If set, this defines the command to execute when quitting the session.
+  #     The default is "exit" which will probably work most of the time.
+  # +retrieve_exit_code+::
+  #     If set to a non-false value, then the default behavior will be to retrieve the exit code from the shell after
+  #     executing a command.  If set to a false or nil value, the default behavior will be to ignore the exit code
+  #     from the shell.  When retrieved, the exit code is stored in the +last_exit_code+ property.
+  #     This option can be overridden by providing an alternate value to the +exec+ method on a case-by-case basis.
+  # +on_non_zero_exit_code+::
+  #     If set to :ignore (the default) then non-zero exit codes will not cause errors.  You will still be able to check
+  #     the +last_exit_code+ property to determine if the command was successful.
+  #     If set to :raise then non-zero exit codes will cause a Shells::NonZeroExitCode to be raised when a command exits
+  #     with a non-zero return value.
+  #     This option only comes into play when +retrieve_exit_code+ is set to a non-false value.
+  #     This option can be overridden by providing an alternate value to the +exec+ method on a case-by-case basis.
+  # +silence_timeout+::
+  #     When a command is executing, this is the maximum amount of time to wait for any feedback from the shell.
+  #     If set to 0 (or less) there is no timeout.
+  #     Unlike +command_timeout+ this value resets every time we receive feedback.
+  #     This option can be overridden by providing an alternate value to the +exec+ method on a case-by-case basis.
+  # +command_timeout+::
+  #     When a command is executing, this is the maximum amount of time to wait for the command to finish.
+  #     If set to 0 (or less) there is no timeout.
+  #     Unlike +silence_timeout+ this value does not reset when we receive feedback.
+  #     This option can be overridden by providing an alternate value to the +exec+ method on a case-by-case basis.
+  # +connect_timeout+::
+  #     This is the maximum amount of time to wait for the initial connection to the SSH shell.
+  #
+  #   Shells::SshShell.new(
+  #       host: '10.10.10.10',
+  #       user: 'somebody',
+  #       password: 'super-secret'
+  #   ) do |shell|
+  #     shell.exec('cd /usr/local/bin')
+  #     user_bin_files = shell.exec('ls -A1').split("\n")
+  #     @app_is_installed = user_bin_files.include?('my_app')
+  #   end
+  #
+  class SshShell < Shells::ShellBase
+
+    ##
+    # The error raised when we failed to request a PTY.
+    class FailedToRequestPty < Shells::ShellError
+
+    end
+
+    ##
+    # The error raised when we fail to start the shell on the PTY.
+    class FailedToStartShell < Shells::ShellError
+
+    end
+
+    attr_accessor :ssh, :channel
+    private :ssh, :ssh=, :channel, :channel=
+
+    add_hook :on_before_run do |sh|
+      sh.instance_eval do
+        self.ssh = nil
+        self.channel = nil
+      end
+    end
+
+    add_hook :on_after_run do |sh|
+      sh.instance_eval do
+        self.ssh = nil
+        self.channel = nil
+      end
+    end
+
+    protected
+
+    def validate_options  #:nodoc:
+      options[:host] ||= 'localhost'
+      options[:port] ||= 22
+      options[:shell] ||= :shell
+      options[:quit] ||= 'exit'
+      options[:connect_timeout] ||= 5
+
+      raise InvalidOption, 'Missing host.' if options[:host].to_s.strip == ''
+      raise InvalidOption, 'Missing user.' if options[:user].to_s.strip == ''
+    end
+
+
+    def connect #:nodoc:
+
+      debug 'Connecting to SSH host...'
+      self.ssh = Net::SSH.start(
+          options[:host],
+          options[:user],
+          password: options[:password],
+          port: options[:port],
+          non_interactive: true,
+          timeout: options[:connect_timeout]
+      )
+      debug ' > connected'
+
+      opened = false
+
+      debug 'Opening channel...'
+      self.channel = ssh.open_channel do |ch|
+        opened = true
+      end
+
+      io_loop { !opened }
+      debug ' > opened'
+
+    end
+
+    def setup #:nodoc:
+      done = false
+      unless options[:shell] == :no_pty
+        debug 'Acquiring PTY...'
+        channel.request_pty do |_, success|
+          raise FailedToRequestPty unless success
+          debug ' > acquired'
+          done = true
+        end
+      end
+
+      until done
+        sleep 0.0001
+      end
+
+      done = false
+      unless [:no_pty,:none].include?(options[:shell])
+        debug 'Starting shell...'
+        # pick a method to start the shell with.
+        meth = (options[:shell] == :shell) ? :send_channel_request : :exec
+        channel.send(meth, options[:shell].to_s) do |_, success|
+          raise FailedToStartShell unless success
+          debug ' > started'
+          done = true
+        end
+      end
+
+      until done
+        sleep 0.0001
+      end
+
+      debug 'Calling setup_prompt...'
+      setup_prompt
+      debug ' > prompt setup'
+    end
+
+    def disconnect #:nodoc:
+      debug 'Marking channel for closure...'
+      channel.close
+      debug ' > marked'
+      debug 'Closing SSH connection...'
+      ssh.close
+      debug ' > closed'
+    end
+
+    def send_data(data) #:nodoc:
+      channel.send_data data
+      debug "Sent: (#{data.size} bytes) #{(data.size > 32 ? (data[0..30] + '...') : data).inspect}"
+    end
+
+    def stdout_received(&block) #:nodoc:
+      channel.on_data do |_,data|
+        debug "Received: (#{data.size} bytes) #{(data.size > 32 ? (data[0..30] + '...') : data).inspect}"
+        block.call data
+      end
+    end
+
+    def stderr_received(&block) #:nodoc:
+      channel.on_extended_data do |_, type, data|
+        if type == 1
+          debug "Received: (#{data.size} bytes) [E] #{(data.size > 32 ? (data[0..30] + '...') : data).inspect}"
+          block.call data
+        else
+          debug "Received: (#{data.size} bytes) [#{type}] #{(data.size > 32 ? (data[0..30] + '...') : data).inspect}"
+        end
+      end
+    end
+
+    def active?
+      channel&.active?
+    end
+
+    def io_loop(&block)
+      shell = self
+      ssh&.loop(0.000001) do |_|
+        shell.instance_eval &block
+      end
+    end
+
+
+  end
+end