net-ssh-cli 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c603e7ea0fcbda5d3e982acf28cd42b1f8eaa5aa7d553f8b4e6e0e783ccf3ec
-  data.tar.gz: 0c70002f557ad71cee9a12f32998c808fe6d984d24c82a1a11c9f7f0a04655e4
+  metadata.gz: 479372e0f9e6a333d880bdf4ff6e1956070292b4983074b37cc51eaba300b59a
+  data.tar.gz: 16809adcd8badca90511c7ba97d4c081ae52cf20e37e812891af313b0bf6592a
 SHA512:
-  metadata.gz: 4f806eb1c4a035b586ce2b2e3783db4a8ba77d4143e7b916686fe95d54a0f5f748139245265b7cca18a52cdf7cbdb28de3f54c71bcbbb8cad15e03eeeb7599b6
-  data.tar.gz: ff6953edf2520f5732ee7b896a30e6fa184506093addb7e39b0c8cb69eb5735f928291047f989a1ba100f2d5a317cda5608cea1c97624eaac6b284c83e34b923
+  metadata.gz: 7b768213f3ccbc060411c96f0051b01b8a87339122f65fabc4c1898d1850fe06d7ffbcee437e5ddb627838a70f861cb3790fe2ddeaf1ee341545b8168cbfd63b
+  data.tar.gz: adb4c879d5f74e14924d9ab041a83512ca4ae551fc634d482a6ef5bd787eb8267ee4c54ff97f59a312af195fbdb1bed1d109c4b2d6fc0d59e6e132db91258640

data/lib/net/ssh/cli.rb

@@ -45,15 +45,23 @@ module Net
         cmd_rm_command:            false,                                        # whether the given command should be removed in the output of #cmd
         run_impact:                false,                                        # whether to run #impact commands. This might align with testing|development|production. example #impact("reboot")
         read_till_timeout:         nil,                                          # timeout for #read_till to find the match
+        read_till_hard_timeout:    nil,                                          # hard timeout for #read_till to find the match using Timeout.timeout(hard_timeout) {}. Might creates unpredicted sideffects
+        read_till_hard_timeout_factor: 1.2,                                      # hard timeout factor in case read_till_hard_timeout is true
         named_prompts:             ActiveSupport::HashWithIndifferentAccess.new, # you can used named prompts for #with_prompt {} 
+        before_cmd_procs:          ActiveSupport::HashWithIndifferentAccess.new, # procs to call before #cmd 
+        after_cmd_procs:           ActiveSupport::HashWithIndifferentAccess.new, # procs to call after  #cmd
         before_on_stdout_procs:    ActiveSupport::HashWithIndifferentAccess.new, # procs to call before data arrives from the underlying connection 
         after_on_stdout_procs:     ActiveSupport::HashWithIndifferentAccess.new, # procs to call after  data arrives from the underlying connection
+        before_on_stdin_procs:     ActiveSupport::HashWithIndifferentAccess.new, # procs to call before data is sent to the underlying channel 
+        after_on_stdin_procs:      ActiveSupport::HashWithIndifferentAccess.new, # procs to call after  data is sent to the underlying channel
         before_open_channel_procs: ActiveSupport::HashWithIndifferentAccess.new, # procs to call before opening a channel 
         after_open_channel_procs:  ActiveSupport::HashWithIndifferentAccess.new, # procs to call after  opening a channel, for example you could call #detect_prompt or #read_till
         open_channel_timeout:      nil,                                          # timeout to open the channel
         net_ssh_options:           ActiveSupport::HashWithIndifferentAccess.new, # a wrapper for options to pass to Net::SSH.start in case net_ssh is undefined
         process_time:              0.00001,                                      # how long #process is processing net_ssh#process or sleeping (waiting for something)
         background_processing:     false,                                        # default false, whether the process method maps to the underlying net_ssh#process or the net_ssh#process happens in a separate loop
+        on_stdout_processing:      100,                                          # whether to optimize the on_stdout performance by calling #process #optimize_on_stdout-times in case more data arrives
+        sleep_procs:               ActiveSupport::HashWithIndifferentAccess.new, # procs to call instead of Kernel.sleep(), perfect for async hooks
       )
 
       def options
@@ -108,19 +116,19 @@ module Net
         before_on_stdout_procs.each { |_name, a_proc| instance_eval(&a_proc) }
         stdout << new_data
         after_on_stdout_procs.each { |_name, a_proc| instance_eval(&a_proc) }
-        self.process_count += 1
-        process unless process_count > 100 # if we receive data, we probably receive more - improves performance - but on a lot of data, this leads to a stack level too deep
-        self.process_count -= 1
+        optimise_stdout_processing
         stdout
       end
 
-      def write(content = String.new)
+      def stdin(content = String.new)
         logger.debug { "#write #{content.inspect}" }
