sshkit 0.0.6 → 0.0.7

data/CHANGELOG.md

@@ -3,6 +3,32 @@
 This file is written in reverse chronological order, newer releases will
 appear at the top.
 
+## 0.0.7
+
+* DSL method `execute()` will now raise `SSHKit::Command::Failed` when the
+  exit status is non-zero. The message of the exception will be whatever the
+  process had written to stdout.
+* New DSL method `test()` behaves as `execute()` used to until this version.
+* `Command` now raises an error in `#exit_status=()` if the exit status given
+  is not zero. (see below)
+* All errors raised by error conditions of SSHKit are defined as subclasses of
+  `SSHKit::StandardError` which is itself a subclass of `StandardError`.
+
+The `Command` objects can be set to not raise, by passing `raise_on_non_zero_exit: false`
+when instantiating them, this is exactly what `test()` does internally.
+
+Example:
+
+    on hosts do |host
+      if test "[ -d /opt/sites ]" do
+        within "/opt/sites" do
+          execute :git, :pull
+        end
+      else
+        execute :git, :clone, 'some-repository', '/opt/sites'
+      end
+    end
+
 ## 0.0.6
 
 * Support arbitrary properties on Host objects. (see below)

data/EXAMPLES.md

@@ -43,7 +43,7 @@ This will output:
 **Note:** This example is a bit misleading, as the `www-data` user doesn't
 have a shell defined, one cannot switch to that user.
 
-## Stack directory nestings:
+## Stack directory nestings
 
     on hosts do
       in "/var" do
@@ -65,7 +65,7 @@ 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.
 
-## Do not care about the host block:
+## Do not care about the host block
 
     on hosts do
       # The |host| argument is optional, it will
@@ -76,7 +76,7 @@ joined according to the expectations of the machine receiving the commands.
 
     SSHKit.config.output = File.open('/dev/null')
 
-## Implement a dirt-simple formatter class:
+## Implement a dirt-simple formatter class
 
     class MyFormatter < SSHKit::Formatter::Abstract
       def write(obj)
@@ -99,16 +99,32 @@ joined according to the expectations of the machine receiving the commands.
       puts capture(:echo, "I don't care about security!")
     end
 
-## Execute and raise an error if something goes wrong:
+## Execute and raise an error if something goes wrong
 
     on hosts do |host|
       execute!(:echo, '"Example Message!" 1>&2; false')
     end
 
