qat-core 6.0.0

data/lib/qat/configuration.rb

@@ -0,0 +1,172 @@
+# -*- encoding : utf-8 -*-
+require 'forwardable'
+require 'yaml'
+require 'erb'
+require 'ipaddr'
+require 'active_support/core_ext/hash/indifferent_access'
+require 'active_support/core_ext/object/deep_dup'
+require 'active_support/core_ext/hash/keys'
+require 'active_support/core_ext/hash/deep_merge'
+require_relative 'core'
+require_relative 'utils/network'
+require_relative 'configuration/environment'
+require_relative 'configuration/parser'
+require 'qat/logger'
+
+#QAT Module works as a namespace for all sub modules.
+#Some singleton methods are also available, as defined by various sub classes.
+module QAT
+
+  # This class represents {QAT}'s Configuration manager
+  #
+  # This class should be used to manage configurations from multiple environments in test projects.
+  # Given a defined environment, all configurations for that environment will be loaded into a cache
+  # from the corresponding folder (with the same name) under the +config+ directory.
+  #
+  # A +common+ folder is also supported which contains configurations shared between multiple environments.
+  # A configuration file can exist in both the environment folder and the common folder with the content of both
+  # being merged at load time and the configuration from the environment taking precedence over the shared (common)
+  # configuration.
+  #
+  # Also supported is the cross-referencing of configurations between files.
+  # Given a file 'foo.yml' with a configuration 'foo: bar'
+  # and a second file 'baz.yml' with configuration 'baz: foo.foo',
+  # after configurations are loaded to cache, the value of 'baz' in cache will be 'bar'.
+  # Cross-referencing between files is made with syntax:
+  # - +<file.yml>+
+  #     `
+  #     key: <other_file.yml>.<key>
+  #     `
+  #@since 0.1.0
+  class Configuration
+    extend Forwardable
+    include QAT::Logger
+    include Utils::Network
+    include Environment
+    include Parser
+
+    def_delegators :@cache, :empty?, :fetch, :keys, :has_key?, :include?, :key?, :member?, :reject, :select, :values_at,
+                   :stringify_keys, :symbolize_keys, :dig
+
+    #@param directory [String] path to configuration directory
+    #@param environment [String] name of the environment from which configurations will be loaded
+    def initialize(directory=Dir.pwd, environment=nil)
+      self.directory = directory
+      log.info { "Initializing configuration from directory #{self.directory}" }
+      self.environment = validate_environment(environment)
+      log.info { "Initialized configuration with environment '#{self.environment}'" }
+    end
+
+    # Returns a copy from cache to avoid data manipulation on runtime
+    #@param key [String|Symbol] cache key
+    #@return [Object]
+    def [](key)
+      @cache[key].deep_dup
+    end
+
+    private
+    # Resolves references between configuration files.
+    def resolve_references!
+      intersect_config @cache
+    end
+
+    # Resets the configuration cache
+    def reset_cache!
+      @cache = ActiveSupport::HashWithIndifferentAccess.new unless @cache and @cache.empty?
+    end
+
+    # Loads the environment configurations for the defined environment.
+    # If an invalid +environment+ was given, an exception is thrown.
+    #
+    #@see #environment=
+    #@raise [NoEnvironmentDefined] When no environment definition if found
+    #@raise [NoEnvironmentFolder] When there is no environment folder for environment definition
+    def load_env!
+      raise NoEnvironmentDefined.new 'No environment definition found!' unless environment
+
+      env_folder = File.join @directory, environment
+      raise NoEnvironmentFolder.new "No folder '#{environment}' found in directory #{@directory}" unless Dir.exist? env_folder
+
+      common_folder = File.join @directory, 'common'
+
+      reset_cache!
+      log.debug { "Loading configuration cache using environment #{environment}" }
+
+      [common_folder, env_folder].each do |folder|
+        if Dir.exist? folder
+          log.debug { "Loading folder #{folder}" }
+          load_root_files(folder)
+          load_root_folders(folder)
+        else
+          log.debug { "Folder #{folder} not found, skipping" }
+        end
+      end
+      log.info { "Configuration cache loaded" }
+
+      resolve_references!
+
+      log.info { "Configuration cache references resolved" }
+    end
+
+    # Analyses +config+ and replaces references between configuration files.
+    #
+    #@param config [ActiveSupport::HashWithIndifferentAccess]
+    #@return [ActiveSupport::HashWithIndifferentAccess]
+    def intersect_config(config)
+      new_hash = {}
+      config.each do |key, value|
+        if value.is_a?(Hash)
+          new_value = intersect_config(value)
+        elsif value.is_a?(Array)
+          new_value = value.map { |element| referenced_value(element) }
+        else
+          new_value = referenced_value(value)
+        end
+        new_hash[key] = new_value
+      end
+      config.update(new_hash)
+    end
+
+    # Returns the value referenced by a given +reference+.
+    #
+    #@param reference [Object] object containing references/values
+    #@return [Object]
+    def referenced_value(reference)
+      if reference.is_a?(Array)
+        reference.each { |element| referenced_value(element) }
+      elsif reference.is_a?(Hash)
+        reference.each { |key, value| reference[key] = referenced_value(value) }
+      else
+        return reference unless reference.is_a?(String) && reference.match(/^\w+(\.\w+)+$/) && !is_ip?(reference)
+
+        value = reference.split('.').inject(@cache) { |cache, key| cache[key] } rescue reference
+
+        if value.equal? reference
+          log.debug { "Reference '#{reference}' not found, keeping original value" }
+        else
+          log.debug { "Replacing '#{reference}' reference for value '#{value}'" }
+        end
+
+        value
+      end
+    end
+
+    public
+    # This class represents a configuration loading error when there is no defined environment
+    class NoEnvironmentDefined < StandardError
+    end
+    # This class represents a configuration loading error when there is no folder for defined environment
+    class NoEnvironmentFolder < StandardError
+    end
+    # This class represents a configuration loading error when there is a folder has an invalid name
+    class InvalidFolderName < StandardError
+    end
+  end
+
+  # Singleton access to a {QAT::Configuration} object. Only available in cucumber mode.
+  #@return [QAT::Configuration] Configuration object for the config folder.
+  def self.configuration
+    to_load        = ENV['QAT_CONFIG_FOLDER'] || 'config'
+    @configuration ||= QAT::Configuration.new to_load
+  end
+end

