rails_twirp 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9dc494fd35fa5a920f6ca55c6a024f73bda616a10cc91336fefb3d7520f9c3ed
-  data.tar.gz: 5da02487fde28997da7fb200c0a9693fc952fc5662a2e43864d0a12c788ec7d5
+  metadata.gz: 6af836779332d2bcf1810379884b7ef9e219f63e81b2972b501a45ae1880f1cb
+  data.tar.gz: b0a967815e9326fa7889fdf1f3ec77b08f835921b8a919cee5cc95150407aa20
 SHA512:
-  metadata.gz: e67eba63003648f4ba6cbc604e4e2006783c5f2873e95745f56bb1f9cfea0660d1f55850b4128b088728f829ef41989c634839b6168d5a512480e465631a60e0
-  data.tar.gz: 163e1cd73f34ed7ee62a531c71b6a5153c35231b731645ceba25e22f37e45d94f0a51fc1ff220928eb33d2297964f108cb71696779ea958cd80dc0e4410fe462
+  metadata.gz: 139e2f8517c0e1b2664b0d264d4722ebdc74fde78bfdb9724ea03d31d80ab99eec66a304a25bfaec23e17ed032b5396406742993ebabc2fc464c3eea338dd5bd
+  data.tar.gz: 4df604dc7f1772238a2ea95b3e573aa352b354a58a92f9caa157add1889ba59dd95d8bbab9283dbf9632b807514c28fc21eca913b03f0bb254d57eadfbef200b

data/.github/workflows/test.yml

@@ -6,7 +6,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
 
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+### 0.13.0
+* Adding #controller_name methods to Metal/Base controller (used for instrumentation)
+* Include `ActionController::Caching` with Base controller/helpers
+
+
+### 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/Gemfile

@@ -4,7 +4,7 @@ source "https://rubygems.org"
 gemspec
 
 gem "sqlite3"
-gem "pbbuilder", "~> 0.12.0"
+gem "pbbuilder"
 gem "standard"
 gem "pry"
 

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/base.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
+
 require "abstract_controller/base"
 require "abstract_controller/rendering"
 require "action_view/rendering"
 require "rails_twirp/render_pb"
 require "rails_twirp/errors"
 require "abstract_controller/asset_paths"
-require "abstract_controller/caching"
 require "abstract_controller/logger"
 require "abstract_controller/callbacks"
 require "action_controller/metal/helpers"
@@ -13,11 +14,10 @@ require "rails_twirp/url_for"
 require "rails_twirp/implicit_render"
 require "rails_twirp/instrumentation"
 require "rails_twirp/exception_handling"
+require "rails_twirp/metal"
 
 module RailsTwirp
-  class Base < AbstractController::Base
-    abstract!
-
+  class Base < RailsTwirp::Metal
     # The order of these includes matter.
     # The rendering modules extend each other, so need to be in this order.
     include AbstractController::Rendering
@@ -26,7 +26,6 @@ module RailsTwirp
     include ActionController::Helpers
     include UrlFor
     include AbstractController::AssetPaths
-    include AbstractController::Caching
 
     include ActionView::Rendering
     include RenderPb
@@ -39,7 +38,14 @@ module RailsTwirp
     include Instrumentation
     include ExceptionHandling
 
-    attr_internal :request, :env, :response_class, :rpc_name
+    ##
+    # :attr_reader: request
+    #
+    # The ActionDispatch::Request instance for the current request.
+    attr_internal :request
+
+    attr_internal :env, :response_class, :rpc_name
+
     def initialize
       @_request = nil
       @_env = nil

data/lib/rails_twirp/engine.rb

@@ -34,7 +34,11 @@ module RailsTwirp
 
     initializer "rails_twirp.helpers" do |app|
       ActiveSupport.on_load(:rails_twirp) do
-        # Load all the application helpers into the controller
+        # Load all the application helpers into the controller.
+        # Note that helpers need to be set up here, because apparently
+        # the AbstractController::Helpers module won't be able to find
+        # the _helpers method on a reloaded controller
+        include ActionController::Caching
         include app.routes.mounted_helpers
         extend ::AbstractController::Railties::RoutesHelpers.with(app.routes, false)
         extend ::ActionController::Railties::Helpers

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/metal.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RailsTwirp
+  # This is a simplest possible controller, providing a valid
+  # Rack interfacee without the additional niceties provided by RailsTwirp.
+  #
+  # Idiologially, it's similar to Rails version of ActionController::Metal
+  class Metal < AbstractController::Base
+    abstract!
+
+    # Returns the last part of the controller's name, underscored, without the ending
+    # <tt>Controller</tt>. For instance, PostsController returns <tt>posts</tt>.
+    # Namespaces are left out, so Admin::PostsController returns <tt>posts</tt> as well.
+    #
+    # ==== Returns
+    # * <tt>string</tt>
+    def self.controller_name
+      @controller_name ||= (name.demodulize.delete_suffix("Controller").underscore unless anonymous?)
+    end
+
+    # Delegates to the class's ::controller_name.
+    def controller_name
+      self.class.controller_name
+    end
+  end
+end

