tonic-rails 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6c9da1fa1dde14dab1bd46c64821154a392dd9e5b5bc31faf396cf8e51dfc28
-  data.tar.gz: f0988c4f232fb3016b205d094ea0970085e7515f71f6845e55bd8bc6d43c7d70
+  metadata.gz: c1578d591791ff33ce8365ae3fe5b5a6bb5dfbac8759e4f9762c7c511e71057a
+  data.tar.gz: e23782ccd2cf964d5db2cf25c98547780525e20d7880f0dab85a0c4c956b45cd
 SHA512:
-  metadata.gz: 82a6eb4a8da4daaf1f91e6ead904b1223c13cc5b02f90e9bebf810ca7fc25bd71cb30cce07e539fde05b81b12fd89e84d540fc5aa5a22d38d7697aacb746a1c0
-  data.tar.gz: 87dbd3f3abcbdefd3d6f47ad8b93ea992672efe67c643bcf47e75e255e920983ab6695ecfea8eb4273db390f57e6de419b9c369ad5067f0e07a0d086a7c9e218
+  metadata.gz: 616f736a4e29cd3fcf8fd4297d6159d9abb145f3973b27a08f6f2c153bf7f5ae87422870ef304dab552e62f8ef7b3037716432c89bfd5d12088ef97e1ae58166
+  data.tar.gz: 07a9749e9188700473883761291731a3f0b947bcdf4d986cd55df81dcb658229863149cfda1174a186a0cfe321e8e09810b7c1113232fefdc38c0ca2f1bba962

data/CHANGELOG.md

@@ -7,7 +7,75 @@ minor versions may contain breaking changes.
 
 ## [Unreleased]
 
-## [0.1.0]
+## [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
+
+- Instrumentation: every RPC publishes a `process_rpc.tonic_rails`
+  ActiveSupport::Notifications event (path, service, rpc, metadata, status,
+  code) for APM agents, OpenTelemetry and custom subscribers. With no
+  subscribers it costs nothing measurable.
+- Response metadata: handlers set `response_metadata` (headers) and
+  `trailing_metadata` (trailers, sent on success or failure).
+- Rich errors: `RpcError.new(..., metadata:, details:)` sends trailing
+  metadata and a `google.rpc.Status` with packed details in
+  `grpc-status-details-bin`, which official gRPC clients decode.
+- Puma plugin: `plugin :tonic_rails` in `config/puma.rb` runs the gRPC
+  server as a child process of Puma, in single and cluster mode, with
+  graceful stop and restart, and a shutdown if either side dies.
+- Windows: precompiled `x64-mingw-ucrt` gems, tested in CI.
+- `Tonic::Rails::Testing.invoke` returns the response together with its
+  headers and trailers.
+
+### Changed
+
+- Response headers are sent with the handler's first output instead of
+  before the handler runs, so handlers can set them. The client deadline
+  applies while waiting.
+- `log_requests` logs one line per RPC through the configured (Rails)
+  logger instead of stderr.
+- Transport events from the native extension (rejected calls, expired
+  deadlines, refused connections, faults) go through the configured (Rails)
+  logger with severities instead of stderr. Handler outcomes, such as a
+  `NOT_FOUND` raised by a handler, are no longer logged by the transport;
+  use `log_requests` or the instrumentation event for those.
+- `Server#stop` signals shutdown through a queue instead of a pipe, so
+  signal handling works the same on every platform.
+- Dependencies: magnus 0.9, google-protobuf 4.36.
+
+## [0.1.0] - 2026-10-10
 
 First public release.
 
@@ -48,5 +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.1.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/Cargo.lock

@@ -469,9 +469,9 @@ checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6"
 
 [[package]]
 name = "magnus"
