kitchen-transport-express 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a21e10d9f04926c86f5594321e1beef3d71c314ed61649ff1476cf4d632a4ee
-  data.tar.gz: 2c0d14e4ae4cc96111e2fea95fde8affc3f89686867910c459007bb06c110bd2
+  metadata.gz: b255fcbeed01b423bd2bd8e71069501b2c0b636e3d2313ccdd48f8347106333d
+  data.tar.gz: 9696bbf314ccbda4c978cf89963e22005a18d064a359d835ccf033403d46f6b8
 SHA512:
-  metadata.gz: f9aa3d0be0cb45cf030333df24ca40431e1c387c7a3d0a086dacb03c5fa2c64f7e15bd02f98e1a5b70374950d986be90dd6757b0faeb460baa614992cca477af
-  data.tar.gz: 95e16299ded0673a3c7fd85db9e04defe7c0d04db6c51459024cd75badd8b3a1672485f8d7f0e40af7e21c6aaa9964e153676a390173d6e7e3a068939905df4d
+  metadata.gz: 548f04230a39e196b59fd952a4a5247bb9ee4c754d88785f61400565d7c0bd8802a1857a3c7896bb7f1a311bb63475c7416b7746768436eee60fb9cfa0b2dcc7
+  data.tar.gz: ba37810bfcdafaa6ba2973e6410c35aac5ac57bc0f9102db149829cffadea1043a4a24c509f41801eacbc6347cec41ae66907c0b79d90d95484a8bc3ea4d3707

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # kitchen-transport-express CHANGELOG
 
+## 1.3.0
+* chore: 📝 minor updates to method documentation
+* chore: 🔧 add metadata to gemspec
+
+## 1.2.0
+* feat: 🥅 add error handling to the thread pool
+* feat: 📝🎨 add YARD tags and cleaned up class namespaces and private methods
+
 ## 1.1.0
 * feat: ⚡️ threaded execution of the upload and extract phase
 * fix: 🩹 add binary mode to archiver when reading a file

data/README.md

@@ -23,7 +23,7 @@ transport:
 Verify that everything has loaded correctly with `kitchen list`.  You should see `ExpressSsh` as the transport.
 
 ```bash
-> kitchen list                                                                                                                                                                                                                                             ─╯
+> kitchen list
 Instance            Driver  Provisioner  Verifier  Transport   Last Action    Last Error
 default-linux       Oci     ChefInfra    Inspec    ExpressSsh  <Not Created>  <None>
 ```

data/kitchen-transport-express.gemspec

@@ -18,12 +18,12 @@ lib = File.expand_path("lib", __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "kitchen/transport/express/version"
 
-Gem::Specification.new do |spec|
+Gem::Specification.new do |spec| # rubocop: disable Metrics/BlockLength
   spec.name          = "kitchen-transport-express"
   spec.version       = Kitchen::Transport::Express::VERSION
   spec.authors       = ["Justin Steele"]
   spec.email         = ["justin.steele@oracle.com"]
-  spec.summary       = %q{Skip the long lines in transport. 15 items or less!}
+  spec.summary       = %q{Skip the long lines in Kitchen Transport!}
   spec.description   = %q{A Test Kitchen Transport plugin that streamlines the file transfer phase to Linux hosts.}
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   spec.homepage      = "https://github.com/justintsteele/kitchen-transport-express.git"
@@ -31,6 +31,13 @@ Gem::Specification.new do |spec|
   spec.license       = "Apache-2.0"
   spec.require_paths = ["lib"]
   spec.required_ruby_version = ">= 2.4"
+  spec.metadata = {
+    "bug_tracker_uri"   => "https://github.com/justintsteele/kitchen-transport-express/issues",
+    "changelog_uri"     => "https://github.com/justintsteele/kitchen-transport-express/blob/main/CHANGELOG.md",
+    "documentation_uri" => "https://github.com/justintsteele/kitchen-transport-express/blob/main/README.md",
+    "homepage_uri"      => "https://github.com/justintsteele/kitchen-transport-express",
+    "source_code_uri"   => "https://github.com/justintsteele/kitchen-transport-express",
+  }
   spec.add_dependency "test-kitchen"
   spec.add_dependency "ffi-libarchive"
   spec.add_dependency "concurrent-ruby"
@@ -39,4 +46,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "pry"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec"
-end
+  spec.add_development_dependency "yard"
+end  # rubocop: enable Metrics/BlockLength

data/lib/kitchen/transport/express/archiver.rb

@@ -19,32 +19,46 @@ require "ffi-libarchive"
 module Kitchen
   module Transport
     class Express
+      # Mixin module that provides methods for creating and extracting archives locally and on the remote host.
+      #
+      # @author Justin Steele <justin.steele@oracle.com>
       module Archiver
+        # Creates the archive locally in the Kitchen cache location.
+        #
+        # @param path [String] the path of the top-level directory to be arvhied.
+        # @return [String] the name of the archive.
         def archive(path)
           archive_basename = ::File.basename(path) + ".tgz"
           archive_full_name = ::File.join(::File.dirname(path), archive_basename)
 
           file_count = ::Dir.glob(::File.join(path, "**/*")).size
-          logger.debug("[#{LOG_PREFIX}] #{path} contains #{file_count} files.")
+          logger.debug("[#{Express::LOG_PREFIX}] #{path} contains #{file_count} files.")
           create_archive(path, archive_full_name)
           archive_full_name
         end
 
+        # Extracts the archive on the remote host.
+        #
+        # @param session [Net::SSH::Connection::Session] The SSH session used to connect to the remote host and execute the extract and cleanup commands.
         def extract(session, local, remote)
           return unless local.match(/.*\.tgz/)
 
           archive_basename = File.basename(local)
-          logger.debug("[#{LOG_PREFIX}] Extracting #{::File.join(remote, archive_basename)}")
+          logger.debug("[#{Express::LOG_PREFIX}] Extracting #{::File.join(remote, archive_basename)}")
           session.open_channel do |channel|
             channel.request_pty
-            channel.exec("tar -xzf #{::File.join(remote, archive_basename)} -C #{remote}")
-            channel.exec("rm -f #{File.join(remote, archive_basename)}")
+            channel.exec("tar -xzf #{::File.join(remote, archive_basename)} -C #{remote} && rm -f #{File.join(remote, archive_basename)}")
           end
           session.loop
         end
 
         private
 
+        # Creats a archive of the directory provided.
+        #
+        # @param path [String] the path to the directory that will be archived.
+        # @param archive_path [String] the fully qualified path to the archive that will be created.
+        # @api private
         def create_archive(path, archive_path)
           Archive.write_open_filename(archive_path, Archive::COMPRESSION_GZIP,
                                       Archive::FORMAT_TAR_PAX_RESTRICTED) do |tar|
@@ -52,54 +66,66 @@ module Kitchen
                                       end
         end
 
+        # Appends the content of each item in the expanded directory path.
+        #
+        # @param tar [Archive::Writer] the instance of the archive class.
+        # @param path [String] the path to the directory that will be archived.
+        # @api private
         def write_content(tar, path)
           all_files = Dir.glob("#{path}/**/*")
           all_files.each do |f|
-            tar.new_entry do |e|
-              entry(e, f, path)
-              tar.write_header e
-              tar.write_data content(f) if File.file? f
+            if File.file? f
+              tar.new_entry do |e|
+                entry(e, f, path)
+                tar.write_header e
+                tar.write_data content(f)
+              end
             end
           end
         end
 
+        # Creates the entry in the Archive for each item.
+        #
+        # @param ent [Archive::Entry] the current entry being added to the archive.
+        # @param file [String] the current file or directory being added to the archive.
+        # @param path [String] the path to the directory being archived.
+        # @api private
         def entry(ent, file, path)
-          ent.pathname = path_name(file, path)
-          ent.size = size(file) if File.file? file
+          ent.pathname = file.gsub(%r{#{File.dirname(path)}/}, "")
+          ent.size = size(file)
           ent.mode = mode(file)
-          ent.filetype = file_type(file)
-          ent.atime = timestamp
-          ent.mtime = timestamp
-        end
-
-        def path_name(file, path)
-          file.gsub(%r{#{File.dirname(path)}/}, "")
-        end
-
-        def file_type(file)
-          if File.file? file
-            Archive::Entry::FILE
-          elsif File.directory? file
-            Archive::Entry::DIRECTORY
-          end
+          ent.filetype = Archive::Entry::FILE
+          ent.atime = Time.now.to_i
+          ent.mtime = Time.now.to_i
         end
 
+        # The content of the file in binary format. Directories have no content.
+        #
+        # @param file [String] the path to the file.
+        # @return [String] the content of the file.
+        # @api private
         def content(file)
-          File.read(file, mode: "rb") unless File.directory? file
+          File.read(file, mode: "rb")
         end
 
+        # The size of the file. Directories have no size.
+        #
+        # @param file [String] the path to the file.
+        # @return [Integer] the size of the file.
+        # @api private
         def size(file)
           content(file).size
         end
 
+        # The file permissions of the file.
+        #
+        # @param file [String] the path to the file or directory.
+        # @return [Integer] the mode of the file or directory.
+        # @api private
         def mode(file)
           f = File.stat(file)
           f.mode
         end
-
-        def timestamp
-          Time.now.to_i
-        end
       end
     end
   end

data/lib/kitchen/transport/express/version.rb

@@ -17,7 +17,10 @@
 module Kitchen
   module Transport
     class Express
-      VERSION = "1.1.0"
+      # The version string for Kitchen Transport Express.
+      #
+      # @author Justin Steele <justin.steele@oracle.com>
+      VERSION = "1.3.0"
     end
   end
 end

data/lib/kitchen/transport/express_ssh.rb

@@ -21,15 +21,37 @@ require_relative "express/archiver"
 
 module Kitchen
   module Transport
-    LOG_PREFIX = "EXPRESS"
+    # Kitchen Transport Express.
+    #
+    # @author Justin Steele <justin.steele@oracle.com>
+    class Express
+      # A constant that gets prepended to debugger messages.
+      LOG_PREFIX = "EXPRESS"
+    end
+
+    # Express SSH Transport Error class.
+    #
+    # @author Justin Steele <justin.steele@oracle.com>
+    class ExpressFailed < StandardError
+      def initialize(message, exit_code = nil)
+        super("#{Express::LOG_PREFIX} file transfer failed. #{message}.")
+      end
+    end
 
+    # Express SSH Transport plugin for Test Kitchen.
+    #
+    # @author Justin Steele <justin.steele@oracle.com>
     class ExpressSsh < Kitchen::Transport::Ssh
       kitchen_transport_api_version 1
       plugin_version Express::VERSION
 
+      # Override the method in the super class to start the connection with our connection class.
+      #
+      # @param options [Hash] connection options.
+      # @return [Ssh::Connection] an instance of Kitchen::Transport::ExpressSsh::Connection.
       def create_new_connection(options, &block)
         if @connection
-          logger.debug("[#{LOG_PREFIX}] Shutting previous connection #{@connection}")
+          logger.debug("[#{Express::LOG_PREFIX}] Shutting previous connection #{@connection}")
           @connection.close
         end
 
@@ -37,10 +59,17 @@ module Kitchen
         @connection = self.class::Connection.new(options, &block)
       end
 
+      # Determines if the Kitchen instance is attempting a Verify stage.
+      #
+      # @param instance [Kitchen::Instance] the instance passed in from Kitchen.
+      # @return [Boolean]
       def verifier_defined?(instance)
         defined?(Kitchen::Verifier::Inspec) && instance.verifier.is_a?(Kitchen::Verifier::Inspec)
       end
 
+      # Finalizes the Kitchen config by executing super and parsing the options provided by the kitchen.yml.
+      # The only difference here is we layer in our ssh options so the verifier can use our transport.
+      # (see Kitchen::Transport::Ssh#finalize_config!)
       def finalize_config!(instance)
         super.tap do
           if verifier_defined?(instance)
@@ -51,33 +80,71 @@ module Kitchen
         end
       end
 
+      # This connection instance overrides the default behavior of the upload method in
+      # Kitchen::Transport::Ssh::Connection to provide the zip-and-ship style transfer of files
+      # to the kitchen instances. All other behavior from the superclass is default.
+      #
+      # @author Justin Steele <justin.steele@oracle.com>
       class Connection < Kitchen::Transport::Ssh::Connection
         include Express::Archiver
 
-        def upload(locals, remote)
-          return super unless valid_remote_requirements?
+        # Overrides the upload method in Kitchen::Transport::Ssh::Connection.
+        # The special sauce here is that we create threaded uploads of archives of the kitchen files rather than serial file uploads.
+        # (see Kitchen::Transport::Base::Connection#upload)
+        #
+        # @param locals [Array] the top-level list of directories and files to be transfered.
+        # @param remote [String] the remote directory (kitchen_root).
+        # @raise [ExpressFailed] if any of the threads raised an exception.
+        def upload(locals, remote) # rubocop: disable Metrics/MethodLength
+          return super unless valid_remote_requirements?(remote)
 
-          execute("mkdir -p #{remote}")
           processed_locals = process_locals(locals)
-          pool = Concurrent::FixedThreadPool.new([processed_locals.length, 10].min)
+          pool, exceptions = thread_pool(processed_locals)
           processed_locals.each do |local|
-            pool.post { transfer(local, remote, session.options) }
+            pool.post do
+              transfer(local, remote, session.options)
+            rescue => e
+              exceptions << e.cause
+            end
           end
           pool.shutdown
           pool.wait_for_termination
+
+          raise ExpressFailed, exceptions.pop unless exceptions.empty?
+        end # rubocop: enable Metrics/MethodLength
+
+        private
+
+        # Creates the thread pool and exceptions queue.
+        #
+        # @param processed_locals [Array] list of files and archives to be uploaded.
+        # @return [Array(Concurrent::FixedThreadPool, Queue)]
+        # @api private
+        def thread_pool(processed_locals)
+          [Concurrent::FixedThreadPool.new([processed_locals.length, 10].min), Queue.new]
         end
 
-        def valid_remote_requirements?
+        # Ensures the remote host has the minimum-required executables to extract the archives.
+        #
+        # @param remote [String] the remote directory (kitchen_root).
+        # @return [Boolean]
+        # @api private
+        def valid_remote_requirements?(remote)
           execute("(which tar && which gzip) > /dev/null")
+          execute("mkdir -p #{remote}")
           true
         rescue => e
-          logger.debug("[#{LOG_PREFIX}] Requirements not met on remote host for Express transport.")
-          logger.debug(e)
+          logger.debug("[#{Express::LOG_PREFIX}] Requirements not met on remote host for Express transport.")
+          logger.debug("[#{Express::LOG_PREFIX}] #{e}")
           false
         end
 
-        private
-
+        # Builds an array of files we want to ship. If the top-level item is a directory, archive it and
+        # add the archive name to the array.
+        #
+        # @param locals [Array] the top-level list of directories and files to be transfered.
+        # @return [Array] the paths to the files and archives that will be transferred.
+        # @api private
         def process_locals(locals)
           processed_locals = []
           Array(locals).each do |local|
@@ -91,12 +158,22 @@ module Kitchen
           processed_locals
         end
 
+        # Uploads the archives or files to the remote host.
+        #
+        # @param local [String] a single top-level item from the upload method.
+        # @param remote [String] path to remote destination.
+        # @param opts [Hash] the ssh options that came in from the Kitchen instance.
+        # @raise [StandardError] if the files could not be uploaded successfully.
+        # @api private
         def transfer(local, remote, opts = {})
-          logger.debug("[#{LOG_PREFIX}] Transferring #{local} to #{remote}")
+          logger.debug("[#{Express::LOG_PREFIX}] Transferring #{local} to #{remote}")
 
           Net::SSH.start(session.host, opts[:user], **opts) do |ssh|
             ssh.scp.upload!(local, remote, opts)
             extract(ssh, local, remote)
+          rescue Net::SCP::Error => ex
+            logger.debug("[#{Express::LOG_PREFIX}] upload failed with #{ex.message.strip}")
+            raise "(#{ex.message.strip})"
           end
         end
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kitchen-transport-express
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Justin Steele
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-01-29 00:00:00.000000000 Z
+date: 2025-02-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: test-kitchen
@@ -122,6 +122,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A Test Kitchen Transport plugin that streamlines the file transfer phase
   to Linux hosts.
 email:
@@ -146,7 +160,11 @@ homepage: https://github.com/justintsteele/kitchen-transport-express.git
 licenses:
 - Apache-2.0
 metadata:
-  github_repo: https://github.com/justintsteele/kitchen-transport-express
+  bug_tracker_uri: https://github.com/justintsteele/kitchen-transport-express/issues
+  changelog_uri: https://github.com/justintsteele/kitchen-transport-express/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/justintsteele/kitchen-transport-express/blob/main/README.md
+  homepage_uri: https://github.com/justintsteele/kitchen-transport-express
+  source_code_uri: https://github.com/justintsteele/kitchen-transport-express
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -165,5 +183,5 @@ requirements: []
 rubygems_version: 3.3.7
 signing_key: 
 specification_version: 4
-summary: Skip the long lines in transport. 15 items or less!
+summary: Skip the long lines in Kitchen Transport!
 test_files: []