sc4ry 0.1.7 → 0.2.1

data/lib/sc4ry/backends/redis.rb

@@ -1,65 +1,63 @@
+# frozen_string_literal: true
+
 module Sc4ry
-    module Backends
-        # Redis backend definition
-        class Redis
+  module Backends
+    # Redis backend definition
+    class Redis
+      # Constructor
+      # @param [Hash] config Config map
+      # @return [Sc4ry::Backends::Redis] a Redis backend
+      def initialize(config)
+        @auth = config.slice(:auth)[:auth]
+        @config = config.slice(:host, :port, :db)
+        @be = ::Redis.new @config
+        @be.auth(@auth) if @auth
+      end
+
+      # return the list of find records in backend for a specific pattern
+      # @return [Array] list of record (for all hostname if hostname is specified)
+      def list
+        @be.keys('*').map(&:to_sym)
+      end
+
+      # return value of queried record
+      # @param key [Symbol] the name of the record
+      # @return [String] content value of record
+      def get(key:)
+        res = YAML.load(@be.get(key))
+        res[:exceptions].map! { |item| Object.const_get(item) if item.instance_of?(String) }
+        res
+      end
+
+      # defined and store value for specified key
+      # @param key [Symbol] :key the name of the record
+      # @param value [Symbol] :value the content value of the record
+      # @return [String] content value of record
+      def put(key:, value:)
+        data = value.dup
+        data[:exceptions].map! { |item| item.name.to_s if item.instance_of?(Class) }
+        @be.set key, data.to_yaml
+      end
+
+      # delete a specific record
+      # @param key [Symbol] the name of the record
+      # @return [Boolean] status of the operation
+      def del(key:)
+        @be.del key
+      end
+
+      # flush all records in backend
+      # @return [Boolean] status of the operation
+      def flush
+        @be.flushdb
+      end
 
-        # Constructor
-        # @param [Hash] config Config map 
-        # @return [Sc4ry::Backends::Redis] a Redis backend
-        def initialize(config)
-          @auth = config.slice(:auth)[:auth]
-          @config = config.slice(:host, :port, :db)
-          @be = ::Redis.new @config
-          @be.auth(@auth) if @auth
-        end
-  
-        # return the list of find records in backend for a specific pattern
-        # @return [Array] list of record (for all hostname if hostname is specified)
-        def list
-           return @store.keys('*')
-        end
-  
-  
-        # return value of queried record
-        # @param [Hash] options
-        # @option options [Symbol] :key the name of the record
-        # @return [String] content value of record
-        def get(options)
-          return @store.get(options[:key])
-        end
-  
-        # defined and store value for specified key
-        # @param [Hash] options
-        # @option options [Symbol] :key the name of the record
-        # @option options [Symbol] :value the content value of the record
-        # @return [String] content value of record
-        def put(options)
-          @store.set options[:key], options[:value]
-        end
-  
-        # delete a specific record
-        # @param [Hash] options
-        # @option options [Symbol] :key the name of the record
-        # @return [Boolean] status of the operation
-        def del(options)
-          @store.del options[:key]
-        end
-  
-        # flush all records in backend
-        def flush
-          @store.flushdb
-        end
-  
-        # verifiy a specific record existance
-        # @param [Hash] options
-        # @option options [Symbol] :key the name of the record
-        # @return [Boolean] presence of the record
-        def exist?(options)
-          return ( not @store.get(options[:key]).nil?)
-        end
-      
-  
+      # verifiy a specific record existence
+      # @param key [Symbol] the name of the record
+      # @return [Boolean] presence of the record
+      def exist?(key:)
+        !@be.get(key).nil?
       end
-  
     end
-end  
+  end
+end

data/lib/sc4ry/circuits.rb

@@ -1,86 +1,258 @@
+# frozen_string_literal: true
+
+# Sc4ry Module
+# @note namespace
 module Sc4ry
+  # Circuits and default configuration management class
   class Circuits