-This will raise `SSHKit::CommandUncleanExit.new("Example Message!")` which
-will cause the command to abort.
+This will raise `SSHKit::Command:Failed` with the `#message` "Example Message!"`
+which will cause the command to abort.
 
-## Do something different on one host, or another depending on a host property:
+## Make a test, or run a command which may fail without raising an error:
+
+    on hosts do |host
+      if test "[ -d /opt/sites ]" do
+        within "/opt/sites" do
+          execute :git, :pull
+        end
+      else
+        execute :git, :clone, 'some-repository', '/opt/sites'
+      end
+    end
+
+The `test()` command behaves exactly the same as execute however will return
+false if the command exits with a non-zero exit (as `man 1 test` does). As ti
+returns boolean it can be used to direct the control flow within the block.
+
+## Do something different on one host, or another depending on a host property
 
     host1 = SSHKit::Host.new 'user@example.com'
     host2 = SSHKit::Host.new 'user@example.org'
@@ -123,7 +139,7 @@ will cause the command to abort.
       execute! :git, :clone, "git@git.#{host.hostname}", target
     end
 
-## Connect to a host in the easiest possible way:
+## Connect to a host in the easiest possible way
 
     on 'example.com' do |host|
       execute :uptime
@@ -133,7 +149,7 @@ This will resolve the `example.com` hostname into a `SSHKit::Host` object, and
 try to pull up the correct configuration for it.
 
 
-## Run a command without it being command-mapped:
+## Run a command without it being command-mapped
 
 If the command you attempt to call contains a space character it won't be
 mapped:

data/lib/sshkit.rb

@@ -1,8 +1,7 @@
-require 'thread'
-require_relative 'sshkit/all'
-
 module SSHKit
 
+  StandardError = Class.new(::StandardError)
+
   class << self
     attr_accessor :config
   end
@@ -25,3 +24,5 @@ module SSHKit
   end
 
 end
+
+require_relative 'sshkit/all'

data/lib/sshkit/backends/abstract.rb

@@ -1,7 +1,7 @@
 module SSHKit
   module Backend
 
-    MethodUnavailableError = Class.new(RuntimeError)
+    MethodUnavailableError = Class.new(SSHKit::StandardError)
 
     class Abstract
 
@@ -25,6 +25,10 @@ module SSHKit
         raise MethodUnavailableError
       end
 
+      def test(command, args=[])
+        raise MethodUnavailableError
+      end
+
       def execute(command, args=[])
         raise MethodUnavailableError
       end
@@ -71,7 +75,8 @@ module SSHKit
       private
 
       def command(*args)
-        SSHKit::Command.new(*args, in: @pwd.nil? ? nil : File.join(@pwd), env: @env, host: @host, user: @user)
+        options = args.extract_options!
+        SSHKit::Command.new(*[*args, options.merge({in: @pwd.nil? ? nil : File.join(@pwd), env: @env, host: @host, user: @user})])
       end
 
       def connection

data/lib/sshkit/backends/netssh.rb

@@ -11,6 +11,11 @@ module SSHKit
         instance_exec(host, &@block)
       end
 
+      def test(*args)
+        options = args.extract_options!.merge(raise_on_non_zero_exit: false)
+        _execute(*[*args, options]).success?
+      end
+
       def execute(*args)
         _execute(*args).success?
       end

data/lib/sshkit/command.rb

@@ -31,6 +31,8 @@ module SSHKit
   # @author Lee Hambley
   class Command
 
+    Failed = Class.new(SSHKit::StandardError)
+
     attr_reader :command, :args, :options, :started_at, :started, :exit_status
 
     attr_accessor :stdout, :stderr
@@ -44,7 +46,7 @@ module SSHKit
     #
     def initialize(*args)
       raise ArgumentError, "May not pass no arguments to Command.new" if args.empty?
-      @options = args.extract_options!
+      @options = default_options.merge(args.extract_options!)
       @command = args.shift.to_s.strip.to_sym
       @args    = args
       @options.symbolize_keys!
@@ -83,6 +85,9 @@ module SSHKit
     def exit_status=(new_exit_status)
       @finished_at = Time.now
       @exit_status = new_exit_status
+      if options[:raise_on_non_zero_exit] && exit_status > 0
+        raise Failed, stderr.empty? ? "No messages written to stderr" : stderr.strip
+      end
     end
 
     def runtime
@@ -136,6 +141,10 @@ module SSHKit
 
     private
 
+      def default_options
+        { raise_on_non_zero_exit: true }
+      end
+
       def sanitize_command!
         command.to_s.strip!
         if command.to_s.match("\n")

data/lib/sshkit/host.rb

@@ -2,7 +2,7 @@ require 'ostruct'
 
 module SSHKit
 
-  UnparsableHostStringError = Class.new(StandardError)
+  UnparsableHostStringError = Class.new(SSHKit::StandardError)
 
   class Host
 

data/lib/sshkit/runners/parallel.rb

@@ -1,3 +1,5 @@
+require 'thread'
+
 module SSHKit
 
   module Runner

data/lib/sshkit/version.rb

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

data/test/helper.rb

@@ -9,7 +9,7 @@ rescue Bundler::BundlerError => e
 end
 require 'tempfile'
 require 'minitest/unit'
-require 'mocha'
+require 'mocha/setup'
 require 'turn'
 require 'unindent'
 require 'debugger'

data/test/integration/backends/test_netssh.rb

@@ -17,7 +17,12 @@ module SSHKit
       end
     end
 
-    class TestPrinter < FunctionalTest
+    class TestNetssh < FunctionalTest
+
+      def setup
+        super
+        SSHKit.config.output = SSHKit::Formatter::BlackHole.new($stdout)
+      end
 
       def block_to_run
         lambda do |host|
@@ -70,26 +75,19 @@ module SSHKit
         end
       end
 
-      def test_exit_status
-
+      def test_execute_raises_on_non_zero_exit_status_and_captures_stderr
+        err = assert_raises SSHKit::Command::Failed do
+          Netssh.new(a_host) do |host|
+            execute :echo, "'Test capturing stderr' 1>&2; false"
+          end.run
+        end
+        assert_equal "Test capturing stderr", err.message
       end
 
-      def test_raising_an_error_if_a_command_returns_a_bad_exit_status
-        skip "Where to implement this?"
-        # NOTE: I think that it might be wise to have Command raise when
-        # Command#exit_status=() is called, it would allow an option to
-        # be passed to command (raise_errors: false), which could also be
-        # inherited through Backend#command and specified on the (not yet
-        # existing) backend configurations.
-        assert_raises RuntimeError do
-          File.open('/dev/null', 'w') do |dnull|
-            SSHKit.capture_output(dnull) do
-              Netssh.new(a_host) do |host|
-                execute :false
-              end.run
-            end
-          end
-        end
+      def test_test_does_not_raise_on_non_zero_exit_status
+        Netssh.new(a_host) do |host|
+          test :false
+        end.run
       end
 
     end

data/test/unit/test_command.rb

@@ -1,4 +1,5 @@
 require 'helper'
+require 'sshkit'
 
 module SSHKit
   class TestCommand < UnitTest
@@ -51,7 +52,7 @@ module SSHKit
     end
 
     def test_complete?
-      c = Command.new(:whoami)
+      c = Command.new(:whoami, raise_on_non_zero_exit: false)
       refute c.complete?
       c.exit_status = 1
       assert c.complete?
@@ -69,7 +70,7 @@ module SSHKit
     end
 
     def test_failure?
-      c = Command.new(:whoami)
+      c = Command.new(:whoami, raise_on_non_zero_exit: false)
       refute c.failure?
       refute c.failed?
       c.exit_status = 1
@@ -93,7 +94,7 @@ module SSHKit
     end
 
     def test_setting_exit_status
-      c = Command.new(:whoami)
+      c = Command.new(:whoami, raise_on_non_zero_exit: false)
       assert_equal nil, c.exit_status
       assert c.exit_status = 1
       assert_equal 1, c.exit_status
@@ -109,5 +110,12 @@ module SSHKit
       end
     end
 
+    def test_command_raises_command_failed_error_when_non_zero_exit
+      error = assert_raises SSHKit::Command::Failed do
+        Command.new(:whoami).exit_status = 1
+      end
+      assert_equal "No messages written to stderr", error.message
+    end
+
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sshkit
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
   prerelease: 
 platform: ruby
 authors: