stenotype 0.1.0

data/lib/stenotype/frameworks/object_ext.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Stenotype
+  #
+  # A namespace containing extensions of various frameworks.
+  # For example Rails components could be extended
+  #
+  module Frameworks
+    #
+    # An extension for a plain Ruby class in order to track invocation of
+    # instance methods.
+    #
+    module ObjectExt
+      #
+      # Class methods for `Object` to be extended by
+      #
+      ClassMethodsExtension = Class.new(Module)
+      #
+      # Instance methods to be included into `Object` ancestors chain
+      #
+      InstanceMethodsExtension = Class.new(Module)
+
+      attr_reader :instance_mod,
+                  :class_mod
+
+      # @!visibility private
+      def self.included(klass)
+        @instance_mod = InstanceMethodsExtension.new
+        @class_mod = ClassMethodsExtension.new
+
+        build_instance_methods
+        build_class_methods
+
+        klass.const_set(:InstanceProxy, Module.new)
+        klass.const_set(:ClassProxy, Module.new)
+
+        klass.send(:include, instance_mod)
+        klass.extend(class_mod)
+
+        super
+      end
+
+      #
+      # @!method emit_event(data = {}, method: caller_locations.first.label, eval_context: nil)
+      #   A method injected into all instances of Object
+      # @!scope instance
+      # @param data {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
+      #
+
+      #
+      # @!method emit_event_before(*methods)
+      #   A method injected into all instances of Object
+      # @!scope instance
+      # @param methods {Array<Symbol>} A list of method before which an event will be emitted
+      #
+
+      #
+      # @!method emit_klass_event_before(*class_methods)
+      #   A class method injected into all subclasses of [Object]
+      # @!scope class
+      # @param class_method {Array<Symbol>} A list of class method before which
+      #   an event will be emitted
+      #
+
+      #
+      # rubocop:disable Metrics/MethodLength
+      # Adds two methods: [#emit_event] and [#emit_event_before] to every object
+      #   inherited from [Object]
+      #
+      def build_instance_methods
+        instance_mod.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def emit_event(data = {}, method: caller_locations.first.label, eval_context: nil)
+            Stenotype::Event.emit!(
+              {
+                type: 'class_instance',
+                **data,
+              },
+              options: {
+                class: self.class.name,
+                method: method.to_sym
+              },
+              eval_context: (eval_context || { klass: self })
+            )
+          end
+
+          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!(
+                    { type: 'class_instance' },
+                    options: {
+                      class: self.class.name,
+                      method: __method__
+                    },
+                    eval_context: { klass: self }
+                  )
+                  super(*args, **rest_args, &block)
+                end
+              end
+            end
+
+            send(:prepend, proxy)
+          end
+        RUBY
+      end
+
+      #
+      # Adds class method [#emit_klass_event_before] to every class
+      #   inherited from [Object]
+      #
+      def build_class_methods
+        class_mod.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          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!(
+                    { type: 'class' },
+                    options: {
+                      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
+      # rubocop:enable Metrics/MethodLength
+    end
+  end
+end

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

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Stenotype
+  module Frameworks
+    module Rails
+      #
+      # An ActionController extension to be injected into classes
+      # inheriting from [ActionController::Base]
+      #
+      module ActionControllerExtension
+        extend ActiveSupport::Concern
+
+        #
+        # Emits and event with given data
+        # @param data {Hash} Data to be sent to targets
+        #
+        def record_freshly_event(data)
+          Stenotype::Event.emit!(data, options: {}, eval_context: { controller: self })
+        end
+
+        #
+        # Class methods to be injected into classes
+        # inherited from [ActionController::Base]
+        #
+        module ClassMethods
+          # 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
+          #   class MyController < ActionController::Base
+          #     track_view :index, :show
+          #
+          #     def index
+          #       # do_something
+          #     end
+          #
+          #     def show
+          #       # do something
+          #     end
+          #
+          #     # Not covered by track_view
+          #     def update
+          #       # do something
+          #     end
+          #   end
+          #
+          # @param actions {Array<Symbol>} a list of tracked controller actions
+          #
+          def track_view(*actions)
+            # A symmetric difference of two sets.
+            # This prevents accidental duplicating of events
+            delta = (_tracked_actions - Set[*actions]) | (Set[*actions] - _tracked_actions)
+
+            return if delta.empty?
+
+            before_action only: delta do
+              record_freshly_event(type: '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.
+          # @see #track_view
+          #
+          # @example
+          #   class MyController < ActionController::Base
+          #     track_all_views
+          #
+          #     def index
+          #       # do_something
+          #     end
+          #
+          #     def show
+          #       # do something
+          #     end
+          #   end
+          #
+          def track_all_views
+            actions = self.action_methods
+
+            # A symmetric difference of two sets.
+            # This prevents accidental duplicating of events
+            delta = ((_tracked_actions - actions) | (actions - _tracked_actions))
+
+            return if delta.empty?
+
+            before_action only: delta.to_a do
+              record_freshly_event(type: "view")
+            end
+
+            # merge is a mutating op
+            _tracked_actions.merge(delta)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Stenotype
+  module Frameworks
+    #
+    # A namespace containing extensions for Ruby on Rails components
+    #
+    module Rails
+      #
+      # An extension for ActiveJob to enable adding a hook
+      # before performing an instance of [ActiveJob::Base] subclass
+      #
+      module ActiveJobExtension
+        # @!visibility private
+        def self.extended(base)
+          base.const_set(:JobExt, Module.new)
+          super
+        end
+
+        #
+        # @example
+        #   class MyJob < ApplicationJob
+        #     trackable_job! # => will prepend a perform action with event recorder
+        #
+        #     def perform(data)
+        #       # do_something
+        #     end
+        #   end
+        #
+        # rubocop:disable Metrics/MethodLength
+        #
+        def trackable_job!
+          proxy = const_get(:JobExt)
+          proxy.module_eval do
+            define_method(:perform) do |*args, **rest_args, &block|
+              Stenotype::Event.emit!(
+                { type: "active_job" },
+                options: {},
+                eval_context: { active_job: self }
+              )
+              super(*args, **rest_args, &block)
+            end
+          end
+
+          # Prepend an instance of module so that
+          # super() can be chained down the ancestors
+          # without changing existing ActiveJob interface
+          #
+          send(:prepend, proxy)
+        end
+        # rubocop:enable Metrics/MethodLength
+      end
+    end
+  end
+end

data/lib/stenotype/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Stenotype
+  # :nodoc:
+  VERSION = '0.1.0'
+  # :nodoc:
+end

data/lib/stenotype.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+#
+# A top level namespace for the freshly-events gem
+#
+module Stenotype
+  class << self
+    ##
+    # Configures the library.
+    # @yield {Stenotype::Configuration}
+    #
+    # @example
+    #
+    #   Stenotype.configure do |config|
+    #     config.targets = [
+    #       Stenotype::Adapters::StdoutAdapter.new,
+    #       Stenotype::Adapters::GoogleCloud.new
+    #     ]
+    #
+    #      config.dispatcher     = Stenotype::Dispatcher.new
+    #      config.gc_project_id  = ENV['GC_PROJECT_ID']
+    #      config.gc_credentials = ENV['GC_CREDENTIALS']
+    #      config.gc_topic       = ENV['GC_TOPIC']
+    #      config.gc_mode        = :async
+    #   end
+    #
+    def configure(&block)
+      Stenotype::Configuration.configure(&block)
+    end
+
+    ##
+    # @return {Stenotype::Configuration}
+    #
+    def config
+      Stenotype::Configuration
+    end
+  end
+end
+
+require "stenotype/adapters"
+require "stenotype/configuration"
+require "stenotype/context_handlers"
+require "stenotype/dispatcher"
+require "stenotype/event"
+require "stenotype/event_serializer"
+require "stenotype/exceptions"
+require "stenotype/version"
+require "stenotype/frameworks/object_ext"
+
+Stenotype.configure do |config|
+  config.uuid_generator = SecureRandom
+  config.dispatcher     = Stenotype::Dispatcher.new
+
+  config.gc_project_id  = ENV['GC_PROJECT_ID']
+  config.gc_credentials = ENV['GC_CREDENTIALS']
+  config.gc_topic       = ENV['GC_TOPIC']
+  config.gc_mode        = :async
+
+  config.targets = [
+    Stenotype::Adapters::StdoutAdapter.new,
+    Stenotype::Adapters::GoogleCloud.new
+  ]
+
+  Stenotype::ContextHandlers.module_eval do
+    register Stenotype::ContextHandlers::Klass
+  end
+
+  Object.send(:include, Stenotype::Frameworks::ObjectExt)
+end
+
+if defined?(Rails)
+  require "stenotype/frameworks/rails/action_controller"
+  require "stenotype/frameworks/rails/active_job"
+
+  module Stenotype
+    class Railtie < Rails::Railtie # :nodoc:
+      config.stenotype = Stenotype.config
+
+      #
+      # Register Rails handlers
+      #
+      Stenotype::ContextHandlers.module_eval do
+        register Stenotype::ContextHandlers::Rails::Controller
+        register Stenotype::ContextHandlers::Rails::ActiveJob
+      end
+
+      ActiveSupport.on_load(:action_controller) do
+        include Stenotype::Frameworks::Rails::ActionControllerExtension
+      end
+
+      ActiveSupport.on_load(:active_job) do
+        # @todo: consider using `::ActiveJob::Base.around_perform`
+        #        or `::ActiveJob::Base.around_enqueue`
+        extend Stenotype::Frameworks::Rails::ActiveJobExtension
+      end
+    end
+  end
+end

data/stenotype.gemspec

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require "stenotype/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = 'stenotype'
+  spec.version       = Stenotype::VERSION
+  spec.authors       = ["Roman Kapitonov"]
+  spec.email         = ["roman.kapitonov@freshly.com"]
+
+  spec.summary       = 'Gem for emitting events and sending them to an external system.'
+  spec.description   = 'Pretty much it'
+  spec.homepage      = 'https://github.com/Freshly/stenotype'
+  spec.license       = 'MIT'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/Freshly/stenotype'
+  spec.metadata['changelog_uri'] = 'https://github.com/Freshly/stenotype/CHANGELOG.md'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activesupport', '>= 5.0.0'
+  spec.add_dependency 'google-cloud-pubsub', '~> 1.0.0'
+
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'github-markup', '~> 3.0'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'redcarpet', '~> 3.5'
+  spec.add_development_dependency 'yard', '~> 0.9'
+
+  spec.add_development_dependency 'pry', '~> 0.12'
+  spec.add_development_dependency 'rails', '~> 5.2.3'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '~> 0.76'
+  spec.add_development_dependency 'simplecov', '~> 0.17'
+  spec.add_development_dependency 'timecop', '~> 0.9'
+end