+    include Sc4ry::Constants
+    include Sc4ry::Exceptions
+
+    @@circuits_store = Sc4ry::Store.instance
+    @@circuits_notifiers = Sc4ry::Notifiers
+    @@circuits_loggers = Sc4ry::Loggers
+    @@config = DEFAULT_CONFIG
+
+    # @!group forwarders
+
+    # Class method how forward the Notifiers class factory/manager
+    # @return [Sc4ry::Notifiers]
+    def self.notifiers
+      @@circuits_notifiers
+    end
+
+    # Class method how forward a Store manager class singleton
+    # @return [Sc4ry::Store]
+    def self.store
+      @@circuits_store
+    end
+
+    # Class method how forward the Logger manager class factory/manager
+    # @return [Sc4ry::Store]
+    def self.loggers
+      @@circuits_loggers
+    end
+
+    # @!endgroup
+
+    # @!group Default Sc4ry configuration management
+
+    # Class method how return de default Sc4ry config
+    # @return [Hash]
+    def self.default_config
+      @@config
+    end
+
+    # class method how merge a differential hash to default config
+    # @param [Hash] diff the differential hash config
+    # @example usage
+    #   include Sc4ry
+    #   Circuits.merge_default_config diff: {max_time: 20, notifiers: [:mattermost]}
+    def self.merge_default_config(diff:)
+      validator = Sc4ry::Config::Validator.new(definition: diff, from: @@config)
+      validator.validate!
+      @@config = validator.result
+    end
+
+    # class method for specifiying config by block
+    # @yield [Sc4ry::Config::ConfigMapper]
+    # @example usage
+    #   include Sc4ry
+    #   Circuits.configure do |spec|
+    #      spec.max_failure_count = 3
+    #   end
+    def self.configure
+      mapper = Sc4ry::Config::ConfigMapper.new(definition: @@config.dup)
+      yield(mapper)
+      validator = Sc4ry::Config::Validator.new(definition: mapper.config, from: @@config)
+      validator.validate!
+      @@config = validator.result
+    end
+
+    # old default config setter
+    # @deprecated use {.merge_default_config} instead
+    # @param [Hash] config
+    def self.default_config=(config)
+      warning_mess = 'DEPRECATED: Circuits.default_config= use Circuits.merge_default_config add: {<config_hash>}'
+      Sc4ry::Helpers.log level: :warn,
+                         message: warning_mess
+      Circuits.merge_default_config(diff: config)
+    end
 
-    @@circuits_store = Sc4ry::Store.instance 
+    # @!endgroup
 
-    @@config = { :max_failure_count => 5,
-                 :timeout_value => 20,
-                 :timeout => false,
-                 :max_timeout_count => 5,
-                 :max_time => 10,
-                 :max_overtime_count => 3,
-                 :check_delay => 30,
-                 :notifiers => [],
-                 :forward_unknown_exceptions => true,
-                 :raise_on_opening => false,
-                 :exceptions => [StandardError, RuntimeError]
-                 }
+    # @!group Circuits management
 
-    def Circuits.default_config
-      return @@config
+    # class method for registering a new circuit, cloud work with a block
+    # @yield [Sc4ry::Config::ConfigMapper]
+    # @param [Symbol] circuit a circuit name
+    # @param [Hash] config a config override on default config for the circuit
+    # @example usage
+    #   include Sc4ry
+    #   Circuits.register circuit: :mycircuit, config: {raise_on_opening: true, timeout: true}
+    #   # or
+    #   Circuits.register circuit: :mycircuit do |spec|
+    #     spec.raise_on_opening = true
+    #     spec.timeout = true
+    #   end
+    # @return [Hash] the full config of the circuit after merge on default
+    # @raise [Sc4ryGenericError] if use config keyword with a block
+    # @raise [Sc4ryGenericError] if circuit already exist in current store.
+    def self.register(circuit:, config: {})
+      if !config.empty? && block_given?
+        raise Sc4ryGenericError,
+              'config: keyword must not be defined when block is given'
+      end
+
+      if block_given?
+        mapper = Sc4ry::Config::ConfigMapper.new(definition: @@config.dup)
+        yield(mapper)
+        validator = Sc4ry::Config::Validator.new(definition: mapper.config, from: @@config.dup)
+      else
+        validator = Sc4ry::Config::Validator.new(definition: config, from: @@config.dup)
+      end
+      validator.validate!
+      Sc4ry::Helpers.log level: :debug, message: "Circuit #{circuit} : registered"
+      raise Sc4ryGenericError, "Circuit: #{circuit} already exist in store" if @@circuits_store.exist? key: circuit
+
+      @@circuits_store.put key: circuit, value: validator.result
+      validator.result
     end
 
