gruf 2.7.0 → 2.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8fb4c36a5bd87553944bb4056fcca8875620cffe1d623f8757db6fa0e88f9aee
-  data.tar.gz: b3903a27dd46302ac99db4cbfa512b7ffc6b3ad9a4faafe83ac22fe83469ae29
+  metadata.gz: b132efe87ccf85ffcf897a67f5c268b8696e60e5f2b280c93c52f08fea1aa122
+  data.tar.gz: 6a1d99886e075daac23eadeabd5e347c92d4fdc7659f7dd639d7e79e38c6b6f8
 SHA512:
-  metadata.gz: ba2ccb4ffe9915044fa8026eefa6e078b746d392af52401a779ad62bcd12ae2ae92cdfce73dc8680564d635bad0f2412b2ff3c740dd0fbfb5291a6a3c3fe70f6
-  data.tar.gz: c3db4263ae977cede3b9f3adb9cd90984e7906f72c1d005d3b61f977bb64eb3b442e8b4a092475f6fdd9af4ad5510d7e316255bbe59613c4f19d0d8231a48edf
+  metadata.gz: b5140ea90e6bc018cef228f7bece3096cd389bec36cc4b80f5e1a9b2ebefbab7afe494146c9f4843418f06ffe27d404885d470477c732986befe94b69191297d
+  data.tar.gz: fb3baf2ad10bf606b57c37f45d419e11c41bb34ce56c9801d3367cb471cfe22f097b42bbfa60aa77cbb3eda338c947eee48f909b2866df1bf660953772ac2b64

data/CHANGELOG.md

@@ -2,6 +2,35 @@ Changelog for the gruf gem. This includes internal history before the gem was ma
 
 ### Pending release
 
