sshkit 0.0.7 → 0.0.8

data/CHANGELOG.md

@@ -3,6 +3,29 @@
 This file is written in reverse chronological order, newer releases will
 appear at the top.
 
+## 0.0.8
+
+* Added DSL method `background()` this sends a task to the background using
+  `nohup` and redirects it's output to `/dev/null` so as to avoid littering
+  the filesystem with `nohup.out` files.
+
+**Note:** Backgrounding a task won't work as you expect if you give it a
+string, that is you must do `background(:sleep, 5)` and not `background("sleep 5")`
+according to the rules by which a command is not processed in any way **if it
+contains a spaca character in it's first argument**.
+
+Usage Example:
+
+    on hosts do
+      background :rake, "assets:precompile" # typically takes 5 minutes!
+    end
+
+**Further:** Many programs are badly behaved and no not work well with `nohup`
+it has to do with the way nohup works, reopening the processe's file
+descriptors and redirecting them. Programs that re-open, or otherwise
+manipulate their own file descriptors may lock up when the SSH session is
+disconnected, often they block writing to, or reading from stdin/out.
+
 ## 0.0.7
 
 * DSL method `execute()` will now raise `SSHKit::Command::Failed` when the

data/EXAMPLES.md

@@ -65,6 +65,25 @@ leading slashes. It may be misleading as the `File.join()` is performed on the
 machine running the code, if that's a Windows box, the paths may be incorrectly
 joined according to the expectations of the machine receiving the commands.
 
+## Running a task in the background
+
+    on hosts do
+      in '/opt/sites/example.com' do
+        background :rails, :server
+      end
+    end
+
+This will run something like `nohup /usr/bin/env rails server > /dev/null &`,
+backgrounding the Rails process, and making sure we don't leave nohup log
+files littering the filesystem.
+
+**Note:** The `background()` method won't do what you expect if you pass a
+string `sleep 5`, according to the rules of processing commands, you must call
+`background(:sleep, "5")` (that is, command: sleep, args: 5).
+
+**Further Note:** The background() task wraps the given command in `nohup .... &` under some
+circumstances the program will hang anyway when the SSH session exits.
+
 ## Do not care about the host block
 
     on hosts do

data/README.md

@@ -178,8 +178,8 @@ should be printed.
 
 * No handling of slow / timed out connections
 * No handling of slow / hung remote commands
-* No built-in way to background() something (execute and background the
-  process).
+* ~~No built-in way to background() something (execute and background the
+  process).~~
 * No environment handling (sshkit might not need to care)
 * ~~No arbitrary `Host` properties (example storing `roles` on servers, or other
   metadata that might be useful in the `on()` block)~~
@@ -190,10 +190,10 @@ should be printed.
 * No verbosity control, commands should have a `Logger::LEVEL` on them,
   user-generated should be at a high level, the commands auto-generated from
   the guards and checks from as() and within() should have a lower level.
-* Decide if `execute()` (and friends) should raise on non-zero exit statuses or
+* ~~Decide if `execute()` (and friends) should raise on non-zero exit statuses or
   not, perhaps a family of similarly named bang methods should be the ones to
   raise. (Perhaps `test()` should be a way to `execute()` without raising, and
-  `execute()` and friends should always raise)
+  `execute()` and friends should always raise)~~
 * It would be nice to be able to say `SSHKit.config.formatter = :pretty` and
   have that method setter do the legwork of updating `SSHKit.config.output` to
   be an instance of the correct formatter class wrapping the existing output
@@ -204,3 +204,6 @@ should be printed.
   easily be modified to look into some connection factory for it's objects,
   saving half a second when running lots of `on()` blocks.
 * Documentation! (YARD style)
+* Wrap all commands in a known shell, that is that `execute('uptime')` should
+  be converted into `sh -c 'uptime'` to ensure that we have a consistent shell
+  experience.

data/lib/sshkit/backends/abstract.rb

@@ -25,6 +25,10 @@ module SSHKit
         raise MethodUnavailableError
       end
 
+      def background(command, args=[])
+        raise MethodUnavailableError
+      end
+
       def test(command, args=[])
         raise MethodUnavailableError
       end

data/lib/sshkit/backends/netssh.rb

@@ -20,6 +20,11 @@ module SSHKit
         _execute(*args).success?
       end
 
+      def background(*args)
+        options = args.extract_options!.merge(run_in_background: true)
+        _execute(*[*args, options]).success?
+      end
+
       def capture(*args)
         _execute(*args).stdout.strip
       end

data/lib/sshkit/command.rb

@@ -128,11 +128,17 @@ module SSHKit
         if options[:user]
           cs << "sudo su #{options[:user]} -c "
         end
+        if options[:run_in_background]
+          cs << 'nohup '
+        end
         cs << SSHKit.config.command_map[command.to_sym]
         if args.any?
           cs << ' '
           cs << args.join(' ')
         end
+        if options[:run_in_background]
+          cs << ' > /dev/null &'
+        end
         if options[:env]
           cs << ' )'
         end
@@ -142,7 +148,7 @@ module SSHKit
     private
 
       def default_options
-        { raise_on_non_zero_exit: true }
+        { raise_on_non_zero_exit: true, run_in_background: false }
       end
 
       def sanitize_command!

data/lib/sshkit/version.rb

@@ -1,3 +1,3 @@
 module SSHKit
-  VERSION = "0.0.7"
+  VERSION = "0.0.8"
 end

