tonic-rails 0.5.0-x86_64-linux-gnu → 0.7.0-x86_64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5aa7de65014581bfcd5575510bdcd6ec9ec4bd0ab81473e49077188093ff436a
-  data.tar.gz: eaf8038cfa3d9b62e16d575b4e56001bb9873cdc30ed19f9ab43967869d907f5
+  metadata.gz: 83bded7e4b04dc72602f73fa065ac32bde6f97631fe4450525432ef6f93df506
+  data.tar.gz: 13bb870aa4bfb1487fa9827745aceac8c1a0a211053a9b5adafebe494975307e
 SHA512:
-  metadata.gz: cc4417d8c41fb9fb0e363ffb0605ac745d9b564e63a413b7b86e6d2d8a0c861f035f2553a6df8602466ead880cd58d1cc50bfc798536e97bc967d67b7b107b0f
-  data.tar.gz: 484f38fa65491cf4e34e32e30e35af03ee7b5de3e354b33e4c23fbbe1df50b55a7dc9d19411f59ef1db04767fca9eb69d90facdae940e79f4f0cd6f92c77700c
+  metadata.gz: 539c6220bfa47fb98b506c826112ad5728bde68693c37a3479dd2727baff3b14fd07cb689c4c72419d05228a4c3042ea4ce636b44f7c1cdbad06013a2084f8ba
+  data.tar.gz: 9ac35b6b569b9f4083ea342c5e55fe321dda57b89ec4d797ec41624ae2477e47957f71cd4569f9c42fb592d5b1860037ba0fdf2378a75fbba2cf3ed894e1c3da

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/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/lib/tonic/rails/base.rb

@@ -248,7 +248,10 @@ module Tonic
 
         @request = build_request(reader, spec)
         response = nil
-        run_callbacks(:rpc) { response = respond(public_send(spec[:handler], @request), spec, sender) }
+        # Calls this handler makes with Tonic::Rails::Client default to its deadline.
+        Client.with_deadline(@grpc_deadline_at) do
+          run_callbacks(:rpc) { response = respond(public_send(spec[:handler], @request), spec, sender) }
+        end
         response
       rescue RpcError
         raise

data/lib/tonic/rails/client/retry_policy.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Tonic
+  module Rails
+    class Client
+      # When and how often a call is retried, following gRPC's retry design
+      # (A6).  Pass one, a Hash of its fields or `true` for the defaults as
+      # `retries:` to Client.new or to a single call.
+      #
+      #   Tonic::Rails::Client.new("items.internal:50051", retries: true)
+      #   Tonic::Rails::Client.new("items.internal:50051", retries: { max_attempts: 4 })
+      #   items.get_item({ id: 1 }, retries: false)
+      #
+      # Only calls the server hasn't started on are retried: the connection
+      # failed, or the server answered with a status and no response
+      # headers.  Each wait is random, up to a cap that grows from
+      # `initial_backoff` by `multiplier` per attempt to `max_backoff`.
+      # Retrying stops when the next attempt couldn't start before the
+      # call's deadline.
+      RetryPolicy = Data.define(:max_attempts, :codes, :initial_backoff, :max_backoff, :multiplier) do
+        # Defaults for the fields left out.
+        def self.defaults
+          { max_attempts: 3, codes: [:unavailable], initial_backoff: 0.1, max_backoff: 1, multiplier: 2 }
+        end
+
+        # @param option [RetryPolicy, Hash, true, false, nil]
+        # @return [RetryPolicy, nil] nil for no retries
+        def self.from(option)
+          case option
+          when nil, false then nil
+          when true then new(**defaults)
+          when Hash then new(**defaults, **option)
+          when self then option
+          else raise ArgumentError, "retries must be true, false, a Hash or a #{name}, got #{option.class}"
+          end
+        end
+
+        # @param max_attempts [Integer] attempts in all, from 2 to 5.  gRPC
+        #   caps it at 5, so a misconfigured client can't multiply an
+        #   outage's traffic by more than that.
+        # @param codes [Array<Symbol, Integer>] status codes worth retrying
+        # @param initial_backoff [Numeric] seconds; the cap on the first wait
+        # @param max_backoff [Numeric] seconds; the cap on any wait
+        # @param multiplier [Numeric] how much the cap grows per attempt
+        def initialize(max_attempts:, codes:, initial_backoff:, max_backoff:, multiplier:)
+          unless max_attempts.is_a?(Integer) && max_attempts.between?(2, 5)
+            raise ArgumentError, "max_attempts must be an Integer from 2 to 5"
+          end
+
+          codes = Array(codes).map { |code| RpcError.normalize_code(code) }.uniq.freeze
+          raise ArgumentError, "codes must name at least one status code other than OK" if codes.empty? || codes.include?(0)
+
+          [[:initial_backoff, initial_backoff], [:max_backoff, max_backoff]].each do |field, value|
+            raise ArgumentError, "#{field} must be a positive number of seconds" unless value.is_a?(Numeric) && value.positive?
+          end
+          raise ArgumentError, "multiplier must be at least 1" unless multiplier.is_a?(Numeric) && multiplier >= 1
+
+          super
+        end
+
+        # @param code [Integer]
+        def retry?(code)
+          codes.include?(code)
+        end
+
+        # Seconds to wait after failed attempt number `attempt` (from 1).
+        def backoff(attempt)
+          rand * [initial_backoff * (multiplier**(attempt - 1)), max_backoff].min
+        end
+      end
+    end
+  end
+end

