tonic-rails 0.1.0-x86_64-linux-gnu → 0.2.0-x86_64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b80385e6e34361d398f683ec43379d519558c45f7762280c278bb52c545316f6
-  data.tar.gz: 1f25a57bf202c59274c178981967aeee274d33ab85aaf6517ca3261ae115a8ae
+  metadata.gz: 73ed3d0d421cd1cb77193b7d5025925cbe8737022553d28f7c95bd0d7ca2242a
+  data.tar.gz: e75d6f30c34e225b6668cdbe7f8072c22b5a5b1e53c782962f4327873cfcf7b2
 SHA512:
-  metadata.gz: 9a6f385bfd4b2fe956e225888cca22663302b31f6a8c3ca97c3edb3a6f6b5ec13ba1224cc37788724ababd4c518e9eaf06f6234c4aa9d380ec6aeffc9b959af1
-  data.tar.gz: a9e4c94967a476ceb84d11135fe3c6a0755219c3808736692d656df6683587d8e362dd00bb3b8f6b8f1ddddf8a0625fdc0bf6c0918c1529b5e97d9a24152baad
+  metadata.gz: d66dbcc4d4bd4721d007fd0ace7004fc2af5ae1c9f209c082e2004d38892fa96373c22375db9da6dbeae358d93b9a0f69c30ba7f3309f0a8bed3615dcb9c11a3
+  data.tar.gz: 209db51bbf3305ed9aeba24a9c407653f08397b875490d295e3ebccaf3667182869ee5a950fe78a747c3b7d3799f5ae879aa9453dc594fbbd8ddedca66bb3fa9

data/CHANGELOG.md

@@ -7,7 +7,43 @@ minor versions may contain breaking changes.
 
 ## [Unreleased]
 
-## [0.1.0]
+## [0.2.0] - 2026-10-11
+
+### Added
+
+- Instrumentation: every RPC publishes a `process_rpc.tonic_rails`
+  ActiveSupport::Notifications event (path, service, rpc, metadata, status,
+  code) for APM agents, OpenTelemetry and custom subscribers. With no
+  subscribers it costs nothing measurable.
+- Response metadata: handlers set `response_metadata` (headers) and
+  `trailing_metadata` (trailers, sent on success or failure).
+- Rich errors: `RpcError.new(..., metadata:, details:)` sends trailing
+  metadata and a `google.rpc.Status` with packed details in
+  `grpc-status-details-bin`, which official gRPC clients decode.
+- Puma plugin: `plugin :tonic_rails` in `config/puma.rb` runs the gRPC
+  server as a child process of Puma, in single and cluster mode, with
+  graceful stop and restart, and a shutdown if either side dies.
+- Windows: precompiled `x64-mingw-ucrt` gems, tested in CI.
+- `Tonic::Rails::Testing.invoke` returns the response together with its
+  headers and trailers.
+
+### Changed
+
+- Response headers are sent with the handler's first output instead of
+  before the handler runs, so handlers can set them. The client deadline
+  applies while waiting.
+- `log_requests` logs one line per RPC through the configured (Rails)
+  logger instead of stderr.
+- Transport events from the native extension (rejected calls, expired
+  deadlines, refused connections, faults) go through the configured (Rails)
+  logger with severities instead of stderr. Handler outcomes, such as a
+  `NOT_FOUND` raised by a handler, are no longer logged by the transport;
+  use `log_requests` or the instrumentation event for those.
+- `Server#stop` signals shutdown through a queue instead of a pipe, so
+  signal handling works the same on every platform.
+- Dependencies: magnus 0.9, google-protobuf 4.36.
+
+## [0.1.0] - 2026-10-10
 
 First public release.
 
@@ -48,5 +84,6 @@ 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.1.0...HEAD
+[Unreleased]: https://github.com/CodingAnarchy/tonic-rails/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/CodingAnarchy/tonic-rails/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/CodingAnarchy/tonic-rails/releases/tag/v0.1.0

data/README.md

@@ -30,10 +30,11 @@ 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).
+- **Fast where it counts.** Inside a Rails app, light RPCs ran at 5–6×
+  the throughput of an equivalent Rails JSON endpoint and 1.4–3× the
+  official `grpc` gem, and server streaming at 4–7× the `grpc` gem.
+  Handlers dominated by slow queries or heavy object building see smaller
+  gains. 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
@@ -44,7 +45,7 @@ end
   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).
