gruf 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 56cf6dec601362d024f7af23944ab121a4f2aff1
-  data.tar.gz: 7e765e811c3c98b53faf823b168bbeca03f34cfc
+  metadata.gz: 0bf92528e6ff160d8d3a6997b8b00a44d86c46ac
+  data.tar.gz: 52bc1ac08fbf89488719d85c00bab0e741359c87
 SHA512:
-  metadata.gz: 3b2bcfb022a963fbf10cb645e92a40691dc0cb4586b4579a4362a452123312a3341c8e72dd79f37f5d3615390acb1db718fc0cb5cf4d69ce0a6b479edd327584
-  data.tar.gz: 534ef51f35af8c749c12455f8c50e63b9967c9f9b9cf9b012795913b51b2080a068cae7acb85235d6ce9ffaddf37172a82473cc559cf864b17b876ca96682d58
+  metadata.gz: 9caf811ac34255710d42a13a1a7f9066279d6c747a0e9b86fb3fff100aea31dc9889deb161acdfaa4b80907810f689c367851497ecd5399cde16a417df2bcf61
+  data.tar.gz: 86151ce87a7c7598e9a2a132b2d21fee05c10e621456766b78c3d11b94df942fb5d7d3e478333a0e84c8d6d7ebf0a223f1272be819dafbf2fd530bb007fd7983

data/CHANGELOG.md

@@ -1,47 +1,65 @@
 Changelog for the gruf gem. This includes internal history before the gem was made.
 
-h3. 1.1.0
+### Pending release
+
+
+
+### 1.2.0
+
+- Instrumentation hooks now execute similarly to outer_around hooks; they can
+  now instrument failures
+- Instrumentation hooks now pass a `RequestContext` object that contains information
+  about the incoming request, instead of relying on instance variables 
+- StatsD hook now sends success/failure metrics for endpoints
+- Add ability to turn off sending exception message on uncaught exception.
+- Add configuration to set the error message when an uncaught exception is
+  handled by gruf.
+- Add a request logging hook for Rails-style request logging, with optional 
+  parameter logging, blacklists, and formatter support 
+- Optimizations around Symbol casting within service calls
+
+### 1.1.0
 
 - Add the ability for call options to the client, which enables deadline setting 
 
-h3. 1.0.0
+### 1.0.0
 
 - Bump gRPC to 1.4 
 
-h3. 0.14.2
+### 0.14.2
 
 - Added rubocop style-guide checks
 
-h3. 0.14.1
+### 0.14.1
 
 - Updated license to MIT
 
-h3. 0.14.0
+### 0.14.0
 
 - Send gRPC status 16 (Unauthenticated) instead of 7 (PermissionDenied) when authentication fails
 
-h3. 0.13.0
+### 0.13.0
 
 - Move to gRPC 1.3.4
 
-h4. 0.12.2
+### 0.12.2
 
 - Add outer_around hook for wrapping the entire call chain
 
-h4. 0.12.1
+### 0.12.1
 
 - Add ability to specify a separate gRPC logger from the Gruf logger
 
-h3. 0.12.0
+### 0.12.0
 
 - Add ability to run multiple around hooks
 - Fix bug with error handling that caused error messages to repeat across streams 
 
-h3. 0.11.5
+### 0.11.5
 
 - Fix issue with around hook
 
-h3. 0.11.4
+### 0.11.4
 
 - Add catchall rescue handler to capture uncaught exceptions and
   raise a GRPC::Internal error.
@@ -49,37 +67,37 @@ h3. 0.11.4
   will call Service.set_debug_info with the exception backtrace
   if an uncaught exception occurs.
 
-h3. 0.11.3
+### 0.11.3
 
 - Pass the service instance into hooks for reference
 
-h3. 0.11.2
+### 0.11.2
 
 - Ensure timer is measuring in milliseconds
 
-h3. 0.11.1
+### 0.11.1
 
 - Fix issue with interceptor and call signature
 
-h3. 0.11.0
+### 0.11.0
 
 - Add instrumentation layer and ability to register new instrumentors
 - Add out-of-the-box statsd instrumentation support
 
-h3. 0.10.0
+### 0.10.0
 
 - Rename Gruf::Endpoint to Gruf::Service
 - Make services auto-mount to server upon declaration
 
-h3. 0.9.2
+### 0.9.2
 
 - Support mount command on services to allow automatic setup on the server
 - Cleanup and consolidate binstub to prevent need for custom binstub per-app
 
-h3. 0.9.1
+### 0.9.1
 
 - Relax licensing to a clean BSD license
 
-h3. 0.9.0
+### 0.9.0
 
 - Initial public release

data/README.md

