gruf 2.6.1 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7280830d85a916cbc0f80677e072402b4336c59396927b6ea110943b59e5732
-  data.tar.gz: 9e2de4546c670e19f7007fc713d70485e2f45d0936c508b13512f9896efeac83
+  metadata.gz: 8fb4c36a5bd87553944bb4056fcca8875620cffe1d623f8757db6fa0e88f9aee
+  data.tar.gz: b3903a27dd46302ac99db4cbfa512b7ffc6b3ad9a4faafe83ac22fe83469ae29
 SHA512:
-  metadata.gz: b87c53908df9b5f577ff374f404f520168865092117678f4ce32b4b3264e226272965e27a243a32548bcbd32bf496fe5139801c19af549d9d641f071cda544b7
-  data.tar.gz: b9b719dc54a055313ab7ee76d95438305989aa961c4c78332555423580371842bc51ed621eae782a2d45df3cab3c9f231d6f4e512afedfda033ed7150a65fa26
+  metadata.gz: ba2ccb4ffe9915044fa8026eefa6e078b746d392af52401a779ad62bcd12ae2ae92cdfce73dc8680564d635bad0f2412b2ff3c740dd0fbfb5291a6a3c3fe70f6
+  data.tar.gz: c3db4263ae977cede3b9f3adb9cd90984e7906f72c1d005d3b61f977bb64eb3b442e8b4a092475f6fdd9af4ad5510d7e316255bbe59613c4f19d0d8231a48edf

data/CHANGELOG.md

@@ -2,6 +2,10 @@ Changelog for the gruf gem. This includes internal history before the gem was ma
 
 ### Pending release
 
+### 2.7.0
+
+- Add hook support for executing code paths before a server is started, and after a server stops
+
 ### 2.6.1
 
 - Add frozen_string_literal: true to files, update rubocop to 0.68

data/README.md

@@ -382,6 +382,46 @@ By default, the ActiveRecord Connection Reset interceptor and Output Metadata Ti
 are loaded into gruf unless explicitly told not to via the `use_default_interceptors` configuration
 parameter.
 
+## Hooks
+
+Hooks, unlike interceptors, are executed outside of the request chain, such as when a server starts
+or stops. They run in FIFO order sequentially and do not wrap one another. They can be used to provide
+custom boot sequences, external instrumentation support, or shutdown alerting. 
+
+You can create a hook by extending the `Gruf::Hooks::Base` class and defining the methods
+on the hook you wish to implement:
+
+```ruby
+class MyHook < Gruf::Hooks::Base
+  def before_server_start(server:)
+    # do my thing before the server starts  
+  end
+  
+  def after_server_stop(server:)
+    # do my thing after the server stops
+  end
+end
+
+# Then in an initializer:
+
+Gruf.configure do |c|
+  c.hooks.use(MyHook, option_foo: 'value 123')
+end
+```
+
+Exceptions raised in hooks will halt the execution chain and bubble up the stack appropriately.
+
+### Available Hook Insertion Points
+
+Current hook insertion points are:
+
+* `before_server_start` - Right before the gRPC server starts
+* `after_server_stop` - Right after the gRPC server is shutdown
+
+Note that exceptions raised in `before_server_start` will halt the execution chain for the remaining 
+`before_server_start` hooks, but will still execute the `after_server_stop` hooks as expected. Exceptions raised
+in `after_server_stop` will prevent further `after_server_stop` hooks from running.
+
 ## Instrumentation
 
 gruf comes out of the box with a couple of instrumentation interceptors packed in:

data/lib/gruf.rb

@@ -30,6 +30,9 @@ require_relative 'gruf/controllers/base'
 require_relative 'gruf/outbound/request_context'
 require_relative 'gruf/interceptors/registry'
 require_relative 'gruf/interceptors/base'
+require_relative 'gruf/hooks/registry'
+require_relative 'gruf/hooks/executor'
+require_relative 'gruf/hooks/base'
 require_relative 'gruf/timer'
 require_relative 'gruf/response'
 require_relative 'gruf/error'

data/lib/gruf/cli/executor.rb

@@ -26,22 +26,39 @@ module Gruf
       ##
       # @param [Hash|ARGV]
       #
