stenotype 0.1.0

data/lib/stenotype/adapters/google_cloud.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'google/cloud/pubsub'
+
+module Stenotype
+  module Adapters
+    #
+    # An adapter implementing method {#publish} to send data to Google Cloud PubSub
+    #
+    class GoogleCloud < Base
+      #
+      # @param event_data {Hash} The data to be published to Google Cloud
+      # @raise {Stenotype::Exceptions::GoogleCloudUnsupportedMode} unless the mode
+      #   in configured to be :sync or :async
+      # @raise {Stenotype::Exceptions::MessageNotPublished} unless message is published
+      #
+      # rubocop:disable Metrics/MethodLength
+      #
+      def publish(event_data, **additional_arguments)
+        case config.gc_mode
+        when :async
+          topic.publish_async(event_data, additional_arguments) do |result|
+            raise Stenotype::Exceptions::MessageNotPublished unless result.succeeded?
+          end
+        when :sync
+          topic.publish(event_data, additional_arguments)
+        else
+          raise Stenotype::Exceptions::GoogleCloudUnsupportedMode,
+                'Please use either :sync or :async modes for publishing the events.'
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      private
+
+      # :nocov:
+      def client
+        @client ||= Google::Cloud::PubSub.new(
+          project_id: config.gc_project_id,
+          credentials: config.gc_credentials
+        )
+      end
+
+      # Use memoization, otherwise a new topic will be created
+      # every time. And a new async_publisher will be created.
+      # :nocov:
+      def topic
+        @topic ||= client.topic config.gc_topic
+      end
+
+      def config
+        Stenotype.config
+      end
+    end
+  end
+end

data/lib/stenotype/adapters/stdout_adapter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Stenotype
+  module Adapters
+    #
+    # An adapter implementing method {#publish} to send data to STDOUT
+    #
+    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)
+      end
+
+      private
+
+      def client
+        @client ||= Logger.new(STDOUT)
+      end
+    end
+  end
+end

data/lib/stenotype/adapters.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'stenotype/adapters/base'
+require 'stenotype/adapters/google_cloud'
+require 'stenotype/adapters/stdout_adapter'

data/lib/stenotype/configuration.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Stenotype
+  #
+  # A module containing freshly-event gem configuration
+  #
+  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
+      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
+      end
+    end
+  end
+end

data/lib/stenotype/context_handlers/base.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Stenotype
+  module ContextHandlers
+    #
+    # An abstract base class for implementing contexts handlers
+    #
+    # @abstract
+    # @attr_reader {Object} context A context in which the event was emitted
+    # @attr_reader {Hash} options A hash of additional options
+    #
+    class Base
+      attr_reader :context, :options
+
+      #
+      # @param context {Object} A context where the event was emitted
+      # @param options {Hash} A hash of additional options
+      #
+      # @return {#as_json} A context handler implementing [#as_json]
+      #
+      def initialize(context, options = {})
+        @context = context
+        @options = options
+      end
+
+      #
+      # @abstract
+      # @raise {NotImplementedError} subclasses must implement this method
+      #
+      def as_json(*_args)
+        raise NotImplementedError, "#{self} must implement method ##{__method__}"
+      end
+
+      #
+      # @attr_writer {Symbol} handler_name The name under which a handler is going to be registered
+      #
+      class << self
+        # Handler name by which it will be registered in {Stenotype::ContextHandlers::Collection}
+        attr_writer :handler_name
+
+        #
+        # @return {Symbol} Name of the handler
+        # @raise {NotImplementedError} in case handler name is not specified.
+        #
+        def handler_name
+          @handler_name || raise(NotImplementedError,
+                                 "Please, specify the handler_name of #{self}")
+        end
+      end
+    end
+  end
+end

data/lib/stenotype/context_handlers/collection.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Stenotype
+  module ContextHandlers
+    #
+    # A class representing a list of available context handlers
+    #
+    class Collection < Array
+      #
+      # @param handler_name {Symbol} a handler to be found in the collection
+      # @raise {Stenotype::Exceptions::UnknownHandler} in case a handler is not registered
+      # @return {#as_json} A handler which respond to #as_json
+      #
+      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.")
+      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
+      #
+      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
+
+      #
+      # @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
+      #
+      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)
+        self
+      end
+
+      #
+      # @param handler {#as_json} a handler to be checked for presence in a collection
+      # @return [true, false]
+      #
+      def registered?(handler)
+        include?(handler)
+      end
+    end
+  end
+end

data/lib/stenotype/context_handlers/klass.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Stenotype
+  module ContextHandlers
+    #
+    # Plain Ruby class handler to support fetching data from a class
+    #
+    class Klass < Stenotype::ContextHandlers::Base
+      self.handler_name = :klass
+
+      #
+      # @todo r.kapitonov Figure out the params
+      # @return {Hash} a JSON representation of a Ruby class
+      #
+      def as_json(*_args)
+        {}
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Stenotype
+  module ContextHandlers
+    #
+    # A namespace containing extension of rails components
+    # for fetching specific data from those components.
+    # For example fetching request from a controller context,
+    # or fetching ActiveJob attributes from an ActiveJob instance
+    #
+    module Rails
+      #
+      # ActiveJob handler to support fetching data out of an ActiveJob instance
+      #
+      class ActiveJob < Stenotype::ContextHandlers::Base
+        self.handler_name = :active_job
+
+        #
+        # @todo How to deal with _args? It won't necessarily respond to #as_json
+        # @return {Hash} a JSON representation of job's data
+        #
+        def as_json(*_args)
+          {
+            job_id: job_id,
+            enqueued_at: Time.now,
+            queue_name: queue_name,
+            class: context.class.name
+          }
+        end
+
+        private
+
+        def job_id
+          context.job_id
+        end
+
+        def queue_name
+          context.queue_name
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Stenotype
+  module ContextHandlers
+    module Rails
+      #
+      # ActionController handler to support fetching data out of a rails controller instance
+      #
+      class Controller < Stenotype::ContextHandlers::Base
+        self.handler_name = :controller
+
+        #
+        # @return {Hash} a JSON representation of controller's data
+        #
+        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
+          }
+        end
+
+        private
+
+        def request
+          context.request
+        end
+      end
+    end
+  end
+end

