Add SSHKit::Backend.current

The point of SSHKit::Backend.current is to give code access to the current
Backend without having to pass around a reference to it. For example, consider
a `git` helper that executes a git command:

def git(*args)
  SSHKit::Backend.current.execute(:git, *args)
end

Thanks to `current`, we can use this git method wherever we are in an `on`
block, without having to pass a reference to `self`:

on release_roles(:all) do
  git "status"
end

Without the thread local, the same task would be much more awkward due to the
necessary passing of `self`:

def git(backend, *args)
  backend.execute(:git, *args)
end

on release_roles(:all) do
  git self, "status"
end

To someone not intimately familiar with SSHKit, what `self` in this context is
confusing and not obvious at all. It is because SSHKit uses `instance_exec`
within the `on` block that `self` magically transforms.

Better to avoid using `self` altogether and prefer the thread local.

Author: mattbrictson

CHANGELOG.md

@@ -17,6 +17,10 @@ appear at the top.
     [PR #308](https://github.com/capistrano/sshkit/pull/308) @mattbrictson
   * `SSHKit::Backend::Printer#test` now always returns true
     [PR #312](https://github.com/capistrano/sshkit/pull/312) @mikz
+  * Add `SSHKit::Backend.current` so that Capistrano plugin authors can refactor
+    helper methods and still have easy access to the currently-executing Backend
+    without having to use global variables.
+    [PR #319](https://github.com/capistrano/sshkit/pull/319) @mattbrictson
 
 ## 1.8.1
 

lib/sshkit/backends/abstract.rb

@@ -4,6 +4,19 @@ module Backend
 
     MethodUnavailableError = Class.new(SSHKit::StandardError)
 
+    # The Backend instance that is running in the current thread. If no Backend
+    # is running, returns `nil` instead.
+    #
+    # Example:
+    #
+    #   on(:local) do
+    #     self == SSHKit::Backend.current # => true
+    #   end
+    #
+    def self.current
+      Thread.current["sshkit_backend"]
+    end
+
     class Abstract
 
       extend Forwardable
@@ -12,7 +25,10 @@ class Abstract
       attr_reader :host
 
       def run
+        Thread.current["sshkit_backend"] = self
         instance_exec(@host, &@block)
+      ensure
+        Thread.current["sshkit_backend"] = nil
       end
 
       def initialize(host, &block)

test/unit/backends/test_abstract.rb

@@ -131,6 +131,28 @@ def test_invoke_raises_no_method_error
         end
       end
 
+      def test_current_refers_to_currently_executing_backend
+        backend = nil
+        current = nil
+
+        backend = ExampleBackend.new do
+          backend = self
+          current = SSHKit::Backend.current
+        end
+        backend.run
+
+        assert_equal(backend, current)
+      end
+
+      def test_current_is_nil_outside_of_the_block
+        backend = ExampleBackend.new do
+          # nothing
+        end
+        backend.run
+
+        assert_nil(SSHKit::Backend.current)
+      end
+
       # Use a concrete ExampleBackend rather than a mock for improved assertion granularity
       class ExampleBackend < Abstract
         attr_writer :full_stdout