-version = "0.8.3"
+version = "0.9.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "86a4f30dd400bf26769435129d7ecc529f56e3d45012ee6c394d6dbff3296bf9"
+checksum = "b9068710e00d21be762edca59b9c4c8946dbdb29820d4f76ad559afea07982c9"
 dependencies = [
  "magnus-macros",
  "rb-sys",
@@ -481,9 +481,9 @@ dependencies = [
 
 [[package]]
 name = "magnus-macros"
-version = "0.8.0"
+version = "0.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "47607461fd8e1513cb4f2076c197d8092d921a1ea75bd08af97398f593751892"
+checksum = "9dafde2eeb66f090e0f326112323eb8324b12cb32b5d1210e541d3df6b0ce77e"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -1023,7 +1023,7 @@ dependencies = [
 
 [[package]]
 name = "tonic_rails_native"
-version = "0.1.0"
+version = "0.3.0"
 dependencies = [
  "axum",
  "bytes",

data/README.md

@@ -30,10 +30,11 @@ end
 
 ## Why tonic-rails
 
-- **Fast where it counts.** Transport overhead is small: an empty RPC
-  runs at roughly 75–80% of a pure-Rust tonic server's throughput. I/O-bound
-  handlers scale with dispatch threads because Ruby releases the GVL
-  while waiting. See [PERF.md](PERF.md).
+- **Fast where it counts.** Inside a Rails app, light RPCs ran at 5–6×
+  the throughput of an equivalent Rails JSON endpoint and 1.4–3× the
+  official `grpc` gem, and server streaming at 4–7× the `grpc` gem.
+  Handlers dominated by slow queries or heavy object building see smaller
+  gains. See [PERF.md](PERF.md).
 - **All four RPC kinds.** Unary, server streaming, client streaming and
   bidirectional streaming, with backpressure in both directions.
 - **Production defaults.** Graceful draining on SIGTERM, health checks
@@ -44,7 +45,7 @@ end
   Reflection is off unless you turn it on. TLS problems stop the server
   instead of silently falling back to plaintext.
 - **No Rust toolchain needed** on the platforms we ship precompiled gems
-  for (Linux and macOS, x86_64 and arm64).
+  for: Linux and macOS (x86_64 and arm64) and Windows (x64).
 
 ## Installation
 
@@ -59,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
@@ -139,7 +161,8 @@ bin/rails tonic_rails:routes   # lists registered methods
 ```
 
 Run it as its own process (a separate Procfile entry, container or
-Kubernetes deployment) next to your web server.
+Kubernetes deployment) next to your web server, or let Puma run it for
+you (see [Running with Puma](#running-with-puma)).
 
 The [example app](example/) is a complete, runnable version of all of the
 above.
@@ -234,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
@@ -248,6 +314,39 @@ end
 When the deadline passes, the client gets `DEADLINE_EXCEEDED` right away;
 check `deadline_exceeded?` in long loops to stop wasted work.
 
+### Response metadata
+
+Set response headers and trailers from a handler:
+
+```ruby
+def get_item(request)
+  response_metadata["x-cache"] = "hit"           # headers
+  trailing_metadata["x-cost-ms"] = "3"           # trailers, sent with the status
+  response_metadata["x-trace-bin"] = trace_bytes # -bin names take binary values
+  Demo::V1::Item.new(id: request.id)
+end
+```
+
+For streaming responses, set headers before the first message is sent.
+Trailers are sent whether the call succeeds or fails.
+
+### Rich errors
+
+`RpcError` can carry trailing metadata and
+[rich error details](https://grpc.io/docs/guides/error/#richer-error-model):
+protobuf messages packed into a `google.rpc.Status` in the standard
+`grpc-status-details-bin` trailer, which official gRPC clients decode for
+you.
+
+```ruby
+raise Tonic::Rails::RpcError.new(
+  "invalid item",
+  code: :invalid_argument,
+  metadata: { "x-request-id" => request_id },
+  details: [Google::Rpc::BadRequest.new(field_violations: violations)],
+)
+```
+
 ### Interceptors
 
 Interceptors wrap every call, outermost first. Call `next_call` to
@@ -280,6 +379,35 @@ expect { Tonic::Rails::Testing.call(ItemService, :GetItem, { id: 0 }) }
 
 # Streaming: pass an Array of requests, get an Array of responses
 Tonic::Rails::Testing.call(ItemService, :ImportItems, [{ name: "a" }, { name: "b" }])
+
+# Response metadata
+result = Tonic::Rails::Testing.invoke(ItemService, :GetItem, { id: 1 })
+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
@@ -313,11 +441,13 @@ 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) |
-| `log_requests` | `false` | Log every call to stderr (errors are always logged) |
-| `auto_start` | `false` | Start inside `rails server` (see below) |
+| `log_requests` | `false` | Log one line per call through `logger` (unexpected exceptions are always logged) |
+| `auto_start` | `false` | Start in a thread of `rails server`; for development (see [auto_start](#auto_start)) |
 
 ### Sizing threads
 
@@ -328,31 +458,92 @@ concurrency your I/O needs, size the database pool to match, and add
 processes for CPU-heavy services: the listener uses `SO_REUSEPORT`, so
 several processes can bind the same port.
 
+### Running with Puma
+
+Add the plugin to `config/puma.rb`:
+
+```ruby
+plugin :tonic_rails
+```
+
+Puma then runs the gRPC server as one child process, in single and cluster
+mode alike, so gRPC gets its own process and GVL instead of competing with
+web workers. It starts after Puma boots and drains gracefully when Puma
+stops or restarts. If the gRPC process dies, Puma shuts down too, so your
+supervisor restarts both. It works with `rails server`, plain `puma`, and
+`preload_app!`. (Not on Windows, which has no `fork()`: run
+`tonic_rails:serve` as its own process there.)
+
+For larger deployments, a dedicated `bin/rails tonic_rails:serve` process
+(scaled separately) is still the most flexible option.
+
 ### auto_start
 
 `auto_start = true` starts the gRPC server in a background thread of
 `rails server` (never in consoles, rake tasks or tests). It's handy in
-development. In production prefer a dedicated `tonic_rails:serve`
-process: forking servers such as Puma in cluster mode would need to
-start one per worker.
+development; in production use the Puma plugin or a dedicated process.
+Don't combine it with the plugin.
 
 ## Operations
 
 - **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.
 - **Load shedding.** When every dispatch thread is busy and the queue is
   full, new calls fail fast with `RESOURCE_EXHAUSTED` instead of piling up.
+- **Instrumentation.** Every RPC publishes a `process_rpc.tonic_rails`
+  event through `ActiveSupport::Notifications`, so APM agents,
+  OpenTelemetry and your own subscribers can trace calls. See
+  [Instrumentation](#instrumentation).
+- **Logs.** Everything goes through your (Rails) logger. With
+  `log_requests = true`, each RPC logs one line, e.g.
+  `gRPC /demo.v1.ItemService/GetItem OK in 1.4ms`. Calls the transport
+  rejects before reaching Ruby (unknown methods, a full queue, expired
+  deadlines, oversized messages, refused connections) are always logged,
+  at info for client-caused problems, warn for overload and error for faults.
 - **Stats.** `Tonic::Rails.server.stats` returns counters for totals,
   successes, errors, cancellations, deadline and resource errors, active
   connections and queued calls.
 - **Reflection.** Turn on `reflection` in development to use
   [grpcurl](https://github.com/fullstorydev/grpcurl) without proto files.
 
+## Instrumentation
+
+Every RPC is wrapped in an `ActiveSupport::Notifications` event, inside the
+Rails executor, so subscribers see the same context as your handler:
+
+```ruby
+ActiveSupport::Notifications.subscribe("process_rpc.tonic_rails") do |event|
+  event.payload[:path]      # "/demo.v1.ItemService/GetItem"
+  event.payload[:service]   # "demo.v1.ItemService"
+  event.payload[:rpc]       # "GetItem"
+  event.payload[:metadata]  # request metadata
+  event.payload[:status]    # :ok, :not_found, :internal, ...
+  event.payload[:code]      # numeric gRPC status
+  event.duration            # milliseconds
+end
+```
+
+When a call fails, `event.payload[:exception_object]` is the
+`Tonic::Rails::RpcError` sent to the client. If a handler raised something
+unexpected, that error's `cause` is the original exception.
+
 ## How it works
 
 ```

data/ext/tonic_rails_native/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tonic_rails_native"
-version = "0.1.0"
+version = "0.3.0"
 edition = "2024"
 rust-version = "1.88"
 publish = false
@@ -23,7 +23,7 @@ crate-type = ["cdylib"]
 #
 # socket2 enables SO_REUSEPORT for multi-process (Puma worker) scaling.
 [dependencies]
-magnus = "0.8"
+magnus = "0.9"
 rb-sys = "0.9"
 tonic = { version = "0.14", default-features = false, features = ["transport", "router", "server", "tls-ring"] }
 tonic-reflection = { version = "0.14", default-features = false, features = ["server"] }