data/lib/stenotype/context_handlers.rb

@@ -0,0 +1,32 @@
+# 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'
+
+module Stenotype
+  #
+  # A namespace to contain various context
+  # handlers implementations
+  #
+  module ContextHandlers
+    class << self
+      attr_writer :known
+      #
+      # @return {Array<#publish>} A list of handlers implementing [#publish]
+      #
+      def known
+        @known ||= Stenotype::ContextHandlers::Collection.new
+      end
+
+      #
+      # @param handler {#publish} A handler with implemented method [#publish]
+      #
+      def register(handler)
+        known.register(handler)
+      end
+    end
+  end
+end

data/lib/stenotype/dispatcher.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Stenotype
+  #
+  # {Stenotype::Dispatcher} is responsible for gluing together
+  # publishing targets and data gathering.
+  #
+  class Dispatcher
+    #
+    # Publishes an event to the list of configured targets.
+    #
+    # @example
+    #
+    #   event = Stenotype::Event.new(data, options, eval_context)
+    #   Stenotype::Dispatcher.new.publish(event)
+    #
+    # @param event {Stenotype::Event} An instance of event to be published.
+    # @param serializer {#serialize} A class responsible for serializing the event
+    # @return {Stenotype::Dispatcher} for the sake of chaining
+    #
+    def publish(event, serializer: Stenotype::EventSerializer)
+      event_data = serializer.new(event).serialize
+
+      targets.each do |t|
+        t.publish(event_data)
+      end
+
+      self
+    end
+
+    private
+
+    def targets
+      Stenotype.config.targets
+    end
+  end
+end

data/lib/stenotype/event.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Stenotype
+  #
+  # {Stenotype::Event} represents a triggered event
+  #
+  class Event
+    #
+    # Delegates event to instance of {Stenotype::Event}.
+    #
+    # @example
+    #
+    #   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]
+    # @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
+    end
+
+    attr_reader :data, :options, :eval_context, :dispatcher
+
+    #
+    # @example
+    #
+    #   Stenotype::Event.emit!(data, options, eval_context)
+    #
+    # @param {Hash} data Data to be published to the targets.
+    # @param {Hash} options A hash of additional options to be tracked.
+    # @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
+      @eval_context = eval_context
+      @dispatcher = dispatcher
+    end
+
+    #
+    # Emits a {Stenotype::Event}.
+    #
+    # @example
+    #
+    #   event = Stenotype::Event.new(data, options, eval_context)
+    #   event.emit!
+    #
+    def emit!
+      dispatcher.publish(self)
+    end
+  end
+end

data/lib/stenotype/event_serializer.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+require 'securerandom'
+
+module Stenotype
+  #
+  # A class used to serialize a {Stenotype::Event}
+  # upon publishing it to targets
+  #
+  class EventSerializer
+    attr_reader :event, :uuid_generator
+
+    #
+    # @param event {Stenotype::Event}
+    # @param uuid_generator {#uuid} an object responding to [#uuid]
+    #
+    def initialize(event, uuid_generator: Stenotype.config.uuid_generator)
+      @event = event
+      @uuid_generator = uuid_generator
+    end
+
+    #
+    # @return {Hash} A hash representation of the event and its context
+    #
+    def serialize
+      {
+        **event_data,
+        **event_options,
+        **default_options,
+        **eval_context_options
+      }
+    end
+
+    private
+
+    def event_data
+      event.data
+    end
+
+    def event_options
+      event.options
+    end
+
+    def eval_context
+      event.eval_context
+    end
+
+    def eval_context_options
+      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
+
+    def default_options
+      {
+        timestamp: Time.now.utc,
+        uuid: uuid_generator.uuid
+      }
+    end
+  end
+end

data/lib/stenotype/exceptions.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Stenotype
+  #
+  # A namespace for holding library-level exceptions.
+  #
+  module Exceptions
+    #
+    # This exception is being raised in case an unsupported mode
+    # for Google Cloud is specified.
+    #
+    class GoogleCloudUnsupportedMode < StandardError; end
+
+    #
+    # This exception is being raised upon unsuccessful publishing of an event.
+    #
+    class MessageNotPublished < StandardError; end
+
+    #
+    # This exception is being raised in case no targets are
+    # specified {Stenotype::Configuration}.
+    #
+    class NoTargetsSpecified < StandardError; end
+
+    #
+    # This exception is being raised upon using a context handler which
+    # has never been registered in known handlers in {Stenotype::ContextHandlers::Collection}.
+    #
+    class UnknownHandler < StandardError; end
+  end
+end