stenotype 0.1.0 → 0.1.6

data/lib/stenotype/adapters/stdout_adapter.rb

@@ -5,12 +5,46 @@ module Stenotype
     #
     # An adapter implementing method {#publish} to send data to STDOUT
     #
+    # @example
+    #   class SomeClassWithEvents
+    #     def method_emitting_enent
+    #       result_of_calculations = collect_some_data
+    #       # This will print the data to STDOUT by default
+    #       stdout_adapter.publish(result_of_calculation, additional: :data, more: :data)
+    #       result_of_calculations
+    #     end
+    #
+    #     def stdout_adapter
+    #       Stenotype::Adapters::StdoutAdapter.new
+    #     end
+    #   end
+    #
     class StdoutAdapter < Base
       #
       # @param event_data {Hash} The data to be published to STDOUT
       #
-      def publish(event_data, **additional_arguments)
-        client.info(event_data, **additional_arguments)
+      # @example Publishing to default client (STDOUT)
+      #  adapter = Stenotype::Adapters::StdoutAdapter.new
+      #  adapter.publish({ event: :data }, { additional: :data })
+      #
+      # @example Publishing to custom client (STDERR)
+      #  adapter = Stenotype::Adapters::StdoutAdapter.new(client: STDERR)
+      #  adapter.publish({ event: :data }, { additional: :data })
+      #
+      def publish(event_data, **additional_attrs)
+        client.info("[Stenotype::Event] emitted with the following attributes") do
+          {
+            **event_data,
+            **additional_attrs,
+          }
+        end
+      end
+
+      #
+      # Does nothing
+      #
+      def flush!
+        # noop
       end
 
       private

data/lib/stenotype/at_exit.rb

@@ -0,0 +1,8 @@
+require 'stenotype'
+
+# :nocov:
+at_exit do
+  targets = Stenotype.config.targets
+  targets.each(&:flush!)
+end
+# :nocov:

data/lib/stenotype/configuration.rb

@@ -4,46 +4,137 @@ module Stenotype
   #
   # A module containing freshly-event gem configuration
   #
+  # @example Configuring the library
+  #   Stenotype.configure do |config|
+  #     config.enabled = true
+  #     config.targets = [Target1.new, Target2.new]
+  #     config.uuid_generator = SecureRandom
+  #
+  #     config.google_cloud do |gc|
+  #       gc.credentials = "abc"
+  #       gc.project_id  = "project"
+  #       gc.topic       = "42"
+  #       gc.async       = true
+  #     end
+  #
+  #     config.rails do |rc|
+  #       rc.enable_action_controller_ext = true
+  #       rc.enable_active_job_ext        =  false
+  #     end
+  #   end
+  #
   module Configuration
-    class << self
-      # @return {Array<#publish>} a list of targets responding to method [#publish]
-      attr_writer :targets
-      # @return {Sting} a string with GC API credential. Refer to GC PubSub documentation
-      attr_accessor :gc_credentials
-      # @return {String} a name of the project in GC PubSub
-      attr_accessor :gc_project_id
-      # @return {String} a name of the topic in GC PubSub
-      attr_accessor :gc_topic
-      # @return [:sync, :async] GC publish mode
-      attr_accessor :gc_mode
-      # @return {#publish} as object responding to method [#publish]
-      attr_accessor :dispatcher
-      # @return {#uuid} an object responding to method [#uuid]
-      attr_accessor :uuid_generator
-
-      #
-      # Yields control to the caller
-      # @yield {Stenotype::Configuration}
-      # @return {Stenotype::Configuration}
-      #
-      def configure
-        yield self
-        self
+    extend Spicerack::Configurable
+
+    # @!attribute graceful_error_handling
+    # @return {true, false} a flag for suppressing error raised withing the gem
+
+    # @!attribute logger
+    # @return {Logger} a logger with default severity methods to output gem level messages
+
+    # @!attribute enabled
+    # @return {true, false} a flag indicating whether event emission is enabled
+
+    # @!attribute targets
+    # @return {Array<#publish>} a list of targets responding to method [#publish]
+
+    # @!attribute [rw] dispatcher
+    # @return {#publish} as object responding to method [#publish]
+
+    # @!attribute [rw] uuid_generator
+    # @return {#uuid} an object responding to method [#uuid]
+
+    # @!attribute [rw] google_cloud
+    # @return [NestedConfiguration] google cloud configuration.
+
+    # @!attribute [rw] google_cloud.credentials
+    # @return {String} a string with GC API credential. Refer to GC PubSub documentation
+
+    # @!attribute [rw] google_cloud.project_id
+    # @return {String} a name of the project in GC PubSub
+
+    # @!attribute [rw] google_cloud.topic
+    # @return {String} a name of the topic in GC PubSub
+
+    # @!attribute [rw] google_cloud.async
+    # @return [true, false] GC publish mode, either async if true, sync if false
+
+
+    # @!attribute [rw] rails
+    # @return [NestedConfiguration] Rails configuration.
+
+    # @!attribute [rw] rails.enable_action_controller_ext
+    # @return [true, false] A flag of whether ActionController ext is enabled
+
+    # @!attribute [rw] rails.enable_active_job_ext
+    # @return [true, false] A flag of whether ActiveJob ext is enabled
+
+    configuration_options do
+      option :graceful_error_handling, default: true
+      option :enabled, default: true
+      option :targets, default: []
+      option :dispatcher, default: Stenotype::Dispatcher
+      option :uuid_generator, default: SecureRandom
+      option :logger
+
+      nested :google_cloud do
+        option :credentials, default: nil
+        option :project_id, default: nil
+        option :topic, default: nil
+        option :async, default: true
       end
 
-      #
-      # @raise {Stenotype::Exceptions::NoTargetsSpecified} in case no targets are configured
-      # @return {Array<#publish>} An array of targets implementing method [#publish]
-      #
-      def targets
-        if @targets.nil? || @targets.empty?
-          raise Stenotype::Exceptions::NoTargetsSpecified,
-                'Please configure a target(s) for events to be sent to. ' \
-                'See Stenotype::Configuration for reference.'
-        else
-          @targets
-        end
+      nested :rails do
+        option :enable_action_controller_ext, default: true
+        option :enable_active_job_ext, default: true
       end
     end
+
+    module_function
+
+    #
+    # @example With default logger
+    #   Stenotype.configure do |config|
+    #     # config.logger = nil # logger not set manually
+    #   end
+    #   Stenotype.config.logger #=> `Logger.new(STDOUT)` instance
+    #
+    # @example With custom logger
+    #   Stenotype.configure do |config|
+    #     config.logger = custom_logger_instance
+    #   end
+    #   Stenotype.config.logger #=> custom_logger_instance
+    #
+    # @return [{Logger, CustomLogger}] a logger object. Logger.new(STDOUT) by
+    #   default if another is not set during configuration
+    #
+    def logger
+      return config.logger if config.logger
+      config.logger || Logger.new(STDOUT)
+    end
+
+    #
+    # @example When at least one target is present
+    #   Stenotype.configure do |config|
+    #     config.targets = [Target1.new, Target2.new]
+    #   end
+    #   Stenotype.config.targets #=> [target_obj1, target_obj2]
+    #
+    # @example When no targets have been configured
+    #   Stenotype.configure { |config| config.targets = [] }
+    #   Stenotype.config.targets #=> Stenotype::NoTargetsSpecifiedError
+    #
+    # @raise {Stenotype::NoTargetsSpecifiedError} in case no targets are configured
+    # @return {Array<#publish>} An array of targets implementing method [#publish]
+    #
+    # @todo THIS NEVER GETS CALLED, needs a fix
+    #
+    def targets
+      return config.targets unless config.targets.empty?
+
+      raise Stenotype::NoTargetsSpecifiedError,
+            "Please configure a target(s) for events to be sent to. "\
+            "See #{Stenotype::Configuration} for reference."
+    end
   end
 end

