stenotype 0.1.0 → 0.1.1

data/lib/generators/stenotype/initializer/initializer_generator.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Stenotype
+  #
+  # A module enclosing Rails generators for gem setup
+  #
+  module Generators
+    #
+    # A class for generating a Rails initializer to setup the gem
+    # upon rails application load.
+    #
+    class InitializerGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      #
+      # Creates an initializer for rails application
+      #
+      def create_initializer
+        template "initializer.rb.erb", File.join("config/initializers/stenotype.rb")
+      end
+    end
+  end
+end

data/lib/generators/stenotype/initializer/templates/initializer.rb.erb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+Rails.application.configure do
+  #
+  # Stenotype allows you to emit events which are then being published to a list of
+  # targets. Currently two targets are provided by default: Google Cloud Pub Sub and
+  # STDOUT for debug purposes.
+  #
+  # There is also a rails integration module which defines a handy DSL
+  # for triggering events in various Rails components. ActionController and
+  # ActiveJob are supported at the time of writing.
+  #
+  # Both extensions for Rails are enabled by default, but there are config options
+  # to control their presence.
+  # config.stenotype.rails do |rails_modules|
+  #   rails_modules.enable_action_controller_ext = true
+  #   rails_modules.enable_active_job_ext = true
+  # end
+  #
+  #
+  # To make publishing possible one must specify a list of targets. You could use
+  # StdoutAdapter for debug purposes before switching to a production publisher.
+  # By default the list of targets is empty and you'll get an error saying
+  # that no targets are specified.
+  #
+  # A config option is available for setting up the targets:
+  #
+  # config.stenotype.targets = [Stenotype::Adapters::StdoutAdapter.new]
+  #
+  # Or using Google Cloud:
+  #
+  # config.stenotype.targets = [Stenotype::Adapters::GoogleCloud.new]
+  #
+  # Or both:
+  #
+  # config.stenotype.targets = [
+  #   Stenotype::Adapters::StdoutAdapter.new,
+  #   Stenotype::Adapters::GoogleCloud.new
+  # ]
+  #
+  # To be able to use Google Cloud one has to specify Google Cloud credentials:
+  #
+  # config.stenotype.google_cloud do |gc_config|
+  #   gc_config.credentials = "SPECIFY YOUR CREDENTIALS" # path/to/key.json
+  #   gc_config.project_id = "SPECIFY YOUR PROJECT ID"
+  #   gc_config.topic = "SPECIFY YOUR TOPIC"
+  #   gc_config.mode = :async
+  # end
+  #
+  # Each event is shipped with a UUID generated with SecureRandom by default.
+  # This might be changed by using a corresponding config option. Note that
+  # uuid_generator expects method #uuid to be implemented
+  #
+  # config.stenotype.uuid_generator = SecureRandom
+  #
+  # In rare cases you might want to get control over how the event is being dispatched.
+  # Dispatcher must implement instance method #publish.
+  # Which dispatcher to use is controlled by the following config option:
+  #
+  # config.stenotype.dispatcher = Stenotype::Dispatcher
+  #
+end
+
+# For more usage instructions please refer to either README.md or yard documentation
+# in gem repository https://github.com/Freshly/stenotype

data/lib/stenotype.rb

@@ -1,98 +1,37 @@
 # 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
+require "securerandom"
 
-    ##
-    # @return {Stenotype::Configuration}
-    #
-    def config
-      Stenotype::Configuration
-    end
-  end
-end
+require "spicery"
+require "stenotype/version"
 
 require "stenotype/adapters"
+require "stenotype/dispatcher"
 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
+require "stenotype/emitter"
 
-  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)
+#
+# A top level namespace for the freshly-events gem
+#
+module Stenotype
+  # A wrapper class for Stenotype specific errors
+  class Error < StandardError; end
+  # This exception is being raised upon unsuccessful publishing of an event.
+  class MessageNotPublishedError < Error; end
+  # This exception is being raised in case no targets are
+  # specified {Stenotype::Configuration}.
+  class NoTargetsSpecifiedError < Error; end
+  # This exception is being raised upon using a context handler which
+  # has never been registered in known handlers in {Stenotype::ContextHandlers::Collection}.
+  class UnknownHandlerError < Error; end
+
+  include Spicerack::Configurable::ConfigDelegation
+  delegates_to_configuration
 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
+Stenotype::ContextHandlers.register(Stenotype::ContextHandlers::Klass)
 
