gruf 2.4.0 → 2.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1af99f62622489376979d133e0c11fe33957a3937941193187508158bfb73398
-  data.tar.gz: 4b280b7a654de95dc0fc2d7ce8562baace9a9bd46861ccd59178682814a43e23
+  metadata.gz: b1289ff979cec29b1c475fc7fb9292d3eab752229e5147b59f18c107fb34531d
+  data.tar.gz: 55acd4dee980cd8274edbbc7308edc63e09b6a4b19e4a87a6d1d1e72b11dd46f
 SHA512:
-  metadata.gz: 75f137a4d62bbbc3169338517c12c9b2bb3bb8a60def87ee7f0ee096cad9f8752660ed7a4367f118d7dfa05c87901a1fd543ee728a9ac273816b2014feb0f6fa
-  data.tar.gz: 3337ab3f9da018e445e245beaaa2d4af7307d31d9182f758e4e6adcbb348c31fd7862bafce81e2eabca7ba02d7b7b678bf0abaa782ffedc8b77a6adb0339a59d
+  metadata.gz: 99959b15a10222393883ac16b80c8550ba35190aa9a9858764687e4349d04db9f696d37fe9ed7fd7bf4db0df8e1841791760eb49de7633392720fe9f8175d733
+  data.tar.gz: 22f6f6f2b9db9bea6768b1f3089c6502d02323e012efdad113becd430a94af4136d8d6f216d4e73079e66d59490ee379c6ba962d1c3f9f9649243fa0b382b57d

data/CHANGELOG.md

@@ -2,6 +2,14 @@ Changelog for the gruf gem. This includes internal history before the gem was ma
 
 ### Pending release
 
