gruf 2.2.2 → 2.9.1

data/lib/gruf/controllers/request.rb

@@ -1,3 +1,5 @@
+# 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
@@ -33,11 +35,16 @@ module Gruf
       delegate :metadata, to: :active_call
       delegate :messages, :client_streamer?, :server_streamer?, :bidi_streamer?, :request_response?, to: :type
 
+      ##
+      # Abstract representation of a gRPC request type
+      #
       class Type
         delegate :client_streamer?, :server_streamer?, :bidi_streamer?, :request_response?, to: :@rpc_desc
 
         ##
-        # @param [GRPC::RpcDesc] rpc_desc
+        # Initialize a new request type object
+        #
+        # @param [GRPC::RpcDesc] rpc_desc The RPC descriptor for the request type
         #
         def initialize(rpc_desc)
           @rpc_desc = rpc_desc
@@ -45,11 +52,13 @@ module Gruf
       end
 
       ##
+      # Initialize an inbound controller request object
+      #
       # @param [Symbol] method_key The method symbol of the RPC method being executed
       # @param [Class] service The class of the service being executed against
       # @param [GRPC::RpcDesc] rpc_desc The RPC descriptor of the call
       # @param [GRPC::ActiveCall] active_call The restricted view of the call
-      # @param [Object] message The protobuf message (or messages) of the request
+      # @param [Object|Google::Protobuf::MessageExts] message The protobuf message (or messages) of the request
       #
       def initialize(method_key:, service:, rpc_desc:, active_call:, message:)
         @method_key = method_key
@@ -64,21 +73,21 @@ module Gruf
       # Returns the service name as a translated name separated by periods. Strips
       # the superfluous "Service" suffix from the name
       #
-      # @return [String]
+      # @return [String] The mapped service key
       #
       def service_key
         @service.name.underscore.tr('/', '.').gsub('.service', '')
       end
 
       ##
-      # @return [Class]
+      # @return [Class] The class of the response message
       #
       def response_class
         @rpc_desc.output
       end
 
       ##
-      # @return [Class]
+      # @return [Class] The class of the request message
       #
       def request_class
         @rpc_desc.input
@@ -90,21 +99,23 @@ module Gruf
       # @return [String] The parsed service method name
       #
       def method_name
-        "#{service_key}.#{method_key}"
+        "#{service_key}.#{@method_key}"
       end
 
       ##
       # Return all messages for this request, properly handling different request types
       #
-      # @return Enumerable<Object>
+      # @return [Enumerable<Object>] All messages for this request
       #
       def messages
         if client_streamer?
-          message.call { |msg| yield msg }
+          # rubocop:disable Style/ExplicitBlockArgument
+          @message.call { |msg| yield msg }
+          # rubocop:enable Style/ExplicitBlockArgument
         elsif bidi_streamer?
-          message
+          @message
         else
-          [message]
+          [@message]
         end
       end
     end

data/lib/gruf/controllers/service_binder.rb

@@ -1,3 +1,5 @@
+# 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
@@ -25,14 +27,18 @@ module Gruf
       class BoundDesc < SimpleDelegator; end
 
       ##
-      # @param [GRPC::GenericService] service
+      # Initialize a service binder instance with the given service
+      #
+      # @param [GRPC::GenericService] service The gRPC service stub to bind
       #
       def initialize(service)
         @service = service
       end
 
       ##
-      # @param [Gruf::Controllers::Base]
+      # Bind all methods on the service to the passed controller
+      #
+      # @param [Class<Gruf::Controllers::Base>] controller
       #
       def bind!(controller)
         rpc_methods.each { |name, desc| bind_method(controller, name, desc) }
@@ -41,6 +47,8 @@ module Gruf
       private
 
       ##
+      # Bind the grpc methods to the service, allowing for server interception and execution control
+      #
       # @param [Gruf::Controllers::Base] controller
       # @param [Symbol] method_name
       # @param [BoundDesc] desc
@@ -52,22 +60,46 @@ module Gruf
         @service.class_eval do
           if desc.request_response?
             define_method(method_key) do |message, active_call|
-              c = controller.new(method_key: method_key, service: service_ref, message: message, active_call: active_call, rpc_desc: desc)
+              c = controller.new(
+                method_key: method_key,
+                service: service_ref,
+                message: message,
+                active_call: active_call,
+                rpc_desc: desc
+              )
               c.call(method_key)
             end
           elsif desc.client_streamer?
             define_method(method_key) do |active_call|
-              c = controller.new(method_key: method_key, service: service_ref, message: proc { |&block| active_call.each_remote_read(&block) }, active_call: active_call, rpc_desc: desc)
+              c = controller.new(
+                method_key: method_key,
+                service: service_ref,
+                message: proc { |&block| active_call.each_remote_read(&block) },
+                active_call: active_call,
+                rpc_desc: desc
+              )
               c.call(method_key)
             end
           elsif desc.server_streamer?
             define_method(method_key) do |message, active_call, &block|
-              c = controller.new(method_key: method_key, service: service_ref, message: message, active_call: active_call, rpc_desc: desc)
+              c = controller.new(
+                method_key: method_key,
+                service: service_ref,
+                message: message,
+                active_call: active_call,
+                rpc_desc: desc
+              )
               c.call(method_key, &block)
             end
           else # bidi
             define_method(method_key) do |messages, active_call, &block|
-              c = controller.new(method_key: method_key, service: service_ref, message: messages, active_call: active_call, rpc_desc: desc)
+              c = controller.new(
+                method_key: method_key,
+                service: service_ref,
+                message: messages,
+                active_call: active_call,
+                rpc_desc: desc
+              )
               c.call(method_key, &block)
             end
           end

data/lib/gruf/error.rb

@@ -1,3 +1,5 @@
+# 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
@@ -50,6 +52,13 @@ module Gruf
       data_loss: GRPC::DataLoss
     }.freeze
 
+    # Default limit on trailing metadata is 8KB. We need to be careful
+    # not to overflow this limit, or the response message will never
+    # be sent. Instead, resource_exhausted will be thrown.
+    MAX_METADATA_SIZE = 7.5 * 1_024
+    METADATA_SIZE_EXCEEDED_CODE = 'metadata_size_exceeded'
+    METADATA_SIZE_EXCEEDED_MSG = 'Metadata too long, risks exceeding http2 trailing metadata limit.'
+
     # @return [Symbol] The given internal gRPC code for the error
     attr_accessor :code
     # @return [Symbol] An arbitrary application code that can be used for logical processing of the error by the client
@@ -58,8 +67,8 @@ module Gruf
     attr_accessor :message
     # @return [Array] An array of field errors that can be returned by the server
     attr_accessor :field_errors
-    # @return [Object] A hash of debugging information, such as a stack trace and exception name, that can be used to
-    # debug an given error response. This is sent by the server over the trailing metadata.
+    # @return [Errors::DebugInfo] A object containing debugging information, such as a stack trace and exception name,
+    # that can be used to debug an given error response. This is sent by the server over the trailing metadata.
     attr_accessor :debug_info
     # @return [GRPC::BadStatus] The gRPC BadStatus error object that was generated
     attr_writer :grpc_error
@@ -72,10 +81,11 @@ module Gruf
     # @param [Hash] args (Optional) An optional hash of arguments that will set fields on the error object
     #
     def initialize(args = {})
+      @field_errors = []
+      @metadata = {}
       args.each do |k, v|
         send("#{k}=", v) if respond_to?(k)
       end
-      @field_errors = []
     end
 
     ##
@@ -116,7 +126,7 @@ module Gruf
     # @return [Hash] The newly set metadata
     #
     def metadata=(metadata)
-      @metadata = metadata.map { |k, str| [k, str.to_s] }.to_h
+      @metadata = metadata.transform_values(&:to_s)
     end
 
     ##
@@ -130,16 +140,30 @@ module Gruf
     end
 
     ##
-    # Append any appropriate errors to the gRPC call and properly update the output metadata
+    # Update the trailing metadata on the given gRPC call, including the error payload if configured
+    # to do so.
     #
     # @param [GRPC::ActiveCall] active_call The marshalled gRPC call
-    # @return [Error] Return the error itself with the GRPC::ActiveCall attached and error metadata appended
+    # @return [Error] Return the error itself after updating metadata on the given gRPC call.
+    #                 In the case of a metadata overflow error, we replace the current error with
+    #                 a new one that won't cause a low-level http2 error.
     #
     def attach_to_call(active_call)
       metadata[Gruf.error_metadata_key.to_sym] = serialize if Gruf.append_server_errors_to_trailing_metadata
-      if !metadata.empty? && active_call && active_call.respond_to?(:output_metadata)
-        active_call.output_metadata.update(metadata)
+      return self if metadata.empty? || !active_call || !active_call.respond_to?(:output_metadata)
+
+      # Check if we've overflown the maximum size of output metadata. If so,
+      # log a warning and replace the metadata with something smaller to avoid
+      # resource exhausted errors.
+      if metadata.inspect.size > MAX_METADATA_SIZE
+        code = METADATA_SIZE_EXCEEDED_CODE
+        msg = METADATA_SIZE_EXCEEDED_MSG
+        logger.warn "#{code}: #{msg} Original error: #{to_h.inspect}"
+        err = Gruf::Error.new(code: :internal, app_code: code, message: msg)
+        return err.attach_to_call(active_call)
       end
