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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73ed3d0d421cd1cb77193b7d5025925cbe8737022553d28f7c95bd0d7ca2242a
-  data.tar.gz: e75d6f30c34e225b6668cdbe7f8072c22b5a5b1e53c782962f4327873cfcf7b2
+  metadata.gz: 06cf21277f2b5442bae8386269a576c89515959d2144d9d8ed3e171b24e73c7d
+  data.tar.gz: 9862766277deb1548e0e6e88d48e611746282d430578b198d1f81430e759cf69
 SHA512:
-  metadata.gz: d66dbcc4d4bd4721d007fd0ace7004fc2af5ae1c9f209c082e2004d38892fa96373c22375db9da6dbeae358d93b9a0f69c30ba7f3309f0a8bed3615dcb9c11a3
-  data.tar.gz: 209db51bbf3305ed9aeba24a9c407653f08397b875490d295e3ebccaf3667182869ee5a950fe78a747c3b7d3799f5ae879aa9453dc594fbbd8ddedca66bb3fa9
+  metadata.gz: 9a72581a9b168d58c71402037b41e0df2650dcad092fa1163b0bf738508da03d3db6babf9c0651b58636fe989be50431231176152b1e7ed894838871a8a706e5
+  data.tar.gz: 5397e3379da5008ccc472b4b3d6f3f88e649675e0290b271dde7a2cfeb1843f45287cbd4d0776750304d12bcb19179c7c2206ef0c05cd7af1744721e6d57c790

data/CHANGELOG.md

@@ -7,6 +7,47 @@ minor versions may contain breaking changes.
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-11
+
+### Added
+
+- gRPC-Web: `config.grpc_web = true` serves browser clients (unary and
+  server-streaming RPCs, binary and text encodings) without a proxy, on the
+  same port as native gRPC, with CORS via `grpc_web_origins`,
+  `grpc_web_allowed_headers` and `grpc_web_exposed_headers`. Closes #22.
+
+## [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 +125,8 @@ 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.4.0...HEAD
+[0.4.0]: https://github.com/CodingAnarchy/tonic-rails/compare/v0.3.0...v0.4.0
+[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
@@ -299,6 +363,44 @@ Tonic::Rails.configure do |config|
 end
 ```
 
+## Browser clients (gRPC-Web)
+
+Browsers can't speak native gRPC, but they can speak
+[gRPC-Web](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-WEB.md).
+Turn it on and your existing handlers serve web frontends directly, with
+no Envoy or other proxy:
+
+```ruby
+Tonic::Rails.configure do |config|
+  config.grpc_web = true
+  config.grpc_web_origins = ["https://app.example.com"]   # CORS; omit for same-origin only
+  config.grpc_web_exposed_headers = %w[x-request-id]     # response metadata browsers may read
+end
+```
+
+Then call it from the browser with any gRPC-Web client, for example
+[Connect](https://connectrpc.com/docs/web/using-clients):
+
+```ts
+import { createClient } from "@connectrpc/connect";
+import { createGrpcWebTransport } from "@connectrpc/connect-web";
+import { ItemService } from "./gen/demo/v1/items_pb";
+
+const client = createClient(ItemService, createGrpcWebTransport({ baseUrl: "https://api.example.com" }));
+const item = await client.getItem({ id: 1n });
+```
+
+- Unary and server-streaming RPCs work; browsers can't do client or
+  bidirectional streaming.
+- Errors, response headers and trailers reach the browser as usual.
+- Native gRPC clients keep working on the same port. Enabling gRPC-Web
+  also accepts HTTP/1.1, which browsers use without TLS; over HTTPS they
+  negotiate HTTP/2.
+- `grpc_web_origins` sets CORS: listed origins may call with credentials
+  (cookies); `"*"` allows any origin without credentials (logged as a
+  warning). `grpc_web_allowed_headers` adds request headers beyond the
+  standard ones (`authorization` is already allowed).
+
 ## Testing handlers
 
 `Tonic::Rails::Testing` calls a handler in-process, with real protobuf
@@ -322,6 +424,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 +479,11 @@ 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 |
+| `grpc_web` | `false` | Serve gRPC-Web for browser clients (see [Browser clients](#browser-clients-grpc-web)) |
+| `grpc_web_origins` | `[]` | Browser origins allowed via CORS; `"*"` for any (no credentials) |
+| `grpc_web_allowed_headers`, `grpc_web_exposed_headers` | `[]` | Extra CORS request / response headers |
+| `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 +530,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