sshkit 1.21.7 → 1.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33d280d41b8674934f244cd9a094ebeb3d34dfb0d700fd172f0a3e4ed25ccd01
-  data.tar.gz: 2f75eb42f4ffa10eaa44e1c35fdccc169f334ca4498c1864c414bfad83138a86
+  metadata.gz: 762a819b65ab2b01aee9bdff39037ca0b5f48a0e55b770c922eeee4b0118dcfb
+  data.tar.gz: 31aa61f4e968d345f0ee2c974ecf6761f86b5acb5e1f735e73c2713931f3bf7a
 SHA512:
-  metadata.gz: 4206a3850adb7e7f666e2031dba9681aef7d236e04baac0cd584f07e118babe25cbfdb49efae13419be567ce870f28ccc33d128538e462d2091a76712f9c1b12
-  data.tar.gz: 622f95a26e026ed0842e3bd1759518303145616ed8b8348e0ebe2a8b5bac5a0c0359118258a56b538ada3a30586542c2e6aa29592a86c51b44c4e06719038bce
+  metadata.gz: bd51f4d17794678ac7bc7f6b9c2588a7af76d94a8709414dfb3f2ba492adf1d4da134f4fc93a2a42096ac3fd2b2265a4570e5c6e7b6289c45326eddebec3bd2c
+  data.tar.gz: 88c219aec07643424633efa06bb9e6c3dd8539e651fb42f04cdbcc2cb513ffde40b72c32a460e5cb6893d69d3b7baad062a57246ee90eaac6062bf64f70b8bc5

data/EXAMPLES.md

@@ -121,9 +121,6 @@ on hosts do |host|
 end
 ```
 
-**Note:** The `upload!()` method doesn't honor the values of `as()` etc, this
-will be improved as the library matures, but we're not there yet.
-
 ## Upload a file from a stream
 
 ```ruby
@@ -148,9 +145,6 @@ end
 This spares one from having to figure out the correct escaping sequences for
 something like "echo(:cat, '...?...', '> /etc/sudoers.d/yolo')".
 
-**Note:** The `upload!()` method doesn't honor the values of `within()`, `as()`
-etc, this will be improved as the library matures, but we're not there yet.
-
 ## Upload a directory of files
 
 ```ruby
@@ -160,7 +154,25 @@ end
 ```
 
 In this case the `recursive: true` option mirrors the same options which are