@@ -32,6 +32,9 @@ Then in an initializer or before use:
 require 'gruf'
 ```
 
+Make sure to review [UPGRADING.md](https://github.com/bigcommerce/gruf/blob/master/UPGRADING.md) 
+if you are upgrading gruf between minor or major versions.
+
 ### Client
 
 From there, you can instantiate a client given a stub service (say on an SslCertificates proto with a GetSslCertificate call):
@@ -42,7 +45,7 @@ require 'gruf'
 id = args[:id].to_i.presence || 1
 
 begin
-  client = ::Gruf::Client.new(service: MyPackage::MyService)
+  client = ::Gruf::Client.new(service: ::Demo::ThingService)
   response = client.call(:GetMyThing, id: id)
   puts response.message.inspect
 rescue Gruf::Client::Error => e
@@ -72,40 +75,40 @@ syntax = "proto3";
 
 package demo;
 
-service Thing {
-    rpc GetThing(GetThingReq) returns (GetSslCertificateResp) { }
+service Jobs {
+    rpc GetJob(GetJobReq) returns (GetJobResp) { }
 }
 
-message ThingReq {
+message GetJobReq {
     uint64 id = 1;
 }
 
-message ThingResp {
+message GetJobResp {
     uint64 id = 1;
     string name = 2;
 }
 ```
 
-You'd have this handler in `/app/rpc/demo/thing_server.rb`
+You'd have this handler in `/app/rpc/demo/job_server.rb`
 
 ```ruby
 module Demo
-  class ThingServer < ::Demo::ThingService::Service
+  class JobServer < ::Demo::Jobs::Service
     include Gruf::Service
   
     ##
-    # @param [Demo::GetThingReq] req
-    # @param [GRPC::ActiveCall] call
-    # @return [Demo::GetThingResp]
+    # @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_thing(req, call)
-      ssl = Thing.find(req.id)
+    def get_job(req, call)
+      thing = Job.find(req.id)
       
-      Demo::Things::GetThingResp.new(
-        id: ssl.id
+      Demo::GetJobResp.new(
+        id: thing.id
       )
     rescue
-      fail!(req, call, :not_found, :thing_not_found, "Failed to find Thing with ID: #{req.id}")
+      fail!(req, call, :not_found, :job_not_found, "Failed to find Job with ID: #{req.id}")
     end
   end
 end
@@ -277,23 +280,70 @@ 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: {
-      client: ::Statsd.new('my.statsd.host', 8125),
-      prefix: 'my_application_prefix.rpc'
-    }
+  c.instrumentation_options[: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.
+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.
+
+### Request Logging
+
+Gruf 1.2+ comes built with request logging out of the box; you'll get Rails-style logs with your gRPC calls:
+
+```
+# plain
+I, [2017-07-14T09:50:54.200506 #70571]  INFO -- : [GRPC::Ok] (thing_service.get_thing) [0.348ms]
+# logstash
+I, [2017-07-14T09:51:03.299050 #70595]  INFO -- : {"message":"[GRPC::Ok] (thing_service.get_thing) [0.372ms]","service":"thing_service","method":"thing_service.get_thing","grpc_status":"GRPC::Ok"}
+ ```
+
+It supports formatters (including custom ones) that you can use to specify the formatting of the logging:
+ 
+```ruby
+Gruf.configure do |c|
+  c.instrumentation_options[:request_logging] = {
+    formatter: :logstash
+  }
+end
+```
+
+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` |
+| log_parameters | If set to true, will log parameters in the response | `false` |
+| blacklist | An array of parameter key names to redact from logging | `[]` |
+| redacted_string | The string to use for redacted parameters. | `REDACTED` |
+
+It's important to maintain a safe blacklist should you decide to log parameters; gruf does no 
+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
+gruf that you can use today:
+ 
+* [gruf-zipkin](https://github.com/bigcommerce/gruf-zipkin) - Provides a [Zipkin](https://zipkin.io)
+integration for gruf
+* [gruf-circuit-breaker](https://github.com/bigcommerce/gruf-circuit-breaker) - Provides circuit breaker
+support for gruf services
+* [gruf-profiler](https://github.com/bigcommerce/gruf-profiler) - Profiles and provides memory usage 
+reports for gruf services
+
 ## License
 
 Copyright (c) 2017-present, BigCommerce Pty. Ltd. All rights reserved 

data/lib/gruf.rb

@@ -33,6 +33,9 @@ require_relative 'gruf/error'
 require_relative 'gruf/client'
 require_relative 'gruf/server'
 
+##
+# Initializes configuration of gruf core module
+#
 module Gruf
   extend Configuration
 end

data/lib/gruf/authentication.rb

@@ -20,11 +20,19 @@ require_relative 'authentication/basic'
 require_relative 'authentication/none'
 
 module Gruf
+  ##
+  # Handles authentication for gruf services
+  #
   module Authentication
+    ##
+    # Custom error class for handling unauthorized requests
+    #
     class UnauthorizedError < StandardError; end
 
     ##
-    # @param [GRPC::ActiveCall] call
+    # Verify a given gruf request
+    #
+    # @param [GRPC::ActiveCall] call The gRPC active call with marshalled data that is being executed
     # @param [Symbol] strategy The authentication strategy to use
     # @return [Boolean]
     #

data/lib/gruf/authentication/base.rb

@@ -17,16 +17,21 @@
 module Gruf
   module Authentication
     ##
-    # Base interface for Authentication strategies
+    # Base interface for Authentication strategies. All derived strategies must define the `valid?` method.
     #
     class Base
       include Gruf::Loggable
 
-      attr_reader :credentials, :options
+      # @return [String] The credentials sent in the request
+      attr_reader :credentials
+      # @return [Hash] A hash of authentication options
+      attr_reader :options
 
       ##
+      # Initialize the authentication middleware
       #
-      # @param [String] credentials
+      # @param [String] credentials The credentials sent in the request
+      # @param [Hash] options A hash of authentication options
       #
       def initialize(credentials, options = {})
         opts = Gruf.authentication_options || {}
@@ -37,17 +42,20 @@ module Gruf
       ##
       # Verify the credentials. Helper class method.
       #
-      # @param [GRPC::ActiveCall] call
-      # @param [String] credentials
-      # @param [Hash] options
+      # @param [GRPC::ActiveCall] call The gRPC active call for the given operation
+      # @param [String] credentials The credentials sent in the request
+      # @param [Hash] options A hash of authentication options
       #
       def self.verify(call, credentials = '', options = {})
         new(credentials, options).valid?(call)
       end
 
       ##
-      # @param [GRPC::ActiveCall] _call
-      # @return [Boolean]
+      # Abstract method that is required to be implemented in every derivative class.
+      # Return true if the call is authenticated, false if a permission denied error is to be sent.
+      #
+      # @param [GRPC::ActiveCall] _call The gRPC active call for the given operation
+      # @return [Boolean] True if the call was authenticated
       #
       def valid?(_call)
         raise NotImplementedError

data/lib/gruf/authentication/basic.rb

@@ -23,8 +23,8 @@ module Gruf
     #
     class Basic < Base
       ##
-      # @param [GRPC::ActiveCall] _call
-      # @return [Boolean]
+      # @param [GRPC::ActiveCall] _call The gRPC active call for the given operation
+      # @return [Boolean] True if the basic authentication was valid
       #
       def valid?(_call)
         server_credentials.any? do |cred|
@@ -41,21 +41,21 @@ module Gruf
       private
 
       ##
-      # @return [Array<Hash>]
+      # @return [Array<Hash>] An array of valid server credentials for this service
       #
       def server_credentials
         options.fetch(:credentials, [])
       end
 
       ##
-      # @return [String]
+      # @return [String] The decoded request credentials
       #
       def request_credentials
         Base64.decode64(credentials.to_s.gsub('Basic ', '').strip)
       end
 
       ##
-      # @return [String]
+      # @return [String] The decoded request username
       # @deprecated
       # :nocov:
       def request_username
@@ -64,7 +64,7 @@ module Gruf
       # :nocov:
 
       ##
-      # @return [String]
+      # @return [String] The decoded request password
       #
       def request_password
         @request_password ||= request_credentials.split(':').last

data/lib/gruf/authentication/none.rb

@@ -21,8 +21,8 @@ module Gruf
     #
     class None < Base
       ##
-      # @param [GRPC::ActiveCall] _call
-      # @return [TrueClass]
+      # @param [GRPC::ActiveCall] _call The gRPC active call for the given operation
+      # @return [TrueClass] Always true for this passthrough strategy.
       #
       def valid?(_call)
         true

data/lib/gruf/authentication/strategies.rb

@@ -20,15 +20,19 @@ module Gruf
     # Provides a modifiable repository of strategies for authentication
     #
     class Strategies
+      ##
+      # Error class that represents when a strategy does not extend the base class
+      #
       class StrategyDescendantError < StandardError; end
 
       class << self
         ##
         # Add an authentication strategy, either through a class or a block
         #
-        # @param [String] name
-        # @param [Class|NilClass] strategy
-        # @return [Class]
+        # @param [String] name The vanity name of the strategy being loaded
+        # @param [Class|NilClass] strategy (Optional) The class that represents the strategy
+        # @param [Proc] &block If given, will attempt to build a strategy class from the base class with this block
+        # @return [Class] The loaded strategy
         #
         def add(name, strategy = nil, &block)
           base = Gruf::Authentication::Base
@@ -46,12 +50,15 @@ module Gruf
         ##
         # Return a strategy via a hash accessor syntax
         #
+        # @param [Symbol] label The name of the strategy
+        # @return [Gruf::Authentication::Base] The requested strategy
+        #
         def [](label)
           _strategies[label.to_sym]
         end
 
         ##
-        # Iterate over each
+        # Iterate over each strategy and yield it to the caller
         #
         def each
           _strategies.each do |s|
@@ -60,21 +67,27 @@ module Gruf
         end
 
         ##
-        # @return [Hash<Class>]
+        # Return the loaded strategies as a hash
+        #
+        # @return [Hash<Class>] A name/strategy pair of loaded strategies
         #
         def to_h
           _strategies
         end
 
         ##
-        # @return [Boolean]
+        # Return if there are any loaded strategies
+        #
+        # @return [Boolean] True if there are loaded strategies
         #
         def any?
           to_h.keys.count > 0
         end
 
         ##
-        # @return [Hash]
+        # Clear all given strategies
+        #
+        # @return [Hash] The newly empty hash
         #
         def clear
           @strategies = {}