stenotype 0.1.2 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b998a75c7aef576ca3040ad7cd7a07082fddc9cd937b57e3d3e84d807124aba
-  data.tar.gz: 29d5bc462c420c881eeeeca851146c74e8f6db1240de777d8e19ca0806274fdd
+  metadata.gz: fe2154ff56ce545931546a0f3fd9abb43b5515ff76eaee7c525af6066caff76e
+  data.tar.gz: 3abc9503558892fc6a00c23207f3e520ff5b6cf711ac5bc355d36a010f89acb5
 SHA512:
-  metadata.gz: 71094a00ecce450e4e2edbbda1327cf2f794c52d5d64bd304b67ec5f2498e49020c0ed4f2a07bc9425d5df8929ebe2d809447ea4b52baca0eb6569af27fcf22a
-  data.tar.gz: 1874d642a66cc7a2771fd78e92a2dc3e7aaea9ea520055cc2b7abe5bb2f9bf51dce5989e1498352411d134a371ec8b546ded1e8cb8e3d75b7408eaa340d06cbd
+  metadata.gz: e9a152c55f8e5e7db574bf2b66adb0f3cb046a4d1549f1c370bc02235f184663a0d2c691378a7ce818da0e20382b22694834b12d8fdab1e39d3126e7e2965f53
+  data.tar.gz: 9ffbd36708152e9006d335e6f76ed46db162dbcba8a8c23ab388f84fce2ed47507b8c39c0966ab5558955bb47490c90f988cf2f1fd7b346dc0bf17ddd6ffb4de

data/.gitignore

@@ -11,3 +11,6 @@
 .rspec_status
 /.rakeTasks
 /.idea
+
+# rbenv
+.ruby-version

data/CHANGELOG.md

@@ -1,6 +1,25 @@
 # Changelog
 
-*Release Date*: 2019/11/21
+*Release Date*: 2020/01/13
+
+### 0.1.7 2020/01/20
+* Adds a config option to allow explicit adapter setup.
+* Adds an `after_initialize` rails hook to setup adapters.
+* Remove topic from the list of Google Cloud adapter arguments.
+
+### 0.1.6 2020/01/17
+* Allow topic to be explicitly set upon Google Cloud adapter initialization
+
+### 0.1.5 2020/01/13
+* In case `graceful_error_handling` is set to off raise a generic `Stenotype::Error` on any exception in order to intercept a single error type in the client code.
+* Adds an `at_exit` hook to flush the async message queue when using the library in async mode.
+
+### 0.1.4 2020/01/10
+* Adds a new configuration option `graceful_error_handling` to suppress errors raised from the gem's internals yet logging the error to specified `config.logger`
+
+### 0.1.3: 2020/01/10
+* Adds a new configuration option `logger` to use during error handling
+* Adds a new config option `Stenotype.config.enabled`. If the option is set to false then event is not going to be published. The option is `true` by default.
 
 ### 0.1.2: 2019/12/10
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    stenotype (0.1.2)
+    stenotype (0.1.7)
       activesupport (>= 5.0.0)
       google-cloud-pubsub (~> 1.0.0)
       spicery (>= 0.19.0, < 1.0)
@@ -75,7 +75,7 @@ GEM
       tablesalt (= 0.19.2)
     faker (1.9.6)
       i18n (>= 0.7)
-    faraday (0.17.1)
+    faraday (0.17.3)
       multipart-post (>= 1.2, < 3)
     github-markup (3.0.4)
     globalid (0.4.2)
@@ -110,7 +110,7 @@ GEM
       multi_json (~> 1.11)
       os (>= 0.9, < 2.0)
       signet (~> 0.12)
-    grpc (1.25.0-universal-darwin)
+    grpc (1.26.0-universal-darwin)
       google-protobuf (~> 3.8)
       googleapis-common-protos-types (~> 1.0)
     grpc-google-iam-v1 (0.6.9)
@@ -147,7 +147,7 @@ GEM
       coderay (~> 1.1.0)
       method_source (~> 0.9.0)
     public_suffix (4.0.1)
-    rack (2.0.7)
+    rack (2.0.8)
     rack-test (1.1.0)
       rack (>= 1.0, < 3)
     rails (5.2.4)

data/README.md

@@ -25,13 +25,17 @@ Or install it yourself as:
 Configuring the library is as simple as:
 ```ruby
 Stenotype.configure do |config|
+  config.enabled = true
   config.targets = [ # Supported targets
     Stenotype::Adapters::StdoutAdapter.new,
     Stenotype::Adapters::GoogleCloud.new
   ]
 
-  config.uuid_generator = SecureRandom
-  config.dispatcher     = Stenotype::Dispatcher.new
+  config.uuid_generator               = SecureRandom
+  config.dispatcher                   = Stenotype::Dispatcher.new
+  config.logger                       = Logger.new(STDOUT)
+  config.graceful_error_handling      = true
+  config.auto_adapter_initialization  = true
 
   config.google_cloud do |gc_config|
     gc_config.project_id  = "google_cloud_project_id"
@@ -47,10 +51,22 @@ Stenotype.configure do |config|
 end
 ```
 