data/test/{integration → functional}/backends/test_netssh.rb

@@ -1,22 +1,10 @@
 require 'helper'
+require 'benchmark'
 
 module SSHKit
 
   module Backend
 
-    class ToSIoFormatter < StringIO
-      extend Forwardable
-      attr_reader :original_output
-      def_delegators :@original_output, :read, :rewind
-      def initialize(oio)
-        @original_output = oio
-      end
-      def write(obj)
-        warn "What: #{obj.to_hash}"
-        original_output.write "> Executing #{obj}\n"
-      end
-    end
-
     class TestNetssh < FunctionalTest
 
       def setup
@@ -47,19 +35,18 @@ module SSHKit
       end
 
       def simple_netssh
-        sio = ToSIoFormatter.new(StringIO.new)
         SSHKit.capture_output(sio) do
           printer.run
         end
         sio.rewind
         result = sio.read
         assert_equal <<-EOEXPECTED.unindent, result
-          > Executing if test ! -d /opt/sites/example.com; then echo "Directory does not exist '/opt/sites/example.com'" 2>&1; false; fi
-          > Executing cd /opt/sites/example.com && /usr/bin/env date
-          > Executing cd /opt/sites/example.com && /usr/bin/env ls -l /some/directory
-          > Executing if test ! -d /opt/sites/example.com/tmp; then echo "Directory does not exist '/opt/sites/example.com/tmp'" 2>&1; false; fi
-          > Executing if ! sudo su -u root whoami > /dev/null; then echo "You cannot switch to user 'root' using sudo, please check the sudoers file" 2>&1; false; fi
-          > Executing cd /opt/sites/example.com/tmp && ( RAILS_ENV=production ( sudo su -u root /usr/bin/env touch restart.txt ) )
+          if test ! -d /opt/sites/example.com; then echo "Directory does not exist '/opt/sites/example.com'" 2>&1; false; fi
+          cd /opt/sites/example.com && /usr/bin/env date
+          cd /opt/sites/example.com && /usr/bin/env ls -l /some/directory
+          if test ! -d /opt/sites/example.com/tmp; then echo "Directory does not exist '/opt/sites/example.com/tmp'" 2>&1; false; fi
+          if ! sudo su -u root whoami > /dev/null; then echo "You cannot switch to user 'root' using sudo, please check the sudoers file" 2>&1; false; fi
+          cd /opt/sites/example.com/tmp && ( RAILS_ENV=production ( sudo su -u root /usr/bin/env touch restart.txt ) )
         EOEXPECTED
       end
 
@@ -90,6 +77,21 @@ module SSHKit
         end.run
       end
 
+      def test_backgrounding_a_process
+        #SSHKit.config.output = SSHKit::Formatter::Pretty.new($stdout)
+        process_list = ""
+        time = Benchmark.measure do
+          Netssh.new(a_host) do
+            background :sleep, 5
+          end.run
+          Netssh.new(a_host) do
+            process_list = capture :ps, "aux | grep sleep | grep -v grep; true"
+          end.run
+        end
+        assert_operator time.real, :<, 1
+        assert_match "sleep 5", process_list
+      end
+
     end
 
   end

data/test/unit/test_command.rb

@@ -51,6 +51,21 @@ module SSHKit
       assert_equal "sudo su anotheruser -c /usr/bin/env whoami", String(c)
     end
 
+    def test_backgrounding_a_task
+      c = Command.new(:sleep, 15, run_in_background: true)
+      assert_equal "nohup /usr/bin/env sleep 15 > /dev/null &", String(c)
+    end
+
+    def test_backgrounding_a_task_as_a_given_user
+      c = Command.new(:sleep, 15, run_in_background: true, user: :anotheruser)
+      assert_equal "sudo su anotheruser -c nohup /usr/bin/env sleep 15 > /dev/null &", String(c)
+    end
+
+    def test_backgrounding_a_task_as_a_given_user_with_env
+      c = Command.new(:sleep, 15, run_in_background: true, user: :anotheruser, env: {a: :b})
+      assert_equal "( A=b sudo su anotheruser -c nohup /usr/bin/env sleep 15 > /dev/null & )", String(c)
+    end
+
     def test_complete?
       c = Command.new(:whoami, raise_on_non_zero_exit: false)
       refute c.complete?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sshkit
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.8
   prerelease: 
 platform: ruby
 authors:
@@ -256,10 +256,10 @@ files:
 - lib/sshkit/runners/sequential.rb
 - lib/sshkit/version.rb
 - sshkit.gemspec
+- test/functional/backends/test_netssh.rb
 - test/functional/test_coordinator.rb
 - test/functional/test_ssh_server_comes_up_for_functional_tests.rb
 - test/helper.rb
-- test/integration/backends/test_netssh.rb
 - test/unit/backends/test_netssh.rb
 - test/unit/backends/test_printer.rb
 - test/unit/core_ext/test_string.rb
@@ -292,10 +292,10 @@ signing_key:
 specification_version: 3
 summary: SSHKit makes it easy to write structured, testable SSH commands in Ruby
 test_files:
+- test/functional/backends/test_netssh.rb
 - test/functional/test_coordinator.rb
 - test/functional/test_ssh_server_comes_up_for_functional_tests.rb
 - test/helper.rb
-- test/integration/backends/test_netssh.rb
 - test/unit/backends/test_netssh.rb
 - test/unit/backends/test_printer.rb
 - test/unit/core_ext/test_string.rb