stenotype 0.1.0 → 0.1.6

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

@@ -14,20 +14,19 @@ module Stenotype
         #
         def as_json(*_args)
           {
-            class: request.controller_class.name,
-            method: request.method,
-            url: request.url,
-            referer: request.referer,
-            params: request.params.except('controller', 'action'),
-            ip: request.remote_ip
+            class: controller_class.name,
+            method: method,
+            url: url,
+            referer: referer,
+            params: params.except("controller", "action"),
+            ip: remote_ip,
           }
         end
 
-        private
-
-        def request
-          context.request
-        end
+        delegate :request, to: :context
+        delegate :method, :url, :referer, :remote_ip, :params,
+                 :controller_class, to: :request
+        private :request, :method, :url, :referer, :remote_ip, :params, :controller_class
       end
     end
   end

data/lib/stenotype/dispatcher.rb

@@ -9,8 +9,7 @@ module Stenotype
     #
     # Publishes an event to the list of configured targets.
     #
-    # @example
-    #
+    # @example Manually dispatching an event
     #   event = Stenotype::Event.new(data, options, eval_context)
     #   Stenotype::Dispatcher.new.publish(event)
     #

data/lib/stenotype/emitter.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Stenotype
+  #
+  # An extension for a plain Ruby class in order to track invocation of
+  # instance methods.
+  #
+  module Emitter
+    #
+    # Class methods for target to be extended by
+    #
+    ClassMethodsExtension = Class.new(Module)
+    #
+    # Instance methods to be included into target class ancestors chain
+    #
+    InstanceMethodsExtension = Class.new(Module)
+
+    # @!visibility private
+    def self.included(klass)
+      instance_mod = InstanceMethodsExtension.new
+      class_mod = ClassMethodsExtension.new
+
+      build_instance_methods(instance_mod)
+      build_class_methods(class_mod)
+
+      klass.const_set(:InstanceProxy, Module.new)
+      klass.const_set(:ClassProxy, Module.new)
+
+      klass.public_send(:include, instance_mod)
+      klass.extend(class_mod)
+
+      super
+    end
+
+    #
+    # @!method emit_event(name, attributes = {}, method: caller_locations.first.label, eval_context: nil)
+    #   A method injected into target class to manually track events
+    #   @!scope instance
+    #   @param name {[String, Symbol]} Event name.
+    #   @param attributes {Hash} Data to be sent to the targets.
+    #   @param method {String} An optional method name.
+    #   @param eval_context {Hash} A hash linking object to context handler
+    #   @return {Stenotype::Event} An instance of emitted event
+    #   @example Usage of emit_event
+    #     class SomeRubyClass
+    #       include Stenotype::Emitter
+    #
+    #       def some_method
+    #         data = collection_data
+    #         emit_event(data, eval_context: self) # Track event with given data
+    #         data
+    #       end
+    #     end
+    #
+
+    #
+    # @!method emit_event_before(*methods)
+    #   A class method injected into target class to track instance methods invocation
+    #   @param methods {Array<Symbol>} A list of method before which an event will be emitted
+    #   @!scope class
+    #   @example Usage of emit_event_before
+    #     class SomeRubyClass
+    #       include Stenotype::Emitter
+    #       emit_event_before :some_method # Triggers an event upon calling some_method
+    #
+    #       def some_method
+    #         # do something
+    #       end
+    #     end
+    #
+
+    #
+    # @!method emit_klass_event_before(*class_methods)
+    #   A class method injected into a target class to track class methods invocation
+    #   @!scope class
+    #   @param class_methods {Array<Symbol>} A list of class method before which
+    #     an event will be emitted
+    #   @example Usage emit_klass_event_before
+    #     class SomeRubyClass
+    #       include Stenotype::Emitter
+    #       emit_klass_event_before :some_method # Triggers an event upon calling some_method
+    #
+    #       def self.some_method
+    #         # do something
+    #       end
+    #     end
+    #
+
+    #
+    # Adds an instance method: [#emit_event] to a target class
+    #   where {Stenotype::Emitter} in included in
+    #
+    def self.build_instance_methods(instance_mod)
+      instance_mod.module_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def emit_event(event_name, attributes = {}, method: caller_locations.first.label, eval_context: nil)
+          Stenotype::Event.emit!(
+            event_name,
+            {
+              type: "instance_method",
+              class: self.class.name,
+              method: method.to_sym,
+              **attributes,
+            },
+            eval_context: (eval_context || { klass: self })
+          )
+        end
+      RUBY
+    end
+
+    #
+    # Adds class method [#emit_klass_event_before] to every class
+    #   inherited from [Object]
+    #
+    def self.build_class_methods(class_mod)
+      class_mod.module_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def emit_event_before(*methods)
+          proxy = const_get(:InstanceProxy)
+
+          methods.each do |method|
+            proxy.module_eval do
+              define_method(method) do |*args, **rest_args, &block|
+                Stenotype::Event.emit!(
+                  # @todo How do we name such events?
+                  "instance_method",
+                  {
+                    type: "instance_method",
+                    class: self.class.name,
+                    method: __method__,
+                  },
+                  eval_context: { klass: self },
+                )
+                super(*args, **rest_args, &block)
+              end
+            end
+          end
+
+          send(:prepend, proxy)
+        end
+
+        def emit_klass_event_before(*class_methods)
+          proxy = const_get(:ClassProxy)
+
+          class_methods.each do |method|
+            proxy.module_eval do
+              define_method(method) do |*args, **rest_args, &block|
+                Stenotype::Event.emit!(
+                  # @todo How do we name such events?
+                  "class_method",
+                  {
+                    type: "class_method",
+                    class: self.name,
+                    method: __method__,
+                  },
+                  eval_context: { klass: self },
+                )
+                super(*args, **rest_args, &block)
+              end
+            end
+
+            singleton_class.send(:prepend, proxy)
+          end
+        end
+      RUBY
+    end
+  end
+end

