sc4ry 0.1.6 → 0.2.0

data/lib/sc4ry/circuits.rb

@@ -1,79 +1,254 @@
+# 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 Circuits.notifiers
+      return @@circuits_notifiers
+    end
+
+    # Class method how forward a Store manager class singleton
+    # @return [Sc4ry::Store]
+    def Circuits.store
+      return @@circuits_store
+    end
+
+    # Class method how forward the Logger manager class factory/manager
+    # @return [Sc4ry::Store]
+    def Circuits.loggers
+      return @@circuits_loggers
+    end
+
 
-    @@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]
-                 }
 
+    # @!endgroup
+
+
+    # @!group Default Sc4ry configuration management
+
+    # Class method how return de default Sc4ry config
+    # @return [Hash] 
     def Circuits.default_config
       return @@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 Circuits.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 Circuits.configure(&bloc)
+      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 Circuits.default_config=(config)
-      @@config = config
+      Sc4ry::Helpers.log level: :warn, message: "DEPRECATED: Circuits.default_config= is deprecated please use Circuits.merge_default_config add: {<config_hash>}"
+      Circuits.merge_default_config(diff: config)
     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 
+    # @!endgroup
+
+    # @!group Circuits management
+
+    # 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 Circuits.register(circuit:, config: {})
+      if config.size > 0 and block_given? then 
+        raise Sc4ryGenericError, "config: keyword must not be defined when block is given"
+      end
+      if block_given? then 
+        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 
+      return validator.result
     end
 
+    # 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 Circuits.list
       return @@circuits_store.list
     end
 
+    # class method how flush all circuits in current store
+    # @example usage
+    #   include Sc4ry 
+    #   Circuits.flush
+    # @return [true,false] 
+    def Circuits.flush
+      return @@circuits_store.flush
+    end
 
-    def Circuits.get(options)
-      @@circuits_store.get key: options[:circuit]
+    # 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 Circuits.unregister(circuit:)
+      if Circuits.list.include? circuit then
+        @@circuits_store.del key: circuit
+        return true
+      else
+        raise Sc4ryGenericError, "Circuit #{circuit} not found"
+        return false
+      end
     end
 
-    def Circuits.run(options = {}, &block)
+
+    # 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 Circuits.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 Circuits.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| [:status,:values].include? key}
+      Circuits.unregister(circuit: circuit)
+      save.merge! config
+      return Circuits.register circuit: circuit, config: save 
+    end
+
+    # 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 Circuits.status(circuit:)
+      data = @@circuits_store.get key: circuit
+      return (data.include? :status)? data[:status][:general] : :never_run
+    end
+
+
+    # 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 Circuits.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)? 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 
+      if circuit_to_run.include? :status then
+        if circuit_to_run[:status][:general] == :open then 
           @now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-          skip = true if ((@now - circuit[:values].last[:end_time]) <  circuit[:check_delay])
+          skip = true if ((@now - circuit_to_run[:values].last[:end_time]) <  circuit_to_run[:check_delay])
         end
       end
       unless skip 
-        controller = Sc4ry::RunController.new(circuit)
+        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]}"
+      return result
     end
 
+    # @!endgroup
+
     private
-    def Circuits.control(options={})
-      data = @@circuits_store.get key: options[:circuit]
+    # 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 Circuits.control(circuit: , values: )
+      data = @@circuits_store.get key: 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
       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
+        if values[control.to_sym] == true then
           data[:status]["#{control}_count".to_sym] += 1
         else
           data[:status]["#{control}_count".to_sym] = 0
@@ -93,10 +268,12 @@ module Sc4ry
         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 
+        raise CircuitBreaked if data[:status][:general] == :open and data[:raise_on_opening]
+        Sc4ry::Helpers.log level: :error, message: "Circuit #{circuit} : breacking ! " if data[:status][:general] == :open
+        Sc4ry::Helpers.log level: :info, message: "Circuit #{circuit} : is now closed" if data[:status][:general] == :closed
+        Sc4ry::Helpers.notify circuit: circuit, config: data 
       end          
-      @@circuits_store.put key: options[:circuit], value: data
+      @@circuits_store.put key: circuit, value: data
     end
   end
 end

data/lib/sc4ry/config.rb

