net-ssh-cli 1.7.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6dd5a361663ac8c45079e1833688679c699f0022c1aa222f5e315992b2457fa3
-  data.tar.gz: d10d53f383ea82e100ff38ca46978fb27fbbaec1f49a8e6c4cd0e8cbca7abf9d
+  metadata.gz: e3557b2b202abb2f722b950d3f16d0e1c36a57716289f138d4c7f04edb453546
+  data.tar.gz: 8e58d5fa7d2e89021ffcb10751fff17526542d1d16314f79769f7e5f67451ea0
 SHA512:
-  metadata.gz: 3ab1b89f32f27604f5c04ed43b262f69860884be324077acc5802b5d0b03ebb544818ea53e36a8c04077a00a47b8e320aa7ae664653fd6eddeb3f6d53f0e30b9
-  data.tar.gz: 99bd97c5b61ea4853a3150047f8b88d6165e00a8e343b1a3ca746fd8648915555edcdc9bcbe0277568cf8d822e7622bdaa3a457604a7956bf9797d73a32eeef4
+  metadata.gz: 447b6ac1b58038620c3886241352e48bf5b89cbe0512a9506e08ab359378f62d3629f0007516bbcf4c360e204ea259d865d65e6396ee66d5d10c8c05275ede08
+  data.tar.gz: a898d86bf7d7fdde7977bd6161e1801606da032b96e3fb04ba6c55a6e104d1d2db0e8f68b12763afb63fee036c19e3c087af203563323543d4328a5fb61c487d

data/README.md

@@ -60,6 +60,12 @@ end
   # => "echo 'bananas'\nbananas"
   cli.cmd "echo 'bananas'", rm_command: true, rm_prompt: true
   # => "bananas"
+  cli.cmd "echo 'bananas'", rm_command: true, rm_prompt: true, minimum_duration: 9
+  # => "bananas"
+  cli.cmd "echo 'bananas'", rm_command: true, rm_prompt: true, prompt: /\nuser@host:/m
+  # => "bananas"
+  cli.cmd "echo 'bananas'", rm_command: true, rm_prompt: true, timeout: 60
+  # => "bananas"
 ```
 
 Remove the command and the prompt for #cmd & #dialog by default
@@ -69,9 +75,23 @@ Remove the command and the prompt for #cmd & #dialog by default
   # => "bananas"
 ```
 
+You can define a timeout for a `#cmd` in order to avoid hanging commands. The timeout gets passed into the underlying function #read_till.
+This is usefull in case your prompt won't match because of an unexpected behaviour or undefined behaviour. For example some form of unexpected dialog. 
+The underlying implementation is using a soft timeout because `Timeout.timeout` is dangerous. In order to deal anyway with hanging low level issues, `Timeout.timeout` is used too, but with a higher value than the soft timeout.
+
+```ruby
+  cli = ssh.cli(default_prompt: /(\nuser@host):/m, read_till_timeout: 11)
+  cli.cmd "echo 'bananas'"                      # timeout is set to 11
+  # => "bananas"
+  cli.cmd "echo 'bananas'", timeout: 22         # timeout is set to 22
+  # => "bananas"
+  cli.cmd "sleep 33", timeout: 22               # timeout is set to 22
+  # Net::SSH::CLI::Error::CMD
+```
+
 ### #cmds
 
-It's the same as #cmd but for multiple commands.
+It's the same as `#cmd` but for multiple commands.
 
 ```ruby
   cli.cmds ["echo 'bananas'", "echo 'apples'"], rm_command: true, rm_prompt: true
@@ -236,6 +256,38 @@ This works usually, but is not guaranteed to work well.
   # => "[my prompt]"
 ```
 
+### An outdated view of all available Options
+
+Please check the file `lib/net/ssh/cli.rb` `OPTIONS` in order to get an up-to-date view of all available options, flags and arguments.
+
+```ruby
+      OPTIONS = ActiveSupport::HashWithIndifferentAccess.new(
+        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
+      )
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/net/ssh/cli.rb

@@ -40,10 +40,11 @@ module Net
       attr_accessor :channel, :stdout, :net_ssh, :logger, :new_data, :process_count
 
       OPTIONS = ActiveSupport::HashWithIndifferentAccess.new(
-        default_prompt:            /\n?^(\S+@.*)\z/,                             # the default prompt to search for
+        default_prompt:            /\n?^(\S+@.*)\z/,                             # the default prompt to search for. It is recommended to use \z to ensure you don't match the prompt too early.
         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)
+        cmd_minimum_duration:      0,                                            # how long do you want to wait/sleep after sending the command. After this waiting time, the output will be processed and the prompt will be searched. 
         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
@@ -253,9 +254,9 @@ module Net
       # 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.
+      # Hint: 'read' first on purpose 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)
+      def cmd(command, pre_read: true, rm_prompt: cmd_rm_prompt, rm_command: cmd_rm_command, prompt: current_prompt, minimum_duration: cmd_minimum_duration, **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
@@ -263,6 +264,7 @@ module Net
         end
         before_cmd_procs.each { |_name, a_proc| instance_eval(&a_proc) }
         write_n command
+        sleep(minimum_duration)
         output = read_till(**opts)
         rm_prompt!(output, **opts)
         rm_command!(output, command, **opts)

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

@@ -3,7 +3,7 @@
 module Net
   module SSH
     module CLI
-      VERSION = '1.7.0'
+      VERSION = '1.8.0'
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: net-ssh-cli
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.8.0
 platform: ruby
 authors:
 - Fabian Stillhart
-autorequire: 
+autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-02-01 00:00:00.000000000 Z
+date: 2021-04-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -125,7 +125,7 @@ homepage: https://github.com/swisscom/net-ssh-cli
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -140,8 +140,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
-signing_key: 
+rubygems_version: 3.2.15
+signing_key:
 specification_version: 4
 summary: 'Net::SSH::CLI: A library to handle CLI Sessions'
 test_files: []