gruf 1.2.7 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8494cc65922d13e3d9d70f0eeed43cb54cec22b0
-  data.tar.gz: e0afec068276451c09ad350d23ca165becb552b0
+  metadata.gz: d589a46b3a36a065a4844e937c177cdf662a19db
+  data.tar.gz: 412c889f35ded87f6a14990f79d25d2a6f5c9323
 SHA512:
-  metadata.gz: 6a783314fd5761fed60ee87426cb1d1aa78d515fc447232b88470a4b73e69b3f5102119f13cb6cea53086a45ef257d461aa467cc38a2dc09f3270b04e9638479
-  data.tar.gz: 2adc8447c02b004a67c06eb9d73b439afd00d1db1750046f4edbeb933686a737da82813fa71b16d4f087279056fb33c1dae821b5f98c9b19fd315a445be16dd8
+  metadata.gz: e80f4936341779ddda0c09c844a97f578c4c738be8c6db55156a4e35af931f4eae87d050906673d3fa141f05d2e0a869f12e2fbe156fc57ad996be31fc896c47
+  data.tar.gz: 78e4ac11542cc8cbc647f68657f1571ee27aa7a7c125e80fb6d8b4d148226e47c9030d3dd2780b4735700bb5bb0744333909d72f75a26a8d7961049bdaa8df8e

data/CHANGELOG.md

@@ -2,6 +2,17 @@ Changelog for the gruf gem. This includes internal history before the gem was ma
 
 ### Pending release
 
+### 2.0.0
+
+Gruf 2.0 is a major shift from Gruf 1.0. See [UPGRADING.md](UPGRADING.md) for details.
+
+- New thread-safe controller-based model
+- New controller request object
+- Hooks deprecated in favor of interceptors
+- New interceptor timer utility class
+- Default logging to logstash formatter
+- Various Gruf::Server improvements
+
 ### 1.2.7
 
 - Fix issues where field errors were persisted in between separate calls

data/README.md

@@ -8,17 +8,18 @@ provide a more streamlined integration into Ruby and Ruby on Rails applications.
 It provides an abstracted server and client for gRPC services, along with other tools to help get gRPC services in Ruby
 up fast and efficiently at scale. Some of its features include:
 
-* Abstracted server endpoints with before, around, outer around, and after hooks during an endpoint call
+* Abstracted controllers with request context support 
+* Full interceptors with timing and unified request context support 
 * Robust client error handling and metadata transport abilities
-* Server authentication strategy support, with basic auth with multiple key support built in
+* Server authentication via interceptors, with basic auth with multiple key support built in
 * TLS support for client-server auth, though we recommend using [linkerd](https://linkerd.io/) instead
-* Error data serialization in output metadata to allow fine-grained error handling in the transport while still 
-preserving gRPC BadStatus codes
+* Error data serialization in output metadata to allow fine-grained error handling in the transport while 
+  still preserving gRPC BadStatus codes
 * Server and client execution timings in responses
 
-gruf currently has active support for gRPC 1.4.x. gruf is compatible and tested with with Ruby 2.2, 2.3, and 2.4. 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).
+gruf currently has active support for gRPC 1.4.x-1.6.x. gruf is compatible and tested with Ruby 2.2, 
+2.3, and 2.4. 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
 
@@ -89,26 +90,22 @@ message GetJobResp {
 }
 ```
 
-You'd have this handler in `/app/rpc/demo/job_server.rb`
+You'd have this handler in `/app/rpc/demo/job_controller.rb`
 
 ```ruby
 module Demo
-  class JobServer < ::Demo::Jobs::Service
-    include Gruf::Service
+  class JobController < ::Gruf::Controllers::Base
+    bind ::Demo::Jobs::Service
   
     ##
-    # @param [Demo::GetJobReq] req The incoming gRPC request object
-    # @param [GRPC::ActiveCall] call The gRPC active call instance
     # @return [Demo::GetJobResp] The job response
     #
