remotus 0.1.0

data/lib/remotus/auth.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "remotus/auth/credential"
+require "remotus/auth/store"
+require "remotus/auth/hash_store"
+
+module Remotus
+  # Module containing remote authentication classes and modules
+  module Auth
+    #
+    # Gets authentication credentials for the given connection and options
+    #
+    # @param [Remotus::SshConnection, Remotus::WinrmConnection, #host] connection remote connection
+    # @param [Hash] options options hash
+    #                       options may be used by different credential stores.
+    #
+    # @return [Remotus::Auth::Credential] found credential
+    #
+    def self.credential(connection, **options)
+      return cache[connection.host] if cache.key?(connection.host)
+
+      stores.each do |store|
+        host_cred = store.credential(connection, **options)
+        if host_cred
+          cache[connection.host] = host_cred
+          return host_cred
+        end
+      end
+      raise Remotus::MissingCredential, "Could not find credential for #{connection.host} in any credential store (#{stores.join(", ")})."
+    end
+
+    #
+    # Gets the credential cache
+    #
+    # @return [Hash{String => Remotus::Auth::Credential}] credential cache with hostname keys
+    #
+    def self.cache
+      @cache ||= {}
+    end
+
+    #
+    # Clears all entries in the credential cache
+    #
+    def self.clear_cache
+      @cache = {}
+    end
+
+    #
+    # Gets the list of associated credential stores
+    #
+    # @return [Array<Remotus::Auth::Store>] credential stores
+    #
+    def self.stores
+      @stores ||= []
+    end
+
+    #
+    # Sets the list of associated credential stores
+    #
+    # @param [Array<Remotus::Auth::Store>] stores credential stores
+    #
+    def self.stores=(stores)
+      @stores = stores
+    end
+  end
+end

data/lib/remotus/auth/credential.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Remotus
+  module Auth
+    # Authentication credential
+    class Credential
+      # @return [String] gets or sets user
+      attr_accessor :user
+
+      # @return [String] gets or sets private key path
+      attr_accessor :private_key
+
+      #
+      # Generates a new credential from a hash
+      #
+      # @param [Hash] hash hash with :user, :password, :private_key, and :private_key_data keys
+      # @option hash [String] :user user name
+      # @option hash [String] :password user password
+      # @option hash [String] :private_key private key path
+      # @option hash [String] :private_key_data private key data as a string
+      #
+      # @return [Remotus::Auth::Credential] newly initialized credential
+      #
+      def self.from_hash(hash)
+        Credential.new(
+          hash[:user],
+          hash[:password],
+          private_key: hash[:private_key],
+          private_key_data: hash[:private_key_data]
+        )
+      end
+
+      #
+      # Creates a new instance of a Remotus::Auth::Credential
+      #
+      # @param [String] user user name
+      # @param [String] password user password
+      # @param [Hash] options options hash
+      # @option options [String] :private_key private key path
+      # @option options [String] :private_key_data private key data as a string
+      #
+      def initialize(user, password = nil, **options)
+        @user = user
+        @crypt_info = { password: {}, private_key_data: {} }
+        @private_key = options[:private_key]
+        self.password = password
+        self.private_key_data = options[:private_key_data]
+      end
+
+      #
+      # Retrieved decrypted password
+      #
+      # @return [String, nil] decrypted password or nil if unset
+      #
+      def password
+        return unless @password
+
+        decrypt(@password, :password)
+      end
+
+      #
+      # Sets password
+      #
+      # @param [String] password new password
+      #
+      def password=(password)
+        @password = password ? encrypt(password.to_s, :password) : nil
+      end
+
+      #
+      # Retrieves decrypted private key data
+      #
+      # @return [String, nil] decrypted private key data or nil if unset
+      #
+      def private_key_data
+        return unless @private_key_data
+
+        decrypt(@private_key_data, :private_key_data)
+      end
+
+      #
+      # Sets private key data
+      #
+      # @param [String] private_key_data private key data
+      #
+      def private_key_data=(private_key_data)
+        @private_key_data = private_key_data ? encrypt(private_key_data.to_s, :private_key_data) : nil
+      end
+
+      #
+      # Converts credential to a string
+      #
+      # @return [String] Credential represented as a string
+      #
+      def to_s
+        "user: #{@user}"
+      end
+
+      #
+      # Inspects credential
+      #
+      # @return [String] Credential represented as an inspection string
+      #
+      def inspect
+        "#{self.class.name}: (#{self})"
+      end
+
+      private
+
+      #
+      # Encrypts string data
+      #
+      # @param [String] data data to encrypt
+      # @param [Symbol] crypt_key key in @crypt_info to store the key and iv for decryption
+      #
+      # @return [Object] encrypted data
+      #
+      def encrypt(data, crypt_key)
+        cipher = OpenSSL::Cipher.new("aes-256-cbc")
+        cipher.encrypt
+        @crypt_info[crypt_key][:key] = cipher.random_key
+        @crypt_info[crypt_key][:iv] = cipher.random_iv
+        cipher.update(data) + cipher.final
+      end
+
+      #
+      # Decrypts data to a string
+      #
+      # @param [Object] data encrypted data
+      # @param [Symbol] crypt_key key in @crypt_info containing the key and iv for decryption
+      #
+      # @return [String] decrypted string
+      #
+      def decrypt(data, crypt_key)
+        decipher = OpenSSL::Cipher.new("aes-256-cbc")
+        decipher.decrypt
+        decipher.key = @crypt_info[crypt_key][:key]
+        decipher.iv = @crypt_info[crypt_key][:iv]
+        decipher.update(data) + decipher.final
+      end
+    end
+  end
+end

