kitchen-transport-express 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a21e10d9f04926c86f5594321e1beef3d71c314ed61649ff1476cf4d632a4ee
-  data.tar.gz: 2c0d14e4ae4cc96111e2fea95fde8affc3f89686867910c459007bb06c110bd2
+  metadata.gz: b9700e07ca7ddd76297069ea6c62e00bb4ed82b87f48f643be7ba41e560e9bd4
+  data.tar.gz: 94f6354276aa9ebad26add90b234a5478f9f1ba1157fe34a69297354a29523ea
 SHA512:
-  metadata.gz: f9aa3d0be0cb45cf030333df24ca40431e1c387c7a3d0a086dacb03c5fa2c64f7e15bd02f98e1a5b70374950d986be90dd6757b0faeb460baa614992cca477af
-  data.tar.gz: 95e16299ded0673a3c7fd85db9e04defe7c0d04db6c51459024cd75badd8b3a1672485f8d7f0e40af7e21c6aaa9964e153676a390173d6e7e3a068939905df4d
+  metadata.gz: a6989457b293f6a59dabef6bea15684548769fbac53ded1413effadcf44bdcf797afe0560fba452378453d18ba3a5f88b16768ae6eb30876ca24cc1756fe0afa
+  data.tar.gz: 9f2a64a0eb918cdb14980d46b3e1f2dfbcb59d4631329784fd41d0835b1c353da2a36900483f0113067bec16b2fb277994e5d95d17af8823a2ce447ea36da899

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # kitchen-transport-express CHANGELOG
 
+## 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

@@ -39,4 +39,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "pry"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec"
+  spec.add_development_dependency "yard"
 end

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

@@ -19,32 +19,47 @@ 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 +67,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,7 @@
 module Kitchen
   module Transport
     class Express
-      VERSION = "1.1.0"
+      VERSION = "1.2.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,73 @@ 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
 
+        # (see Kitchen::Transport::Base::Connection#upload)
+        # Overrides the upload method in Kitchen::Transport::Ssh::Connection
+        # The special sauce here is that we create threaded executions of uploading our archives
+        #
+        # @param locals [Array] the top-level list of directories and files to be transfered
+        # @param remote [String] the remote directory config[:kitchen_root]
+        # @raise [ExpressFailed] if any of the threads raised an exception
+        # rubocop: disable Metrics/MethodLength
         def upload(locals, remote)
-          return super unless valid_remote_requirements?
+          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
 
-        def valid_remote_requirements?
+        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
+
+        # Ensures the remote host has the minimum-required executables to extract the archives.
+        #
+        # @param remote [String] the remote directory config[: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 +160,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.2.0
 platform: ruby
 authors:
 - Justin Steele
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-01-29 00:00:00.000000000 Z
+date: 2025-02-06 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: