sc4ry 0.1.7 → 0.2.1

data/lib/sc4ry/exceptions.rb

@@ -1,11 +1,44 @@
+# frozen_string_literal: true
+
+# Sc4ry module
+# @note namespace
 module Sc4ry
-    module Exceptions
-        class CircuitBreaked < StandardError
-            def initialize(msg="Circuit just opened")
-                super(msg)
-              end
-        
-        end
+  # 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)
+      end
+    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
+end

data/lib/sc4ry/exporters/init.rb

@@ -1 +1,3 @@
-Dir[File.dirname(__FILE__) + '/*.rb'].sort.each { |file| require file unless File.basename(file) == 'init.rb' }
+# frozen_string_literal: true
+
+Dir["#{File.dirname(__FILE__)}/*.rb"].sort.each { |file| require file unless File.basename(file) == 'init.rb' }

data/lib/sc4ry/helpers.rb

@@ -1,10 +1,22 @@
+# frozen_string_literal: true
 
+# Sc4ry module
+# @note namespace
 module Sc4ry
+  # Sc4ry::Helpers module
+  # @note namespace
   module Helpers
-
-    def Helpers.log(options)
-      Sc4ry::Logger.current = options[:target] if options[:target]
-      Sc4ry::Logger.get.send options[:level], "Sc4ry : #{options[:message]}"  
+    # 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 self.log(message:, target: nil, level: :info)
+      save = Sc4ry::Loggers.current
+      Sc4ry::Loggers.current = target if target
+      Sc4ry::Loggers.get.send level, "Sc4ry : #{message}"
+      Sc4ry::Loggers.current = save
+      true
     end
 
     # TCP/IP service checker
@@ -13,37 +25,34 @@ module Sc4ry
     # @option options [String] :host hostname
     # @option options [String] :port TCP port
     # @option options [String] :url full URL, priority on :host and :port
-    def Helpers.verify_service(options ={})
-      begin
-        if options[:url] then
-          uri = URI.parse(options[:url])
-          host = uri.host
-          port = uri.port
-        else
-          host = options[:host]
-          port = options[:port]
-        end
-        Timeout::timeout(1) do
-          begin
-            s = TCPSocket.new(host, port)
-            s.close
-            return true
-          rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
-            return false
-          end
-        end
-      rescue Timeout::Error
+    def self.verify_service(options = {})
+      if options[:url]
+        uri = URI.parse(options[:url])
+        host = uri.host
+        port = uri.port
+      else
+        host = options[:host]
+        port = options[:port]
+      end
+      Timeout.timeout(1) do
+        s = TCPSocket.new(host, port)
+        s.close
+        return true
+      rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
         return false
       end
+    rescue Timeout::Error
+      false
     end
 
-
-    def Helpers.notify(options = {})
+    # class method (module) to help send notifiesby Sc4ry::Notifiers
+    # @param [Hash] options a Notifying structure
+    # @return [Boolean]
+    def self.notify(options = {})
       Sc4ry::Notifiers.list.each do |record|
         notifier = Sc4ry::Notifiers.get name: record
-        notifier[:class].notify(options) if options[:config][:notifiers].include? record 
+        notifier[:class].notify(options) if options[:config][:notifiers].include? record
       end
     end
-
-  end 
-end
+  end
+end

data/lib/sc4ry/logger.rb

@@ -1,30 +1,67 @@
+# frozen_string_literal: true
 
+# Sc4ry module
+# @note namespace
 module Sc4ry
-  class Logger
-    
-    @@loggers = {:stdout => ::Logger.new(STDOUT)}
+  # 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 self.list_available
+      @@loggers.keys
     end
-    
-    def Logger.current
-      return @@current
+
+    # return the current logger name (initially :stdtout )
+    # @return [symbol] the name of the logger
+    # @example usage
+    #    include Sc4ry
+    #    puts Circuits.loggers.current
+    def self.current
+      @@current
     end
-    
-    def Logger.get
-      return @@loggers[@@current]
+
+    # 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 self.get
+      @@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 self.current=(sym)
       raise "Logger not define : #{sym}" unless @@loggers.keys.include? sym
