gruf 2.15.1 → 2.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5186fbfc554b119075aff88683ee7f1661a884d96d9766e59664d10805bd4ab2
-  data.tar.gz: 68b995a644b15dc703595df4e35a25539e0edf77d5f5218bffa28253b60eedbf
+  metadata.gz: 3d83766bdf6739e3997891fd7b5e5ecd393aa17c8fab0ab839ff0789756726cf
+  data.tar.gz: b959a1644c29c5732438a60a079dc318136146eddb96d4060091f0f39fc7e5c6
 SHA512:
-  metadata.gz: 8328cccfcc712c21cb5a477939762524d774d3d45a0882217fe3b7d701cfda90e9dcd27af7ab4c4cbc73ca46d420d85e55be3712efc950590212658030217c40
-  data.tar.gz: 2cf04dce0c4e378edf56ab6b204293ce2b4dc660d2ac103ac55d99e893891ac3a76feb2e05dee4ac3371b47083fd8523441e7e2c87881bacd2511b016a1965b3
+  metadata.gz: ef7b011e2d693c2cb05b10697e0b67fcedb1d72ffc8adeac5f207557a30494860878a5b80e94fc8d512e7a4e5e6cb69b2bc8a854e72cd80f2e1507e0c1f379b6
+  data.tar.gz: a75845718660f4013015eff266c737315ce7bb00e147c83bc175390c87d890be525ee88059f5bb3ec224bbe30a96fb348143dfccd0c377a2dee8bd3eb674a6ea

data/CHANGELOG.md

@@ -2,6 +2,15 @@ Changelog for the gruf gem. This includes internal history before the gem was ma
 
 ### Pending release
 
