libssh 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7be9ae9a286b0ce4ae93064adb441780d087d3b8
-  data.tar.gz: 16f67e922fe6a5079b4f1548b815496b5151664b
+  metadata.gz: f05291298150e6683ac9b6647515440e7dafe6a7
+  data.tar.gz: 9c174e89993c04dee954032011fdf13987947bfa
 SHA512:
-  metadata.gz: fb7c02285aba9f22d8c5c60ed386d2b8e1e167032ebd044d804bbc747ceeb6f740d76643312cf3910c6a04c18385e160cda2f9efdfc48db32a0385edadcafcd6
-  data.tar.gz: af5ed17903b463d777f6b7eee70a2fc8347a66d16eab1cad402bb8ffd272c509d4b741547505226ff40324193726dd1a90764e51a60c0f4ba3ee841bc420b3c3
+  metadata.gz: 4760b23e84edef76e93604c38a0903bbf04ea682652754c5df1029fb21b688cf728acf5fa211253827884002612a1a5a038d7f33ff8c10e91c8b60b181c11396
+  data.tar.gz: 82a03d32630272ddd632527ba70e83daa87b2a84af5d35aa8cee8a8ff83947e9ed241b6ed2d7363e62f6871342a66c5041ad5b2110a0f25e17e536d1aad9b90b

data/.rubocop.yml

@@ -5,6 +5,8 @@ AllCops:
 
 Metrics/AbcSize:
   Enabled: false
+Metrics/ClassLength:
+  Enabled: false
 Metrics/CyclomaticComplexity:
   Enabled: false
 Metrics/LineLength:

data/CHANGELOG.md

@@ -1,2 +1,6 @@
+## 0.2.0 (2016-01-30)
+- Add many wrapper methods
+- Support `upload!` and `download!` as SSHKit backend.
+
 ## 0.1.0 (2016-01-24)
 - Initial release

data/README.md

@@ -1,4 +1,5 @@
 # LibSSH
