tonic-rails 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 234f197083161b48c0fa820f8e9e8bb20138208c131e8467279cd40d9b73d872
-  data.tar.gz: a5ec7ea58b4325c881045c7550468a19de879b7119212e212500c4632e581f56
+  metadata.gz: 338a8abe3329b9c34aeb471e4b1b152696ae0a371ded6e375f2d42807775a8a2
+  data.tar.gz: 3ed3aedfabbde45d5ef7ed7598a2937f88232a0becaf93a0e3f17a9f8073503c
 SHA512:
-  metadata.gz: 59c579e49bfc33f7f551ba522823fac67e253d939723c0fcdf4368560f558094b519a1339ca325d81cd2e06fa3dd51e1b7486b790b11da711ab04a24bfe2d375
-  data.tar.gz: 229844b0f0d86b85f0545c715bb04c70148ecff829ea699283d5bf0a624aab91e788224af557ad513db559b3f42ed9c381350f0dd00238e0c78f0be67731437f
+  metadata.gz: eefe02d7dbed4dae8bf2d9af2743823877f8468d933b406f0e76f2b848de789c9dee0a95778804186c025aeffc60ea24dc28edc6f5645100e5c7d25dfd1c93ec
+  data.tar.gz: 2b9eaa3a25ca8fe7091bb761ddaf86a15564f187252045a81a24e8ce96f50da50479f2b2af108ccd5804c3c5b4ee3055000f54624fdc8f97a0aa223d8df421bd

data/CHANGELOG.md

@@ -7,6 +7,47 @@ minor versions may contain breaking changes.
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-10-11
+
+### Added
+
+- Client: opt-in retries, per client or per call (`retries: true` or a
+  Hash of `max_attempts`, `codes`, `initial_backoff`, `max_backoff` and
+  `multiplier`), following gRPC's retry design. Only calls the server
+  never started on are retried: a failed connection, or a status sent
+  without response headers. Waits are random with exponential caps, stop
+  before the deadline and follow `grpc-retry-pushback-ms`. Each retry is
+  logged, and `request_rpc.tonic_rails` reports `:attempts`. Closes #39.
+
+### Changed
+
+- The server answers calls it turns away before a handler runs (shutting
+  down, dispatch queue full, malformed requests) with a Trailers-Only
+  response: the status in the headers and no body. Clients that follow
+  gRPC's retry rules can tell those calls never started and retry them
+  safely.
+
+## [0.6.0] - 2026-10-11
+
+### Added
+
+- Client: `Tonic::Rails::Client` makes unary calls to other gRPC
+  services without the grpc gem. Stubs come from the descriptors that
+  `tonic_rails:compile_protos` generates. Calls take deadlines (and
+  default to the deadline of the RPC being handled), send metadata,
+  return headers and trailers with `return_call: true`, and raise
+  `RpcError` with rich details. TLS uses the system's root certificates,
+  a custom CA or mutual TLS. Clients keep working across `fork` with no
+  hooks, and `Timeout` and `Thread#raise` interrupt calls. Each call
+  publishes a `request_rpc.tonic_rails` event. Closes #37.
+- Client: server-streaming calls. The stub method returns a stream that
+  yields each message as it arrives. A slow reader holds the server back
+  through HTTP/2 flow control, and stopping early (`break`, `first(n)`,
+  an exception) cancels the call. The deadline covers the whole stream,
+  an error partway through raises `RpcError` after the messages before
+  it, and `headers` and `trailers` are available once the stream ends.
+  Closes #38.
+
 ## [0.5.0] - 2026-10-11
 
 ### Added