+### 2.4.1
+
+- Safer configuration of GRPC::RpcServer. From now on, use `Gruf.rpc_server_options` for the params
+  to be sent to GPRC::RpcServer. Also provide sane defaults for params for GRPC::RpcServer. [#55]
+- Added ability to monitor `RESOURCE_EXHAUSTED` and `UNIMPLEMENTED`. By setting `event_listener_proc` in
+  the Gruf configuration, you will receive a callback when these events occur. The parameter to your
+  callback will be a symbol (`:thread_pool_exhausted` or `:unimplemented`). Others may be added in the future.
+
 ### 2.4.0
 
 - Added a hash of error log levels to RequestLogging interceptor, mapping error code to level of logging to use. To 

data/README.md

@@ -17,8 +17,8 @@ up fast and efficiently at scale. Some of its features include:
   still preserving gRPC BadStatus codes
 * Server and client execution timings in responses
 
-gruf currently has active support for gRPC 1.10.x+. gruf is compatible and tested with Ruby 2.2-2.5. 
-gruf is also not [Rails](https://github.com/rails/rails)-specific, and can be used in any Ruby framework 
+gruf currently has active support for gRPC 1.10.x+. gruf is compatible and tested with Ruby 2.2-2.5.
+gruf is also not [Rails](https://github.com/rails/rails)-specific, and can be used in any Ruby framework
 (such as [Grape](https://github.com/ruby-grape/grape), for instance).
 
 ## Installation
@@ -86,13 +86,13 @@ class MyInterceptor < Gruf::Interceptors::ClientInterceptor
 end
 
 ::Gruf::Client.new(
-  service: ::Demo::ThingService, 
+  service: ::Demo::ThingService,
   client_options: [
     interceptors: [MyInterceptor.new]
   ])
 ```
 
-The `interceptors` option in `client_options` can accept either a `GRPC::ClientInterceptor` class or a 
+The `interceptors` option in `client_options` can accept either a `GRPC::ClientInterceptor` class or a
 `Gruf::Interceptors::ClientInterceptor`, since the latter just extends the former. The gruf client interceptors
 take an optional alternative approach: rather than having separate methods for each request type, it provides a default
 `call` method that passes in a `RequestContext` object, which has the following attributes:
@@ -178,8 +178,8 @@ Gruf comes baked in with a few command-line options for the binstub:
 | --suppress-default-interceptors | Do not use the default interceptors for the server |
 | --backtrace-on-error | Push backtraces on exceptions to the error serializer |
 
-These options will override whatever is passed in the Gruf configure block or 
-initializer. 
+These options will override whatever is passed in the Gruf configure block or
+initializer.
 
 ### Basic Authentication
 
@@ -255,6 +255,18 @@ Gruf.configure do |c|
 end
 ```
 
+### GRPC::RpcServer configuration
+To customize parameters for the underlying GRPC::RpcServer, such as the size of the gRPC thread pool,
+you can pass them in via Gruf.rpc\_server\_options.
+
+```ruby
+Gruf.configure do |c|
+  # The size of the underlying thread pool. No more concurrent requests can be made
+  # than the size of the thread pool.
+  c.rpc_server_options[:pool_size] = 100
+end
+```
+
 ## Server Interceptors
 
 gruf supports interceptors around the grpc server calls, allowing you to perform actions around your service
@@ -395,6 +407,77 @@ It's important to maintain a safe blacklist should you decide to log parameters;
 parameter sanitization on its own. We also recommend blacklisting parameters that may contain
 very large values (such as binary or json data).
 
+## Testing with RSpec
+
+### Controllers
+
+In order to test your controller, you first need to mock a GRPC ActiveCall. You can create the following file under `/spec/support/` path of your project:
+```
+require 'grpc'
+
+module Rpc
+  module Test
+    class Call
+      attr_reader :metadata
+
+      def initialize(md = nil)
+        @metadata = md || { 'authorization' => "Basic #{Base64.encode64('grpc:magic')}" }
+      end
+
+      def output_metadata
+        @output_metadata ||= {}
+      end
+    end
+  end
+end
+```
+
+Imagine you have the following controller to test:
+```
+class ThingController < ::Gruf::Controllers::Base
+  bind ::Rpc::ThingService::Service
+
+  def get_thing
+    thing = Rpc::Thing.new(id: message_id, name: 'Foo')
+    Rpc::GetThingResponse.new(thing: thing)
+  end
+
+  private
+
+  def message_id
+    request.message.id
+  end
+end
+```
+
+You can stub it in the specs this way:
+```
+describe ThingController do
+  let(:rpc_service) { ::Rpc::ThingService::Service }
+  let(:rpc_desc) { Rpc::ThingService::Service.rpc_descs.values.first }
+  let(:message) { Rpc::GetThingRequest.new(id: 1) }
+  let(:controller) do
+    described_class.new(
+      method_key: :get_thing,
+      service: rpc_service,
+      active_call: Rpc::Test::Call.new,
+      message: message,
+      rpc_desc: rpc_desc
+    )
+  end
+
+  describe '.call' do
+    context 'with :get_thing as an argument' do
+      let(:result) { controller.call(:get_thing) }
+
+      it 'returns an instance of Rpc::GetThingResponse' do
+        expect(result).to be_instance_of(Rpc::GetThingResponse)
+      end
+    end
+  end
+end
+```
+
 ## Plugins
 
 You can build your own hooks and middleware for gruf; here's a list of known open source gems for

data/gruf.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
   spec.licenses      = ['MIT']
 
   spec.summary       = 'gRPC Ruby Framework'
-  spec.description   = spec.summary
+  spec.description   = 'gRPC Ruby Framework for building complex gRPC applications at scale'
   spec.homepage      = 'https://github.com/bigcommerce/gruf'
 
   spec.files         = Dir['README.md', 'CHANGELOG.md', 'CODE_OF_CONDUCT.md', 'lib/**/*', 'gruf.gemspec']

data/lib/gruf.rb

@@ -32,6 +32,7 @@ require_relative 'gruf/timer'
 require_relative 'gruf/response'
 require_relative 'gruf/error'
 require_relative 'gruf/client'
+require_relative 'gruf/instrumentable_grpc_server'
 require_relative 'gruf/server'
 
 ##

data/lib/gruf/configuration.rb

@@ -37,7 +37,16 @@ module Gruf
       use_default_interceptors: true,
       backtrace_on_error: false,
       use_exception_message: true,
-      internal_error_message: 'Internal Server Error'
+      internal_error_message: 'Internal Server Error',
+      event_listener_proc: nil,
+      rpc_server_options: {
+        pool_size: GRPC::RpcServer::DEFAULT_POOL_SIZE,
+        max_waiting_requests: GRPC::RpcServer::DEFAULT_MAX_WAITING_REQUESTS,
+        poll_period: GRPC::RpcServer::DEFAULT_POLL_PERIOD,
+        pool_keep_alive: GRPC::Pool::DEFAULT_KEEP_ALIVE,
+        connect_md_proc: nil,
+        server_args: {}
+      }.freeze
     }.freeze
 
     attr_accessor *VALID_CONFIG_KEYS.keys

data/lib/gruf/error.rb

@@ -175,7 +175,8 @@ module Gruf
     # @return [GRPC::BadStatus]
     #
     def grpc_error
-      @grpc_error = grpc_class.new(message, **@metadata)
+      md = @metadata ? @metadata : {}
+      @grpc_error = grpc_class.new(message, **md)
     end
 
     private

data/lib/gruf/instrumentable_grpc_server.rb

@@ -0,0 +1,61 @@
+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 unless @event_listener_proc && @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/server.rb

@@ -31,11 +31,11 @@ module Gruf
     ##
     # Initialize the server and load and setup the services
     #
-    # @param [Hash] options
+    # @param [Hash] opts
     #
-    def initialize(options = {})
-      @options = options || {}
-      @interceptors = options.fetch(:interceptor_registry, Gruf.interceptors)
+    def initialize(opts = {})
+      @options = opts || {}
+      @interceptors = opts.fetch(:interceptor_registry, Gruf.interceptors)
       @interceptors = Gruf::Interceptors::Registry.new unless @interceptors.is_a?(Gruf::Interceptors::Registry)
       @services = []
       @started = false
@@ -43,7 +43,8 @@ module Gruf
       @stop_server_cv = ConditionVariable.new
       @stop_server_mu = Monitor.new
       @server_mu = Monitor.new
-      @hostname = options.fetch(:hostname, Gruf.server_binding_url)
+      @hostname = opts.fetch(:hostname, Gruf.server_binding_url)
+      @event_listener_proc = opts.fetch(:event_listener_proc, Gruf.event_listener_proc)
       setup
     end
 
@@ -53,7 +54,24 @@ module Gruf
     def server
       @server_mu.synchronize do
         @server ||= begin
-          server = GRPC::RpcServer.new(options)
+          # For backward compatibility, we allow these options to be passed directly
+          # in the Gruf::Server options, or via Gruf.rpc_server_options.
+          server_options = {
+            pool_size: options.fetch(:pool_size, Gruf.rpc_server_options[:pool_size]),
+            max_waiting_requests: options.fetch(:max_waiting_requests, Gruf.rpc_server_options[:max_waiting_requests]),
+            poll_period: options.fetch(:poll_period, Gruf.rpc_server_options[:poll_period]),
+            pool_keep_alive: options.fetch(:pool_keep_alive, Gruf.rpc_server_options[:pool_keep_alive]),
+            connect_md_proc: options.fetch(:connect_md_proc, Gruf.rpc_server_options[:connect_md_proc]),
+            server_args: options.fetch(:server_args, Gruf.rpc_server_options[:server_args])
+          }
+
+          server = if @event_listener_proc
+                     server_options[:event_listener_proc] = @event_listener_proc
+                     Gruf::InstrumentableGrpcServer.new(server_options)
+                   else
+                     GRPC::RpcServer.new(server_options)
+                   end
+
           @port = server.add_http2_port(@hostname, ssl_credentials)
           @services.each { |s| server.handle(s) }
           server
@@ -122,11 +140,11 @@ module Gruf
     #
     # @param [Class] before_class The interceptor that you want to add the new interceptor before
     # @param [Class] interceptor_class The Interceptor to add to the registry
-    # @param [Hash] options A hash of options for the interceptor
+    # @param [Hash] opts A hash of options for the interceptor
     #
-    def insert_interceptor_before(before_class, interceptor_class, options = {})
+    def insert_interceptor_before(before_class, interceptor_class, opts = {})
       raise ServerAlreadyStartedError if @started
-      @interceptors.insert_before(before_class, interceptor_class, options)
+      @interceptors.insert_before(before_class, interceptor_class, opts)
     end
 
     ##
@@ -134,11 +152,11 @@ module Gruf
     #
     # @param [Class] after_class The interceptor that you want to add the new interceptor after
     # @param [Class] interceptor_class The Interceptor to add to the registry
-    # @param [Hash] options A hash of options for the interceptor
+    # @param [Hash] opts A hash of options for the interceptor
     #
-    def insert_interceptor_after(after_class, interceptor_class, options = {})
+    def insert_interceptor_after(after_class, interceptor_class, opts = {})
       raise ServerAlreadyStartedError if @started
-      @interceptors.insert_after(after_class, interceptor_class, options)
+      @interceptors.insert_after(after_class, interceptor_class, opts)
     end
 
     ##

data/lib/gruf/version.rb

@@ -14,5 +14,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.4.0'.freeze
+  VERSION = '2.4.1'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gruf
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 2.4.1
 platform: ruby
 authors:
 - Shaun McCormick
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-06-12 00:00:00.000000000 Z
+date: 2018-08-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -108,7 +108,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.6'
-description: gRPC Ruby Framework
+description: gRPC Ruby Framework for building complex gRPC applications at scale
 email:
 - splittingred@gmail.com
 executables:
@@ -132,6 +132,7 @@ files:
 - lib/gruf/errors/debug_info.rb
 - lib/gruf/errors/field.rb
 - lib/gruf/errors/helpers.rb
+- lib/gruf/instrumentable_grpc_server.rb
 - lib/gruf/interceptors/active_record/connection_reset.rb
 - lib/gruf/interceptors/authentication/basic.rb
 - lib/gruf/interceptors/base.rb