stenotype 0.1.0 → 0.1.6

data/Rakefile

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 

data/TODO.md

@@ -15,3 +15,21 @@
  - [ ] Figure out the params for plain ruby class context handler.
  - [ ] Consider `ContextHandlers::ActiveJob` params. How to deal with \_args? It won't necessarily respond to `#as_json`.
  - [ ] Consider a way to switch from evaluating ruby code to using plain modules extension.
+
+Feedback TODO:
+
+ - [x] Move all exceptions into root module Stenotype. **Moved exceptions into root module**
+ - [x] Inherit gem specific error from a root error object specific for the gem. **All gem specific error inherit from Stenotype::Errors**
+ - [x] Inherit the root error from standard error. **Stenotype::Errors inherits from StandardError**
+ - [x] Utilize concerns and allow gem users to extend the code they need with a concern rather than aggressively extend Object. **Added an Stenotype::Emitter module instead of aggressively including it into Object**
+ - [x] Use Railtie to introduce rails specific logic instead of checking whether Rails is defined in the root module. **Added a Railtie, active only in Rails world**
+ - [?] Use delegation instead of defining tiny methods. Do not forget about Demeter's. **Rails `delegate` method is used in Rails specific extensions. Otherwise simple methods are used**
+ - [x] Add more examples to yard documentation, consider collecting README.md from the yard doc. **Covered most of the classes/modules with yard examples**
+ - [x] Enable on-off triggers in the configuration to  enable/disable framework specific features. Like whether  we want to extend ActiveJob or not. **Added two configuration options for currently implemented Rails extensions**
+ - [x] Memoization! **Not actually needed**
+ - [ ] Consider potential double wrapping in the meta-programming stuff. Take a look at around-the-world and consider switching to using it.
+ - [ ] Utilize input objects for attr_readers (what was the name of the tool?)
+ - [ ] Consider configurable for configuration instead of implementing custom configuration object
+ - [ ] Consider using collectible gem to handle collection of context handlers
+ - [ ] Consider naming (e.g. #as_json => #to_h), try to be more  specific to not pollute the namespace or introduce any ambiguity.
+ - [ ] Remove freshly mentions from the gem.

data/bin/console

@@ -1,8 +1,8 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'bundler/setup'
-require 'stenotype'
+require "bundler/setup"
+require "stenotype"
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -11,5 +11,5 @@ require 'stenotype'
 # require "pry"
 # Pry.start
 
-require 'pry'
+require "pry"
 Pry.start(__FILE__)

data/lib/generators/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Generate the Stenotype configuration initializer.
+
+Example:
+    `rails generate stenotype:initializer`
+
+    Generates:
+      Initializer: config/initializers/stenotype.rb

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,82 @@
+# frozen_string_literal: true
+
+Rails.application.configure do
+  Stenotype.configure do |config|
+    #
+    # 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.rails do |rails_modules|
+    #   rails_modules.enable_action_controller_ext = true
+    #   rails_modules.enable_active_job_ext = true
+    # end
+    #
+    # To enable or disable the library use the following config option:
+    #
+    # config.enabled = true # or false
+    #
+    # 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.targets = [Stenotype::Adapters::StdoutAdapter.new]
+    #
+    # Or using Google Cloud:
+    #
+    # config.targets = [Stenotype::Adapters::GoogleCloud.new]
+    #
+    # Or both:
+    #
+    # config.targets = [
+    #   Stenotype::Adapters::StdoutAdapter.new,
+    #   Stenotype::Adapters::GoogleCloud.new
+    # ]
+    #
+    # To be able to use Google Cloud one has to specify Google Cloud credentials:
+    #
+    # config.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.async = true
+    # 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.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.dispatcher = Stenotype::Dispatcher
+    #
+    # An option to suppress exception within a gem is available:
+    #
+    # config.graceful_error_handling = true
+    #
+    # To log errors a logger config option is available. Logger.new(STDOUT) is used by default.
+    #
+    # config.logger = Logger.new(STDOUT)
+    #
+    # Add your own context handlers
+    #
+    # Stenotype::ContextHandlers.register Your::Custom::HandlerClass
+    #
+  end
+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
@@ -25,12 +35,25 @@ module Stenotype
       #
       # This method is expected to be implemented by subclasses
       # @abstract
-      # @raise [NotImplementedError] unless implemented in a subclass
+      # @raise {NotImplementedError} unless implemented in a subclass
       #
-      def publish(_event_data, **_additional_arguments)
+      def publish(_event_data, **_additional_attrs)
         raise NotImplementedError,
               "#{self.class.name} must implement method #publish"
       end
+
+      #
+      # This method is expected to be implemented by subclasses. In case async
+      # publisher is used the process might end before the async queue of
+      # messages is processed, so this method is going to be used in a
+      # `at_exit` hook to flush the queue.
+      # @abstract
+      # @raise {NotImplementedError} unless implemented in a subclass
+      #
+      def flush!
+        raise NotImplementedError,
+              "#{self.class.name} must implement method #flush"
+      end
     end
   end
 end

data/lib/stenotype/adapters/google_cloud.rb

@@ -1,55 +1,103 @@
 # 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
+      attr_reader :topic
+
+      def initialize(client: nil, topic: nil)
+        super(client: client)
+        @topic = topic
+      end
       #
       # @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)
+      def publish(event_data, **additional_attrs)
+        if config.async
+          publish_async(event_data, **additional_attrs)
         else
-          raise Stenotype::Exceptions::GoogleCloudUnsupportedMode,
-                'Please use either :sync or :async modes for publishing the events.'
+          publish_sync(event_data, **additional_attrs)
         end
       end
-      # rubocop:enable Metrics/MethodLength
+
+      #
+      # Flushes the topic's async queue
+      #
+      def flush!
+        # a publisher might be uninitialized until the first event is published
+        return unless topic.async_publisher
+
+        topic.async_publisher.stop.wait!
+      end
 
       private
 
+      def publish_sync(event_data, **additional_attrs)
+        topic.publish(event_data, additional_attrs)
+      end
+
+      def publish_async(event_data, **additional_attrs)
+        topic.publish_async(event_data, additional_attrs) 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