-      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
+require "stenotype/railtie" if defined?(Rails)

data/lib/stenotype/adapters.rb

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

data/lib/stenotype/adapters/base.rb

@@ -11,6 +11,16 @@ module Stenotype
     # An abstract base class for implementing adapters
     #
     # @abstract
+    # @example Defining a custom adapter
+    #  MyCustomAdapter < Stenotype::Adapters::Base
+    #    def publish(event_data, **additional_arguments)
+    #      client.publish(event_data, **additional_arguments)
+    #    end
+    #
+    #    def client
+    #      @client ||= SomeCustomClient.new(some_credential)
+    #    end
+    #  end
     #
     class Base
       attr_reader :client

data/lib/stenotype/adapters/google_cloud.rb

@@ -1,55 +1,87 @@
 # frozen_string_literal: true
 
-require 'google/cloud/pubsub'
+require "google/cloud/pubsub"
 
 module Stenotype
   module Adapters
     #
     # An adapter implementing method {#publish} to send data to Google Cloud PubSub
     #
+    # @example A general usage within some method in the class
+    #   class EventEmittingClass
+    #     def method_emitting_enent
+    #       result_of_calculations = collect_some_data
+    #       gc_adapter.publish(result_of_calculation, additional: :data, more: :data)
+    #       result_of_calculations
+    #     end
+    #
+    #     def gc_adapter
+    #       Stenotype::Adapters::GoogleCloud.new
+    #     end
+    #   end
+    #
+    # @example Overriding a client
+    #   class EventEmittingClass
+    #     def method_emitting_enent
+    #       result_of_calculations = collect_some_data
+    #       gc_adapter.publish(result_of_calculation, additional: :data, more: :data)
+    #       result_of_calculations
+    #     end
+    #
+    #     def gc_adapter
+    #       Stenotype::Adapters::GoogleCloud.new(client: CustomGcClient.new)
+    #     end
+    #   end
+    #
     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
+      # @raise {Stenotype::MessageNotPublishedError} unless message is published
+      #
+      # @example With default client
+      #   google_cloud_adapter = Stenotype::Adapters::GoogleCloud.new
+      #   # publishes to default client
+      #   google_cloud_adapter.publish({ event: :data }, { additional: :data })
       #
-      # rubocop:disable Metrics/MethodLength
+      # @example With client override
+      #   google_cloud_adapter = Stenotype::Adapters::GoogleCloud.new(CustomGCClient.new)
+      #   # publishes to default CustomGCClient
+      #   google_cloud_adapter.publish({ event: :data }, { additional: :data })
       #
       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)
+        if config.async
+          publish_async(event_data, **additional_arguments)
         else
-          raise Stenotype::Exceptions::GoogleCloudUnsupportedMode,
-                'Please use either :sync or :async modes for publishing the events.'
+          publish_sync(event_data, **additional_arguments)
         end
       end
-      # rubocop:enable Metrics/MethodLength
 
       private
 
+      def publish_sync(event_data, **additional_arguments)
+        topic.publish(event_data, additional_arguments)
+      end
+
+      def publish_async(event_data, **additional_arguments)
+        topic.publish_async(event_data, additional_arguments) do |result|
+          raise Stenotype::MessageNotPublishedError unless result.succeeded?
+        end
+      end
+
       # :nocov:
       def client
-        @client ||= Google::Cloud::PubSub.new(
-          project_id: config.gc_project_id,
-          credentials: config.gc_credentials
-        )
+        @client ||= Google::Cloud::PubSub.new(project_id: config.project_id, credentials: config.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
+        @topic ||= client.topic config.topic
       end
 
       def config
-        Stenotype.config
+        Stenotype.config.google_cloud
       end
     end
   end

data/lib/stenotype/adapters/stdout_adapter.rb

@@ -5,12 +5,34 @@ 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
       #
+      # @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_arguments)
-        client.info(event_data, **additional_arguments)
+        client.info(**event_data, **additional_arguments)
       end
 
       private

data/lib/stenotype/configuration.rb

@@ -4,46 +4,101 @@ module Stenotype
   #
   # A module containing freshly-event gem configuration
   #
+  # @example Configuring the library
+  #   Stenotype.configure do |config|
+  #     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 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 :targets, default: []
+      option :dispatcher, default: Stenotype::Dispatcher
+      option :uuid_generator, default: SecureRandom
+
+      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 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]
+    #
+    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