+### 2.10.0
+
+- Drop support for Ruby 2.4/2.5 to align with Ruby EOL schedule, supporting 2.6+ only
+- Allow for float/TimeSpec timeout values on clients
+
+### 2.9.0
+
+- Change to racially neutral terminology across library
+  - blacklist->blocklist
+  - master->main branch
+- Explicitly declare development dependencies in gemspec
+- Add script/e2e test for full e2e test in regression suite
+- Explicitly declare [json gem](https://rubygems.org/gems/json) dependency
+- Update to Rubocop 1.4, add in rubocop-rspec for spec tests
+- Add Ruby 2.7, 3.0 support
+
+### 2.8.1
+
+- Fix issue with --suppress-default-interceptors not working [#95]
+- Loosen rake development dependency to >= 10.0 [#97]
+
+### 2.8.0
+
+- Pass the controller request object into the request logging formatters [#92]  
+
+### 2.7.1
+
+- Add `channel_credentials` option to `Gruf::Client` and `default_channel_credentials` option to `Gruf::Configuration` [#85] [#87]
+
 ### 2.7.0
 
 - Add hook support for executing code paths before a server is started, and after a server stops
@@ -132,11 +161,11 @@ Gruf 2.0 is a major shift from Gruf 1.0. See [UPGRADING.md](UPGRADING.md) for de
 ### 1.2.4
 
 - Loosen explicit Protobuf dependency now that 3.4.0.2 is released
-- Guard against nil params in logger blacklist
+- Guard against nil params in logger blocklist
 
 ### 1.2.3
 
-- Support nested blacklist parameters in path.to.key format
+- Support nested blocklist parameters in path.to.key format
 
 ### 1.2.2
 
@@ -158,7 +187,7 @@ Gruf 2.0 is a major shift from Gruf 1.0. See [UPGRADING.md](UPGRADING.md) for de
 - 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
+  parameter logging, blocklists, and formatter support
 - Optimizations around Symbol casting within service calls
 
 ### 1.1.0

data/README.md

@@ -1,8 +1,8 @@
 # gruf - gRPC Ruby Framework
 
-[![CircleCI](https://circleci.com/gh/bigcommerce/gruf/tree/master.svg?style=svg)](https://circleci.com/gh/bigcommerce/gruf/tree/master) [![Gem Version](https://badge.fury.io/rb/gruf.svg)](https://badge.fury.io/rb/gruf) [![Documentation](https://inch-ci.org/github/bigcommerce/gruf.svg?branch=master)](https://inch-ci.org/github/bigcommerce/gruf?branch=master)
+[![CircleCI](https://circleci.com/gh/bigcommerce/gruf/tree/main.svg?style=svg)](https://circleci.com/gh/bigcommerce/gruf/tree/main) [![Gem Version](https://badge.fury.io/rb/gruf.svg)](https://badge.fury.io/rb/gruf) [![Documentation](https://inch-ci.org/github/bigcommerce/gruf.svg?branch=main)](https://inch-ci.org/github/bigcommerce/gruf?branch=main)
 
-gruf is a Ruby framework that wraps the [gRPC Ruby library](https://github.com/grpc/grpc/tree/master/src/ruby) to
+gruf is a Ruby framework that wraps the [gRPC Ruby library](https://github.com/grpc/grpc/tree/main/src/ruby) to
 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
@@ -17,515 +17,20 @@ 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 currently has active support for gRPC 1.10.x+. gruf is compatible and tested with Ruby 2.2-2.7.
 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).
+(such as [Grape](https://github.com/ruby-grape/grape) or [dry-rb](https://dry-rb.org/), for instance).
 
-## Installation
+### Getting Started
 
-```ruby
-gem 'gruf'
-```
-
-Then in an initializer or before use:
-
-```ruby
-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
-
-Add an initializer:
-
-```ruby
-require 'gruf'
-
-Gruf.configure do |c|
-  c.default_client_host = 'grpc.service.com:9003'
-end
-```
-
-If you don't explicitly set `default_client_host`, you will need to pass it into the options, like so:
-
-```ruby
-client = ::Gruf::Client.new(service: ::Demo::ThingService, options: {hostname: 'grpc.service.com:9003'})
-```
-
-From there, you can instantiate a client given a stub service (say on an SslCertificates proto with a GetSslCertificate call):
-
-```ruby
-require 'gruf'
-
-id = args[:id].to_i.presence || 1
-
-begin
-  client = ::Gruf::Client.new(service: ::Demo::ThingService)
-  response = client.call(:GetMyThing, id: id)
-  puts response.message.inspect
-rescue Gruf::Client::Error => e
-  puts e.error.inspect
-end
-```
-
-Note this returns a response object. The response object can provide `trailing_metadata` as well as a `execution_time`.
-
-### SynchronizedClient
-
-SynchronizedClient wraps Client with some additional behavior to help prevent generating spikes
-of redundant requests. If multiple calls to the same endpoint with the same parameters are made,
-the first one will be executed and the following ones will block, waiting for the first result.
-
-```ruby
-require 'gruf'
-require 'thwait'
-
-id = args[:id].to_i.presence || 1
-client = ::Gruf::SynchronizedClient.new(service: ::Demo::ThingService)
-thread1 = Thread.new { client.call(:GetMyThing, id: id) }
-thread2 = Thread.new { client.call(:GetMyThing, id: id) }
-ThreadsWait.all_waits(thread1, thread2)
-```
-
-In the above example, thread1 will make the rpc call, thread2 will block until the call is complete, and then
-will get the same value without making a second rpc call.
-
-You can also skip this behavior for certain methods if desired.
-
-```ruby
-require 'gruf'
-require 'thwait'
-
-id = args[:id].to_i.presence || 1
-client = ::Gruf::SynchronizedClient.new(service: ::Demo::ThingService, options: { unsynchronized_methods: [:GetMyThing] })
-thread1 = Thread.new { client.call(:GetMyThing, id: id) }
-thread2 = Thread.new { client.call(:GetMyThing, id: id) }
-ThreadsWait.all_waits(thread1, thread2)
-```
-
-In the above example, thread1 and thread2 will make rpc calls in parallel, in the same way as if you had used
-`Gruf::Client`.
-
-### Client Interceptors
-
-Gruf comes with an assistance class for client interceptors that you can use - or you can use the native gRPC core
-interceptors. Either way, you pass them into the `client_options` when creating a client:
-
-```ruby
-class MyInterceptor < Gruf::Interceptors::ClientInterceptor
-  def call(request_context:)
-    logger.info "Got method #{request_context.method}!"
-    yield
-  end
-end
-
-::Gruf::Client.new(
-  service: ::Demo::ThingService,
-  client_options: {
-    interceptors: [MyInterceptor.new]
-  })
-```
-
-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:
-
-* *type* - A Symbol of the type of request (`request_response`, `server_streamer`, etc)
-* *requests* An enumerable of requests being sent. For unary requests, this is a single request in an array
-* *call* - The `GRPC::ActiveCall` object
-* *method* - The Method being called
-* *metadata* - The hash of outgoing metadata
-
-Note that you _must_ yield back the block when building a client interceptor, so that the call can be executed.
-
-### Server
-
-Add an initializer:
-
-```ruby
-require 'gruf'
-
-Gruf.configure do |c|
-  c.server_binding_url = 'grpc.service.com:9003'
-end
-```
-
-Next, setup some handlers based on your proto configurations in `/app/rpc/`. For example, for the Thing service, with a
-GetThingReq/GetThingResp call based on this proto:
-
-```proto
-syntax = "proto3";
-
-package demo;
-
-service Jobs {
-    rpc GetJob(GetJobReq) returns (GetJobResp) { }
-}
-
-message GetJobReq {
-    uint64 id = 1;
-}
-
-message GetJobResp {
-    uint64 id = 1;
-    string name = 2;
-}
-```
-
-You'd have this handler in `/app/rpc/demo/job_controller.rb`
-
-```ruby
-module Demo
-  class JobController < ::Gruf::Controllers::Base
-    bind ::Demo::Jobs::Service
-
-    ##
-    # @return [Demo::GetJobResp] The job response
-    #
-    def get_job
-      thing = Job.find(request.message.id)
-
-      Demo::GetJobResp.new(id: thing.id)
-    rescue
-      fail!(:not_found, :job_not_found, "Failed to find Job with ID: #{request.message.id}")
-    end
-  end
-end
-```
-
-Finally, you can start the server by running:
-
-```bash
-bundle exec gruf
-```
-
-### Command-Line Options
-
-Gruf comes baked in with a few command-line options for the binstub:
-
-| Option | Description |
-| ------ | ----------- |
-| -h, --help | Displays the help message |
-| -v, --version | Displays the gruf version |
-| --host | Specify the server binding host |
-| --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.
-
-### Basic Authentication
-
-Gruf comes packaged in with a Basic Authentication interceptor. It takes in an array of supported
-username and password pairs (or password-only credentials).
-
-In Server:
-
-```ruby
-Gruf.configure do |c|
-  c.interceptors.use(
-    Gruf::Interceptors::Authentication::Basic,
-    credentials: [{
-      username: 'my-username-here',
-      password: 'my-password-here',
-    },{
-      username: 'another-username',
-      password: 'another-password',
-    },{
-      password: 'a-password-only'
-    }]
-  )
-end
-```
-
-In Client:
-
-```ruby
-require 'gruf'
-
-id = args[:id].to_i.presence || 1
-
-options = {
-  username: ENV.fetch('DEMO_THING_SERVICE_USERNAME'),
-  password: ENV.fetch('DEMO_THING_SERVICE_PASSWORD')
-}
-
-begin
-  client = ::Gruf::Client.new(service: ::Demo::ThingService, options: options)
-  response = client.call(:GetMyThing, id: id)
-  puts response.message.inspect
-rescue Gruf::Client::Error => e
-  puts e.error.inspect
-end
-```
-
-Supporting an array of credentials allow for unique credentials per service, or for easy credential
-rotation with zero downtime.
-
-### SSL Configuration
-
-We don't recommend using TLS for gRPC, but instead using something like [linkerd](https://linkerd.io) for TLS
-encryption between services. If you need it, however, this library supports TLS.
-
-For the client, you'll need to point to the public certificate:
-
-```ruby
-::Gruf::Client.new(
-  service: Demo::ThingService,
-  options: {
-    ssl_certificate: 'x509 public certificate here',
-    # OR
-    ssl_certificate_file: '/path/to/my.crt'
-  }
-)
-```
-
-If you want to run a server you'll need both the CRT and the key file if you want to do credentialed auth:
-
-```ruby
-Gruf.configure do |c|
-  c.use_ssl = true
-  c.ssl_crt_file = "#{Rails.root}/config/ssl/#{Rails.env}.crt"
-  c.ssl_key_file = "#{Rails.root}/config/ssl/#{Rails.env}.key"
-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
-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::Interceptor::ServerInterceptor`,
-and a `call` method that yields control to get the method result:
-
-```ruby
-class MyInterceptor < ::Gruf::Interceptors::ServerInterceptor
-  def call
-    yield
-  end
-end
-```
-
-Interceptors have access to the `request` object, which is the `Gruf::Controller::Request` object
-described above.
-
-### Failing in an Interceptor
-
-Interceptors can fail requests with the same method calls as a controller:
-
-```ruby
-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
-```
-
-Similarly, you can raise `GRPC::BadStatus` calls to trigger similar errors without accompanying metadata.
-
-### Configuring Interceptors
-
-From there, the interceptor can be added to the server manually (if not executing via `bundle exec gruf`):
-
-```ruby
-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
-```
-
-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.
-
-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
-```
-
-By default, the ActiveRecord Connection Reset interceptor and Output Metadata Timing interceptor
-are loaded into gruf unless explicitly told not to via the `use_default_interceptors` configuration
-parameter.
-
-## Hooks
-
-Hooks, unlike interceptors, are executed outside of the request chain, such as when a server starts
-or stops. They run in FIFO order sequentially and do not wrap one another. They can be used to provide
-custom boot sequences, external instrumentation support, or shutdown alerting. 
-
-You can create a hook by extending the `Gruf::Hooks::Base` class and defining the methods
-on the hook you wish to implement:
-
-```ruby
-class MyHook < Gruf::Hooks::Base
-  def before_server_start(server:)
-    # do my thing before the server starts  
-  end
-  
-  def after_server_stop(server:)
-    # do my thing after the server stops
-  end
-end
-
-# Then in an initializer:
-
-Gruf.configure do |c|
-  c.hooks.use(MyHook, option_foo: 'value 123')
-end
-```
-
-Exceptions raised in hooks will halt the execution chain and bubble up the stack appropriately.
-
-### Available Hook Insertion Points
-
-Current hook insertion points are:
-
-* `before_server_start` - Right before the gRPC server starts
-* `after_server_stop` - Right after the gRPC server is shutdown
-
-Note that exceptions raised in `before_server_start` will halt the execution chain for the remaining 
-`before_server_start` hooks, but will still execute the `after_server_stop` hooks as expected. Exceptions raised
-in `after_server_stop` will prevent further `after_server_stop` hooks from running.
-
-## Instrumentation
-
-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.
-
-### StatsD
-
-The StatsD support is not enabled by default. To enable it, you'll want to do:
-
-```ruby
-Gruf.configure do |c|
-  c.interceptors.use(
-    Gruf::Interceptors::Instrumentation::Statsd,
-    client: ::Statsd.new('my.statsd.host', 8125),
-    prefix: 'my_application_prefix.rpc'
-  )
-end
-```
-
-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:
-
-```
-# 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.interceptors.use(
-    Gruf::Interceptors::Instrumentation::RequestLogging::Interceptor,
-    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. | `: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` |
-| ignore_methods | An array of method names to ignore from logging. E.g. `['namespace.health.check']` | `[]` |
-
-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).
-
-## Testing with RSpec
-
-There is a gem specifically for easy testing with RSpec: [gruf-rspec](https://github.com/bigcommerce/gruf-rspec). Take
-a look at its README for more information.
-
-## 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-lightstep](https://github.com/bigcommerce/gruf-lightstep) - Provides a seamless
-[LightStep](https://lightstep.com) integration
-* [gruf-zipkin](https://github.com/bigcommerce/gruf-zipkin) - Provides a [Zipkin](https://zipkin.io)
-integration
-* [gruf-newrelic](https://github.com/bigcommerce/gruf-newrelic) - Easy [New Relic](https://newrelic.com/) integration
-* [gruf-commander](https://github.com/bigcommerce/gruf-commander) - Request/command-style validation and
-execution patterns for services
-* [gruf-profiler](https://github.com/bigcommerce/gruf-profiler) - Profiles and provides memory usage
-reports for clients and services
-* [gruf-circuit-breaker](https://github.com/bigcommerce/gruf-circuit-breaker) - Circuit breaker
-support for services
+Please see the [gruf wiki](https://github.com/bigcommerce/gruf/wiki) for detailed information on getting started
+using gruf.
 
 ## 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.
 
-## Roadmap
-
-### Gruf 3.0
-
-* 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
-
-## Companies Using Gruf
-
-Using gruf and want to show your support? Let us know and we'll add your name here.
-
-* [BigCommerce](https://www.bigcommerce.com/)
-
 ## License
 
 Copyright (c) 2017-present, BigCommerce Pty. Ltd. All rights reserved