tonic-rails 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6c9da1fa1dde14dab1bd46c64821154a392dd9e5b5bc31faf396cf8e51dfc28
-  data.tar.gz: f0988c4f232fb3016b205d094ea0970085e7515f71f6845e55bd8bc6d43c7d70
+  metadata.gz: f526af49b4f7647168bcdf7d64131c00c63880d3372f0355d60aa7e347240856
+  data.tar.gz: 7698d7d70a8e3c75ef3ee63ec46ce032267688e12cb86fbca35bf74e41f6f29f
 SHA512:
-  metadata.gz: 82a6eb4a8da4daaf1f91e6ead904b1223c13cc5b02f90e9bebf810ca7fc25bd71cb30cce07e539fde05b81b12fd89e84d540fc5aa5a22d38d7697aacb746a1c0
-  data.tar.gz: 87dbd3f3abcbdefd3d6f47ad8b93ea992672efe67c643bcf47e75e255e920983ab6695ecfea8eb4273db390f57e6de419b9c369ad5067f0e07a0d086a7c9e218
+  metadata.gz: ad814eb2ab41e6009649bd5307a8f304e3f1baab030f00a25045b65ec0bd1279aa7eceac041d141932281073ce650172191e0fcfbec9c74066f5c224b64e811c
+  data.tar.gz: b1cc149c6beb0f3bb2f99579cc5b4ef4e13964654a93969b431bf0032a25f9fa624f5888748eb0fe37fef1c13762146b881aec6d3347cbc27fe0fee468990275

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/Cargo.lock

@@ -469,9 +469,9 @@ checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6"
 
 [[package]]
 name = "magnus"