+
       @@current = sym
+      @@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 self.register(name:, instance:)
+      raise Sc4ry::Exceptions::Sc4ryGenericError, 'name: keyword must be a Symbol' unless name.instance_of?(Symbol)
+
+      @@loggers[name] = instance
+      name
     end
-    
   end
 end

data/lib/sc4ry/notifiers/init.rb

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

data/lib/sc4ry/notifiers/mattermost.rb

@@ -1,35 +1,42 @@
+# frozen_string_literal: true
+
+# Sc4ry module
+# @note namespace
 module Sc4ry
-    module Notifiers
-        
-        class Mattermost
-            
-            # send metrics to Prometheus PushGateway
-            # @return [Bool]
-            def Mattermost.notify(options = {})
-                config = Sc4ry::Notifiers.get({name: :mattermost})[:config]
-                status = options[:config][:status][:general]
-                circuit = options[:circuit]
-                status_map = {:open => 0, :half_open => 1, :closed => 2}
-                
-                uri = URI.parse("#{config[:url]}/hooks/#{config[:token]}")
-                message = "notifying for circuit #{circuit.to_s}, state : #{status.to_s}."
-                if Sc4ry::Helpers::verify_service url: config[:url] then
-                    request = ::Net::HTTP::Post.new(uri)
-                    request.content_type = "application/json"
-                    req_options = {
-                        use_ssl: uri.scheme == "https",
-                    }
-                    payload = { "text" => "message : #{message } from #{Socket.gethostname}", "username" => "Sc4ry" }
-                    Sc4ry::Helpers.log level: :debug, message: "Mattermost Notifier : #{message}"
-                    request.body = ::JSON.dump(payload)
-                    response = ::Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
-                        http.request(request)
-                    end
-                    
-                else
-                    Sc4ry::Helpers.log level: :warn, message: "Mattermost Notifier : can't notify Mattermost not reachable."
-                end
+  # Sc4ry::Notifiers module
+  # @note namespace
+  module Notifiers
+    # Mattermost Notifier class
+    class Mattermost
+      # send metrics to Prometheus PushGateway
+      # @return [Bool]
+      def self.notify(options = {})
+        config = Sc4ry::Notifiers.get(name: :mattermost)[:config]
+        status = options[:config][:status][:general]
+        circuit = options[:circuit]
+        begin
+          uri = URI.parse("#{config[:url]}/hooks/#{config[:token]}")
+          message = "notifying for circuit #{circuit}, state : #{status}."
+          if Sc4ry::Helpers.verify_service url: config[:url]
+            request = ::Net::HTTP::Post.new(uri)
+            request.content_type = 'application/json'
+            req_options = {
+              use_ssl: uri.scheme == 'https'
+            }
+            payload = { 'text' => "message : #{message} from #{Socket.gethostname}", 'username' => 'Sc4ry' }
+            Sc4ry::Helpers.log level: :debug, message: "Mattermost Notifying : #{message}"
+            request.body = ::JSON.dump(payload)
+            ::Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
+              http.request(request)
             end
+
+          else
+            Sc4ry::Helpers.log level: :warn, message: "Mattermost Notifier : can't notify Mattermost not reachable."
+          end
+        rescue URI::InvalidURIError
+          Sc4ry::Helpers.log level: :warn, message: 'Mattermost Notifier : URL malformed'
         end
+      end
     end
-end
+  end
+end

data/lib/sc4ry/notifiers/prometheus.rb

@@ -1,37 +1,39 @@
+# frozen_string_literal: true
+
+# Sc4ry module
+# @note namespace
 module Sc4ry
+  # Sc4ry::Notifiers module
+  # @note namespace
   module Notifiers
-
-  
+    # Prometheus notifier class
     class Prometheus
-
-      @@registry = ::Prometheus::Client::Registry::new
-      @@metric_circuit_state = ::Prometheus::Client::Gauge.new(:cuircuit_state, docstring: 'Sc4ry metric : state of a circuit', labels: [:circuit])
+      @@registry = ::Prometheus::Client::Registry.new
+      @@metric_circuit_state = ::Prometheus::Client::Gauge.new(:cuircuit_state,
+                                                               docstring: 'Sc4ry metric : state of a circuit',
+                                                               labels: [:circuit])
 
       @@registry.register(@@metric_circuit_state)
 
