tonic-rails 0.1.0-aarch64-linux-gnu

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0b055719a1717245ea8a65525f12c18389f8209de1a17a1f474c35d76dff2a20
+  data.tar.gz: 1021a911c9ea4e1d2f3c86e8ce1d6b643d2d209807bda77782c87f827fcf1900
+SHA512:
+  metadata.gz: 74deac3a8dba345a0a690571cdb56fc387b07de8643bef429f364b4ae9cffbb1e401ae0939a19cb33bc3558a34c8ba74434cb3068c4c71200c43a51519368473
+  data.tar.gz: 05abf283904c216b82bb94265cef50ec79886f02c0e585df343148fc7f7feaf8751309a671fe57a60255c198ef5d44fa1b0b2e0a26d5eae259d222f42162e144

data/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
+project follows [Semantic Versioning](https://semver.org/). Until 1.0,
+minor versions may contain breaking changes.
+
+## [Unreleased]
+
+## [0.1.0]
+
+First public release.
+
+### Serving
+
+- gRPC server for Rails built on tonic 0.14 (HTTP/2, TLS via rustls,
+  keepalive, flow control), with Ruby handlers running on a pool of
+  dispatch threads inside the Rails executor.
+- Unary, server-streaming, client-streaming and bidirectional RPCs, with
+  backpressure in both directions and incremental streaming.
+- Handlers declared with `rpc_service` (read from the protobuf descriptor
+  pool) or individual `rpc` calls; requests as Hashes or, with
+  `request_format :message`, protobuf messages; responses as either.
+- Routes registered at runtime: no service definitions are compiled into
+  the native extension.
+- Built-in `grpc.health.v1` (per service, flips to NOT_SERVING on
+  shutdown) and opt-in `grpc.reflection.v1` generated from loaded
+  descriptors.
+- Interceptors, request metadata, client deadlines (`deadline_ms`,
+  `deadline_exceeded?`) and shutdown awareness (`cancelled?`).
+- `Tonic::Rails::Testing.call` for in-process handler tests.
+- Railtie: `config.tonic_rails.*` settings, Rails logger and error
+  reporter, code reloading support, rake tasks `tonic_rails:serve`,
+  `tonic_rails:routes` and `tonic_rails:compile_protos`.
+
+### Production behaviour
+
+- Graceful shutdown on SIGTERM/SIGINT: health flips to NOT_SERVING, new
+  connections are refused, in-flight calls drain for `drain_timeout`.
+- Limits: `max_message_size` (also caps gzip-decompressed size),
+  `max_connections`, `concurrency_limit_per_connection`, request metadata
+  size, and `dispatch_queue_size` load shedding (`RESOURCE_EXHAUSTED`).
+- TLS and mutual TLS (`tls_client_ca_path`). Invalid TLS configuration
+  stops startup; the server never falls back to plaintext.
+- Unexpected exceptions (in handlers or interceptors) reach clients only
+  as `INTERNAL: internal error`; details are logged and reported.
+- `grpc-message` is percent-encoded per the gRPC spec.
+- 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.1.0...HEAD
+[0.1.0]: https://github.com/CodingAnarchy/tonic-rails/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Tanous
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,391 @@
+# tonic-rails
+
+[![CI](https://github.com/CodingAnarchy/tonic-rails/actions/workflows/ci.yml/badge.svg)](https://github.com/CodingAnarchy/tonic-rails/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/tonic-rails.svg)](https://rubygems.org/gems/tonic-rails)
+
+Serve gRPC from your Rails app, with the transport handled by
+[tonic], Rust's production gRPC stack.
+
+Think of it like Puma for gRPC. Puma handles sockets and HTTP so your
+controllers only see requests. tonic-rails does the same for gRPC:
+HTTP/2, TLS, flow control, keepalives, health checks and reflection all
+run in Rust, outside the GVL. Your handlers are plain Ruby classes that
+receive protobuf messages and return them, inside the Rails executor,
+with your models, caches and error reporting all available.
+
+```ruby
+class ItemService
+  include Tonic::Rails::Base
+  rpc_service "demo.v1.ItemService"
+  request_format :message
+
+  def get_item(request)
+    item = Item.find_by(id: request.id)
+    raise Tonic::Rails::RpcError.new("item not found", code: :not_found) unless item
+
+    Demo::V1::Item.new(id: item.id, name: item.name)
+  end
+end
+```
+
+## Why tonic-rails
+
+- **Fast where it counts.** Transport overhead is small: an empty RPC
+  runs at roughly 75–80% of a pure-Rust tonic server's throughput. I/O-bound
+  handlers scale with dispatch threads because Ruby releases the GVL
+  while waiting. See [PERF.md](PERF.md).
+- **All four RPC kinds.** Unary, server streaming, client streaming and
+  bidirectional streaming, with backpressure in both directions.
+- **Production defaults.** Graceful draining on SIGTERM, health checks
+  that flip to NOT_SERVING during shutdown, deadlines, message size and
+  connection limits, load shedding, gzip, TLS and mutual TLS.
+- **Safe by default.** Unexpected exceptions reach clients as a generic
+  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.
+- **No Rust toolchain needed** on the platforms we ship precompiled gems
+  for (Linux and macOS, x86_64 and arm64).
+
+## Installation
+
+```ruby
+# Gemfile
+gem "tonic-rails"
+gem "google-protobuf"
+```
+
+Requires Ruby 3.3+ and Rails 7.1+ (or just ActiveSupport, outside Rails).
+On platforms without a precompiled gem, installation builds the
+extension from source, which needs a [Rust toolchain](https://rustup.rs).
+
+To generate Ruby classes from your `.proto` files you also need `protoc`
+(the Protocol Buffers compiler) during development.
+
+## Quick start
+
+### 1. Define the service
+
+```protobuf
+// app/protos/items.proto
+syntax = "proto3";
+package demo.v1;
+
+message Item { int64 id = 1; string name = 2; }
+message GetItemRequest { int64 id = 1; }
+
+service ItemService {
+  rpc GetItem(GetItemRequest) returns (Item);
+}
+```
+
+Generate the Ruby classes:
+
+```sh
+bin/rails tonic_rails:compile_protos   # app/protos → lib/grpc
+```
+
+Generated files `require` each other by name, so keep them out of the
+autoload paths and put their directory on the load path:
+
+```ruby
+# config/application.rb
+$LOAD_PATH.unshift(File.expand_path("../lib/grpc", __dir__))
+
+module MyApp
+  class Application < Rails::Application
+    config.autoload_lib(ignore: %w[grpc])
+  end
+end
+```
+
+### 2. Write a handler
+
+Handlers live anywhere Rails autoloads from; `app/grpc` is a good home.
+Each RPC maps to a snake_case method.
+
+```ruby
+# app/grpc/item_service.rb
+require "items_pb"
+
+class ItemService
+  include Tonic::Rails::Base
+
+  rpc_service "demo.v1.ItemService"   # every RPC, read from the descriptor
+  request_format :message             # receive protobuf messages
+
+  def get_item(request)
+    item = Item.find(request.id)
+    Demo::V1::Item.new(id: item.id, name: item.name)
+  rescue ActiveRecord::RecordNotFound
+    raise Tonic::Rails::RpcError.new("item #{request.id} not found", code: :not_found)
+  end
+end
+```
+
+### 3. Register and run
+
+Register handlers in `to_prepare` so they work with code reloading:
+
+```ruby
+# config/initializers/tonic_rails.rb
+Rails.application.config.to_prepare do
+  Tonic::Rails.server.register(ItemService)
+end
+```
+
+```sh
+bin/rails tonic_rails:serve    # serves on 0.0.0.0:50051
+bin/rails tonic_rails:routes   # lists registered methods
+```
+
+Run it as its own process (a separate Procfile entry, container or
+Kubernetes deployment) next to your web server.
+
+The [example app](example/) is a complete, runnable version of all of the
+above.
+
+## Handlers
+
+### Requests and responses
+
+By default handlers receive a string-keyed Hash. With
+`request_format :message` they receive the decoded protobuf message
+instead, which is faster and type-safe. Either way, return a protobuf
+message or a Hash:
+
+```ruby
+def get_item(request)
+  { "id" => request.id, "name" => "Widget" }   # a Hash works too
+end
+```
+
+A fresh handler instance serves each call, so instance variables never
+leak between requests.
+
+### Declaring RPCs
+
+`rpc_service "package.Service"` reads every RPC (and its streaming kind)
+from the generated descriptor. To declare RPCs one at a time instead:
+
+```ruby
+class ItemService
+  include Tonic::Rails::Base
+  service "demo.v1.ItemService"
+
+  rpc :GetItem, Demo::V1::GetItemRequest, Demo::V1::Item
+  rpc :ListItems, Demo::V1::ListItemsRequest, Demo::V1::Item, stream: :server
+end
+```
+
+RPCs declared without a handler method answer `UNIMPLEMENTED`.
+
+### Streaming
+
+Server streaming: return any Enumerable. Messages go out as you produce
+them, and if the client reads slowly your handler waits (without holding
+the GVL) instead of buffering everything in memory.
+
+```ruby
+def list_items(request)
+  Enumerator.new do |stream|
+    Item.where(tag: request.tag).find_each do |item|
+      break if cancelled?   # the server is shutting down
+      stream << Demo::V1::Item.new(id: item.id, name: item.name)
+    end
+  end
+end
+```
+
+Client streaming: the argument is an Enumerator that yields each request
+as it arrives.
+
+```ruby
+def import_items(requests)
+  created = requests.count { |r| Item.create!(name: r.name) }
+  Demo::V1::ImportItemsResponse.new(created: created)
+end
+```
+
+Bidirectional streaming combines both: take the request Enumerator and
+return an Enumerable. Responses can be sent before the client finishes
+sending.
+
+```ruby
+def chat(messages)
+  Enumerator.new do |out|
+    messages.each { |m| out << Demo::V1::Reply.new(text: m.text.upcase) }
+  end
+end
+```
+
+### Errors
+
+Raise `Tonic::Rails::RpcError` to end a call with a status:
+
+```ruby
+raise Tonic::Rails::RpcError.new("name is required", code: :invalid_argument)
+```
+
+Codes are the standard gRPC names (`:not_found`, `:permission_denied`,
+`:unauthenticated`, `:unavailable`, and so on) or their numbers. The
+message goes to the client, so keep internal details out of it.
+
+Any other exception becomes `INTERNAL` with the message `internal error`.
+The real exception is logged and passed to `Rails.error.report`, so your
+error tracker sees it.
+
+### Metadata, deadlines and shutdown
+
+```ruby
+def get_item(request)
+  token = grpc_metadata["authorization"]   # request headers, lower-case
+  deadline_ms                                # ms left before the client's deadline, or nil
+  deadline_exceeded?                         # true once it has passed
+  cancelled?                                 # true while the server shuts down
+end
+```
+
+When the deadline passes, the client gets `DEADLINE_EXCEEDED` right away;
+check `deadline_exceeded?` in long loops to stop wasted work.
+
+### Interceptors
+
+Interceptors wrap every call, outermost first. Call `next_call` to
+continue, or raise to reject:
+
+```ruby
+Tonic::Rails.configure do |config|
+  config.interceptors << lambda do |path, metadata, next_call|
+    unless valid_token?(metadata["authorization"])
+      raise Tonic::Rails::RpcError.new("invalid token", code: :unauthenticated)
+    end
+    next_call.call
+  end
+end
+```
+
+## Testing handlers
+
+`Tonic::Rails::Testing` calls a handler in-process, with real protobuf
+encoding, no network and no native extension:
+
+```ruby
+require "tonic/rails/testing"
+
+response = Tonic::Rails::Testing.call(ItemService, :GetItem, { id: 1 })
+expect(response.name).to eq("Widget")
+
+expect { Tonic::Rails::Testing.call(ItemService, :GetItem, { id: 0 }) }
+  .to raise_error(Tonic::Rails::RpcError) { |e| expect(e.code_name).to eq(:not_found) }
+
+# Streaming: pass an Array of requests, get an Array of responses
+Tonic::Rails::Testing.call(ItemService, :ImportItems, [{ name: "a" }, { name: "b" }])
+```
+
+## Configuration
+
+Set options in `config/application.rb` or an environment file:
+
+```ruby
+config.tonic_rails.bind_address = "0.0.0.0:50051"
+config.tonic_rails.dispatch_threads = ENV.fetch("RAILS_MAX_THREADS", 5).to_i
+```
+
+or with a block (which runs after, and wins over, `config.tonic_rails`):
+
+```ruby
+Tonic::Rails.configure do |config|
+  config.tls_cert_path = "/etc/tls/tls.crt"
+  config.tls_key_path = "/etc/tls/tls.key"
+end
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `bind_address` | `"0.0.0.0:50051"` | Address to listen on |
+| `dispatch_threads` | `4` | Ruby threads running handlers; match your database pool |
+| `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) |
+| `max_connections` | `64` | Concurrent connections; `0` = unlimited |
+| `concurrency_limit_per_connection` | `32` | Concurrent streams per connection; `0` = unlimited |
+| `tls_cert_path`, `tls_key_path` | `nil` | PEM certificate and key; set both to enable TLS |
+| `tls_client_ca_path` | `nil` | PEM CA bundle; requires client certificates (mutual TLS) |
+| `drain_timeout` | `10` | Seconds to let in-flight calls finish on shutdown |
+| `keepalive_interval`, `keepalive_timeout` | `15`, `5` | HTTP/2 PING interval and timeout, seconds |
+| `compression` | `false` | gzip responses over 1 KiB for clients that accept it |
+| `reflection` | `false` | Serve `grpc.reflection.v1`; exposes your schema |
+| `interceptors` | `[]` | See [Interceptors](#interceptors) |
+| `log_requests` | `false` | Log every call to stderr (errors are always logged) |
+| `auto_start` | `false` | Start inside `rails server` (see below) |
+
+### Sizing threads
+
+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.
+
+### auto_start
+
+`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 prefer a dedicated `tonic_rails:serve`
+process: forking servers such as Puma in cluster mode would need to
+start one per worker.
+
+## Operations
+
+- **Health checks.** `grpc.health.v1.Health` reports `SERVING` for the
+  server (`""`) and every registered service, and flips to `NOT_SERVING`
+  as soon as shutdown begins. Point your load balancer or Kubernetes
+  gRPC probes at it.
+- **Graceful shutdown.** On SIGTERM or SIGINT the server stops
+  accepting connections, tells clients to go away (HTTP/2 GOAWAY), lets
+  in-flight calls finish for up to `drain_timeout` seconds, then exits.
+- **Load shedding.** When every dispatch thread is busy and the queue is
+  full, new calls fail fast with `RESOURCE_EXHAUSTED` instead of piling up.
+- **Stats.** `Tonic::Rails.server.stats` returns counters for totals,
+  successes, errors, cancellations, deadline and resource errors, active
+  connections and queued calls.
+- **Reflection.** Turn on `reflection` in development to use
+  [grpcurl](https://github.com/fullstorydev/grpcurl) without proto files.
+
+## How it works
+
+```
+ client ──HTTP/2──▶ tonic (Rust, no GVL)
+                     ├─ TLS, flow control, keepalive, limits
+                     ├─ grpc.health.v1, grpc.reflection.v1
+                     └─ everything else ─▶ queue ─▶ Ruby dispatch thread
+                                                   (takes the GVL)
+                                                   decode → handler → encode
+```
+
+Rust never decodes your messages; it passes raw protobuf bytes to Ruby,
+where the `google-protobuf` C extension decodes them once. Routes come
+from the handlers you register, so nothing about your services is
+compiled into the extension.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake compile   # build the extension (needs Rust)
+bundle exec rake           # Ruby specs + Rust unit tests
+bundle exec rubocop
+bundle exec rake cargo:lint
+```
+
+The integration specs start real servers and call them with the official
+`grpc` gem; the reflection specs also need `grpcurl` on your PATH.
+Benchmarks live in [bench/](bench/) (see [PERF.md](PERF.md)). See
+[CONTRIBUTING.md](CONTRIBUTING.md) for more.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+[tonic]: https://github.com/hyperium/tonic

data/lib/tonic/rails/base.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/class/attribute"
+require "active_support/core_ext/hash/keys"
+require "active_support/core_ext/string/inflections"
+
+module Tonic
+  module Rails
+    # Include in a class to define a gRPC service handler.
+    #
+    #   class ProductService
+    #     include Tonic::Rails::Base
+    #     rpc_service "shop.ProductService"   # every RPC from the descriptor
+    #
+    #     def get_product(request)
+    #       Shop::Product.new(id: request.id, title: "Widget")
+    #     end
+    #   end
+    #
+    # Handler methods are the snake_case RPC names.  A new instance is
+    # created for every call, so instance variables never leak between
+    # requests.
+    #
+    # Requests are decoded protobuf messages when `request_format :message`
+    # is set (fastest), or string-keyed Hashes by default.  Handlers may
+    # return either a protobuf message or a Hash; streaming handlers
+    # return any Enumerable of them.
+    module Base
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.class_attribute :grpc_service_name, instance_writer: false
+        base.class_attribute :grpc_rpcs, instance_writer: false, default: {}
+        base.class_attribute :grpc_request_format, instance_writer: false, default: :hash
+      end
+
+      module ClassMethods
+        # @param name [String] fully-qualified service name, e.g. "shop.ProductService"
+        def service(name)
+          self.grpc_service_name = name.to_s
+        end
+
+        # How requests are passed to handlers.
+        # @param format [Symbol] :hash (string-keyed Hash, the default) or
+        #   :message (the decoded protobuf message — avoids a conversion)
+        def request_format(format)
+          unless %i[hash message].include?(format)
+            raise ArgumentError, "request_format must be :hash or :message, got #{format.inspect}"
+          end
+
+          self.grpc_request_format = format
+        end
+
+        # Declare one RPC.
+        # @param method_name [Symbol, String] RPC name as in the .proto, e.g. :GetProduct
+        # @param request_class [Class] protobuf request message class
+        # @param response_class [Class] protobuf response message class
+        # @param stream [Symbol, nil] :server, :client, :bidi, or nil for unary
+        def rpc(method_name, request_class, response_class, stream: nil)
+          unless [nil, :server, :client, :bidi].include?(stream)
+            raise ArgumentError, "stream must be :server, :client, :bidi, or nil, got #{stream.inspect}"
+          end
+
+          name = method_name.to_s
+          self.grpc_rpcs = grpc_rpcs.merge(
+            name => {
+              request: request_class,
+              response: response_class,
+              request_stream: %i[client bidi].include?(stream),
+              response_stream: %i[server bidi].include?(stream),
+              handler: name.underscore.to_sym,
+            }.freeze,
+          )
+        end
+
+        # Declare the service and every RPC in it from the protobuf
+        # descriptor pool.  Load the generated `_pb.rb` file first.
+        #
+        # @param full_name [String] fully-qualified service name
+        def rpc_service(full_name)
+          descriptor = Google::Protobuf::DescriptorPool.generated_pool.lookup(full_name.to_s)
+          unless descriptor.is_a?(Google::Protobuf::ServiceDescriptor)
+            raise NotConfiguredError,
+                  "rpc_service: #{full_name} is not a known protobuf service. " \
+                  "Require its generated _pb.rb file (protoc --ruby_out) before declaring the handler."
+          end
+
+          service(full_name)
+          descriptor.each do |method|
+            stream = if method.client_streaming && method.server_streaming
+              :bidi
+            elsif method.client_streaming
+              :client
+            elsif method.server_streaming
+              :server
+            end
+            rpc(method.name, method.input_type.msgclass, method.output_type.msgclass, stream: stream)
+          end
+        end
+
+        # @api private  Called by Server#register.
+        def register_on(router)
+          raise NotConfiguredError, "#{self} has no service name; call `service` or `rpc_service`" unless grpc_service_name
+          raise NotConfiguredError, "#{self} declares no RPCs" if grpc_rpcs.empty?
+
+          router.add(self)
+        end
+      end
+
+      # gRPC request metadata (lower-case header names).  Binary (`-bin`)
+      # values are base64-encoded, as sent on the wire.
+      # @return [Hash{String=>String}]
+      attr_reader :grpc_metadata
+
+      # Milliseconds left before the client's deadline, or nil if the
+      # client did not set one.
+      # @return [Integer, nil]
+      def deadline_ms
+        return unless @grpc_deadline_at
+
+        remaining = ((@grpc_deadline_at - Process.clock_gettime(Process::CLOCK_MONOTONIC)) * 1000).to_i
+        remaining.negative? ? 0 : remaining
+      end
+
+      # True when the deadline has passed.
+      def deadline_exceeded?
+        !deadline_ms.nil? && deadline_ms.zero?
+      end
+
+      # True when the server is shutting down.
+      def cancelled?
+        Tonic::Rails.cancelled?
+      end
+
+      # @api private
+      # Run one RPC.  `reader` yields raw request messages (`#next`, then
+      # `#error` once exhausted); `sender` accepts raw response messages
+      # (`#push`) for server-streaming RPCs.
+      # @return [String, nil] the encoded unary response, or nil when
+      #   messages were streamed through `sender`
+      def call_rpc(rpc_name, metadata:, reader:, sender: nil, timeout_ms: nil)
+        spec = self.class.grpc_rpcs[rpc_name.to_s]
+        raise RpcError.new("method not implemented", code: :unimplemented) unless spec
+        raise RpcError.new("method #{rpc_name} not implemented", code: :unimplemented) unless respond_to?(spec[:handler])
+
+        @grpc_metadata = metadata
+        @grpc_deadline_at = timeout_ms && (Process.clock_gettime(Process::CLOCK_MONOTONIC) + (timeout_ms / 1000.0))
+
+        request = if spec[:request_stream]
+          Enumerator.new do |y|
+            while (message = read_request(reader, spec))
+              y << message
+            end
+          end
+        else
+          read_request(reader, spec) || raise(RpcError.new("missing request message", code: :invalid_argument))
+        end
+
+        result = public_send(spec[:handler], request)
+
+        if spec[:response_stream]
+          unless result.respond_to?(:each)
+            raise TypeError, "streaming handler #{self.class}##{spec[:handler]} must return an Enumerable, got #{result.class}"
+          end
+
+          result.each { |item| push_response(sender, encode_response(item, spec)) }
+          nil
+        else
+          encode_response(result, spec)
+        end
+      rescue RpcError
+        raise
+      rescue StandardError => e
+        Tonic::Rails.log_exception(e, "#{self.class}##{rpc_name}")
+        raise RpcError.new("internal error", code: :internal)
+      end
+
+      private
+
+      def read_request(reader, spec)
+        bytes = reader.next
+        if bytes.nil?
+          code, message = reader.error
+          raise RpcError.new(message, code: code) if code
+
+          return
+        end
+
+        message = begin
+          spec[:request].decode(bytes)
+        rescue Google::Protobuf::ParseError, ArgumentError
+          raise RpcError.new("invalid protobuf request", code: :invalid_argument)
+        end
+        self.class.grpc_request_format == :message ? message : message.to_h.deep_stringify_keys
+      end
+
+      def encode_response(item, spec)
+        klass = spec[:response]
+        message = case item
+        when klass then item
+        when Hash then klass.new(item)
+        else
+          raise TypeError, "#{self.class}##{spec[:handler]} must return a #{klass} or Hash, got #{item.class}"
+        end
+        klass.encode(message)
+      end
+
+      def push_response(sender, bytes)
+        sender.push(bytes)
+      rescue IOError
+        # The client went away; nothing left to deliver to.
+        raise RpcError.new("client cancelled the stream", code: :cancelled)
+      end
+    end
+  end
+end