@@ -0,0 +1,91 @@
+# 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::new("Unknown keys in config set : #{unknown_keys.to_s}") 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|
+                    raise ConfigError::new("#{spec} value #{DEFAULT_CONFIG_FORMATS[spec][:desc]}") unless DEFAULT_CONFIG_FORMATS[spec][:proc].call(value)
+                    if DEFAULT_CONFIG_FORMATS[spec].include? :list then
+                        value.each do |item|
+                            raise ConfigError::new("#{spec} value must be in #{DEFAULT_CONFIG_FORMATS[spec][:list]}") unless DEFAULT_CONFIG_FORMATS[spec][:list].include? item
+                        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 = (item.class == 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|
+                    self.define_singleton_method "#{key.to_s}=".to_sym do |val|
+                        key = __method__.to_s.chop.to_sym
+                        @config[key]=val
+                    end
+                    self.define_singleton_method key do 
+                        return @config[__method__]
+                    end
+                end
+            end
+        end
+
+    end
+end

data/lib/sc4ry/constants.rb

@@ -0,0 +1,51 @@
+# Sc4ry module
+# @note namespace
+module Sc4ry
+    # Sc4ry::Constants module
+    # @note namespace
+    module Constants
+
+        # notifiers available in Sc4ry natively
+        CURRENT_NOTIFIERS = [: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::new {|item| item.class == Integer}, :desc => "must be an Integer"}, 
+            :timeout_value => {:proc => Proc::new {|item| item.class == Integer}, :desc => "must be an Integer"},
+            :timeout => {:proc => Proc::new {|item| [true,false].include? item}, :desc => "must be a Boolean"},
+            :max_timeout_count => {:proc => Proc::new {|item| item.class == Integer}, :desc => "must be an Integer"},
+            :max_time => {:proc => Proc::new {|item| item.class == Integer}, :desc => "must be an Integer"},
+            :max_overtime_count => {:proc => Proc::new {|item| item.class == Integer}, :desc => "must be an Integer"},
+            :check_delay => {:proc => Proc::new {|item| item.class == Integer}, :desc => "must be an Integer"},
+            :notifiers => {
+                :proc => Proc::new {|item| 
+                  item.class == Array and item.select {|val|  val.class == Symbol }.size == item.size
+                  }, 
+                :desc => "must be an Array of Symbol",
+                :list => CURRENT_NOTIFIERS},
+            :forward_unknown_exceptions => {:proc => Proc::new {|item| [true,false].include? item}, :desc => "must be a Boolean"},
+            :raise_on_opening => {:proc => Proc::new {|item| [true,false].include? item}, :desc => "must be a Boolean"},
+            :exceptions => {
+                :proc => Proc::new {|item| item.class == Array and item.select {|val|  
+                    [Class,String].include? val.class}.size == item.size
+                }, 
+                :desc => "must be an Array of Exception(Class) or String"}
+            }
+
+    end
+end

data/lib/sc4ry/dependencies.rb

@@ -1,7 +1,11 @@
+# rubygems depends
 require 'rest-client'
 require 'prometheus/client'
 require 'prometheus/client/push'
+require 'redis'
+require 'version'
 
+# Stdlibs depends
 require 'logger' 
 require 'timeout'
 require 'forwardable'
@@ -11,15 +15,20 @@ 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'
+

data/lib/sc4ry/exceptions.rb

@@ -1,5 +1,12 @@
+# Sc4ry module
+# @note namespace
 module Sc4ry
+
+    # Sc4ry::Exceptions module
+    # @note namespace
     module Exceptions
+
+        # Exception use in {Sc4ry::Circuits} when running circuit {Sc4ry::Circuits::run} 
         class CircuitBreaked < StandardError
             def initialize(msg="Circuit just opened")
                 super(msg)
@@ -7,5 +14,37 @@ module Sc4ry
         
         end
 
+        # Generic Exception use in {Sc4ry::Circuits} 
+        class Sc4ryGenericError < StandardError
+            def initialize(msg="")
+                super(msg)
+              end
+        
+        end
+
+        # Exception use in {Sc4ry::Store} or/and {Sc4ry::Backend} on data string issues
+        class Sc4ryBackendError < StandardError
+            def initialize(msg="")
+                super(msg)
+              end
+        
+        end
+
+        # Exception use in {Sc4ry::Notifiers} on notification issues
+        class Sc4ryNotifierError < StandardError
+            def initialize(msg="")
+                super(msg)
+              end
+        
+        end
+        
+        # Exception use in {Sc4ry::Circuits} on config management issues
+        class ConfigError < StandardError
+            def initialize(msg="")
+                super(msg)
+              end
+        
+        end
+
     end
 end

