cem_acpt 0.1.0

data/lib/cem_acpt/shared_objects.rb

@@ -0,0 +1,416 @@
+# frozen_string_literal: true
+
+require 'concurrent-ruby'
+require 'deep_merge'
+require 'json'
+require 'ostruct'
+require 'yaml'
+require_relative 'core_extensions'
+require_relative 'logging'
+
+module CemAcpt
+  using CemAcpt::CoreExtensions::ExtendedHash
+
+  class ConfigImmutableError < RuntimeError; end
+
+  # Holds module methods for writing various config objects
+  # to files.
+  module ConfigUtils
+    class << self
+      include CemAcpt::Logging
+    end
+
+    def self.object_to_file(obj, file_path)
+      case File.extname(file_path)
+      when '.json'
+        raise "Object #{obj} is not serializable to JSON" unless obj.respond_to?(:to_json)
+
+        logger.debug("Writing object to #{file_path}")
+        File.write(file_path, obj.to_json)
+      when '.yaml', '.yml'
+        raise "Object #{obj} is not serializable to YAML" unless obj.respond_to?(:to_yaml)
+
+        logger.debug("Writing object to #{file_path}")
+        File.write(file_path, obj.to_yaml)
+      else
+        raise "File extension #{File.extname(file_path)} is not supported"
+      end
+    end
+  end
+
+  # Provides a thread-safe Config object.
+  # Once the config is loaded by calling the `load` method, the object is
+  # immutable and thread-safe as long as the internal hash is only accessed
+  # by the `#get` and `#has?` methods. If `#load` is called more than once,
+  # the object will raise an error.
+  class Config
+    include CemAcpt::Logging
+
+    attr_reader :config_file
+
+    def initialize
+      @opts = {}
+    end
+
+    # Returns the value of the dot-separated key.
+    # If the key is not found, returns nil.
+    # @param dot_key [String] Dot-separated key
+    # @return [Object] Value of the key
+    def get(dot_key)
+      @opts.dot_dig(dot_key)
+    end
+
+    # Checks if the dot-separated key exists in the config.
+    # @param dot_key [String] Dot-separated key
+    # @return [Boolean] True if the key exists, false otherwise
+    def has?(dot_key)
+      !!get(dot_key)
+    end
+
+    # Loads the config from specified file path. Config files must be in YAML
+    # format. If 'opts' is specified, it will be merged with the config file.
+    # Values in 'opts' will override values in the config file.
+    # @param opts [Hash] Options to be merged with the config file
+    # @param config_file [String] Path to the config file
+    def load(opts: {}, config_file: '~/.cem_acpt.yaml')
+      raise ConfigImmutableError, 'Config is immutable, cannot load more than once' if frozen?
+      raise ArgumentError, 'opts must be a Hash' unless opts.is_a?(Hash)
+      raise ArgumentError, 'config_file must be a String' unless config_file.is_a?(String)
+
+      @config_file = File.expand_path(config_file)
+      @opts = load_opts_from_file(File.expand_path(config_file)).deep_merge(opts)
+      @opts.format!
+      @opts.freeze
+      freeze
+    end
+
+    # Returns the config as a Hash.
+    # @return [Hash] Config as a Hash
+    def to_h
+      ::Marshal.load(::Marshal.dump(@opts))
+    end
+
+    # Returns the config as a YAML string.
+    # @return [String] Config as a YAML string
+    def to_yaml
+      to_h.to_yaml
+    end
+
+    # Returns the config as a JSON string.
+    # @return [String] Config as a JSON string
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    private
+
+    # Loads the config from the specified file path.
+    # @param config_file [String] Path to the config file
+    # @return [Hash] Config hash
+    def load_opts_from_file(config_file)
+      return {} unless File.exist?(config_file)
+
+      logger.debug("Loading config from #{config_file}")
+      YAML.load_file(config_file)
+    end
+  end
+
+  # Provides an object to hold NodeData configs.
+  # Not thread-safe. Should not be mutated by itself,
+  # but can be mutated safely by the NodeInventory object.
+  # Currently unused.
+  class NodeData
+    include CemAcpt::Logging
+
+    attr_reader :name, :data
+
+    def initialize(name, data)
+      data.format!
+      @name = name
+      @opts = data
+    end
+
+    def deep_merge(other)
+      @opts.deep_merge(other.to_h)
+    end
+
+    def dot_dig(dot_key)
+      @opts.dot_dig(dot_key)
+    end
+
+    def dot_store(dot_key, value)
+      @opts.dot_store(dot_key, value)
+    end
+
+    def to_h
+      @opts
+    end
+
+    def to_yaml
+      to_h.to_yaml
+    end
+
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+  end
+
+  class NodeClaimedError < StandardError; end
+  class NodeDoesNotExistError < StandardError; end
+
+  # Provides a thread-safe inventory of test nodes.
+  class NodeInventory
+    include CemAcpt::Logging
+
+    attr_accessor :save_file_path
+
+    def initialize
+      @inventory = Concurrent::Map.new
+      @lock = Concurrent::ReadWriteLock.new
+      @claimed = Concurrent::Set.new
+      @save_on_claim = false
+      @save_file_path = 'spec/fixtures/node_inventory.yaml'
+    end
+
+    # When called, enables saving the inventory to a file on claim.
+    def save_on_claim
+      @save_on_claim = true
+    end
+
+    # Checks if save_on_claim is enabled.
+    def save_on_claim?
+      @save_on_claim
+    end
+
+    # Adds a new node to the inventory.
+    # @param node_name [String] The name of the node to add.
+    # @param node_data [Hash] The node data to add.
+    def add(node_name, node_data)
+      @inventory.put_if_absent(node_name, node_data)
+    end
+
+    # Returns the node data for a given node.
+    # @param node_name [String] The name of the node to get data for.
+    def get(node_name)
+      @inventory[node_name]
+    end
+
+    # Sets a specific property on a node in the inventory.
+    # @param node_name [String] The name of the node to set the property on.
+    # @param property_path [String] The dot-separated property path to set.
+    # @param value [Object] The value to set.
+    def set(node_name, property_path, value)
+      @inventory[node_name].dot_store(property_path, value)
+    end
+
+    # Merges new node data in with the existing node data for the given node.
+    # @param node_name [String] The name of the node to merge data for.
+    # @param new_node_data [Hash] The new node data to merge.
+    def merge!(node_name, new_node_data)
+      @inventory.merge_pair(node_name, new_node_data) do |old_data|
+        old_data.deep_merge(new_node_data)
+      end
+    end
+
+    # Checks if a node is claimed.
+    # @param node_name [String] The name of the node to check.
+    # @return [Boolean] True if the node is claimed, false otherwise.
+    def claimed?(node_name)
+      raise NodeDoesNotExistError, "Node #{node_name} does not exist" unless @inventory.keys.include?(node_name)
+
+      @claimed.include?(node_name)
+    end
+
+    # Claims a node, which returns the node data and adds that node to the
+    # claimed set. Raises an error if the node is already claimed or does
+    # not exist. This is used during acceptance testing to ensure that
+    # nodes are not reused.
+    # @param node_name [String] The name of the node to claim.
+    # @return [String] The name of the node that was claimed.
+    # @raise [NodeDoesNotExistError] If the node does not exist in the inventory.
+    # @raise [NodeClaimedError] If the node is already claimed.
+    def claim(node_name)
+      @lock.with_write_lock do
+        unless @inventory.keys.include?(node_name)
+          raise NodeDoesNotExistError, "Node #{node_name} does not exist in inventory"
+        end
+
+        if @claimed.include?(node_name)
+          raise NodeClaimedError, "Node #{node_name} is already tainted and cannot be claimed"
+        end
+
+        @claimed.add(node_name)
+        save_no_lock!(@save_file_path) if @save_on_claim
+        node_name
+      end
+    end
+
+    # Claims a node based on a property of the node data and a value that property should equal.
+    # If a node is found but is already claimed, the method will continue to search for an
+    # unclaimed node. Raises an error if no valid node is found. This is used during acceptance
+    # testing to ensure that nodes are not reused.
+    # @param property_path [String] The dot-separated property path to check.
+    # @param value [Object] The value to check for.
+    # @return [String] The name of the node that was claimed.
+    # @raise [NodeDoesNotExistError] If no valid node is found.
+    def claim_by_property(property_path, value)
+      claimed_set = @claimed.dup
+      claim_name = nil
+      @inventory.each_pair do |node_name, node_data|
+        next if claimed_set.include?(node_name)
+
+        claim_name = node_name if node_data.dot_dig(property_path) == value
+      end
+      return claim(claim_name) unless claim_name.nil?
+
+      raise NodeDoesNotExistError, "No node found with property #{property_path} == #{value}"
+    end
+
+    # Deletes a node from the inventory.
+    # @param node_name [String] The name of the node to delete.
+    def delete(node_name)
+      @inventory.delete(node_name)
+    end
+
+    # Returns all node names in the current inventory.
+    def nodes
+      @inventory.keys
+    end
+
+    # Clears the inventory and removes claimed nodes. DOES NOT USE LOCK.
+    # If this is called outside of a lock, it will not be thread-safe.
+    def clear_no_lock!
+      nodes.each { |node| delete(node) }
+      @claimed.clear
+    end
+
+    # Clears the inventory and removes claimed nodes. Thread-safe.
+    def clear!
+      @lock.with_write_lock do
+        clear_no_lock!
+      end
+    end
+
+    # Checks if the inventory contains a node with the given property.
+    # @param node_name [String] The name of the node to check.
+    # @param property_path [String] The dot-separated property path to check.
+    def property?(node_name, property_path)
+      !!@inventory[node_name].dot_dig(property_path)
+    end
+
+    # Returns a hash of the inventory.
+    def to_h
+      h = {}
+      @inventory.each_pair do |node_name, node_data|
+        h[node_name] = node_data.to_h
+      end
+      h[:claimed] = @claimed.to_a
+      h
+    end
+
+    # Returns a YAML string of the inventory.
+    def to_yaml
+      to_h.to_yaml
+    end
+
+    # Returns a JSON string of the inventory.
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    # Saves the current node inventory to a file. DOES NOT USE LOCK.
+    # If this is called outside of a lock, it will not be thread-safe.
+    def save_no_lock!(file_path = @save_file_path)
+      File.open(file_path, 'w') do |file|
+        file.write(to_yaml)
+      end
+    end
+
+    # Saves the current node inventory to a yaml file. Thread-safe.
+    # @param file_path [String] The path to the file to save to.
+    def save(file_path = @save_file_path)
+      @lock.with_write_lock do
+        save_no_lock!(file_path)
+      end
+    end
+
+    # Loads a node inventory from a file. DOES NOT USE LOCK.
+    # If this is called outside of a lock, it will not be thread-safe.
+    def load_no_lock!(file_path = @save_file_path)
+      require 'net/ssh/proxy/command' # If ProxyCommand is used in ssh options, this is required.
+      clear_no_lock!
+      YAML.load_file(file_path).each_pair do |node_name, node_data|
+        if node_name == :claimed
+          @claimed = Set.new(node_data)
+        else
+          add(node_name, node_data)
+        end
+      end
+    end
+
+    # Loads a node inventory from a yaml file. Thread-safe.
+    # @param file_path [String] The path to the file to load from.
+    def load(file_path = @save_file_path)
+      @lock.with_write_lock do
+        load_no_lock!(file_path)
+      end
+    end
+  end
+
+  class LocalPortAllocationError < StandardError; end
+
+  # Handles local port allocation for things like local SSH tunnels.
+  # This class is thread-safe as the port range is a Concurrent::Array,
+  # which blocks when modified. When this class is initialized, it's
+  # total assignable ports are set to all ports in the ephemeral port range.
+  # When a port is allocated, it's removed from the port range.
+  class LocalPortAllocator
+    EPHEMERAL_PORT_RANGE = (49_152..65_535).to_a.freeze
+
+    def initialize
+      @port_range = Concurrent::Array.new(EPHEMERAL_PORT_RANGE.dup).shuffle!
+    end
+
+    # Returns an open port(s) in the ephemeral port range on the local machine.
+    # If 'number_of_ports' is specified and greater than one, returns an array of ports.
+    # If 'number_of_ports' is not specified or is one, returns a single port.
+    # @param number_of_ports [Integer] the number of ports to allocate
+    # @return [Integer, Array<Integer>] the port(s) allocated
+    # @raise [ArgumentError] if number_of_ports is not an Integer or is less than one
+    # @raise [LocalPortAllocationError] if there are no ports available
+    def allocate(number_of_ports = 1)
+      unless number_of_ports.is_a?(Integer) && number_of_ports.positive?
+        raise ArgumentError, 'number_of_ports must be a positive integer'
+      end
+      raise LocalPortAllocationError, 'No ports available' if @port_range.empty?
+
+      ports = []
+      while ports.length < number_of_ports
+        port = @port_range.pop
+        next unless local_port_open?(port)
+
+        ports << port
+      end
+      return ports[0] if ports.length == 1
+
+      ports
+    end
+
+    private
+
+    # Checks if the given port is open on the local machine. This is done by
+    # opening a socket on the port and checking if it raises an exception.
+    # @param port [Integer] the port to check
+    # @return [Boolean] true if the port is open, false otherwise
+    def local_port_open?(port)
+      require 'socket'
+      socket = Socket.new(Socket::Constants::AF_INET, Socket::Constants::SOCK_STREAM, 0)
+      socket.bind(Socket.pack_sockaddr_in(port, '0.0.0.0'))
+      true
+    rescue Errno::EADDRINUSE, Errno::CONNREFUSED
+      false
+    ensure
+      socket&.close
+    end
+  end
+end