-    def Circuits.default_config=(config)
-      @@config = config
-      @@config[:exceptions].map! {|item| item = Object.const_get item if item.class == String}
+    # class method how list all circuits in current store
+    # @example usage
+    #   include Sc4ry
+    #   circuits = Circuits.list
+    # @return [Array] the list of [Symbol] circuits name
+    def self.list
+      @@circuits_store.list
+    end
 
+    # class method how flush all circuits in current store
+    # @example usage
+    #   include Sc4ry
+    #   Circuits.flush
+    # @return [true,false]
+    def self.flush
+      @@circuits_store.flush
     end
 
-    def Circuits.register(options = {})
-      raise ":circuit is mandatory" unless options[:circuit]
-      name = options[:circuit]
-      override = (options[:config].class == Hash)? options[:config] : {}
-      config = @@config.merge override
-      @@circuits_store.put key: name, value: config 
+    # class method for unregistering a circuit
+    # @param [Symbol] circuit a circuit name
+    # @example usage
+    #   include Sc4ry
+    #   Circuits.unregister circuit: :mycircuit
+    # @raise [Sc4ryGenericError] if circuit not found in current store.
+    # @return [true,false]
+    def self.unregister(circuit:)
+      raise Sc4ryGenericError, "Circuit #{circuit} not found" unless Circuits.list.include? circuit
+
+      @@circuits_store.del key: circuit
+      Sc4ry::Helpers.log level: :debug, message: "Circuit #{circuit} : unregistered"
+      true
     end
 
-    def Circuits.list
-      return @@circuits_store.list
+    # class method for get a specific circuit by circuit name
+    # @param [Symbol] circuit a circuit name
+    # @example usage
+    #   include Sc4ry
+    #   Circuits.get circuit: :mycircuit
+    # @return [Hash] the circuit record in current store included values and status if the circuit have already run.
+    def self.get(circuit:)
+      @@circuits_store.get key: circuit
     end
 
+    # class method for update the config of a specific circuit by circuit name
+    # @param [Symbol] circuit a circuit name
+    # @param [Hash] config a config hash to merge on current config
+    # @example usage
+    #   include Sc4ry
+    #   Circuits.update_config circuit: :mycircuit, config: {}
+    # @note : <b>important</b> updating config will reset status and values !
+    # @return [Hash] new config for this circuit
+    def self.update_config(circuit:, config: { forward_unknown_exceptions: false })
+      raise Sc4ryGenericError, "Circuit #{circuit} not found" unless Circuits.list.include? circuit
+
+      save = @@circuits_store.get key: circuit
+      save.delete_if { |key, _val| %i[status values].include? key }
+      Circuits.unregister(circuit: circuit)
+      save.merge! config
+      Circuits.register circuit: circuit, config: save
+    end
 
-    def Circuits.get(options)
-      @@circuits_store.get key: options[:circuit]
+    # class method for get the status of a specific circuit by circuit name
+    # @param [Symbol] circuit a circuit name
+    # @example usage
+    #   include Sc4ry
+    #   Circuits.status circuit: :mycircuit
+    # @return [Symbol]  status must in [:open,:half_open,:closed,:never_run]
+    def self.status(circuit:)
+      data = @@circuits_store.get key: circuit
+      data.include?(:status) ? data[:status][:general] : :never_run
     end
 
