Add SSHKit::Backend.current

[mattbrictson]

This PR adds the SSHKit::Backend.current method that I originally introduced in a monkey patch in this Capistrano PR: capistrano/capistrano#1561

[leehambley]

Small PRs are lovely <3

[robd]

I'm very late to the party, so I realise that this is needed for stuff that is already merged in Capistrano, but I just wanted to understand a bit more about this.

I read up about this here, and I think it's a good idea to stop monkey patching Object, but I just wondered if a thread local is the only way of achieving this. I don't really know how capistrano holds onto it's SSHKit instance but would it be possible to allow the plugin API to provide the SSHKit backend instance explicitly to the plugins via a method, argument, yield param or something rather than depending on a thread local having to have been set by SSHKit? Maybe this is impossible without significant changes to everything, I cannot work it out!

My limited experience with thread locals is that they can be hard to reason about / test because they rely on things being set up at the right time.

Were you thinking of the public API for this to be SSHKit::Backend.current, or would the plugins access the thread local directly? I think it would be good to hide the thread local as an implementation detail and access only through SSHKit::Backend.current, which looks as if this might be what you are thinking of too.

[mattbrictson]

I think it would be good to hide the thread local as an implementation detail and access only through SSHKit::Backend.current, which looks as if this might be what you are thinking of too.

Yes, in fact current is an implementation detail as well. Plugin authors will access the backend through a private backend helper method that hides the details.

See: https://github.com/capistrano/capistrano/blob/4f56f6914c200d695071eb4eb8d6a4838b3f0f3a/lib/capistrano/plugin.rb#L103

[robd]

OK yeah I see - thanks for that link.

I see now in that same class, that normally plugin access through to SSHKit is provided via the on method.

In cases when you need to use SSHKit's backend outside of an on block

One thing I don't understand is if a plugin hasn't called the on method, how would the sshkit_backend thread local have been set? Is there somewhere else which sets up an SSHKit session (and the related state on the thread) before calling the plugin?

[mattbrictson]

One thing I don't understand is if a plugin hasn't called the on method…

It's in the case where the on method is called in a different location. The SCM plugins, for example, have the on blocks defined in a .rake file, but within those blocks the tasks make use of helper methods that are defined somewhere else (i.e. in the plugin class).

So your .rake file might include:

task :check do
  on release_roles(:all) do
    plugin.git "status"
  end
end

And then in the plugin class:

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

Without the backend helper (using the thread local), it is very awkward to use helper methods like these. You'd have to pass self, which because the backend uses instance_exec, is very confusing in practice.

See also my commit message here: mattbrictson@8032db6

[robd]

Ah sorry - I somehow managed to miss that commit message which has all the info I needed - I understand now. Thanks for explaining it all again here.