sc4ry 0.1.8 → 0.2.0

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,9 +15,10 @@ require 'openssl'
 require 'net/http'
 require 'uri'
 require 'json'
+require 'yaml'
 
 
-
+# Sc4ry internal depends
 require_relative 'helpers'
 require_relative 'exceptions'
 require_relative 'logger'

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,15 +14,33 @@ module Sc4ry
         
         end
 
+        # Generic Exception use in {Sc4ry::Circuits} 
         class Sc4ryGenericError < StandardError
-            def initialize(msg)
+            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)
+            def initialize(msg="")
                 super(msg)
               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

data/lib/sc4ry/notifiers/init.rb

@@ -1,32 +1,56 @@
 Dir[File.dirname(__FILE__) + '/*.rb'].sort.each { |file| require file unless File.basename(file) == 'init.rb' }
 
+# Sc4ry module
+# @note namespace
 module Sc4ry 
-  module Notifiers
 
+  # Sc4ry::Notifiers module 
+  # @note namespace 
+    module Notifiers
+
+    # default notifiers specifications
     DEFAULT_NOTIFIERS = {:prometheus => {:class => Sc4ry::Notifiers::Prometheus, :config => {:url => 'http://localhost:9091'}},
                           :mattermost => {:class => Sc4ry::Notifiers::Mattermost, :config => {:url => 'http://localhost:9999', :token => "<CHANGE_ME>"}}
                         }
     @@notifiers_list =  DEFAULT_NOTIFIERS.dup                           
   
+    # class method how display a specific notifier config
+    # @param notifier [Symbol] a notifier name
+    # @return [Hash] the config                     
+    def Notifiers.display_config(notifier: )
+      raise Sc4ry::Exceptions::Sc4ryNotifierError, "Notifier #{notifier} not found" unless @@notifiers_list.include? notifier
+      return @@notifiers_list[notifier][:config]
+    end
 
+    # class method how return the list of known notifiers
+    # @return [Array] a list of [Symbol] notifiers name
     def Notifiers.list
       return @@notifiers_list.keys
     end
 
-    def Notifiers.get(options ={})
-      return @@notifiers_list[options[:name]]
+    # class method how return a specific notifier by name
+    # @param name [Symbol] a notifier name
+    # @return [Hash] the notifier structure                     
+    def Notifiers.get(name: )
+      return @@notifiers_list[name]
     end
 
-    def Notifiers.register(options)
-      raise ":name is mandatory" unless options[:name]
-      raise ":definition is mandatory" unless options[:definition]
-      @@notifiers_list[options[:name]] = options[:definition]
+    # class method how register a specific notifier 
+    # @param name [Symbol] a notifier name
+    # @param definition [Hash] a notifier definition 
+    # @return [Hash] the notifier structure                     
+    def Notifiers.register(name: , definition: )
+      @@notifiers_list[name] = definition
     end
 
-    def Notifiers.config(options)
-      raise ":name is mandatory" unless options[:name]
-      raise ":config is mandatory" unless options[:config]
-      @@notifiers_list[options[:name]][:config] = options[:config]
+    
+    # class method how configure a specific notifier 
+    # @param name [Symbol] a notifier name
+    # @param config [Hash] a notifier config  
+    # @return [Hash] the notifier structure                     
+    def Notifiers.config(name:, config: )
+      @@notifiers_list[name][:config] = config
+      return config
     end
  end
 end

data/lib/sc4ry/notifiers/mattermost.rb

@@ -1,12 +1,17 @@
+# Sc4ry module
+# @note namespace 
 module Sc4ry
+    # Sc4ry::Notifiers module
+    # @note namespace
     module Notifiers
         
+        # Mattermost Notifier class
         class Mattermost
             
             # send metrics to Prometheus PushGateway
             # @return [Bool]
             def Mattermost.notify(options = {})
-                config = Sc4ry::Notifiers.get({name: :mattermost})[:config]
+                config = Sc4ry::Notifiers.get(name: :mattermost)[:config]
                 status = options[:config][:status][:general]
                 circuit = options[:circuit]
                 status_map = {:open => 0, :half_open => 1, :closed => 2}
@@ -20,7 +25,7 @@ module Sc4ry
                             use_ssl: uri.scheme == "https",
                         }
                         payload = { "text" => "message : #{message } from #{Socket.gethostname}", "username" => "Sc4ry" }
-                        Sc4ry::Helpers.log level: :debug, message: "Mattermost Notifier : #{message}"
+                        Sc4ry::Helpers.log level: :debug, message: "Mattermost Notifying : #{message}"
                         request.body = ::JSON.dump(payload)
                         response = ::Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
                             http.request(request)

data/lib/sc4ry/notifiers/prometheus.rb

@@ -1,7 +1,13 @@
+# Sc4ry module
+# @note namespace
 module Sc4ry
+
+  # Sc4ry::Notifiers module
+  # @note namespace
   module Notifiers
 
   
+    # Prometheus notifier class
     class Prometheus
 
       @@registry = ::Prometheus::Client::Registry::new
