SFTP client for mruby

Inspired by Net::SFTP, empowers mruby, a work in progress!

The SFTP client is based on mruby-ssh and libssh2. The API design follows Net::SFTP as much as possible.

The resulting binary will be statically linked agains libssh2 and mbedtls. There are no external runtime dependencies and the code should run fine for Linux, Unix and Windows platform.

The snippet demontrates how to read a remote file line by line:

SFTP.start('test.rebex.net', 'demo', password: 'password') do |sftp|
  sftp.file.open('readme.txt', 'r') do |file|
    file.each_line(chomp: true) { |line| puts line }
  end
end

Installation

Add the line below to your build_config.rb:

MRuby::Build.new do |conf|
  # ... (snip) ...
  conf.gem 'mruby-sftp'
end

Or add this line to your aplication's mrbgem.rake:

MRuby::Gem::Specification.new('your-mrbgem') do |spec|
  # ... (snip) ...
  spec.add_dependency 'mruby-sftp'
end

Usage

To initiate a SFTP session it is recommended to use either SFTP.start

SFTP.start('test.rebex.net', 'demo', password: 'password') do |sftp|
  sftp # => SFTP::Session
end

or SSH::Session#sftp

SSH.start('test.rebex.net', 'demo', key: '~/.ssh/id_rsa') do |session|
  session.sftp # => SFTP::Session
end

_SFTP.start works the same way like _SSH.start. See the doc for mruby-ssh for how to connect and login to a SSH server.

SFTP::Session

The Session class encapsulates a single SFTP channel on a SSH connection. Instances of this class are what most applications will interact with most, as it provides access to both low-level (mkdir, rename, remove, symlink, etc.) and high-level (upload, download, etc.) SFTP operations.

SFTP.start('test.rebex.net', 'demo', password: 'password') do |sftp|
  sftp.download('remote/file', 'local/file') if sftp.exist? 'remote/file'
  sftp.upload('local/file', 'remote/file')
end

See session.rb and session.c for a complete list of available methods.

SFTP::Stat

A class representing the attributes of a file or directory on the server. It may be used to specify new attributes, or to query existing attributes.

SFTP.start('test.rebex.net', 'demo', password: 'password') do |sftp|
  sftp.stat('remote/file').size
  sftp.lstat('remote/file').file?
  sftp.fstat(file).uid
  sftp.setstat('remote/file', gid: 104)
end

See stat.rb and stat.c for a complete list of available methods.

SFTP::Dir

A convenience class for working with remote directories. It provides methods for searching and enumerating directory entries, similarly to the standard ::Dir class.

SFTP.start('test.rebex.net', 'demo', password: 'password') do |sftp|
  sftp.dir.foreach('/') do |entry|
    entry.name       # => 'readme.txt'
    entry.longname   # => '-rw------- 1 demo users        403 Apr 08  2014 readme.txt'
    entry.stats.size # => 403
  end
end

See dir.rb for a complete list of available methods.

SFTP::File

A wrapper around an SFTP file handle, that exposes an IO-like interface for interacting with the remote file.

SFTP.start('test.rebex.net', 'demo', password: 'password') do |sftp|
  sftp.file.open('readme.txt', 'r') do |file|
    file.readline  # => Read first line
    file.gets(5)   # => Read next 5 characters
    file.gets(nil) # => Read until end of file
    file.eof?      # => true
  end
end

See file_factory.rb, file.rb, file.c, handle.rb and handle.c for a complete list of available methods.

Build Flags

The underlying mruby-ssh mgem offers a set of build flags that are useful for SFTP operations.

Compression

To speed up the download/upload of files its possible to enable compression. The feature is optional and disabled by default.

To make us of it add the line below to your build_config.rb:

MRuby::Build.new do |conf|
  # ... (snip) ...
  conf.cc.defines += %w[LIBSSH2_HAVE_ZLIB HAVE_UNISTD_H]
end

Or add this line to your aplication's mrbgem.rake:

MRuby::Gem::Specification.new('your-mrbgem') do |spec|
  # ... (snip) ...
  spec.mruby.cc.defines += %w[LIBSSH2_HAVE_ZLIB HAVE_UNISTD_H]
end

Now initiate a new SFTP session with compress:true:

SFTP.start('test.rebex.net', 'demo', password: 'password', compress: true)

Optimize memory footprint

Its possible to reduce the memory footprint by a few kB if the tool only depend on SFTP operations without the need of advanced SSH functionality.

To make us of it add the line below to your build_config.rb:

MRuby::Build.new do |conf|
  # ... (snip) ...
  conf.cc.defines << 'MRB_SSH_TINY'
end

Or add this line to your aplication's mrbgem.rake:

MRuby::Gem::Specification.new('your-mrbgem') do |spec|
  # ... (snip) ...
  spec.mruby.cc.defines << 'MRB_SSH_TINY'
end

Development

Clone the repo:

$ git clone https://github.com/katzer/mruby-sftp.git && cd mruby-sftp/

Compile the source:

$ rake compile

Run the tests:

$ rake test

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/katzer/mruby-sftp.

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Authors

• Sebastián Katzer, Fa. appPlant GmbH

License

The mgem is available as open source under the terms of the MIT License.

Made with 😋 in Leipzig

© 2017 appPlant GmbH