rails_twirp 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9dc494fd35fa5a920f6ca55c6a024f73bda616a10cc91336fefb3d7520f9c3ed
-  data.tar.gz: 5da02487fde28997da7fb200c0a9693fc952fc5662a2e43864d0a12c788ec7d5
+  metadata.gz: '09e97be65f570cd7a2cecaaf0ef83d2ead287fd1fc8c556b833ae45395ee1c2b'
+  data.tar.gz: 1b30d280c8c724747b0b71ef7996ad23fd0a8e189818156602f284677ac9c637
 SHA512:
-  metadata.gz: e67eba63003648f4ba6cbc604e4e2006783c5f2873e95745f56bb1f9cfea0660d1f55850b4128b088728f829ef41989c634839b6168d5a512480e465631a60e0
-  data.tar.gz: 163e1cd73f34ed7ee62a531c71b6a5153c35231b731645ceba25e22f37e45d94f0a51fc1ff220928eb33d2297964f108cb71696779ea958cd80dc0e4410fe462
+  metadata.gz: 858ea0680c3efd03f2f1fdc766f6097b6e0a7b19ff39974412207139cd28a432d4c620a7a4f9243b63b9f70eff1919cb5a92d0c3dc6b5cd73ba99eb1349ac870
+  data.tar.gz: ba6311d0b7cb64755380eff9d1168d24458d5804f36acf21c7fceab2a8b0db305722353d8c5f493bf1692225f973342e3194f825d995df286802da6958631e3a

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+### 0.12.0
+
+* Allow a custom exception handling proc to be assigned using `RailsTwirp.unhandled_exception_handler`
+
+### 0.11.0
+
+* Update configuration and tests for Rails 7 compatibility
+
+### 0.10.0
+
+* Handle exceptions more like the Rails controllers do it, do not capture all of them as if they were Twirp exceptions

data/README.md

@@ -1,8 +1,56 @@
 # RailsTwirp