data/lib/stenotype/event.rb

@@ -8,52 +8,75 @@ module Stenotype
     #
     # Delegates event to instance of {Stenotype::Event}.
     #
-    # @example
-    #
+    # @example Emit an event using class method
     #   Stenotype::Event.emit!(data, options, eval_context)
     #
-    # @param data {Hash} Data to be published to the targets.
-    # @param options {Hash} A hash of additional options to be tracked.
-    # @param eval_context {Hash} A context having handler defined in {Stenotype::ContextHandlers}.
-    # @param dispatcher {#publish} A dispatcher object responding to [#publish]
+    # @param {[String, Symbol]} name Event name.
+    # @param {Hash} attributes Data to be published to the targets.
+    # @param {Hash} eval_context A context having handler defined in {Stenotype::ContextHandlers}.
+    # @param dispatcher {#publish} A dispatcher object responding to [#publish].
     # @return {Stenotype::Event} An instance of {Stenotype::Event}
     #
-    def self.emit!(data, options: {}, eval_context: {}, dispatcher: Stenotype.config.dispatcher)
-      event = new(data, options: options, eval_context: eval_context, dispatcher: dispatcher)
-      event.emit!
-      event
+    def self.emit!(name, attributes = {}, eval_context: {}, dispatcher: Stenotype.config.dispatcher)
+      return unless Stenotype.config.enabled
+
+      begin
+        event = new(name, attributes, eval_context: eval_context, dispatcher: dispatcher)
+        event.emit!
+        event
+      rescue => error
+        #
+        # @todo This is a temporary solution to enable conditional logger fetching
+        #   needs a fix to use default Spicerack::Configuration functionality
+        #
+        Stenotype::Configuration.logger.error(error)
+
+        raise Stenotype::Error unless Stenotype.config.graceful_error_handling
+      end
     end
 
-    attr_reader :data, :options, :eval_context, :dispatcher
+    attr_reader :name, :attributes, :eval_context, :dispatcher
 
     #
-    # @example
-    #
-    #   Stenotype::Event.emit!(data, options, eval_context)
+    # @example Create an event
+    #   event = Stenotype::Event.new(data, options, eval_context)
+    # @example Create an event with custom dispatcher
+    #   event = Stenotype::Event.new(data, options, eval_context, dispatcher: MyDispatcher.new)
     #
