tonic-rails 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df7cc56c6ca7ca2594bc38ab5e676d9c68f6dbcd6464155d14b3d7a83ef98ef2
-  data.tar.gz: 9763e38411184f3c9a796f9e72bf9238ae3e20c16c7687cefa3792192cba7516
+  metadata.gz: 8b39b4d814c854c16c5a1f9c7ec05415402fdbb49716846bc3883442931f5165
+  data.tar.gz: f4dcedf8d10ec7cd0786232a7637e192ec5dd7746ee15542322465d56bc11436
 SHA512:
-  metadata.gz: d2bf2cad63a78055da0874e0a934a44f41a015c9dd98d2512b1b8ef8b6830cfdb64d262d65c55fad5b532574ec6b7a63f4777f79b6f13e7d23dd06808417c46c
-  data.tar.gz: 04df783ef65a2eb4d8a717d4643e4e406a0040a053289d5c2841014c6bb69ec267223e2bf52b9323dc1314b179969e7bb6da2606fee8bf4f93121b2932f5ce2a
+  metadata.gz: b1b5406e16afb900514ae85ae11350d7a7546c0a08ed27c3c1042622de85b4ea9ac692185e3a0d27792f95ca36e61a1f2ff0b5729bf8e38eb645ed9e45c011ee
+  data.tar.gz: 7b3b7386f1c8342cf0c25fce33ea1564c38e1be027788b7b919377354b9a9a53f3c58338e334185d8dd0377f261b9775fadeee1cc4a2b0ac627764737329fd2b

data/CHANGELOG.md

@@ -7,6 +7,47 @@ 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
+
+- Multi-process mode: `config.processes = 4` runs four server processes
+  on one port, so services that spend their time in Ruby use four cores
+  instead of one. The app loads once and forks the workers. They share
+  the listening socket, with new connections going to the least busy
+  worker. Workers that die are replaced, and SIGTERM drains them all.
+  `on_worker_boot` runs in each worker after fork. Works with
+  `tonic_rails:serve` and the Puma plugin; Unix only. Closes #23.
+- Benchmark: `PROCESSES` and `CONNECTIONS` for `bench/run_bench.sh`, and
+  `-connections` for the Go client.
+
+### Changed
+
+- The Puma plugin waits `drain_timeout` + 10 seconds (was + 5) for the
+  gRPC server to stop before killing it, which leaves a multi-process
+  server time to stop its own workers.
+
 ## [0.4.0] - 2026-10-11
 
 ### Added
@@ -125,7 +166,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.4.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
 [0.2.0]: https://github.com/CodingAnarchy/tonic-rails/compare/v0.1.0...v0.2.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.4.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
@@ -470,6 +665,8 @@ end
 |--------|---------|-------------|
 | `bind_address` | `"0.0.0.0:50051"` | Address to listen on |
 | `dispatch_threads` | `4` | Ruby threads running handlers; match your database pool |
+| `processes` | `1` | Server processes sharing the port (see [Threads or processes](#threads-or-processes)); Unix only |
+| `on_worker_boot` | `nil` | Callable run in each worker process after fork, given its index |
 | `dispatch_queue_size` | `128` | Calls that may wait for a thread; beyond this, `RESOURCE_EXHAUSTED` |
 | `worker_threads` | CPU count | Tokio threads for the transport |
 | `max_message_size` | 4 MiB | Request and response limit (also caps decompressed size) |
@@ -490,14 +687,60 @@ end
 | `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
+### Threads or processes
 
 Handlers run on `dispatch_threads` Ruby threads. Blocking I/O (database,
-HTTP) releases the GVL, so more threads means more concurrent I/O. CPU
-work does not parallelise within a process. Set threads to the
-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.
+HTTP) releases Ruby's global VM lock, so more threads means more
+concurrent I/O. Ruby code itself runs one thread at a time per process,
+though: a service that spends its time in Ruby (building large
+responses, serializing, computing) tops out at one core however many
+threads it has.
+
+So:
+
+- **Mostly waiting on I/O?** Add threads. They're cheap, and one process
+  goes a long way. Size the database pool to match.
+- **Mostly running Ruby?** Add processes. `processes = 4` runs four
+  copies of the server on the same port and uses four cores.
+
+```ruby
+config.tonic_rails.processes = ENV.fetch("GRPC_PROCESSES", 4).to_i
+config.tonic_rails.dispatch_threads = 5 # per process
+```
+
+Most services mix both. A reasonable start is one process per core and
+a handful of threads in each. Every process has its own database pool,
+so the database sees up to `processes × dispatch_threads` connections.
+
+With `processes` above 1, `bin/rails tonic_rails:serve` loads the app
+once and forks the workers, which share memory until they write to it.
+The process you started supervises them:
+
+- Workers share one listening socket, and a worker with fewer open
+  connections picks up new ones first. gRPC clients keep connections
+  open and send every call over them, so a single client connection
+  is served by a single worker: spread load with several connections
+  or several clients.
+- If a worker dies, it's logged and replaced.
+- SIGTERM or SIGINT to the supervisor drains every worker (health
+  reports `NOT_SERVING`, in-flight calls finish) and it exits once all
+  have stopped. Workers stop on their own if the supervisor disappears.
+- If a worker fails while starting (a bad configuration, say), the
+  server doesn't start.
+
+Active Record reconnects in each worker by itself. Reopen anything else
+that can't be shared across `fork` in `on_worker_boot`:
+
+```ruby
+config.tonic_rails.on_worker_boot = ->(index) { MyQueueClient.reconnect! }
+```
+
+Health checks, `health_check`, `serving!`, `not_serving!` and `stats`
+work per worker: calling `serving!` or `not_serving!` in the supervisor
+after the server has started doesn't reach the workers.
+
+Multi-process mode needs `fork()`, so it isn't available on Windows. Run
+one server process per core there, each on its own port.
 
 ### Running with Puma
 
@@ -513,7 +756,8 @@ 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.)
+`tonic_rails:serve` as its own process there.) With `processes` above 1,
+that child process supervises the gRPC workers.
 
 For larger deployments, a dedicated `bin/rails tonic_rails:serve` process
 (scaled separately) is still the most flexible option.
@@ -523,7 +767,7 @@ For larger deployments, a dedicated `bin/rails tonic_rails:serve` process
 `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 use the Puma plugin or a dedicated process.
-Don't combine it with the plugin.
+Don't combine it with the plugin, and it can't run multiple `processes`.
 
 ## Operations
 
@@ -585,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.4.0"
+version = "0.6.0"
 edition = "2024"
 rust-version = "1.88"
 publish = false
@@ -21,7 +21,12 @@ crate-type = ["cdylib"]
 # and no service definitions are compiled into the extension — routes
 # are registered from Ruby at runtime.
 #
-# socket2 enables SO_REUSEPORT for multi-process (Puma worker) scaling.
+# 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"
@@ -44,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"