tonic-rails 0.2.0-x86_64-linux-gnu → 0.3.0-x86_64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73ed3d0d421cd1cb77193b7d5025925cbe8737022553d28f7c95bd0d7ca2242a
-  data.tar.gz: e75d6f30c34e225b6668cdbe7f8072c22b5a5b1e53c782962f4327873cfcf7b2
+  metadata.gz: 3b594b6ba6699510bedb286cab5e05fc8fa3578d200fdb704fd8335529ee0105
+  data.tar.gz: df3ddc7f65ca300dce59a26855fcadfd88f573c9f892039afa727ec16a3dc01e
 SHA512:
-  metadata.gz: d66dbcc4d4bd4721d007fd0ace7004fc2af5ae1c9f209c082e2004d38892fa96373c22375db9da6dbeae358d93b9a0f69c30ba7f3309f0a8bed3615dcb9c11a3
-  data.tar.gz: 209db51bbf3305ed9aeba24a9c407653f08397b875490d295e3ebccaf3667182869ee5a950fe78a747c3b7d3799f5ae879aa9453dc594fbbd8ddedca66bb3fa9
+  metadata.gz: 0d8da9f21bc78c95c31b708a0349d54f23e9a5395bad4de0d46937ec1fae721bd6590a74d498dd523e087b1a1c90b23af6a10c93f2cfaab262d554e3c74272a0
+  data.tar.gz: a67219c39168b2eeae48a638b73ebdfa65a4c5a0300138577088f214868db989e36196647639753563584e49dfb256da0175f2b13aac0b8526d30cb9cee38f44

data/CHANGELOG.md

@@ -7,6 +7,38 @@ minor versions may contain breaking changes.
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-11
+
+### Added
+
+- Generators: `rails g tonic_rails:install` (initializer, proto and
+  generated-code directories, Puma plugin) and `rails g tonic_rails:service
+  Item GetItem ListItems:server` (proto, handler with a stub per RPC,
+  registration, and an RSpec or Minitest test).
+- Controller-style callbacks for handlers: `before_rpc`, `after_rpc` and
+  `around_rpc` with `only:` / `except:`, plus `current_rpc` and `request`
+  accessors.
+- `rescue_from` (ActiveSupport::Rescuable) with a `code:` shorthand that maps
+  an exception class to a gRPC status.
+- `peer` in handlers: the client's address and, with mutual TLS, its
+  certificate (`peer.certificate`, an `OpenSSL::X509::Certificate`).
+  `Testing.call`/`invoke` accept `peer:`.
+- App-controlled health: `config.health_check` (polled every
+  `health_check_interval` seconds inside the Rails executor) and
+  `Tonic::Rails.server.serving!` / `not_serving!` for the whole server or
+  individual services, so readiness probes reflect real dependency health.
+- Test helpers: the `raise_grpc_error(code).with_message(...)` RSpec matcher
+  (`require "tonic/rails/testing/rspec"`) and `assert_grpc_error` for Minitest
+  (`Tonic::Rails::Testing::Assertions`). Both accept `Tonic::Rails::RpcError`
+  and the grpc gem's `GRPC::BadStatus`.
+
+### Changed
+
+- `tonic_rails:compile_protos` requires protoc 22 or newer and says so,
+  instead of generating code google-protobuf 4 can't load (older protoc,
+  such as Ubuntu's 3.21 package, emits a Ruby DSL that google-protobuf 4
+  removed).
+
 ## [0.2.0] - 2026-10-11
 
 ### Added
@@ -84,6 +116,7 @@ First public release.
 - Precompiled native gems for Linux (x86_64, aarch64; glibc and musl) and
   macOS (x86_64, arm64), Ruby 3.3 to 4.0.
 
-[Unreleased]: https://github.com/CodingAnarchy/tonic-rails/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/CodingAnarchy/tonic-rails/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/CodingAnarchy/tonic-rails/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/CodingAnarchy/tonic-rails/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/CodingAnarchy/tonic-rails/releases/tag/v0.1.0

data/README.md