-available to [`Net::{SCP,SFTP}`](http://net-ssh.github.io/net-scp/).
+available to [`Net::SCP`](https://github.com/net-ssh/net-scp) and
+[`Net::SFTP`](https://github.com/net-ssh/net-sftp).
+
+## Set the upload/download method (SCP or SFTP).
+
+SSHKit can use SCP or SFTP for file transfers. The default is SCP, but this can be changed to SFTP per host:
+
+```ruby
+host = SSHKit::Host.new('user@example.com')
+host.transfer_method = :sftp
+```
+
+or globally:
+
+```ruby
+SSHKit::Backend::Netssh.configure do |ssh|
+  ssh.transfer_method = :sftp
+end
+```
 
 ## Setting global SSH options
 
@@ -235,16 +247,16 @@ end
 
 ```ruby
 # The default format is pretty, which outputs colored text
-SSHKit.config.format = :pretty
+SSHKit.config.use_format :pretty
 
 # Text with no coloring
-SSHKit.config.format = :simpletext
+SSHKit.config.use_format :simpletext
 
 # Red / Green dots for each completed step
-SSHKit.config.format = :dot
+SSHKit.config.use_format :dot
 
 # No output
-SSHKit.config.format = :blackhole
+SSHKit.config.use_format :blackhole
 ```
 
 ## Implement a dirt-simple formatter class
@@ -254,7 +266,7 @@ module SSHKit
   module Formatter
     class MyFormatter < SSHKit::Formatter::Abstract
       def write(obj)
-        case obj.is_a? SSHKit::Command
+        if obj.is_a? SSHKit::Command
           # Do something here, see the SSHKit::Command documentation
         end
       end
@@ -263,7 +275,7 @@ module SSHKit
 end
 
 # If your formatter is defined in the SSHKit::Formatter module configure with the format option:
-SSHKit.config.format = :myformatter
+SSHKit.config.use_format :myformatter
 
 # Or configure the output directly
 SSHKit.config.output = MyFormatter.new($stdout)

data/README.md

@@ -68,7 +68,8 @@ you can pass the `strip: false` option: `capture(:ls, '-l', strip: false)`
 ### Transferring files
 
 All backends also support the `upload!` and `download!` methods for transferring files.
-For the remote backend, the file is transferred with scp.
+For the remote backend, the file is transferred with scp by default, but sftp is also
+supported. See [EXAMPLES.md](EXAMPLES.md) for details.
 
 ```ruby
 on '1.example.com' do

data/lib/sshkit/backends/netssh/scp_transfer.rb

@@ -0,0 +1,26 @@
+require "net/scp"
+
+module SSHKit
+  module Backend
+    class Netssh < Abstract
+      class ScpTransfer
+        def initialize(ssh, summarizer)
+          @ssh = ssh
+          @summarizer = summarizer
+        end
+
+        def upload!(local, remote, options)
+          ssh.scp.upload!(local, remote, options, &summarizer)
+        end
+
+        def download!(remote, local, options)
+          ssh.scp.download!(remote, local, options, &summarizer)
+        end
+
+        private
+
+        attr_reader :ssh, :summarizer
+      end
+    end
+  end
+end

data/lib/sshkit/backends/netssh/sftp_transfer.rb

@@ -0,0 +1,46 @@
+require "net/sftp"
+
+module SSHKit
+  module Backend
+    class Netssh < Abstract
+      class SftpTransfer
+        def initialize(ssh, summarizer)
+          @ssh = ssh
+          @summarizer = summarizer
+        end
+
+        def upload!(local, remote, options)
+          options = { progress: self }.merge(options || {})
+          ssh.sftp.connect!
+          ssh.sftp.upload!(local, remote, options)
+        ensure
+          ssh.sftp.close_channel
+        end
+
+        def download!(remote, local, options)
+          options = { progress: self }.merge(options || {})
+          destination = local ? local : StringIO.new.tap { |io| io.set_encoding('BINARY') }
+
+          ssh.sftp.connect!
+          ssh.sftp.download!(remote, destination, options)
+          local ? true : destination.string
+        ensure
+          ssh.sftp.close_channel
+        end
+
+        def on_get(download, entry, offset, data)
+          entry.size ||= download.sftp.file.open(entry.remote) { |file| file.stat.size }
+          summarizer.call(nil, entry.remote, offset + data.bytesize, entry.size)
+        end
+
+        def on_put(_upload, file, offset, data)
+          summarizer.call(nil, file.local, offset + data.bytesize, file.size)
+        end
+
+        private
+
+        attr_reader :ssh, :summarizer
+      end
+    end
+  end
+end

data/lib/sshkit/backends/netssh.rb

@@ -2,7 +2,6 @@ require 'English'
 require 'strscan'
 require 'mutex_m'
 require 'net/ssh'
-require 'net/scp'
 
 module Net
   module SSH
@@ -23,10 +22,27 @@ module SSHKit
   module Backend
 
     class Netssh < Abstract
+      def self.assert_valid_transfer_method!(method)
+        return if [:scp, :sftp].include?(method)
+
+        raise ArgumentError, "#{method.inspect} is not a valid transfer method. Supported methods are :scp, :sftp."
+      end
+
       class Configuration
         attr_accessor :connection_timeout, :pty
+        attr_reader :transfer_method
         attr_writer :ssh_options
 
+        def initialize
+          self.transfer_method = :scp
+        end
+
+        def transfer_method=(method)
+          Netssh.assert_valid_transfer_method!(method)
+
+          @transfer_method = method
+        end
+
         def ssh_options
           default_options.merge(@ssh_options ||= {})
         end
@@ -64,16 +80,16 @@ module SSHKit
       def upload!(local, remote, options = {})
         summarizer = transfer_summarizer('Uploading', options)
         remote = File.join(pwd_path, remote) unless remote.to_s.start_with?("/") || pwd_path.nil?
-        with_ssh do |ssh|
-          ssh.scp.upload!(local, remote, options, &summarizer)
+        with_transfer(summarizer) do |transfer|
+          transfer.upload!(local, remote, options)
         end
       end
 
       def download!(remote, local=nil, options = {})
         summarizer = transfer_summarizer('Downloading', options)
         remote = File.join(pwd_path, remote) unless remote.to_s.start_with?("/") || pwd_path.nil?
-        with_ssh do |ssh|
-          ssh.scp.download!(remote, local, options, &summarizer)
+        with_transfer(summarizer) do |transfer|
+          transfer.download!(remote, local, options)
         end
       end
 
@@ -105,7 +121,7 @@ module SSHKit
         last_percentage = nil
         proc do |_ch, name, transferred, total|
           percentage = (transferred.to_f * 100 / total.to_f)
-          unless percentage.nan?
+          unless percentage.nan? || percentage.infinite?
             message = "#{action} #{name} #{percentage.round(2)}%"
             percentage_r = (percentage / log_percent).truncate * log_percent
             if percentage_r > 0 && (last_name != name || last_percentage != percentage_r)
@@ -183,6 +199,20 @@ module SSHKit
         )
       end
 
+      def with_transfer(summarizer)
+        transfer_method = host.transfer_method || self.class.config.transfer_method
+        transfer_class = if transfer_method == :sftp
+                           require_relative "netssh/sftp_transfer"
+                           SftpTransfer
+                         else
+                           require_relative "netssh/scp_transfer"
+                           ScpTransfer
+                         end
+
+        with_ssh do |ssh|
+          yield(transfer_class.new(ssh, summarizer))
+        end
+      end
     end
   end
 

data/lib/sshkit/host.rb

@@ -7,6 +7,7 @@ module SSHKit
   class Host
 
     attr_accessor :password, :hostname, :port, :user, :ssh_options
+    attr_reader :transfer_method
 
     def key=(new_key)
       @keys = [new_key]
@@ -41,6 +42,12 @@ module SSHKit
       end
     end
 
+    def transfer_method=(method)
+      Backend::Netssh.assert_valid_transfer_method!(method) unless method.nil?
+
+      @transfer_method = method
+    end
+
     def local?
       @local
     end

data/lib/sshkit/version.rb

@@ -1,3 +1,3 @@
 module SSHKit
-  VERSION = "1.21.7".freeze
+  VERSION = "1.22.0".freeze
 end

data/sshkit.gemspec

@@ -23,6 +23,7 @@ Gem::Specification.new do |gem|
   gem.add_runtime_dependency('mutex_m')
   gem.add_runtime_dependency('net-ssh',  '>= 2.8.0')
   gem.add_runtime_dependency('net-scp',  '>= 1.1.2')
+  gem.add_runtime_dependency('net-sftp', '>= 2.1.2')
 
   gem.add_development_dependency('danger')
   gem.add_development_dependency('minitest', '>= 5.0.0')

data/test/functional/backends/netssh_transfer_tests.rb

@@ -0,0 +1,83 @@
+require 'securerandom'
+
+module SSHKit
+  module Backend
+    module NetsshTransferTests
+      def setup
+        super
+        @output = String.new
+        SSHKit.config.output_verbosity = :debug
+        SSHKit.config.output = SSHKit::Formatter::SimpleText.new(@output)
+      end
+
+      def a_host
+        VagrantWrapper.hosts['one']
+      end
+
+      def test_upload_and_then_capture_file_contents
+        actual_file_contents = ""
+        file_name = File.join("/tmp", SecureRandom.uuid)
+        File.open file_name, 'w+' do |f|
+          f.write "Some Content\nWith a newline and trailing spaces    \n "
+        end
+        Netssh.new(a_host) do
+          upload!(file_name, file_name)
+          actual_file_contents = capture(:cat, file_name, strip: false)
+        end.run
+        assert_equal "Some Content\nWith a newline and trailing spaces    \n ", actual_file_contents
+      end
+
+      def test_upload_within
+        file_name = SecureRandom.uuid
+        file_contents = "Some Content"
+        dir_name = SecureRandom.uuid
+        actual_file_contents = ""
+        Netssh.new(a_host) do |_host|
+          within("/tmp") do
+            execute :mkdir, "-p", dir_name
+            within(dir_name) do
+              upload!(StringIO.new(file_contents), file_name)
+            end
+          end
+          actual_file_contents = capture(:cat, "/tmp/#{dir_name}/#{file_name}", strip: false)
+        end.run
+        assert_equal file_contents, actual_file_contents
+      end
+
+      def test_upload_string_io
+        file_contents = ""
+        Netssh.new(a_host) do |_host|
+          file_name = File.join("/tmp", SecureRandom.uuid)
+          upload!(StringIO.new('example_io'), file_name)
+          file_contents = download!(file_name)
+        end.run
+        assert_equal "example_io", file_contents
+      end
+
+      def test_upload_large_file
+        size      = 25
+        fills     = SecureRandom.random_bytes(1024*1024)
+        file_name = "/tmp/file-#{size}.txt"
+        File.open(file_name, 'wb') do |f|
+          (size).times {f.write(fills) }
+        end
+        file_contents = ""
+        Netssh.new(a_host) do
+          upload!(file_name, file_name)
+          file_contents = download!(file_name)
+        end.run
+        assert_equal File.open(file_name, 'rb').read, file_contents
+      end
+
+      def test_upload_via_pathname
+        file_contents = ""
+        Netssh.new(a_host) do |_host|
+          file_name = Pathname.new(File.join("/tmp", SecureRandom.uuid))
+          upload!(StringIO.new('example_io'), file_name)
+          file_contents = download!(file_name)
+        end.run
+        assert_equal "example_io", file_contents
+      end
+    end
+  end
+end

data/test/functional/backends/test_netssh.rb

@@ -1,5 +1,4 @@
 require 'helper'
-require 'securerandom'
 require 'benchmark'
 
 module SSHKit
@@ -136,71 +135,6 @@ module SSHKit
         end.run
       end
 
-      def test_upload_and_then_capture_file_contents
-        actual_file_contents = ""
-        file_name = File.join("/tmp", SecureRandom.uuid)
-        File.open file_name, 'w+' do |f|
-          f.write "Some Content\nWith a newline and trailing spaces    \n "
-        end
-        Netssh.new(a_host) do
-          upload!(file_name, file_name)
-          actual_file_contents = capture(:cat, file_name, strip: false)
-        end.run
-        assert_equal "Some Content\nWith a newline and trailing spaces    \n ", actual_file_contents
-      end
-
-      def test_upload_within
-        file_name = SecureRandom.uuid
-        file_contents = "Some Content"
-        dir_name = SecureRandom.uuid
-        actual_file_contents = ""
-        Netssh.new(a_host) do |_host|
-          within("/tmp") do
-            execute :mkdir, "-p", dir_name
-            within(dir_name) do
-              upload!(StringIO.new(file_contents), file_name)
-            end
-          end
-          actual_file_contents = capture(:cat, "/tmp/#{dir_name}/#{file_name}", strip: false)
-        end.run
-        assert_equal file_contents, actual_file_contents
-      end
-
-      def test_upload_string_io
-        file_contents = ""
-        Netssh.new(a_host) do |_host|
-          file_name = File.join("/tmp", SecureRandom.uuid)
-          upload!(StringIO.new('example_io'), file_name)
-          file_contents = download!(file_name)
-        end.run
-        assert_equal "example_io", file_contents
-      end
-
-      def test_upload_large_file
-        size      = 25
-        fills     = SecureRandom.random_bytes(1024*1024)
-        file_name = "/tmp/file-#{size}.txt"
-        File.open(file_name, 'wb') do |f|
-          (size).times {f.write(fills) }
-        end
-        file_contents = ""
-        Netssh.new(a_host) do
-          upload!(file_name, file_name)
-          file_contents = download!(file_name)
-        end.run
-        assert_equal File.open(file_name, 'rb').read, file_contents
-      end
-
-      def test_upload_via_pathname
-        file_contents = ""
-        Netssh.new(a_host) do |_host|
-          file_name = Pathname.new(File.join("/tmp", SecureRandom.uuid))
-          upload!(StringIO.new('example_io'), file_name)
-          file_contents = download!(file_name)
-        end.run
-        assert_equal "example_io", file_contents
-      end
-
       def test_interaction_handler
         captured_command_result = nil
         Netssh.new(a_host) do

data/test/functional/backends/test_netssh_scp.rb

@@ -0,0 +1,23 @@
+require 'helper'
+require_relative 'netssh_transfer_tests'
+
+module SSHKit
+  module Backend
+    class TestNetsshScp < FunctionalTest
+      include NetsshTransferTests
+
+      def setup
+        super
+        SSHKit::Backend::Netssh.configure do |ssh|
+          ssh.transfer_method = :scp
+        end
+      end
+
+      def test_scp_implementation_is_used
+        Netssh.new(a_host).send(:with_transfer, nil) do |transfer|
+          assert_instance_of Netssh::ScpTransfer, transfer
+        end
+      end
+    end
+  end
+end

data/test/functional/backends/test_netssh_sftp.rb

@@ -0,0 +1,23 @@
+require 'helper'
+require_relative 'netssh_transfer_tests'
+
+module SSHKit
+  module Backend
+    class TestNetsshSftp < FunctionalTest
+      include NetsshTransferTests
+
+      def setup
+        super
+        SSHKit::Backend::Netssh.configure do |ssh|
+          ssh.transfer_method = :sftp
+        end
+      end
+
+      def test_sftp_implementation_is_used
+        Netssh.new(a_host).send(:with_transfer, nil) do |transfer|
+          assert_instance_of Netssh::SftpTransfer, transfer
+        end
+      end
+    end
+  end
+end

data/test/unit/backends/test_netssh.rb

@@ -5,6 +5,12 @@ module SSHKit
   module Backend
     class TestNetssh < UnitTest
 
+      def teardown
+        super
+        # Reset config to defaults after each test
+        backend.instance_variable_set :@config, nil
+      end
+
       def backend
         @backend ||= Netssh
       end
@@ -13,6 +19,7 @@ module SSHKit
         backend.configure do |ssh|
           ssh.pty = true
           ssh.connection_timeout = 30
+          ssh.transfer_method = :sftp
           ssh.ssh_options = {
             keys: %w(/home/user/.ssh/id_rsa),
             forward_agent: false,
@@ -21,6 +28,7 @@ module SSHKit
         end
 
         assert_equal 30, backend.config.connection_timeout
+        assert_equal :sftp, backend.config.transfer_method
         assert_equal true, backend.config.pty
 
         assert_equal %w(/home/user/.ssh/id_rsa),  backend.config.ssh_options[:keys]
@@ -29,6 +37,46 @@ module SSHKit
         assert_instance_of backend::KnownHosts,   backend.config.ssh_options[:known_hosts]
       end
 
+      def test_transfer_method_prohibits_invalid_values
+        error = assert_raises ArgumentError do
+          backend.configure do |ssh|
+            ssh.transfer_method = :nope
+          end
+        end
+
+        assert_match ":nope is not a valid transfer method", error.message
+      end
+
+      def test_transfer_method_does_not_allow_nil
+        error = assert_raises ArgumentError do
+          backend.configure do |ssh|
+            ssh.transfer_method = nil
+          end
+        end
+
+        assert_match "nil is not a valid transfer method", error.message
+      end
+
+      def test_transfer_method_defaults_to_scp
+        assert_equal :scp, backend.config.transfer_method
+      end
+
+      def test_host_can_override_transfer_method
+        backend.configure do |ssh|
+          ssh.transfer_method = :scp
+        end
+
+        host = Host.new("fake")
+        host.transfer_method = :sftp
+
+        netssh = backend.new(host)
+        netssh.stubs(:with_ssh).yields(nil)
+
+        netssh.send(:with_transfer, nil) do |transfer|
+          assert_instance_of Netssh::SftpTransfer, transfer
+        end
+      end
+
       def test_netssh_ext
         assert_includes  Net::SSH::Config.default_files, "#{Dir.pwd}/.ssh/config"
       end

data/test/unit/test_host.rb

@@ -142,6 +142,33 @@ module SSHKit
       end
     end
 
+    def test_transfer_method_defaults_to_nil
+      host = Host.new 'example.com'
+      assert_nil host.transfer_method
+    end
+
+    def test_transfer_method_can_be_configured
+      host = Host.new 'example.com'
+
+      host.transfer_method = :scp
+      assert_equal :scp, host.transfer_method
+
+      host.transfer_method = :sftp
+      assert_equal :sftp, host.transfer_method
+
+      host.transfer_method = nil
+      assert_nil host.transfer_method
+    end
+
+    def test_transfer_method_prohibits_invalid_values
+      host = Host.new 'example.com'
+
+      error = assert_raises ArgumentError do
+        host.transfer_method = :nope
+      end
+
+      assert_match ":nope is not a valid transfer method", error.message
+    end
   end
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sshkit
 version: !ruby/object:Gem::Version
-  version: 1.21.7
+  version: 1.22.0
 platform: ruby
 authors:
 - Lee Hambley
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-12-26 00:00:00.000000000 Z
+date: 2024-01-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mutex_m
@@ -53,6 +53,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.1.2
+- !ruby/object:Gem::Dependency
+  name: net-sftp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.1.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.1.2
 - !ruby/object:Gem::Dependency
   name: danger
   requirement: !ruby/object:Gem::Requirement
@@ -228,6 +242,8 @@ files:
 - lib/sshkit/backends/local.rb
 - lib/sshkit/backends/netssh.rb
 - lib/sshkit/backends/netssh/known_hosts.rb
+- lib/sshkit/backends/netssh/scp_transfer.rb
+- lib/sshkit/backends/netssh/sftp_transfer.rb
 - lib/sshkit/backends/printer.rb
 - lib/sshkit/backends/skipper.rb
 - lib/sshkit/color.rb
@@ -255,8 +271,11 @@ files:
 - lib/sshkit/version.rb
 - sshkit.gemspec
 - test/boxes.json
+- test/functional/backends/netssh_transfer_tests.rb
 - test/functional/backends/test_local.rb
 - test/functional/backends/test_netssh.rb
+- test/functional/backends/test_netssh_scp.rb
+- test/functional/backends/test_netssh_sftp.rb
 - test/functional/test_ssh_server_comes_up_for_functional_tests.rb
 - test/helper.rb
 - test/known_hosts/github
@@ -311,8 +330,11 @@ specification_version: 4
 summary: SSHKit makes it easy to write structured, testable SSH commands in Ruby
 test_files:
 - test/boxes.json
+- test/functional/backends/netssh_transfer_tests.rb
 - test/functional/backends/test_local.rb
 - test/functional/backends/test_netssh.rb
+- test/functional/backends/test_netssh_scp.rb
+- test/functional/backends/test_netssh_sftp.rb
 - test/functional/test_ssh_server_comes_up_for_functional_tests.rb
 - test/helper.rb
 - test/known_hosts/github