-    
-
       # send metrics to Prometheus PushGateway
       # @return [Bool]
-      def Prometheus.notify(options = {})
-        @config = Sc4ry::Notifiers.get({name: :prometheus})[:config]
+      def self.notify(options = {})
+        @config = Sc4ry::Notifiers.get(name: :prometheus)[:config]
         status = options[:config][:status][:general]
         circuit = options[:circuit]
-        status_map = {:open => 0, :half_open => 1, :closed => 2}
-        if Sc4ry::Helpers::verify_service url: @config[:url] then
-          
-          @@metric_circuit_state.set(status_map[status], labels: {circuit: circuit.to_s })
-          Sc4ry::Helpers.log level: :debug, message: "Prometheus Notifier : notifying for circuit #{circuit.to_s}, state : #{status.to_s}."
+        status_map = { open: 0, half_open: 1, closed: 2 }
+        if Sc4ry::Helpers.verify_service url: @config[:url]
 
-          return ::Prometheus::Client::Push.new(job: "Sc4ry", instance: Socket.gethostname, gateway: @config[:url]).add(@@registry)
+          @@metric_circuit_state.set(status_map[status], labels: { circuit: circuit.to_s })
+          Sc4ry::Helpers.log level: :debug,
+                             message: "Prometheus Notifier : notifying for circuit #{circuit}, state : #{status}."
+
+          ::Prometheus::Client::Push.new(job: 'Sc4ry', instance: Socket.gethostname,
+                                         gateway: @config[:url]).add(@@registry)
         else
           Sc4ry::Helpers.log level: :warn, message: "Prometheus Notifier : can't notify Push Gateway not reachable."
         end
       end
     end
-
-    
-    
   end
-
 end

data/lib/sc4ry/run_controller.rb

@@ -1,9 +1,15 @@
+# frozen_string_literal: true
 
+# 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,53 +18,56 @@ module Sc4ry
       @overtime = false
     end
 
+    # return if the Proc failed on a covered exception by this circuit
+    # @return [Boolean]
     def failed?
-      return @failure
-    end 
-    
-    def overtimed? 
-      return @overtime
+      @failure
+    end
+
+    # return if the Proc overtime the specified time of the circuit
+    # @return [Boolean]
+    def overtimed?
+      @overtime
     end
 
-    def timeout? 
-      return @timeout
+    # return if the Proc timeout the timeout defined value of the circuit, if timeout is active
+    # @return [Boolean]
+    def timeout?
+      @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 
+      begin
         if @circuit[:timeout] == true
-          Timeout::timeout(@circuit[:timeout_value]) do 
-            options[:block].call
+          Timeout.timeout(@circuit[:timeout_value]) do
+            block.call
           end
           @timeout = false
         else
-          options[:block].call
+          block.call
         end
-      rescue Exception => e
-        @last_exception = e.class
-        if e.class  == Timeout::Error then 
+      rescue StandardError => e
+        @last_exception = e.class.to_s
+        if e.instance_of?(Timeout::Error)
           @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}"
-          end
-          
-        end 
+        elsif @circuit[:forward_unknown_exceptions]
+          raise e.class, "Sc4ry forward: #{e.message}"
+        else
+          Sc4ry::Helpers.log level: :debug, message: "skipped : #{@last_exception}"
+
+        end
       end
       @end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       @execution_time = @end_time - start_time
-      @overtime = @execution_time > @circuit[:max_time] 
-      return {failure: @failure, overtime: @overtime, timeout: @timeout, execution_time: @execution_time, end_time: @end_time, last_exception: @last_exception}
-
+      @overtime = @execution_time > @circuit[:max_time]
+      { failure: @failure, overtime: @overtime, timeout: @timeout, execution_time: @execution_time,
+        end_time: @end_time, last_exception: @last_exception }
     end
-
-
-
   end
-end
+end