-    def get_job(req, call)
-      thing = Job.find(req.id)
+    def get_job
+      thing = Job.find(request.message.id)
       
-      Demo::GetJobResp.new(
-        id: thing.id
-      )
+      Demo::GetJobResp.new(id: thing.id)
     rescue
-      fail!(req, call, :not_found, :job_not_found, "Failed to find Job with ID: #{req.id}")
+      fail!(:not_found, :job_not_found, "Failed to find Job with ID: #{request.message.id}")
     end
   end
 end
@@ -118,35 +115,15 @@ Finally, you can start the server by running:
 
     bundle exec gruf
 
-### Authentication
+### Basic Authentication
 
-Authentication is done via a strategy pattern and are injectable via middleware. If any of the strategies return `true`,
-it will proceed the request as successful. For example, to add basic auth, you can do:
+Gruf comes packaged in with a Basic Authentication interceptor. It takes in an array of supported 
+username and password pairs (or password-only credentials).
 
 ```ruby
-Gruf::Authentication::Strategies.add(:basic, Gruf::Authentication::Basic)
-```
-
-Options to the middleware libraries can be passed through the `authentication_options` configuration option.
-
-To add a custom authentication pattern, your class must extend the `Gruf::Authentication::Base` class, and implement
-the `valid?(call)` method. For example, this class allows everyone in:
-
-```
-class NoAuth < Gruf::Authentication::Base
-  def valid?(_call)
-    true
-  end
-end
-```
-
-#### Basic Auth
-
-gruf supports simple basic authentication with an array of accepted credentials:
-
-```ruby
-Gruf.configure do |c|  
-  c.authentication_options = {
+Gruf.configure do |c|
+  c.interceptors.use(
+    Gruf::Instrumentation::Authentication::Basic,
     credentials: [{
       username: 'my-username-here',
       password: 'my-password-here',    
@@ -156,12 +133,12 @@ Gruf.configure do |c|
     },{
       password: 'a-password-only'
     }]
-  }
+  )
 end
 ```
 
-Supporting an array of credentials allow for unique credentials per service, or for easy credential rotation with
-zero downtime.
+Supporting an array of credentials allow for unique credentials per service, or for easy credential 
+rotation with zero downtime.
 
 ### SSL Configuration
 
@@ -189,90 +166,88 @@ Gruf.configure do |c|
 end
 ```
 
-## Hooks
+## Server Interceptors
 
-gruf supports hooks that act as interceptors around the grpc server calls, allowing you to perform actions before, 
-after, and even around your server endpoints. This can be used to add tracing data, connection resets in the grpc thread 
-pool, further instrumentation, and other things.
+gruf supports interceptors around the grpc server calls, allowing you to perform actions around your service
+method calls. This can be used to add tracing data, connection resets in the grpc thread pool, further 
+instrumentation, and other things.
 
-Adding a hook is as simple as creating a class that extends `Gruf::Hooks::Base`, and implementing it via the registry.
+Adding a hook is as simple as creating a class that extends `Gruf::Interceptor::ServerInterceptor`, 
+and a `call` method that yields control to get the method result:
 
-### Before
-
-A before hook passes in the method call signature, request object, and `GRPC::ActiveCall` object:
 ```ruby
-class MyBeforeHook < Gruf::Hooks::Base
-  def before(call_signature, request, active_call)
-    # do my thing before the call. Calling `fail!` here will prevent the call from happening.
+class MyInterceptor < ::Gruf::Interceptors::ServerInterceptor
+  def call
+    yield
   end
 end
