gruf 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8db09af385df9c2a441b0bf6ece236e8d3a0735a
+  data.tar.gz: dff8c04b4439335743edb8c6cbd7e74d7cb64f43
+SHA512:
+  metadata.gz: 040cfcf2678a142635796b35706dc1599e4b0364a4cc6a90fbc9628e02d3b273427452b3325d6e08988b53e80d2a08482879072c90927de16f697ad7f7937c3f
+  data.tar.gz: 3a67f98f29b8be1b9216a0c609e040308721afe822719d591cd74a82cb3d3c791b796d96eee750e096b2de7c837607377e01101b760d1fd4fb82dcc2e98ca904

data/CHANGELOG.md

@@ -0,0 +1,81 @@
+Changelog for the gruf gem. This includes internal history before the gem was made.
+
+h3. 1.0.0
+
+- Bump gRPC to 1.4 
+
+h3. 0.14.2
+
+- Added rubocop style-guide checks
+
+h3. 0.14.1
+
+- Updated license to MIT
+
+h3. 0.14.0
+
+- Send gRPC status 16 (Unauthenticated) instead of 7 (PermissionDenied) when authentication fails
+
+h3. 0.13.0
+
+- Move to gRPC 1.3.4
+
+h4. 0.12.2
+
+- Add outer_around hook for wrapping the entire call chain
+
+h4. 0.12.1
+
+- Add ability to specify a separate gRPC logger from the Gruf logger
+
+h3. 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
+
+- Fix issue with around hook
+
+h3. 0.11.4
+
+- Add catchall rescue handler to capture uncaught exceptions and
+  raise a GRPC::Internal error.
+- Add Gruf.backtrace_on_error configuration value. If set, Gruf
+  will call Service.set_debug_info with the exception backtrace
+  if an uncaught exception occurs.
+
+h3. 0.11.3
+
+- Pass the service instance into hooks for reference
+
+h3. 0.11.2
+
+- Ensure timer is measuring in milliseconds
+
+h3. 0.11.1
+
+- Fix issue with interceptor and call signature
+
+h3. 0.11.0
+
+- Add instrumentation layer and ability to register new instrumentors
+- Add out-of-the-box statsd instrumentation support
+
+h3. 0.10.0
+
+- Rename Gruf::Endpoint to Gruf::Service
+- Make services auto-mount to server upon declaration
+
+h3. 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
+
+- Relax licensing to a clean BSD license
+
+h3. 0.9.0
+
+- Initial public release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at splittingred@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/README.md

@@ -0,0 +1,312 @@
+# gruf - gRPC Ruby Framework
+
+[![Build Status](https://travis-ci.com/bigcommerce/gruf.svg?token=D3Cc4LCF9BgpUx4dpPpv&branch=master)](https://travis-ci.com/bigcommerce/gruf)
+
+gruf is a Ruby framework that wraps the [gRPC Ruby library](https://github.com/grpc/grpc/tree/master/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
+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
+* Robust client error handling and metadata transport abilities
+* Server authentication strategy support, 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
+* 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).
+
+## Installation
+
+```ruby
+gem 'gruf'
+```
+
+Then in an initializer or before use:
+
+```ruby
+require 'gruf'
+```
+
+### Client
+
+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: MyPackage::MyService)
+  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`.
+
+### 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:
+
+```
+syntax = "proto3";
+
+package demo;
+
+service Thing {
+    rpc GetThing(GetThingReq) returns (GetSslCertificateResp) { }
+}
+
+message ThingReq {
+    uint64 id = 1;
+}
+
+message ThingResp {
+    uint64 id = 1;
+    string name = 2;
+}
+```
+
+You'd have this handler in `/app/rpc/demo/thing_server.rb`
+
+```ruby
+module Demo
+  class ThingServer < ::Demo::ThingService::Service
+    include Gruf::Service
+  
+    ##
+    # @param [Demo::GetThingReq] req
+    # @param [GRPC::ActiveCall] call
+    # @return [Demo::GetThingResp]
+    #
+    def get_thing(req, call)
+      ssl = Thing.find(req.id)
+      
+      Demo::Things::GetThingResp.new(
+        id: ssl.id
+      )
+    rescue
+      fail!(req, call, :not_found, :thing_not_found, "Failed to find Thing with ID: #{req.id}")
+    end
+  end
+end
+```
+
+Finally, you can start the server by running:
+
+    bundle exec gruf
+
+### 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:
+
+```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 = {
+    credentials: [{
+      username: 'my-username-here',
+      password: 'my-password-here',    
+    },{
+      username: 'another-username',
+      password: 'another-password',    
+    },{
+      password: 'a-password-only'
+    }]
+  }
+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,
+  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
+```
+
+## Hooks
+
+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.
+
+Adding a hook is as simple as creating a class that extends `Gruf::Hooks::Base`, and implementing it via the registry.
+
+### 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.
+  end
+end
+Gruf::Hooks::Registry.add(:my_before_hook, MyBeforeHook)
+```
+
+### After
+
+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)
+```
+
+### Around
+
+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
+  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.  
+
+### Outer Around
+
+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):
+
+```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
+end
+Gruf::Hooks::Registry.add(:my_outer_around_hook, MyOuterAroundHook)
+```
+
+Outer around hooks behave similarly in execution order to around hooks.
+
+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.
+
+## Instrumentation
+
+gruf comes out of the box with a couple of instrumentors 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.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.
+
+### Custom Instrumentors
+
+Similar to hooks, simply extend the `Gruf::Instrumentation::Base` class, and implement the `call` method. See the StatsD 
+instrumentor for an example.
+
+## License
+
+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.