libssh 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f05291298150e6683ac9b6647515440e7dafe6a7
-  data.tar.gz: 9c174e89993c04dee954032011fdf13987947bfa
+  metadata.gz: 639bee53286516a176e3e46c5646a93593405f3e
+  data.tar.gz: e934c062774b730c8a35a4b69ea075f9389af9d1
 SHA512:
-  metadata.gz: 4760b23e84edef76e93604c38a0903bbf04ea682652754c5df1029fb21b688cf728acf5fa211253827884002612a1a5a038d7f33ff8c10e91c8b60b181c11396
-  data.tar.gz: 82a03d32630272ddd632527ba70e83daa87b2a84af5d35aa8cee8a8ff83947e9ed241b6ed2d7363e62f6871342a66c5041ad5b2110a0f25e17e536d1aad9b90b
+  metadata.gz: 6e1596553a20bb479ebb3878fc1a2dbb968bbf9eb3fb3a4c6308ec85ce2e34ddd52770584b85764a8fde72260fb4ddec5da926923ae4a5da1e137d91fe1147b2
+  data.tar.gz: 4ba23660ed50cb0193df4bdac73134138fcb2dfe6bef6c84c00c4b883d81db8bc2ccd2f6b8ac3bb37e9281efb33b22a0bfde564b33b8ef7ce792063d0eb9cf31

data/.gitignore

@@ -12,3 +12,7 @@
 *.o
 *.a
 mkmf.log
+
+spec/examples.txt
+spec/known_hosts.valid
+spec/known_hosts.invalid

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.rubocop.yml

@@ -3,20 +3,19 @@ inherit_from: .rubocop_todo.yml
 AllCops:
   DisplayCopNames: true
 
-Metrics/AbcSize:
-  Enabled: false
-Metrics/ClassLength:
-  Enabled: false
-Metrics/CyclomaticComplexity:
-  Enabled: false
-Metrics/LineLength:
-  Enabled: false
-Metrics/MethodLength:
+Style/Documentation:
+  Exclude:
+    - 'lib/libssh/key.rb' # Documented in ext
+    - 'spec/**'
+
+Metrics:
   Enabled: false
 
 Style/GlobalVars:
   Exclude:
     - 'ext/libssh_ruby/extconf.rb'
+Style/GuardClause:
+  Enabled: false
 Style/HashSyntax:
   Exclude:
     - 'Rakefile'

data/.rubocop_todo.yml

@@ -1,7 +0,0 @@
-Style/Documentation:
-  Exclude:
-    - 'spec/**/*'
-    - 'test/**/*'
-    - 'lib/libssh.rb'
-    - 'lib/libssh/key.rb'
-    - 'lib/sshkit/backends/libssh.rb'

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 0.3.0 (2016-02-06)
+- Add wrapper methods
+    - `Session#fd`
+    - `Session#read_nonblocking`
+    - `Session#disconnect`
+- Make `Channel#get_exit_status` and `Channel#open_session` interruptible
+- More documentations
+- Add integration test
+
 ## 0.2.0 (2016-01-30)
 - Add many wrapper methods
 - Support `upload!` and `download!` as SSHKit backend.

data/Rakefile

@@ -1,5 +1,6 @@
 require 'bundler/gem_tasks'
 require 'rake/extensiontask'
+require 'rspec/core/rake_task'
 
 task :build => :compile
 
@@ -7,4 +8,11 @@ Rake::ExtensionTask.new('libssh_ruby') do |ext|
   ext.lib_dir = 'lib/libssh'
 end
 
-task :default => [:clobber, :compile]
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => [:clobber, :compile, :docker, :spec]
+
+desc 'Build docker image for integration test'
+task :docker do
+  sh 'docker build -t libssh-ruby spec'
+end

data/example/exec.rb

@@ -1,5 +1,6 @@
 #!/usr/bin/env ruby
 require 'libssh'
+require 'io/wait'
 
 GC.stress = true
 puts "libssh #{LibSSH::LIBSSH_VERSION}"
@@ -38,17 +39,28 @@ end
 bufsiz = 16384
 
 channel = LibSSH::Channel.new(session)
+io = IO.for_fd(session.fd, autoclose: false)
 channel.open_session do
   channel.request_exec('ps auxf')
   until channel.eof?
-    stdout_avail = channel.poll(timeout: 1)
-    if stdout_avail && stdout_avail > 0
-      $stdout.write(channel.read(bufsiz))
+    io.wait_readable
+
+    loop do
+      out = channel.read_nonblocking(bufsiz)
+      if out && !out.empty?
+        $stdout.write(out)
+      else
+        break
+      end
     end
 
-    stderr_avail = channel.poll(stderr: true, timeout: 1)
-    if stderr_avail && stderr_avail > 0
-      $stderr.write(channel.read(bufsiz, stderr: true))
+    loop do
+      err = channel.read_nonblocking(bufsiz, true)
+      if err && !err.empty?
+        $stderr.write(err)
+      else
+        break
+      end
     end
   end
 end