data/lib/cem_acpt/spec_helper_acceptance.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module CemAcpt
+  require_relative 'shared_objects'
+
+  # This methods is used in spec_helper_acceptance.rb to set up
+  # baseline configurations used in acceptance tests.
+  def self.configure_spec_helper!
+    require 'serverspec'
+    require 'yaml'
+
+    RSpec.configure do |config|
+      config.include CemAcpt::SpecHelperAcceptance
+      config.extend CemAcpt::SpecHelperAcceptance
+      config.add_setting :acpt_test_data, default: {}
+      config.add_setting :acpt_node_inventory
+    end
+
+    return unless RSpec.configuration.acpt_node_inventory.nil?
+
+    raise 'Node inventory file not found!' unless File.exist?('spec/fixtures/node_inventory.yaml')
+
+    node_inventory = NodeInventory.new
+    node_inventory.save_on_claim
+    node_inventory.save_file_path = 'spec/fixtures/node_inventory.yaml'
+    node_inventory.load
+    RSpec.configuration.acpt_node_inventory = node_inventory
+  end
+
+  # This module provides methods used in accpetance tests.
+  module SpecHelperAcceptance
+    # This method must be used inside of a `describe` block as the first
+    # statement. This prepares the ServerSpec configuration for the test node
+    # and sets up the test data.
+    def initialize_test_environment!
+      test_file = caller_locations.first.path
+
+      node_name = RSpec.configuration.acpt_node_inventory.claim_by_property('test_data.test_file', test_file)
+      node_data = RSpec.configuration.acpt_node_inventory.get(node_name)
+      backend = nil
+      host = nil
+      ssh_options = nil
+      puppet_path = nil
+
+      # Set remote communication variables based on transport type
+      case node_data[:transport]
+      when /ssh/
+        backend = :ssh
+        host = node_data[:node_name]
+        ssh_options = node_data[:ssh_opts]
+        sudo_options = '-n -u root -i'
+        puppet_path = '/opt/puppetlabs/bin/puppet'
+      when /winrm/
+        backend = :winrm
+        puppet_path = 'C:\Program Files\Puppet Labs\Puppet\bin\puppet.bat'
+      else
+        raise "Unknown transport: #{node[:transport]}"
+      end
+
+      # Set serverspec transport options and host for remote communication.
+      set :backend, backend
+      set :host, host
+      set(:ssh_options, ssh_options) if ssh_options
+      set(:sudo_options, sudo_options) if sudo_options
+      set(:os, family: 'windows') if backend == :winrm
+
+      # Get the command provider from the node's platform
+      # We add this as a RSpec config option so that we can use it in
+      # other functions.
+      require 'cem_acpt/platform'
+
+      acpt_test_data = {
+        test_file: test_file,
+        node_name: node_name,
+        node_data: node_data,
+        backend: backend,
+        platform: CemAcpt::Platform.get(node_data[:platform]),
+        puppet_path: puppet_path,
+      }
+      acpt_test_data[:host] = host if host
+      RSpec.configuration.acpt_test_data = acpt_test_data
+    end
+
+    # This method formats Puppet Apply options 
+    def puppet_apply_options(opts = {})
+      if [opts[:catch_changes], opts[:expect_changes], opts[:catch_failures], opts[:expect_failures]].compact.length > 1
+        raise ArgumentError, 'Please specify only one of "catch_changes", "expect_changes", "catch_failures", or "expect_failures"'
+      end
+
+      apply_opts = { trace: true }.merge(opts)
+
+      if opts[:catch_changes]
+        apply_opts[:detailed_exit_codes] = true
+        apply_opts[:acceptable_exit_codes] = [0]
+      elsif opts[:catch_failures]
+        apply_opts[:detailed_exit_codes] = true
+        apply_opts[:acceptable_exit_codes] = [0, 2]
+      elsif opts[:expect_failures]
+        apply_opts[:detailed_exit_codes] = true
+        apply_opts[:acceptable_exit_codes] = [1, 4, 6]
+      elsif opts[:expect_changes]
+        apply_opts[:detailed_exit_codes] = true
+        apply_opts[:acceptable_exit_codes] = [2]
+      else
+        apply_opts[:detailed_exit_codes] = false
+        apply_opts[:acceptable_exit_codes] = [0]
+      end
+      apply_opts
+    end
+
+    # This methods handles formatting the output from Puppet apply.
+    def handle_puppet_apply_output(result, apply_opts)
+      exit_code = result.exitstatus
+      output = result.to_s
+      if apply_opts[:catch_changes] && !apply_opts[:acceptable_exit_codes].include?(exit_code)
+        failure = <<~ERROR
+          Apply manifest expected no changes. Puppet Apply returned exit code #{exit_code}
+          ====== Start output of Puppet apply with unexpected changes ======
+          #{output}
+          ====== End output of Puppet apply with unexpected changes ======
+        ERROR
+        raise failure
+      elsif !apply_opts[:acceptable_exit_codes].include?(exit_code)
+        failure = <<~ERROR
+          Apply manifest failed with exit code #{exit_code} (expected: #{apply_opts[:acceptable_exit_codes]})
+          ====== Start output of failed Puppet apply ======
+          #{output}
+          ====== End output of failed Puppet apply ======
+        ERROR
+        raise failure
+      end
+
+      yield result if block_given?
+
+      if ENV['RSPEC_DEBUG']
+        run_result = <<~RUNRES
+          apply manifest succeded with status #{exit_code}
+          ===== Start output of successful Puppet apply ======
+          #{output}
+          ===== End output of successful Puppet apply ======
+        RUNRES
+        puts run_result
+      end
+      result
+    end
+
+    # This method runs a shell command on the test node.
+    def run_shell(cmd, opts = {})
+      cmd = cmd.join(' ') if cmd.is_a?(Array)
+
+      host = RSpec.configuration.acpt_test_data[:node_name]
+      opts[:ssh_opts] = RSpec.configuration.acpt_test_data[:node_data][:ssh_opts]
+      RSpec.configuration.acpt_test_data[:platform].run_shell(host, cmd, opts)
+    end
+
+    # This method runs puppet apply on the test node using the provided manifest.
+    def apply_manifest(manifest, opts = {})
+      host = RSpec.configuration.acpt_test_data[:node_name]
+      opts = {
+        apply: puppet_apply_options(opts),
+        ssh_opts: RSpec.configuration.acpt_test_data[:node_data][:ssh_opts],
+        puppet_path: RSpec.configuration.acpt_test_data[:puppet_path],
+      }
+      result = RSpec.configuration.acpt_test_data[:platform].apply_manifest(host, manifest, opts)
+      handle_puppet_apply_output(result, opts[:apply])
+    end
+
+    # This method runs puppet apply on the test node using the provided manifest twice and
+    # asserts that the second run has no changes.
+    def idempotent_apply(manifest, opts = {})
+      opts.reject! { |k, _| %i[catch_changes expect_changes catch_failures expect_failures].include?(k) }
+      apply_manifest(manifest, opts.merge(catch_failures: true))
+      apply_manifest(manifest, opts.merge(catch_changes: true))
+    end
+  end
+end