@@ -145,7 +186,9 @@ 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.5.0...HEAD
+[Unreleased]: https://github.com/CodingAnarchy/tonic-rails/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/CodingAnarchy/tonic-rails/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/CodingAnarchy/tonic-rails/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/CodingAnarchy/tonic-rails/compare/v0.4.0...v0.5.0
 [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

data/Cargo.lock

@@ -155,6 +155,22 @@ dependencies = [
  "libloading",
 ]
 
+[[package]]
+name = "core-foundation"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b2a6cd9ae233e7f62ba4e9353e81a88df7fc8a5987b8d445b4d90c879bd156f6"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
+[[package]]
+name = "core-foundation-sys"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
+
 [[package]]
 name = "crc32fast"
 version = "1.5.2"
@@ -551,6 +567,12 @@ version = "1.21.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
+[[package]]
+name = "openssl-probe"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7c87def4c32ab89d880effc9e097653c8da5d6ef28e6b539d313baaacfbafcbe"
+
 [[package]]
 name = "parking_lot"
 version = "0.12.5"
@@ -759,6 +781,18 @@ dependencies = [
  "zeroize",
 ]
 
+[[package]]
+name = "rustls-native-certs"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dab5152771c58876a2146916e53e35057e1a4dfa2b9df0f0305b07f611fdea4d"
+dependencies = [
+ "openssl-probe",
+ "rustls-pki-types",
+ "schannel",
+ "security-framework",
+]
+
 [[package]]
 name = "rustls-pki-types"
 version = "1.15.1"
@@ -779,12 +813,44 @@ dependencies = [
  "untrusted",
 ]
 
+[[package]]
+name = "schannel"
+version = "0.1.29"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "91c1b7e4904c873ef0710c1f407dde2e6287de2bebc1bbbf7d430bb7cbffd939"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "scopeguard"
 version = "1.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 
+[[package]]
+name = "security-framework"
+version = "3.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d"
+dependencies = [
+ "bitflags",
+ "core-foundation",
+ "core-foundation-sys",
+ "libc",
+ "security-framework-sys",
+]
+
+[[package]]
+name = "security-framework-sys"
+version = "2.17.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2691df843ecc5d231c0b14ece2acc3efb62c0a398c7e1d875f3983ce020e3"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
 [[package]]
 name = "seq-macro"
 version = "0.3.6"
@@ -1041,9 +1107,10 @@ dependencies = [
 
 [[package]]
 name = "tonic_rails_native"
-version = "0.5.0"
+version = "0.7.0"
 dependencies = [
  "axum",
+ "base64",
  "bytes",
  "crossbeam-channel",
  "flate2",
@@ -1055,6 +1122,7 @@ dependencies = [
  "prost",
  "prost-types",
  "rb-sys",
+ "rustls-native-certs",
  "socket2",
  "tokio",
  "tokio-stream",

data/README.md

@@ -44,6 +44,10 @@ end
   INTERNAL error (the details go to your logs and `Rails.error`).
   Reflection is off unless you turn it on. TLS problems stop the server
   instead of silently falling back to plaintext.
+- **A client too.** Make unary and server-streaming calls to other gRPC
+  services, with deadlines that follow your handler's, without the
+  `grpc` gem and its fork crashes. See
+  [Calling other services](#calling-other-services).
 - **No Rust toolchain needed** on the platforms we ship precompiled gems
   for: Linux and macOS (x86_64 and arm64) and Windows (x64).
 
@@ -401,6 +405,261 @@ const item = await client.getItem({ id: 1n });
   warning). `grpc_web_allowed_headers` adds request headers beyond the
   standard ones (`authorization` is already allowed).
 
+## Calling other services
+
+tonic-rails includes a client for unary and server-streaming calls to
+other gRPC services, so
+an app that serves gRPC (or just calls it) doesn't need the `grpc` gem.
+It runs on the same Rust stack as the server, and it keeps working after
+`fork`. That matters because the `grpc` gem crashes or hangs in forked
+processes (Puma with `preload_app!`, Sidekiq swarm, Resque) unless you
+opt in to its Linux-only fork support and call `GRPC.prefork` and
+friends around every fork yourself.
+
+Create a client once and share it; it holds one HTTP/2 connection and is
+safe to use from any thread:
+
+```ruby
+# config/initializers/grpc_clients.rb
+ITEMS = Tonic::Rails::Client.new("items.internal:50051", deadline: 2)
+```
+
+Then get a stub for a service and call its methods, named in snake_case:
+
+```ruby
+items = ITEMS.stub("demo.v1.ItemService")
+
+item = items.get_item(Demo::V1::GetItemRequest.new(id: 1))  # a message
+item = items.get_item(id: 1)                                 # or its fields
+item = items.get_item({ id: 1 }, deadline: 0.5, metadata: { "x-request-id" => request.request_id })
+```
+
+Stubs are built from the protobuf descriptors in the `_pb.rb` files that
+`tonic_rails:compile_protos` generates, the same ones your handlers use.
+There's no `grpc_tools_ruby_protoc` step and no `_services_pb.rb`.
+Responses are protobuf messages.
+
+### Server streaming
+
+A server-streaming method returns a stream you read with `each`, or any
+Enumerable method:
+
+```ruby
+items.list_items(category: "books").each { |item| index(item) }
+items.list_items(category: "books").first(10)  # stops after ten
+```
+
+- Nothing is sent until you start reading. Then each message is yielded
+  as it arrives, not when the stream ends.
+- Stopping early, with `break`, `first(n)` or an exception, cancels the
+  call, and the server sees it cancelled.
+- A slow reader holds the server back. A few messages are read ahead,
+  and HTTP/2 flow control stops the server after a couple of megabytes,
+  so a fast server can't fill your memory.
+- If the server fails partway through, you get every message it sent
+  first, then `Tonic::Rails::RpcError`.
+- Once the stream has ended, `headers` and `trailers` return its
+  metadata.
+- A stream can be read once. Call the method again for a new one.
+
+Client and bidirectional streaming aren't supported yet; their stub
+methods raise `NotImplementedError`.
+
+### Deadlines
+
+- `deadline:` on a call is seconds from now (`0.5`) or a `Time`. Without
+  one, the client's `deadline:` applies.
+- **Inside a handler, outgoing calls default to the time left on the
+  handler's own deadline**, so a service that's out of time doesn't keep
+  its dependencies working on an answer nobody will read. If the client
+  also has a default deadline, the earlier of the two wins. A deadline on
+  the call itself always wins.
+- When a deadline passes, the call raises `DEADLINE_EXCEEDED`, and the
+  server sees the call cancelled.
+- A stream's deadline covers the whole stream, including the time your
+  block spends on each message. It's set when you call the method, so a
+  stream read later still keeps the handler's deadline.
+
+Set a deadline. Without one, a call to a server that never answers waits
+forever (or until `Timeout` interrupts it, which also works).
+
+### Errors
+
+A call that fails raises `Tonic::Rails::RpcError`, the same class your
+handlers raise:
+
+```ruby
+begin
+  items.get_item(id: 1)
+rescue Tonic::Rails::RpcError => e
+  e.code_name  # :not_found, :unavailable, :deadline_exceeded, ...
+  e.message    # the server's status message
+  e.details    # rich error details (google.rpc.Status), as messages
+  e.metadata   # trailing metadata
+end
+```
+
+Rich error details come back as their message class when its `_pb.rb` is
+loaded, and as `Google::Protobuf::Any` otherwise. A server that can't be
+reached raises `UNAVAILABLE`.
+
+If a handler lets the error propagate, its caller receives the same
+status, message, details and trailing metadata. Rescue it and raise your
+own error when those are internal.
+
+### Retries
+
+Retries are off unless you turn them on, for a client or a single call:
+
+```ruby
+ITEMS = Tonic::Rails::Client.new("items.internal:50051", deadline: 2, retries: true)
+
+items.get_item({ id: 1 }, retries: false)                    # not this call
+items.get_item({ id: 1 }, retries: { max_attempts: 5 })      # or differently
+```
+
+`retries: true` tries a call up to 3 times when it fails with
+`UNAVAILABLE`. A Hash changes any of these:
+
+| Field | Default | |
+|---|---|---|
+| `max_attempts` | 3 | attempts in all, from 2 to 5 |
+| `codes` | `[:unavailable]` | status codes worth retrying |
+| `initial_backoff` | 0.1 | seconds; the cap on the first wait |
+| `max_backoff` | 1 | seconds; the cap on any wait |
+| `multiplier` | 2 | how much the cap grows per attempt |
+
+The rules come from gRPC's own retry design, so they avoid the usual
+mistakes of a hand-written retry loop:
+
+- **A call is retried only if the server never started on it.** That
+  means the connection failed (refused, reset, a pod restarting), or the
+  server answered with only a status and no response headers. Servers do
+  that when they turn a call away before any handler runs: a
+  tonic-rails server that's shutting down or whose queue is full, or a
+  proxy with no healthy backend. Once response headers arrive, the call
+  is never repeated, even if it then fails with a code you listed.
+- **Waits are random.** Each one is anywhere from zero up to a cap that
+  starts at `initial_backoff` and grows by `multiplier` per attempt, up to
+  `max_backoff`. Clients that failed together don't retry together.
+- **The deadline covers every attempt.** If the next attempt couldn't
+  start before the deadline, the client stops and raises the last
+  failure.
+- **The server can steer.** A `grpc-retry-pushback-ms` trailer sets the
+  wait, and a negative one stops retries.
+- A server stream is retried only before its first message.
+
+Which calls are safe to retry? With the default `[:unavailable]`, nearly
+all of them. By gRPC convention, `UNAVAILABLE` means the call can be tried
+again, and from a tonic-rails server it's retried only when no handler
+ran. For a tonic-rails server, `:resource_exhausted` is worth adding too:
+a full dispatch queue returns it before any handler runs.
+
+Take more care with codes a handler might raise after doing some work,
+like `:aborted`. A tonic-rails server sends headers before it runs a
+handler, so those calls still won't be retried. Other servers may answer
+with only a status after a handler ran, so list those codes only for
+methods that are safe to run twice.
+
+Each retry is logged as a warning, through the client's `logger:` (by
+default `Tonic::Rails.configuration.logger`, which is the Rails logger in
+a Rails app):
+
+```
+tonic-rails: /demo.v1.ItemService/GetItem failed with UNAVAILABLE: ... (attempt 1 of 3); retrying in 64ms
+```
+
+### Metadata
+
+`metadata:` on a call, and on the client for every call, works like
+response metadata in handlers: `-bin` names take binary values. To read
+what the server sent back, pass `return_call: true`:
+
+```ruby
+call = items.get_item({ id: 1 }, return_call: true)
+call.response   # the message
+call.headers    # response headers, -bin values decoded
+call.trailers   # trailing metadata
+```
+
+### TLS
+
+TLS is on unless you turn it off, and plaintext needs an explicit
+`tls: false`:
+
+```ruby
+Tonic::Rails::Client.new("items.internal:50051")                           # system root certificates
+Tonic::Rails::Client.new("items.internal:50051", tls_ca_path: "ca.pem")    # your own CA instead
+Tonic::Rails::Client.new("items.internal:50051", tls_ca_path: "ca.pem",
+                         tls_cert_path: "client.pem", tls_key_path: "client.key")  # mutual TLS
+Tonic::Rails::Client.new("localhost:50051", tls: false)                    # plaintext
+```
+
+`tls_server_name:` checks the server's certificate against another name
+than the host you connect to. Unreadable certificates or keys raise when
+the client is created, not on the first call.
+
+### Options
+
+| Option | Default | |
+|---|---|---|
+| `tls` | `true` | `false` for plaintext |
+| `tls_ca_path` | system roots | CA certificates (PEM) to trust instead |
+| `tls_cert_path`, `tls_key_path` | none | client certificate and key (PEM), for mutual TLS |
+| `tls_server_name` | the host | name to verify the server's certificate against |
+| `deadline` | none | seconds each call may take, unless the call sets its own |
+| `metadata` | `{}` | sent with every call |
+| `max_message_size` | 4 MiB | largest message sent or received |
+| `connect_timeout` | 5 | seconds to wait for a connection |
+| `retries` | `false` | retry calls the server never started on; see [Retries](#retries) |
+| `logger` | `Tonic::Rails.configuration.logger` | where retries are logged |
+
+### Fork safety
+
+A client created before `fork` works in both processes, on Linux and
+macOS, with nothing to call. Each process opens its own connection on
+its first call, and a child never touches the threads or sockets it
+inherited from its parent. Create clients in initializers, before Puma or
+Sidekiq forks, and use them anywhere.
+
+On macOS, also create the first client that uses the system's root
+certificates before forking. Loading them goes through macOS's security
+APIs, which abort in a process forked from a multi-threaded one. Loaded
+once, they're kept and inherited, so clients created later in children
+are fine. Linux has no such limit.
+
+### Migrating from the grpc gem
+
+Call sites barely change; how you build the stub does:
+
+```ruby
+# Before: grpc gem
+stub = Demo::V1::ItemService::Stub.new("items.internal:50051", GRPC::Core::ChannelCredentials.new)
+item = stub.get_item(Demo::V1::GetItemRequest.new(id: 1), deadline: Time.now + 2, metadata: { "x-id" => "1" })
+
+# After: tonic-rails
+stub = Tonic::Rails::Client.new("items.internal:50051").stub("demo.v1.ItemService")
+item = stub.get_item(Demo::V1::GetItemRequest.new(id: 1), deadline: Time.now + 2, metadata: { "x-id" => "1" })
+```
+
+- `stub` also accepts the grpc gem's service class
+  (`Demo::V1::ItemService::Service`), which helps while both gems are
+  installed.
+- `deadline:` takes a `Time`, as before, or seconds.
+- `return_op: true` becomes `return_call: true`, which returns the
+  response with its headers and trailers instead of an operation.
+- `GRPC::BadStatus` subclasses become one `Tonic::Rails::RpcError`:
+  `rescue GRPC::NotFound` becomes `rescue Tonic::Rails::RpcError => e`
+  and a check of `e.code_name == :not_found`. The `raise_grpc_error`
+  matcher and `assert_grpc_error` accept both.
+- `:this_channel_is_insecure` becomes `tls: false`.
+- Server-streaming methods return a stream instead of an Enumerator.
+  Code that calls `each` or other Enumerable methods on the result works
+  unchanged; for `next`, call `each` first to get an Enumerator.
+- Client and bidirectional streaming aren't supported yet. Stubs refuse
+  those methods with a `NotImplementedError`; keep the grpc gem for them
+  for now.
+
 ## Testing handlers
 
 `Tonic::Rails::Testing` calls a handler in-process, with real protobuf
@@ -634,6 +893,12 @@ 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.
 
+Calls made with `Tonic::Rails::Client` publish `request_rpc.tonic_rails`,
+with the same payload plus `:address`, the server called, and
+`:attempts`, how many times it was tried. For a
+server-streaming call, the event covers the whole stream, including the
+time your block spends on each message.
+
 ## How it works
 
 ```

data/ext/tonic_rails_native/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tonic_rails_native"
-version = "0.5.0"
+version = "0.7.0"
 edition = "2024"
 rust-version = "1.88"
 publish = false
@@ -23,6 +23,10 @@ crate-type = ["cdylib"]
 #
 # socket2 configures the listener (SO_REUSEADDR/SO_REUSEPORT, backlog) and
 # adopts the listening socket worker processes inherit in multi-process mode.
+#
+# The client (`TonicRails::Native::Channel`) uses tonic's Channel with the
+# same raw-byte passthrough.  rustls-native-certs loads the system's root
+# certificates for TLS, and base64 turns them into PEM for tonic.
 [dependencies]
 magnus = "0.9"
 rb-sys = "0.9"
@@ -45,3 +49,5 @@ http-body-util = "0.1"
 bytes = "1"
 tower = "0.5"
 flate2 = { version = "1", features = ["rust_backend"] }
+rustls-native-certs = "0.8"
+base64 = "0.22"

data/ext/tonic_rails_native/src/body.rs

@@ -12,7 +12,6 @@ use std::task::{Context, Poll};
 use std::time::Instant;
 
 use bytes::Bytes;
-use http::HeaderMap;
 use http_body::{Body, Frame};
 use tokio::sync::mpsc;
 use tonic::{Code, Status};
@@ -71,35 +70,6 @@ impl ServerStats {
     }
 }
 
-/// Trailers-only error response for requests rejected before dispatch.
-pub struct ErrorBody {
-    trailers: Option<HeaderMap>,
-}
-
-impl ErrorBody {
-    pub fn new(code: Code, message: &str) -> Self {
-        Self {
-            trailers: Some(status_trailers(code as u32, message)),
-        }
-    }
-}
-
-impl Body for ErrorBody {
-    type Data = Bytes;
-    type Error = Status;
-
-    fn poll_frame(
-        mut self: Pin<&mut Self>,
-        _cx: &mut Context<'_>,
-    ) -> Poll<Option<Result<Frame<Bytes>, Status>>> {
-        Poll::Ready(self.trailers.take().map(|t| Ok(Frame::trailers(t))))
-    }
-
-    fn is_end_stream(&self) -> bool {
-        self.trailers.is_none()
-    }
-}
-
 /// Streaming response body fed by the Ruby handler through an mpsc
 /// channel.  Each `Data` message becomes a gRPC frame; `End` (or the
 /// deadline) produces the trailers.
@@ -232,6 +202,7 @@ impl Drop for ResponseBody {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use http::HeaderMap;
     use std::task::Waker;
 
     type PolledFrame = Poll<Option<Result<Frame<Bytes>, Status>>>;
@@ -262,16 +233,6 @@ mod tests {
         }
     }
 
-    #[test]
-    fn error_body_yields_trailers_once() {
-        let mut body = ErrorBody::new(Code::NotFound, "missing");
-        let t = trailers(poll(&mut body));
-        assert_eq!(t["grpc-status"], "5");
-        assert_eq!(t["grpc-message"], "missing");
-        assert!(matches!(poll(&mut body), Poll::Ready(None)));
-        assert!(body.is_end_stream());
-    }
-
     #[test]
     fn response_body_streams_data_then_ok() {
         let (tx, rx) = mpsc::channel(4);