data/lib/tonic/rails/client.rb

@@ -0,0 +1,460 @@
+# frozen_string_literal: true
+
+require "active_support/inflector"
+
+module Tonic
+  module Rails
+    # Calls other gRPC services, without the grpc gem.
+    #
+    #   ITEMS = Tonic::Rails::Client.new("items.internal:50051", deadline: 2)
+    #
+    #   items = ITEMS.stub("demo.v1.ItemService")
+    #   item = items.get_item(Demo::V1::GetItemRequest.new(id: 1))
+    #   item = items.get_item(id: 1)
+    #   item = items.get_item({ id: 1 }, deadline: 0.5, metadata: { "x-request-id" => request_id })
+    #   items.list_items(category: "books").each { |item| ... }
+    #
+    # Retries are opt-in: `retries: true` (or a Hash; see RetryPolicy) on
+    # the client or a call retries calls the server never started on.
+    #
+    # Stubs are built from the protobuf descriptors that
+    # `tonic_rails:compile_protos` (protoc --ruby_out) generates; no
+    # `_services_pb.rb` is needed.  A failed call raises
+    # Tonic::Rails::RpcError.
+    #
+    # A client holds one HTTP/2 connection and is safe to share between
+    # threads, so create it once (a constant or an initializer).  It keeps
+    # working across `fork`: each process connects on its own, with no
+    # hooks to call.
+    class Client
+      # A response with its headers and trailers; see `return_call:`.
+      Call = Data.define(:response, :headers, :trailers)
+
+      DEFAULT_MAX_MESSAGE_SIZE = 4 * 1024 * 1024
+
+      # Trailer a server sends to ask for a retry after so many
+      # milliseconds, or (with a negative value) for none.
+      RETRY_PUSHBACK = "grpc-retry-pushback-ms"
+      private_constant :RETRY_PUSHBACK
+
+      # @return [String] "host:port"
+      attr_reader :address
+
+      # @return [Numeric, nil] default deadline in seconds
+      attr_reader :deadline
+
+      # @return [RetryPolicy, nil] how calls are retried, unless they say otherwise
+      attr_reader :retries
+
+      # @param address [String] "host:port"
+      # @param tls [Boolean] false for plaintext, which must be explicit
+      # @param tls_ca_path [String, nil] CA certificates (PEM) to trust instead
+      #   of the system's root certificates
+      # @param tls_cert_path [String, nil] client certificate (PEM), for mutual TLS
+      # @param tls_key_path [String, nil] client private key (PEM), for mutual TLS
+      # @param tls_server_name [String, nil] name to verify the server's
+      #   certificate against, if not the host in `address`
+      # @param deadline [Numeric, nil] seconds each call may take, unless the
+      #   call sets its own
+      # @param metadata [Hash] sent with every call (see Tonic::Rails::Metadata)
+      # @param max_message_size [Integer] largest message sent or received, in bytes
+      # @param connect_timeout [Numeric] seconds to wait for a connection
+      # @param retries [RetryPolicy, Hash, Boolean] retry calls the server
+      #   never started on (see RetryPolicy); off by default
+      # @param logger [Logger, nil] where retries are logged; defaults to
+      #   Tonic::Rails.configuration.logger
+      def initialize(address, tls: true, tls_ca_path: nil, tls_cert_path: nil, tls_key_path: nil,
+                     tls_server_name: nil, deadline: nil, metadata: {}, max_message_size: DEFAULT_MAX_MESSAGE_SIZE,
+                     connect_timeout: 5, retries: false, logger: nil)
+        Tonic::Rails.native_extension!
+        validate_address!(address)
+        validate_tls!(tls, tls_cert_path, tls_key_path)
+        positive!(:deadline, deadline) unless deadline.nil?
+        positive!(:connect_timeout, connect_timeout)
+        unless max_message_size.is_a?(Integer) && max_message_size.positive?
+          raise ArgumentError, "max_message_size must be a positive Integer"
+        end
+
+        @address = address
+        @deadline = deadline
+        @retries = RetryPolicy.from(retries)
+        @logger = logger
+        @metadata = Metadata.encode(metadata)
+        @stubs = {}
+        tls_options = [read_pem(tls_ca_path, "CA"), read_pem(tls_cert_path, "certificate"),
+                       read_pem(tls_key_path, "key"), tls_server_name]
+        @native = TonicRails::Native::Channel.new(
+          "#{tls ? 'https' : 'http'}://#{address}", max_message_size, (connect_timeout * 1000).ceil,
+          (tls_options if tls)
+        )
+      end
+
+      # A stub with one method per RPC of the service, named in snake_case
+      # (`GetItem` becomes `get_item`).
+      #
+      # @param service [String, Google::Protobuf::ServiceDescriptor, #service_name]
+      #   the fully-qualified service name, its descriptor, or a grpc gem
+      #   service class (`Demo::V1::ItemService::Service`)
+      # @return [Tonic::Rails::Client::Stub]
+      def stub(service)
+        descriptor = service_descriptor(service)
+        @stubs[descriptor.name] ||= Stub.for(descriptor).new(self)
+      end
+
+      def inspect
+        "#<#{self.class.name} #{address}>"
+      end
+
+      # The deadline of the RPC this thread is handling, as a monotonic
+      # clock time; outgoing calls default to it.
+      # @api private
+      def self.current_deadline
+        Thread.current[:tonic_rails_deadline]
+      end
+
+      # @api private
+      def self.with_deadline(deadline)
+        previous = Thread.current[:tonic_rails_deadline]
+        Thread.current[:tonic_rails_deadline] = deadline
+        yield
+      ensure
+        Thread.current[:tonic_rails_deadline] = previous
+      end
+
+      # Make a unary call.  Stubs call this; use them instead.
+      # @api private
+      def unary(path, input, output, request, deadline: nil, metadata: {}, return_call: false, retries: nil)
+        bytes = input.encode(request_message(path, input, request))
+        metadata = call_metadata(metadata)
+        deadline_at = deadline_at(deadline)
+        policy = retry_policy(retries)
+
+        Instrumentation.instrument_request(path, address, metadata) do |payload|
+          code, error_message, response, headers, trailers, details = with_retries(path, policy, deadline_at, payload) do
+            @native.unary(path, bytes, metadata, remaining_ms(deadline_at))
+          end
+          headers = decode_metadata(headers)
+          trailers = decode_metadata(trailers)
+          check_status!(code, error_message, trailers, details)
+
+          response = decode_response(output, response, path)
+          return_call ? Call.new(response: response, headers: headers, trailers: trailers) : response
+        end
+      end
+
+      # Start a server-streaming call.  Stubs call this; use them instead.
+      # @api private
+      def server_streaming(path, input, output, request, deadline: nil, metadata: {}, retries: nil)
+        bytes = input.encode(request_message(path, input, request))
+        metadata = call_metadata(metadata)
+        # Fixed now, so the stream keeps the deadline of the RPC this
+        # thread is handling even if it's read later.
+        deadline_at = deadline_at(deadline)
+        policy = retry_policy(retries)
+
+        ServerStream.new(path) do |stream, block|
+          Instrumentation.instrument_request(path, address, metadata) do |payload|
+            # A message arrives only after the response headers, which
+            # commit the call, so an attempt that yielded anything is never
+            # retried.
+            code, error_message, _, headers, trailers, details = with_retries(path, policy, deadline_at, payload) do
+              read_stream(@native.server_streaming(path, bytes, metadata, remaining_ms(deadline_at)), output, path, &block)
+            end
+            trailers = decode_metadata(trailers)
+            stream.finish(decode_metadata(headers), trailers)
+            check_status!(code, error_message, trailers, details)
+          end
+        end
+      end
+
+      private
+
+      def validate_address!(address)
+        return if address.is_a?(String) && address.match?(%r{\A[^\s/]+:\d+\z})
+
+        raise ArgumentError, "address must be \"host:port\", got #{address.inspect}"
+      end
+
+      def validate_tls!(tls, cert_path, key_path)
+        raise ArgumentError, "tls must be true or false" unless [true, false].include?(tls)
+        raise ArgumentError, "tls_cert_path and tls_key_path must be set together" if cert_path.nil? != key_path.nil?
+        raise ArgumentError, "tls_cert_path and tls_key_path need tls: true" if cert_path && !tls
+      end
+
+      def positive!(name, value)
+        raise ArgumentError, "#{name} must be a positive number of seconds" unless value.is_a?(Numeric) && value.positive?
+      end
+
+      def read_pem(path, what)
+        return unless path
+        raise ArgumentError, "TLS #{what} file not found: #{path}" unless File.file?(path)
+
+        File.read(path)
+      end
+
+      def service_descriptor(service)
+        return service if service.is_a?(Google::Protobuf::ServiceDescriptor)
+
+        name = service.respond_to?(:service_name) ? service.service_name : service.to_s
+        descriptor = Google::Protobuf::DescriptorPool.generated_pool.lookup(name)
+        return descriptor if descriptor.is_a?(Google::Protobuf::ServiceDescriptor)
+
+        raise NotConfiguredError,
+              "#{name} is not a known protobuf service. Require its generated _pb.rb file (protoc --ruby_out) first."
+      end
+
+      def request_message(path, input, request)
+        case request
+        when input then request
+        when Hash then input.new(request)
+        else raise TypeError, "#{path} expects a #{input} or Hash, got #{request.class}"
+        end
+      end
+
+      def call_metadata(metadata)
+        metadata.empty? ? @metadata : @metadata.merge(Metadata.encode(metadata))
+      end
+
+      # When the call must end, as a monotonic clock time: the call's own
+      # deadline, or else the earlier of the client's default and the
+      # deadline of the RPC being handled.
+      def deadline_at(deadline)
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        case deadline
+        when nil then [(now + @deadline if @deadline), self.class.current_deadline].compact.min
+        when Numeric then now + deadline
+        when Time then now + (deadline - Time.now)
+        else raise ArgumentError, "deadline must be seconds (Numeric) or a Time, got #{deadline.class}"
+        end
+      end
+
+      # Milliseconds left until `deadline_at`, or nil for no deadline.
+      def remaining_ms(deadline_at)
+        return unless deadline_at
+
+        remaining = deadline_at - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        raise RpcError.new("deadline exceeded", code: :deadline_exceeded) unless remaining.positive?
+
+        (remaining * 1000).ceil
+      end
+
+      def retry_policy(retries)
+        retries.nil? ? @retries : RetryPolicy.from(retries)
+      end
+
+      # Yield each message of a native stream, then return its result.
+      def read_stream(native, output, path)
+        while (bytes = native.next)
+          yield decode_response(output, bytes, path)
+        end
+        native.result
+      ensure
+        native.close
+      end
+
+      # Run attempts of a call (the block returns a native result) until one
+      # succeeds or shouldn't be retried; return its result.
+      def with_retries(path, policy, deadline_at, payload)
+        attempt = 1
+        loop do
+          payload[:attempts] = attempt if payload
+          result = yield
+          delay = retry_delay(policy, attempt, result, deadline_at)
+          if delay.nil?
+            log_gave_up(path, attempt, result) if attempt > 1 && !result[0].zero?
+            return result
+          end
+
+          log_retry(path, attempt, policy.max_attempts, result, delay)
+          sleep(delay)
+          attempt += 1
+        end
+      end
+
+      # Seconds to wait before retrying, or nil not to retry.  The server
+      # can ask for a delay, or for no retry, with grpc-retry-pushback-ms.
+      def retry_delay(policy, attempt, result, deadline_at)
+        code, _, _, _, trailers, _, committed = result
+        return if policy.nil? || code.zero? || committed || attempt >= policy.max_attempts || !policy.retry?(code)
+
+        pushback = trailers.assoc(RETRY_PUSHBACK)&.last
+        delay = if pushback.nil? then policy.backoff(attempt)
+        elsif pushback.match?(/\A\d+\z/) then pushback.to_i / 1000.0
+        end
+        return if delay.nil?
+        return if deadline_at && Process.clock_gettime(Process::CLOCK_MONOTONIC) + delay >= deadline_at
+
+        delay
+      end
+
+      def logger
+        @logger || Tonic::Rails.configuration.logger
+      end
+
+      def log_retry(path, attempt, max_attempts, result, delay)
+        logger&.warn(format("tonic-rails: %<path>s failed with %<status>s (attempt %<attempt>d of %<max>d); " \
+                            "retrying in %<ms>dms", path: path, status: status_text(result), attempt: attempt,
+                                                    max: max_attempts, ms: (delay * 1000).round))
+      end
+
+      def log_gave_up(path, attempts, result)
+        logger&.warn("tonic-rails: #{path} failed with #{status_text(result)} after #{attempts} attempts")
+      end
+
+      def status_text(result)
+        code, message = result
+        text = RpcError::CODE_NAMES.fetch(code, code).to_s.upcase
+        message.empty? ? text : "#{text}: #{message}"
+      end
+
+      def check_status!(code, message, trailers, details)
+        return if code.zero?
+
+        raise RpcError.new(message.empty? ? nil : message, code: code, metadata: trailers,
+                                                           details: RpcError.decode_details(details))
+      end
+
+      # Wire-form [name, value] pairs to a Hash: `-bin` values decoded,
+      # repeated names collected into an Array, and transport headers
+      # (content-type, grpc-*) dropped.
+      def decode_metadata(pairs)
+        pairs.each_with_object({}) do |(name, value), metadata|
+          next if name.start_with?("grpc-") || Metadata::RESERVED.include?(name)
+
+          value = value.unpack1("m") if name.end_with?("-bin")
+          metadata[name] = metadata.key?(name) ? [*metadata[name], value] : value
+        end
+      end
+
+      def decode_response(output, bytes, path)
+        output.decode(bytes)
+      rescue Google::Protobuf::ParseError
+        raise RpcError.new("invalid protobuf response from #{path}", code: :internal)
+      end
+
+      # Calls an RPC's methods.  Built per service from its descriptor; get
+      # one with Client#stub.
+      class Stub
+        class << self
+          # @api private
+          attr_reader :service_name
+
+          # @api private
+          def for(descriptor)
+            Class.new(self) do
+              @service_name = descriptor.name
+              descriptor.each { |method| define_rpc(method) }
+            end
+          end
+
+          def inspect
+            service_name ? "#{Stub.name}(#{service_name})" : super
+          end
+
+          private
+
+          def define_rpc(method)
+            path = "/#{service_name}/#{method.name}"
+            name = ActiveSupport::Inflector.underscore(method.name)
+            if method.client_streaming
+              define_method(name) do |*, **|
+                raise NotImplementedError,
+                      "#{path} is a client-streaming RPC; the tonic-rails client makes unary and server-streaming calls"
+              end
+              return
+            end
+
+            input = method.input_type.msgclass
+            output = method.output_type.msgclass
+            if method.server_streaming
+              define_method(name) do |request = nil, deadline: nil, metadata: {}, retries: nil, **fields|
+                request = rpc_request(name, request, fields)
+                @client.server_streaming(path, input, output, request, deadline: deadline, metadata: metadata,
+                                                                       retries: retries)
+              end
+            else
+              # `get_item(id: 1)` works as well as `get_item({ id: 1 })`.
+              define_method(name) do |request = nil, deadline: nil, metadata: {}, return_call: false, retries: nil,
+                                      **fields|
+                request = rpc_request(name, request, fields)
+                @client.unary(path, input, output, request, deadline: deadline, metadata: metadata,
+                                                            return_call: return_call, retries: retries)
+              end
+            end
+          end
+        end
+
+        # @return [Tonic::Rails::Client]
+        attr_reader :client
+
+        def initialize(client)
+          @client = client
+        end
+
+        def inspect
+          "#<#{self.class.inspect} #{client.address}>"
+        end
+
+        private
+
+        def rpc_request(name, request, fields)
+          unless request.nil? || fields.empty?
+            raise ArgumentError, "#{name}: pass the request or its fields, not both (#{fields.keys.join(', ')})"
+          end
+
+          request || fields
+        end
+      end
+
+      # The responses of a server-streaming call.  Nothing is sent until
+      # it's read; then messages are yielded as they arrive, a few at most
+      # buffered ahead of the reader.
+      #
+      #   items.list_items(category: "books").each { |item| ... }
+      #   items.list_items(category: "books").first(10)
+      #
+      # Stopping early (`break`, `first(n)`, an exception) cancels the call.
+      # An error from the server raises Tonic::Rails::RpcError after the
+      # messages that came before it.  A stream can be read once.
+      class ServerStream
+        include Enumerable
+
+        # @return [Hash, nil] response headers, once the stream has ended
+        attr_reader :headers
+
+        # @return [Hash, nil] trailing metadata, once the stream has ended
+        attr_reader :trailers
+
+        # @api private
+        def initialize(path, &read)
+          @path = path
+          @read = read
+        end
+
+        # @yieldparam response [Google::Protobuf::AbstractMessage]
+        # @return [self, Enumerator] an Enumerator without a block
+        def each(&block)
+          return enum_for(:each) unless block
+          raise Error, "the #{@path} stream has already been read" unless @read
+
+          read = @read
+          @read = nil
+          read.call(self, block)
+          self
+        end
+
+        # @api private
+        def finish(headers, trailers)
+          @headers = headers
+          @trailers = trailers
+        end
+
+        def inspect
+          "#<#{self.class.name} #{@path}>"
+        end
+      end
+    end
+  end
+end
+
+require "tonic/rails/client/retry_policy"