data/lib/remotus/auth/hash_store.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Remotus
+  module Auth
+    # Hash-based authentication store that requires credentials to be added manually
+    class HashStore < Store
+      #
+      # Creates the HashStore
+      #
+      def initialize
+        super
+        @store = {}
+      end
+
+      #
+      # Retrieves a credential from the hash store
+      #
+      # @param [Remotus::SshConnection, Remotus::WinrmConnection, #host] connection <description>
+      # @param [Hash] _options unused options hash
+      #
+      # @return [Remotus::Auth::Credential, nil] found credential or nil
+      #
+      def credential(connection, **_options)
+        @store[connection.host.downcase]
+      end
+
+      #
+      # Adds a credential to the store for a given connection
+      #
+      # @param [Remotus::SshConnection, Remotus::WinrmConnection, #host] connection associated connection
+      # @param [Remotus::Auth::Credential] credential new credential
+      #
+      def add(connection, credential)
+        @store[connection.host.downcase] = credential
+      end
+
+      #
+      # Removes a credential from the store for a given connection
+      #
+      # @param [Remotus::SshConnection, Remotus::WinrmConnection, #host] connection associated connection
+      #
+      def remove(connection)
+        @store.delete(connection.host.downcase)
+      end
+
+      #
+      # String representation of the hash store
+      #
+      # @return [String] string representation of the hash store
+      #
+      def to_s
+        "HashStore"
+      end
+    end
+  end
+end

data/lib/remotus/auth/store.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Remotus
+  module Auth
+    # Authentication store base class
+    class Store
+      #
+      # Base method fo retrieving a credential from the hash store.
+      # This must be overridden in derived classes or it will raise an exception.
+      #
+      # @param [Remotus::SshConnection, Remotus::WinrmConnection, #host] _connection unused associated connection
+      # @param [Hash] _options unused options hash
+      #
+      def credential(_connection, **_options)
+        raise Remotus::MissingOverride, "credential method not implemented in credential store #{self.class}"
+      end
+
+      #
+      # Gets the user for a given connection and options
+      #
+      # @param [Remotus::SshConnection, Remotus::WinrmConnection, #host] connection associated connection
+      # @param [Hash] options options hash
+      #
+      # @return [String] user
+      #
+      def user(connection, **options)
+        credential(connection, **options)&.user
+      end
+
+      #
+      # Gets the password for a given connection and options
+      #
+      # @param [Remotus::SshConnection, Remotus::WinrmConnection, #host] connection associated connection
+      # @param [Hash] options options hash
+      #
+      # @return [String] password
+      #
+      def password(connection, **options)
+        credential(connection, **options)&.password
+      end
+    end
+  end
+end

