tonic-rails 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 234f197083161b48c0fa820f8e9e8bb20138208c131e8467279cd40d9b73d872
-  data.tar.gz: a5ec7ea58b4325c881045c7550468a19de879b7119212e212500c4632e581f56
+  metadata.gz: 8b39b4d814c854c16c5a1f9c7ec05415402fdbb49716846bc3883442931f5165
+  data.tar.gz: f4dcedf8d10ec7cd0786232a7637e192ec5dd7746ee15542322465d56bc11436
 SHA512:
-  metadata.gz: 59c579e49bfc33f7f551ba522823fac67e253d939723c0fcdf4368560f558094b519a1339ca325d81cd2e06fa3dd51e1b7486b790b11da711ab04a24bfe2d375
-  data.tar.gz: 229844b0f0d86b85f0545c715bb04c70148ecff829ea699283d5bf0a624aab91e788224af557ad513db559b3f42ed9c381350f0dd00238e0c78f0be67731437f
+  metadata.gz: b1b5406e16afb900514ae85ae11350d7a7546c0a08ed27c3c1042622de85b4ea9ac692185e3a0d27792f95ca36e61a1f2ff0b5729bf8e38eb645ed9e45c011ee
+  data.tar.gz: 7b3b7386f1c8342cf0c25fce33ea1564c38e1be027788b7b919377354b9a9a53f3c58338e334185d8dd0377f261b9775fadeee1cc4a2b0ac627764737329fd2b

data/CHANGELOG.md

@@ -7,6 +7,27 @@ minor versions may contain breaking changes.
 
 ## [Unreleased]
 
+## [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 +166,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.5.0...HEAD
+[Unreleased]: https://github.com/CodingAnarchy/tonic-rails/compare/v0.6.0...HEAD
+[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.6.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,197 @@ 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.
+
+### 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 |
+
+### 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 +829,11 @@ 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. 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.6.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"