@@ -14,7 +20,7 @@ module Sc4ry
       # send metrics to Prometheus PushGateway
       # @return [Bool]
       def Prometheus.notify(options = {})
-        @config = Sc4ry::Notifiers.get({name: :prometheus})[:config]
+        @config = Sc4ry::Notifiers.get(name: :prometheus)[:config]
         status = options[:config][:status][:general]
         circuit = options[:circuit]
         status_map = {:open => 0, :half_open => 1, :closed => 2}

data/lib/sc4ry/run_controller.rb

@@ -1,9 +1,16 @@
 
+# Sc4ry module
+# @note namespace 
 module Sc4ry
+
+  # class Facility to run and update values/status for a circuit Proc
   class RunController
 
+    # return the execution time of the proc
     attr_reader :execution_time
 
+    # constructor
+    # @param [Hash] circuit the data of the circuit 
     def initialize(circuit = {})
       @circuit = circuit
       @execution_time = 0
@@ -12,38 +19,47 @@ module Sc4ry
       @overtime = false
     end
 
+    # return if the Proc failed on a covered exception by this circuit
+    # @return [Boolean]
     def failed?
       return @failure
     end 
-    
+
+    # return if the Proc overtime the specified time of the circuit
+    # @return [Boolean]
     def overtimed? 
       return @overtime
     end
 
+    # return if the Proc timeout the timeout defined value of the circuit, if timeout is active
+    # @return [Boolean]
     def timeout? 
       return @timeout
     end
 
-    
-    def run(options = {})
+    # run and update values for the bloc given by keyword
+    # @param [Proc] block a block to run and calculate
+    # @return [Hash] a result Hash
+    def run(block: )
       start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       begin 
         if @circuit[:timeout] == true
           Timeout::timeout(@circuit[:timeout_value]) do 
-            options[:block].call
+            block.call
           end
           @timeout = false
         else
-          options[:block].call
+          block.call
         end
       rescue Exception => e
-        @last_exception = e.class
+        @last_exception = e.class.to_s
         if e.class  == Timeout::Error then 
           @timeout = true
         elsif @circuit[:exceptions].include? e.class
           @failure = true
         else  
           if @circuit[:forward_unknown_exceptions] then
+
             raise e.class, "Sc4ry forward: #{e.message}" 
           else
             Sc4ry::Helpers.log level: :debug, message: "skipped : #{@last_exception}"

data/lib/sc4ry/store.rb

@@ -1,4 +1,10 @@
+# Sc4ry module
+# @note namespace
 module Sc4ry
+
+# Sc4ry::Store class
+# Store Class Provider/manager singleton Forwarder on {Sc4ry::Backends::Memory} or {Sc4ry::Backends::Redis}
+# @note must be accessed by {Sc4ry::Circuits.store}
   class Store
 
     @@current = :memory
@@ -6,35 +12,92 @@ module Sc4ry
     extend Forwardable
     include Singleton
 