data/lib/remotus/host_pool.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "remotus"
+require "remotus/auth"
+require "remotus/ssh_connection"
+require "remotus/winrm_connection"
+require "connection_pool"
+
+module Remotus
+  # Class representing a remote connection pool (SSH or WinRM) for a single host
+  class HostPool
+    # @return [Time] when the host pool will expire
+    attr_reader :expiration_time
+
+    # @return [Integer] size of the host connection pool
+    attr_reader :size
+
+    # @return [Integer] Number of seconds to wait for a connection from the pool
+    attr_reader :timeout
+
+    # @return [Symbol] host pool protocol (:ssh or :winrm)
+    attr_reader :proto
+
+    # @return [String] host pool remote host
+    attr_reader :host
+
+    # Number of seconds to wait for a connection from the pool by default
+    DEFAULT_EXPIRATION_SECONDS = 600
+
+    # Default size of the connection pool
+    DEFAULT_POOL_SIZE = 2
+
+    #
+    # Creates a host pool for a specific host
+    #
+    # @param [String] host hostname
+    # @param [Integer] size number of connections in the pool (optional)
+    # @param [Integer] timeout amount of time to wait for a connection from the pool (optional)
+    # @param [Integer] port port to use for the connection
+    # @param [Symbol] proto protocol to use for the connection (:winrm, :ssh), must be specified if port is specified
+    #
+    def initialize(host, size: DEFAULT_POOL_SIZE, timeout: DEFAULT_EXPIRATION_SECONDS, port: nil, proto: nil)
+      Remotus.logger.debug { "Creating host pool for #{host}" }
+
+      @host = host
+      @proto = proto || Remotus.host_type(host)
+
+      raise Remotus::HostTypeDeterminationError, "Could not determine whether to use SSH or WinRM for #{host}" unless @proto
+
+      connection_class = Object.const_get("Remotus::#{@proto.capitalize}Connection")
+      port ||= connection_class::REMOTE_PORT
+
+      @pool = ConnectionPool.new(size: size, timeout: timeout) { connection_class.new(host, port) }
+      @size = size.to_i
+      @timeout = timeout.to_i
+      @expiration_time = Time.now + timeout
+    end
+
+    #
+    # Whether the pool is currently expired
+    #
+    # @return [Boolean] whether pool is expired
+    #
+    def expired?
+      Time.now > @expiration_time
+    end
+
+    #
+    # Force immediate expiration of the pool
+    #
+    def expire
+      Remotus.logger.debug { "Expiring #{@proto} host pool #{object_id} (#{@host})" }
+      @expiration_time = Time.now
+    end
+
+    #
+    # Provides an SSH or WinRM connection to a given block of code
+    #
+    # @example Run a command over SSH or WinRM using a pooled connection
+    #   pool.with { |c| c.run("ls") }
+    #
+    # @param [Hash] options options hash
+    # @option options [Integer] :timeout amount of time to wait for a connection if none is available
+    #
+    # @return [Object] return value of the provided block
+    #
+    def with(**options, &block)
+      # Update expiration time since the pool has been used
+      @expiration_time = Time.now + (@timeout + options[:timeout].to_i)
+      Remotus.logger.debug { "Updating #{@proto} host pool #{object_id} (#{@host}) expiration time to #{@expiration_time}" }
+
+      # Run the provided block against the connection
+      Remotus.logger.debug { "Running block in #{@proto} host pool #{object_id} (#{@host})" }
+      @pool.with(options, &block)
+    end
+
+    #
+    # Gets remote host connection port
+    # @see Remotus::SshConnection#port
+    # @see Remotus::WinrmConnection#port
+    #
+    def port
+      Remotus.logger.debug { "Getting port from #{@proto} host pool #{object_id} (#{@host})" }
+      with(&:port)
+    end
+
+    #
+    # Checks if connection port is open on the remote host
+    # @see Remotus::SshConnection#port_open?
+    # @see Remotus::WinrmConnection#port_open?
+    #
+    def port_open?
+      Remotus.logger.debug { "Checking if port is open from #{@proto} host pool #{object_id} (#{@host})" }
+      with(&:port_open?)
+    end
+
+    #
+    # Runs command on the remote host
+    # @see Remotus::SshConnection#run
+    # @see Remotus::WinrmConnection#run
+    #
+    def run(command, *args, **options)
+      with { |c| c.run(command, *args, **options) }
+    end
+
+    #
+    # Runs script on the remote host
+    # @see Remotus::SshConnection#run_script
+    # @see Remotus::WinrmConnection#run_script
+    #
+    def run_script(local_path, remote_path, *args, **options)
+      with { |c| c.run_script(local_path, remote_path, *args, **options) }
+    end
+
+    #
+    # Uploads file to the remote host
+    # @see Remotus::SshConnection#upload
+    # @see Remotus::WinrmConnection#upload
+    #
+    def upload(local_path, remote_path, **options)
+      with { |c| c.upload(local_path, remote_path, **options) }
+    end
+
+    #
+    # Downloads file from the remote host
+    # @see Remotus::SshConnection#download
+    # @see Remotus::WinrmConnection#download
+    #
+    def download(remote_path, local_path = nil, **options)
+      with { |c| c.download(remote_path, local_path, **options) }
+    end
+
+    #
+    # Checks if file exists on the remote host
+    # @see Remotus::SshConnection#file_exist?
+    # @see Remotus::WinrmConnection#file_exist?
+    #
+    def file_exist?(remote_path, **options)
+      with { |c| c.file_exist?(remote_path, **options) }
+    end
+
+    #
+    # Gets the current host credential (if any)
+    # @see Remotus::Auth#credential
+    #
+    def credential(**options)
+      with { |c| Remotus::Auth.credential(c, **options) }
+    end
+
+    #
+    # Sets the current host credential
+    #
+    # @param [Remotus::Auth::Credential, Hash] credential new credential
+    #
+    def credential=(credential)
+      # If the credential is a hash, transform it prior to setting it
+      credential = Remotus::Auth::Credential.from_hash(credential) unless credential.is_a?(Remotus::Auth::Credential)
+      Remotus::Auth.cache[host] = credential
+    end
+  end
+end