data/lib/rails_twirp/version.rb

@@ -1,3 +1,3 @@
 module RailsTwirp
-  VERSION = "0.11.0"
+  VERSION = "0.13.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/rails_twirp.gemspec

@@ -10,7 +10,6 @@ Gem::Specification.new do |spec|
   spec.license = "MIT"
 
   spec.files = `git ls-files`.split("\n")
-  spec.test_files = `git ls-files -- test/*`.split("\n")
 
   spec.add_dependency "rails", ">= 6.1.3"
   spec.add_dependency "twirp", ">= 1.7.2", "~> 1.9.0"

data/test/dummy/app/views/dummy/rpc_name_check.pb.pbbuilder

@@ -1 +1,3 @@
-pb.rpc_name @rpc_name
+pb.cache! "rpc-#{@rpc_name}", expire_in: 1.minute do
+	pb.rpc_name @rpc_name
+end

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.13.0
 platform: ruby
 authors:
 - Bouke van der Bijl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-12 00:00:00.000000000 Z
+date: 2023-01-24 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
@@ -72,6 +73,7 @@ files:
 - lib/rails_twirp/instrumentation.rb
 - lib/rails_twirp/log_subscriber.rb
 - lib/rails_twirp/mapper.rb
+- lib/rails_twirp/metal.rb
 - lib/rails_twirp/render_pb.rb
 - lib/rails_twirp/rescue.rb
 - lib/rails_twirp/route_set.rb
@@ -169,71 +171,4 @@ rubygems_version: 3.2.32
 signing_key:
 specification_version: 4
 summary: Integrate Twirp into Rails
-test_files:
-- test/dummy/Rakefile
-- test/dummy/app/assets/config/manifest.js
-- test/dummy/app/assets/images/.keep
-- test/dummy/app/assets/stylesheets/application.css
-- test/dummy/app/channels/application_cable/channel.rb
-- test/dummy/app/channels/application_cable/connection.rb
-- test/dummy/app/controllers/application_controller.rb
-- test/dummy/app/controllers/application_twirp_controller.rb
-- test/dummy/app/controllers/concerns/.keep
-- test/dummy/app/controllers/dummy_controller.rb
-- test/dummy/app/controllers/pings_controller.rb
-- test/dummy/app/controllers/testmod/nested/other_controller.rb
-- test/dummy/app/helpers/application_helper.rb
-- test/dummy/app/helpers/random_helper.rb
-- test/dummy/app/javascript/packs/application.js
-- test/dummy/app/jobs/application_job.rb
-- test/dummy/app/mailers/application_mailer.rb
-- test/dummy/app/models/application_record.rb
-- test/dummy/app/models/concerns/.keep
-- test/dummy/app/views/dummy/rpc_name_check.pb.pbbuilder
-- test/dummy/app/views/layouts/application.html.erb
-- test/dummy/app/views/layouts/mailer.html.erb
-- test/dummy/app/views/layouts/mailer.text.erb
-- test/dummy/app/views/pings/ping_template.pb.pbbuilder
-- test/dummy/bin/generate
-- test/dummy/bin/rails
-- test/dummy/bin/rake
-- test/dummy/bin/setup
-- test/dummy/config.ru
-- test/dummy/config/application.rb
-- test/dummy/config/boot.rb
-- test/dummy/config/cable.yml
-- test/dummy/config/database.yml
-- test/dummy/config/environment.rb
-- test/dummy/config/environments/development.rb
-- test/dummy/config/environments/production.rb
-- test/dummy/config/environments/test.rb
-- test/dummy/config/initializers/application_controller_renderer.rb
-- test/dummy/config/initializers/backtrace_silencers.rb
-- test/dummy/config/initializers/content_security_policy.rb
-- test/dummy/config/initializers/cookies_serializer.rb
-- test/dummy/config/initializers/filter_parameter_logging.rb
-- test/dummy/config/initializers/inflections.rb
-- test/dummy/config/initializers/mime_types.rb
-- test/dummy/config/initializers/permissions_policy.rb
-- test/dummy/config/initializers/wrap_parameters.rb
-- test/dummy/config/locales/en.yml
-- test/dummy/config/puma.rb
-- test/dummy/config/routes.rb
-- test/dummy/config/storage.yml
-- test/dummy/config/twirp/routes.rb
-- test/dummy/lib/assets/.keep
-- test/dummy/log/.keep
-- test/dummy/proto/api.proto
-- test/dummy/proto/api_pb.rb
-- test/dummy/proto/api_twirp.rb
-- test/dummy/public/404.html
-- test/dummy/public/422.html
-- test/dummy/public/500.html
-- test/dummy/public/apple-touch-icon-precomposed.png
-- test/dummy/public/apple-touch-icon.png
-- test/dummy/public/favicon.ico
-- test/dummy_test.rb
-- test/other_controller_test.rb
-- test/ping_controller_test.rb
-- test/rails_twirp_test.rb
-- test/test_helper.rb
+test_files: []