-    # @param {Hash} data Data to be published to the targets.
-    # @param {Hash} options A hash of additional options to be tracked.
+    # @param {[String, Symbol]} name Event name.
+    # @param {Hash} attributes Data to be published to the targets.
     # @param {Hash} eval_context A context having handler defined in {Stenotype::ContextHandlers}.
     # @param dispatcher {#publish} A dispatcher object responding to [#publish].
     # @return {Stenotype::Event} An instance of event
     #
-    def initialize(data, options: {}, eval_context: {}, dispatcher: Stenotype.config.dispatcher)
-      @data = data
-      @options = options
+    def initialize(name, attributes = {}, eval_context: {}, dispatcher: Stenotype.config.dispatcher)
+      @name = name
+      @attributes = attributes
       @eval_context = eval_context
-      @dispatcher = dispatcher
+      @dispatcher = dispatcher.new
     end
 
     #
     # Emits a {Stenotype::Event}.
     #
-    # @example
-    #
-    #   event = Stenotype::Event.new(data, options, eval_context)
-    #   event.emit!
+    # @example Emit an instance of event
+    #   event = Stenotype::Event.new('events_name', { key: :value }, eval_context: { controller: ctrl })
+    #   event.emit! #=> Publishes the event to targets
     #
     def emit!
-      dispatcher.publish(self)
+      return unless Stenotype.config.enabled
+
+      begin
+        dispatcher.publish(self)
+      rescue => error
+        #
+        # @todo This is a temporary solution to enable conditional logger fetching
+        #   needs a fix to use default Spicerack::Configuration functionality
+        #
+        Stenotype::Configuration.logger.error(error)
+
+        raise Stenotype::Error unless Stenotype.config.graceful_error_handling
+      end
     end
   end
 end

data/lib/stenotype/event_serializer.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-require 'securerandom'
 
 module Stenotype
   #
@@ -9,6 +8,14 @@ module Stenotype
   class EventSerializer
     attr_reader :event, :uuid_generator
 
+    #
+    # @example Serializing an event with default UUID generator
+    #   event = Stenotype::Event.new(data, attributes, eval_context)
+    #   serializer = Stenotype::EventSerializer.new(event)
+    #
+    # @example Serializing an event with custom UUID generator
+    #   event = Stenotype::Event.new(data, attributes, eval_context)
+    #   serializer = Stenotype::EventSerializer.new(event, uuid_generator: CustomUUIDGen)
     #
     # @param event {Stenotype::Event}
     # @param uuid_generator {#uuid} an object responding to [#uuid]
@@ -18,26 +25,38 @@ module Stenotype
       @uuid_generator = uuid_generator
     end
 
+    #
+    # @example Serializing an event with default uuid generator (SecureRandom)
+    #   event = Stenotype::Event.new(data, attributes, eval_context)
+    #   serializer = Stenotype::EventSerializer.new(event)
+    #   serializer.serialize #=> A hash with event.data, event.options,
+    #                        # default_options and eval_context_options
+    #
+    # @example Serializing an event with custom uuid generator
+    #   event = Stenotype::Event.new(data, attributes, eval_context)
+    #   serializer = Stenotype::EventSerializer.new(event, uuid_generator: CustomUUIDGen)
+    #   serializer.serialize #=> A hash with event.data, event.options,
+    #                        # default_options and eval_context_options
     #
     # @return {Hash} A hash representation of the event and its context
     #
     def serialize
       {
-        **event_data,
-        **event_options,
+        name: event_name,
+        **event_attributes,
         **default_options,
-        **eval_context_options
+        **eval_context_options,
       }
     end
 
     private
 
-    def event_data
-      event.data
+    def event_name
+      event.name
     end
 
-    def event_options
-      event.options
+    def event_attributes
+      event.attributes
     end
 
     def eval_context
@@ -45,16 +64,17 @@ module Stenotype
     end
 
     def eval_context_options
