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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5aa7de65014581bfcd5575510bdcd6ec9ec4bd0ab81473e49077188093ff436a
-  data.tar.gz: eaf8038cfa3d9b62e16d575b4e56001bb9873cdc30ed19f9ab43967869d907f5
+  metadata.gz: 69a7ded16d01d0e9fc54dd2a24eecc85b36aa49362c4984dd5f4f234429e24a4
+  data.tar.gz: 267553cdb615846fd3e3c39c0e3417154cce6e7cbdb470b42b4a7229717908d1
 SHA512:
-  metadata.gz: cc4417d8c41fb9fb0e363ffb0605ac745d9b564e63a413b7b86e6d2d8a0c861f035f2553a6df8602466ead880cd58d1cc50bfc798536e97bc967d67b7b107b0f
-  data.tar.gz: 484f38fa65491cf4e34e32e30e35af03ee7b5de3e354b33e4c23fbbe1df50b55a7dc9d19411f59ef1db04767fca9eb69d90facdae940e79f4f0cd6f92c77700c
+  metadata.gz: 50ad4688167a303a40c8b64bca81de9301c997c9bc29e2d355cd773bcbec1696f029c357ec343fc96fa1eca9b1e936ba40e8e602a015dc49a804f6428090e425
+  data.tar.gz: d14c5ab406b10f432169da4917c44647cbca451c1e6d1b607b9ee1fab8d1038edfe998f2f7b597edf94404323a0654f9d6e98b8c18d682c747c7cf0b4bf042e1

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/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/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.rb

@@ -0,0 +1,371 @@
+# 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| ... }
+    #
+    # 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
+
+      # @return [String] "host:port"
+      attr_reader :address
+
+      # @return [Numeric, nil] default deadline in seconds
+      attr_reader :deadline
+
+      # @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
+      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)
+        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
+        @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)
+        message = request_message(path, input, request)
+        metadata = call_metadata(metadata)
+        timeout_ms = remaining_ms(deadline_at(deadline))
+
+        Instrumentation.instrument_request(path, address, metadata) do
+          code, error_message, response, headers, trailers, details =
+            @native.unary(path, input.encode(message), metadata, timeout_ms)
+          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: {})
+        message = 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)
+
+        ServerStream.new(path) do |stream, block|
+          timeout_ms = remaining_ms(deadline_at)
+          Instrumentation.instrument_request(path, address, metadata) do
+            native = @native.server_streaming(path, input.encode(message), metadata, timeout_ms)
+            begin
+              while (bytes = native.next)
+                block.call(decode_response(output, bytes, path))
+              end
+              code, error_message, _, headers, trailers, details = native.result
+              trailers = decode_metadata(trailers)
+              stream.finish(decode_metadata(headers), trailers)
+              check_status!(code, error_message, trailers, details)
+            ensure
+              native.close
+            end
+          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 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: {}, **fields|
+                request = rpc_request(name, request, fields)
+                @client.server_streaming(path, input, output, request, deadline: deadline, metadata: metadata)
+              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, **fields|
+                request = rpc_request(name, request, fields)
+                @client.unary(path, input, output, request, deadline: deadline, metadata: metadata,
+                                                            return_call: return_call)
+              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

data/lib/tonic/rails/instrumentation.rb

@@ -24,17 +24,32 @@ 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.
+      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
+
+      # @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 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
+        payload = { path: path, service: service, rpc: rpc, metadata: metadata, code: nil, status: nil, **extra }
+        ActiveSupport::Notifications.instrument(event, payload) do
           result = yield
           payload[:code] = 0
           payload[:status] = :ok

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.6.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.6.0
 platform: x86_64-linux-gnu
 authors:
 - Matt Tanous
@@ -67,6 +67,7 @@ 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/cluster.rb
 - lib/tonic/rails/configuration.rb
 - lib/tonic/rails/health.rb