kino 0.2.1 → 0.4.0

data/ext/kino/src/request.rs

@@ -41,6 +41,44 @@ pub struct RequestCtx {
     /// here and ride to hyper without a copy (pin.rs).
     pub pin_slab: Arc<crate::pin::PinSlab>,
     pub responder: Arc<Responder>,
+    /// When this request entered the queue, for the queue-wait histogram.
+    /// Stamped at ctx creation; read once at admit (queue.rs).
+    pub enqueued_at: std::time::Instant,
+    /// Whether the access log wants timing: decided at intake, read on
+    /// the way out, so an idle log costs nothing per request.
+    pub timed: bool,
+    /// Queue wait, stamped at admit (queue.rs): the log's `wait`.
+    pub wait: std::time::Duration,
+    /// When a worker took the request; elapsed at the response head it is
+    /// the log's `ruby`.
+    pub admitted_at: std::time::Instant,
+    /// GC pause and objects allocated during the app call, when the
+    /// worker measured them (Request#timing).
+    pub gc: Option<(std::time::Duration, u64)>,
+}
+
+impl RequestCtx {
+    /// The timing this request carries to the access log.
+    fn timing(&self) -> crate::access_log::Timing {
+        crate::access_log::Timing {
+            wait: self.wait,
+            ruby: self.admitted_at.elapsed(),
+            gc: self.gc,
+        }
+    }
+}
+
+/// Attach the request's timing to a response head when the access log
+/// wants it; the extension is the one allocation an idle log skips.
+fn timed(
+    ctx: &RequestCtx,
+    builder: hyper::http::response::Builder,
+) -> hyper::http::response::Builder {
+    if ctx.timed {
+        builder.extension(ctx.timing())
+    } else {
+        builder
+    }
 }
 
 impl Drop for RequestCtx {
@@ -230,7 +268,7 @@ pub fn respond_simple(
     body: RString,
 ) -> Result<bool, Error> {
     let ctx = request.0.borrow();
-    let builder = build_head(status, headers)?;
+    let builder = timed(&ctx, build_head(status, headers)?);
     let bytes = body_bytes(&ctx, body);
     let response = builder
         .body(full_body(bytes))
@@ -249,6 +287,13 @@ fn body_bytes(ctx: &RequestCtx, body: RString) -> Bytes {
 }
 
 impl Request {
+    /// The worker's measurements around the app call, for the access log's
+    /// breakdown: the GC pause in nanoseconds and the objects allocated.
+    /// Called only when the access log is on.
+    pub fn set_timing(_ruby: &Ruby, rb_self: &Request, gc_nanos: u64, allocs: u64) {
+        rb_self.0.borrow_mut().gc = Some((std::time::Duration::from_nanos(gc_nanos), allocs));
+    }
+
     /// Next chunk of the request body, at most `max_len` bytes; nil at EOF.
     /// Blocks (GVL released) until the client sends more.
     pub fn read_body(
@@ -303,7 +348,7 @@ impl Request {
         headers: RHash,
     ) -> Result<bool, Error> {
         let ctx = rb_self.0.borrow();
-        let builder = build_head(status, headers)?;
+        let builder = timed(&ctx, build_head(status, headers)?);
         ctx.responder
             .send_stream_head(builder)
             .map_err(|e| invalid_response(ruby, e))
@@ -425,6 +470,11 @@ pub fn test_ctx() -> crate::registry::BoxedCtx {
         slot: None,
         pin_slab: Arc::new(crate::pin::PinSlab::new()),
         responder: Arc::new(Responder::new(head_tx)),
+        enqueued_at: std::time::Instant::now(),
+        timed: false,
+        wait: std::time::Duration::ZERO,
+        admitted_at: std::time::Instant::now(),
+        gc: None,
     })
 }
 

data/ext/kino/src/server.rs

@@ -2,7 +2,7 @@
 //! intake. Ruby is never on these threads; the only contact points are the
 //! flume queue (in) and each request's Responder (out).
 
-use std::net::SocketAddr;
+use std::net::{IpAddr, Ipv4Addr, SocketAddr};
 use std::sync::atomic::Ordering;
 use std::sync::Arc;
 use std::time::Duration;
@@ -13,6 +13,7 @@ use hyper_util::rt::TokioIo;
 use magnus::{Error, Ruby};
 use parking_lot::{Mutex, RwLock};
 
+use crate::listen::Listener;
 use crate::registry::{self, BoxedCtx, ServerInner, WorkerSlot};
 use crate::request::RequestCtx;
 use crate::response::{plain_response, HyperResponse, Responder};
@@ -44,8 +45,10 @@ fn cfg_opt<T: magnus::TryConvert>(
 /// at boot, so Hash-lookup cost is irrelevant and the interface stays
 /// extensible. Binding is synchronous so address errors raise in Ruby at
 /// `start` time; returns the actual port for `port: 0`. TLS config errors
-/// (bad cert/key) also raise here, before any traffic.
-pub fn server_start(ruby: &Ruby, config: magnus::RHash) -> Result<(u64, u16), Error> {
+/// (bad cert/key) also raise here, before any traffic. The third element
+/// of the return tuple is the control-plane port (nil unless control_bind
+/// is configured).
+pub fn server_start(ruby: &Ruby, config: magnus::RHash) -> Result<(u64, u16, Option<u16>), Error> {
     let bind: String = cfg(ruby, config, "bind")?;
     let port: u16 = cfg(ruby, config, "port")?;
     let queue_depth: usize = cfg(ruby, config, "queue_depth")?;
@@ -58,6 +61,10 @@ pub fn server_start(ruby: &Ruby, config: magnus::RHash) -> Result<(u64, u16), Er
     let tls_key: Option<String> = cfg_opt(ruby, config, "tls_key")?;
     let lanes: bool = cfg_opt(ruby, config, "lanes")?.unwrap_or(false);
     let log_requests: bool = cfg_opt(ruby, config, "log_requests")?.unwrap_or(false);
+    let mode: String = cfg_opt(ruby, config, "mode")?.unwrap_or_else(|| "threaded".to_string());
+    let workers: usize = cfg_opt(ruby, config, "workers")?.unwrap_or(0);
+    let threads: usize = cfg_opt(ruby, config, "threads")?.unwrap_or(0);
+    let batch: usize = cfg_opt(ruby, config, "batch")?.unwrap_or(1);
     let acceptor = match (&tls_cert, &tls_key) {
         (Some(cert), Some(key)) => Some(
             crate::tls::build_acceptor(cert, key)
@@ -72,15 +79,32 @@ pub fn server_start(ruby: &Ruby, config: magnus::RHash) -> Result<(u64, u16), Er
         }
     };
 
-    let listener = std::net::TcpListener::bind((bind.as_str(), port))
-        .map_err(|e| io_error(ruby, "bind failed", e))?;
-    listener
-        .set_nonblocking(true)
-        .map_err(|e| io_error(ruby, "listener setup failed", e))?;
+    let listener =
+        Listener::bind(&bind, port).map_err(|e| io_error(ruby, "bind failed", e))?;
+    // Ruby refuses this combination up front; this guards embedders
+    // calling the native layer directly.
+    if acceptor.is_some() && matches!(listener, Listener::Unix(..)) {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "TLS is not supported on a unix socket bind",
+        ));
+    }
     let local_port = listener
-        .local_addr()
-        .map_err(|e| io_error(ruby, "listener setup failed", e))?
-        .port();
+        .port()
+        .map_err(|e| io_error(ruby, "listener setup failed", e))?;
+    let unix_path = match &listener {
+        Listener::Unix(_, path) => Some(path.clone()),
+        Listener::Tcp(_) => None,
+    };
+
+    let control_bind_addr: Option<String> = cfg_opt(ruby, config, "control_bind")?;
+    let control_token: Option<String> = cfg_opt(ruby, config, "control_token")?;
+    let control_bind = control_bind_addr
+        .as_deref()
+        .map(|addr| {
+            crate::control::bind_control(addr).map_err(|e| io_error(ruby, "control bind failed", e))
+        })
+        .transpose()?;
 
     let mut builder = tokio::runtime::Builder::new_multi_thread();
     builder.enable_all().thread_name("kino-tokio");
@@ -108,17 +132,22 @@ pub fn server_start(ruby: &Ruby, config: magnus::RHash) -> Result<(u64, u16), Er
         request_timeout_ms,
         max_body_size,
         timeouts: std::sync::atomic::AtomicU64::new(0),
+        state: std::sync::atomic::AtomicU8::new(registry::STATE_BOOTING),
+        respawns: std::sync::atomic::AtomicU64::new(0),
+        quarantine_replacements: std::sync::atomic::AtomicU64::new(0),
+        topology: registry::Topology { mode, workers, threads, batch },
         https: acceptor.is_some(),
+        unix_path,
         access_log: log_requests.then(|| crate::logsink::Sink::new(std::io::stdout())),
         lanes,
         lane_cursor: std::sync::atomic::AtomicUsize::new(0),
         pin_slab: Arc::new(crate::pin::PinSlab::new()),
+        queue_histogram: registry::QueueHistogram::new(),
     });
 
     let tokio_listener = {
         let _guard = runtime.enter();
-        tokio::net::TcpListener::from_std(listener)
-            .map_err(|e| io_error(ruby, "listener setup failed", e))?
+        AsyncListener::from_std(listener).map_err(|e| io_error(ruby, "listener setup failed", e))?
     };
     runtime.spawn(accept_loop(
         tokio_listener,
@@ -130,8 +159,28 @@ pub fn server_start(ruby: &Ruby, config: magnus::RHash) -> Result<(u64, u16), Er
     *server.runtime.lock() = Some(runtime);
 
     let id = server.id;
+    let control_port = match control_bind {
+        // Not yet in the registry: on failure Ruby never learns this id, so
+        // nothing could ever reach it to shut it down. The accept loop's
+        // task holds its own Arc back to `server` (stored inside its own
+        // `runtime` field), so just dropping our handle would leak the
+        // runtime forever; take it out and stop it explicitly instead.
+        // Safe to block here: this is the plain Ruby thread, no async
+        // context above it.
+        Some(bind) => match crate::control::start(bind, server.clone(), control_token) {
+            Ok(port) => port,
+            Err(e) => {
+                // A plain drop blocks until the accept loop's task (its
+                // only task, idling on accept/shutdown) is torn down; the
+                // runtime only ever had this one thing to cancel.
+                drop(server.runtime.lock().take());
+                return Err(io_error(ruby, "control start failed", e));
+            }
+        },
+        None => None,
+    };
     registry::insert(server);
-    Ok((id, local_port))
+    Ok((id, local_port, control_port))
 }
 
 /// Slowloris guard for TLS: a client that completes the TCP connect but then
@@ -142,8 +191,59 @@ pub fn server_start(ruby: &Ruby, config: magnus::RHash) -> Result<(u64, u16), Er
 /// timeout: not a knob.
 const TLS_HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(10);
 
+/// What a unix-socket connection reports as its addresses. The peer is
+/// local by definition (REMOTE_ADDR 127.0.0.1), and a socket has no port,
+/// so SERVER_PORT falls back to http's default when the Host header names
+/// none, the way Puma reports unix-socket requests.
+const UNIX_PEER: SocketAddr = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 0);
+const UNIX_LOCAL: SocketAddr = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 80);
+
+/// The accept loop's listener: TCP (optionally behind TLS), or a unix
+/// socket, which carries plain HTTP only.
+enum AsyncListener {
+    Tcp(tokio::net::TcpListener),
+    Unix(tokio::net::UnixListener),
+}
+
+/// One accepted connection, before the protocol layer sees it.
+enum Conn {
+    Tcp(tokio::net::TcpStream),
+    Unix(tokio::net::UnixStream),
+}
+
+impl AsyncListener {
+    /// Register the bound listener with the current runtime.
+    fn from_std(listener: Listener) -> std::io::Result<AsyncListener> {
+        Ok(match listener {
+            Listener::Tcp(listener) => AsyncListener::Tcp(tokio::net::TcpListener::from_std(listener)?),
+            Listener::Unix(listener, _) => {
+                AsyncListener::Unix(tokio::net::UnixListener::from_std(listener)?)
+            }
+        })
+    }
+
+    /// The next connection with its (peer, local) addresses.
+    async fn accept(&self) -> std::io::Result<(Conn, SocketAddr, SocketAddr)> {
+        match self {
+            AsyncListener::Tcp(listener) => {
+                let (stream, remote_addr) = listener.accept().await?;
+                // Small responses must not wait on Nagle + delayed ACK.
+                let _ = stream.set_nodelay(true);
+                let local_addr = stream
+                    .local_addr()
+                    .unwrap_or_else(|_| SocketAddr::from(([0, 0, 0, 0], 0)));
+                Ok((Conn::Tcp(stream), remote_addr, local_addr))
+            }
+            AsyncListener::Unix(listener) => {
+                let (stream, _) = listener.accept().await?;
+                Ok((Conn::Unix(stream), UNIX_PEER, UNIX_LOCAL))
+            }
+        }
+    }
+}
+
 async fn accept_loop(
-    listener: tokio::net::TcpListener,
+    listener: AsyncListener,
     acceptor: Option<tokio_rustls::TlsAcceptor>,
     server: Arc<ServerInner>,
     max_connections: usize,
@@ -162,25 +262,20 @@ async fn accept_loop(
                 Err(_) => break, // semaphore closed
             },
         };
-        let (stream, remote_addr) = tokio::select! {
+        let (conn, remote_addr, local_addr) = tokio::select! {
             _ = shutdown_rx.changed() => break,
             accepted = listener.accept() => match accepted {
-                Ok(pair) => pair,
+                Ok(accepted) => accepted,
                 Err(_) => continue, // transient accept error; permit drops, retry
             },
         };
-        // Small responses must not wait on Nagle + delayed ACK.
-        let _ = stream.set_nodelay(true);
-        let local_addr = stream
-            .local_addr()
-            .unwrap_or_else(|_| SocketAddr::from(([0, 0, 0, 0], 0)));
         let server = server.clone();
         let acceptor = acceptor.clone();
         tokio::spawn(async move {
             // Held for the connection's lifetime; dropping it frees a slot.
             let _permit = permit;
-            match acceptor {
-                Some(acceptor) => {
+            match (conn, acceptor) {
+                (Conn::Tcp(stream), Some(acceptor)) => {
                     // Handshake failures (port scans, plain HTTP to a TLS
                     // port) and stalled handshakes (slowloris) just drop the
                     // connection; the timeout bounds the latter.
@@ -188,7 +283,13 @@ async fn accept_loop(
                     let Ok(Ok(tls)) = handshake.await else { return };
                     serve_connection(tls, server, remote_addr, local_addr).await;
                 }
-                None => serve_connection(stream, server, remote_addr, local_addr).await,
+                (Conn::Tcp(stream), None) => {
+                    serve_connection(stream, server, remote_addr, local_addr).await
+                }
+                // TLS over a unix socket is refused at bind time.
+                (Conn::Unix(stream), _) => {
+                    serve_connection(stream, server, remote_addr, local_addr).await
+                }
             }
         });
     }
@@ -270,18 +371,17 @@ async fn handle_request(
     let (parts, body) = req.into_parts();
 
     // Access-log metadata is captured only when logging is on: one Instant
-    // read plus one small String per request.
-    let log_meta = server.access_log.as_ref().map(|_| {
+    // read plus two small Strings per request. The arrival record is
+    // queued now, before the app sees the request, so a hang shows as an
+    // arrow with no answer; the completion record follows the response.
+    let log_meta = server.access_log.as_ref().map(|log| {
         let target = match parts.uri.query() {
             Some(q) => format!("{}?{}", parts.uri.path(), q),
             None => parts.uri.path().to_string(),
         };
-        (
-            std::time::Instant::now(),
-            parts.method.to_string(),
-            target,
-            parts.version,
-        )
+        let method = parts.method.to_string();
+        log.write_line(crate::access_log::arrival(&method, &target, remote_addr.ip()));
+        (std::time::Instant::now(), method, target)
     });
 
     // Body-size guard: an honestly-declared oversize body is refused with a
@@ -338,6 +438,7 @@ async fn handle_request(
 
     let (head_tx, head_rx) = tokio::sync::oneshot::channel();
     let responder = Arc::new(Responder::new(head_tx));
+    let now = std::time::Instant::now();
     let ctx = Box::new(RequestCtx {
         method: parts.method,
         uri: parts.uri,
@@ -353,6 +454,11 @@ async fn handle_request(
         slot: None,
         pin_slab: server.pin_slab.clone(),
         responder,
+        enqueued_at: now,
+        timed: server.access_log.is_some(),
+        wait: Duration::ZERO,
+        admitted_at: now,
+        gc: None,
     });
 
     // Drop guard, not manual decrement: when a client aborts mid-request,
@@ -431,17 +537,20 @@ async fn handle_request(
         }
     };
 
-    if let (Some(log), Some((start, method, target, version))) =
-        (server.access_log.as_ref(), log_meta)
-    {
-        let status = response.status().as_u16();
-        let line = format!(
-            "{} [{}] \"{method} {target} {version:?}\" {status} {:.1}ms",
-            remote_addr.ip(),
-            httpdate::fmt_http_date(std::time::SystemTime::now()),
-            start.elapsed().as_secs_f64() * 1000.0
-        );
-        log.write_line(crate::style::status_colored(status, &line));
+    if let (Some(log), Some((start, method, target))) = (server.access_log.as_ref(), log_meta) {
+        // The worker attached its timing to the response head; a 503 or
+        // 504 never reached a worker and carries none.
+        let timing = response
+            .extensions()
+            .get::<crate::access_log::Timing>()
+            .copied();
+        log.write_line(crate::access_log::completion(
+            response.status().as_u16(),
+            &method,
+            &target,
+            start.elapsed(),
+            timing,
+        ));
     }
 
     Ok(branded(response))
@@ -518,11 +627,28 @@ pub fn register_worker(ruby: &Ruby, server_id: u64) -> Result<usize, Error> {
 
 pub fn stop_accepting(_ruby: &Ruby, server_id: u64) -> Result<(), Error> {
     if let Some(server) = registry::try_get(server_id) {
+        server.state.store(registry::STATE_DRAINING, Ordering::Relaxed);
         let _ = server.shutdown_tx.send(true);
     }
     Ok(())
 }
 
+/// Ruby reports the worker pool up; /ready starts answering 200.
+pub fn control_ready(_ruby: &Ruby, server_id: u64) -> Result<(), Error> {
+    if let Some(server) = registry::try_get(server_id) {
+        server.state.store(registry::STATE_READY, Ordering::Relaxed);
+    }
+    Ok(())
+}
+
+/// One worker respawn, recorded by the Ruby supervisor.
+pub fn record_respawn(_ruby: &Ruby, server_id: u64) -> Result<(), Error> {
+    if let Some(server) = registry::try_get(server_id) {
+        server.respawns.fetch_add(1, Ordering::Relaxed);
+    }
+    Ok(())
+}
+
 pub fn close_queue(_ruby: &Ruby, server_id: u64) -> Result<(), Error> {
     if let Some(server) = registry::try_get(server_id) {
         server.req_tx.lock().take();
@@ -546,6 +672,12 @@ fn abort_slot(slot: &WorkerSlot) {
             responder.respond_500_if_unsent();
         }
     }
+    // A dead worker holds nothing: every request it had is answered above
+    // (or already was), so the slot is quiescent from here on. Without
+    // this, a crashed worker's slot reports in_flight>=1 forever (the
+    // supervisor never reuses a slot after a crash), wedging /stats,
+    // /metrics and server.stats with a phantom busy worker.
+    slot.in_flight.store(0, Ordering::Relaxed);
     // Lane mode: this worker is dead. Close its lane so the dispatcher
     // skips it, and drain anything queued; dropping each ctx fires the
     // Drop-500 backstop so those clients aren't left hanging.
@@ -587,6 +719,10 @@ pub fn shutdown_runtime(_ruby: &Ruby, server_id: u64, timeout_ms: u64) -> Result
         if let Some(runtime) = server.runtime.lock().take() {
             runtime.shutdown_timeout(Duration::from_millis(timeout_ms));
         }
+        // The listener is closed with the runtime; its socket file is not.
+        if let Some(path) = &server.unix_path {
+            crate::listen::cleanup_unix(path);
+        }
     }
     Ok(())
 }
@@ -601,21 +737,15 @@ pub fn pin_keeper(
     Ok(ruby.obj_wrap(crate::pin::PinKeeper(server.pin_slab.clone())))
 }
 
-/// Errors print in red on color terminals. Covers worker errors,
-/// supervisor crash reports, and everything apps write to rack.errors.
-pub fn log_error(message: String) {
-    eprintln!("{}", crate::style::red(&format!("[Kino] {message}")));
-}
-
 /// Full stats snapshot: [queued, in_flight, served, rejected, timeouts,
-/// lane_depths]. lane_depths is nil unless lane dispatch is on.
+/// respawns, lane_depths]. lane_depths is nil unless lane dispatch is on.
 #[allow(clippy::type_complexity)]
 pub fn server_stats(
     _ruby: &Ruby,
     server_id: u64,
-) -> Result<(usize, usize, u64, u64, u64, Option<Vec<usize>>), Error> {
+) -> Result<(usize, usize, u64, u64, u64, u64, Option<Vec<usize>>), Error> {
     let Some(server) = registry::try_get(server_id) else {
-        return Ok((0, 0, 0, 0, 0, None));
+        return Ok((0, 0, 0, 0, 0, 0, None));
     };
     let lane_depths = server.lane_depths();
     let queued = server.req_rx.len() + lane_depths.as_ref().map_or(0, |d| d.iter().sum::<usize>());
@@ -625,10 +755,56 @@ pub fn server_stats(
         server.served.load(Ordering::Relaxed),
         server.rejected.load(Ordering::Relaxed),
         server.timeouts.load(Ordering::Relaxed),
+        server.respawns.load(Ordering::Relaxed),
         lane_depths,
     ))
 }
 
+/// Queue-wait count and summed seconds for Server#stats parity. Zeros when
+/// the server is gone.
+pub fn queue_time(_ruby: &Ruby, server_id: u64) -> Result<(u64, f64), Error> {
+    let Some(server) = registry::try_get(server_id) else {
+        return Ok((0, 0.0));
+    };
+    let h = server.queue_histogram.snapshot();
+    Ok((h.count, h.sum_seconds()))
+}
+
+/// One worker slot's [index, served, in_flight, busy_ms, quarantined] row.
+pub type WorkerStatRow = (usize, u64, usize, u64, bool);
+
+/// Per-slot rows for Server#stats parity: [index, served, in_flight,
+/// busy_ms, quarantined] each. Empty when the server is gone.
+pub fn worker_stats(
+    _ruby: &Ruby,
+    server_id: u64,
+) -> Result<Vec<WorkerStatRow>, Error> {
+    let Some(server) = registry::try_get(server_id) else {
+        return Ok(Vec::new());
+    };
+    Ok(crate::control::collect_worker_status(&server)
+        .into_iter()
+        .map(|w| (w.index, w.served, w.in_flight, w.busy_ms, w.quarantined))
+        .collect())
+}
+
+/// Mark a slot quarantined (the monitor has abandoned it as wedged).
+pub fn quarantine_slot(ruby: &Ruby, server_id: u64, worker_id: usize) -> Result<(), Error> {
+    if let Some(server) = registry::try_get(server_id) {
+        let slot = server.slot(ruby, worker_id)?;
+        slot.quarantined.store(true, Ordering::Relaxed);
+    }
+    Ok(())
+}
+
+/// One replacement spawned by the quarantine monitor.
+pub fn record_quarantine_replacement(_ruby: &Ruby, server_id: u64) -> Result<(), Error> {
+    if let Some(server) = registry::try_get(server_id) {
+        server.quarantine_replacements.fetch_add(1, Ordering::Relaxed);
+    }
+    Ok(())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

data/ext/kino/src/style.rs

@@ -1,18 +1,19 @@
-//! ANSI styling for the few places the native layer writes to the
-//! terminal: stderr error lines and the stdout access log. (The Ruby-side
-//! startup banner has its own twin in Kino::CLI.) Color-capability is
-//! decided once per stream; every styled string resets at its end so
-//! nothing bleeds.
+//! ANSI styling for what the native layer writes to the terminal: the
+//! access log on stdout and server log lines on either stream. (The
+//! Ruby-side startup banner has its own twin in Kino::CLI.) Color
+//! capability is decided once per stream; every styled string resets at
+//! its end so nothing bleeds.
 
 use std::sync::OnceLock;
 
 #[derive(Clone, Copy)]
-enum Stream {
+pub enum Stream {
     Stdout,
     Stderr,
 }
 
-fn enabled(stream: Stream) -> bool {
+/// Whether `stream` is a color terminal: a tty, no NO_COLOR, TERM not dumb.
+pub fn enabled(stream: Stream) -> bool {
     use std::io::IsTerminal;
     static STDOUT: OnceLock<bool> = OnceLock::new();
     static STDERR: OnceLock<bool> = OnceLock::new();
@@ -27,55 +28,51 @@ fn enabled(stream: Stream) -> bool {
     }
 }
 
-/// Wrap `text` in an SGR code (e.g. "31" red, "1" bold, "38;5;208"
-/// 256-color), plain when the stream isn't a color terminal.
-fn paint(stream: Stream, code: &str, text: &str) -> String {
-    if enabled(stream) {
+/// Wrap `text` in an SGR code ("1" bold, "91" bright red, "1;32" bold
+/// green) when `color`, resetting at the end; plain otherwise.
+pub fn sgr(code: &str, text: &str, color: bool) -> String {
+    if color {
         format!("\x1b[{code}m{text}\x1b[0m")
     } else {
         text.to_string()
     }
 }
 
-/// Errors on stderr are bright red (91): the base red slot (31) is
-/// remapped to odd hues by some terminal themes; 91 stays red.
-pub fn red(text: &str) -> String {
-    paint(Stream::Stderr, "91", text)
-}
+/// Dark gray: timestamps and the timing breakdown recede behind the record.
+pub const DIM: &str = "90";
+/// Bold bright white: the arrival line, which has no status to color by.
+pub const BOLD_WHITE: &str = "1;97";
+/// Warnings are yellow.
+pub const WARN: &str = "33";
+/// Errors are bright red (91): the base red slot (31) is remapped to odd
+/// hues by some terminal themes; 91 stays red.
+pub const ERROR: &str = "91";
 
-/// The SGR code for a status class (basic 16-color palette only):
-/// 2xx green, 3xx yellow, 4xx maroon (ANSI color 1, plain dark red),
-/// 5xx bright red, anything else uncolored.
-fn status_sgr(status: u16) -> Option<&'static str> {
+/// The SGR code for a status class, bold so the record leads its line
+/// (basic 16-color palette only): 2xx green, 3xx yellow, 4xx maroon
+/// (ANSI color 1, plain dark red), 5xx bright red, anything else uncolored.
+pub fn status_sgr(status: u16) -> Option<&'static str> {
     match status {
-        200..=299 => Some("32"),
-        300..=399 => Some("33"),
-        400..=499 => Some("31"),
-        500..=599 => Some("91"),
+        200..=299 => Some("1;32"),
+        300..=399 => Some("1;33"),
+        400..=499 => Some("1;31"),
+        500..=599 => Some("1;91"),
         _ => None,
     }
 }
 
-/// Access-log lines on stdout, tinted by status class.
-pub fn status_colored(status: u16, line: &str) -> String {
-    match status_sgr(status) {
-        Some(code) => paint(Stream::Stdout, code, line),
-        None => line.to_string(),
-    }
-}
-
 #[cfg(test)]
 mod tests {
-    use super::status_sgr;
+    use super::{sgr, status_sgr};
 
     #[test]
     fn status_classes_map_to_their_colors() {
-        assert_eq!(status_sgr(200), Some("32")); // green
-        assert_eq!(status_sgr(299), Some("32"));
-        assert_eq!(status_sgr(301), Some("33")); // yellow
-        assert_eq!(status_sgr(404), Some("31")); // maroon
-        assert_eq!(status_sgr(500), Some("91")); // bright red
-        assert_eq!(status_sgr(599), Some("91"));
+        assert_eq!(status_sgr(200), Some("1;32")); // green
+        assert_eq!(status_sgr(299), Some("1;32"));
+        assert_eq!(status_sgr(301), Some("1;33")); // yellow
+        assert_eq!(status_sgr(404), Some("1;31")); // maroon
+        assert_eq!(status_sgr(500), Some("1;91")); // bright red
+        assert_eq!(status_sgr(599), Some("1;91"));
     }
 
     #[test]
@@ -84,4 +81,10 @@ mod tests {
         assert_eq!(status_sgr(199), None);
         assert_eq!(status_sgr(600), None);
     }
+
+    #[test]
+    fn sgr_wraps_and_resets_only_when_coloring() {
+        assert_eq!(sgr("1;32", "ok", true), "\x1b[1;32mok\x1b[0m");
+        assert_eq!(sgr("1;32", "ok", false), "ok");
+    }
 }