-Gruf::Hooks::Registry.add(:my_before_hook, MyBeforeHook)
 ```
 
-### After
+Interceptors have access to the `request` object, which is the `Gruf::Controller::Request` object
+described above.
 
-An after hook passes in the response object, method call signature, request object, and `GRPC::ActiveCall` object:
-```ruby
-class MyAfterHook < Gruf::Hooks::Base
-  def after(success, response, call_signature, request, active_call)
-    # You can modify the response object
-  end
-end
-Gruf::Hooks::Registry.add(:my_after_hook, MyAfterHook)
-```
+### Failing in an Interceptor
 
-### Around
+Interceptors can fail requests with the same method calls as a controller:
 
-An around hook passes in the method call signature, request object, `GRPC::ActiveCall` object, and the block 
-being executed:
 ```ruby
-class MyAroundHook < Gruf::Hooks::Base
-  def around(call_signature, request, active_call, &block)
-    # do my thing here 
-    resp = yield
-    # do my thing there
-    resp
+class MyFailingInterceptor < ::Gruf::Interceptors::ServerInterceptor
+  def call
+    result = yield # this returns the protobuf message
+    unless result.dont_hijack
+      # we'll assume this "dont_hijack" attribute exists on the message for this example
+      fail!(:internal, :hijacked, 'Hijack all the things!')
+    end 
+    result
   end
 end
-Gruf::Hooks::Registry.add(:my_around_hook, MyAroundHook)
 ```
 
-Around hooks are a special case - because each needs to wrap the call, they are run recursively within each other.
-This means that if you have three hooks - `Hook1`, `Hook2`, and `Hook3` - they will run in LIFO (last in, first out) 
-order. `Hook3` will run, calling `Hook2`, which will then call `Hook1`, ending the chain.  
+Similarly, you can raise `GRPC::BadStatus` calls to trigger similar errors without accompanying metadata.
 
-### Outer Around
+### Configuring Interceptors
 
-And finally, an "outer" around hook passes in the method call signature, request object, `GRPC::ActiveCall` 
-object, and the block being executed, and executes around the _entire_ call chain (before, around, request, after):
+From there, the interceptor can be added to the server manually (if not executing via `bundle exec gruf`):
 
 ```ruby
-class MyOuterAroundHook < Gruf::Hooks::Base
-  def outer_around(call_signature, request, active_call, &block)
-    # do my thing here 
-    resp = yield
-    # do my thing there
-    resp
-  end
+server = Gruf::Server.new
+server.add_interceptor(MyInterceptor, option_foo: 'value 123')
+```
+
+Or, alternatively, the more common method of passing them into the `interceptors` configuration hash:
+
+```ruby
+Gruf.configure do |c|
+  c.interceptors.use(MyInterceptor, option_foo: 'value 123')
 end
-Gruf::Hooks::Registry.add(:my_outer_around_hook, MyOuterAroundHook)
 ```
 
-Outer around hooks behave similarly in execution order to around hooks.
+Interceptors each wrap the call and are run recursively within each other. This means that if you have 
+three interceptors - `Interceptor1`, `Interceptor2`, and `Interceptor3` - they will run in FIFO 
+(first in, first out) order. `Interceptor1` will run, yielding to `Interceptor2`, 
+which will then yield to `Interceptor3`, which will then yield to your service method call, 
+ending the chain.
 
-Note: It's important to note that the authentication step happens immediately before the first _before_ hook is called,
-so don't perform any actions that you want behind authentication in outer around hooks, as they are not called with
-authentication.
+You can utilize the `insert_before` and `insert_after` methods to maintain order:
+
+```ruby
+Gruf.configure do |c|
+  c.interceptors.use(Interceptor1)
+  c.interceptors.use(Interceptor2)
+  c.interceptors.insert_before(Interceptor2, Interceptor3) # 3 will now happen before 2
+  c.interceptors.insert_after(Interceptor1, Interceptor4) # 4 will now happen after 1
+end
+```
 
 ## Instrumentation
 
-gruf comes out of the box with a couple of instrumentors packed in: output metadata timings, and StatsD
-support. 
+gruf comes out of the box with a couple of instrumentation interceptors packed in: 
+output metadata timings and StatsD support. 
 
 ### Output Metadata Timing
 
-Enabled by default, this will push timings for _successful responses_ through the response output metadata back to the 
-client.
+Enabled by default, this will push timings for _successful responses_ through the response output 
+metadata back to the client.
 
 ### StatsD
 
@@ -280,22 +255,20 @@ The StatsD support is not enabled by default. To enable it, you'll want to do:
 
 ```ruby
 Gruf.configure do |c|