-    def Circuits.run(options = {}, &block)
+    # class method for running circuit, need a block
+    # @yield [Proc]
+    # @param [Symbol] circuit a circuit name
+    # @example usage
+    #   include Sc4ry
+    #   Circuits.run circuit: :mycircuit do
+    #       #  [...]  your code like a Restclient.get("URL")
+    #   end
+    #   # or
+    #   Circuits.run do
+    #        # [...] your code like a Restclient.get("URL")
+    #        #  running with the first define circuit (use only on a one circuit usage)
+    #   end
+    # @return [Hash] a result like ":general=>:open, :failure_count=>X, :overtime_count=>X, :timeout_count=>X"
+    # @raise [Sc4ryGenericError] if circuit already not exit, block is missing or store empty
+    def self.run(circuit: nil, &block)
       circuits_list = Circuits.list
-      raise "No circuit block given" unless block_given?
-      raise "No circuits defined" if circuits_list.empty? 
-      circuit_name = (options[:circuit])? options[:circuit] : circuits_list.first
-      raise "Circuit #{circuit_name} not found" unless circuits_list.include? circuit_name
-      circuit = Circuits.get circuit: circuit_name
+      raise Sc4ryGenericError, 'No circuit block given' unless block_given?
+      raise Sc4ryGenericError, 'No circuits defined' if circuits_list.empty?
+
+      circuit_name = circuit || circuits_list.first
+      raise Sc4ryGenericError, "Circuit #{circuit_name} not found" unless circuits_list.include? circuit_name
+
+      circuit_to_run = Circuits.get circuit: circuit_name
       skip = false
-      if circuit.include? :status then
-        if circuit[:status][:general] == :open then 
-          @now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-          skip = true if ((@now - circuit[:values].last[:end_time]) <  circuit[:check_delay])
-        end
+      if circuit_to_run.include?(:status) && (circuit_to_run[:status][:general] == :open)
+        @now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        skip = true if (@now - circuit_to_run[:values].last[:end_time]) < circuit_to_run[:check_delay]
       end
-      unless skip 
-        controller = Sc4ry::RunController.new(circuit)
+      unless skip
+        controller = Sc4ry::RunController.new(circuit_to_run)
         Circuits.control circuit: circuit_name, values: controller.run(block: block)
       end
-      Sc4ry::Helpers.log level: :info, message: "Circuit #{circuit_name} : status #{circuit[:status]}"
-
+      result = @@circuits_store.get key: circuit_name
+      Sc4ry::Helpers.log level: :debug, message: "Circuit #{circuit_name} : status #{result[:status]}"
+      result
     end
 
-    private
-    def Circuits.control(options={})
-      data = @@circuits_store.get key: options[:circuit]
-      data[:status] = {:general => :closed, :failure_count => 0, :overtime_count => 0, :timeout_count => 0} unless data.include? :status
-      data[:values] = Array::new unless data.include? :values
+    # @!endgroup
+
+    # the private class method to control circuits running status
+    # @param [Symbol] circuit the name the circuit to control
+    # @param [Hash] values the resut value of a run
+    # @return [Boolean]
+    def self.control(circuit:, values:)
+      data = @@circuits_store.get key: circuit
+      unless data.include? :status
+        data[:status] =
+          { general: :closed, failure_count: 0, overtime_count: 0, timeout_count: 0 }
+      end
+      data[:values] = [] unless data.include? :values
       level = [data[:max_failure_count].to_i, data[:max_timeout_count].to_i, data[:max_overtime_count].to_i].max
       data[:values].shift if data[:values].size > level
-      data[:values].push options[:values]
+      data[:values].push values
       worst_status = []
-      ['failure','overtime','timeout'].each do |control|
-        if options[:values][control.to_sym] == true then
+      %w[failure overtime timeout].each do |control|
+        if values[control.to_sym] == true
           data[:status]["#{control}_count".to_sym] += 1
         else
           data[:status]["#{control}_count".to_sym] = 0
         end