data/lib/qat/configuration/environment.rb

@@ -0,0 +1,103 @@
+module QAT
+  class Configuration
+    # Namespace for environment helper methods
+    module Environment
+      attr_reader :environment, :directory
+
+      # Sets the configuration directory
+      #
+      # If an invalid path is given, an exception will thrown.
+      # Given a valid +directory+ path:
+      # - if the path is the same as the current path no configurations will loaded.
+      # - if the identifier is for a new path, cache is cleared and the new configurations are loaded.
+      #
+      #@param directory [String] directory path
+      #@raise [ArgumentError] When directory is invalid.
+      def directory=(directory)
+        raise ArgumentError.new 'No directory to set' unless directory
+        unless File.exist? directory and File.directory? directory
+          raise ArgumentError.new "#{directory} does not exist or is not a directory"
+        end
+        if @directory and File.absolute_path(directory) == File.absolute_path(@directory)
+          log.info { "New directory is the same as the old one, cache will not be refreshed." }
+        else
+          old_dir    = @directory
+          @directory = directory
+          log.info { "Using directory #{@directory}" }
+          reset_cache!
+          load_env! if old_dir
+        end
+      rescue NoEnvironmentDefined
+        log.warn "Environment is not defined! When defined, cache will be refreshed."
+          #Loading can happen when environment is defined
+      rescue NoEnvironmentFolder
+        log.warn "Defined environment does not exist in current directory, choose a valid environment to load cache"
+        self.environment = nil
+      end
+
+      # Sets the current environment
+      #
+      # Given a +environment+ identifier:
+      # - if the identifier is the same as the current environment no configurations will loaded.
+      # - if the identifier is for a new environment, cache is cleared and the new configurations are loaded.
+      # - if a +nil+ environment is given, configuration cache is cleared.
+      #
+      #@param environment [String] environment identifier (name)
+      #@raise [NoEnvironmentDefined] When no environment definition if found
+      #@raise [NoEnvironmentFolder] When there is no environment folder for environment definition
+      def environment=(environment)
+        return if @environment == environment
+        old_env      = @environment
+        @environment = environment
+
+        if environment
+          load_env!
+        else
+          reset_cache!
+        end
+      rescue
+        @environment = old_env
+        raise
+      end
+
+      # Returns all the defined environments in the configuration directory
+      #
+      #@return [Array<String>] All environments defined
+      def environments
+        Dir.glob(File.join directory, '*/').map { |entry| File.basename(entry) }.reject { |entry| entry == 'common' }
+      end
+
+      # Executes a code +block+ in all environments of the current configuration directory
+      #
+      #@yield block to execute
+      #@yieldparam [Configuration] Configuration loaded for each environment
+      def each_environment(&block)
+        old_env = @environment
+        environments.sort.each do |env|
+          self.environment = env
+          block.call(self)
+        end
+      ensure
+        self.environment = old_env
+      end
+
+      private
+      # Validates and returns the environment to be used based on precedences
+      # @param environment [String] environment reference
+      # @return [String]
+      def validate_environment(environment)
+        if environment
+          log.debug { "Reading environment from default variable" }
+          environment
+        elsif ENV['QAT_CONFIG_ENV']
+          log.debug { "Reading environment from QAT_CONFIG_ENV environment variable" }
+          ENV['QAT_CONFIG_ENV']
+        else
+          default_file = File.join @directory, 'default.yml'
+          log.debug { "Reading default file #{default_file}" }
+          read_yml(default_file)['env'] rescue nil
+        end
+      end
+    end
+  end
+end