data/lib/stenotype/context_handlers.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-require 'stenotype/context_handlers/base'
-require 'stenotype/context_handlers/rails/controller'
-require 'stenotype/context_handlers/rails/active_job'
-require 'stenotype/context_handlers/klass'
-require 'stenotype/context_handlers/collection'
+require "stenotype/context_handlers/base"
+require "stenotype/context_handlers/rails/controller"
+require "stenotype/context_handlers/rails/active_job"
+require "stenotype/context_handlers/klass"
+require "stenotype/context_handlers/collection"
 
 module Stenotype
   #
@@ -24,9 +24,7 @@ module Stenotype
       #
       # @param handler {#publish} A handler with implemented method [#publish]
       #
-      def register(handler)
-        known.register(handler)
-      end
+      delegate :register, to: :known
     end
   end
 end

data/lib/stenotype/context_handlers/base.rb

@@ -9,6 +9,18 @@ module Stenotype
     # @attr_reader {Object} context A context in which the event was emitted
     # @attr_reader {Hash} options A hash of additional options
     #
+    # @example Defining a custom Handler
+    #   class MyCustomHandler < Stenotype::ContextHandlers::Base
+    #     self.context_name = :custom_handler
+    #
+    #     def as_json(*_args)
+    #       {
+    #         value1: context.value1,
+    #         value2: context.value2
+    #       }
+    #     end
+    #   end
+    #
     class Base
       attr_reader :context, :options
 
@@ -18,7 +30,7 @@ module Stenotype
       #
       # @return {#as_json} A context handler implementing [#as_json]
       #
-      def initialize(context, options = {})
+      def initialize(context, options: {})
         @context = context
         @options = options
       end
@@ -43,8 +55,7 @@ module Stenotype
         # @raise {NotImplementedError} in case handler name is not specified.
         #
         def handler_name
-          @handler_name || raise(NotImplementedError,
-                                 "Please, specify the handler_name of #{self}")
+          @handler_name || raise(NotImplementedError, "Please, specify the handler_name of #{self}")
         end
       end
     end

data/lib/stenotype/context_handlers/collection.rb

@@ -4,61 +4,105 @@ module Stenotype
   module ContextHandlers
     #
     # A class representing a list of available context handlers
+    # @example Complete usage overview
+    #   class MyCustomHander
+    #     self.handler_name = :custom_handler
     #
-    class Collection < Array
+    #     def as_json(*_args)
+    #       {
+    #         key: :value
+    #       }
+    #     end
+    #   end
+    #
+    #   collection = Stenotype::ContextHandlers::Collection.new
+    #   collection.register(MyCustomHandler)
+    #
+    #   collection.registered?(MyCustomHandler) #=> true
+    #   collection.choose(handler_name: :custom_handler) #=> MyCustomHandler
+    #   collection.unregister(MyCustomHandler)
+    #   collection.registered?(MyCustomHandler) #=> false
+    #
+    #   collection.register(SomeRandomClass) #=> ArgumentError
+    #   collection.unregister(SomeRandomClass) #=> ArgumentError
+    #   collection.choose(handler_name: :unknown) #=> Stenotype::UnknownHandlerError
+    #
+    class Collection < ::Collectible::CollectionBase
+      #
+      # Return a handler with given handler_name if found in collection,
+      # raises if a handler is not registered
       #
       # @param handler_name {Symbol} a handler to be found in the collection
-      # @raise {Stenotype::Exceptions::UnknownHandler} in case a handler is not registered
+      # @raise {Stenotype::Errors::UnknownHandler} in case a handler is not registered
       # @return {#as_json} A handler which respond to #as_json
       #
+      # @example When a handler is present in the collection
+      #   collection = Stenotype::ContextHandlers::Collection.new
+      #   collection.register(MyCustomHandler) # with handler_name = :custom_handler
+      #   collection.choose(handler_name: :custom_handler) #=> MyCustomHandler
+      #
+      # @example When a handler is not present in the collection
+      #   collection = Stenotype::ContextHandlers::Collection.new
+      #   collection.choose(handler_name: :custom_handler) #=> MyCustomHandler
+      #
       def choose(handler_name:)