data/ext/libssh_ruby/channel.c

@@ -57,6 +57,12 @@ static size_t channel_memsize(RB_UNUSED_VAR(const void *arg)) {
   return sizeof(ChannelHolder);
 }
 
+/* @overload initialize(session)
+ *  Initialize a channel from the session.
+ *  @param [Session] session
+ *  @see http://api.libssh.org/stable/group__libssh__channel.html
+ *    ssh_channel_new
+ */
 static VALUE m_initialize(VALUE self, VALUE session) {
   ChannelHolder *holder;
   SessionHolder *session_holder;
@@ -83,7 +89,6 @@ static void *nogvl_close(void *ptr) {
 /*
  * @overload close
  *  Close a channel.
- *  @since 0.1.0
  *  @return [nil]
  *  @see http://api.libssh.org/stable/group__libssh__channel.html
  *    ssh_channel_close
@@ -100,16 +105,37 @@ static VALUE m_close(VALUE self) {
   return Qnil;
 }
 
+static void select_session(ssh_session session) {
+  fd_set fds;
+  int fd;
+
+  FD_ZERO(&fds);
+  fd = ssh_get_fd(session);
+  FD_SET(fd, &fds);
+  select(fd + 1, &fds, NULL, NULL, NULL);
+}
+
 static void *nogvl_open_session(void *ptr) {
   struct nogvl_channel_args *args = ptr;
-  args->rc = ssh_channel_open_session(args->channel);
+  ssh_session session = ssh_channel_get_session(args->channel);
+  int blocking = ssh_is_blocking(session);
+
+  ssh_set_blocking(session, 0);
+  while (1) {
+    args->rc = ssh_channel_open_session(args->channel);
+    if (args->rc != SSH_AGAIN) {
+      break;
+    }
+    rb_thread_check_ints();
+    select_session(session);
+  }
+  ssh_set_blocking(session, blocking);
   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
@@ -120,6 +146,11 @@ static VALUE m_open_session(VALUE self) {
   struct nogvl_channel_args args;
 
   TypedData_Get_Struct(self, ChannelHolder, &channel_type, holder);
+  /* When ssh_channel_open_session is called before ssh_connect, libssh would
+   * crash :-< */
+  if (!ssh_is_connected(ssh_channel_get_session(holder->channel))) {
+    rb_raise(rb_eArgError, "Session isn't connected");
+  }
   args.channel = holder->channel;
   rb_thread_call_without_gvl(nogvl_open_session, &args, RUBY_UBF_IO, NULL);
   RAISE_IF_ERROR(args.rc);
@@ -147,7 +178,6 @@ static void *nogvl_request_exec(void *ptr) {
 /*
  * @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
@@ -174,7 +204,6 @@ static void *nogvl_request_pty(void *ptr) {
 /*
  * @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
@@ -209,7 +238,6 @@ static void *nogvl_read(void *ptr) {
 /*
  * @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.
@@ -250,10 +278,62 @@ static VALUE m_read(int argc, VALUE *argv, VALUE self) {
   return ret;
 }
 
+struct nogvl_read_nonblocking_args {
+  ssh_channel channel;
+  char *buf;
+  uint32_t count;
+  int is_stderr;
+  int rc;
+};
+
+static void *nogvl_read_nonblocking(void *ptr) {
+  struct nogvl_read_nonblocking_args *args = ptr;
+  args->rc = ssh_channel_read_nonblocking(args->channel, args->buf, args->count,
+                                          args->is_stderr);
+  return NULL;
+}
+
+/*
+ * @overload read_nonblocking(count, is_stderr = false)
+ *  Do a nonblocking read on the channel.
+ *  @param [Fixnum] count The count of bytes to be read.
+ *  @param [Boolean] is_stderr Read from the stderr flow or not.
+ *  @return [String, nil] Data read from the channel. +nil+ on EOF.
+ *  @since 0.3.0
+ *  @see http://api.libssh.org/stable/group__libssh__channel.html
+ *    ssh_channel_read_nonblocking
+ */
+static VALUE m_read_nonblocking(int argc, VALUE *argv, VALUE self) {
+  ChannelHolder *holder;
+  VALUE count, is_stderr;
+  struct nogvl_read_nonblocking_args args;
+  VALUE ret;
+
+  TypedData_Get_Struct(self, ChannelHolder, &channel_type, holder);
+  args.channel = holder->channel;
+  rb_scan_args(argc, argv, "11", &count, &is_stderr);
+  Check_Type(count, T_FIXNUM);
+  args.count = FIX2UINT(count);
+  if (is_stderr == Qundef) {
+    args.is_stderr = 0;
+  } else {
+    args.is_stderr = RTEST(is_stderr) ? 1 : 0;
+  }
+  args.buf = ALLOC_N(char, args.count);
+  rb_thread_call_without_gvl(nogvl_read_nonblocking, &args, RUBY_UBF_IO, NULL);
+
+  if (args.rc == SSH_EOF) {
+    ret = Qnil;
+  } else {
+    ret = rb_utf8_str_new(args.buf, args.rc);
+  }
+  ruby_xfree(args.buf);
+  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
@@ -282,7 +362,6 @@ static void *nogvl_poll(void *ptr) {
 /*
  * @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.
@@ -326,14 +405,25 @@ static VALUE m_poll(int argc, VALUE *argv, VALUE self) {
 
 static void *nogvl_get_exit_status(void *ptr) {
   struct nogvl_channel_args *args = ptr;
-  args->rc = ssh_channel_get_exit_status(args->channel);
+  ssh_session session = ssh_channel_get_session(args->channel);
+  int blocking = ssh_is_blocking(session);
+
+  ssh_set_blocking(session, 0);
+  while (1) {
+    args->rc = ssh_channel_get_exit_status(args->channel);
+    if (args->rc != SSH_ERROR) {
+      break;
+    }
+    rb_thread_check_ints();
+    select_session(session);
+  }
+  ssh_set_blocking(session, blocking);
   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
@@ -369,7 +459,6 @@ static void *nogvl_write(void *ptr) {
 /*
  * @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
@@ -398,7 +487,6 @@ static void *nogvl_send_eof(void *ptr) {
 /*
  * @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
@@ -414,6 +502,14 @@ static VALUE m_send_eof(VALUE self) {
   return Qnil;
 }
 
+/*
+ * Document-class: LibSSH::Channel
+ * Wrapper for ssh_channel struct in libssh.
+ *
+ * @since 0.1.0
+ * @see http://api.libssh.org/stable/group__libssh__channel.html
+ */
+
 void Init_libssh_channel(void) {
   rb_cLibSSHChannel = rb_define_class_under(rb_mLibSSH, "Channel", rb_cObject);
   rb_define_alloc_func(rb_cLibSSHChannel, channel_alloc);
@@ -428,6 +524,8 @@ void Init_libssh_channel(void) {
   rb_define_method(rb_cLibSSHChannel, "request_pty",
                    RUBY_METHOD_FUNC(m_request_pty), 0);
   rb_define_method(rb_cLibSSHChannel, "read", RUBY_METHOD_FUNC(m_read), -1);
+  rb_define_method(rb_cLibSSHChannel, "read_nonblocking",
+                   RUBY_METHOD_FUNC(m_read_nonblocking), -1);
   rb_define_method(rb_cLibSSHChannel, "poll", RUBY_METHOD_FUNC(m_poll), -1);
   rb_define_method(rb_cLibSSHChannel, "eof?", RUBY_METHOD_FUNC(m_eof_p), 0);
   rb_define_method(rb_cLibSSHChannel, "get_exit_status",

data/ext/libssh_ruby/error.c

@@ -3,10 +3,22 @@
 VALUE rb_eLibSSHError;
 ID id_code;
 
+/*
+ * Document-class: LibSSH::Error
+ * Error returned from libssh.
+ *
+ * @since 0.1.0
+ * @see http://api.libssh.org/stable/group__libssh__error.html
+ *
+ * @!attribute [r] code
+ *  Error code returned from libssh.
+ *  @return [Fixnum]
+ */
+
 void Init_libssh_error(void) {
   rb_eLibSSHError =
       rb_define_class_under(rb_mLibSSH, "Error", rb_eStandardError);
-  id_code = rb_intern("code");
+  id_code = rb_intern("@code");
 
   rb_define_attr(rb_eLibSSHError, "code", 1, 0);
 }

data/ext/libssh_ruby/key.c

@@ -28,6 +28,11 @@ static size_t key_memsize(RB_UNUSED_VAR(const void *arg)) {
   return sizeof(KeyHolder);
 }
 
+/*
+ * @overload initialize
+ *  Initialize an empty key.
+ *  @see http://api.libssh.org/stable/group__libssh__pki.html ssh_key_new
+ */
 static VALUE m_initialize(VALUE self) {
   KeyHolder *holder;
   TypedData_Get_Struct(self, KeyHolder, &key_type, holder);
@@ -44,7 +49,6 @@ KeyHolder *libssh_ruby_key_holder(VALUE key) {
 /*
  * @overload sha1
  *  Return the hash in SHA1 form.
- *  @since 0.1.0
  *  @return [String]
  *  @see http://api.libssh.org/stable/group__libssh__pki.html
  */
@@ -65,7 +69,6 @@ static VALUE m_sha1(VALUE self) {
 /*
  * @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
  */
@@ -76,7 +79,6 @@ static VALUE m_type(VALUE self) {
 /*
  * @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
@@ -89,7 +91,6 @@ static VALUE m_type_str(VALUE self) {
 /*
  * @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
  */
@@ -100,7 +101,6 @@ static VALUE m_public_p(VALUE self) {
 /*
  * @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
  */
@@ -108,6 +108,14 @@ static VALUE m_private_p(VALUE self) {
   return ssh_key_is_private(libssh_ruby_key_holder(self)->key) ? Qtrue : Qfalse;
 }
 
+/*
+ * Document-class: LibSSH::Key
+ * Wrapper for ssh_key struct in libssh.
+ *
+ * @since 0.1.0
+ * @see http://api.libssh.org/stable/group__libssh__pki.html
+ */
+
 void Init_libssh_key(void) {
   rb_cLibSSHKey = rb_define_class_under(rb_mLibSSH, "Key", rb_cObject);
   rb_define_alloc_func(rb_cLibSSHKey, key_alloc);

data/ext/libssh_ruby/libssh_ruby.c

@@ -27,30 +27,44 @@ static VALUE m_version(int argc, VALUE *argv, RB_UNUSED_VAR(VALUE self)) {
 
 void Init_libssh_ruby(void) {
   rb_mLibSSH = rb_define_module("LibSSH");
-#define SERVER(name) \
-  rb_define_const(rb_mLibSSH, "SERVER_" #name, INT2FIX(SSH_SERVER_##name))
-  SERVER(KNOWN_OK);
-  SERVER(KNOWN_CHANGED);
-  SERVER(FOUND_OTHER);
-  SERVER(NOT_KNOWN);
-  SERVER(FILE_NOT_FOUND);
-#undef SERVER
-#define AUTH(name) \
-  rb_define_const(rb_mLibSSH, "AUTH_" #name, INT2FIX(SSH_AUTH_##name))
-  AUTH(DENIED);
-  AUTH(PARTIAL);
-  AUTH(SUCCESS);
-  AUTH(AGAIN);
-#undef AUTH
 
+  /* @see Session#server_known */
+  rb_define_const(rb_mLibSSH, "SERVER_KNOWN_OK", INT2FIX(SSH_SERVER_KNOWN_OK));
+  /* @see Session#server_known */
+  rb_define_const(rb_mLibSSH, "SERVER_KNOWN_CHANGED",
+                  INT2FIX(SSH_SERVER_KNOWN_CHANGED));
+  /* @see Session#server_known */
+  rb_define_const(rb_mLibSSH, "SERVER_FOUND_OTHER",
+                  INT2FIX(SSH_SERVER_FOUND_OTHER));
+  /* @see Session#server_known */
+  rb_define_const(rb_mLibSSH, "SERVER_NOT_KNOWN",
+                  INT2FIX(SSH_SERVER_NOT_KNOWN));
+  /* @see Session#server_known */
+  rb_define_const(rb_mLibSSH, "SERVER_FILE_NOT_FOUND",
+                  INT2FIX(SSH_SERVER_FILE_NOT_FOUND));
+
+  /* Return value that indicates an authentication failure. */
+  rb_define_const(rb_mLibSSH, "AUTH_DENIED", INT2FIX(SSH_AUTH_DENIED));
+  /* Return value that indicates a partially authenticated. */
+  rb_define_const(rb_mLibSSH, "AUTH_PARTIAL", INT2FIX(SSH_AUTH_PARTIAL));
+  /* Return value that indicates a successful authentication. */
+  rb_define_const(rb_mLibSSH, "AUTH_SUCCESS", INT2FIX(SSH_AUTH_SUCCESS));
+  /* Return value that indicates EAGAIN in nonblocking mode. */
+  rb_define_const(rb_mLibSSH, "AUTH_AGAIN", INT2FIX(SSH_AUTH_AGAIN));
+
+  /* Major version defined in header. */
   rb_define_const(rb_mLibSSH, "LIBSSH_VERSION_MAJOR",
                   INT2FIX(LIBSSH_VERSION_MAJOR));
+  /* Minor version defined in header. */
   rb_define_const(rb_mLibSSH, "LIBSSH_VERSION_MINOR",
                   INT2FIX(LIBSSH_VERSION_MINOR));
+  /* Micro version defined in header. */
   rb_define_const(rb_mLibSSH, "LIBSSH_VERSION_MICRO",
                   INT2FIX(LIBSSH_VERSION_MICRO));
+  /* Major version defined in header. */
   rb_define_const(rb_mLibSSH, "LIBSSH_VERSION_INT",
                   INT2FIX(LIBSSH_VERSION_INT));
+  /* String version defined in header. */
   rb_define_const(rb_mLibSSH, "LIBSSH_VERSION",
                   rb_str_new_cstr(SSH_STRINGIFY(LIBSSH_VERSION)));
 

data/ext/libssh_ruby/scp.c

@@ -54,7 +54,6 @@ static size_t scp_memsize(RB_UNUSED_VAR(const void *arg)) {
 
 /* @overload initialize(session, mode, path)
  *  Create a new scp session.
- *  @since 0.2.0
  *  @param [Session] session The SSH session to use.
  *  @param [Symbol] mode +:read+ or +:write+.
  *  @param [String] path The directory in which write or read will be done.
@@ -99,7 +98,6 @@ static void *nogvl_close(void *ptr) {
 
 /* @overload close
  *  Close the scp channel.
- *  @since 0.2.0
  *  @return [nil]
  *  @see http://api.libssh.org/stable/group__libssh__scp.html ssh_scp_close
  */
@@ -123,7 +121,6 @@ static void *nogvl_init(void *ptr) {
 
 /* @overload init
  *  Initialize the scp channel.
- *  @since 0.2.0
  *  @yieldparam [Scp] scp self
  *  @return [Object] Return value of the block
  *  @see http://api.libssh.org/stable/group__libssh__scp.html ssh_scp_init
@@ -157,7 +154,6 @@ static void *nogvl_push_file(void *ptr) {
 
 /* @overload push_file(filename, size, mode)
  *  Initialize the sending of a file to a scp in sink mode.
- *  @since 0.2.0
  *  @param [String] filename The name of the file being sent.
  *  @param [Integer] size Exact size in bytes of the file being sent.
  *  @param [Fixnum] mode The UNIX permissions for the new file.
@@ -194,7 +190,6 @@ static void *nogvl_write(void *ptr) {
 
 /* @overload write(data)
  *  Write into a remote scp file.
- *  @since 0.2.0
  *  @param [String] data The data to write.
  *  @return [nil]
  *  @see http://api.libssh.org/stable/group__libssh__scp.html ssh_scp_write
@@ -221,7 +216,6 @@ static void *nogvl_pull_request(void *ptr) {
 
 /* @overload pull_request
  *  Wait for a scp request.
- *  @since 0.2.0
  *  @return [Fixnum]
  *    REQUEST_NEWFILE: The other side is sending a file.
  *    REQUEST_NEWDIR: The other side is sending a directory.
@@ -244,7 +238,6 @@ static VALUE m_pull_request(VALUE self) {
 
 /* @overload request_size
  *  Get the size of the file being pushed from the other party.
- *  @since 0.2.0
  *  @return [Integer] The numeric size of the file being read.
  *  @see http://api.libssh.org/stable/group__libssh__scp.html
  *    ssh_scp_request_get_size64
@@ -260,7 +253,6 @@ static VALUE m_request_size(VALUE self) {
 
 /* @overload request_filename
  *  Get the name of the directory or file being pushed from the other party.
- *  @since 0.2.0
  *  @return [String, nil] The filename. +nil+ on error.
  *  @see http://api.libssh.org/stable/group__libssh__scp.html
  *    ssh_scp_request_get_filename
@@ -281,7 +273,6 @@ static VALUE m_request_filename(VALUE self) {
 /* @overload request_permissions
  *  Get the permissions of the directory or file being pushed from the other
  *  party.
- *  @since 0.2.0
  *  @return [Fixnum] The UNIX permissions.
  *  @see http://api.libssh.org/stable/group__libssh__scp.html
  *    ssh_scp_request_get_permissions
@@ -305,7 +296,6 @@ static void *nogvl_accept_request(void *ptr) {
 /* @overload accept_request
  *  Accepts transfer of a file or creation of a directory coming from the remote
  *  party.
- *  @since 0.2.0
  *  @return [nil]
  *  @see http://api.libssh.org/stable/group__libssh__scp.html
  *    ssh_scp_accept_request
@@ -336,7 +326,6 @@ static void *nogvl_deny_request(void *ptr) {
 /* @overload deny_request
  *  Deny the transfer of a file or creation of a directory coming from the
  *  remote party.
- *  @since 0.2.0
  *  @return [nil]
  *  @see http://api.libssh.org/stable/group__libssh__scp.html
  *    ssh_scp_deny_request
@@ -368,7 +357,6 @@ static void *nogvl_read(void *ptr) {
 
 /* @overload read(size)
  *  Read from a remote scp file.
- *  @since 0.2.0
  *  @param [Fixnum] The size of the buffer.
  *  @return [String]
  *  @see http://api.libssh.org/stable/group__libssh__scp.html ssh_scp_read
@@ -396,7 +384,6 @@ static VALUE m_read(VALUE self, VALUE size) {
 
 /* @overload request_warning
  *  Get the warning string.
- *  @since 0.2.0
  *  @return [String, nil] A warning string. +nil+ on error.
  *  @see http://api.libssh.org/stable/group__libssh__scp.html
  *    ssh_scp_request_get_warning
@@ -414,18 +401,30 @@ static VALUE m_request_warning(VALUE self) {
   }
 }
 
+/* Document-class: LibSSH::Scp
+ * Wrapper for ssh_scp struct in libssh.
+ *
+ * @since 0.2.0
+ * @see http://api.libssh.org/stable/group__libssh__scp.html
+ */
+
 void Init_libssh_scp(void) {
   rb_cLibSSHScp = rb_define_class_under(rb_mLibSSH, "Scp", rb_cObject);
   rb_define_alloc_func(rb_cLibSSHScp, scp_alloc);
 
+  /* @see #pull_request */
   rb_define_const(rb_cLibSSHScp, "REQUEST_NEWFILE",
                   INT2FIX(SSH_SCP_REQUEST_NEWFILE));
+  /* @see #pull_request */
   rb_define_const(rb_cLibSSHScp, "REQUEST_NEWDIR",
                   INT2FIX(SSH_SCP_REQUEST_NEWDIR));
+  /* @see #pull_request */
   rb_define_const(rb_cLibSSHScp, "REQUEST_ENDDIR",
                   INT2FIX(SSH_SCP_REQUEST_ENDDIR));
+  /* @see #pull_request */
   rb_define_const(rb_cLibSSHScp, "REQUEST_WARNING",
                   INT2FIX(SSH_SCP_REQUEST_WARNING));
+  /* @see #pull_request */
   rb_define_const(rb_cLibSSHScp, "REQUEST_EOF", INT2FIX(SSH_SCP_REQUEST_EOF));
 
   rb_define_method(rb_cLibSSHScp, "initialize", RUBY_METHOD_FUNC(m_initialize),

data/ext/libssh_ruby/session.c

@@ -49,6 +49,11 @@ static size_t session_memsize(RB_UNUSED_VAR(const void *arg)) {
   return sizeof(SessionHolder);
 }
 
+/*
+ * @overload initialize
+ * Create a new SSH session.
+ * @see http://api.libssh.org/stable/group__libssh__session.html ssh_new
+ */
 static VALUE m_initialize(VALUE self) {
   SessionHolder *holder;
 
@@ -60,10 +65,10 @@ static VALUE m_initialize(VALUE self) {
 /*
  * @overload log_verbosity=(verbosity)
  *  Set the session logging verbosity.
- *  @since 0.1.0
  *  @param [Symbol] verbosity +:none+, +:warn+, +:info+, +:debug+, or +:trace+.
  *  @return [nil]
- *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_set(SSH_OPTIONS_LOG_VERBOSITY)
+ *  @see http://api.libssh.org/stable/group__libssh__session.html
+ *    ssh_options_set(SSH_OPTIONS_LOG_VERBOSITY)
  */
 static VALUE m_set_log_verbosity(VALUE self, VALUE verbosity) {
   ID id_verbosity;
@@ -104,7 +109,6 @@ static VALUE set_string_option(VALUE self, enum ssh_options_e type, VALUE str) {
 /*
  * @overload host=(host)
  *  Set the hostname or IP address to connect to.
- *  @since 0.1.0
  *  @param [String] host
  *  @return [nil]
  *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_set(SSH_OPTIONS_HOST)
@@ -289,8 +293,8 @@ static VALUE m_set_hostkeys(VALUE self, VALUE hostkeys) {
  */
 static VALUE m_set_compression(VALUE self, VALUE compression) {
   SessionHolder *holder;
-  char *val;
   if (compression == Qtrue || compression == Qfalse) {
+    const char *val;
     if (compression == Qtrue) {
       val = "yes";
     } else {
@@ -384,7 +388,6 @@ static VALUE m_set_gssapi_delegate_credentials(VALUE self, VALUE enable) {
 /*
  * @overload parse_config(path = nil)
  *  Parse the ssh_config file.
- *  @since 0.1.0
  *  @param [String, nil] Path to ssh_config. If +nil+, the default ~/.ssh/config will be used.
  *  @return [Boolean] Parsing the ssh_config was successful or not.
  *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_parse_config
@@ -413,7 +416,6 @@ static VALUE m_parse_config(int argc, VALUE *argv, VALUE self) {
 /*
  * @overload add_identity(path_format)
  *  Add the identity file name format.
- *  @since 0.1.0
  *  @param [String] path_format Format string for identity file.
  *  @return [nil]
  *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_options_set(SSH_OPTIONS_ADD_IDENTITY)
@@ -442,7 +444,6 @@ static void *nogvl_connect(void *ptr) {
 /*
  * @overload connect
  *  Connect to the SSH server.
- *  @since 0.1.0
  *  @return [nil]
  *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_connect
  */
@@ -458,10 +459,34 @@ static VALUE m_connect(VALUE self) {
   return Qnil;
 }
 
+static void *nogvl_disconnect(void *ptr) {
+  struct nogvl_session_args *args = ptr;
+  ssh_disconnect(args->session);
+  args->rc = 0;
+  return NULL;
+}
+
+/*
+ * @overload disconnect
+ *  Disconnect from a session.
+ *  @return [nil]
+ *  @since 0.3.0
+ *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_disconnect
+ */
+static VALUE m_disconnect(VALUE self) {
+  SessionHolder *holder;
+  struct nogvl_session_args args;
+
+  TypedData_Get_Struct(self, SessionHolder, &session_type, holder);
+  args.session = holder->session;
+  rb_thread_call_without_gvl(nogvl_disconnect, &args, RUBY_UBF_IO, NULL);
+
+  return Qnil;
+}
+
 /*
  * @overload server_known
  *  Check if the server is knonw.
- *  @since 0.1.0
  *  @return [Fixnum]
  *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_is_server_known
  */
@@ -475,10 +500,22 @@ static VALUE m_server_known(VALUE self) {
   return INT2FIX(rc);
 }
 
+/*
+ * @overload fd
+ * Get the fd of a connection
+ * @return [Fixnum]
+ * @since 0.3.0
+ * @see http://api.libssh.org/stable/group__libssh__session.html ssh_get_fd
+ */
+static VALUE m_fd(VALUE self) {
+  SessionHolder *holder;
+  TypedData_Get_Struct(self, SessionHolder, &session_type, holder);
+  return INT2FIX(ssh_get_fd(holder->session));
+}
+
 /*
  * @overload userauth_none
  *  Try to authenticate through then "none" method.
- *  @since 0.1.0
  *  @return [Fixnum]
  *  @see http://api.libssh.org/stable/group__libssh__auth.html ssh_userauth_none
  */
@@ -495,7 +532,6 @@ static VALUE m_userauth_none(VALUE self) {
 /*
  * @overload userauth_list
  *  Get available authentication methods from the server.
- *  @since 0.1.0
  *  @return [Array<Symbol>]
  *  @see http://api.libssh.org/stable/group__libssh__auth.html ssh_userauth_list
  */
@@ -539,7 +575,6 @@ static void *nogvl_userauth_publickey_auto(void *ptr) {
 /*
  * @overload userauth_publickey_auto
  *  Try to automatically authenticate with public key and "none".
- *  @since 0.1.0
  *  @return [Fixnum]
  *  @see http://api.libssh.org/stable/group__libssh__auth.html ssh_userauth_publickey_auto
  */
@@ -557,7 +592,6 @@ static VALUE m_userauth_publickey_auto(VALUE self) {
 /*
  * @overload get_publickey
  *  Get the server public key from a session.
- *  @since 0.1.0
  *  @return [Key]
  *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_get_publickey
  */
@@ -576,7 +610,6 @@ static VALUE m_get_publickey(VALUE self) {
 /*
  * @overload write_knownhost
  *  Write the current server as known in the known_hosts file.
- *  @since 0.1.0
  *  @return [nil]
  *  @see http://api.libssh.org/stable/group__libssh__session.html ssh_write_knownhost
  */
@@ -588,6 +621,14 @@ static VALUE m_write_knownhost(VALUE self) {
   return Qnil;
 }
 
+/*
+ * Document-class: LibSSH::Session
+ * Wrapper for ssh_session struct in libssh.
+ *
+ * @since 0.1.0
+ * @see http://api.libssh.org/stable/group__libssh__session.html
+ */
+
 void Init_libssh_session() {
   rb_cLibSSHSession = rb_define_class_under(rb_mLibSSH, "Session", rb_cObject);
   rb_define_alloc_func(rb_cLibSSHSession, session_alloc);
@@ -650,8 +691,12 @@ void Init_libssh_session() {
                    RUBY_METHOD_FUNC(m_add_identity), 1);
   rb_define_method(rb_cLibSSHSession, "connect", RUBY_METHOD_FUNC(m_connect),
                    0);
+  rb_define_method(rb_cLibSSHSession, "disconnect",
+                   RUBY_METHOD_FUNC(m_disconnect), 0);
   rb_define_method(rb_cLibSSHSession, "server_known",
                    RUBY_METHOD_FUNC(m_server_known), 0);
+  rb_define_method(rb_cLibSSHSession, "fd", RUBY_METHOD_FUNC(m_fd), 0);
+
   rb_define_method(rb_cLibSSHSession, "userauth_none",
                    RUBY_METHOD_FUNC(m_userauth_none), 0);
   rb_define_method(rb_cLibSSHSession, "userauth_list",

data/lib/libssh/key.rb

@@ -2,6 +2,10 @@ require 'libssh/libssh_ruby'
 
 module LibSSH
   class Key
+    # Return the hash in SHA1 in hexadecimal notation.
+    # @return [String]
+    # @see #sha1
+    # @since 0.1.0
     def sha1_hex
       sha1.unpack('H*')[0].each_char.each_slice(2).map(&:join).join(':')
     end

data/lib/libssh/version.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
 module LibSSH
-  VERSION = '0.2.0'.freeze
+  # The version of libssh gem.
+  VERSION = '0.3.0'.freeze
 end

data/lib/sshkit/backends/libssh.rb

@@ -1,11 +1,31 @@
 require 'libssh'
+require 'io/wait'
 require 'sshkit/backends/abstract'
 require 'sshkit/backends/connection_pool'
 
+# Namespace of sshkit gem.
 module SSHKit
+  # Namespace of sshkit gem.
   module Backend
+    # SSHKit backend class for libssh.
+    # @since 0.1.0
+    # @see https://github.com/capistrano/sshkit
     class Libssh < Abstract
+      # Configuration class compatible with
+      # {SSHKit::Backend::Netssh::Configuration}.
+      # @since 0.1.0
       class Configuration
+        # @!attribute [rw] pty
+        #   Allocate a PTY or not. Default is +false+.
+        #   @return [Boolean]
+        # @!attribute [rw] connection_timeout
+        #   Connection timeout in second. Default is +30+.
+        #   @return [Fixnum]
+        # @!attribute [rw] ssh_options
+        #   Various options for libssh. Some of them are compatible with
+        #   {SSHKit::Backend::Netssh::Configuration#ssh_options}.
+        #   @todo Describe supported options.
+        #   @return [Hash]
         attr_accessor :pty, :connection_timeout, :ssh_options
 
         def initialize
@@ -19,7 +39,13 @@ module SSHKit
       BUFSIZ = 16384
       private_constant :BUFSIZ
 
-      # @override
+      # Upload a local file to the remote party.
+      # @param [String, #read] local Path to the local file to be uploaded.
+      #   If +local+ responds to +#read+, +local+ is treated as IO-like object.
+      # @param [String] remote Path to the remote file.
+      # @since 0.2.0
+      # @see SSHKit::Backend::Abstract#upload!.
+      # @todo Make +options+ compatible with {SSHKit::Backend::Netssh#upload!}.
       def upload!(local, remote, _options = {})
         with_session do |session|
           scp = LibSSH::Scp.new(session, :write, File.dirname(remote))
@@ -35,7 +61,13 @@ module SSHKit
         end
       end
 
-      # @override
+      # Download a remote file to local.
+      # @param [String] remote Path to the remote file to be downloaded.
+      # @param [String, #write] local Path to the local file.
+      #   If +local+ responds to +#write+, +local+ is treated as IO-like object.
+      # @since 0.2.0
+      # @see SSHKit::Backend::Abstract#download!.
+      # @todo Make +options+ compatible with {SSHKit::Backend::Netssh#download!}.
       def download!(remote, local, _options = {})
         with_session do |session|
           scp = LibSSH::Scp.new(session, :read, remote)
@@ -58,9 +90,13 @@ module SSHKit
       @pool = SSHKit::Backend::ConnectionPool.new
 
       class << self
+        # @!attribute [rw] pool
+        #   Connection pool for libssh.
+        #   @return [SSHKit::Backend::ConnectionPool]
         attr_accessor :pool
 
-        # @override
+        # Global configuration for {SSHKit::Backend::Netssh}.
+        # @return [Configuration]
         def config
           @config ||= Configuration.new
         end
@@ -74,24 +110,33 @@ module SSHKit
 
         with_session do |session|
           channel = LibSSH::Channel.new(session)
+          io = IO.for_fd(session.fd, autoclose: false)
           channel.open_session do
             if Libssh.config.pty
               channel.request_pty
             end
             channel.request_exec(cmd.to_command)
             until channel.eof?
-              stdout_avail = channel.poll(timeout: 1)
-              if stdout_avail && stdout_avail > 0
-                buf = channel.read(BUFSIZ)
-                cmd.on_stdout(channel, buf)
-                output.log_command_data(cmd, :stdout, buf)
+              io.wait_readable
+
+              loop do
+                buf = channel.read_nonblocking(BUFSIZ)
+                if buf && !buf.empty?
+                  cmd.on_stdout(channel, buf)
+                  output.log_command_data(cmd, :stdout, buf)
+                else
+                  break
+                end
               end
 
-              stderr_avail = channel.poll(stderr: true, timeout: 1)
-              if stderr_avail && stderr_avail > 0
-                buf = channel.read(BUFSIZ, stderr: true)
-                cmd.on_stderr(channel, buf)
-                output.log_command_data(cmd, :stderr, buf)
+              loop do
+                buf = channel.read_nonblocking(BUFSIZ, true)
+                if buf && !buf.empty?
+                  cmd.on_stderr(channel, buf)
+                  output.log_command_data(cmd, :stderr, buf)
+                else
+                  break
+                end
               end
             end
 

data/libssh.gemspec

@@ -24,6 +24,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rake-compiler'
+  spec.add_development_dependency 'rspec', '>= 3.0.0'
   spec.add_development_dependency 'rubocop', '>= 0.36.0'
   spec.add_development_dependency 'sshkit'
   spec.add_development_dependency 'yard'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: libssh
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Kohei Suzuki
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-01-30 00:00:00.000000000 Z
+date: 2016-02-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.0
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -104,6 +118,7 @@ extra_rdoc_files: []
 files:
 - ".clang-format"
 - ".gitignore"
+- ".rspec"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
 - ".travis.yml"