-version = "0.8.3"
+version = "0.9.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "86a4f30dd400bf26769435129d7ecc529f56e3d45012ee6c394d6dbff3296bf9"
+checksum = "b9068710e00d21be762edca59b9c4c8946dbdb29820d4f76ad559afea07982c9"
 dependencies = [
  "magnus-macros",
  "rb-sys",
@@ -481,9 +481,9 @@ dependencies = [
 
 [[package]]
 name = "magnus-macros"
-version = "0.8.0"
+version = "0.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "47607461fd8e1513cb4f2076c197d8092d921a1ea75bd08af97398f593751892"
+checksum = "9dafde2eeb66f090e0f326112323eb8324b12cb32b5d1210e541d3df6b0ce77e"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -1023,7 +1023,7 @@ dependencies = [
 
 [[package]]
 name = "tonic_rails_native"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
  "axum",
  "bytes",

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/ext/tonic_rails_native/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tonic_rails_native"
-version = "0.1.0"
+version = "0.2.0"
 edition = "2024"
 rust-version = "1.88"
 publish = false
@@ -23,7 +23,7 @@ crate-type = ["cdylib"]
 #
 # socket2 enables SO_REUSEPORT for multi-process (Puma worker) scaling.
 [dependencies]
-magnus = "0.8"
+magnus = "0.9"
 rb-sys = "0.9"
 tonic = { version = "0.14", default-features = false, features = ["transport", "router", "server", "tls-ring"] }
 tonic-reflection = { version = "0.14", default-features = false, features = ["server"] }

data/ext/tonic_rails_native/src/body.rs

@@ -7,7 +7,7 @@
 use std::future::Future;
 use std::pin::Pin;
 use std::sync::Arc;
-use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
+use std::sync::atomic::{AtomicUsize, Ordering};
 use std::task::{Context, Poll};
 use std::time::Instant;
 
@@ -17,8 +17,9 @@ use http_body::{Body, Frame};
 use tokio::sync::mpsc;
 use tonic::{Code, Status};
 
-use crate::framing::{COMPRESSION_THRESHOLD, frame, sanitize_for_log, status_trailers};
+use crate::framing::{COMPRESSION_THRESHOLD, append_metadata, frame, status_trailers};
 use crate::gvl::StreamMessage;
+use crate::log::{Level, LogSink, status_name};
 
 /// Request counters, exposed to Ruby via `Server#stats`.
 #[derive(Default)]
@@ -30,12 +31,14 @@ pub struct ServerStats {
     pub deadline_exceeded: AtomicUsize,
     pub resource_exhausted: AtomicUsize,
     pub unimplemented: AtomicUsize,
-    /// Log every request (including OK) to stderr.  Errors are always logged.
-    pub log_requests: AtomicBool,
+    pub log: LogSink,
 }
 
 impl ServerStats {
-    pub fn record(&self, path: &str, code: u32, message: &str, start: Instant) {
+    /// Count a finished call.  `transport` marks outcomes decided here in
+    /// Rust (rejections, deadlines, limits) rather than by the Ruby handler;
+    /// only those are logged, since Ruby instruments and logs its own calls.
+    pub fn record(&self, path: &str, code: u32, message: &str, start: Instant, transport: bool) {
         let counter = match Code::from_i32(code as i32) {
             Code::Ok => &self.successful,
             Code::Cancelled => &self.cancelled,
@@ -55,16 +58,15 @@ impl ServerStats {
             _ => {}
         }
 
-        let is_error = !matches!(Code::from_i32(code as i32), Code::Ok | Code::Cancelled);
-        if is_error || self.log_requests.load(Ordering::Relaxed) {
-            let path = sanitize_for_log(path);
-            let dur_us = start.elapsed().as_micros();
-            if message.is_empty() {
-                eprintln!("tonic-rails: path={path} code={code} duration_us={dur_us}");
+        if transport && code != Code::Ok as u32 {
+            let ms = start.elapsed().as_secs_f64() * 1000.0;
+            let status = status_name(code);
+            let line = if message.is_empty() {
+                format!("gRPC {path} {status} in {ms:.1}ms")
             } else {
-                let message = sanitize_for_log(message);
-                eprintln!("tonic-rails: path={path} code={code} duration_us={dur_us} message={message}");
-            }
+                format!("gRPC {path} {status} in {ms:.1}ms: {message}")
+            };
+            self.log.log(Level::for_code(code), &line);
         }
     }
 }
@@ -102,6 +104,8 @@ impl Body for ErrorBody {
 /// channel.  Each `Data` message becomes a gRPC frame; `End` (or the
 /// deadline) produces the trailers.
 pub struct ResponseBody {
+    /// A message already received while waiting for response headers.
+    pub pending: Option<StreamMessage>,
     pub receiver: Option<mpsc::Receiver<StreamMessage>>,
     pub stats: Arc<ServerStats>,
     pub path: String,
@@ -112,12 +116,63 @@ pub struct ResponseBody {
     pub finished: bool,
 }
 
+type Polled = Poll<Option<Result<Frame<Bytes>, Status>>>;
+
 impl ResponseBody {
-    fn finish(&mut self, code: Code, message: &str) -> Poll<Option<Result<Frame<Bytes>, Status>>> {
+    fn finish(&mut self, code: Code, message: &str, transport: bool) -> Polled {
+        self.finish_with(code, message, transport, &[])
+    }
+
+    fn finish_with(
+        &mut self,
+        code: Code,
+        message: &str,
+        transport: bool,
+        metadata: &[(String, String)],
+    ) -> Polled {
         self.receiver = None;
         self.finished = true;
-        self.stats.record(&self.path, code as u32, message, self.start);
-        Poll::Ready(Some(Ok(Frame::trailers(status_trailers(code as u32, message)))))
+        self.stats
+            .record(&self.path, code as u32, message, self.start, transport);
+        let mut trailers = status_trailers(code as u32, message);
+        let skipped = append_metadata(&mut trailers, metadata);
+        if !skipped.is_empty() {
+            self.stats.log.log(
+                Level::Warn,
+                &format!(
+                    "gRPC {} dropped invalid or reserved trailers: {}",
+                    self.path,
+                    skipped.join(", ")
+                ),
+            );
+        }
+        Poll::Ready(Some(Ok(Frame::trailers(trailers))))
+    }
+
+    /// Turn one handler message into a frame (None: nothing to emit).
+    fn handle(&mut self, message: StreamMessage) -> Option<Polled> {
+        match message {
+            StreamMessage::Data(bytes) => {
+                if bytes.len() > self.max_message_size {
+                    return Some(self.finish(
+                        Code::ResourceExhausted,
+                        "response message exceeds max_message_size",
+                        true,
+                    ));
+                }
+                let compress = self.compress && bytes.len() > COMPRESSION_THRESHOLD;
+                Some(Poll::Ready(Some(Ok(Frame::data(frame(&bytes, compress))))))
+            }
+            StreamMessage::End { status, trailers } => Some(match status {
+                None => self.finish_with(Code::Ok, "", false, &trailers),
+                Some((code, message)) => {
+                    self.finish_with(Code::from_i32(code as i32), &message, false, &trailers)
+                }
+            }),
+            // Headers are only valid first and are consumed by the
+            // dispatcher; a late one has nowhere to go.
+            StreamMessage::Headers(_) => None,
+        }
     }
 }
 
@@ -125,39 +180,36 @@ impl Body for ResponseBody {
     type Data = Bytes;
     type Error = Status;
 
-    fn poll_frame(
-        mut self: Pin<&mut Self>,
-        cx: &mut Context<'_>,
-    ) -> Poll<Option<Result<Frame<Bytes>, Status>>> {
-        let Some(receiver) = self.receiver.as_mut() else {
-            return Poll::Ready(None);
-        };
+    fn poll_frame(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Polled {
+        if let Some(message) = self.pending.take()
+            && let Some(poll) = self.handle(message)
+        {
+            return poll;
+        }
 
         // Drain ready messages before checking the deadline so a response
         // that made it in time is never discarded.
-        match receiver.poll_recv(cx) {
-            Poll::Ready(Some(StreamMessage::Data(bytes))) => {
-                if bytes.len() > self.max_message_size {
-                    return self.finish(
-                        Code::ResourceExhausted,
-                        "response message exceeds max_message_size",
-                    );
+        loop {
+            let Some(receiver) = self.receiver.as_mut() else {
+                return Poll::Ready(None);
+            };
+            match receiver.poll_recv(cx) {
+                Poll::Ready(Some(message)) => {
+                    if let Some(poll) = self.handle(message) {
+                        return poll;
+                    }
                 }
-                let compress = self.compress && bytes.len() > COMPRESSION_THRESHOLD;
-                return Poll::Ready(Some(Ok(Frame::data(frame(&bytes, compress)))));
-            }
-            Poll::Ready(Some(StreamMessage::End(None))) => return self.finish(Code::Ok, ""),
-            Poll::Ready(Some(StreamMessage::End(Some((code, message))))) => {
-                return self.finish(Code::from_i32(code as i32), &message);
+                Poll::Ready(None) => {
+                    return self.finish(Code::Internal, "handler ended without a response", true);
+                }
+                Poll::Pending => break,
             }
-            Poll::Ready(None) => return self.finish(Code::Internal, "handler ended without a response"),
-            Poll::Pending => {}
         }
 
         if let Some(deadline) = self.deadline.as_mut()
             && deadline.as_mut().poll(cx).is_ready()
         {
-            return self.finish(Code::DeadlineExceeded, "deadline exceeded");
+            return self.finish(Code::DeadlineExceeded, "deadline exceeded", true);
         }
         Poll::Pending
     }
@@ -173,12 +225,6 @@ impl Drop for ResponseBody {
         // (RST_STREAM / disconnect) — count it as cancelled.
         if !self.finished {
             self.stats.cancelled.fetch_add(1, Ordering::Relaxed);
-            if self.stats.log_requests.load(Ordering::Relaxed) {
-                eprintln!(
-                    "tonic-rails: path={} code=1 message=cancelled by client",
-                    sanitize_for_log(&self.path)
-                );
-            }
         }
     }
 }
@@ -197,6 +243,7 @@ mod tests {
 
     fn response_body(rx: mpsc::Receiver<StreamMessage>, stats: Arc<ServerStats>) -> ResponseBody {
         ResponseBody {
+            pending: None,
             receiver: Some(rx),
             stats,
             path: "/test.Svc/Method".into(),
@@ -231,7 +278,11 @@ mod tests {
         let stats = Arc::new(ServerStats::default());
         let mut body = response_body(rx, stats.clone());
         tx.try_send(StreamMessage::Data(b"abc".to_vec())).ok();
-        tx.try_send(StreamMessage::End(None)).ok();
+        tx.try_send(StreamMessage::End {
+            status: None,
+            trailers: vec![("x-done".into(), "yes".into())],
+        })
+        .ok();
 
         match poll(&mut body) {
             Poll::Ready(Some(Ok(frame))) => {
@@ -242,7 +293,9 @@ mod tests {
             }
             _ => panic!("expected data"),
         }
-        assert_eq!(trailers(poll(&mut body))["grpc-status"], "0");
+        let t = trailers(poll(&mut body));
+        assert_eq!(t["grpc-status"], "0");
+        assert_eq!(t["x-done"], "yes");
         assert!(matches!(poll(&mut body), Poll::Ready(None)));
         drop(body);
         assert_eq!(stats.successful.load(Ordering::Relaxed), 1);
@@ -263,12 +316,23 @@ mod tests {
     fn response_body_reports_handler_error() {
         let (tx, rx) = mpsc::channel(4);
         let mut body = response_body(rx, Arc::new(ServerStats::default()));
-        tx.try_send(StreamMessage::End(Some((7, "denied".into())))).ok();
+        tx.try_send(StreamMessage::error(Code::PermissionDenied, "denied"))
+            .ok();
         let t = trailers(poll(&mut body));
         assert_eq!(t["grpc-status"], "7");
         assert_eq!(t["grpc-message"], "denied");
     }
 
+    #[test]
+    fn response_body_starts_with_a_pending_message() {
+        let (tx, rx) = mpsc::channel(4);
+        let mut body = response_body(rx, Arc::new(ServerStats::default()));
+        body.pending = Some(StreamMessage::Data(b"x".to_vec()));
+        tx.try_send(StreamMessage::error(Code::Aborted, "stop")).ok();
+        assert!(matches!(poll(&mut body), Poll::Ready(Some(Ok(f))) if f.is_data()));
+        assert_eq!(trailers(poll(&mut body))["grpc-status"], "10");
+    }
+
     #[test]
     fn response_body_closed_channel_is_internal() {
         let (tx, rx) = mpsc::channel(4);

data/ext/tonic_rails_native/src/dispatch.rs

@@ -23,8 +23,9 @@ use tonic::Code;
 use tonic::body::Body as TonicBody;
 
 use crate::body::{ErrorBody, ResponseBody, ServerStats};
-use crate::framing::{MessageReader, parse_grpc_timeout};
+use crate::framing::{MessageReader, append_metadata, parse_grpc_timeout};
 use crate::gvl::{DispatchContext, RequestError, StreamMessage};
+use crate::log::Level;
 
 /// Messages buffered per direction before backpressure applies.
 const STREAM_BUFFER: usize = 32;
@@ -62,8 +63,8 @@ impl tower::Service<Request<axum::body::Body>> for DispatchService {
     }
 
     fn call(&mut self, req: Request<axum::body::Body>) -> Self::Future {
-        let response = self.0.handle(req);
-        Box::pin(async move { Ok(response) })
+        let inner = self.0.clone();
+        Box::pin(async move { Ok(inner.handle(req).await) })
     }
 }
 
@@ -83,11 +84,11 @@ fn grpc_response(body: TonicBody, compressed: bool) -> Response<TonicBody> {
 
 impl DispatchInner {
     fn reject(&self, path: &str, start: Instant, code: Code, message: &str) -> Response<TonicBody> {
-        self.stats.record(path, code as u32, message, start);
+        self.stats.record(path, code as u32, message, start, true);
         grpc_response(TonicBody::new(ErrorBody::new(code, message)), false)
     }
 
-    fn handle(&self, req: Request<axum::body::Body>) -> Response<TonicBody> {
+    async fn handle(&self, req: Request<axum::body::Body>) -> Response<TonicBody> {
         let start = Instant::now();
         self.stats.total.fetch_add(1, Ordering::Relaxed);
         let path = req.uri().path().to_owned();
@@ -164,6 +165,7 @@ impl DispatchInner {
             response_tx,
             request_rx,
             request_error: request_error.clone(),
+            log: self.stats.log.clone(),
         });
 
         match self.request_tx.try_send(ctx) {
@@ -190,17 +192,52 @@ impl DispatchInner {
             gzip_request,
         ));
 
+        // Response headers wait for the handler's first output, so it can
+        // set initial metadata; unary calls send headers with the response
+        // as usual.  The client's deadline applies while we wait.
+        let mut response_rx = response_rx;
+        let mut deadline = timeout.map(|t| Box::pin(tokio::time::sleep(t)));
+        let first = match deadline.as_mut() {
+            Some(deadline) => tokio::select! {
+                biased;
+                message = response_rx.recv() => Some(message),
+                _ = deadline.as_mut() => None,
+            },
+            None => Some(response_rx.recv().await),
+        };
+        let (headers, pending) = match first {
+            None => return self.reject(&path, start, Code::DeadlineExceeded, "deadline exceeded"),
+            Some(None) => {
+                return self.reject(&path, start, Code::Internal, "handler ended without a response");
+            }
+            Some(Some(StreamMessage::Headers(headers))) => (headers, None),
+            Some(Some(message)) => (Vec::new(), Some(message)),
+        };
+
         let body = ResponseBody {
+            pending,
             receiver: Some(response_rx),
             stats: self.stats.clone(),
             path,
             start,
             compress,
-            deadline: timeout.map(|t| Box::pin(tokio::time::sleep(t))),
+            deadline,
             max_message_size,
             finished: false,
         };
-        grpc_response(TonicBody::new(body), compress)
+        let path = body.path.clone();
+        let mut response = grpc_response(TonicBody::new(body), compress);
+        let skipped = append_metadata(response.headers_mut(), &headers);
+        if !skipped.is_empty() {
+            self.stats.log.log(
+                Level::Warn,
+                &format!(
+                    "gRPC {path} dropped invalid or reserved response headers: {}",
+                    skipped.join(", ")
+                ),
+            );
+        }
+        response
     }
 }