-    @@backends = {:memory => {:class => Sc4ry::Backends::Memory},
+    @@backends = {:memory => {:class => Sc4ry::Backends::Memory, config: {}},
                   :redis  => {:class => Sc4ry::Backends::Redis, :config => {:host => 'localhost', :port => 6379, :db => 10 }}}
 
+    # accessor on current backend (default :memory)
     attr_reader :be
+    
     def_delegators :@be, :put, :get, :flush, :exist?, :del, :list
 
+    # constructor pointing on :memory backend
     def initialize
       change_backend name: @@current 
     end 
 
+    # return the current backend
+    # @return [Object] in {Sc4ry::Backends::Memory} or {Sc4ry::Backends::Redis}
+    # @example usage
+    #    include Sc4ry
+    #    puts Circuits.store.current
     def current
       return @@current
     end
 
-    def change_backend(options)
-      @@current = options[:name]
+    # return  the config of a specific backend
+    # @param [Symbol] backend the name the backend 
+    # @return [Hash] the config of the backend 
+    # @raise  Sc4ry::Exceptions::Sc4ryBackendError if backend is not found
+    # @example usage
+    #    include Sc4ry
+    #    puts Circuits.store.get_config backend: :redis
+    def get_config(backend: )
+      raise Sc4ry::Exceptions::Sc4ryBackendError, "backend #{backend} not found" unless @@backends.include? backend
+      return @@backends[backend][:config]
+    end
+
+    # list backend available  
+    # @return [Array] of Symbol the list of backend name
+    # @example usage
+    #    include Sc4ry
+    #    puts Circuits.store.list_backend
+    def list_backend
+      return @@backends.keys
+    end
+
+    # change the current backend 
+    # @note if changing form :memory to :redis => all values and result are lost and circuits will be lost 
+    # @note if changing to :redis, get all the define circuits with values and status (ideal) for distributed worker/instance/runner/services
+    # @param [Symbol] name the name of the target backend
+    # @return [Symbol] the name of the new current backend
+    # @raise Sc4ry::Exceptions::Sc4ryBackendError if backend is not found
+    def change_backend(name: )
+      raise Sc4ry::Exceptions::Sc4ryBackendError, "backend #{name} not found" unless @@backends.include? name
+      @@current =  name
       @be = @@backends[@@current][:class]::new(@@backends[@@current][:config])
+      return name
     end
 
-    def register_backend(options)
-      raise ":name is mandatory" unless options[:name]
-      raise ":definition is mandatory" unless options[:definition]
-      @@backends[options[:name]] = options[:definition]
+    # register a new backend 
+    # @param [Symbol] name the name of the backend
+    # @param [Hash] config the config for this backend
+    # @param [Class] backend_class the class name of the new backend 
+    # @raise Sc4ry::Exceptions::Sc4ryBackendError if backend already exist
+    # @return [Symbol] the name of the backend  
+    def register_backend(name:, config: {}, backend_class:)
+      raise Sc4ry::Exceptions::Sc4ryBackendError , "backend #{name} already exist" if @@backends.include? name
+      @@backends[name] = {config: config, class: backend_class}
+      return name
     end
 
-    def config_backend(options)
-      raise ":name is mandatory" unless options[:name]
-      raise ":config is mandatory" unless options[:config]
-      @@backends[options[:name]][:config] = options[:config]
+    # delete the specified backend reference
+    # @param [Symbol] name the name of the target backend
+    # @raise Sc4ry::Exceptions::Sc4ryBackendError if backend is not found, or name == :memory or :redis
+    # @return [Boolean]
+    def delete_backend(name: )
+      raise Sc4ry::Exceptions::Sc4ryBackendError , "Delete forbidden for backend in [:redis,:memory]" if [:memory,:redis].include? name
+      raise Sc4ry::Exceptions::Sc4ryBackendError , "backend #{name} not found" unless @@backends.include? name
+      return @@backends.delete(name)
+    end
+ 
+    # change the specified backend config
+    # @param [Symbol] name the name of the target backend
+    # @param [Hash] config the config of the specified backend
+    # @raise Sc4ry::Exceptions::Sc4ryBackendError if backend is not found, or name == :memory
+    def config_backend(name:, config:)
+      raise Sc4ry::Exceptions::Sc4ryBackendError, "backend #{name} not found" unless @@backends.include? name
+      raise Sc4ry::Exceptions::Sc4ryBackendError, "backend :memory not need config" if name == :memory
+      @@backends[name][:config] = config
     end
 
 

data/lib/sc4ry/version.rb

@@ -1,3 +1,9 @@
+require 'version'
+
+# Sc4ry module
+# @note namespace
 module Sc4ry
-  VERSION = "0.1.8"
+
+  # the version of Sc4ry
+  VERSION = Version.current
 end

data/sc4ry.gemspec

@@ -1,8 +1,7 @@
-require_relative 'lib/sc4ry/version'
 
 Gem::Specification.new do |spec|
   spec.name          = "sc4ry"
-  spec.version       = Sc4ry::VERSION
+  spec.version       = `cat VERSION`.chomp
   spec.authors       = ["Romain GEORGES"]
   spec.email         = ["romain.georges@orange.com"]
 
@@ -22,6 +21,11 @@ Gem::Specification.new do |spec|
   
   spec.add_dependency "prometheus-client", "~> 3.0"
   spec.add_dependency "rest-client", "~> 2.1"
+  spec.add_dependency "redis", "~> 4.6"
 
-
+  spec.add_development_dependency "yard", "~> 0.9.27"
+  spec.add_development_dependency 'code_statistics', '~> 0.2.13'
+  spec.add_development_dependency "yard-rspec", "~> 0.1"
+  spec.add_development_dependency "roodi", "~> 5.0"
+  spec.add_dependency "version", "~> 1.1"
 end

data/ultragreen_roodi_coding_convention.yml

@@ -0,0 +1,25 @@
+AssignmentInConditionalCheck:
+CaseMissingElseCheck:
+ClassLineCountCheck:             
+  line_count: 300 # including comments yard
+ClassNameCheck:                  
+  pattern: !ruby/regexp /^[A-Z][a-zA-Z0-9]*$/
+#ClassVariableCheck:
+CyclomaticComplexityBlockCheck:  
+  complexity: 5
+CyclomaticComplexityMethodCheck: 
+  complexity: 10
+EmptyRescueBodyCheck:
+ForLoopCheck:
+MethodLineCountCheck:            
+  line_count: 30
+MethodNameCheck:                 
+  pattern: !ruby/regexp /^[_a-z<>=\[|+-\/\*`]+[_a-z0-9_<>=~@\[\]]*[=!\?]?$/ 
+# MissingForeignKeyIndexCheck:
+ModuleLineCountCheck:            
+  line_count: 300
+ModuleNameCheck:          
+  pattern: !ruby/regexp /^[A-Z][a-zA-Z0-9]*$/
+ParameterNumberCheck:            
+  parameter_count: 5
+