tonic-rails 0.1.0 → 0.2.0

data/ext/tonic_rails_native/src/framing.rs

@@ -190,6 +190,35 @@ pub fn sanitize_for_log(message: &str) -> String {
         .collect()
 }
 
+/// Headers a handler may not set: they belong to HTTP/2 or the gRPC
+/// protocol itself.
+fn is_reserved_metadata(name: &str) -> bool {
+    matches!(
+        name,
+        "content-type" | "te" | "user-agent" | "content-length" | "connection" | "transfer-encoding"
+    ) || (name.starts_with("grpc-") && name != "grpc-status-details-bin")
+}
+
+/// Append handler-supplied metadata to `headers`, skipping names or values
+/// that are invalid HTTP/2 headers or reserved by gRPC.  Returns the names
+/// that were skipped so the caller can report them.
+pub fn append_metadata(headers: &mut HeaderMap, metadata: &[(String, String)]) -> Vec<String> {
+    let mut skipped = Vec::new();
+    for (name, value) in metadata {
+        let header = (!is_reserved_metadata(name))
+            .then(|| http::HeaderName::from_bytes(name.as_bytes()).ok())
+            .flatten()
+            .filter(|n| n.as_str() == name.as_str()); // must already be lower-case
+        match (header, HeaderValue::from_str(value)) {
+            (Some(header), Ok(value)) => {
+                headers.append(header, value);
+            }
+            _ => skipped.push(name.clone()),
+        }
+    }
+    skipped
+}
+
 pub fn status_trailers(code: u32, message: &str) -> HeaderMap {
     let mut trailers = HeaderMap::with_capacity(2);
     trailers.insert("grpc-status", HeaderValue::from(code));
@@ -342,6 +371,27 @@ mod tests {
         assert!(t.get("grpc-message").is_none());
     }
 
+    #[test]
+    fn append_metadata_skips_reserved_and_invalid() {
+        let mut headers = HeaderMap::new();
+        let skipped = append_metadata(
+            &mut headers,
+            &[
+                ("x-request-id".into(), "abc".into()),
+                ("x-trace-bin".into(), "AAE=".into()),
+                ("grpc-status-details-bin".into(), "CAU=".into()),
+                ("grpc-status".into(), "0".into()),
+                ("content-type".into(), "text/plain".into()),
+                ("Upper".into(), "x".into()),
+                ("x-bad".into(), "line\nbreak".into()),
+            ],
+        );
+        assert_eq!(headers["x-request-id"], "abc");
+        assert_eq!(headers["x-trace-bin"], "AAE=");
+        assert_eq!(headers["grpc-status-details-bin"], "CAU=");
+        assert_eq!(skipped, ["grpc-status", "content-type", "Upper", "x-bad"]);
+    }
+
     #[test]
     fn sanitize_for_log_strips_controls() {
         assert_eq!(sanitize_for_log("a\nb\tc"), "a b c");

data/ext/tonic_rails_native/src/gvl.rs

@@ -15,7 +15,11 @@ use std::sync::Arc;
 use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
 use std::task::{Context, Poll, Wake, Waker};
 
-use magnus::{Error, RString, Ruby, Value, prelude::*, typed_data::DataTypeFunctions, value::Opaque};
+use crate::log::{Level, LogSink};
+use magnus::{
+    Error, RHash, RString, Ruby, Value, prelude::*, r_hash::ForEach, typed_data::DataTypeFunctions,
+    value::Opaque,
+};
 use parking_lot::Mutex;
 use rb_sys::{RB_NOGVL_INTR_FAIL, rb_nogvl, rb_thread_call_with_gvl};
 use tokio::sync::{Notify, mpsc};
@@ -193,35 +197,91 @@ pub fn send_with_interrupts<T>(ruby: &Ruby, tx: &mpsc::Sender<T>, mut msg: T) ->
 
 // ─── Response stream ──────────────────────────────────────────────
 
+/// gRPC metadata as (lower-case name, value) pairs; `-bin` values are
+/// already base64-encoded.
+pub type Metadata = Vec<(String, String)>;
+
 /// Messages from the Ruby handler to the tokio response body.
 pub enum StreamMessage {
+    /// Response headers (initial metadata).  Only ever the first message.
+    Headers(Metadata),
     /// One encoded protobuf response message.
     Data(Vec<u8>),
-    /// End of stream: `None` = OK, `Some((code, message))` = error.
-    End(Option<(u32, String)>),
+    /// End of stream: `status` None = OK, `Some((code, message))` = error,
+    /// plus trailing metadata.
+    End {
+        status: Option<(u32, String)>,
+        trailers: Metadata,
+    },
+}
+
+impl StreamMessage {
+    pub fn error(code: tonic::Code, message: &str) -> Self {
+        StreamMessage::End {
+            status: Some((code as u32, message.to_owned())),
+            trailers: Vec::new(),
+        }
+    }
+}
+
+/// Convert a Ruby Hash of String => String into metadata pairs.
+fn metadata_from_hash(hash: RHash) -> Result<Metadata, Error> {
+    let mut pairs = Vec::with_capacity(hash.len());
+    hash.foreach(|name: String, value: String| {
+        pairs.push((name, value));
+        Ok(ForEach::Continue)
+    })?;
+    Ok(pairs)
 }
 
 /// `TonicRails::Native::StreamSender` — pushes encoded response messages
-/// to the client with backpressure.
+/// (and response metadata) to the client with backpressure.
 #[derive(magnus::TypedData)]
 #[magnus(class = "TonicRails::Native::StreamSender", free_immediately)]
 pub struct StreamSender {
     tx: mpsc::Sender<StreamMessage>,
+    trailers: Arc<Mutex<Metadata>>,
+    started: AtomicBool,
 }
 
 impl StreamSender {
+    fn closed(ruby: &Ruby) -> Error {
+        Error::new(ruby.exception_io_error(), "response stream closed by peer")
+    }
+
     /// Raises `IOError` if the client has gone away.
     pub fn push(ruby: &Ruby, this: &Self, data: RString) -> Result<(), Error> {
+        this.started.store(true, Ordering::Release);
         let bytes = unsafe { data.as_slice() }.to_vec();
         if send_with_interrupts(ruby, &this.tx, StreamMessage::Data(bytes))? {
             Ok(())
         } else {
-            Err(Error::new(
-                ruby.exception_io_error(),
-                "response stream closed by peer",
-            ))
+            Err(Self::closed(ruby))
         }
     }
+
+    /// Send response headers.  Must come before any message.
+    pub fn send_headers(ruby: &Ruby, this: &Self, headers: RHash) -> Result<(), Error> {
+        if this.started.swap(true, Ordering::AcqRel) {
+            return Err(Error::new(
+                ruby.exception_runtime_error(),
+                "response headers must be sent before any response message",
+            ));
+        }
+        let headers = metadata_from_hash(headers)?;
+        if send_with_interrupts(ruby, &this.tx, StreamMessage::Headers(headers))? {
+            Ok(())
+        } else {
+            Err(Self::closed(ruby))
+        }
+    }
+
+    /// Add trailing metadata, sent with the final status.
+    pub fn add_trailers(&self, trailers: RHash) -> Result<(), Error> {
+        let trailers = metadata_from_hash(trailers)?;
+        self.trailers.lock().extend(trailers);
+        Ok(())
+    }
 }
 
 impl DataTypeFunctions for StreamSender {}
@@ -308,6 +368,7 @@ pub struct DispatchContext {
     pub response_tx: mpsc::Sender<StreamMessage>,
     pub request_rx: mpsc::Receiver<Vec<u8>>,
     pub request_error: Arc<RequestError>,
+    pub log: LogSink,
 }
 
 /// Bounds on how long one thread keeps the GVL to drain a busy queue.
@@ -357,17 +418,15 @@ pub fn dispatch(first: Box<DispatchContext>, queue: &crossbeam_channel::Receiver
 
 fn run_guarded(ctx: DispatchContext) {
     let response_tx = ctx.response_tx.clone();
+    let log = ctx.log.clone();
     if let Err(panic) = catch_unwind(AssertUnwindSafe(|| run_handler(ctx))) {
         let msg = panic
             .downcast_ref::<String>()
             .map(String::as_str)
             .or_else(|| panic.downcast_ref::<&str>().copied())
             .unwrap_or("unknown panic");
-        eprintln!("tonic-rails: panic in dispatch: {msg}");
-        let _ = response_tx.try_send(StreamMessage::End(Some((
-            tonic::Code::Internal as u32,
-            "internal error".into(),
-        ))));
+        log.log(Level::Error, &format!("panic in dispatch: {msg}"));
+        let _ = response_tx.try_send(StreamMessage::error(tonic::Code::Internal, "internal error"));
     }
 }
 
@@ -381,9 +440,11 @@ fn run_handler(ctx: DispatchContext) {
         response_tx,
         request_rx,
         request_error,
+        log,
     } = ctx;
 
-    let end = match call_handler(
+    let trailers = Arc::new(Mutex::new(Metadata::new()));
+    let result = call_handler(
         &ruby,
         callback,
         &path,
@@ -392,9 +453,11 @@ fn run_handler(ctx: DispatchContext) {
         &response_tx,
         request_rx,
         request_error,
-    ) {
-        Ok(()) => StreamMessage::End(None),
-        Err(e) => StreamMessage::End(Some(error_status(&e))),
+        trailers.clone(),
+    );
+    let end = StreamMessage::End {
+        status: result.err().map(|e| error_status(&e, &log)),
+        trailers: std::mem::take(&mut *trailers.lock()),
     };
     // Ignore failures: the client may already be gone.
     let _ = send_with_interrupts(&ruby, &response_tx, end);
@@ -410,6 +473,7 @@ fn call_handler(
     response_tx: &mpsc::Sender<StreamMessage>,
     request_rx: mpsc::Receiver<Vec<u8>>,
     request_error: Arc<RequestError>,
+    trailers: Arc<Mutex<Metadata>>,
 ) -> Result<(), Error> {
     let md = ruby.hash_new_capa(metadata.len());
     for (k, v) in metadata {
@@ -425,6 +489,8 @@ fn call_handler(
         ruby.to_symbol("sender"),
         StreamSender {
             tx: response_tx.clone(),
+            trailers,
+            started: AtomicBool::new(false),
         },
     )?;
     if let Some(ms) = timeout_ms {
@@ -451,7 +517,7 @@ fn call_handler(
 /// Map a Ruby exception to a gRPC status.  Only exceptions carrying an
 /// Integer `@code` (i.e. `Tonic::Rails::RpcError`) expose their message;
 /// anything else becomes a generic INTERNAL so details never leak.
-fn error_status(e: &Error) -> (u32, String) {
+fn error_status(e: &Error, log: &LogSink) -> (u32, String) {
     if let Some(exc) = e.value() {
         let code = exc
             .funcall::<_, _, Option<i64>>("instance_variable_get", ("@code",))
@@ -464,9 +530,9 @@ fn error_status(e: &Error) -> (u32, String) {
         let description = exc
             .funcall::<_, _, String>("inspect", ())
             .unwrap_or_else(|_| "unknown exception".into());
-        eprintln!(
-            "tonic-rails: unhandled exception in dispatch: {}",
-            crate::framing::sanitize_for_log(&description)
+        log.log(
+            Level::Error,
+            &format!("unhandled exception in dispatch: {description}"),
         );
     }
     (tonic::Code::Internal as u32, "internal error".into())

data/ext/tonic_rails_native/src/lib.rs

@@ -22,6 +22,7 @@
 //! - [`body`]     — response bodies and request stats
 //! - [`dispatch`] — the fallback tower service that queues RPCs for Ruby
 //! - [`gvl`]      — GVL release/acquire and the Ruby stream objects
+//! - [`log`]      — transport log events for Ruby's logger
 //! - [`net`]      — listener and connection cap
 //! - [`server`]   — `TonicRails::Native::Server`
 
@@ -29,6 +30,7 @@ mod body;
 mod dispatch;
 mod framing;
 mod gvl;
+mod log;
 mod net;
 mod server;
 
@@ -60,7 +62,6 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
         "set_dispatch_queue_size",
         method!(NativeServer::set_dispatch_queue_size, 1),
     )?;
-    class.define_method("set_log_requests", method!(NativeServer::set_log_requests, 1))?;
     class.define_method("set_compression", method!(NativeServer::set_compression, 1))?;
     class.define_method("set_reflection", method!(NativeServer::set_reflection, 1))?;
     class.define_method("set_routes", method!(NativeServer::set_routes, 1))?;
@@ -74,12 +75,15 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     class.define_method("wait_for_drain", method!(NativeServer::wait_for_drain, 1))?;
     class.define_method("stop_workers", method!(NativeServer::stop_workers, 0))?;
     class.define_method("stop_server", method!(NativeServer::stop_server, 0))?;
+    class.define_method("next_log_events", method!(NativeServer::next_log_events, 1))?;
     class.define_method("running?", method!(NativeServer::is_running, 0))?;
     class.define_method("stats", method!(NativeServer::stats, 0))?;
 
     let sender = native.define_class("StreamSender", ruby.class_object())?;
     sender.undef_default_alloc_func();
     sender.define_method("push", method!(StreamSender::push, 1))?;
+    sender.define_method("send_headers", method!(StreamSender::send_headers, 1))?;
+    sender.define_method("add_trailers", method!(StreamSender::add_trailers, 1))?;
 
     let reader = native.define_class("RequestReader", ruby.class_object())?;
     reader.undef_default_alloc_func();

data/ext/tonic_rails_native/src/log.rs

@@ -0,0 +1,131 @@
+//! Transport log events, delivered to Ruby's logger.
+//!
+//! tokio threads cannot call Ruby, so events go through a bounded channel
+//! that a Ruby thread drains (`Server#next_log_events`).  If nobody is
+//! draining, or the channel is full, events fall back to stderr.
+
+use crossbeam_channel::{Receiver, Sender, TrySendError};
+use tonic::Code;
+
+use crate::framing::sanitize_for_log;
+
+/// Events buffered before falling back to stderr.
+const CAPACITY: usize = 1024;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Level {
+    Info,
+    Warn,
+    Error,
+}
+
+impl Level {
+    /// Client-caused outcomes are informational; overload is a warning;
+    /// anything that suggests a server fault is an error.
+    pub fn for_code(code: u32) -> Level {
+        match Code::from_i32(code as i32) {
+            Code::Internal | Code::Unknown | Code::DataLoss => Level::Error,
+            Code::ResourceExhausted | Code::Unavailable => Level::Warn,
+            _ => Level::Info,
+        }
+    }
+
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Level::Info => "info",
+            Level::Warn => "warn",
+            Level::Error => "error",
+        }
+    }
+}
+
+const STATUS_NAMES: [&str; 17] = [
+    "OK",
+    "CANCELLED",
+    "UNKNOWN",
+    "INVALID_ARGUMENT",
+    "DEADLINE_EXCEEDED",
+    "NOT_FOUND",
+    "ALREADY_EXISTS",
+    "PERMISSION_DENIED",
+    "RESOURCE_EXHAUSTED",
+    "FAILED_PRECONDITION",
+    "ABORTED",
+    "OUT_OF_RANGE",
+    "UNIMPLEMENTED",
+    "INTERNAL",
+    "UNAVAILABLE",
+    "DATA_LOSS",
+    "UNAUTHENTICATED",
+];
+
+/// The canonical gRPC status name, e.g. `NOT_FOUND`.
+pub fn status_name(code: u32) -> &'static str {
+    STATUS_NAMES.get(code as usize).copied().unwrap_or("UNKNOWN")
+}
+
+pub struct LogEvent {
+    pub level: Level,
+    pub message: String,
+}
+
+#[derive(Clone)]
+pub struct LogSink {
+    tx: Sender<LogEvent>,
+}
+
+impl LogSink {
+    pub fn new() -> (Self, Receiver<LogEvent>) {
+        let (tx, rx) = crossbeam_channel::bounded(CAPACITY);
+        (Self { tx }, rx)
+    }
+
+    pub fn log(&self, level: Level, message: &str) {
+        let event = LogEvent {
+            level,
+            message: sanitize_for_log(message),
+        };
+        match self.tx.try_send(event) {
+            Ok(()) => {}
+            Err(TrySendError::Full(event) | TrySendError::Disconnected(event)) => {
+                eprintln!("tonic-rails: [{}] {}", event.level.as_str(), event.message);
+            }
+        }
+    }
+}
+
+impl Default for LogSink {
+    /// A sink nobody drains: every event goes to stderr.
+    fn default() -> Self {
+        Self::new().0
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn levels_by_status() {
+        assert_eq!(Level::for_code(Code::Internal as u32), Level::Error);
+        assert_eq!(Level::for_code(Code::ResourceExhausted as u32), Level::Warn);
+        assert_eq!(Level::for_code(Code::Unimplemented as u32), Level::Info);
+        assert_eq!(Level::for_code(Code::DeadlineExceeded as u32), Level::Info);
+    }
+
+    #[test]
+    fn status_names() {
+        assert_eq!(status_name(0), "OK");
+        assert_eq!(status_name(12), "UNIMPLEMENTED");
+        assert_eq!(status_name(99), "UNKNOWN");
+    }
+
+    #[test]
+    fn events_reach_the_receiver_sanitized() {
+        let (sink, rx) = LogSink::new();
+        sink.log(Level::Warn, "queue full\nforged line");
+        let event = rx.try_recv().expect("event");
+        assert_eq!(event.level, Level::Warn);
+        assert_eq!(event.message, "queue full forged line");
+    }
+}

data/ext/tonic_rails_native/src/net.rs

@@ -14,6 +14,8 @@ use tokio::sync::{OwnedSemaphorePermit, Semaphore};
 use tokio_stream::Stream;
 use tonic::transport::server::{Connected, TcpConnectInfo};
 
+use crate::log::{Level, LogSink};
+
 /// Bind with SO_REUSEADDR + SO_REUSEPORT so several worker processes can
 /// share a port (the kernel load-balances accepts) and restarts don't
 /// fail on TIME_WAIT.  Must be called inside a tokio runtime context.
@@ -110,6 +112,7 @@ pub struct LimitedIncoming<S> {
     pub inner: S,
     pub semaphore: Arc<Semaphore>,
     pub active: Arc<AtomicUsize>,
+    pub log: LogSink,
 }
 
 impl<S> Stream for LimitedIncoming<S>
@@ -138,7 +141,10 @@ where
                 }
                 Err(_) => {
                     let active = self.active.load(Ordering::Relaxed);
-                    eprintln!("tonic-rails: connection refused: max_connections reached ({active} active)");
+                    self.log.log(
+                        Level::Warn,
+                        &format!("connection refused: max_connections reached ({active} active)"),
+                    );
                 }
             }
         }

data/ext/tonic_rails_native/src/server.rs

@@ -32,6 +32,7 @@ use tonic_health::server::HealthReporter;
 use crate::body::ServerStats;
 use crate::dispatch::{DispatchInner, DispatchService};
 use crate::gvl::{self, Cancel, DispatchContext};
+use crate::log::{Level, LogEvent, LogSink};
 use crate::net::{LimitedIncoming, bind};
 
 /// The overall-server health entry (empty service name).
@@ -91,6 +92,8 @@ pub struct NativeServer {
     stats: Arc<ServerStats>,
     compression: Arc<AtomicBool>,
     active_connections: Arc<AtomicUsize>,
+    /// Transport log events waiting for Ruby (`next_log_events`).
+    log_rx: crossbeam_channel::Receiver<LogEvent>,
 }
 
 impl DataTypeFunctions for NativeServer {
@@ -128,15 +131,20 @@ impl NativeServer {
         bind_address
             .parse::<SocketAddr>()
             .map_err(|e| arg_error(ruby, format!("invalid bind address {bind_address:?}: {e}")))?;
+        let (log, log_rx) = LogSink::new();
         Ok(Self {
             bind_address,
             max_message_size,
             callback: Mutex::new(None),
             options: Mutex::new(Options::default()),
             running: Mutex::new(None),
-            stats: Arc::new(ServerStats::default()),
+            stats: Arc::new(ServerStats {
+                log,
+                ..ServerStats::default()
+            }),
             compression: Arc::new(AtomicBool::new(false)),
             active_connections: Arc::new(AtomicUsize::new(0)),
+            log_rx,
         })
     }
 
@@ -187,10 +195,6 @@ impl NativeServer {
         self.options.lock().dispatch_queue_size = size.max(1);
     }
 
-    pub fn set_log_requests(&self, enabled: bool) {
-        self.stats.log_requests.store(enabled, Ordering::Relaxed);
-    }
-
     pub fn set_compression(&self, enabled: bool) {
         self.compression.store(enabled, Ordering::Relaxed);
     }
@@ -353,16 +357,18 @@ impl NativeServer {
             inner: tokio_stream::wrappers::TcpListenerStream::new(listener),
             semaphore: Arc::new(Semaphore::new(permits)),
             active: this.active_connections.clone(),
+            log: this.stats.log.clone(),
         };
 
         let (shutdown_tx, mut shutdown_rx) = watch::channel(false);
         let (done_tx, done_rx) = crossbeam_channel::bounded(1);
+        let log = this.stats.log.clone();
         runtime.spawn(async move {
             let signal = async move {
                 let _ = shutdown_rx.wait_for(|stop| *stop).await;
             };
             if let Err(e) = router.serve_with_incoming_shutdown(incoming, signal).await {
-                eprintln!("tonic-rails: server error: {e}");
+                log.log(Level::Error, &format!("server error: {e}"));
             }
             let _ = done_tx.send(());
         });
@@ -478,6 +484,40 @@ impl NativeServer {
         }
     }
 
+    /// Wait up to `timeout` seconds (GVL released) for transport log
+    /// events and return them as `[[level, message], ...]`, oldest first.
+    /// Returns an empty Array on timeout.
+    pub fn next_log_events(ruby: &Ruby, this: &Self, timeout: f64) -> Result<RArray, Error> {
+        let cancel = Cancel::default();
+        let rx = &this.log_rx;
+        let deadline = Instant::now() + secs(timeout);
+        let first = gvl::without_gvl(&cancel, || {
+            while !cancel.is_cancelled() {
+                let remaining = deadline.saturating_duration_since(Instant::now());
+                if remaining.is_zero() {
+                    return None;
+                }
+                match rx.recv_timeout(remaining.min(Duration::from_millis(100))) {
+                    Ok(event) => return Some(event),
+                    Err(crossbeam_channel::RecvTimeoutError::Timeout) => {}
+                    Err(crossbeam_channel::RecvTimeoutError::Disconnected) => return None,
+                }
+            }
+            None
+        })
+        .flatten();
+
+        let events = ruby.ary_new();
+        for event in first.into_iter().chain(rx.try_iter().take(255)) {
+            events.push((ruby.to_symbol(event.level.as_str()), event.message))?;
+        }
+        if events.is_empty() {
+            // Interrupted: let Ruby run trap handlers / raise before retrying.
+            ruby.thread_check_ints()?;
+        }
+        Ok(events)
+    }
+
     pub fn is_running(&self) -> bool {
         self.running.lock().is_some()
     }

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