net-ssh-simple 1.0.1 → 1.1.0

data/lib/net/ssh/simple/core.rb

@@ -5,7 +5,10 @@ module Net
     # @example
     #   # Block Syntax (synchronous)
     #   Net::SSH::Simple.sync do
-    #     ssh    'example1.com', 'echo "Hello World."'
+    #     r = ssh 'example1.com', 'echo "Hello World."'
+    #     puts r.stdout    #=> "Hello World."
+    #     puts r.exit_code #=> 0
+    #
     #     scp_ul 'example2.com', '/tmp/local_foo', '/tmp/remote_bar'
     #     scp_dl 'example3.com', '/tmp/remote_foo', '/tmp/local_bar'
     #   end
@@ -133,6 +136,72 @@ module Net
     #     end
     #   end
     #
+    # @example
+    #   #
+    #   # Here be dragons: Using the event-API for a stdin->stdout pipeline
+    #   #
+    #   Net::SSH::Simple.sync do
+    #     # open a shell
+    #     r = ssh('localhost', '/bin/sh') do |e,c,d|
+    #       # e = :start, :stdout, :stderr, :exit_code, :exit_signal or :finish
+    #       # c = our Net::SSH::Connection::Channel instance
+    #       # d = data for this event
+    #       case e
+    #         # :start is triggered exactly once per connection
+    #         when :start
+    #           # we can send data using Channel#send_data
+    #           c.send_data("echo 'hello stdout'\n")
+    #           c.send_data("echo 'hello stderr' 1>&2\n")
+    #           # don't forget to eof when done feeding!
+    #           c.eof!
+    #
+    #         # :stdout is triggered when there's stdout data from remote.
+    #         # by default the data is also appended to result[:stdout].
+    #         # you may return :no_append as seen below to avoid that.
+    #         when :stdout
+    #           # read the input line-wise (it *will* arrive fragmented!)
+    #           (@buf ||= '') << d
+    #           while line = @buf.slice!(/(.*)\r?\n/)
+    #             puts line #=> "hello stdout"
+    #           end
+    #           :no_append
+    #
+    #         # :stderr is triggered when there's stderr data from remote.
+    #         # by default the data is also appended to result[:stderr].
+    #         # you may return :no_append as seen below to avoid that.
+    #         when :stderr
+    #           # read the input line-wise (it *will* arrive fragmented!)
+    #           (@buf ||= '') << d
+    #           while line = @buf.slice!(/(.*)\r?\n/)
+    #             puts line #=> "hello stderr"
+    #           end
+    #           :no_append
+    #
+    #         # :exit_code is triggered when the remote process exits normally.
+    #         # it does *not* trigger when the remote process exits by signal!
+    #         when :exit_code
+    #           puts d #=> 0
+    #
+    #         # :exit_signal is triggered when the remote is killed by signal.
+    #         # this would normally raise a Net::SSH::Simple::Error but
+    #         # we suppress that here by returning :no_raise
+    #         when :exit_signal
+    #           puts d  # won't fire in this example, could be "TERM"
+    #           :no_raise
+    #
+    #         # :finish triggers after :exit_code when the command exits normally.
+    #         # it does *not* trigger when the remote process exits by signal!
+    #         when :finish
+    #           puts "we are finished!"
+    #       end
+    #     end
+    #   end
+    #
+    #   # Our Result has been populated normally, except for
+    #   # :stdout and :stdin (because we used :no_append).
+    #   puts r #=> Net::SSH::Simple::Result
+    #
+    #
     # @author moe@busyloop.net
     #
     class Simple
@@ -221,7 +290,7 @@ module Net
       # @param [String] host Destination hostname or ip-address
       # @param [String] cmd  Shell command to execute
       # @param opts (see Net::SSH::Simple#ssh)
-      # @param [Block] block Progress callback (optional)
+      # @param [Block] &block Progress callback (optional)
       # @return [Net::SSH::Simple::Result] Result
       #
       def scp_ul(host, src, dst, opts={}, &block)
@@ -236,7 +305,7 @@ module Net
       # @param [String] host Destination hostname or ip-address
       # @param [String] cmd  Shell command to execute
       # @param [Hash]   opts Parameters for the underlying Net::SSH
-      # @param [Block] block Progress callback (optional)
+      # @param [Block] &block Progress callback (optional)
       # @return [Net::SSH::Simple::Result] Result
       # @see Net::SSH::Simple#scp_ul
       #
@@ -253,6 +322,7 @@ module Net
       # @param [String] host Destination hostname or ip-address
       # @param [String] cmd  Shell command to execute
       # @param [Hash]   opts Parameters for the underlying Net::SSH