data/lib/sc4ry/helpers.rb

@@ -1,10 +1,22 @@
-
+# Sc4ry module
+# @note namespace
 module Sc4ry
-  module Helpers
 
-    def Helpers.log(options)
-      Sc4ry::Logger.current = options[:target] if options[:target]
-      Sc4ry::Logger.get.send options[:level], "Sc4ry : #{options[:message]}"  
+# Sc4ry::Helpers module
+# @note namespace
+   module Helpers
+
+    # class method (module) to help logging messages
+    # @param [Symbol] target a specific logger, restored old after
+    # @param [Symbol] level (default :info) a logging level (see Logger Stdlib)
+    # @param [String] message your message
+    # @return [Boolean]
+    def Helpers.log(target: nil, level: :info, message:  )
+      save = Sc4ry::Loggers.current 
+      Sc4ry::Loggers.current = target if target
+      Sc4ry::Loggers.get.send level, "Sc4ry : #{message}"  
+      Sc4ry::Loggers.current = save
+      return true
     end
 
     # TCP/IP service checker
@@ -37,7 +49,9 @@ module Sc4ry
       end
     end
 
-
+    # class method (module) to help send notifiesby Sc4ry::Notifiers
+    # @param [Hash] options a Notifying structure
+    # @return [Boolean]
     def Helpers.notify(options = {})
       Sc4ry::Notifiers.list.each do |record|
         notifier = Sc4ry::Notifiers.get name: record

data/lib/sc4ry/logger.rb

@@ -1,29 +1,65 @@
-
+# Sc4ry module
+# @note namespace
 module Sc4ry
-  class Logger
+
+  # Sc4ry loggers Factory/provider
+  # @note must be accessed by [Sc4ry::Circuits.loggers]
+  class Loggers
     
     @@loggers = {:stdout => ::Logger.new(STDOUT)}
     @@current = :stdout
     
-    def Logger.list_avaible
-      return @@loggers
+    # give the list of available loggers (initially internal Sc4ry logger )
+    # @return [Array] of [symbol] the list of defined loggers
+    # @note default :stdout => ::Logger(STDOUT) from Ruby Stdlib
+    # @example usage
+    #    include Sc4ry
+    #    Circuits.loggers.list_available.each {|logger| puts logger }
+    def Loggers.list_available
+      return @@loggers.keys
     end
     
-    def Logger.current
+    # return the current logger name (initially :stdtout )
+    # @return [symbol] the name of the logger
+    # @example usage
+    #    include Sc4ry
+    #    puts Circuits.loggers.current
+    def Loggers.current
       return @@current
     end
     
-    def Logger.get
+    # return the current logger Object (initially internal Sc4ry Stdlib Logger on STDOUT )
+    # @return [symbol] the name of the logger
+    # @example usage
+    #    include Sc4ry
+    #    Circuits.loggers.get :stdout
+    def Loggers.get
       return @@loggers[@@current]
     end
     
-    def Logger.current=(sym)
+    # Set the current logger 
+    # @param [Symbol] sym the name of the logger
+    # @return [symbol] the name of the logger updated
+    # @example usage
+    #    include Sc4ry
+    #    Circuits.loggers.current = :newlogger
+    def Loggers.current=(sym)
       raise "Logger not define : #{sym}" unless @@loggers.keys.include? sym
       @@current = sym
+      return @@current
     end
     
-    def Logger.register(options = {})
-      @@loggers[options[:name]] = options[:instance] 
+    # register un new logger
+    # @param [Symbol] name the name of the new logger
+    # @param [Object] instance the new logger object
+    # raise Sc4ry::Exceptions::Sc4ryGenericError if name is not a Symbol
+    # @example usage
+    #    include Sc4ry
+    #    Circuits.loggers.register name: :newlogger, instance: Logger::new('/path/to/my.log') 
+    def Loggers.register(name: , instance: )
+      raise Sc4ry::Exceptions::Sc4ryGenericError, "name: keyword must be a Symbol" unless name.class == Symbol
+      @@loggers[name] = instance
+      return name
     end
     
   end