-      def initialize(args = ARGV)
+      def initialize(
+        args = ARGV,
+        server: nil,
+        services: nil,
+        hook_executor: nil,
+        logger: nil
+      )
         @args = args
-        setup!
+        setup! # ensure we set some defaults from CLI here so we can allow configuration
+        @services = services || Gruf.services
+        @hook_executor = hook_executor || Gruf::Hooks::Executor.new(hooks: Gruf.hooks&.prepare)
+        @server = server || Gruf::Server.new(Gruf.server_options)
+        @logger = logger || Gruf.logger || ::Logger.new(STDERR)
       end
 
       ##
       # Run the server
       #
       def run
-        server = Gruf::Server.new(Gruf.server_options)
-        Gruf.services.each { |s| server.add_service(s) }
-        server.start!
-      rescue StandardError => e
-        msg = "FATAL ERROR: #{e.message} #{e.backtrace.join("\n")}"
-        logger = Gruf.logger || ::Logger.new(STDERR)
-        logger.fatal msg
+        exception = nil
+        begin
+          @services.each { |s| @server.add_service(s) }
+          @hook_executor.call(:before_server_start, server: @server)
+          @server.start!
+        rescue StandardError => e
+          exception = e
+          # Catch the exception here so that we always ensure the post hook runs
+          # This allows systems wanting to provide external server instrumentation
+          # the ability to properly handle server failures
+          @logger.fatal("FATAL ERROR: #{e.message} #{e.backtrace.join("\n")}")
+        end
+        @hook_executor.call(:after_server_stop, server: @server)
+        raise exception if exception
       end
 
       private

data/lib/gruf/configuration.rb

@@ -25,6 +25,7 @@ module Gruf
       server_binding_url: '0.0.0.0:9001',
       server_options: {},
       interceptors: nil,
+      hooks: nil,
       default_client_host: '',
       use_ssl: false,
       ssl_crt_file: '',
@@ -99,6 +100,7 @@ module Gruf
         send((k.to_s + '='), v)
       end
       self.interceptors = Gruf::Interceptors::Registry.new
+      self.hooks = Gruf::Hooks::Registry.new
       self.root_path = Rails.root.to_s.chomp('/') if defined?(Rails)
       if defined?(Rails) && Rails.logger
         self.logger = Rails.logger

data/lib/gruf/hooks/base.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2017-present, BigCommerce Pty. Ltd. All rights reserved
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+# documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+# persons to whom the Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+# Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+# OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+module Gruf
+  module Hooks
+    ##
+    # Base class for a hook that allows execution at various points of Gruf server processes
+    #
+    class Base
+      include Gruf::Loggable
+
+      ##
+      # @param [Hash] options
+      #
+      def initialize(options: nil)
+        @options = options || {}
+      end
+    end
+  end
+end

data/lib/gruf/hooks/executor.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2017-present, BigCommerce Pty. Ltd. All rights reserved
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+# documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+# persons to whom the Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+# Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+# OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+module Gruf
+  module Hooks
+    ##
+    # Base class for a hook that allows execution at various points of gRPC server processes
+    #
+    class Executor
+      include Gruf::Loggable
+
+      def initialize(hooks: nil)
+        @hooks = hooks || Gruf.hooks&.prepare || []
+      end
+
+      ##
+      # Execute a hook point for each registered hook in the registry
+      #
+      # @param [Symbol] name
+      # @param [Hash] arguments
+      #
+      def call(name, arguments = {})
+        name = name.to_sym
+
+        @hooks.each do |hook|
+          next unless hook.respond_to?(name)
+
+          hook.send(name, arguments)
+        end
+      end
+    end
+  end
+end

data/lib/gruf/hooks/registry.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2017-present, BigCommerce Pty. Ltd. All rights reserved
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+# documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+# persons to whom the Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+# Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+# OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+module Gruf
+  module Hooks
+    ##
+    # Handles registration of hooks
+    #
+    class Registry
+      class HookNotFoundError < StandardError; end
+
+      def initialize
+        @registry = []
+      end
+
+      ##
+      # Add a hook to the registry
+      #
+      # @param [Class] hook_class The class of the hook to add
+      # @param [Hash] options A hash of options to pass into the hook during initialization
+      #
+      def use(hook_class, options = {})
+        hooks_mutex do
+          @registry << {
+            klass: hook_class,
+            options: options
+          }
+        end
+      end
+
+      ##
+      # Remove a hook from the registry
+      #
+      # @param [Class] hook_class The hook class to remove
+      # @raise [HookNotFoundError] if the hook is not found
+      #
+      def remove(hook_class)
+        pos = @registry.find_index { |opts| opts.fetch(:klass, '') == hook_class }
+        raise HookNotFoundError if pos.nil?
+
+        @registry.delete_at(pos)
+      end
+
+      ##
+      # Insert a hook before another specified hook
+      #
+      # @param [Class] before_class The hook to insert before
+      # @param [Class] hook_class The class of the hook to add
+      # @param [Hash] options A hash of options to pass into the hook during initialization
+      # @raise [HookNotFoundError] if the before hook is not found
+      #
+      def insert_before(before_class, hook_class, options = {})
+        hooks_mutex do
+          pos = @registry.find_index { |opts| opts.fetch(:klass, '') == before_class }
+          raise HookNotFoundError if pos.nil?
+
+          @registry.insert(
+            pos,
+            klass: hook_class,
+            options: options
+          )
+        end
+      end
+
+      ##
+      # Insert a hook after another specified hook
+      #
+      # @param [Class] after_class The hook to insert after
+      # @param [Class] hook_class The class of the hook to add
+      # @param [Hash] options A hash of options to pass into the hook during initialization
+      # @raise [HookNotFoundError] if the after hook is not found
+      #
+      def insert_after(after_class, hook_class, options = {})
+        hooks_mutex do
+          pos = @registry.find_index { |opts| opts.fetch(:klass, '') == after_class }
+          raise HookNotFoundError if pos.nil?
+
+          @registry.insert(
+            (pos + 1),
+            klass: hook_class,
+            options: options
+          )
+        end
+      end
+
+      ##
+      # Return a list of the hook classes in the registry in their execution order
+      #
+      # @return [Array<Class>]
+      #
+      def list
+        hooks_mutex do
+          @registry.map { |h| h[:klass] }
+        end
+      end
+
+      ##
+      # Lazily load and return all hooks for the given request
+      #
+      # @return [Array<Gruf::Hooks::Base>]
+      #
+      def prepare
+        is = []
+        hooks_mutex do
+          @registry.each do |o|
+            is << o[:klass].new(options: o[:options])
+          end
+        end
+        is
+      end
+
+      ##
+      # Clear the registry
+      #
+      def clear
+        hooks_mutex do
+          @registry = []
+        end
+      end
+
+      ##
+      # @return [Integer] The number of hooks currently loaded
+      #
+      def count
+        hooks_mutex do
+          @registry ||= []
+          @registry.count
+        end
+      end
+
+      private
+
+      ##
+      # Handle mutations to the hook registry in a thread-safe manner
+      #
+      def hooks_mutex(&block)
+        @hooks_mutex ||= begin
+          require 'monitor'
+          Monitor.new
+        end
+        @hooks_mutex.synchronize(&block)
+      end
+    end
+  end
+end

data/lib/gruf/version.rb

@@ -16,5 +16,5 @@
 # OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Gruf
-  VERSION = '2.6.1'
+  VERSION = '2.7.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gruf
 version: !ruby/object:Gem::Version
-  version: 2.6.1
+  version: 2.7.0
 platform: ruby
 authors:
 - Shaun McCormick
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-05-01 00:00:00.000000000 Z
+date: 2019-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -148,6 +148,9 @@ files:
 - lib/gruf/errors/debug_info.rb
 - lib/gruf/errors/field.rb
 - lib/gruf/errors/helpers.rb
+- lib/gruf/hooks/base.rb
+- lib/gruf/hooks/executor.rb
+- lib/gruf/hooks/registry.rb
 - lib/gruf/instrumentable_grpc_server.rb
 - lib/gruf/integrations/rails/railtie.rb
 - lib/gruf/interceptors/active_record/connection_reset.rb
@@ -193,8 +196,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.7
+rubygems_version: 3.0.2
 signing_key: 
 specification_version: 4
 summary: gRPC Ruby Framework