+
+      active_call.output_metadata.update(metadata)
       self
     end
 
@@ -175,7 +199,8 @@ module Gruf
     # @return [GRPC::BadStatus]
     #
     def grpc_error
-      @grpc_error = grpc_class.new(message, **@metadata)
+      md = @metadata || {}
+      @grpc_error = grpc_class.new(message, **md)
     end
 
     private

data/lib/gruf/errors/debug_info.rb

@@ -1,3 +1,5 @@
+# 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
@@ -30,13 +32,18 @@ module Gruf
       #
       def initialize(detail, stack_trace = [])
         @detail = detail
-        @stack_trace = stack_trace.is_a?(String) ? stack_trace.split("\n") : stack_trace
+        @stack_trace = (stack_trace.is_a?(String) ? stack_trace.split("\n") : stack_trace)
+
+        # Limit the size of the stack trace to reduce risk of overflowing metadata
+        stack_trace_limit = Gruf.backtrace_limit.to_i
+        stack_trace_limit = 10 if stack_trace_limit.negative?
+        @stack_trace = @stack_trace[0..stack_trace_limit] if stack_trace_limit.positive?
       end
 
       ##
       # Return this object marshalled into a hash
       #
-      # @return [Hash] The debug info represented as a has
+      # @return [Hash] The debug info represented as a hash
       #
       def to_h
         {

data/lib/gruf/errors/field.rb

@@ -1,3 +1,5 @@
+# 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

data/lib/gruf/errors/helpers.rb

@@ -1,3 +1,5 @@
+# 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
@@ -15,6 +17,9 @@
 #
 module Gruf
   module Errors
+    ##
+    # Helper module for standardizing error interaction
+    #
     module Helpers
       delegate :add_field_error, :set_debug_info, :has_field_errors?, to: :error
 

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/instrumentable_grpc_server.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Gruf
+  ##
+  # A subclass of GRPC::RpcServer that can be used for enhanced monitoring
+  # of thread pool. Note that since we are reaching into the internals of
+  # GRPC::RpcServer, we need to watch the evolution of that class.
+  #
+  class InstrumentableGrpcServer < GRPC::RpcServer
+    ##
+    # Add an event_listener_proc that, if supplied, will be called
+    # when interesting events happen in the server.
+    #
+    def initialize(pool_size: DEFAULT_POOL_SIZE,
+                   max_waiting_requests: DEFAULT_MAX_WAITING_REQUESTS,
+                   poll_period: DEFAULT_POLL_PERIOD,
+                   pool_keep_alive: Pool::DEFAULT_KEEP_ALIVE,
+                   connect_md_proc: nil,
+                   server_args: {},
+                   interceptors: [],
+                   event_listener_proc: nil)
+      # Call the base class initializer
+      super(
+        pool_size: pool_size,
+        max_waiting_requests: max_waiting_requests,
+        poll_period: poll_period,
+        pool_keep_alive: pool_keep_alive,
+        connect_md_proc: connect_md_proc,
+        server_args: server_args,
+        interceptors: interceptors
+      )
+
+      # Save event listener for later
+      @event_listener_proc = event_listener_proc
+    end
+
+    ##
+    # Notify the event listener of something interesting
+    #
+    def notify(event)
+      return if @event_listener_proc.nil? || !@event_listener_proc.respond_to?(:call)
+
+      @event_listener_proc.call(event)
+    end
+
+    ##
+    # Hook into the thread pool availability check for monitoring
+    #
+    def available?(an_rpc)
+      super.tap do |obj|
+        notify(:thread_pool_exhausted) unless obj
+      end
+    end
+
+    ##
+    # Hook into the method implementation check for monitoring
+    #
+    def implemented?(an_rpc)
+      super.tap do |obj|
+        notify(:unimplemented) unless obj
+      end
+    end
+  end
+end

data/lib/gruf/integrations/rails/railtie.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Gruf
+  module Integrations
+    module Rails
+      class Railtie < ::Rails::Railtie
+      end
+    end
+  end
+end

data/lib/gruf/interceptors/active_record/connection_reset.rb

@@ -1,3 +1,5 @@
+# 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
@@ -25,9 +27,8 @@ module Gruf
         # connection pool, we need to ensure that this is done to properly
         #
         def call
-          if enabled? && !::ActiveRecord::Base.connection.active?
-            ::ActiveRecord::Base.establish_connection
-          end
+          ::ActiveRecord::Base.establish_connection if enabled? && !::ActiveRecord::Base.connection.active?
+
           yield
         ensure
           ::ActiveRecord::Base.clear_active_connections! if enabled?