module Net::SFTP

# File lib/net/sftp.rb, line 30
def self.start(host, user, options={}, &block)
  session = Net::SSH.start(host, user, options)
  sftp = Net::SFTP::Session.new(session, &block).connect!

  if block_given?
    sftp.loop
    session.close
    return nil
  end

  sftp
rescue Object => anything
  begin
    session.shutdown!
  rescue ::Exception
    # swallow exceptions that occur while trying to shutdown
  end

  raise anything
end

A convenience method for starting a standalone SFTP session. It will start up an SSH session using the given arguments (see the documentation for Net::SSH::Session for details), and will then start a new SFTP session with the SSH session. This will block until the new SFTP is fully open and initialized before returning it.

sftp = Net::SFTP.start("localhost", "user")
sftp.upload! "/local/file.tgz", "/remote/file.tgz"

If a block is given, it will be passed to the SFTP session and will be called once the SFTP session is fully open and initialized. When the block terminates, the new SSH session will automatically be closed.

Net::SFTP.start("localhost", "user") do |sftp|
  sftp.upload! "/local/file.tgz", "/remote/file.tgz"
end

# File lib/net/sftp/session.rb, line 153
def dir
  @dir ||= Operations::Dir.new(self)
end

Returns a Net::SFTP::Operations::Dir instance, which can be used to conveniently iterate over and search directories on the remote server.

sftp.dir.glob("/base/path", "*/**/*.rb") do |entry|
  p entry.name
end

See Net::SFTP::Operations::Dir for a more detailed discussion of how to use this.

# File lib/net/sftp/session.rb, line 114
def download(remote, local, options={}, &block)
  Operations::Download.new(self, local, remote, options, &block)
end

Initiates a download from remote to local, asynchronously. This method will return a new Net::SFTP::Operations::Download instance, and requires that the event loop be run in order for the download to progress. See Net::SFTP::Operations::Download for a full discussion of hos this method can be used.

download = sftp.download("/remote/path", "/local/path")
download.wait

# File lib/net/sftp/session.rb, line 122
def download!(remote, local=nil, options={}, &block)
  require 'stringio' unless defined?(StringIO)
  destination = local || StringIO.new
  result = download(remote, destination, options, &block).wait
  local ? result : destination.string
end

Identical to download, but blocks until the download is complete. If local is omitted, downloads the file to an in-memory buffer and returns the result as a string; otherwise, returns the Net::SFTP::Operations::Download instance.

# File lib/net/sftp/session.rb, line 140
def file
  @file ||= Operations::FileFactory.new(self)
end

Returns an Net::SFTP::Operations::FileFactory instance, which can be used to mimic synchronous, IO-like file operations on a remote file via SFTP.

sftp.file.open("/path/to/file") do |file|
  while line = file.gets
    puts line
  end
end

See Net::SFTP::Operations::FileFactory and Net::SFTP::Operations::File for more details.

# File lib/net/sftp/session.rb, line 102
def upload!(local, remote = File.basename(local), options={}, &block)
  upload(local, remote, options, &block).wait
end

Identical to upload, but blocks until the upload is complete.