@@ -60,10 +60,31 @@ On platforms without a precompiled gem, installation builds the
 extension from source, which needs a [Rust toolchain](https://rustup.rs).
 
 To generate Ruby classes from your `.proto` files you also need `protoc`
-(the Protocol Buffers compiler) during development.
+(the Protocol Buffers compiler) **22.0 or newer** during development.
+Older versions, such as Ubuntu's `protobuf-compiler` package (3.21),
+generate code that google-protobuf 4 can't load; install a current
+release from the [protobuf releases page](https://github.com/protocolbuffers/protobuf/releases)
+or Homebrew.
 
 ## Quick start
 
+The generators set everything up:
+
+```sh
+bin/rails generate tonic_rails:install
+bin/rails generate tonic_rails:service Item GetItem ListItems:server
+bin/rails tonic_rails:compile_protos
+```
+
+`install` adds `config/initializers/tonic_rails.rb` (load path for
+generated code, configuration, handler registration), `app/protos/`,
+`lib/grpc/`, and the Puma plugin. `service` writes the `.proto`, a handler
+in `app/grpc/` with a stub per RPC, its registration, and a spec (or
+Minitest test). RPCs take an optional `:server`, `:client` or `:bidi`
+streaming kind.
+
+The rest of this section shows the same steps by hand.
+
 ### 1. Define the service
 
 ```protobuf
@@ -236,11 +257,54 @@ Any other exception becomes `INTERNAL` with the message `internal error`.
 The real exception is logged and passed to `Rails.error.report`, so your
 error tracker sees it.
 
+### Callbacks and rescue_from
+
+Handlers get controller-style callbacks and exception mapping:
+
+```ruby
+class ItemService
+  include Tonic::Rails::Base
+  rpc_service "demo.v1.ItemService"
+
+  before_rpc :authenticate, except: :ListItems
+  around_rpc :with_tenant
+  after_rpc { StatsD.increment("grpc.#{current_rpc}") }
+
+  rescue_from ActiveRecord::RecordNotFound, code: :not_found
+  rescue_from ActiveRecord::RecordInvalid, code: :invalid_argument, message: ->(e) { e.record.errors.full_messages.join(", ") }
+  rescue_from Pundit::NotAuthorizedError, with: :forbidden
+
+  private
+
+  def authenticate
+    @user = User.from_token(grpc_metadata["authorization"])
+    raise Tonic::Rails::RpcError.new("invalid token", code: :unauthenticated) unless @user
+  end
+
+  def with_tenant(&) = Tenant.switch(@user.tenant, &)
+
+  def forbidden(_e) = raise(Tonic::Rails::RpcError.new("not allowed", code: :permission_denied))
+end
+```
+
+- `before_rpc`, `after_rpc` and `around_rpc` accept method names or a
+  block, plus `only:` / `except:` with RPC names (`:GetItem` or
+  `:get_item`). Raising in a `before_rpc` stops the call.
+- `current_rpc` is the RPC being handled and `request` the decoded
+  request, so callbacks can inspect it.
+- `after_rpc` runs once a streamed response has been fully sent.
+- `rescue_from` covers the handler and its callbacks. With `code:`, the
+  exception's message is sent to the client unless you pass `message:`.
+  Handlers given with `with:` or a block must raise an `RpcError`.
+  Anything unmapped becomes `INTERNAL`, as before.
+
 ### Metadata, deadlines and shutdown
 
 ```ruby
 def get_item(request)
   token = grpc_metadata["authorization"]   # request headers, lower-case
+  peer.ip                                    # client address ("10.0.4.17")
+  peer.certificate&.subject                  # client certificate, with mutual TLS
   deadline_ms                                # ms left before the client's deadline, or nil
   deadline_exceeded?                         # true once it has passed
   cancelled?                                 # true while the server shuts down
@@ -322,6 +386,30 @@ result.headers["x-cache"]    # => "hit"
 result.trailers["x-cost-ms"] # => "3"
 ```
 
+Matchers for gRPC statuses work with `Testing.call` and with the official
+`grpc` client's errors:
+
+```ruby
+# spec/rails_helper.rb
+require "tonic/rails/testing/rspec"
+
+expect { Tonic::Rails::Testing.call(ItemService, :GetItem, { id: 0 }) }
+  .to raise_grpc_error(:not_found).with_message(/0/)
+```
+
+```ruby
+# Minitest
+require "tonic/rails/testing/minitest"
+
+class ItemServiceTest < ActiveSupport::TestCase
+  include Tonic::Rails::Testing::Assertions
+
+  test "missing items" do
+    assert_grpc_error(:not_found) { Tonic::Rails::Testing.call(ItemService, :GetItem, { id: 0 }) }
+  end
+end
+```
+
 ## Configuration
 
 Set options in `config/application.rb` or an environment file:
@@ -353,6 +441,8 @@ end
 | `tls_client_ca_path` | `nil` | PEM CA bundle; requires client certificates (mutual TLS) |
 | `drain_timeout` | `10` | Seconds to let in-flight calls finish on shutdown |
 | `keepalive_interval`, `keepalive_timeout` | `15`, `5` | HTTP/2 PING interval and timeout, seconds |
+| `health_check` | `nil` | Callable; while false or raising, health reports `NOT_SERVING` |
+| `health_check_interval` | `5` | Seconds between health checks |
 | `compression` | `false` | gzip responses over 1 KiB for clients that accept it |
 | `reflection` | `false` | Serve `grpc.reflection.v1`; exposes your schema |
 | `interceptors` | `[]` | See [Interceptors](#interceptors) |
@@ -399,7 +489,19 @@ Don't combine it with the plugin.
 - **Health checks.** `grpc.health.v1.Health` reports `SERVING` for the
   server (`""`) and every registered service, and flips to `NOT_SERVING`
   as soon as shutdown begins. Point your load balancer or Kubernetes
-  gRPC probes at it.
+  gRPC probes at it. To make readiness reflect your dependencies, add a
+  check that runs every `health_check_interval` seconds (default 5):
+
+  ```ruby
+  config.health_check = -> { ActiveRecord::Base.connection.active? }
+  ```
+
+  While it returns false or raises, the server reports `NOT_SERVING`
+  (calls are still served). You can also mark the server or a service
+  yourself, for example during maintenance:
+  `Tonic::Rails.server.not_serving!("demo.v1.ItemService")` and
+  `serving!`. A service is `SERVING` only while the check passes and it
+  isn't marked otherwise.
 - **Graceful shutdown.** On SIGTERM or SIGINT the server stops
   accepting connections, tells clients to go away (HTTP/2 GOAWAY), lets
   in-flight calls finish for up to `drain_timeout` seconds, then exits.

data/lib/generators/tonic_rails/install/install_generator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module TonicRails
+  module Generators
+    # rails generate tonic_rails:install
+    #
+    # Sets an app up for gRPC: an initializer (load path for generated
+    # protobuf code, configuration, handler registration), the proto and
+    # generated-code directories, and the Puma plugin.
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :skip_puma, type: :boolean, default: false,
+                               desc: "Don't add `plugin :tonic_rails` to config/puma.rb"
+      class_option :skip_next_steps, type: :boolean, default: false, hide: true
+
+      def create_initializer
+        template "tonic_rails.rb.tt", "config/initializers/tonic_rails.rb"
+      end
+
+      def create_directories
+        create_file "app/protos/.keep"
+        create_file "lib/grpc/.keep"
+      end
+
+      def add_puma_plugin
+        return if options[:skip_puma]
+
+        puma = "config/puma.rb"
+        return unless File.exist?(File.join(destination_root, puma))
+        return if File.read(File.join(destination_root, puma)).match?(/plugin\s+:tonic_rails/)
+
+        append_to_file puma, "\n# Run the tonic-rails gRPC server alongside Puma.\nplugin :tonic_rails\n"
+      end
+
+      def show_next_steps
+        return if options[:skip_next_steps]
+
+        say "\nNext: rails generate tonic_rails:service Item GetItem ListItems:server", :green
+      end
+    end
+  end
+end

data/lib/generators/tonic_rails/install/templates/tonic_rails.rb.tt

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Ruby code generated from app/protos by `bin/rails tonic_rails:compile_protos`
+# lives in lib/grpc. Its files require each other by plain name, so put the
+# directory on the load path and keep Zeitwerk away from it.
+Rails.root.join("lib/grpc").then do |generated|
+  $LOAD_PATH.unshift(generated.to_s) unless $LOAD_PATH.include?(generated.to_s)
+  Rails.autoloaders.main.ignore(generated)
+end
+
+Tonic::Rails.configure do |config|
+  # config.bind_address = "0.0.0.0:50051"
+  # config.dispatch_threads = ENV.fetch("RAILS_MAX_THREADS", 5).to_i
+  # config.reflection = Rails.env.development?
+  # config.health_check = -> { ActiveRecord::Base.connection.active? }
+end
+
+# Handlers in app/grpc are autoloaded; register them here so they're
+# picked up again after code reloads.
+Rails.application.config.to_prepare do
+end

data/lib/generators/tonic_rails/service/service_generator.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module TonicRails
+  module Generators
+    # rails generate tonic_rails:service Item GetItem ListItems:server ImportItems:client Sync:bidi
+    #
+    # Creates a .proto with the service and its messages, a handler with a
+    # method per RPC, the handler's registration, and a test.
+    class ServiceGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      STREAM_KINDS = %w[unary server client bidi].freeze
+
+      argument :rpcs, type: :array, default: [], banner: "Rpc[:server|:client|:bidi] ..."
+
+      class_option :package, type: :string,
+                             desc: "Protobuf package (default: <app name>.v1)"
+
+      def check_rpcs
+        rpc_specs.each do |rpc|
+          next if rpc[:name].match?(/\A[A-Z][A-Za-z0-9]*\z/) && STREAM_KINDS.include?(rpc[:kind])
+
+          raise Thor::Error, "Invalid RPC #{rpc[:raw].inspect}: use CamelCase names, optionally :server, :client or :bidi"
+        end
+      end
+
+      def create_proto
+        template "service.proto.tt", "app/protos/#{package_path}/#{service_file}_service.proto"
+      end
+
+      def create_handler
+        template "handler.rb.tt", "app/grpc/#{service_file}_service.rb"
+      end
+
+      def register_handler
+        initializer = "config/initializers/tonic_rails.rb"
+        invoke "tonic_rails:install", [], skip_next_steps: true unless File.exist?(File.join(destination_root, initializer))
+        inject_into_file initializer, "  Tonic::Rails.server.register(#{service_class})\n",
+                         after: "Rails.application.config.to_prepare do\n"
+      end
+
+      def create_test
+        if File.directory?(File.join(destination_root, "spec"))
+          template "service_spec.rb.tt", "spec/grpc/#{service_file}_service_spec.rb"
+        else
+          template "service_test.rb.tt", "test/grpc/#{service_file}_service_test.rb"
+        end
+      end
+
+      def show_next_steps
+        say "\nNext: bin/rails tonic_rails:compile_protos, then fill in app/grpc/#{service_file}_service.rb", :green
+      end
+
+      private
+
+      # "Item" and "ItemService" both mean the service ItemService.
+      def service_base
+        class_name.delete_suffix("Service")
+      end
+
+      def service_file
+        service_base.underscore
+      end
+
+      def service_class
+        "#{service_base}Service"
+      end
+
+      def package
+        options[:package] || "#{app_name}.v1"
+      end
+
+      def app_name
+        app = defined?(::Rails.application) && ::Rails.application
+        name = app ? app.class.module_parent_name : File.basename(destination_root)
+        name.to_s.underscore.tr("-", "_").presence || "app"
+      end
+
+      def package_path
+        package.tr(".", "/")
+      end
+
+      def ruby_module
+        package.split(".").map(&:camelize).join("::")
+      end
+
+      def full_service_name
+        "#{package}.#{service_class}"
+      end
+
+      def rpc_specs
+        list = rpcs.empty? ? ["Get#{service_base}"] : rpcs
+        list.map do |raw|
+          name, kind = raw.split(":", 2)
+          { raw: raw, name: name.to_s, kind: kind || "unary", method: name.to_s.underscore }
+        end
+      end
+
+      def proto_rpc_line(rpc)
+        request = "#{rpc[:name]}Request"
+        response = "#{rpc[:name]}Response"
+        request = "stream #{request}" if %w[client bidi].include?(rpc[:kind])
+        response = "stream #{response}" if %w[server bidi].include?(rpc[:kind])
+        "rpc #{rpc[:name]}(#{request}) returns (#{response});"
+      end
+    end
+  end
+end

data/lib/generators/tonic_rails/service/templates/handler.rb.tt

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "<%= package_path %>/<%= service_file %>_service_pb"
+
+class <%= service_class %>
+  include Tonic::Rails::Base
+
+  rpc_service "<%= full_service_name %>"
+  request_format :message
+<% rpc_specs.each do |rpc| %>
+<% case rpc[:kind] -%>
+<% when "unary" -%>
+  # @param request [<%= ruby_module %>::<%= rpc[:name] %>Request]
+  # @return [<%= ruby_module %>::<%= rpc[:name] %>Response]
+  def <%= rpc[:method] %>(request)
+    raise Tonic::Rails::RpcError.new("<%= rpc[:name] %> is not implemented yet", code: :unimplemented)
+  end
+<% when "server" -%>
+  # @param request [<%= ruby_module %>::<%= rpc[:name] %>Request]
+  # @return [Enumerable<<%= ruby_module %>::<%= rpc[:name] %>Response>] each element is streamed as it's produced
+  def <%= rpc[:method] %>(request)
+    raise Tonic::Rails::RpcError.new("<%= rpc[:name] %> is not implemented yet", code: :unimplemented)
+  end
+<% when "client" -%>
+  # @param requests [Enumerator<<%= ruby_module %>::<%= rpc[:name] %>Request>] yields messages as they arrive
+  # @return [<%= ruby_module %>::<%= rpc[:name] %>Response]
+  def <%= rpc[:method] %>(requests)
+    raise Tonic::Rails::RpcError.new("<%= rpc[:name] %> is not implemented yet", code: :unimplemented)
+  end
+<% else -%>
+  # @param requests [Enumerator<<%= ruby_module %>::<%= rpc[:name] %>Request>] yields messages as they arrive
+  # @return [Enumerable<<%= ruby_module %>::<%= rpc[:name] %>Response>]
+  def <%= rpc[:method] %>(requests)
+    raise Tonic::Rails::RpcError.new("<%= rpc[:name] %> is not implemented yet", code: :unimplemented)
+  end
+<% end -%>
+<% end -%>
+end

data/lib/generators/tonic_rails/service/templates/service.proto.tt

@@ -0,0 +1,16 @@
+syntax = "proto3";
+
+package <%= package %>;
+
+service <%= service_class %> {
+<% rpc_specs.each do |rpc| -%>
+  <%= proto_rpc_line(rpc) %>
+<% end -%>
+}
+<% rpc_specs.each do |rpc| %>
+message <%= rpc[:name] %>Request {
+}
+
+message <%= rpc[:name] %>Response {
+}
+<% end -%>

data/lib/generators/tonic_rails/service/templates/service_spec.rb.tt

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+require "tonic/rails/testing/rspec"
+
+RSpec.describe <%= service_class %> do
+<% rpc_specs.each_with_index do |rpc, i| -%>
+<% if i.positive? %>
+<% end -%>
+  describe "<%= rpc[:name] %>" do
+    it "is not implemented yet" do
+      request = <%= %w[client bidi].include?(rpc[:kind]) ? "[#{ruby_module}::#{rpc[:name]}Request.new]" : "#{ruby_module}::#{rpc[:name]}Request.new" %>
+      expect { Tonic::Rails::Testing.call(described_class, :<%= rpc[:name] %>, request) }.to raise_grpc_error(:unimplemented)
+    end
+  end
+<% end -%>
+end

data/lib/generators/tonic_rails/service/templates/service_test.rb.tt

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "tonic/rails/testing/minitest"
+
+class <%= service_class %>Test < ActiveSupport::TestCase
+  include Tonic::Rails::Testing::Assertions
+<% rpc_specs.each do |rpc| %>
+  test "<%= rpc[:name] %> is not implemented yet" do
+    request = <%= %w[client bidi].include?(rpc[:kind]) ? "[#{ruby_module}::#{rpc[:name]}Request.new]" : "#{ruby_module}::#{rpc[:name]}Request.new" %>
+    assert_grpc_error(:unimplemented) { Tonic::Rails::Testing.call(<%= service_class %>, :<%= rpc[:name] %>, request) }
+  end
+<% end -%>
+end

data/lib/tonic/rails/base.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "active_support/callbacks"
+require "active_support/rescuable"
 require "active_support/core_ext/class/attribute"
 require "active_support/core_ext/hash/keys"
 require "active_support/core_ext/string/inflections"
@@ -25,8 +27,17 @@ module Tonic
     # is set (fastest), or string-keyed Hashes by default.  Handlers may
     # return either a protobuf message or a Hash; streaming handlers
     # return any Enumerable of them.
+    #
+    # Like controllers, handlers get callbacks and exception mapping:
+    #
+    #   before_rpc :authenticate, except: :Health
+    #   rescue_from ActiveRecord::RecordNotFound, code: :not_found
+    #   rescue_from Pundit::NotAuthorizedError, with: :forbidden
     module Base
       def self.included(base)
+        base.include(ActiveSupport::Callbacks)
+        base.include(ActiveSupport::Rescuable)
+        base.define_callbacks(:rpc)
         base.extend(ClassMethods)
         base.class_attribute :grpc_service_name, instance_writer: false
         base.class_attribute :grpc_rpcs, instance_writer: false, default: {}
@@ -34,6 +45,20 @@ module Tonic
       end
 
       module ClassMethods
+        private
+
+        def add_rpc_callback(kind, methods, only, except, block)
+          only &&= rpc_name_matcher(only)
+          except &&= rpc_name_matcher(except)
+          condition = lambda do |handler|
+            name = handler.current_rpc.underscore
+            (only.nil? || only.include?(name)) && (except.nil? || !except.include?(name))
+          end
+          (methods + [block].compact).each { |callback| set_callback(:rpc, kind, callback, if: condition) }
+        end
+
+        public
+
         # @param name [String] fully-qualified service name, e.g. "shop.ProductService"
         def service(name)
           self.grpc_service_name = name.to_s
@@ -97,6 +122,51 @@ module Tonic
           end
         end
 
+        # Run a method or block before each RPC.  Raising (e.g. an RpcError)
+        # stops the call.  The decoded `request` is available.
+        # @param only [Symbol, String, Array] RPC names to apply to
+        # @param except [Symbol, String, Array] RPC names to skip
+        def before_rpc(*methods, only: nil, except: nil, &block)
+          add_rpc_callback(:before, methods, only, except, block)
+        end
+
+        # Run after each RPC that completes without raising (for streaming
+        # responses, after the last message is sent).
+        def after_rpc(*methods, only: nil, except: nil, &block)
+          add_rpc_callback(:after, methods, only, except, block)
+        end
+
+        # Wrap each RPC; the method or block must yield to run it.
+        def around_rpc(*methods, only: nil, except: nil, &block)
+          add_rpc_callback(:around, methods, only, except, block)
+        end
+
+        # Map exceptions raised during an RPC (including callbacks) to a
+        # gRPC status.  Same as ActiveSupport::Rescuable, plus a `code:`
+        # shorthand:
+        #
+        #   rescue_from ActiveRecord::RecordNotFound, code: :not_found
+        #   rescue_from Stale, code: :aborted, message: "please retry"
+        #   rescue_from Denied, with: :deny            # def deny(e) = raise RpcError...
+        #
+        # With `code:`, the client receives `message` (a String, or a Proc
+        # given the exception), defaulting to the exception's own message.
+        # Handlers given via `with:` or a block must raise an RpcError.
+        def rescue_from(*klasses, with: nil, code: nil, message: nil, &)
+          return super(*klasses, with: with, &) unless code
+
+          RpcError.normalize_code(code) # fail at definition time on typos
+          super(*klasses) do |exception|
+            text = message.respond_to?(:call) ? message.call(exception) : (message || exception.message)
+            raise RpcError.new(text, code: code)
+          end
+        end
+
+        # @api private
+        def rpc_name_matcher(names)
+          Array(names).map { |name| name.to_s.underscore }
+        end
+
         # @api private  Called by Server#register.
         def register_on(router)
           raise NotConfiguredError, "#{self} has no service name; call `service` or `rpc_service`" unless grpc_service_name
@@ -106,6 +176,18 @@ module Tonic
         end
       end
 
+      # The RPC being handled, as named in the .proto (e.g. "GetItem").
+      # @return [String]
+      attr_reader :current_rpc
+
+      # The client: address, and certificate with mutual TLS.
+      # @return [Tonic::Rails::Peer]
+      attr_reader :peer
+
+      # The decoded request: a message (or Hash), or for client-streaming
+      # RPCs an Enumerator of them.  Also passed to the handler method.
+      attr_reader :request
+
       # gRPC request metadata (lower-case header names).  Binary (`-bin`)
       # values are base64-encoded, as sent on the wire.
       # @return [Hash{String=>String}]
@@ -152,29 +234,46 @@ module Tonic
       # (`#push`) for server-streaming RPCs.
       # @return [String, nil] the encoded unary response, or nil when
       #   messages were streamed through `sender`
-      def call_rpc(rpc_name, metadata:, reader:, sender: nil, timeout_ms: nil)
+      def call_rpc(rpc_name, metadata:, reader:, sender: nil, timeout_ms: nil, peer: nil)
         spec = self.class.grpc_rpcs[rpc_name.to_s]
         raise RpcError.new("method not implemented", code: :unimplemented) unless spec
         raise RpcError.new("method #{rpc_name} not implemented", code: :unimplemented) unless respond_to?(spec[:handler])
 
+        @current_rpc = rpc_name.to_s
+        @peer = peer || Peer.new
         @grpc_metadata = metadata
         @grpc_sender = sender
         @grpc_headers_sent = false
         @grpc_deadline_at = timeout_ms && (Process.clock_gettime(Process::CLOCK_MONOTONIC) + (timeout_ms / 1000.0))
 
-        result = public_send(spec[:handler], build_request(reader, spec))
-        respond(result, spec, sender)
+        @request = build_request(reader, spec)
+        response = nil
+        run_callbacks(:rpc) { response = respond(public_send(spec[:handler], @request), spec, sender) }
+        response
       rescue RpcError
         raise
       rescue StandardError => e
-        Tonic::Rails.log_exception(e, "#{self.class}##{rpc_name}")
-        raise RpcError.new("internal error", code: :internal)
+        rescue_exception(e)
       ensure
         attach_trailing_metadata
       end
 
       private
 
+      # rescue_from handlers must raise; anything they don't handle (or a
+      # handler that returns normally) becomes a logged INTERNAL error.
+      def rescue_exception(exception)
+        if rescue_with_handler(exception)
+          Tonic::Rails.log_exception(
+            TypeError.new("rescue_from handler for #{exception.class} returned instead of raising an RpcError"),
+            "#{self.class}##{current_rpc}",
+          )
+        else
+          Tonic::Rails.log_exception(exception, "#{self.class}##{current_rpc}")
+        end
+        raise RpcError.new("internal error", code: :internal)
+      end
+
       def build_request(reader, spec)
         unless spec[:request_stream]
           return read_request(reader, spec) || raise(RpcError.new("missing request message", code: :invalid_argument))

data/lib/tonic/rails/configuration.rb

@@ -69,6 +69,17 @@ module Tonic
       # HTTP/2 PING interval and ack timeout, in seconds.  Defaults 15 / 5.
       attr_accessor :keepalive_interval, :keepalive_timeout
 
+      # Callable checked every `health_check_interval` seconds (inside the
+      # Rails executor).  While it returns false or raises, grpc.health.v1
+      # reports NOT_SERVING so readiness probes and load balancers route
+      # around this instance.  Default nil (always SERVING while up).
+      #
+      #   config.health_check = -> { ActiveRecord::Base.connection.active? }
+      attr_accessor :health_check
+
+      # Seconds between health checks.  Default 5.
+      attr_accessor :health_check_interval
+
       # Look handler classes up again on each request so code reloading
       # works.  The Railtie enables this when Rails reloading is on.
       attr_accessor :reload_handlers
@@ -94,6 +105,8 @@ module Tonic
         @keepalive_interval = 15
         @keepalive_timeout = 5
         @reload_handlers = false
+        @health_check = nil
+        @health_check_interval = 5
       end
 
       def tls?
@@ -113,15 +126,24 @@ module Tonic
         raise ArgumentError, "max_message_size must be at most 4 GiB" if max_message_size > 0xFFFF_FFFF
         raise ArgumentError, "tls_cert_path and tls_key_path must be set together" if tls_cert_path.nil? != tls_key_path.nil?
         raise ArgumentError, "tls_client_ca_path requires tls_cert_path and tls_key_path" if tls_client_ca_path && !tls?
-        unless interceptors.respond_to?(:each) && interceptors.all? { |i| i.respond_to?(:call) }
-          raise ArgumentError, "interceptors must be an Array of callables"
-        end
+
+        validate_callables!
 
         self
       end
 
       private
 
+      def validate_callables!
+        raise ArgumentError, "health_check must respond to #call" if health_check && !health_check.respond_to?(:call)
+        unless health_check_interval.is_a?(Numeric) && health_check_interval.positive?
+          raise ArgumentError, "health_check_interval must be a positive number, got #{health_check_interval.inspect}"
+        end
+        return if interceptors.respond_to?(:each) && interceptors.all? { |i| i.respond_to?(:call) }
+
+        raise ArgumentError, "interceptors must be an Array of callables"
+      end
+
       def positive_integer!(name)
         value = public_send(name)
         return if value.is_a?(Integer) && value.positive?

data/lib/tonic/rails/health.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Tonic
+  module Rails
+    # What grpc.health.v1 reports, per service ("" = the whole server).
+    #
+    # A service reports SERVING only while the app hasn't marked it
+    # NOT_SERVING (Server#not_serving!) *and* the optional
+    # `config.health_check` passes.  Neither overrides the other.
+    # @api private
+    class Health
+      def initialize(configuration, router)
+        @configuration = configuration
+        @router = router
+        @marks = {}
+        @check_passing = true
+        @native = nil
+        @checker = nil
+      end
+
+      def mark(services, serving)
+        names = services.empty? ? names_to_report : services.map(&:to_s)
+        names.each { |name| @marks[name] = serving }
+        publish(names)
+      end
+
+      # Start reporting through a running native server.
+      def attach(native)
+        @native = native
+        @check_passing = true
+        publish(names_to_report)
+        start_checker
+      end
+
+      # Stop the checker before shutdown flips everything NOT_SERVING, so
+      # a passing check can't flip it back.
+      def detach
+        stop_checker
+        @native = nil
+      end
+
+      private
+
+      def names_to_report
+        ["", *@router.service_names, *@marks.keys].uniq
+      end
+
+      def publish(names)
+        native = @native
+        return unless native
+
+        names.each { |name| native.set_health(name, @check_passing && @marks.fetch(name, true)) }
+      end
+
+      def start_checker
+        check = @configuration.health_check
+        return unless check
+
+        @wakeup = Thread::Queue.new
+        @checker = Thread.new do
+          Thread.current.name = "tonic-rails-health"
+          loop do
+            passing = run_check(check)
+            changed(passing) if passing != @check_passing
+            break if @wakeup.pop(timeout: @configuration.health_check_interval)
+          end
+        end
+      end
+
+      def stop_checker
+        return unless @checker
+
+        @wakeup << :stop
+        @checker.join(@configuration.drain_timeout.to_f + 5)
+        @checker = nil
+      end
+
+      def changed(passing)
+        @check_passing = passing
+        publish(names_to_report)
+        logger = @configuration.logger
+        return unless logger
+
+        if passing
+          logger.info("tonic-rails: health check passing; SERVING")
+        else
+          logger.warn("tonic-rails: health check failing; NOT_SERVING")
+        end
+      end
+
+      # Runs inside the Rails executor so database connections are returned.
+      def run_check(check)
+        result = if defined?(::Rails.application) && ::Rails.application
+          ::Rails.application.executor.wrap { check.call }
+        else
+          check.call
+        end
+        result ? true : false
+      rescue StandardError => e
+        Tonic::Rails.log_exception(e, "health check")
+        false
+      end
+    end
+  end
+end

data/lib/tonic/rails/peer.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Tonic
+  module Rails
+    # The client on the other end of an RPC, available in handlers as
+    # `peer`:
+    #
+    #   peer.address       # => "10.0.4.17:51234"
+    #   peer.ip            # => "10.0.4.17"
+    #   peer.certificate   # => OpenSSL::X509::Certificate, with mutual TLS
+    #   peer.certificate&.subject.to_s  # => "/CN=billing-service"
+    class Peer
+      # @return [String, nil] "ip:port" ("[ipv6]:port" for IPv6)
+      attr_reader :address
+
+      # @param address [String, nil]
+      # @param certificates [Array<String>] DER-encoded chain, leaf first
+      def initialize(address = nil, certificates = [])
+        @address = address
+        @certificate_ders = certificates
+      end
+
+      # @return [String, nil]
+      def ip
+        return unless address
+
+        host = address.rpartition(":").first
+        host.delete_prefix("[").delete_suffix("]")
+      end
+
+      # @return [Integer, nil]
+      def port
+        address && Integer(address.rpartition(":").last, exception: false)
+      end
+
+      # The client certificate presented over mutual TLS, or nil.
+      # @return [OpenSSL::X509::Certificate, nil]
+      def certificate
+        certificate_chain.first
+      end
+
+      # @return [Array<OpenSSL::X509::Certificate>] leaf first
+      def certificate_chain
+        @certificate_chain ||= begin
+          require "openssl"
+          @certificate_ders.map { |der| OpenSSL::X509::Certificate.new(der) }
+        end
+      end
+
+      # True when the client authenticated with a certificate.
+      def authenticated?
+        !@certificate_ders.empty?
+      end
+
+      def inspect
+        "#<#{self.class.name} #{address || 'unknown'}#{' (certificate)' if authenticated?}>"
+      end
+    end
+  end
+end

data/lib/tonic/rails/router.rb

@@ -38,6 +38,7 @@ module Tonic
           reader: call[:reader],
           sender: call[:sender],
           timeout_ms: call[:timeout_ms],
+          peer: Peer.new(call[:peer_address], call[:peer_certificates] || []),
         )
       end
 

data/lib/tonic/rails/server.rb

@@ -22,6 +22,7 @@ module Tonic
         @state = :stopped
         @stop_signal = nil
         @stop_requested = false
+        @health = Health.new(configuration, @router)
         @lock = Mutex.new
       end
 
@@ -58,6 +59,7 @@ module Tonic
           @native = build_native_server
           @native.start_server
           log_pump = spawn_log_pump
+          @health.attach(@native)
           @state = :running
 
           request_log = subscribe_request_logger
@@ -67,10 +69,12 @@ module Tonic
           yield self if block_given?
 
           wait_for_stop(workers)
+          @health.detach
           shutdown(workers)
         ensure
           ActiveSupport::Notifications.unsubscribe(request_log) if request_log
           previous_handlers&.each { |signal, handler| Signal.trap(signal, handler || "DEFAULT") }
+          @health.detach
           @native&.stop_server
           stop_log_pump(log_pump)
           @native = nil
@@ -91,6 +95,25 @@ module Tonic
         @state == :running
       end
 
+      # Mark the whole server, or the given services (fully-qualified
+      # names), SERVING in grpc.health.v1.  Takes effect immediately when
+      # running, otherwise when the server starts.
+      #
+      # With `config.health_check`, a service reports SERVING only while the
+      # check passes *and* it's marked serving here.
+      def serving!(*services)
+        @health.mark(services, true)
+        self
+      end
+
+      # Mark the whole server, or the given services, NOT_SERVING (e.g. for
+      # maintenance), so load balancers and readiness probes route around
+      # this instance.  Calls are still served.
+      def not_serving!(*services)
+        @health.mark(services, false)
+        self
+      end
+
       # @return [Hash{Symbol=>Integer}] request and connection counters
       def stats
         native = @native

data/lib/tonic/rails/tasks/tonic-rails.rake

@@ -27,7 +27,19 @@ namespace :tonic_rails do
     ruby_out = ENV.fetch("RUBY_OUT", "lib/grpc")
     protos = Dir.glob(File.join(proto_dir, "**", "*.proto"))
     abort "No .proto files found in #{proto_dir}/" if protos.empty?
-    abort "protoc not found on PATH. Install the Protocol Buffers compiler." unless system("protoc", "--version", out: File::NULL)
+    version = begin
+      IO.popen(%w[protoc --version], err: File::NULL, &:read)[/\d+(\.\d+)+/]
+    rescue SystemCallError
+      nil
+    end
+    abort "protoc not found on PATH. Install the Protocol Buffers compiler (22.0 or newer)." unless version
+    # protoc before 22 emits the Ruby DSL that google-protobuf 4 removed
+    # (`undefined method 'build' for DescriptorPool` at load time).
+    major = version.split(".").then { |parts| parts.first == "3" ? parts[1].to_i : parts.first.to_i }
+    if major < 22
+      abort "protoc #{version} is too old for google-protobuf 4: install protoc 22.0 or newer " \
+            "(distribution packages are often older; see https://github.com/protocolbuffers/protobuf/releases)."
+    end
 
     FileUtils.mkdir_p(ruby_out)
     sh "protoc", "--ruby_out=#{ruby_out}", "-I#{proto_dir}", *protos

data/lib/tonic/rails/testing/errors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Tonic
+  module Rails
+    module Testing
+      # Shared helpers for the RSpec matcher and Minitest assertions.
+      # @api private
+      module Errors
+        module_function
+
+        # Exceptions that carry a gRPC status: tonic-rails' own, and the
+        # official grpc gem client's, when it's loaded.
+        def classes
+          [Tonic::Rails::RpcError, (GRPC::BadStatus if defined?(GRPC::BadStatus))].compact
+        end
+
+        def status?(error)
+          classes.any? { |klass| error.is_a?(klass) }
+        end
+
+        # @return [Integer]
+        def code(error)
+          error.code
+        end
+
+        # @return [String] the status message the client sees.  The grpc
+        # gem keeps it in #details (its #message adds the code).
+        def message(error)
+          text = defined?(GRPC::BadStatus) && error.is_a?(GRPC::BadStatus) ? error.details.to_s : error.message
+          text.dup.force_encoding(Encoding::UTF_8)
+        end
+
+        def code_name(code)
+          Tonic::Rails::RpcError::CODE_NAMES.fetch(code, code)
+        end
+
+        def message_matches?(expected, actual)
+          expected.is_a?(Regexp) ? expected.match?(actual) : expected.to_s == actual
+        end
+
+        def describe(error)
+          "#{code_name(code(error)).to_s.upcase} (#{message(error).inspect})"
+        end
+      end
+    end
+  end
+end

data/lib/tonic/rails/testing/minitest.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "tonic/rails/testing"
+require "tonic/rails/testing/errors"
+
+module Tonic
+  module Rails
+    module Testing
+      # Minitest assertions for gRPC statuses:
+      #
+      #   class ItemServiceTest < ActiveSupport::TestCase
+      #     include Tonic::Rails::Testing::Assertions
+      #
+      #     test "missing items" do
+      #       error = assert_grpc_error(:not_found) { Tonic::Rails::Testing.call(ItemService, :GetItem, { id: 0 }) }
+      #       assert_match(/0/, error.message)
+      #     end
+      #   end
+      module Assertions
+        # Asserts the block raises a gRPC status (Tonic::Rails::RpcError or
+        # GRPC::BadStatus) with the given code and, optionally, message
+        # (String or Regexp).  Returns the error.
+        def assert_grpc_error(code = nil, message = nil, &)
+          errors = Testing::Errors
+          error = assert_raises(*errors.classes, &)
+          if code
+            expected = Tonic::Rails::RpcError.normalize_code(code)
+            assert_equal(
+              errors.code_name(expected), errors.code_name(errors.code(error)),
+              "Expected gRPC status #{errors.code_name(expected).to_s.upcase}, got #{errors.describe(error)}"
+            )
+          end
+          if message
+            assert(
+              errors.message_matches?(message, errors.message(error)),
+              "Expected gRPC message #{message.inspect}, got #{errors.message(error).inspect}",
+            )
+          end
+          error
+        end
+      end
+    end
+  end
+end

data/lib/tonic/rails/testing/rspec.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "rspec/expectations"
+require "tonic/rails/testing"
+require "tonic/rails/testing/errors"
+
+# Matches a block that ends with a gRPC status, raised as a
+# Tonic::Rails::RpcError (Testing.call) or a GRPC::BadStatus (the official
+# client):
+#
+#   expect { Tonic::Rails::Testing.call(ItemService, :GetItem, { id: 0 }) }
+#     .to raise_grpc_error(:not_found)
+#   expect { stub.get_item(request) }.to raise_grpc_error(:invalid_argument).with_message(/name/)
+#   expect { ... }.to raise_grpc_error   # any non-OK status
+RSpec::Matchers.define :raise_grpc_error do |expected_code = nil|
+  errors = Tonic::Rails::Testing::Errors
+
+  supports_block_expectations
+
+  chain(:with_message) { |message| @expected_message = message }
+
+  match do |block|
+    @expected = expected_code && Tonic::Rails::RpcError.normalize_code(expected_code)
+    begin
+      block.call
+      @error = nil
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      raise unless errors.status?(e)
+
+      @error = e
+    end
+    return false unless @error
+
+    (@expected.nil? || errors.code(@error) == @expected) &&
+      (!defined?(@expected_message) || errors.message_matches?(@expected_message, errors.message(@error)))
+  end
+
+  description do
+    text = +"raise a gRPC error"
+    text << " #{errors.code_name(@expected).to_s.upcase}" if @expected
+    text << " with message #{@expected_message.inspect}" if defined?(@expected_message)
+    text
+  end
+
+  failure_message do
+    actual = @error ? "got #{errors.describe(@error)}" : "nothing was raised"
+    "expected block to #{description}, but #{actual}"
+  end
+
+  failure_message_when_negated do
+    "expected block not to #{description}, but got #{errors.describe(@error)}"
+  end
+end

data/lib/tonic/rails/testing.rb

@@ -65,11 +65,12 @@ module Tonic
       #   request; an Array of them for client- and bidi-streaming RPCs
       # @param metadata [Hash{String=>String}]
       # @param timeout_ms [Integer, nil] simulated client deadline
+      # @param peer [Tonic::Rails::Peer, nil] simulated client (address, certificates)
       # @return [Google::Protobuf::AbstractMessage, Array] the response, or
       #   an Array of responses for server- and bidi-streaming RPCs
       # @raise [RpcError] when the handler ends the call with a status
-      def call(service_class, rpc_name, request, metadata: {}, timeout_ms: nil)
-        invoke(service_class, rpc_name, request, metadata: metadata, timeout_ms: timeout_ms).response
+      def call(service_class, rpc_name, request, metadata: {}, timeout_ms: nil, peer: nil)
+        invoke(service_class, rpc_name, request, metadata: metadata, timeout_ms: timeout_ms, peer: peer).response
       end
 
       # Like #call, but returns a Result with the response metadata too:
@@ -80,7 +81,7 @@ module Tonic
       #   result.trailers["x-cost-ms"]   # => "3"
       #
       # @return [Result]
-      def invoke(service_class, rpc_name, request, metadata: {}, timeout_ms: nil)
+      def invoke(service_class, rpc_name, request, metadata: {}, timeout_ms: nil, peer: nil)
         spec = service_class.grpc_rpcs.fetch(rpc_name.to_s) do
           raise ArgumentError, "#{service_class} has no RPC #{rpc_name}"
         end
@@ -95,6 +96,7 @@ module Tonic
           reader: reader,
           sender: sender,
           timeout_ms: timeout_ms,
+          peer: peer,
         )
 
         response = if spec[:response_stream]