-Short description and motivation.
+
+Allows for effortless integration of [Twirp](https://github.com/twitchtv/twirp) endpoints into your Rails application. RailsTwirp permits you to define your Twirp endpoints using the familiar vocabulary of Rails routes, controllers, actions and views.
+
+Using an extra routes file you map your Twirp RPCs to controllers, and define your views using [pbbuilder.](https://github.com/cheddar-me/pbbuilder) Even though you are now serving Twirp RPC endpoints instead of HTML or JSON, all the skills and tools you have for working your usual Rails infrastructure apply. `TwirpRails` provides a customised controller superclass called `RailsTwirp::Base` which includes all the relevant ActionController components which still make sense when using Protobufs.
 
 ## Usage
-How to use my plugin.
+
+Add the gem to your project (see "Installation" below). Then add a file called `config/twirp/routes.rb` to your application, and map your RPCs inside of that file. We will map a `GreetWorld` RPC call as an example:
+
+```ruby
+Rails.application.twirp.routes.draw do
+  service HelloService, module: :api do
+    rpc "GreetWorld", to: "greetings#greet"
+  end
+end
+```
+
+The `module` defines the module which will contain your `TwirpRails` controller. The `HelloService` module is your Protobuf mapping generated using Twirp, it inherits from `Twirp::Service` and could look like this:
+
+```ruby
+class HelloService < Twirp::Service
+  package 'api'
+  service 'App'
+  rpc :GreetWorld, GreetWorldRequest, GreetWorldResponse, :ruby_method => :greet_world
+end
+```
+
+The `GreetWorldRequest` in this case is the autogenerated protobuf request class, the `GreetWorldResponse` is the response class.
+
+Then you define your controller, which looks like a standard Rails controller - just with a different base class:
+
+```ruby
+class API::GreetingsController  < RailsTwirp::Base
+  def greet
+    render pb: API::GreetResponse.new
+  end
+end
+```
+
+Note that the controller is routed using the same naming conventions as Rails. Inside of a `TwirpRails` controller you can do most of the things you are used to from Rails controllers, such as renders and implicit renders - which have to be `pbbuilder` views. If our `GreetWorldResponse` has a `greeting` field, it can be filled inside the `pbbuilder` view like so:
+
+```ruby
+pb.greeting "Hello stranger"
+```
+
+Inside the controllers you have access to the call parameters of your RPC call using `request`:
+
+```ruby
+def greet
+  request.name #=> # Returns the value of the "name" field from the request Protobuf
+end
+```
 
 ## Installation
 Add this line to your application's Gemfile:
@@ -37,7 +85,14 @@ end
 ```
 
 ## Contributing
-Contribution directions go here.
+
+* Check out the latest `main` to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for your change. This is important so we don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history.
 
 ## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/rails_twirp/exception_handling.rb

@@ -9,17 +9,27 @@ module RailsTwirp
     def process_action(*)
       super
     rescue Exception => e
+      # Only the exceptions which are not captured by ActionController-like "rescue_from" end up here.
+      # The idea is that any exception which is rescued by the controller is treated as part of the business
+      # logic, and thus taking action on it is the responsibility of the controller which uses "rescue_from".
+      # If an exception ends up here it means it wasn't captured by the handlers defined in the controller.
+
       # We adopt the same error handling logic as Rails' standard middlewares:
       # 1. When we 'show exceptions' we make the exception bubble up—this is useful for testing
+      #    If the exception gets raised here error reporting will happen in the middleware of the APM package
+      #    higher in the call stack.
       raise e unless http_request.show_exceptions?
 
-      # 2. When we want to show detailed exceptions we include the exception message in the error
+      # 2. We report the error to the error tracking service, this needs to be configured.
+      RailsTwirp.unhandled_exception_handler&.call(e)
+
+      # 3. When we want to show detailed exceptions we include the exception message in the error
       if http_request.get_header("action_dispatch.show_detailed_exceptions")
         self.response_body = Twirp::Error.internal_with(e)
         return
       end
 
-      # 3. Otherwise we just return a vague internal error message
+      # 4. Otherwise we just return a vague internal error message
       self.response_body = Twirp::Error.internal("Internal error")
     end
   end

data/lib/rails_twirp/version.rb

@@ -1,3 +1,3 @@
 module RailsTwirp
-  VERSION = "0.11.0"
+  VERSION = "0.12.0"
 end

data/lib/rails_twirp.rb

@@ -8,6 +8,7 @@ require "rails_twirp/log_subscriber"
 
 module RailsTwirp
   mattr_accessor :test_app
+  mattr_accessor :unhandled_exception_handler
 end
 
 require "rails_twirp/engine" if defined?(Rails)

data/test/ping_controller_test.rb

@@ -66,6 +66,24 @@ class PingControllerTest < RailsTwirp::IntegrationTest
     Rails.application.env_config["action_dispatch.show_exceptions"] = false
   end
 
+  test "uncaught errors should be fanned out to the exception handler proc if one is defined" do
+    Rails.application.env_config["action_dispatch.show_exceptions"] = true
+
+    captured_exception = nil
+    RailsTwirp.unhandled_exception_handler = ->(e) { captured_exception = e }
+
+    req = RPC::DummyAPI::PingRequest.new
+    rpc RPC::DummyAPI::DummyService, "UncaughtError", req
+    assert_instance_of Twirp::Error, response
+    assert_equal :internal, response.code
+    assert_equal "Uncaught", response.msg
+    assert_equal "StandardError", response.meta["cause"]
+    assert_kind_of StandardError, captured_exception
+  ensure
+    RailsTwirp.unhandled_exception_handler = nil
+    Rails.application.env_config["action_dispatch.show_exceptions"] = false
+  end
+
   test "uncaught errors should return an internal error without if show_exceptions is true and show_detailed_exceptions is false" do
     Rails.application.env_config["action_dispatch.show_exceptions"] = true
     Rails.application.env_config["action_dispatch.show_detailed_exceptions"] = false

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_twirp
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Bouke van der Bijl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-12 00:00:00.000000000 Z
+date: 2022-01-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -56,6 +56,7 @@ files:
 - ".gitignore"
 - ".ruby-version"
 - ".standard.yml"
+- CHANGELOG.md
 - Gemfile
 - MIT-LICENSE
 - README.md