-    
+
         case data[:status]["#{control}_count".to_sym]
         when 0
           worst_status.push :closed
@@ -91,14 +263,23 @@ module Sc4ry
         end
       end
       save = data[:status][:general]
-      [:closed,:half_open,:open].each do |status|
+      %i[closed half_open open].each do |status|
         data[:status][:general] = status if worst_status.include? status
       end
-      if save != data[:status][:general] then
-        raise Sc4ry::Exceptions::CircuitBreaked if data[:status][:general] == :open and data[:raise_on_opening]
-        Sc4ry::Helpers.notify circuit: options[:circuit], config: data 
-      end          
-      @@circuits_store.put key: options[:circuit], value: data
+      if save != data[:status][:general]
+        raise CircuitBreaked if data[:status][:general] == :open && data[:raise_on_opening]
+
+        if data[:status][:general] == :open
+          Sc4ry::Helpers.log level: :error,
+                             message: "Circuit #{circuit} : breacking ! "
+        end
+        if data[:status][:general] == :closed
+          Sc4ry::Helpers.log level: :info,
+                             message: "Circuit #{circuit} : is now closed"
+        end
+        Sc4ry::Helpers.notify circuit: circuit, config: data
+      end
+      @@circuits_store.put key: circuit, value: data
     end
   end
-end
+end