+- Add opt-in ability to serve the official [gRPC health check](https://github.com/grpc/grpc/blob/master/src/ruby/pb/grpc/health/v1/health_services_pb.rb)
+  automatically via `health_check_enabled` configuration option (or `GRUF_HEALTH_CHECK_ENABLED` environment
+  variable).
+- Add `health_check_hook` configuration option to implement a custom response for the above gRPC built-in health check
+- [#156] Allow passing a specific list of services to run via the gruf binstub
+- [#163] Add `context` hash attribute to `Gruf::Controllers::Request` to allow interceptors to pass information down
+  to a gruf controller
+- Drop Ruby 2.6 support (EOL'ed on March 31st, 2022)
+
 ### 2.15.1
 
 - Fix issue where GRPC_SERVER_POOL_KEEP_ALIVE and GRPC_SERVER_POLL_PERIOD when set via ENV are not cast to int

data/gruf.gemspec

@@ -32,7 +32,7 @@ Gem::Specification.new do |spec|
   spec.executables << 'gruf'
   spec.require_paths = ['lib']
 
-  spec.required_ruby_version = '>= 2.6', '< 3.2'
+  spec.required_ruby_version = '>= 2.7', '< 3.2'
 
   spec.metadata = {
     'bug_tracker_uri' => 'https://github.com/bigcommerce/gruf/issues',
@@ -44,12 +44,7 @@ Gem::Specification.new do |spec|
   }
 
   spec.add_development_dependency 'bundler-audit', '>= 0.6'
-  # rubocop:disable Gemspec/RubyVersionGlobalsUsage
-  spec.add_development_dependency(
-    'factory_bot',
-    (Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('2.5') ? '>= 6.1' : '~> 5.2')
-  )
-  # rubocop:enable Gemspec/RubyVersionGlobalsUsage
+  spec.add_development_dependency 'factory_bot', '>= 6.1'
   spec.add_development_dependency 'ffaker', '>= 2.15'
   spec.add_development_dependency 'pry', '~> 0.12'
   spec.add_development_dependency 'pry-byebug', '>= 3.9'

data/lib/gruf/cli/executor.rb

@@ -52,19 +52,11 @@ module Gruf
       #
       def run
         exception = nil
-        # wait to load controllers until last possible second to allow late configuration
-        ::Gruf.autoloaders.load!(controllers_path: Gruf.controllers_path)
-        # allow lazy registering globally as late as possible, this allows more flexible binstub injections
-        @services = ::Gruf.services unless @services&.any?
 
-        unless @services.any?
-          raise NoServicesBoundError,
-                'No services bound to this gruf process; please bind a service to a Gruf controller ' \
-                'to start the server successfully'
-        end
+        # allow lazy registering globally as late as possible, this allows more flexible binstub injections
+        register_services!
 
         begin
-          @services.each { |s| @server.add_service(s) }
           @hook_executor.call(:before_server_start, server: @server)
           @server.start!
         rescue StandardError => e
@@ -84,14 +76,15 @@ module Gruf
       # Setup options for CLI execution and configure Gruf based on inputs
       #
       def setup!
-        opts = parse_options
+        @options = parse_options
 
-        Gruf.server_binding_url = opts[:host] if opts[:host]
-        if opts.suppress_default_interceptors?
+        Gruf.server_binding_url = @options[:host] if @options[:host]
+        if @options.suppress_default_interceptors?
           Gruf.interceptors.remove(Gruf::Interceptors::ActiveRecord::ConnectionReset)
           Gruf.interceptors.remove(Gruf::Interceptors::Instrumentation::OutputMetadataTimer)
         end
-        Gruf.backtrace_on_error = true if opts.backtrace_on_error?
+        Gruf.backtrace_on_error = true if @options.backtrace_on_error?
+        Gruf.health_check_enabled = true if @options.health_check?
       end
 
       ##
@@ -106,6 +99,8 @@ module Gruf
             exit(0)
           end
           o.string '--host', 'Specify the binding url for the gRPC service'
+          o.string '--services', 'Optional. Run gruf with only the passed gRPC service classes (comma-separated)'
+          o.bool '--health-check', 'Serve the default gRPC health check (defaults to false). '
           o.bool '--suppress-default-interceptors', 'Do not use the default interceptors'
           o.bool '--backtrace-on-error', 'Push backtraces on exceptions to the error serializer'
           o.null '-v', '--version', 'print gruf version' do
@@ -114,6 +109,85 @@ module Gruf
           end
         end
       end
+
+      ##
+      # Register services; note that this happens after gruf is initialized, and right before the server is run.
+      # This will interpret the services to run in the following precedence:
+      # 1. initializer arguments to the executor
+      # 2. ARGV options (the --services option)
+      # 3. services set to the global gruf configuration (Gruf.services)
+      #
+      def register_services!
+        # wait to load controllers until last possible second to allow late configuration
+        ::Gruf.autoloaders.load!(controllers_path: Gruf.controllers_path)
+
+        services = determine_services(@services)
+        services = bind_health_check!(services) if health_check_enabled?
+
+        services.map! { |s| s.is_a?(Class) ? s : s.constantize }
+
+        if services.any?
+          services.each { |s| @server.add_service(s) }
+          return
+        end
+
+        raise NoServicesBoundError
+      rescue NoServicesBoundError
+        @logger.fatal 'FATAL ERROR: No services bound to this gruf process; please bind a service to a Gruf ' \
+                      'controller to start the server successfully'
+        exit(1)
+      rescue NameError => e
+        @logger.fatal 'FATAL ERROR: Could not start server; passed services to run are not loaded or valid ' \
+                      "constants: #{e.message}"
+        exit(1)
+      rescue StandardError => e
+        @logger.fatal "FATAL ERROR: Could not start server: #{e.message}"
+        exit(1)
+      end
+
+      ##
+      # @return [Boolean]
+      #
+      def health_check_enabled?
+        ::Gruf.health_check_enabled
+      end
+
+      ##
+      # Load the health check if enabled into the services array
+      #
+      # @param [Array<Class>] services
+      # @return [Array<Class>]
+      #
+      def bind_health_check!(services)
+        # do this here to trigger autoloading the controller in zeitwerk, since we don't explicitly load this
+        # controller. This binds the service and makes sure the method handlers are setup.
+        # rubocop:disable Lint/Void
+        Gruf::Controllers::HealthController
+        # rubocop:enable Lint/Void
+        # if we're already bound to the services array (say someone explicitly passes the health check in, skip)
+        return services if services.include?(::Grpc::Health::V1::Health::Service)
+
+        # otherwise, manually add the grpc service
+        services << ::Grpc::Health::V1::Health::Service
+        services
+      end
+
+      ##
+      # Determine how we load services (initializer -> ARGV -> Gruf.services)
+      #
+      # @return [Array<Class>]
+      #
+      def determine_services(services = [])
+        # first check initializer arguments
+        return services if services.any?
+
+        # next check CLI arguments
+        services = @options[:services].to_s.split(',').map(&:strip).uniq
+        # finally, if none, use global gruf autoloaded services
+        services = (::Gruf.services || []) unless services.any?
+
+        services
+      end
     end
   end
 end

data/lib/gruf/configuration.rb

@@ -77,6 +77,13 @@ module Gruf
     #   @return [Integer] Internal cache expiry period (in seconds) for the SynchronizedClient
     # @!attribute rpc_server_options
     #   @return [Hash] A hash of RPC options for GRPC server configuration
+    # @!attribute health_check_enabled
+    #   @return [Boolean] If true, will load and register `Gruf::Controllers::HealthController` with the default gRPC
+    #     health check to the loaded gRPC server
+    # @!attribute health_check_hook
+    #   @return [NilClass]
+    #   @return [Proc] If set, will call this in the gRPC health check. It is required to return a
+    #     `::Grpc::Health::V1::HealthCheckResponse` object in this proc to indicate the health of the server.
     VALID_CONFIG_KEYS = {
       root_path: '',
       server_binding_url: '0.0.0.0:9001',
@@ -101,6 +108,8 @@ module Gruf
       use_exception_message: true,
       internal_error_message: 'Internal Server Error',
       event_listener_proc: nil,
+      health_check_enabled: false,
+      health_check_hook: nil,
       synchronized_client_internal_cache_expiry: 60,
       rpc_server_options: {
         pool_size: GRPC::RpcServer::DEFAULT_POOL_SIZE,
@@ -181,6 +190,7 @@ module Gruf
         interceptors.use(::Gruf::Interceptors::ActiveRecord::ConnectionReset)
         interceptors.use(::Gruf::Interceptors::Instrumentation::OutputMetadataTimer)
       end
+      self.health_check_enabled = ::ENV.fetch('GRUF_HEALTH_CHECK_ENABLED', 0).to_i.positive?
       options
     end
 

data/lib/gruf/controllers/health_controller.rb

@@ -0,0 +1,37 @@
+# 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 Controllers
+    ##
+    # Dynamic standard grpc health check controller. Can be used as-is, or can use ::Gruf.health_check_hook to
+    # provide custom responses.
+    #
+    class HealthController < Gruf::Controllers::Base
+      bind ::Grpc::Health::V1::Health::Service
+
+      def check
+        health_proc = ::Gruf.health_check_hook
+        return health_proc.call(request, error) if !health_proc.nil? && health_proc.respond_to?(:call)
+
+        ::Grpc::Health::V1::HealthCheckResponse.new(
+          status: ::Grpc::Health::V1::HealthCheckResponse::ServingStatus::SERVING
+        )
+      end
+    end
+  end
+end

data/lib/gruf/controllers/request.rb

@@ -36,6 +36,11 @@ module Gruf
       # @!attribute [r] service
       #   @return [Class] The GRPC service class for this request
       attr_reader :service
+      # @!attribute [r] context
+      #   @return [::ActiveSupport::HashWithIndifferentAccess] An arbitrary hash of key/value entries that are
+      #     accessible for interceptors, that can be used to shared information between interceptors and pass down into
+      #     the controller.
+      attr_reader :context
 
       delegate :metadata, to: :active_call
       delegate :messages, :client_streamer?, :server_streamer?, :bidi_streamer?, :request_response?, to: :type
@@ -72,6 +77,7 @@ module Gruf
         @message = message
         @rpc_desc = rpc_desc
         @type = Type.new(rpc_desc)
+        @context = ::ActiveSupport::HashWithIndifferentAccess.new
       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.15.1'
+  VERSION = '2.16.0'
 end

data/lib/gruf.rb

@@ -17,8 +17,10 @@
 #
 require 'grpc'
 require 'active_support/core_ext/module/delegation'
+require 'active_support/hash_with_indifferent_access'
 require 'active_support/concern'
 require 'active_support/inflector'
+require 'grpc/health/v1/health_services_pb'
 require 'base64'
 
 # use Zeitwerk to lazily autoload all the files in the lib directory

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gruf
 version: !ruby/object:Gem::Version
-  version: 2.15.1
+  version: 2.16.0
 platform: ruby
 authors:
 - Shaun McCormick
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-07-08 00:00:00.000000000 Z
+date: 2022-08-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler-audit
@@ -341,6 +341,7 @@ files:
 - lib/gruf/configuration.rb
 - lib/gruf/controllers/autoloader.rb
 - lib/gruf/controllers/base.rb
+- lib/gruf/controllers/health_controller.rb
 - lib/gruf/controllers/request.rb
 - lib/gruf/controllers/service_binder.rb
 - lib/gruf/error.rb
@@ -395,7 +396,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.6'
+      version: '2.7'
   - - "<"
     - !ruby/object:Gem::Version
       version: '3.2'
@@ -405,7 +406,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.12
+rubygems_version: 3.3.3
 signing_key:
 specification_version: 4
 summary: gRPC Ruby Framework