+#### config.enabled
+
+A flag checked upon emission of an event. Will prevent event emission if set to false. An event is emitted if set to true.
+
 #### config.targets
 
 Contain an array of targets for the events to be published to. Targets must implement method `#publish(event_data, **additional_arguments)`.
 
+#### config.logger
+
+Specifies a logger for messages and exceptions to be output to. If not set defaults to `Logger.new(STDOUT)`, otherwise a manually set logger is used.
+
+#### config.graceful_error_handling
+
+This flag if set to `true` is going to suppress all `StandardError`'s raised within a gem. Raises the error to the caller if set to `false`
+
 #### config.uuid_generator
 
 An object that must implement method `#uuid`. Used when an event is emitted to generate a unique id for each event.
@@ -83,6 +99,10 @@ Allows to enable/disable Rails ActionController extension
 
 Allows to enable/disable Rails ActiveJob extension
 
+#### config.rails.auto_adapter_initialization
+
+Controls whether the hook `auto_initialize!` is run for each adapter. If set to true `auto_initialize!` is invoked for every adapter. If false `auto_initialize!` is not run. For example for google cloud adapter this will instantiate `client` and `topic` objects before first publish. If set to false `client` and `topic` are lazy initialized.
+
 #### Configuring context handlers
 
 Each event is emitted in a context which might be an ActionController instance or an ActiveJob instance or potentially any other place. Context handlers are implemented as plain ruby classes, so before using them you must register them. By default a plain `Class` handler is registered when not used with any framework. In case Ruby on Rails is used, then there are two additional context handlers for `ActionController` and `ActiveJob` instances.
@@ -213,6 +233,14 @@ class CustomAdapter < Stenotype::Adapters::Base
   def publish(event_data, **additional_arguments)
     # custom publishing logic
   end