data/lib/tonic/rails/instrumentation.rb

@@ -24,18 +24,34 @@ module Tonic
     module Instrumentation
       EVENT = "process_rpc.tonic_rails"
 
+      # Outgoing 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.
+      REQUEST_EVENT = "request_rpc.tonic_rails"
+
       module_function
 
       # @api private
-      def instrument(path, metadata)
+      def instrument(path, metadata, &)
+        publish(EVENT, path, metadata, &)
+      end
+
+      # @api private
+      def instrument_request(path, address, metadata, &)
+        publish(REQUEST_EVENT, path, metadata, address: address, &)
+      end
+
+      # Yields the payload, or nil when nothing is listening.
+      # @api private
+      def publish(event, path, metadata, **extra)
         # Without subscribers, skip building the payload: this runs on
         # every RPC.
-        return yield unless ActiveSupport::Notifications.notifier.listening?(EVENT)
+        return yield(nil) unless ActiveSupport::Notifications.notifier.listening?(event)
 
         service, rpc = path.delete_prefix("/").split("/", 2)
-        payload = { path: path, service: service, rpc: rpc, metadata: metadata, code: nil, status: nil }
-        ActiveSupport::Notifications.instrument(EVENT, payload) do
-          result = yield
+        payload = { path: path, service: service, rpc: rpc, metadata: metadata, code: nil, status: nil, **extra }
+        ActiveSupport::Notifications.instrument(event, payload) do
+          result = yield(payload)
           payload[:code] = 0
           payload[:status] = :ok
           result