+      # @param [Block]  &block Use the event-API (see example above)
       # @option opts [Array] :auth_methods
       #  an array of authentication methods to try
       #
@@ -360,7 +430,7 @@ module Net
       #
       # @see http://net-ssh.github.com/ssh/v2/api/classes/Net/SSH/Config.html
       #      Net::SSH documentation for the 'opts'-hash
-      def ssh(host, cmd, opts={})
+      def ssh(host, cmd, opts={}, &block)
         with_session(host, opts) do |session|
           @result = Result.new(
             { :host   => host, :cmd    => cmd, :start_at => Time.new,
@@ -371,23 +441,33 @@ module Net
             chan.exec cmd do |ch, success|
               @result[:success] = success
               ch.on_data do |c, data|
-                @result[:stdout] += data.to_s
+                r = block.call(:stdout, ch, data) if block
+                @result[:stdout] += data.to_s unless r == :no_append
               end
               ch.on_extended_data do |c, type, data|
-                @result[:stderr] += data.to_s
+                r = block.call(:stderr, ch, data) if block
+                @result[:stderr] += data.to_s unless r == :no_append
               end
               ch.on_request('exit-status') do |c, data|
-                @result[:exit_code] = data.read_long
+                exit_code = data.read_long
+                block.call(:exit_code, ch, exit_code) if block
+                @result[:exit_code] = exit_code
               end
               ch.on_request('exit-signal') do |c, data|
-                @result[:exit_signal] = data.read_string
+                exit_signal = data.read_string
+                r = block.call(:exit_signal, ch, exit_signal) if block
+                @result[:exit_signal] = exit_signal
                 @result[:success] = false
-                raise "Killed by SIG#{@result[:exit_signal]}"
+                unless r == :no_raise
+                  raise "Killed by SIG#{@result[:exit_signal]}"
+                end
               end
+              block.call(:start, ch, nil) if block
             end
           end
           channel.wait
           @result[:finish_at] = Time.new
+          block.call(:finish, channel, nil) if block
           @result
         end
       end

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

@@ -1,7 +1,7 @@
 module Net
   module SSH
     class Simple
-      VERSION = "1.0.1"
+      VERSION = "1.1.0"
     end
   end
 end

data/spec/net-ssh-simple.rb

@@ -272,4 +272,215 @@ describe Net::SSH::Simple do
       v.to_s.should == 'Killed by SIGTERM @ ["localhost", {}]'
     end
   end
+
+  describe "event api" do
+    it "handles long stdin->stdout pipe" do
+      mockie = mock(:callbacks)
+      mockie.should_receive(:start).once.ordered
+      mockie.should_receive(:exit_code).once.ordered
+      mockie.should_receive(:finish).once.ordered
+      mockie.should_not_receive(:exit_signal)
+
+      stdout_copy = ''
+      a = Net::SSH::Simple.sync do
+        i = 0
+        r = ssh('localhost', 'sed "s/0/X/g"') do |e,c,d|
+          case e
+            when :start
+              mockie.start()
+              (0..16384).each do |i|
+                c.send_data("foobar #{i}\n")
+              end
+              c.eof!
+            when :stdout
+              stdout_copy << d
+              (@buf ||= '') << d
+              while line = @buf.slice!(/(.*)\r?\n/)
+                line.chop.should == "foobar #{i}".gsub('0','X')
+                i += 1
+              end
+            when :exit_code
+              mockie.exit_code()
+            when :exit_signal
+              mockie.exit_signal()
+            when :finish
+              mockie.finish()
+          end
+        end
+        r.stdout.should == stdout_copy
+        r.stderr.should == ''
+      end
+    end
+
+    it "handles intermingled stdout/stderr" do
+      mockie = mock(:callbacks)
+      mockie.should_receive(:start).once.ordered
+      mockie.should_receive(:exit_code).once.ordered
+      mockie.should_receive(:finish).once.ordered
+      mockie.should_not_receive(:exit_signal)
+      a = Net::SSH::Simple.sync do
+        stdout_c = 0
+        stderr_c = 0
+        stdout_copy = ''
+        stderr_copy = ''
+        r = ssh('localhost', '/bin/sh') do |e,c,d|
+          case e
+            when :start
+              mockie.start()
+              (1..420).each do |i|
+                c.send_data("echo 'hello stderr' 1>&2\n")
+                c.send_data("echo 'hello stdout'\n")
+                c.send_data("echo 'HELLO STDERR' 1>&2\n")
+                c.send_data("echo 'HELLO STDOUT'\n")
+              end
+              c.eof!
+            when :stdout
+              stdout_copy << d
+              (@buf ||= '') << d
+              while line = @buf.slice!(/(.*)\r?\n/)
+                oddeven = stdout_c % 2
+                case oddeven
+                  when 0
+                    line.chop.should == "hello stdout"
+                  else
+                    line.chop.should == "HELLO STDOUT"
+                end
+                stdout_c += 1
+              end
+            when :stderr
+              stderr_copy << d
+              (@buf ||= '') << d
+              while line = @buf.slice!(/(.*)\r?\n/)
+                oddeven = stderr_c % 2
+                case oddeven
+                  when 0
+                    line.chop.should == "hello stderr"
+                  else
+                    line.chop.should == "HELLO STDERR"
+                end
+                stderr_c += 1
+              end
+            when :exit_code
+              mockie.exit_code()
+
+            when :exit_signal
+              mockie.exit_signal()
+
+            when :finish
+              stdout_c.should == 840
+              stderr_c.should == 840
+              mockie.finish()
+          end
+        end
+        # result should be populated
+        r.stdout.should == stdout_copy
+        r.stderr.should == stderr_copy
+        r.exit_code.should == 0
+      end
+    end
+
+    it "handles signals" do
+      mockie = mock(:callbacks)
+      mockie.should_receive(:start).once.ordered
+      mockie.should_not_receive(:exit_code)
+      mockie.should_receive(:exit_signal).once
+      mockie.should_not_receive(:finish)
+
+      victim = Net::SSH::Simple.async do
+        begin
+          ssh('localhost', 'sleep 1020304157') do |e,c,d|
+            case e
+              when :start
+                mockie.start()
+              when :exit_signal
+                d.should == 'TERM'
+                mockie.exit_signal()
+              when :exit_code
+                mockie.exit_code()
+              when :finish
+                mockie.finish()
+            end
+          end
+        rescue => e
+          e
+        end
+      end
+
+      killer = Net::SSH::Simple.async do
+        ssh('localhost', "pkill -f 'sleep 1020304157'")
+      end
+
+      k = killer.value
+      k.success.should == true
+
+      v = victim.value
+      v.to_s.should == 'Killed by SIGTERM @ ["localhost", {}]'
+    end
+
+    it "handles signals (:no_raise)" do
+      mockie = mock(:callbacks)
+      mockie.should_receive(:start).once.ordered
+      mockie.should_not_receive(:exit_code)
+      mockie.should_receive(:exit_signal).once
+      mockie.should_receive(:finish).once.ordered
+
+      victim = Net::SSH::Simple.async do
+        begin
+          ssh('localhost', 'sleep 1020304157') do |e,c,d|
+            case e
+              when :start
+                mockie.start()
+              when :exit_signal
+                d.should == 'TERM'
+                mockie.exit_signal()
+                :no_raise
+              when :exit_code
+                mockie.exit_code()
+              when :finish
+                mockie.finish()
+            end
+          end
+        rescue => e
+          e
+        end
+      end
+
+      killer = Net::SSH::Simple.async do
+        ssh('localhost', "pkill -f 'sleep 1020304157'")
+      end
+
+      k = killer.value
+      k.success.should == true
+
+      v = victim.value
+      v.success.should == false
+      v.exit_signal.should == 'TERM'
+    end
+
+    it "respects :no_append" do
+      r = Net::SSH::Simple.sync do
+        stdout_c = 0
+        stderr_c = 0
+        stdout_copy = ''
+        stderr_copy = ''
+        ssh('localhost', '/bin/sh') do |e,c,d|
+          case e
+            when :start
+              c.send_data("echo 'hello stderr' 1>&2\n")
+              c.send_data("echo 'hello stdout'\n")
+              c.send_data("echo 'HELLO STDERR' 1>&2\n")
+              c.send_data("echo 'HELLO STDOUT'\n")
+              c.eof!
+            when :stdout
+              :no_append
+            when :stderr
+              :no_append
+          end
+        end
+      end
+      r.stdout.should == ''
+      r.stderr.should == ''
+    end
+
+  end
 end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 1
-  - 0
   - 1
-  version: 1.0.1
+  - 0
+  version: 1.1.0
 platform: ruby
 authors: 
 - Moe
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-10-23 00:00:00 +02:00
+date: 2011-10-25 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -149,7 +149,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 4169602504577549835
+      hash: -3127829972184651328
       segments: 
       - 0
       version: "0"
@@ -158,7 +158,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 4169602504577549835
+      hash: -3127829972184651328
       segments: 
       - 0
       version: "0"