+
+  def flush!
+    # actions to be taken to flush the messages
+  end
+
+  def auto_initialize!
+    # actions to be taken to setup internal adapter state (client, endpoint, whatsoever)
+  end
 end
 ```
 

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

@@ -18,6 +18,9 @@ Rails.application.configure do
     #   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.
@@ -60,6 +63,14 @@ Rails.application.configure do
     #
     # 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

data/lib/stenotype/adapters/base.rb

@@ -35,12 +35,33 @@ 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_attrs)
         raise NotImplementedError,
               "#{self.class.name} must implement method #publish"
       end
+
+      #
+      # Allows custom setup of the adapter. Noop by default
+      # @abstract
+      #
+      def auto_initialize!
+        # noop by default
+      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

@@ -56,6 +56,26 @@ module Stenotype
         end
       end
 
+      #
+      # 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
+
+      #
+      # If not called both client and topic are lazy initialized on first call (if not
+      # passed to #initialize). #auto_initialize! is going to explicitly initialize
+      # both client and topic.
+      #
+      def auto_initialize!
+        client
+        topic
+      end
+
       private
 
       def publish_sync(event_data, **additional_attrs)

data/lib/stenotype/adapters/stdout_adapter.rb

@@ -40,6 +40,13 @@ module Stenotype
         end
       end
 
+      #
+      # Does nothing
+      #
+      def flush!
+        # noop
+      end
+
       private
 
       def client

data/lib/stenotype/at_exit.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# :nocov:
+require "stenotype"
+
+at_exit do
+  targets = Stenotype.config.targets
+  targets.each(&:flush!)
+end
+# :nocov:

data/lib/stenotype/configuration.rb

@@ -6,6 +6,7 @@ module Stenotype
   #
   # @example Configuring the library
   #   Stenotype.configure do |config|
+  #     config.enabled = true
   #     config.targets = [Target1.new, Target2.new]
   #     config.uuid_generator = SecureRandom
   #
@@ -25,6 +26,18 @@ module Stenotype
   module Configuration
     extend Spicerack::Configurable
 
+    # @!attribute graceful_error_handling
+    # @return {true, false} a flag for suppressing error raised withing the gem
+
+    # @!attribute logger
+    # @return {Logger} a logger with default severity methods to output gem level messages
+
+    # @!attribute enabled
+    # @return {true, false} a flag indicating whether event emission is enabled
+
+    # @!attribute auto_adapter_initialization
+    # @return {true, false} enables/disables lazy initialization of adapters' clients
+
     # @!attribute targets
     # @return {Array<#publish>} a list of targets responding to method [#publish]
 
@@ -49,7 +62,6 @@ module Stenotype
     # @!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.
 
@@ -60,9 +72,12 @@ module Stenotype
     # @return [true, false] A flag of whether ActiveJob ext is enabled
 
     configuration_options do
+      option :graceful_error_handling, default: true
+      option :enabled, default: true
       option :targets, default: []
       option :dispatcher, default: Stenotype::Dispatcher
       option :uuid_generator, default: SecureRandom
+      option :logger
 
       nested :google_cloud do
         option :credentials, default: nil
@@ -74,11 +89,34 @@ module Stenotype
       nested :rails do
         option :enable_action_controller_ext, default: true
         option :enable_active_job_ext, default: true
+        option :auto_adapter_initialization, default: false
       end
     end
 
     module_function
 
+    #
+    # @example With default logger
+    #   Stenotype.configure do |config|
+    #     # config.logger = nil # logger not set manually
+    #   end
+    #   Stenotype.config.logger #=> `Logger.new(STDOUT)` instance
+    #
+    # @example With custom logger
+    #   Stenotype.configure do |config|
+    #     config.logger = custom_logger_instance
+    #   end
+    #   Stenotype.config.logger #=> custom_logger_instance
+    #
+    # @return [{Logger, CustomLogger}] a logger object. Logger.new(STDOUT) by
+    #   default if another is not set during configuration
+    #
+    def logger
+      return config.logger if config.logger
+
+      config.logger || Logger.new(STDOUT)
+    end
+
     #
     # @example When at least one target is present
     #   Stenotype.configure do |config|
@@ -93,6 +131,8 @@ module Stenotype
     # @raise {Stenotype::NoTargetsSpecifiedError} in case no targets are configured
     # @return {Array<#publish>} An array of targets implementing method [#publish]
     #
+    # @todo THIS NEVER GETS CALLED, needs a fix
+    #
     def targets
       return config.targets unless config.targets.empty?
 

data/lib/stenotype/event.rb

@@ -18,9 +18,21 @@ module Stenotype
     # @return {Stenotype::Event} An instance of {Stenotype::Event}
     #
     def self.emit!(name, attributes = {}, eval_context: {}, dispatcher: Stenotype.config.dispatcher)
-      event = new(name, attributes, eval_context: eval_context, dispatcher: dispatcher)
-      event.emit!
-      event
+      return unless Stenotype.config.enabled
+
+      begin
+        event = new(name, attributes, eval_context: eval_context, dispatcher: dispatcher)
+        event.emit!
+        event
+      rescue StandardError => exception
+        #
+        # @todo This is a temporary solution to enable conditional logger fetching
+        #   needs a fix to use default Spicerack::Configuration functionality
+        #
+        Stenotype::Configuration.logger.error(exception)
+
+        raise Stenotype::Error unless Stenotype.config.graceful_error_handling
+      end
     end
 
     attr_reader :name, :attributes, :eval_context, :dispatcher
@@ -52,7 +64,19 @@ module Stenotype
     #   event.emit! #=> Publishes the event to targets
     #
     def emit!
-      dispatcher.publish(self)
+      return unless Stenotype.config.enabled
+
+      begin
+        dispatcher.publish(self)
+      rescue StandardError => exception
+        #
+        # @todo This is a temporary solution to enable conditional logger fetching
+        #   needs a fix to use default Spicerack::Configuration functionality
+        #
+        Stenotype::Configuration.logger.error(exception)
+
+        raise Stenotype::Error unless Stenotype.config.graceful_error_handling
+      end
     end
   end
 end

data/lib/stenotype/railtie.rb

@@ -18,6 +18,8 @@ module Stenotype
 
     config.stenotype = Stenotype.config
 
+    config.after_initialize { config.stenotype.targets.each(&:auto_initialize!) } if config.stenotype.rails.auto_adapter_initialization
+
     if config.stenotype.rails.enable_action_controller_ext
       ActiveSupport.on_load(:action_controller) do
         Stenotype::ContextHandlers.register Stenotype::ContextHandlers::Rails::Controller

data/lib/stenotype/version.rb

@@ -2,6 +2,6 @@
 
 module Stenotype
   # :nodoc:
-  VERSION = "0.1.2"
+  VERSION = "0.1.8"
   # :nodoc:
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stenotype
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.8
 platform: ruby
 authors:
 - Roman Kapitonov
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-12-11 00:00:00.000000000 Z
+date: 2020-01-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -267,6 +267,7 @@ files:
 - lib/stenotype/adapters/base.rb
 - lib/stenotype/adapters/google_cloud.rb
 - lib/stenotype/adapters/stdout_adapter.rb
+- lib/stenotype/at_exit.rb
 - lib/stenotype/configuration.rb
 - lib/stenotype/context_handlers.rb
 - lib/stenotype/context_handlers/base.rb