+[![Gem Version](https://badge.fury.io/rb/libssh.svg)](https://badge.fury.io/rb/libssh)
 [![Build Status](https://travis-ci.org/eagletmt/libssh-ruby.svg?branch=master)](https://travis-ci.org/eagletmt/libssh-ruby)
 
 Ruby binding for [libssh](https://www.libssh.org/) .
@@ -30,7 +31,7 @@ Or install it yourself as:
 
 ## Usage
 
-See [example/exec.rb](example/exec.rb) and [example/write.rb](example/write.rb).
+See [example](example) directory.
 
 ### With SSHKit
 
@@ -43,6 +44,9 @@ require 'sshkit/backends/libssh'
 set :sshkit_backend, SSHKit::Backend::Libssh
 ```
 
+## Documentation
+http://www.rubydoc.info/github/eagletmt/libssh-ruby
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/example/exec.rb

@@ -2,6 +2,8 @@
 require 'libssh'
 
 GC.stress = true
+puts "libssh #{LibSSH::LIBSSH_VERSION}"
+puts LibSSH.version
 session = LibSSH::Session.new
 # session.log_verbosity = :debug
 session.host = 'barkhorn'

data/example/scp_download.rb

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+require 'libssh'
+
+host = 'barkhorn'
+remote_path = '/etc/passwd'
+
+GC.stress = true
+session = LibSSH::Session.new
+# session.log_verbosity = :debug
+session.host = host
+session.parse_config
+session.add_identity('%d/id_ed25519')
+
+session.connect
+if session.server_known != LibSSH::SERVER_KNOWN_OK
+  raise
+end
+if session.userauth_publickey_auto != LibSSH::AUTH_SUCCESS
+  raise 'authorization failed'
+end
+
+scp = LibSSH::Scp.new(session, :read, remote_path)
+scp.init do
+  loop do
+    case scp.pull_request
+    when LibSSH::Scp::REQUEST_NEWFILE
+      size = scp.request_size
+      puts "size=#{size}, filename=#{scp.request_filename}, mode=#{scp.request_permissions.to_s(8)}"
+      scp.accept_request
+
+      n = 0
+      buf = ''
+      while n < size
+        s = scp.read(size)
+        puts "Read #{s.size}"
+        n += s.size
+        buf << s
+      end
+      puts buf
+    when LibSSH::Scp::REQUEST_NEWDIR
+      puts "newdir: name=#{scp.request_filename}, mode=#{scp.request_permissions.to_s(8)}"
+      scp.accept_request
+    when LibSSH::Scp::REQUEST_ENDDIR
+      puts 'enddir'
+    when LibSSH::Scp::REQUEST_WARNING
+      puts "warning: #{scp.request_warning}"
+    when LibSSH::Scp::REQUEST_EOF
+      break
+    end
+  end
+end

data/example/scp_upload.rb

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+require 'libssh'
+require 'pathname'
+
+host = 'barkhorn'
+target_dir = '/tmp'
+
+GC.stress = true
+session = LibSSH::Session.new
+# session.log_verbosity = :debug
+session.host = host
+session.parse_config
+session.add_identity('%d/id_ed25519')
+
+session.connect
+if session.server_known != LibSSH::SERVER_KNOWN_OK
+  raise
+end
+if session.userauth_publickey_auto != LibSSH::AUTH_SUCCESS
+  raise 'authorization failed'
+end
+
+scp = LibSSH::Scp.new(session, :write, target_dir)
+scp.init do
+  path = Pathname.new(__dir__).parent.join('README.md')
+  scp.push_file(path.basename.to_s, path.size, path.stat.mode & 0xfff)
+  path.read do |buf|
+    scp.write(buf)
+  end
+  puts "Uploaded #{path} to #{host}:#{File.join(target_dir, path.basename)}"
+end

data/example/sshkit.rb

@@ -7,6 +7,10 @@ require 'sshkit/dsl'
 SSHKit.config.backend = SSHKit::Backend::Libssh
 SSHKit.config.backend.configure do |backend|
   backend.pty = ENV.key?('REQUEST_PTY')
+  backend.ssh_options[:user] = ENV['SSH_USER']
+  if ENV.key?('SSH_PORT')
+    backend.ssh_options[:port] = ENV['SSH_PORT'].to_i
+  end
 end
 SSHKit.config.output = SSHKit::Formatter::Pretty.new($stdout)
 SSHKit.config.output_verbosity = :debug
@@ -20,3 +24,10 @@ on %w[barkhorn rossmann], in: :parallel do
   execute :ruby, '-e', Shellwords.escape('puts "stdout"; $stderr.puts "stderr"')
   execute :false, raise_on_non_zero_exit: false
 end
+
+on %w[barkhorn rossmann], in: :parallel do |host|
+  upload! __FILE__, '/tmp/sshkit.rb'
+  upload! StringIO.new("libssh\n"), '/tmp/libssh.txt'
+
+  download! '/etc/passwd', "/tmp/#{host}-passwd"
+end

data/ext/libssh_ruby/channel.c

@@ -80,6 +80,14 @@ static void *nogvl_close(void *ptr) {
   return NULL;
 }
 
+/*
+ * @overload close
+ *  Close a channel.
+ *  @since 0.1.0
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__channel.html
+ *    ssh_channel_close
+ */
 static VALUE m_close(VALUE self) {
   ChannelHolder *holder;
   struct nogvl_channel_args args;
@@ -98,6 +106,15 @@ static void *nogvl_open_session(void *ptr) {
   return NULL;
 }
 
+/*
+ * @overload open_session
+ *  Open a session channel, and close it after the block.
+ *  @since 0.1.0
+ *  @yieldparam [Channel] channel self
+ *  @return [Object] Return value of the block
+ *  @see http://api.libssh.org/stable/group__libssh__channel.html
+ *    ssh_channel_open_session
+ */
 static VALUE m_open_session(VALUE self) {
   ChannelHolder *holder;
   struct nogvl_channel_args args;
@@ -127,6 +144,15 @@ static void *nogvl_request_exec(void *ptr) {
   return NULL;
 }
 
+/*
+ * @overload request_exec(cmd)
+ *  Run a shell command without an interactive shell.
+ *  @since 0.1.0
+ *  @param [String] cmd The command to execute
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__channel.html
+ *    ssh_channel_request_exec
+ */
 static VALUE m_request_exec(VALUE self, VALUE cmd) {
   ChannelHolder *holder;
   struct nogvl_request_exec_args args;
@@ -145,6 +171,14 @@ static void *nogvl_request_pty(void *ptr) {
   return NULL;
 }
 
+/*
+ * @overload request_pty
+ *  Request a PTY.
+ *  @since 0.1.0
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__channel.html
+ *    ssh_channel_request_pty
+ */
 static VALUE m_request_pty(VALUE self) {
   ChannelHolder *holder;
   struct nogvl_channel_args args;
@@ -172,6 +206,17 @@ static void *nogvl_read(void *ptr) {
   return NULL;
 }
 
+/*
+ * @overload read(count, is_stderr: false, timeout: -1)
+ *  Read data from a channel.
+ *  @since 0.1.0
+ *  @param [Fixnum] count The count of bytes to be read.
+ *  @param [Boolean] is_stderr Read from the stderr flow or not.
+ *  @param [Fixnum] timeout A timeout in seconds. +-1+ means infinite timeout.
+ *  @return [String] Data read from the channel.
+ *  @see http://api.libssh.org/stable/group__libssh__channel.html
+ *    ssh_channel_read_timeout
+ */
 static VALUE m_read(int argc, VALUE *argv, VALUE self) {
   ChannelHolder *holder;
   VALUE count, opts;
@@ -205,6 +250,14 @@ static VALUE m_read(int argc, VALUE *argv, VALUE self) {
   return ret;
 }
 
+/*
+ * @overload eof?
+ *  Check if remote ha sent an EOF.
+ *  @since 0.1.0
+ *  @return [Boolean]
+ *  @see http://api.libssh.org/stable/group__libssh__channel.html
+ *    ssh_channel_is_eof
+ */
 static VALUE m_eof_p(VALUE self) {
   ChannelHolder *holder;
 
@@ -226,6 +279,18 @@ static void *nogvl_poll(void *ptr) {
   return NULL;
 }
 
+/*
+ * @overload poll(is_stderr: false, timeout: -1)
+ *  Poll a channel for data to read.
+ *  @since 0.1.0
+ *  @param [Boolean] is_stderr A boolean to select the stderr stream.
+ *  @param [Fixnum] timeout A timeout in milliseconds. A negative value means an
+ *    infinite timeout.
+ *  @return [Fixnum, nil] The number of bytes available for reading. +nil+ if
+ *    timed out.
+ *  @see http://api.libssh.org/stable/group__libssh__channel.html
+ *    ssh_channel_poll_timeout
+ */
 static VALUE m_poll(int argc, VALUE *argv, VALUE self) {
   ChannelHolder *holder;
   VALUE opts;
@@ -265,6 +330,15 @@ static void *nogvl_get_exit_status(void *ptr) {
   return NULL;
 }
 
+/*
+ * @overload get_exit_status
+ *  Get the exit status of the channel.
+ *  @since 0.1.0
+ *  @return [Fixnum, nil] The exit status. +nil+ if no exit status has been
+ *    returned.
+ *  @see http://api.libssh.org/stable/group__libssh__channel.html
+ *    ssh_channel_get_exit_status
+ */
 static VALUE m_get_exit_status(VALUE self) {
   ChannelHolder *holder;
   struct nogvl_channel_args args;
@@ -292,6 +366,15 @@ static void *nogvl_write(void *ptr) {
   return NULL;
 }
 
+/*
+ * @overload write(data)
+ *  Write data on the channel.
+ *  @since 0.1.0
+ *  @param [String] data Data to write.
+ *  @return [Fixnum] The number of bytes written.
+ *  @see http://api.libssh.org/stable/group__libssh__channel.html
+ *    ssh_channel_write
+ */
 static VALUE m_write(VALUE self, VALUE data) {
   ChannelHolder *holder;
   struct nogvl_write_args args;
@@ -312,6 +395,14 @@ static void *nogvl_send_eof(void *ptr) {
   return NULL;
 }
 
+/*
+ * @overload send_eof
+ *  Send EOF on the channel.
+ *  @since 0.1.0
+ *  @return [nil]
+ *  @see http://api.libssh.org/stable/group__libssh__channel.html
+ *    ssh_channel_send_eof
+ */
 static VALUE m_send_eof(VALUE self) {
   ChannelHolder *holder;
   struct nogvl_channel_args args;

data/ext/libssh_ruby/key.c

@@ -41,6 +41,13 @@ KeyHolder *libssh_ruby_key_holder(VALUE key) {
   return holder;
 }
 
+/*
+ * @overload sha1
+ *  Return the hash in SHA1 form.
+ *  @since 0.1.0
+ *  @return [String]
+ *  @see http://api.libssh.org/stable/group__libssh__pki.html
+ */
 static VALUE m_sha1(VALUE self) {
   KeyHolder *holder;
   unsigned char *c_hash;
@@ -55,19 +62,48 @@ static VALUE m_sha1(VALUE self) {
   return hash;
 }
 
+/*
+ * @overload type
+ *  Return the type of a SSH key.
+ *  @since 0.1.0
+ *  @return [Fixnum]
+ *  @see http://api.libssh.org/stable/group__libssh__pki.html ssh_key_type
+ */
 static VALUE m_type(VALUE self) {
   return INT2FIX(ssh_key_type(libssh_ruby_key_holder(self)->key));
 }
 
+/*
+ * @overload type_str
+ *  Return the type of a SSH key in string format.
+ *  @since 0.1.0
+ *  @return [String]
+ *  @see http://api.libssh.org/stable/group__libssh__pki.html ssh_key_type and
+ *    ssh_key_type_to_char
+ */
 static VALUE m_type_str(VALUE self) {
   return rb_str_new_cstr(
       ssh_key_type_to_char(ssh_key_type(libssh_ruby_key_holder(self)->key)));
 }
 
+/*
+ * @overload public?
+ *  Check if the key is a public key.
+ *  @since 0.1.0
+ *  @return [Boolean]
+ *  @see http://api.libssh.org/stable/group__libssh__pki.html ssh_key_is_public
+ */
 static VALUE m_public_p(VALUE self) {
   return ssh_key_is_public(libssh_ruby_key_holder(self)->key) ? Qtrue : Qfalse;
 }
 
+/*
+ * @overload private?
+ *  Check if the key is a private key.
+ *  @since 0.1.0
+ *  @return [Boolean]
+ *  @see http://api.libssh.org/stable/group__libssh__pki.html ssh_key_is_private
+ */
 static VALUE m_private_p(VALUE self) {
   return ssh_key_is_private(libssh_ruby_key_holder(self)->key) ? Qtrue : Qfalse;
 }

data/ext/libssh_ruby/libssh_ruby.c

@@ -2,6 +2,29 @@
 
 VALUE rb_mLibSSH;
 
+/*
+ * @overload version(req_version = 0)
+ *  When +req_version+ is given, check if libssh is the required version.
+ *  When +req_version+ isn't given, return the libssh version string.
+ *
+ *  @since 0.2.0
+ *  @param [Fixnum] req_version The version required.
+ *  @return [String, nil] The libssh version string if it's newer than
+ *    +req_version+ .
+ *  @see http://api.libssh.org/stable/group__libssh__misc.html
+ */
+static VALUE m_version(int argc, VALUE *argv, RB_UNUSED_VAR(VALUE self)) {
+  VALUE req_version;
+  int c_req_version = 0;
+
+  rb_scan_args(argc, argv, "01", &req_version);
+  if (!NIL_P(req_version)) {
+    Check_Type(req_version, T_FIXNUM);
+    c_req_version = FIX2INT(req_version);
+  }
+  return rb_str_new_cstr(ssh_version(c_req_version));
+}
+
 void Init_libssh_ruby(void) {
   rb_mLibSSH = rb_define_module("LibSSH");
 #define SERVER(name) \
@@ -20,8 +43,23 @@ void Init_libssh_ruby(void) {
   AUTH(AGAIN);
 #undef AUTH
 
+  rb_define_const(rb_mLibSSH, "LIBSSH_VERSION_MAJOR",
+                  INT2FIX(LIBSSH_VERSION_MAJOR));
+  rb_define_const(rb_mLibSSH, "LIBSSH_VERSION_MINOR",
+                  INT2FIX(LIBSSH_VERSION_MINOR));
+  rb_define_const(rb_mLibSSH, "LIBSSH_VERSION_MICRO",
+                  INT2FIX(LIBSSH_VERSION_MICRO));
+  rb_define_const(rb_mLibSSH, "LIBSSH_VERSION_INT",
+                  INT2FIX(LIBSSH_VERSION_INT));
+  rb_define_const(rb_mLibSSH, "LIBSSH_VERSION",
+                  rb_str_new_cstr(SSH_STRINGIFY(LIBSSH_VERSION)));
+
+  rb_define_singleton_method(rb_mLibSSH, "version", RUBY_METHOD_FUNC(m_version),
+                             -1);
+
   Init_libssh_session();
   Init_libssh_channel();
   Init_libssh_error();
   Init_libssh_key();
+  Init_libssh_scp();
 }

data/ext/libssh_ruby/libssh_ruby.h

@@ -15,6 +15,7 @@ void Init_libssh_session(void);
 void Init_libssh_channel(void);
 void Init_libssh_error(void);
 void Init_libssh_key(void);
+void Init_libssh_scp(void);
 
 void libssh_ruby_raise(ssh_session session);