data/lib/tonic/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Tonic
   module Rails
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/tonic-rails.rb

@@ -11,11 +11,13 @@ end
 
 require "tonic/rails/version"
 require "tonic/rails/metadata"
+require "tonic/rails/peer"
 require "tonic/rails/rpc_error"
 require "tonic/rails/configuration"
 require "tonic/rails/router"
 require "tonic/rails/instrumentation"
 require "tonic/rails/base"
+require "tonic/rails/health"
 require "tonic/rails/reflection"
 require "tonic/rails/server"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tonic-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: x86_64-linux-gnu
 authors:
 - Matt Tanous
@@ -54,6 +54,13 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- lib/generators/tonic_rails/install/install_generator.rb
+- lib/generators/tonic_rails/install/templates/tonic_rails.rb.tt
+- lib/generators/tonic_rails/service/service_generator.rb
+- lib/generators/tonic_rails/service/templates/handler.rb.tt
+- lib/generators/tonic_rails/service/templates/service.proto.tt
+- lib/generators/tonic_rails/service/templates/service_spec.rb.tt
+- lib/generators/tonic_rails/service/templates/service_test.rb.tt
 - lib/puma/plugin/tonic_rails.rb
 - lib/tonic-rails.rb
 - lib/tonic/rails/3.3/tonic_rails_native.so
@@ -61,8 +68,10 @@ files:
 - lib/tonic/rails/4.0/tonic_rails_native.so
 - lib/tonic/rails/base.rb
 - lib/tonic/rails/configuration.rb
+- lib/tonic/rails/health.rb
 - lib/tonic/rails/instrumentation.rb
 - lib/tonic/rails/metadata.rb
+- lib/tonic/rails/peer.rb
 - lib/tonic/rails/railtie.rb
 - lib/tonic/rails/reflection.rb
 - lib/tonic/rails/router.rb
@@ -70,6 +79,9 @@ files:
 - lib/tonic/rails/server.rb
 - lib/tonic/rails/tasks/tonic-rails.rake
 - lib/tonic/rails/testing.rb
+- lib/tonic/rails/testing/errors.rb
+- lib/tonic/rails/testing/minitest.rb
+- lib/tonic/rails/testing/rspec.rb
 - lib/tonic/rails/version.rb
 homepage: https://github.com/CodingAnarchy/tonic-rails
 licenses: