https://github.com/katzer/mruby-sftp
SFTP client for mruby
https://github.com/katzer/mruby-sftp
mruby-gem sftp sftp-client ssh
Last synced: 5 months ago
JSON representation
SFTP client for mruby
- Host: GitHub
- URL: https://github.com/katzer/mruby-sftp
- Owner: katzer
- License: mit
- Created: 2018-03-07T13:52:20.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2024-08-24T16:38:19.000Z (over 1 year ago)
- Last Synced: 2024-08-24T18:08:52.407Z (over 1 year ago)
- Topics: mruby-gem, sftp, sftp-client, ssh
- Language: Ruby
- Size: 133 KB
- Stars: 1
- Watchers: 5
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# SFTP client for mruby
[](https://travis-ci.com/katzer/mruby-sftp) [](https://ci.appveyor.com/project/katzer/mruby-sftp/branch/master) [](https://codebeat.co/projects/github-com-katzer-mruby-sftp-master)
Inspired by [Net::SFTP][net_sftp], empowers [mruby][mruby], a work in progress!
The SFTP client is based on [mruby-ssh][mruby_ssh] and [libssh2][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:
```ruby
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`:
```ruby
MRuby::Build.new do |conf|
# ... (snip) ...
conf.gem 'mruby-sftp'
end
```
Or add this line to your aplication's `mrbgem.rake`:
```ruby
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`
```ruby
SFTP.start('test.rebex.net', 'demo', password: 'password') do |sftp|
sftp # => SFTP::Session
end
```
or `SSH::Session#sftp`
```ruby
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][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.
```ruby
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](mrblib/sftp/session.rb) and [session.c](src/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.
```ruby
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](mrblib/sftp/stat.rb) and [stat.c](src/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.
```ruby
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](mrblib/sftp/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.
```ruby
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](mrblib/sftp/file_factory.rb), [file.rb](mrblib/sftp/file.rb), [file.c](src/file.c), [handle.rb](mrblib/sftp/handle.rb) and [handle.c](src/handle.c) for a complete list of available methods.
### Build Flags
The underlying [mruby-ssh][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`:
```ruby
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`:
```ruby
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`:
```ruby
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`:
```ruby
MRuby::Build.new do |conf|
# ... (snip) ...
conf.cc.defines << 'MRB_SSH_TINY'
end
```
Or add this line to your aplication's `mrbgem.rake`:
```ruby
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][license].
Made with :yum: in Leipzig
© 2017 [appPlant GmbH][appplant]
[mruby]: https://github.com/mruby/mruby
[net_sftp]: https://github.com/net-ssh/net-sftp
[mruby_ssh]: https://github.com/katzer/mruby-ssh
[libssh2]: https://www.libssh2.org
[license]: http://opensource.org/licenses/MIT
[appplant]: www.appplant.de