data/lib/qat/configuration/parser.rb

@@ -0,0 +1,100 @@
+module QAT
+  class Configuration
+    # Namespace for configuration parsing helper methods
+    module Parser
+      private
+
+      # Loads all files from the root configuration folder
+      #@param folder [String] root configuration folder path
+      def load_root_files(folder)
+        Dir.glob(File.join(folder, '*.yml')).each do |file|
+          log.debug { "Loading file #{file}" }
+          data = read_yml file
+
+          base = File.basename(file, '.yml').to_sym
+
+          @cache[base] ||= HashWithIndifferentAccess.new
+
+          @cache[base].update data.with_indifferent_access do |key, old, new|
+            log.debug { "Replacing key '#{key}' in cache with value '#{new}' (previously was '#{old}')" }
+            new
+          end
+          log.debug { 'Loaded file' }
+        end
+      end
+
+      # Loads all folders from the root configuration folder
+      #@param folder [String] root configuration folder path
+      def load_root_folders(folder)
+        child_folders(folder).each do |child_folder|
+          log.debug { "Loading folder #{child_folder}" }
+
+          base = File.basename(child_folder).to_sym
+
+          raise(InvalidFolderName, "A file with name #{base} exists and was already loaded!") if File.exist?("#{child_folder}.yml")
+
+          @cache[base] ||= {}
+
+          data = load_child_folder(child_folder).deep_symbolize_keys!
+
+          merge_with_cache!(base, data)
+
+          log.debug { 'Loaded folder' }
+        end
+      end
+
+      # Return the child folder for a given directory
+      # @param folder [String] directory path
+      # @return [Array]
+      def child_folders(folder)
+        Dir.glob(File.join(folder, '*')).select { |entry| File.directory? entry }
+      end
+
+      def merge_with_cache!(base, data)
+        symbolized_cache = @cache[base].deep_symbolize_keys
+
+        symbolized_cache.deep_merge! data do |key, old, new|
+          log.debug { "Replacing key '#{key}' in cache with value '#{new}' (previously was '#{old}')" }
+          new
+        end
+
+        @cache[base] = symbolized_cache.with_indifferent_access
+      end
+
+      # Loads a configuration folder within another folder
+      #@param folder [String] configuration folder path
+      def load_child_folder(folder)
+        content = {}
+
+        Dir.glob(File.join(folder, '*.yml')).each do |file|
+          base = File.basename(file, '.yml').to_sym
+
+          content[base] = read_yml(file)
+        end
+
+        folders = Dir.glob(File.join(folder, '*')).select { |entry| File.directory? entry }
+        folders.each do |folder_name|
+          base = File.basename(folder_name).to_sym
+
+          raise(InvalidFolderName, "A file with name #{base} exists and was already loaded!") if content[base]
+          content[base] = load_child_folder(folder_name)
+        end
+
+        content
+      end
+
+      # Reads and parses a YAML file. Allows for ERB syntax to be used.
+      #
+      #@param file_path [String] YAML file path
+      #@return [Hash]
+      #@raise Psych::SyntaxError
+      def read_yml(file_path)
+        log.debug "Loading '#{file_path}'..."
+        YAML::load(ERB.new(File.read(file_path)).result) || {}
+      rescue Psych::SyntaxError
+        log.error "Error parsing YAML file '#{file_path}'!"
+        raise
+      end
+    end
+  end
+end