-      eval_context.map do |context_name, context|
+      context_attributes = eval_context.map do |context_name, context|
         handler = Stenotype::ContextHandlers.known.choose(handler_name: context_name)
         handler.new(context).as_json
-      end.reduce(:merge!) || {}
+      end
+      context_attributes.reduce(:merge!) || {}
     end
 
     def default_options
       {
         timestamp: Time.now.utc,
-        uuid: uuid_generator.uuid
+        uuid: uuid_generator.uuid,
       }
     end
   end

data/lib/stenotype/frameworks/rails/action_controller.rb

@@ -3,6 +3,10 @@
 require "active_support/concern"
 
 module Stenotype
+  #
+  # A namespace containing extensions of various frameworks.
+  # For example Rails components could be extended
+  #
   module Frameworks
     module Rails
       #
@@ -12,12 +16,15 @@ module Stenotype
       module ActionControllerExtension
         extend ActiveSupport::Concern
 
+        private
+
         #
         # Emits and event with given data
-        # @param data {Hash} Data to be sent to targets
+        # @param name {[String, Symbol]} Event name
+        # @todo What is really the name here?
         #
-        def record_freshly_event(data)
-          Stenotype::Event.emit!(data, options: {}, eval_context: { controller: self })
+        def _record_freshly_event(name)
+          Stenotype::Event.emit!(name, { type: "controller_action" }, { eval_context: { controller: self }})
         end
 
         #
@@ -28,12 +35,19 @@ module Stenotype
           # Adds a before_action to each action from the passed list. A before action
           # is emitting a {Stenotype::Event}. Please note that in case track_view is
           # used several times, it will keep track of the actions which emit events.
-          # Each time a new track_view is called it will find a symmetric difference
-          # of two sets: set of 'used' actions and a set passed to `track_view`.
           #
-          # @example
+          # @note Each time a new track_view is called it will find a symmetric difference
+          #   of two sets: set of already tracked actions and a set passed to `track_view`.
+          #
+          # @example Tracking multiple actions with track_view
+          #   Stenotype.configure do |config|
+          #     config.enable_action_controller_extension = true
+          #     config.enable_active_job_extension = true
+          #   end
+          #
           #   class MyController < ActionController::Base
-          #     track_view :index, :show
+          #     track_view :index, :show # Emits an event upon calling index and show actions,
+          #                              # but does not trigger an event on create
           #
           #     def index
           #       # do_something
@@ -59,36 +73,36 @@ module Stenotype
             return if delta.empty?
 
             before_action only: delta do
-              record_freshly_event(type: 'view')
+              _record_freshly_event("view")
             end
 
             _tracked_actions.merge(delta)
           end
 
-          # :nodoc:
-          def _tracked_actions
-            @_tracked_actions ||= Set.new
-          end
-
-          # Note this action will only define a symmetric difference of
-          # the covered with events actions and the ones not used yet.
+          #
+          # @note This action will only define a symmetric difference of
+          # the tracked actions and the ones not tracked yet.
           # @see #track_view
           #
-          # @example
-          #   class MyController < ActionController::Base
-          #     track_all_views
+          # @example Emitting an event before all actions in controller
+          #   class UsersController < ApplicationController
+          #     track_all_views # Emits an event before all actions in a controller
           #
           #     def index
-          #       # do_something
+          #       # do something
           #     end
           #
           #     def show
           #       # do something
           #     end
+          #
+          #     def create
+          #       # do something
+          #     end
           #   end
           #
           def track_all_views
-            actions = self.action_methods
+            actions = action_methods
 
             # A symmetric difference of two sets.
             # This prevents accidental duplicating of events
@@ -97,12 +111,21 @@ module Stenotype
             return if delta.empty?
 
             before_action only: delta.to_a do
-              record_freshly_event(type: "view")
+              _record_freshly_event("view")
             end
 
             # merge is a mutating op
             _tracked_actions.merge(delta)
           end
+
+          private
+
+          #
+          # @return {Set<Symbol>} a set of tracked actions
+          #
+          def _tracked_actions
+            @_tracked_actions ||= Set.new
+          end
         end
       end
     end