net-ssh-cli 1.3.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2e89dcb750ca04e0f861e75a15f7b43f5c18a9409857bd1c44e1458227d2e153
-  data.tar.gz: f9e6ac90efa410f49401c04a4f66fa26e5977739005feba233b200d3336a41cf
+  metadata.gz: 6dd5a361663ac8c45079e1833688679c699f0022c1aa222f5e315992b2457fa3
+  data.tar.gz: d10d53f383ea82e100ff38ca46978fb27fbbaec1f49a8e6c4cd0e8cbca7abf9d
 SHA512:
-  metadata.gz: d71c9a4d883426849d939b49505c84d336fdcf26a3bce7ef1cae364f903881d6de2654091da2061d0ebb50e806ab56fea71b090b591c0924388976944b0aff27
-  data.tar.gz: a25df68ad93832c42767a88e6e14800160301e2ce36e4e938efb65954dbf2b8c5fdcd92a1cabab57b2ec06482cdf27a14936f101fa120914ae656fe828f0bd3c
+  metadata.gz: 3ab1b89f32f27604f5c04ed43b262f69860884be324077acc5802b5d0b03ebb544818ea53e36a8c04077a00a47b8e320aa7ae664653fd6eddeb3f6d53f0e30b9
+  data.tar.gz: 99bd97c5b61ea4853a3150047f8b88d6165e00a8e343b1a3ca746fd8648915555edcdc9bcbe0277568cf8d822e7622bdaa3a457604a7956bf9797d73a32eeef4

data/.ruby-version

@@ -1 +1 @@
-2.6
+3.0

data/README.md

@@ -79,12 +79,22 @@ It's the same as #cmd but for multiple commands.
 ```
 
 ### #dialog
+
+Use this method to specify a differnt 'prompt' for once. This is perfect for interactive commands. 
+
 ```ruby
   cli.dialog "echo 'are you sure?' && read -p 'yes|no>'", /\nyes|no>/
   # => "echo 'are you sure?' && read -p 'yes|no>'\nyes|no>"
   cli.cmd "yes"
 ```
 
+```ruby
+cli.dialog "passwd", /Current Password:/i
+cli.dialog "Old Password", /New Password:/i
+cli.dialog "New Password", /Repeat Password:/i
+cli.cmd "New Password"
+```
+
 ### #impact
 
 The very same as `#cmd` but it respects a flag whether to run commands with 'impact'.
@@ -148,10 +158,12 @@ Nearly everything can be configured.
 ### Callbacks
 
 The following callbacks are available
- - #before_open_channel
- - #after_open_channel
- - #before_on_data
- - #before_on_data
+ - before_open_channel
+ - after_open_channel
+ - before_on_stdout
+ - after_on_stdout
+ - before_on_stdin
+ - after_on_stdin
 
 ```ruby
 cli.before_open_channel do
@@ -166,6 +178,41 @@ cli.after_open_channel do
 end
 ```
 
+Using the callbacks you can define a debugger which shows the `stdout` buffer content each time new data is received.
+
+```ruby
+cli.after_on_stdout do
+  warn stdout
+end
+```
+
+```ruby
+cli.after_on_stdout do
+  puts "the following new data arrived on stdout #{new_data.inspect} from #{hostname}"
+end
+```
+
+or convert new lines between different OS
+```ruby
+cli.after_on_stdout do
+  stdout.gsub!("\r\n", "\n")
+end
+```
+
+or hide passwords
+```ruby
+cli.after_on_stdout do
+  stdout.gsub!(/password:\S+/, "<HIDDEN>")
+end
+```
+
+or change the stdin before sending it
+```ruby
+cli.before_on_stdin do
+  content.gsub("\n\n", "\n")
+end
+```
+
 ### #hostname #host #to_s
 
 ```ruby

data/lib/net/ssh/cli.rb

@@ -17,6 +17,7 @@ module Net
         class OpenChannelTimeout < Error; end
         class ReadTillTimeout < Error; end
         class PromptDetection < Error; end
+        class CMD < Error; end
       end
 
       # Example
@@ -42,17 +43,26 @@ module Net
         default_prompt:            /\n?^(\S+@.*)\z/,                             # the default prompt to search for
         cmd_rm_prompt:             false,                                        # whether the prompt should be removed in the output of #cmd
         cmd_rm_command:            false,                                        # whether the given command should be removed in the output of #cmd
+        cmd_rm_command_tail:       "\n",                                         # which format does the end of line return after a command has been submitted. Could be something like "ls\n" "ls\r\n" or "ls \n" (extra spaces)
         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
@@ -107,19 +117,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"
@@ -128,7 +138,7 @@ module Net
       def read
         process
         var = stdout!
-        logger.debug("#read: \n#{var}")
+        logger.debug { "#read: \n#{var}" }
         var
       end
 
@@ -139,6 +149,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]
 
@@ -147,20 +167,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
@@ -171,22 +196,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
-
-        ::Timeout.timeout(timeout + 0.5, Error::ReadTillTimeout) do
-          with_prompt(prompt) do
-            soft_timeout = Time.now + timeout 
-            until stdout[current_prompt] do
-              raise Error::ReadTillTimeout, "Timeout after #{timeout}s, #{current_prompt.inspect} never matched #{stdout.inspect}" if soft_timeout < Time.now
+        hard_timeout = (read_till_hard_timeout_factor * timeout) if timeout and hard_timeout == true
+        hard_timeout = nil if hard_timeout == true
+
+        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 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
@@ -194,40 +245,65 @@ module Net
 
       def dialog(command, prompt, **opts)
         opts = opts.clone.merge(prompt: prompt)
-        cmd(command, opts)
+        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)
+        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"
       end
       alias command cmd
       alias exec cmd
 
+      # Execute multiple cmds, see #cmd
       def cmds(*commands, **opts)
         commands.flatten.map { |command| [command, cmd(command, **opts)] }
       end
       alias commands cmds
 
       def rm_command!(output, command, **opts)
-        output[command + "\n"] = '' if rm_command?(opts) && output[command + "\n"]
+        output[command + cmd_rm_command_tail] = '' if rm_command?(**opts) && output[command + cmd_rm_command_tail]
       end
 
-      def rm_prompt!(output, **opts)
-        if rm_prompt?(opts)
-          prompt = opts[:prompt] || current_prompt
+      # 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)
           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
@@ -254,6 +330,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
       #
 
@@ -326,6 +415,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.3.0'
+      VERSION = '1.7.0'
     end
   end
 end

data/net-ssh-cli.gemspec

@@ -39,7 +39,7 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'bump'
-  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_dependency 'activesupport', '>= 4.0'
   spec.add_dependency 'net-ssh', '>= 4.0'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: net-ssh-cli
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.7.0
 platform: ruby
 authors:
 - Fabian Stillhart
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-07-15 00:00:00.000000000 Z
+date: 2021-02-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -140,7 +140,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.4
+rubygems_version: 3.2.3
 signing_key: 
 specification_version: 4
 summary: 'Net::SSH::CLI: A library to handle CLI Sessions'