Skip to content
SFTP client for mruby
Ruby C C++
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
include/mruby/ext Improve compiling with c++ Jul 27, 2018
mrblib Use safe navigation operator May 22, 2019
src Fix some bugs with file stats Jul 31, 2019
test Fix some bugs with file stats Jul 31, 2019
.appveyor.yml Upgrade mingw64 and ruby Jul 31, 2019
.codebeatsettings Initial commit Mar 7, 2018
.gitignore
.hound.yml Initial commit Mar 7, 2018
.rubocop.yml TargetRubyVersion: 2.5 Jul 31, 2019
.travis.yml Move to travis-ci.com Apr 9, 2019
LICENSE Initial commit Mar 7, 2018
README.md Move to travis-ci.com Apr 9, 2019
Rakefile Move to travis-ci.com Apr 9, 2019
build_config.rb Move to travis-ci.com Apr 9, 2019
mrbgem.rake

README.md

SFTP client for mruby
Build Status Build status codebeat badge

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

You can’t perform that action at this time.