-  c.instrumentation_options[:statsd] = {
+  c.interceptors.use(
+    Gruf::Interceptors::Instrumentation::Statsd,
     client: ::Statsd.new('my.statsd.host', 8125),
     prefix: 'my_application_prefix.rpc'
-  }
+  )
 end
-Gruf::Instrumentation::Registry.add(:statsd, Gruf::Instrumentation::Statsd)
 ```
 
-This will measure counts and timings for each endpoint. Note: instrumentation hooks happen in LIFO order; they also
-run similarly to an outer_around hook, executing _before_ authorization happens. Note: It's important that in your 
-instrumentors, you pass-through exceptions (such as `GRPC::BadStatus`); catching them in instrumentors will cause errors 
-upstream.
+This will measure counts and timings for each endpoint.
 
 ### Request Logging
 
-Gruf 1.2+ comes built with request logging out of the box; you'll get Rails-style logs with your gRPC calls:
+Gruf 1.2+ comes built with request logging out of the box; you'll get Rails-style logs with your 
+gRPC calls:
 
 ```
 # plain
@@ -308,9 +281,10 @@ It supports formatters (including custom ones) that you can use to specify the f
  
 ```ruby
 Gruf.configure do |c|
-  c.instrumentation_options[:request_logging] = {
+  c.interceptors.use(
+    Gruf::Interceptors::Instrumentation::RequestLogging::Interceptor,
     formatter: :logstash
-  }
+  )
 end
 ```
 
@@ -318,7 +292,7 @@ It comes with a few more options as well:
 
 | Option | Description | Default |
 | ------ | ----------- | ------- |
-| formatter | The formatter to use. By default `:plain` and `:logstash` are supported. | `:plain` |
+| formatter | The formatter to use. By default `:plain` and `:logstash` are supported. | `:logstash` |
 | log_parameters | If set to true, will log parameters in the response | `false` |
 | blacklist | An array of parameter key names to redact from logging, in path.to.key format | `[]` |
 | redacted_string | The string to use for redacted parameters. | `REDACTED` |
@@ -327,11 +301,6 @@ 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).
 
-### Custom Instrumentors
-
-Similar to hooks, simply extend the `Gruf::Instrumentation::Base` class, and implement the `call` method. See the StatsD 
-instrumentor for an example.
-
 ## Plugins
 
 You can build your own hooks and middleware for gruf; here's a list of known open source gems for
@@ -346,8 +315,18 @@ reports for gruf services
 
 ## Demo Rails App
 