-        handler = detect { |e| e.handler_name == handler_name }
-        handler || raise(Stenotype::Exceptions::UnknownHandler,
-                         "Handler '#{handler_name}' is not found. " \
-                         "Please make sure the handler you've specified is " \
-                         'registered in the list of known handlers. ' \
-                         "See #{Stenotype::ContextHandlers} for more information.")
+        handler = find_by(handler_name: handler_name)
+        handler || raise(
+          Stenotype::UnknownHandlerError,
+          "Handler '#{handler_name}' is not found. "\
+          "Please make sure the handler you've specified is "\
+          "registered in the list of known handlers. "\
+          "See #{Stenotype::ContextHandlers} for more information.",
+        )
       end
 
       #
-      # @param handler {#as_json} a new handler to be added to collection
-      # @raise {ArgumentError} in case handler does not inherit from {Stenotype::ContextHandlers::Base}
-      # @return {Stenotype::ContextHandlers::Collection} a collection object
+      # @!method register(handler)
+      #   Registers a new handler.
+      #   @!scope instance
+      #   @param handler {#as_json} a new handler to be added to collection
+      #   @return {Stenotype::ContextHandlers::Collection} a collection object
+      #   @example Registering a new handler
+      #     collection = Stenotype::ContextHandlers::Collection.new
+      #     collection.register(MyCustomHandler) # with handler_name = :custom_handler
       #
-      def register(handler)
-        unless handler < Stenotype::ContextHandlers::Base
-          raise ArgumentError,
-                "Handler must inherit from #{Stenotype::ContextHandlers::Base}, " \
-                "but inherited from #{handler.superclass}"
-        end
-
-        push(handler) unless registered?(handler)
-        self
-      end
+      alias_method :register, :push
 
+      #
+      # Removes a registered handler.
+      #
+      # @example Register and unregister a handler
+      #   collection = Stenotype::ContextHandlers::Collection.new
+      #   collection.register(MyCustomHandler) # with handler_name = :custom_handler
+      #   collection.unregister(MyCustomHandler) # removes MyCustomHandler from the list of handlers
       #
       # @param handler {#as_json} a handler to be removed from the collection of known handlers
-      # @raise {ArgumentError} in case handler does not inherit from {Stenotype::ContextHandlers::Base}
       # @return {Stenotype::ContextHandlers::Collection} a collection object
       #
+      # @todo Add delete to the collectible delegation list
+      #   and then use `alias_method :unregister, :delete`
       def unregister(handler)
-        unless handler < Stenotype::ContextHandlers::Base
-          raise ArgumentError,
-                "Handler must inherit from #{Stenotype::ContextHandlers::Base}, " \
-                "but inherited from #{handler.superclass}"
-        end
-
-        delete(handler) if registered?(handler)
+        items.delete(handler)
         self
       end
 
       #
-      # @param handler {#as_json} a handler to be checked for presence in a collection
-      # @return [true, false]
+      # @!method registered?(handler)
+      #   Checks whether a given handler is registered in collection
+      #   @!scope instance
+      #   @param handler {#as_json} a handler to be checked for presence in a collection
+      #   @return [true, false]
+      #   @example When a handler is registered
+      #     collection = Stenotype::ContextHandlers::Collection.new
+      #     collection.register(MyCustomHandler) # with handler_name = :custom_handler
+      #     collection.registered?(MyCustomHandler) # true
       #
-      def registered?(handler)
-        include?(handler)
-      end
+      #   @example When a handler is not registered
+      #     collection = Stenotype::ContextHandlers::Collection.new
+      #     collection.registered?(UnregisteredHandler) # false
+      #
+
+      alias_method :registered?, :include?
     end
   end
 end

data/lib/stenotype/context_handlers/rails/active_job.rb

@@ -22,21 +22,13 @@ module Stenotype
         def as_json(*_args)
           {
             job_id: job_id,
-            enqueued_at: Time.now,
+            enqueued_at: Time.now.utc,
             queue_name: queue_name,
-            class: context.class.name
+            class: context.class.name,
           }
         end
 
-        private
-
-        def job_id
-          context.job_id
-        end
-
-        def queue_name
-          context.queue_name
-        end
+        delegate :job_id, :queue_name, to: :context
       end
     end
   end