data/lib/tonic/rails/rpc_error.rb

@@ -19,6 +19,8 @@ module Tonic
     # The message, metadata and details go to the client, so keep internal
     # details out of them.  Any other exception becomes INTERNAL with a
     # generic message and is logged server-side.
+    #
+    # Tonic::Rails::Client raises it too, for calls that fail.
     class RpcError < Error
       CODES = {
         ok: 0,
@@ -114,6 +116,65 @@ module Tonic
         CODE_NAMES.fetch(@code)
       end
 
+      # Unpacks the details of an encoded google.rpc.Status (from the
+      # grpc-status-details-bin trailer).  Details whose message type is
+      # loaded come back as that message; others stay Google::Protobuf::Any.
+      # @api private
+      # @return [Array<Google::Protobuf::AbstractMessage>]
+      def self.decode_details(bytes)
+        return [] if bytes.nil? || bytes.empty?
+
+        require "google/protobuf/well_known_types"
+        details = []
+        each_length_delimited_field(bytes.b) do |field, value|
+          details << unpack_detail(Google::Protobuf::Any.decode(value)) if field == 3
+        end
+        details
+      rescue Google::Protobuf::ParseError, ArgumentError
+        []
+      end
+
+      # Yields (field number, bytes) for each length-delimited field,
+      # skipping varints; raises ArgumentError on anything malformed.
+      def self.each_length_delimited_field(buf)
+        pos = 0
+        while pos < buf.bytesize
+          key, pos = read_varint(buf, pos)
+          case key & 7
+          when 0 then _, pos = read_varint(buf, pos)
+          when 2
+            length, pos = read_varint(buf, pos)
+            raise ArgumentError, "truncated google.rpc.Status" if pos + length > buf.bytesize
+
+            yield key >> 3, buf.byteslice(pos, length)
+            pos += length
+          else raise ArgumentError, "unexpected wire type in google.rpc.Status"
+          end
+        end
+      end
+      private_class_method :each_length_delimited_field
+
+      def self.read_varint(buf, pos)
+        value = 0
+        shift = 0
+        loop do
+          byte = buf.getbyte(pos) or raise ArgumentError, "truncated varint"
+          pos += 1
+          value |= (byte & 0x7f) << shift
+          return [value, pos] if byte < 0x80
+
+          shift += 7
+          raise ArgumentError, "varint too long" if shift > 63
+        end
+      end
+      private_class_method :read_varint
+
+      def self.unpack_detail(any)
+        type = Google::Protobuf::DescriptorPool.generated_pool.lookup(any.type_name)
+        type.is_a?(Google::Protobuf::Descriptor) ? any.unpack(type.msgclass) : any
+      end
+      private_class_method :unpack_detail
+
       # @api private
       def self.normalize_code(code)
         case code

data/lib/tonic/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Tonic
   module Rails
-    VERSION = "0.5.0"
+    VERSION = "0.7.0"
   end
 end

data/lib/tonic-rails.rb

@@ -21,6 +21,7 @@ require "tonic/rails/health"
 require "tonic/rails/reflection"
 require "tonic/rails/cluster"
 require "tonic/rails/server"
+require "tonic/rails/client"
 
 module Tonic
   module Rails

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tonic-rails
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: x86_64-linux-gnu
 authors:
 - Matt Tanous
@@ -67,6 +67,8 @@ files:
 - lib/tonic/rails/3.4/tonic_rails_native.so
 - lib/tonic/rails/4.0/tonic_rails_native.so
 - lib/tonic/rails/base.rb
+- lib/tonic/rails/client.rb
+- lib/tonic/rails/client/retry_policy.rb
 - lib/tonic/rails/cluster.rb
 - lib/tonic/rails/configuration.rb
 - lib/tonic/rails/health.rb