sshkit 0.0.2 → 0.0.3

data/.gitignore

@@ -1,3 +1,4 @@
 *.gem
+.yardoc
 .vagrant
 test/tmp

data/.yardopts

@@ -1 +1 @@
---no-private - README.md CHANGELOG.md FAQ.md LICENSE.md EXAMPLES.md
+--no-private - README.md CHANGELOG.md FAQ.md LICENSE.md EXAMPLES.md CONTRIBUTING.md RELEASING.md

data/CHANGELOG.md

@@ -3,6 +3,10 @@
 This file is written in reverse chronological order, newer releases will
 appear at the top.
 
+## 0.0.3
+
+* Refactor the runner classes into an abstract heirarchy.
+
 ## 0.0.2
 
 * Include a *Pretty* formatter

data/CONTRIBUTING.md

@@ -0,0 +1,4 @@
+# Contributing to SSHKit
+
+ * [**Don't** push your pull request](http://www.igvita.com/2011/12/19/dont-push-your-pull-requests/)
+ * [**Do** write a good commit message](http://365git.tumblr.com/post/3308646748/writing-git-commit-messages)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sshkit (0.0.1)
+    sshkit (0.0.2)
       net-ssh
       term-ansicolor
 

data/README.md

@@ -1,5 +1,4 @@
-![SSHKit Logo](/Users/leehambley/Projects/deployrb-deploy/assets/images/logo.png)
-
+![SSHKit Logo](https://raw.github.com/wacku/sshkit/master/assets/images/logo.png)
 
 **SSHKit** is a toolkit for running commands in a structured way on one or
 more servers.
@@ -48,7 +47,7 @@ the raised error.
 Helpers such as `runner()` and `rake()` which expand to `execute(:rails, "runner", ...)` and
 `execute(:rake, ...)` are convenience helpers for Ruby, and Rails based apps.
 
-## Parallel
+## Parallel
 
 Notice on the `on()` call the `in: :sequence` option, the following will do
 what you might expect:
@@ -156,6 +155,8 @@ first argument before attempting to find it in the *command map*.
 
 ## Output Handling
 
+![Example Output](https://raw.github.com/wacku/sshkit/master/assets/images/example_output.png)
+
 The output handling comprises two objects, first is the output itself, by
 default this is *$stdout*, but can be any object responding to a
 *StringIO*-like interface. The second part is the *formatter*.
@@ -173,9 +174,30 @@ should be printed.
 ## Known Issues
 
 * No handling of slow / timed out connections
-* No handling ot slow / hung remote commands
+* No handling of slow / hung remote commands
 * No built-in way to background() something (execute and background the
-  process)
-* No environment handling
-* No arbitrary `Host` properties
-
+  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)
+* No log/warning facility (passing Log messages to the output would work)
+  A log object could be made available globally which would emit a LogMessage
+  type object which would be recognised by the formatters that need to care
+  about them.
+* 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
+  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)
+* 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
+  stream.
+* No closing of connections, the abstract backend class should include a
+  cleanup method which is empty but can be overriden by
+* No conncetion pooling, the `connection` method of the NetSSH backend could
+  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)

data/RELEASING.md

@@ -0,0 +1,10 @@
+# Releasing
+
+* **Ensure the tests are passing.**
+* Determine which would be the correct next version number according to [semver](http://semver.org/).
+* Update the version in `./lib/sshkit/version.rb`.
+* Update the `CHANGELOG`.
+* Commit the changelog and version in a single commit, the message should be "Preparing vX.Y.Z"
+* Tag the commit `git tag vX.Y.Z` (if tagging a historical commit, `git tag` can take a *SHA1* after the tag name)
+* Push new commits, and tags to Github.
+* Push the gem to [rubygems](http://rubygems.org).

data/lib/sshkit/all.rb

@@ -11,6 +11,7 @@ require_relative 'connection_manager'
 require_relative 'formatters/abstract'
 require_relative 'formatters/black_hole'
 require_relative 'formatters/pretty'
+require_relative 'formatters/dot'
 
 require_relative 'backends/abstract'
 require_relative 'backends/printer'

data/lib/sshkit/backends/printer.rb

@@ -10,7 +10,7 @@ module SSHKit
       end
 
       def execute(*args)
-        output << command(*args)
+        output << String(command(*args)) + "\n"
       end
 
       def capture(command, args=[])

data/lib/sshkit/connection_manager.rb

@@ -1,54 +1,68 @@
 require 'timeout'
 
-class Runner
+module SSHKit
 
-  attr_reader :hosts, :block
+  module Runner
 
-  def initialize(hosts, &block)
-    @hosts       = Array(hosts)
-    @block       = block
-  end
+    class Abstract
 
-end
+      attr_reader :hosts, :block
+
+      def initialize(hosts, &block)
+        @hosts       = Array(hosts)
+        @block       = block
+      end
+
+      private
 
-class ParallelRunner < Runner
-  def execute
-    threads = []
-    hosts.each do |host|
-      threads << Thread.new(host) do |h|
-        SSHKit.config.backend.new(host, &block).run
+      def backend(host, &block)
+        SSHKit.config.backend.new(host, &block)
       end
+
     end
-    threads.map(&:join)
-  end
-end
 
-class SequentialRunner < Runner
-  attr_writer :wait_interval
-  def execute
-    hosts.each do |host|
-      SSHKit.config.backend.new(host, &block).run
-      sleep wait_interval
+    class Parallel < Abstract
+      def execute
+        threads = []
+        hosts.each do |host|
+          threads << Thread.new(host) do |h|
+            backend(host, &block).run
+          end
+        end
+        threads.map(&:join)
+      end
+    end
+
+    class Sequential < Abstract
+      attr_writer :wait_interval
+      def execute
+        hosts.each do |host|
+          backend(host, &block).run
+          sleep wait_interval
+        end
+      end
+      private
+      def wait_interval
+        @wait_interval ||= 2
+      end
+    end
+
+    class Group < Sequential
+      attr_writer :group_size
+      def execute
+        hosts.each_slice(group_size).collect do |group_hosts|
+          Parallel.new(group_hosts, &block).execute
+          sleep wait_interval
+        end.flatten
+      end
+      private
+      def group_size
+        @group_size ||= 2
+      end
     end
-  end
-  private
-  def wait_interval
-    @wait_interval ||= 2
-  end
-end
 
-class GroupRunner < SequentialRunner
-  attr_writer :group_size
-  def execute
-    hosts.each_slice(group_size).collect do |group_hosts|
-      ParallelRunner.new(group_hosts, &block).execute
-      sleep wait_interval
-    end.flatten
-  end
-  private
-  def group_size
-    @group_size ||= 2
   end
+
 end
 
 module SSHKit
@@ -68,9 +82,9 @@ module SSHKit
     def each(options={}, &block)
       options = default_options.merge(options)
       case options[:in]
-      when :parallel then ParallelRunner
-      when :sequence then SequentialRunner
-      when :groups   then GroupRunner
+      when :parallel then Runner::Parallel
+      when :sequence then Runner::Sequential
+      when :groups   then Runner::Group
       else
         raise RuntimeError, "Don't know how to handle run style #{options[:in].inspect}"
       end.new(hosts, &block).execute

data/lib/sshkit/formatters/dot.rb

@@ -0,0 +1,28 @@
+require 'term/ansicolor'
+
+module SSHKit
+
+  module Formatter
+
+    class Dot < Abstract
+
+      def write(obj)
+        if obj.is_a? SSHKit::Command
+          if obj.finished?
+            original_output << (obj.failure? ? c.red('.') : c.green('.'))
+          end
+        end
+      end
+      alias :<< :write
+
+      private
+
+      def c
+        @c ||= Term::ANSIColor
+      end
+
+    end
+
+  end
+
+end

data/lib/sshkit/version.rb

@@ -1,3 +1,3 @@
 module SSHKit
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/test/unit/backends/test_printer.rb

@@ -4,18 +4,6 @@ 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)
-        original_output.write "> Executing #{obj}\n"
-      end
-    end
-
     class TestPrinter < UnitTest
 
       def block_to_run
@@ -39,19 +27,19 @@ module SSHKit
       end
 
       def test_simple_printing
-        sio = ToSIoFormatter.new(StringIO.new)
+        sio = 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'" 1>&2; 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'" 1>&2; false; fi
-          > Executing if ! sudo su root -c whoami > /dev/null; then echo "You cannot switch to user 'root' using sudo, please check the sudoers file" 1>&2; false; fi
-          > Executing cd /opt/sites/example.com/tmp && ( RAILS_ENV=production sudo su root -c /usr/bin/env touch restart.txt )
+          if test ! -d /opt/sites/example.com; then echo "Directory does not exist '/opt/sites/example.com'" 1>&2; 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'" 1>&2; false; fi
+          if ! sudo su root -c whoami > /dev/null; then echo "You cannot switch to user 'root' using sudo, please check the sudoers file" 1>&2; false; fi
+          cd /opt/sites/example.com/tmp && ( RAILS_ENV=production sudo su root -c /usr/bin/env touch restart.txt )
         EOEXPECTED
       end
 

data/test/unit/test_connection_manager.rb

@@ -1,3 +1,4 @@
+require 'time'
 require 'helper'
 
 module SSHKit
@@ -5,7 +6,18 @@ module SSHKit
   class TestConnectionManager < UnitTest
 
     def setup
-      SSHKit.config.backend = SSHKit::Backend::Abstract
+      @s = String.new
+      SSHKit.config.backend = SSHKit::Backend::Printer
+    end
+
+    def tearddown
+      @s = nil
+    end
+
+    def block_to_run
+      lambda do |host|
+        execute "echo #{Time.now}"
+      end
     end
 
     def test_connection_manager_handles_a_single_argument
@@ -26,40 +38,38 @@ module SSHKit
     end
 
     def test_the_connection_manager_yields_the_host_to_each_connection_instance
-      spy = lambda do |host, connection|
-        assert_equal host, Host.new("1.example.com")
+      spy = lambda do |host|
+        execute "echo #{host.hostname}"
+      end
+      String.new.tap do |str|
+        SSHKit.capture_output str do
+          ConnectionManager.new(%w{1.example.com}).each &spy
+        end
+        assert_equal "echo 1.example.com", str.strip
       end
-      ConnectionManager.new(%w{1.example.com}).each &spy
     end
 
     def test_the_connection_manaager_runs_things_in_parallel_by_default
-      results = []
-      command = lambda do |host,connection|
-        results << Time.now
+      SSHKit.capture_output @s do
+        ConnectionManager.new(%w{1.example.com 2.example.com}).each &block_to_run
       end
-      ConnectionManager.new(%w{1.example.com 2.example.com}).each &command
       assert_equal 2, results.length
       assert_equal *results.map(&:to_i)
     end
 
     def test_the_connection_manager_can_run_things_in_sequence
-      results = []
-      command = lambda do |host,connection|
-        results << Time.now
+      SSHKit.capture_output @s do
+        ConnectionManager.new(%w{1.example.com 2.example.com}).each in: :sequence, &block_to_run
       end
-      ConnectionManager.new(%w{1.example.com 2.example.com}).each(in: :sequence, &command)
       assert_equal 2, results.length
       assert_operator results.first.to_i, :<, results.last.to_i
     end
 
     def test_the_connection_manager_can_run_things_in_groups
-      results = []
-      command = lambda do |host,connection|
-        debugger
-        results << Time.now
+      SSHKit.capture_output @s do
+        ConnectionManager.new(%w{1.example.com 2.example.com 3.example.com
+                                 4.example.com 5.example.com 6.example.com}).each in: :groups, &block_to_run
       end
-      ConnectionManager.new(%w{1.example.com 2.example.com 3.example.com
-                               4.example.com 5.example.com 6.example.com}).each(in: :groups, &command)
       assert_equal 6, results.length
       assert_equal *results[0..1].map(&:to_i)
       assert_equal *results[2..3].map(&:to_i)
@@ -68,9 +78,12 @@ module SSHKit
       assert_operator results[3].to_i, :<, results[4].to_i
     end
 
-    def test_slow_host_timeout
-      # Ensure that we throw an error and rollback if one host takes an
-      # exceptional length of time longer than the others
+    private
+
+    def results
+      @s.lines.collect do |line|
+        Time.parse(line.split[1..-1].join(' '))
+      end
     end
 
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sshkit
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-16 00:00:00.000000000 Z
+date: 2013-01-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-ssh
@@ -221,20 +221,19 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .travis.yml
-- .yardoc/checksums
-- .yardoc/object_types
-- .yardoc/objects/root.dat
-- .yardoc/proxy_types
 - .yardopts
 - CHANGELOG.md
+- CONTRIBUTING.md
 - EXAMPLES.md
 - FAQ.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.md
 - README.md
+- RELEASING.md
 - Rakefile
 - Vagrantfile
+- assets/images/example_output.png
 - assets/images/logo.png
 - example.rb
 - lib/core_ext/array.rb
@@ -250,6 +249,7 @@ files:
 - lib/sshkit/dsl.rb
 - lib/sshkit/formatters/abstract.rb
 - lib/sshkit/formatters/black_hole.rb
+- lib/sshkit/formatters/dot.rb
 - lib/sshkit/formatters/pretty.rb
 - lib/sshkit/host.rb
 - lib/sshkit/version.rb

data/.yardoc/checksums

@@ -1,13 +0,0 @@
-lib/deploy.rb 8f584561b611345114f38176ec53bf00f9d5550f
-lib/deploy/all.rb 9fc0b15f0968612fbd2ffaf0bba9dff6f788e3d1
-lib/deploy/host.rb 777a8deedcdd5b41dceab8773c992bafa5ee9f92
-lib/core_ext/hash.rb b7a0f0d1ab3b83f6b251e2f865ad6fa3766124a0
-lib/deploy/command.rb 1a04acc7d5abd1b288bbea3676c287434849ef05
-lib/core_ext/array.rb 3d495a96a0d1566877bf2ebb70ab9ea10a7d32e1
-lib/deploy/version.rb 30e41688e07f7ee74377aaef147250340df4a3f0
-lib/deploy/configuration.rb 3e9f042e0e9e9860d3950a1406a988586434de16
-lib/deploy/backends/netssh.rb c931441edd28ba7e134b0d3ae2fbf40efb347b81
-lib/deploy/backends/printer.rb db41b51e9624105efd7cb7f1fef426b506ebadaa
-lib/deploy/backends/abstract.rb 74260020d3a6c4913f7a3d9294968e1b2a1304a9
-lib/deploy/connection_manager.rb 28c8ef12a8a5923aeaa497ed02fd22869f57186b
-lib/deploy/dsl.rb a487b4e65ab52955b12a5fe55bda99dec61e16b9