data/lib/qat/core.rb

@@ -0,0 +1,53 @@
+# -*- encoding : utf-8 -*-
+require 'forwardable'
+require 'singleton'
+require_relative 'core/version'
+
+module QAT
+  #Core shared memory class. Works as a singleton.
+  #
+  #Apart from a regular shared cache class with CRUD operations, it also has a reset functionality,
+  #allowing to define exception values that will never be reset.
+  #
+  #@since 0.1.0
+  class Core
+    include Singleton
+    extend Forwardable
+
+    def_delegators :@storage, :[], :[]=, :store, :delete
+
+    def initialize
+      @storage    = {}
+      @exceptions = []
+    end
+
+    #Makes a key permanent in the cache, so that it won't deleted when {#reset!} is called.
+    #@param [Object] key Key to make permanent
+    #@see #reset!
+    def make_permanent key
+      @exceptions << key unless @exceptions.include? key
+    end
+
+
+    #Stores value to the given key and marks key as permanent, so that it won't deleted when {#reset!} is called.
+    #@param [Object] key Key to make permanent
+    #@param [Object] value Value to store in cache
+    #@see #reset!
+    def store_permanently key, value
+      make_permanent key
+      store key, value
+    end
+
+    #Deletes all keys not maked as permanent from the cache.
+    #@since 0.1.0
+    def reset!
+      @storage.select! { |key, _| @exceptions.include?(key) }
+    end
+  end
+
+  class << self
+    extend Forwardable
+    def_delegators :'QAT::Core.instance', *(QAT::Core.public_instance_methods - Object.public_instance_methods)
+  end
+
+end

data/lib/qat/core/version.rb

@@ -0,0 +1,11 @@
+#encoding: utf-8
+#QAT Module works as a namespace for all sub modules.
+#Some singleton methods are also available, as defined by various sub classes.
+#@since 0.1.0
+module QAT
+  # Namespace for QAT Core implementation
+  class Core
+    # Represents QAT's Core version
+    VERSION = '6.0.0'
+  end
+end

data/lib/qat/core_ext/integer.rb

@@ -0,0 +1,12 @@
+# Integer Class extension
+class Integer
+  # Generates a random integer with a given number of digits
+  # @param length [Integer] number of digits of random integer. Default is 1.
+  # @return [Integer]
+  # @since 1.2.0
+  def self.random(length=1)
+    raise(ArgumentError, 'Argument should be an Integer!') unless length.is_a?(Integer)
+    elements = (0..9).to_a
+    [(1..9).to_a.sample, (length-1).times.map { elements.sample }].flatten.join.to_i
+  end
+end