+  for: Linux and macOS (x86_64 and arm64) and Windows (x64).
 
 ## Installation
 
@@ -139,7 +140,8 @@ 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.
+Kubernetes deployment) next to your web server, or let Puma run it for
+you (see [Running with Puma](#running-with-puma)).
 
 The [example app](example/) is a complete, runnable version of all of the
 above.
@@ -248,6 +250,39 @@ end
 When the deadline passes, the client gets `DEADLINE_EXCEEDED` right away;
 check `deadline_exceeded?` in long loops to stop wasted work.
 
+### Response metadata
+
+Set response headers and trailers from a handler:
+
+```ruby
+def get_item(request)
+  response_metadata["x-cache"] = "hit"           # headers
+  trailing_metadata["x-cost-ms"] = "3"           # trailers, sent with the status
+  response_metadata["x-trace-bin"] = trace_bytes # -bin names take binary values
+  Demo::V1::Item.new(id: request.id)
+end
+```
+
+For streaming responses, set headers before the first message is sent.
+Trailers are sent whether the call succeeds or fails.
+
+### Rich errors
+
+`RpcError` can carry trailing metadata and
+[rich error details](https://grpc.io/docs/guides/error/#richer-error-model):
+protobuf messages packed into a `google.rpc.Status` in the standard
+`grpc-status-details-bin` trailer, which official gRPC clients decode for
+you.
+
+```ruby
+raise Tonic::Rails::RpcError.new(
+  "invalid item",
+  code: :invalid_argument,
+  metadata: { "x-request-id" => request_id },
+  details: [Google::Rpc::BadRequest.new(field_violations: violations)],
+)
+```
+
 ### Interceptors
 
 Interceptors wrap every call, outermost first. Call `next_call` to
@@ -280,6 +315,11 @@ expect { Tonic::Rails::Testing.call(ItemService, :GetItem, { id: 0 }) }
 
 # Streaming: pass an Array of requests, get an Array of responses
 Tonic::Rails::Testing.call(ItemService, :ImportItems, [{ name: "a" }, { name: "b" }])
+
+# Response metadata
+result = Tonic::Rails::Testing.invoke(ItemService, :GetItem, { id: 1 })
+result.headers["x-cache"]    # => "hit"
+result.trailers["x-cost-ms"] # => "3"
 ```
 
 ## Configuration
@@ -316,8 +356,8 @@ end
 | `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) |
+| `log_requests` | `false` | Log one line per call through `logger` (unexpected exceptions are always logged) |
+| `auto_start` | `false` | Start in a thread of `rails server`; for development (see [auto_start](#auto_start)) |
 
 ### Sizing threads
 
@@ -328,13 +368,31 @@ 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.
 
+### Running with Puma
+
+Add the plugin to `config/puma.rb`:
+
+```ruby
+plugin :tonic_rails
+```
+
+Puma then runs the gRPC server as one child process, in single and cluster
+mode alike, so gRPC gets its own process and GVL instead of competing with
+web workers. It starts after Puma boots and drains gracefully when Puma
+stops or restarts. If the gRPC process dies, Puma shuts down too, so your
+supervisor restarts both. It works with `rails server`, plain `puma`, and
+`preload_app!`. (Not on Windows, which has no `fork()`: run
+`tonic_rails:serve` as its own process there.)
+
+For larger deployments, a dedicated `bin/rails tonic_rails:serve` process
+(scaled separately) is still the most flexible option.
+
 ### 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.
+development; in production use the Puma plugin or a dedicated process.
+Don't combine it with the plugin.
 
 ## Operations
 
@@ -347,12 +405,43 @@ start one per worker.
   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.
+- **Instrumentation.** Every RPC publishes a `process_rpc.tonic_rails`
+  event through `ActiveSupport::Notifications`, so APM agents,
+  OpenTelemetry and your own subscribers can trace calls. See
+  [Instrumentation](#instrumentation).
+- **Logs.** Everything goes through your (Rails) logger. With
+  `log_requests = true`, each RPC logs one line, e.g.
+  `gRPC /demo.v1.ItemService/GetItem OK in 1.4ms`. Calls the transport
+  rejects before reaching Ruby (unknown methods, a full queue, expired
+  deadlines, oversized messages, refused connections) are always logged,
+  at info for client-caused problems, warn for overload and error for faults.
 - **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.
 
+## Instrumentation
+
+Every RPC is wrapped in an `ActiveSupport::Notifications` event, inside the
+Rails executor, so subscribers see the same context as your handler:
+
+```ruby
+ActiveSupport::Notifications.subscribe("process_rpc.tonic_rails") do |event|
+  event.payload[:path]      # "/demo.v1.ItemService/GetItem"
+  event.payload[:service]   # "demo.v1.ItemService"
+  event.payload[:rpc]       # "GetItem"
+  event.payload[:metadata]  # request metadata
+  event.payload[:status]    # :ok, :not_found, :internal, ...
+  event.payload[:code]      # numeric gRPC status
+  event.duration            # milliseconds
+end
+```
+
+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.
+
 ## How it works
 
 ```

data/lib/puma/plugin/tonic_rails.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "puma/plugin"
+
+# Runs the tonic-rails gRPC server alongside Puma:
+#
+#   # config/puma.rb
+#   plugin :tonic_rails
+#
+# The gRPC server runs as one child process of the Puma master, in single
+# and cluster mode alike, so it has its own GVL and never competes with web
+# workers.  It starts once Puma has booted, drains gracefully when Puma
+# stops or restarts, stops itself if Puma goes away, and if it dies
+# unexpectedly Puma shuts down too, so a supervisor can restart both.
+Puma::Plugin.create do
+  def start(launcher)
+    @launcher = launcher
+    unless Process.respond_to?(:fork)
+      log "tonic-rails: the Puma plugin needs fork(), which this platform lacks; " \
+          "run `bin/rails tonic_rails:serve` as a separate process instead"
+      return
+    end
+
+    @puma_pid = Process.pid
+    @grpc_pid = nil
+
+    events = launcher.events
+    if events.respond_to?(:after_booted) # Puma 7+
+      events.after_booted { start_grpc }
+      events.after_stopped { stop_grpc }
+      events.before_restart { stop_grpc }
+    else
+      events.on_booted { start_grpc }
+      events.on_stopped { stop_grpc }
+      events.on_restart { stop_grpc }
+    end
+
+    in_background { monitor_grpc }
+  end
+
+  private
+
+  def start_grpc
+    @grpc_pid = fork { run_grpc_server }
+    log "tonic-rails: gRPC server started (pid #{@grpc_pid})"
+  end
+
+  def run_grpc_server
+    # The web listeners belong to Puma; don't hold them open in this process.
+    @launcher.binder.ios.each { |io| io.close rescue nil } # rubocop:disable Style/RescueModifier
+    load_rails_app
+    Thread.new { stop_when_puma_exits }
+    Tonic::Rails.server.start
+  end
+
+  # `rails server` and preload_app! boot the app before forking; plain
+  # `puma` in cluster mode does not, so boot it here.
+  def load_rails_app
+    return if defined?(Rails.application) && Rails.application&.initialized?
+
+    require File.expand_path("config/environment", Dir.pwd)
+  end
+
+  # Puma fires its stop hooks from its TERM trap handler, so this must
+  # not block indefinitely: allow the server's drain timeout plus a margin,
+  # then kill it.
+  def stop_grpc
+    pid = @grpc_pid
+    return unless pid
+
+    @grpc_pid = nil
+    log "tonic-rails: stopping gRPC server (pid #{pid})"
+    Process.kill(:TERM, pid)
+    deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + stop_timeout
+    until Process.waitpid(pid, Process::WNOHANG)
+      if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+        log "tonic-rails: gRPC server (pid #{pid}) did not stop in #{stop_timeout}s; killing it"
+        Process.kill(:KILL, pid)
+        Process.wait(pid)
+        break
+      end
+      sleep 0.05
+    end
+  rescue Errno::ESRCH, Errno::ECHILD
+    nil
+  end
+
+  def stop_timeout
+    drain = defined?(Tonic::Rails) ? Tonic::Rails.configuration.drain_timeout.to_f : 10.0
+    drain + 5
+  end
+
+  def monitor_grpc
+    loop do
+      sleep 1
+      pid = @grpc_pid
+      next unless pid && Process.waitpid(pid, Process::WNOHANG)
+
+      @grpc_pid = nil
+      log "tonic-rails: gRPC server (pid #{pid}) exited unexpectedly; stopping Puma"
+      Process.kill(:TERM, @puma_pid)
+      break
+    rescue Errno::ECHILD
+      nil
+    end
+  end
+
+  def stop_when_puma_exits
+    sleep 1 while Process.ppid == @puma_pid
+    Tonic::Rails.server.stop
+  end
+
+  def log(message)
+    @launcher.log_writer.log(message)
+  end
+end

data/lib/tonic/rails/base.rb

@@ -111,6 +111,21 @@ module Tonic
       # @return [Hash{String=>String}]
       attr_reader :grpc_metadata
 
+      # Response headers (initial metadata) for this call.  For streaming
+      # responses, set them before the first message; for unary RPCs,
+      # anywhere in the handler.  `-bin` names take binary values.
+      # @return [Hash]
+      def response_metadata
+        @response_metadata ||= {}
+      end
+
+      # Trailing metadata, sent with the final status, whether the call
+      # succeeds or fails.
+      # @return [Hash]
+      def trailing_metadata
+        @trailing_metadata ||= {}
+      end
+
       # Milliseconds left before the client's deadline, or nil if the
       # client did not set one.
       # @return [Integer, nil]
@@ -143,39 +158,52 @@ module Tonic
         raise RpcError.new("method #{rpc_name} not implemented", code: :unimplemented) unless respond_to?(spec[:handler])
 
         @grpc_metadata = metadata
+        @grpc_sender = sender
+        @grpc_headers_sent = false
         @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
+        result = public_send(spec[:handler], build_request(reader, spec))
+        respond(result, spec, sender)
       rescue RpcError
         raise
       rescue StandardError => e
         Tonic::Rails.log_exception(e, "#{self.class}##{rpc_name}")
         raise RpcError.new("internal error", code: :internal)
+      ensure
+        attach_trailing_metadata
       end
 
       private
 
+      def build_request(reader, spec)
+        unless spec[:request_stream]
+          return read_request(reader, spec) || raise(RpcError.new("missing request message", code: :invalid_argument))
+        end
+
+        Enumerator.new do |y|
+          while (message = read_request(reader, spec))
+            y << message
+          end
+        end
+      end
+
+      # Unary: the encoded response.  Streaming: nil, after pushing each
+      # message through the sender.
+      def respond(result, spec, sender)
+        unless spec[:response_stream]
+          encoded = encode_response(result, spec)
+          send_response_headers
+          return encoded
+        end
+
+        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
+      end
+
       def read_request(reader, spec)
         bytes = reader.next
         if bytes.nil?
@@ -205,11 +233,30 @@ module Tonic
       end
 
       def push_response(sender, bytes)
+        send_response_headers
         sender.push(bytes)
       rescue IOError
         # The client went away; nothing left to deliver to.
         raise RpcError.new("client cancelled the stream", code: :cancelled)
       end
+
+      def send_response_headers
+        return if @grpc_headers_sent
+
+        @grpc_headers_sent = true
+        return if @response_metadata.nil? || @response_metadata.empty? || @grpc_sender.nil?
+
+        @grpc_sender.send_headers(Metadata.encode(@response_metadata))
+      end
+
+      # Runs in `ensure`, so it must never raise over the call's outcome.
+      def attach_trailing_metadata
+        return if @trailing_metadata.nil? || @trailing_metadata.empty? || @grpc_sender.nil?
+
+        @grpc_sender.add_trailers(Metadata.encode(@trailing_metadata))
+      rescue StandardError => e
+        Tonic::Rails.log_exception(e, "#{self.class} trailing metadata")
+      end
     end
   end
 end

data/lib/tonic/rails/configuration.rb

@@ -47,7 +47,8 @@ module Tonic
       # Concurrent HTTP/2 streams per connection.  0 = unlimited.  Default 32.
       attr_accessor :concurrency_limit_per_connection
 
-      # Log every request, not just errors, to stderr.  Default false.
+      # Log one line per RPC (path, status, duration) through `logger`.
+      # Unexpected exceptions are always logged.  Default false.
       attr_accessor :log_requests
 
       # Callables wrapping every RPC, outermost first:

data/lib/tonic/rails/instrumentation.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/notifications"
+
+module Tonic
+  module Rails
+    # Every RPC is wrapped in an ActiveSupport::Notifications event, so APM
+    # agents, OpenTelemetry and your own subscribers can observe it:
+    #
+    #   ActiveSupport::Notifications.subscribe("process_rpc.tonic_rails") do |event|
+    #     event.payload[:path]      # "/demo.v1.ItemService/GetItem"
+    #     event.payload[:service]   # "demo.v1.ItemService"
+    #     event.payload[:rpc]       # "GetItem"
+    #     event.payload[:metadata]  # request metadata Hash
+    #     event.payload[:code]      # gRPC status code, 0 = OK
+    #     event.payload[:status]    # :ok, :not_found, :internal, ...
+    #     event.duration            # milliseconds
+    #   end
+    #
+    # When a call fails, :exception_object holds the RpcError. If a handler
+    # raised something unexpected, that RpcError's #cause is the original
+    # exception.
+    module Instrumentation
+      EVENT = "process_rpc.tonic_rails"
+
+      module_function
+
+      # @api private
+      def instrument(path, metadata)
+        # Without subscribers, skip building the payload: this runs on
+        # every RPC.
+        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
+          result = yield
+          payload[:code] = 0
+          payload[:status] = :ok
+          result
+        rescue RpcError => e
+          payload[:code] = e.code
+          payload[:status] = e.code_name
+          raise
+        rescue StandardError
+          payload[:code] = RpcError::CODES[:internal]
+          payload[:status] = :internal
+          raise
+        end
+      end
+
+      # Logs one line per RPC through the configured logger, e.g.
+      #   gRPC /demo.v1.ItemService/GetItem OK in 1.4ms
+      #   gRPC /demo.v1.ItemService/GetItem NOT_FOUND in 0.9ms: item 7 not found
+      # Enabled by `config.log_requests = true`.
+      class RequestLogger
+        def initialize(logger)
+          @logger = logger
+        end
+
+        def call(event)
+          payload = event.payload
+          status = (payload[:status] || :unknown).to_s.upcase
+          line = format("gRPC %<path>s %<status>s in %<ms>.1fms", path: payload[:path], status: status, ms: event.duration)
+          error = payload[:exception_object]
+          line = "#{line}: #{error.message}" if error && payload[:code] != 0
+          @logger.info(line)
+        end
+
+        # @return [Object] the subscription, for #unsubscribe
+        def subscribe
+          ActiveSupport::Notifications.subscribe(EVENT, self)
+        end
+      end
+    end
+  end
+end

data/lib/tonic/rails/metadata.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Tonic
+  module Rails
+    # Converts handler-supplied gRPC metadata into header pairs.
+    #
+    # Names are lower-cased and must be valid gRPC metadata names; names
+    # ending in "-bin" carry binary values, which are base64-encoded as the
+    # gRPC spec requires.  Other values must be printable ASCII.
+    module Metadata
+      NAME = /\A[0-9a-z_.-]+\z/
+      PRINTABLE = /\A[\x20-\x7e]*\z/
+      RESERVED = %w[content-type te user-agent content-length connection transfer-encoding].freeze
+
+      module_function
+
+      # @param metadata [Hash{String,Symbol=>String,Array<String>}]
+      # @return [Hash{String=>String}]
+      # @raise [ArgumentError] for invalid or reserved names and values
+      def encode(metadata)
+        metadata.each_with_object({}) do |(name, value), out|
+          name = name.to_s.downcase
+          validate_name!(name)
+          out[name] = encode_value(name, value)
+        end
+      end
+
+      def validate_name!(name)
+        raise ArgumentError, "invalid gRPC metadata name #{name.inspect}" unless NAME.match?(name)
+        return unless RESERVED.include?(name) || (name.start_with?("grpc-") && name != "grpc-status-details-bin")
+
+        raise ArgumentError, "gRPC metadata name #{name.inspect} is reserved"
+      end
+
+      def encode_value(name, value)
+        values = Array(value).map(&:to_s)
+        if name.end_with?("-bin")
+          values.map { |v| [v].pack("m0") }.join(",")
+        else
+          values.each do |v|
+            next if PRINTABLE.match?(v)
+
+            raise ArgumentError, "gRPC metadata #{name} must be printable ASCII; use a -bin name for binary"
+          end
+          values.join(",")
+        end
+      end
+    end
+  end
+end

data/lib/tonic/rails/railtie.rb

@@ -28,8 +28,8 @@ module Tonic
       config.after_initialize do
         configuration = Tonic::Rails.configuration
         # Only inside an actual web server process — not consoles, rake
-        # tasks, or test runs.  Forking servers (Puma cluster mode) must
-        # instead start the server per worker, e.g. in `on_worker_boot`.
+        # tasks, or test runs.  With Puma, prefer `plugin :tonic_rails`
+        # (lib/puma/plugin/tonic_rails.rb), which also covers cluster mode.
         if configuration.auto_start && defined?(::Rails::Server)
           server = Tonic::Rails.server
           thread = Thread.new do

data/lib/tonic/rails/rpc_error.rb

@@ -2,13 +2,23 @@
 
 module Tonic
   module Rails
-    # Raise from a handler to end the RPC with a gRPC status.
+    # Raise from a handler (or interceptor) to end the RPC with a gRPC status.
     #
-    #   raise Tonic::Rails::RpcError.new("product not found", code: :not_found)
+    #   raise Tonic::Rails::RpcError.new("item not found", code: :not_found)
     #
-    # The message is sent to the client, so keep internal details out of
-    # it.  Any other exception becomes INTERNAL with a generic message
-    # and is logged server-side.
+    # Optionally attach trailing metadata and rich error details (protobuf
+    # messages such as google.rpc.BadRequest, sent in the standard
+    # grpc-status-details-bin trailer as a google.rpc.Status):
+    #
+    #   raise Tonic::Rails::RpcError.new(
+    #     "invalid item", code: :invalid_argument,
+    #     metadata: { "x-request-id" => request_id },
+    #     details: [Google::Rpc::BadRequest.new(field_violations: [...])],
+    #   )
+    #
+    # 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.
     class RpcError < Error
       CODES = {
         ok: 0,
@@ -35,13 +45,70 @@ module Tonic
       # @return [Integer] numeric gRPC status code
       attr_reader :code
 
+      # @return [Hash] trailing metadata sent with the status
+      attr_reader :metadata
+
+      # @return [Array<Google::Protobuf::AbstractMessage>] rich error details
+      attr_reader :details
+
       # @param message [String] status message sent to the client
       # @param code [Symbol, Integer] gRPC status code (see CODES)
-      def initialize(message = nil, code: :unknown)
+      # @param metadata [Hash] trailing metadata (see Tonic::Rails::Metadata)
+      # @param details [Array<Google::Protobuf::AbstractMessage>] messages
+      #   packed into google.rpc.Status.details
+      def initialize(message = nil, code: :unknown, metadata: {}, details: [])
         @code = self.class.normalize_code(code)
+        @metadata = metadata
+        @details = Array(details)
         super(message || code_name.to_s)
       end
 
+      # @api private
+      # @return [Hash{String=>String}] trailers to send with this status
+      def trailers
+        trailers = Metadata.encode(metadata)
+        trailers["grpc-status-details-bin"] = [status_proto].pack("m0") unless details.empty?
+        trailers
+      end
+
+      # The encoded google.rpc.Status (code = 1, message = 2, details = 3 as
+      # google.protobuf.Any), built directly so googleapis protos aren't a
+      # dependency.
+      def status_proto
+        require "google/protobuf/well_known_types"
+        buf = (+"").b
+        buf << field_key(1, 0) << varint(code)
+        buf << length_delimited(2, message.b)
+        details.each do |detail|
+          any = detail.is_a?(Google::Protobuf::Any) ? detail : Google::Protobuf::Any.pack(detail)
+          buf << length_delimited(3, Google::Protobuf::Any.encode(any))
+        end
+        buf
+      end
+
+      private
+
+      def field_key(field, wire_type)
+        varint((field << 3) | wire_type)
+      end
+
+      def length_delimited(field, bytes)
+        field_key(field, 2) + varint(bytes.bytesize) + bytes
+      end
+
+      def varint(value)
+        bytes = []
+        loop do
+          byte = value & 0x7f
+          value >>= 7
+          bytes << (value.zero? ? byte : byte | 0x80)
+          break if value.zero?
+        end
+        bytes.pack("C*")
+      end
+
+      public
+
       # @return [Symbol] e.g. :not_found
       def code_name
         CODE_NAMES.fetch(@code)

data/lib/tonic/rails/server.rb

@@ -20,8 +20,7 @@ module Tonic
         @router = Router.new
         @native = nil
         @state = :stopped
-        @stop_reader = nil
-        @stop_writer = nil
+        @stop_signal = nil
         @stop_requested = false
         @lock = Mutex.new
       end
@@ -51,12 +50,17 @@ module Tonic
           @configuration.validate!
           Tonic::Rails.native_extension!
           Tonic::Rails._set_shutting_down(false)
-          @stop_reader, @stop_writer = IO.pipe
+          # A Queue rather than a self-pipe: pushing to it is safe from trap
+          # handlers, and unlike pipes it can be waited on with a timeout
+          # on every platform (Windows select() only handles sockets).
+          @stop_signal = Thread::Queue.new
           stop if @stop_requested # requested while we were starting up
           @native = build_native_server
           @native.start_server
+          log_pump = spawn_log_pump
           @state = :running
 
+          request_log = subscribe_request_logger
           previous_handlers = install_signal_handlers ? trap_signals : {}
           workers = Array.new(@configuration.dispatch_threads) { |i| spawn_worker(i) }
           log_startup
@@ -65,11 +69,12 @@ module Tonic
           wait_for_stop(workers)
           shutdown(workers)
         ensure
+          ActiveSupport::Notifications.unsubscribe(request_log) if request_log
           previous_handlers&.each { |signal, handler| Signal.trap(signal, handler || "DEFAULT") }
           @native&.stop_server
+          stop_log_pump(log_pump)
           @native = nil
-          [@stop_reader, @stop_writer].each { |io| io.close if io && !io.closed? }
-          @stop_reader = @stop_writer = nil
+          @stop_signal = nil
           Tonic::Rails._set_shutting_down(false)
           @state = :stopped
         end
@@ -79,9 +84,7 @@ module Tonic
       # other threads; returns immediately.
       def stop
         @stop_requested = true
-        @stop_writer&.write_nonblock(".", exception: false)
-      rescue IOError
-        # Already stopped.
+        @stop_signal&.push(:stop)
       end
 
       def running?
@@ -113,7 +116,6 @@ module Tonic
         native.set_worker_threads(config.worker_threads || 0)
         native.set_keepalive(config.keepalive_interval.to_f, config.keepalive_timeout.to_f)
         native.set_dispatch_queue_size(config.dispatch_queue_size)
-        native.set_log_requests(config.log_requests ? true : false)
         native.set_compression(config.compression ? true : false)
         native.set_reflection(config.reflection ? true : false)
         native.set_reflection_descriptors(Reflection.file_descriptors(@router.service_names)) if config.reflection
@@ -133,8 +135,9 @@ module Tonic
         end
 
         guarded = lambda do |path, metadata, transport|
-          call.call(path, metadata, transport)
-        rescue RpcError
+          Instrumentation.instrument(path, metadata) { call.call(path, metadata, transport) }
+        rescue RpcError => e
+          attach_error_trailers(transport, e)
           raise
         rescue StandardError => e
           Tonic::Rails.log_exception(e, path)
@@ -144,6 +147,15 @@ module Tonic
         wrap_with_rails_executor(guarded)
       end
 
+      # An RpcError's own metadata and rich details travel as trailers.
+      def attach_error_trailers(transport, error)
+        return if error.metadata.empty? && error.details.empty?
+
+        transport[:sender]&.add_trailers(error.trailers)
+      rescue StandardError => e
+        Tonic::Rails.log_exception(e, "RpcError trailers")
+      end
+
       # Each RPC runs inside the Rails executor (or reloader, when code
       # reloading is on): ActiveRecord connections are returned, query
       # caches and CurrentAttributes are reset — the same isolation Rack
@@ -156,6 +168,41 @@ module Tonic
         ->(path, metadata, transport) { wrapper.wrap { callback.call(path, metadata, transport) } }
       end
 
+      def subscribe_request_logger
+        return unless @configuration.log_requests && @configuration.logger
+
+        Instrumentation::RequestLogger.new(@configuration.logger).subscribe
+      end
+
+      # Transport events from the Rust side (rejected calls, expired
+      # deadlines, refused connections, faults) can't call Ruby directly;
+      # this thread drains them into the configured logger.
+      def spawn_log_pump
+        native = @native
+        logger = @configuration.logger
+        @log_pump_running = true
+        Thread.new do
+          Thread.current.name = "tonic-rails-log"
+          write_transport_logs(logger, native.next_log_events(0.25)) while @log_pump_running
+          write_transport_logs(logger, native.next_log_events(0)) # whatever shutdown produced
+        rescue StandardError => e
+          warn("tonic-rails: log thread stopped: #{e.class}: #{e.message}")
+        end
+      end
+
+      def stop_log_pump(thread)
+        return unless thread
+
+        @log_pump_running = false
+        thread.join(2)
+      end
+
+      def write_transport_logs(logger, events)
+        return unless logger
+
+        events.each { |level, message| logger.public_send(level, "tonic-rails: #{message}") }
+      end
+
       def spawn_worker(index)
         native = @native
         Thread.new do
@@ -174,7 +221,7 @@ module Tonic
 
       def wait_for_stop(workers)
         loop do
-          break if @stop_reader.wait_readable(1)
+          break if @stop_signal.pop(timeout: 1)
 
           dead = workers.reject(&:alive?)
           unless dead.empty?

data/lib/tonic/rails/testing.rb

@@ -28,19 +28,35 @@ module Tonic
         attr_reader :error
       end
 
-      # Response side of a call: collects encoded messages.
+      # Response side of a call: collects encoded messages and metadata.
       class Sender
-        attr_reader :messages
+        attr_reader :messages, :headers, :trailers
 
         def initialize
           @messages = []
+          @headers = {}
+          @trailers = {}
         end
 
         def push(bytes)
           @messages << bytes
         end
+
+        def send_headers(headers)
+          raise "response headers must be sent before any response message" unless @messages.empty?
+
+          @headers.merge!(headers)
+        end
+
+        def add_trailers(trailers)
+          @trailers.merge!(trailers)
+        end
       end
 
+      # What a call produced: the response (or responses, for streaming),
+      # plus the response headers and trailers as they'd go on the wire.
+      Result = Struct.new(:response, :headers, :trailers)
+
       module_function
 
       # @param service_class [Class] handler class
@@ -53,6 +69,18 @@ module Tonic
       #   an Array of responses for server- and bidi-streaming RPCs
       # @raise [RpcError] when the handler ends the call with a status
       def call(service_class, rpc_name, request, metadata: {}, timeout_ms: nil)
+        invoke(service_class, rpc_name, request, metadata: metadata, timeout_ms: timeout_ms).response
+      end
+
+      # Like #call, but returns a Result with the response metadata too:
+      #
+      #   result = Tonic::Rails::Testing.invoke(ItemService, :GetItem, { id: 1 })
+      #   result.response.name           # => "Widget"
+      #   result.headers["x-cache"]      # => "hit"
+      #   result.trailers["x-cost-ms"]   # => "3"
+      #
+      # @return [Result]
+      def invoke(service_class, rpc_name, request, metadata: {}, timeout_ms: nil)
         spec = service_class.grpc_rpcs.fetch(rpc_name.to_s) do
           raise ArgumentError, "#{service_class} has no RPC #{rpc_name}"
         end
@@ -69,11 +97,12 @@ module Tonic
           timeout_ms: timeout_ms,
         )
 
-        if spec[:response_stream]
+        response = if spec[:response_stream]
           sender.messages.map { |bytes| spec[:response].decode(bytes) }
         else
           spec[:response].decode(result)
         end
+        Result.new(response, sender.headers, sender.trailers)
       end
 
       def encode(klass, message)

data/lib/tonic/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Tonic
   module Rails
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/tonic-rails.rb

@@ -10,9 +10,11 @@ module Tonic
 end
 
 require "tonic/rails/version"
+require "tonic/rails/metadata"
 require "tonic/rails/rpc_error"
 require "tonic/rails/configuration"
 require "tonic/rails/router"
+require "tonic/rails/instrumentation"
 require "tonic/rails/base"
 require "tonic/rails/reflection"
 require "tonic/rails/server"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tonic-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: x86_64-linux-gnu
 authors:
 - Matt Tanous
@@ -54,12 +54,15 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- lib/puma/plugin/tonic_rails.rb
 - lib/tonic-rails.rb
 - lib/tonic/rails/3.3/tonic_rails_native.so
 - 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/configuration.rb
+- lib/tonic/rails/instrumentation.rb
+- lib/tonic/rails/metadata.rb
 - lib/tonic/rails/railtie.rb
 - lib/tonic/rails/reflection.rb
 - lib/tonic/rails/router.rb