data/lib/sc4ry/config.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+# Sc4ry module
+# @note namespace
+module Sc4ry
+  # Sc4ry::Config module
+  # @note namespace
+  module Config
+    # Configuration validator for Sc4ry default and circuits configuration
+    # @private
+    class Validator
+      # accessor on Circuit definition given for validation
+      attr_reader :input
+
+      # accessor on circuit initial definition from default config or given in construction by from keyword
+      # @note altered by reference to final result mapping with {#validate!}
+      attr_reader :config
+
+      def result
+        @config
+      end
+
+      include Sc4ry::Constants
+      include Sc4ry::Exceptions
+      # Validator constructor
+      # @param [Hash] definition the config hash to merge and validate
+      # @param [Hash] from config hash merged on origin (default : the Sc4ry base config from Constants )
+      # @return [Validator] a new instance of Validator
+      def initialize(definition:, from: DEFAULT_CONFIG)
+        @config = from
+        @input = definition
+      end
+
+      # Validation method, alter by reference the config attribut
+      # @raise ConfigError if un unknown key is given in definition to merge.
+      def validate!
+        unknown_keys = @input.keys.difference @config.keys
+        raise ConfigError, "Unknown keys in config set : #{unknown_keys}" unless unknown_keys.empty?
+
+        validate_formats
+        @config.merge! @input
+        format_exceptions
+      end
+
+      private
+
+      # Validation private sub method
+      # @raise ConfigError if proposed values haven't the good format and deeply in array
+      def validate_formats
+        @input.each do |spec, value|
+          unless DEFAULT_CONFIG_FORMATS[spec][:proc].call(value)
+            raise ConfigError,
+                  "#{spec} value #{DEFAULT_CONFIG_FORMATS[spec][:desc]}"
+          end
+
+          next unless DEFAULT_CONFIG_FORMATS[spec].include? :list
+
+          value.each do |item|
+            unless DEFAULT_CONFIG_FORMATS[spec][:list].include? item
+              raise ConfigError,
+                    "#{spec} value must be in #{DEFAULT_CONFIG_FORMATS[spec][:list]}"
+            end
+          end
+        end
+      end
+
+      # adapter for exception key in config String to Constant Class Name if need
+      # @note by reference
+      def format_exceptions
+        @config[:exceptions].map! { |item| item.instance_of?(String) ? Object.const_get(item) : item }
+      end
+    end
+
+    # Config Data mapper for block yielding methods for configuration
+    # @note work for/with {Sc4ry::Circuits.configure} and {Sc4ry::Circuits.register} when block given
+    class ConfigMapper
+      include Sc4ry::Constants
+
+      # config from given definition passed in constructor
+      attr_reader :config
+
+      # the mapping constructor from a given definition or the default From Sc4ry config (Constant)
+      # @param [Hash] definition a config hash
+      # @note creating dynamically accessors on config record given in definition
+      def initialize(definition: DEFAULT_CONFIG)
+        @config = definition
+        @config.each do |key, _value|
+          define_singleton_method "#{key}=".to_sym do |val|
+            key = __method__.to_s.chop.to_sym
+            @config[key] = val
+          end
+          define_singleton_method key do
+            return @config[__method__]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sc4ry/constants.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# Sc4ry module
+# @note namespace
+module Sc4ry
+  # Sc4ry::Constants module
+  # @note namespace
+  module Constants
+    # notifiers available in Sc4ry natively
+    CURRENT_NOTIFIERS = %i[prometheus mattermost]
+
+    # the Sc4ry default config entries and values
+    DEFAULT_CONFIG = {
+      max_failure_count: 5,
+      timeout_value: 20,
+      timeout: false,
+      max_timeout_count: 5,
+      max_time: 10,
+      max_overtime_count: 3,
+      check_delay: 30,
+      notifiers: [],
+      forward_unknown_exceptions: true,
+      raise_on_opening: false,
+      exceptions: [StandardError, RuntimeError]
+    }
+
+    # Default config supported entries with format and Proc checker for {Sc4ry::Config::Validator}
+    DEFAULT_CONFIG_FORMATS = {
+      max_failure_count: { proc: proc { |item| item.instance_of?(Integer) }, desc: 'must be an Integer' },
+      timeout_value: { proc: proc { |item| item.instance_of?(Integer) }, desc: 'must be an Integer' },
+      timeout: { proc: proc { |item| [true, false].include? item }, desc: 'must be a Boolean' },
+      max_timeout_count: { proc: proc { |item| item.instance_of?(Integer) }, desc: 'must be an Integer' },
+      max_time: { proc: proc { |item| item.instance_of?(Integer) }, desc: 'must be an Integer' },
+      max_overtime_count: { proc: proc { |item| item.instance_of?(Integer) }, desc: 'must be an Integer' },
+      check_delay: { proc: proc { |item| item.instance_of?(Integer) }, desc: 'must be an Integer' },
+      notifiers: {
+        proc: proc do |item|
+                item.instance_of?(Array) and item.select { |val| val.instance_of?(Symbol) }.size == item.size
+              end,
+        desc: 'must be an Array of Symbol',
+        list: CURRENT_NOTIFIERS
+      },
+      forward_unknown_exceptions: { proc: proc { |item| [true, false].include? item }, desc: 'must be a Boolean' },
+      raise_on_opening: { proc: proc { |item| [true, false].include? item }, desc: 'must be a Boolean' },
+      exceptions: {
+        proc: proc do |item|
+                item.instance_of?(Array) and item.select do |val|
+                  [Class, String].include? val.class
+                end.size == item.size
+              end,
+        desc: 'must be an Array of Exception(Class) or String'
+      }
+    }
+  end
+end

data/lib/sc4ry/dependencies.rb

@@ -1,8 +1,14 @@
+# frozen_string_literal: true
+
+# rubygems depends
 require 'rest-client'
 require 'prometheus/client'
 require 'prometheus/client/push'
+require 'redis'
+require 'version'
 
-require 'logger' 
+# Stdlibs depends
+require 'logger'
 require 'timeout'
 require 'forwardable'
 require 'singleton'
@@ -11,15 +17,18 @@ require 'openssl'
 require 'net/http'
 require 'uri'
 require 'json'
+require 'yaml'
 
-
-
+# Sc4ry internal depends
 require_relative 'helpers'
 require_relative 'exceptions'
 require_relative 'logger'
+require_relative 'constants'
+require_relative 'config'
+require_relative 'notifiers/init'
+require_relative 'exporters/init'
 require_relative 'backends/init'
+
 require_relative 'store'
 require_relative 'run_controller'
 require_relative 'circuits'
-require_relative 'notifiers/init'
-require_relative 'exporters/init'