-There is a [demonstration Rails application here](https://github.com/bigcommerce/gruf-demo) you can view and clone
-that shows how to integrate Gruf into an existing Rails application. 
+There is a [demonstration Rails application here](https://github.com/bigcommerce/gruf-demo) you can 
+view and clone that shows how to integrate Gruf into an existing Rails application. 
+
+## Roadmap
+
+### Gruf 3.0
+
+* Utilize the new core Ruby interceptors in gRPC 1.7
+* Change configuration to an injectable object to ensure thread safety on chained server/client interactions
+* Move all references to `Gruf.` configuration into injectable parameters
+* Redo server configuration to be fully injectable
+* Move client calls to their native method implementation
 
 ## License
 

data/bin/gruf

@@ -17,13 +17,19 @@
 #
 require 'rubygems'
 require 'bundler/setup'
-require 'gruf'
 require 'rails' rescue nil
 load 'config/environment.rb' if defined?(Rails)
+require 'gruf'
 
 begin
-  server = Gruf::Server.new
+  server = Gruf::Server.new(Gruf.server_options)
+  Gruf.services.each { |s| server.add_service(s) }
   server.start!
 rescue => e
-  Gruf.logger.fatal "FATAL ERROR: #{e.message} #{e.backtrace.join("\n")}"
+  msg = "FATAL ERROR: #{e.message} #{e.backtrace.join("\n")}"
+  if Gruf.logger
+    Gruf.logger.fatal msg
+  else
+    Logger.new(STDOUT).fatal msg
+  end
 end

data/lib/gruf.rb

@@ -23,10 +23,10 @@ require_relative 'gruf/version'
 require_relative 'gruf/logging'
 require_relative 'gruf/loggable'
 require_relative 'gruf/configuration'
-require_relative 'gruf/authentication'
-require_relative 'gruf/hooks/registry'
-require_relative 'gruf/instrumentation/registry'
-require_relative 'gruf/service'
+require_relative 'gruf/errors/helpers'
+require_relative 'gruf/controllers/base'
+require_relative 'gruf/interceptors/registry'
+require_relative 'gruf/interceptors/base'
 require_relative 'gruf/timer'
 require_relative 'gruf/response'
 require_relative 'gruf/error'

data/lib/gruf/configuration.rb

@@ -23,22 +23,19 @@ module Gruf
       root_path: '',
       server_binding_url: '0.0.0.0:9001',
       server_options: {},
-      authentication_options: {},
-      instrumentation_options: {},
-      hook_options: {},
+      interceptors: nil,
       default_client_host: '',
       use_ssl: false,
       ssl_crt_file: '',
       ssl_key_file: '',
-      servers_path: '',
+      controllers_path: '',
       services: [],
       logger: nil,
       grpc_logger: nil,
       error_metadata_key: :'error-internal-bin',
       error_serializer: nil,
-      authorization_metadata_key: 'authorization',
       append_server_errors_to_trailing_metadata: true,
-      use_default_hooks: true,
+      use_default_interceptors: true,
       backtrace_on_error: false,
       use_exception_message: true,
       internal_error_message: 'Internal Server Error'
@@ -85,27 +82,21 @@ module Gruf
       VALID_CONFIG_KEYS.each do |k, v|
         send((k.to_s + '='), v)
       end
+      self.interceptors = Gruf::Interceptors::Registry.new
+      self.root_path = Rails.root.to_s.chomp('/') if defined?(Rails)
       if defined?(Rails) && Rails.logger
-        self.root_path = Rails.root
         self.logger = Rails.logger
       else
         require 'logger'
         self.logger = ::Logger.new(STDOUT)
       end
       self.grpc_logger = logger if grpc_logger.nil?
-      self.ssl_crt_file = "#{root_path}/config/ssl/#{environment}.crt"
-      self.ssl_key_file = "#{root_path}/config/ssl/#{environment}.key"
-      self.servers_path = "#{root_path}/app/rpc"
-      self.authentication_options = {
-        credentials: [{
-          username: 'grpc',
-          password: 'magic'
-        }]
-      }
-      if use_default_hooks
-        Gruf::Hooks::Registry.add(:ar_connection_reset, Gruf::Hooks::ActiveRecord::ConnectionReset)
-        Gruf::Instrumentation::Registry.add(:output_metadata_timer, Gruf::Instrumentation::OutputMetadataTimer)
-        Gruf::Instrumentation::Registry.add(:request_logging, Gruf::Instrumentation::RequestLogging::Hook)
+      self.ssl_crt_file = "#{root_path}config/ssl/#{environment}.crt"
+      self.ssl_key_file = "#{root_path}config/ssl/#{environment}.key"
+      self.controllers_path = root_path.to_s.empty? ? 'app/rpc' : "#{root_path}/app/rpc"
+      if use_default_interceptors
+        interceptors.use(Gruf::Interceptors::ActiveRecord::ConnectionReset)
+        interceptors.use(Gruf::Interceptors::Instrumentation::OutputMetadataTimer)
       end
       options
     end