+        before_on_stdin_procs.each { |_name, a_proc| instance_eval(&a_proc) }
         channel.send_data content
         process
+        after_on_stdin_procs.each { |_name, a_proc| instance_eval(&a_proc) }
         content
       end
-      alias stdin write
+      alias write stdin
 
       def write_n(content = String.new)
         write content + "\n"
@@ -129,7 +137,7 @@ module Net
       def read
         process
         var = stdout!
-        logger.debug("#read: \n#{var}")
+        logger.debug { "#read: \n#{var}" }
         var
       end
 
@@ -140,6 +148,16 @@ module Net
         with_prompts[-1] || default_prompt
       end
 
+      # run something with a different named prompt
+      #
+      # named_prompts["root"] = /(?<prompt>\nroot)\z/
+      #
+      # with_named_prompt("root") do
+      #   cmd("sudo -i")
+      #   cmd("cat /etc/passwd")
+      # end
+      # cmd("exit")
+      #
       def with_named_prompt(name)
         raise Error::UndefinedMatch, "unknown named_prompt #{name}" unless named_prompts[name]
 
@@ -148,20 +166,25 @@ module Net
         end
       end
 
+      # tries to detect the prompt
+      # sends a "\n", waits for a X seconds, and uses the last line as prompt
+      # this won't work reliable if the prompt changes during the session
       def detect_prompt(seconds: 3)
         write_n
-        future = Time.now + seconds
-        while future > Time.now
-          process
-          sleep 0.1
-        end
+        process(seconds)
         self.default_prompt = read[/\n?^.*\z/]
         raise Error::PromptDetection, "couldn't detect a prompt" unless default_prompt.present?
 
         default_prompt
       end
 
-      # prove a block where the default prompt changes
+      # run something with a different prompt
+      #
+      # with_prompt(/(?<prompt>\nroot)\z/) do
+      #   cmd("sudo -i")
+      #   cmd("cat /etc/passwd")
+      # end
+      # cmd("exit")
       def with_prompt(prompt)
         logger.debug { "#with_prompt: #{current_prompt.inspect} => #{prompt.inspect}" }
         with_prompts << prompt
@@ -172,26 +195,48 @@ module Net
         logger.debug { "#with_prompt: => #{current_prompt.inspect}" }
       end
 
-      def read_till(prompt: current_prompt, timeout: read_till_timeout, **_opts)
+      # continues to process the ssh connection till #stdout matches the given prompt.
+      # might raise a timeout error if a soft/hard timeout is given
+      # be carefull when using the hard_timeout, this is using the dangerous Timeout.timeout
+      # this gets really slow on large outputs, since the prompt will be searched in the whole output. Use \z in the regex if possible
+      #
+      # Optional named arguments:
+      #  - prompt: expected to be a regex
+      #  - timeout: nil or a number
+      #  - hard_timeout: nil, true, or a number
+      #  - hard_timeout_factor: nil, true, or a number
+      #  -   when hard_timeout == true, this will set the hard_timeout as (read_till_hard_timeout_factor * read_till_timeout), defaults to 1.2 = +20%
+      def read_till(prompt: current_prompt, timeout: read_till_timeout, hard_timeout: read_till_hard_timeout, hard_timeout_factor: read_till_hard_timeout_factor, **_opts)
         raise Error::UndefinedMatch, 'no prompt given or default_prompt defined' unless prompt
+        hard_timeout = (read_till_hard_timeout_factor * timeout) if timeout and hard_timeout == true
+        hard_timeout = nil if hard_timeout == true
 
-        hard_timeout = timeout
-        hard_timeout += 0.5 if timeout
-        ::Timeout.timeout(hard_timeout, Error::ReadTillTimeout, "#{current_prompt.inspect} didn't match on #{stdout.inspect} within #{timeout}s") do
-          with_prompt(prompt) do
+        with_prompt(prompt) do
+          ::Timeout.timeout(hard_timeout, Error::ReadTillTimeout, "#{current_prompt.inspect} didn't match on #{stdout.inspect} within #{hard_timeout}s") do
             soft_timeout = Time.now + timeout if timeout
-            until stdout[current_prompt] do
+            until prompt_in_stdout? do
               if timeout and soft_timeout < Time.now
                 raise Error::ReadTillTimeout, "#{current_prompt.inspect} didn't match on #{stdout.inspect} within #{timeout}s"
               end
               process
-              sleep 0.1
+              sleep 0.01 # don't race for CPU
             end
           end
         end
         read
       end
 
+      def prompt_in_stdout?
+        case current_prompt
+        when Regexp
+          !!stdout[current_prompt]
+        when String
+          stdout.include?(current_prompt)
+        else
+          raise Net::SSH::CLI::Error, "prompt/current_prompt is not a String/Regex #{current_prompt.inspect}"
+        end
+      end
+
       def read_for(seconds:)
         process(seconds)
         read
@@ -202,18 +247,25 @@ module Net
         cmd(command, **opts)
       end
 
-      # 'read' first on purpuse as a feature. once you cmd you ignore what happend before. otherwise use read|write directly.
-      # this should avoid many horrible state issues where the prompt is not the last prompt
+      # send a command and get the output as return value
+      # 1. sends the given command to the ssh connection channel
+      # 2. continues to process the ssh connection until the prompt is found in the stdout
+      # 3. prepares the output using your callbacks
+      # 4. returns the output of your command
+      # Hint: 'read' first on purpuse as a feature. once you cmd you ignore what happend before. otherwise use read|write directly.
+      #       this should avoid many horrible state issues where the prompt is not the last prompt
       def cmd(command, pre_read: true, rm_prompt: cmd_rm_prompt, rm_command: cmd_rm_command, prompt: current_prompt, **opts)
         opts = opts.clone.merge(pre_read: pre_read, rm_prompt: rm_prompt, rm_command: rm_command, prompt: prompt)
         if pre_read
           pre_read_data = read
           logger.debug { "#cmd ignoring pre-command output: #{pre_read_data.inspect}" } if pre_read_data.present?
         end
+        before_cmd_procs.each { |_name, a_proc| instance_eval(&a_proc) }
         write_n command
         output = read_till(**opts)
         rm_prompt!(output, **opts)
         rm_command!(output, command, **opts)
+        after_cmd_procs.each { |_name, a_proc| instance_eval(&a_proc) }
         output
       rescue Error::ReadTillTimeout => error
         raise Error::CMD, "#{error.message} after cmd #{command.inspect} was sent"
@@ -221,6 +273,7 @@ module Net
       alias command cmd
       alias exec cmd
 
+      # Execute multiple cmds, see #cmd
       def cmds(*commands, **opts)
         commands.flatten.map { |command| [command, cmd(command, **opts)] }
       end
@@ -230,11 +283,26 @@ module Net
         output[command + "\n"] = '' if rm_command?(**opts) && output[command + "\n"]
       end
 
-      def rm_prompt!(output, **opts)
+      # removes the prompt from the given output
+      # prompt should contain a named match 'prompt' /(?<prompt>.*something.*)\z/
+      # for backwards compatibility it also tries to replace the first match of the prompt /(something)\z/
+      # it removes the whole match if no matches are given /something\z/ 
+      def rm_prompt!(output, prompt: current_prompt, **opts)
         if rm_prompt?(**opts)
-          prompt = opts[:prompt] || current_prompt
           if output[prompt]
-            prompt.is_a?(Regexp) ? output[prompt, 1] = '' : output[prompt] = ''
+            case prompt
+            when String then output[prompt] = ''
+            when Regexp
+              if prompt.names.include?("prompt")
+                output[prompt, "prompt"] = ''
+              else
+                begin
+                  output[prompt, 1] = ''
+                rescue IndexError
+                  output[prompt] = ''
+                end
+              end
+            end
           end
         end
       end
@@ -261,6 +329,19 @@ module Net
       alias hostname host
       alias to_s host
 
+      # if #sleep_procs are set, they will be called instead of Kernel.sleep
+      # great for async
+      # .sleep_procs["async"] = proc do |duration| async_reactor.sleep(duration) end
+      #
+      # cli.sleep(1)
+      def sleep(duration)
+        if sleep_procs.any?
+          sleep_procs.each { |_name, a_proc| instance_exec(duration, &a_proc) }
+        else
+          Kernel.sleep(duration)
+        end
+      end
+
       ## NET::SSH
       #
 
@@ -333,6 +414,17 @@ module Net
       def rm_command?(**opts)
         opts[:rm_cmd].nil? ? cmd_rm_command : opts[:rm_cmd]
       end
+
+      # when new data is beeing received, likely more data will arrive - this improves the performance by a large factor
+      # but on a lot of data, this leads to a stack level too deep
+      # therefore it is limited to max #on_stdout_processing
+      # the bigger on_stdout_processing, the closer we get to a stack level too deep
+      def optimise_stdout_processing
+        self.process_count += 1
+        process unless process_count > on_stdout_processing
+      ensure
+        self.process_count -= 1
+      end
     end
   end
 end

data/lib/net/ssh/cli/version.rb

@@ -3,7 +3,7 @@
 module Net
   module SSH
     module CLI
-      VERSION = '1.5.0'
+      VERSION = '1.6.0'
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: net-ssh-cli
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Fabian Stillhart
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-03-13 00:00:00.000000000 Z
+date: 2020-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -140,7 +140,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: 'Net::SSH::CLI: A library to handle CLI Sessions'