kino 0.3.0 → 0.5.0

data/ext/kino/src/log.rs

@@ -0,0 +1,152 @@
+//! Server log lines: lifecycle notices, crashes and respawns, hook
+//! failures, the failed-request report, and whatever apps write to
+//! rack.errors, all in one shape:
+//!
+//! ```text
+//! kino[4213] worker-3: after_worker_boot hook raised RuntimeError: boom
+//! ```
+//!
+//! The label is syslog's `ident[pid]` tag plus the source that spoke (the
+//! ractor and/or thread name, `main` for neither), styled by level; the
+//! message stays plain. Ruby builds the source, since only Ruby knows its
+//! ractor and thread names, and hands the rest over; this side decides
+//! color per stream and writes, so worker ractors never touch $stdout or
+//! $stderr themselves. A multi-line message is labelled on its first line.
+
+use std::io::Write;
+
+use magnus::{Error, Ruby};
+
+use crate::style::{self, Stream};
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Level {
+    Info,
+    Warn,
+    Error,
+}
+
+impl Level {
+    /// The level named by Ruby ("info", "warn", "error").
+    pub fn parse(name: &str) -> Option<Level> {
+        match name {
+            "info" => Some(Level::Info),
+            "warn" => Some(Level::Warn),
+            "error" => Some(Level::Error),
+            _ => None,
+        }
+    }
+
+    /// Notes go to stdout; warnings and errors to stderr.
+    fn stream(self) -> Stream {
+        match self {
+            Level::Info => Stream::Stdout,
+            Level::Warn | Level::Error => Stream::Stderr,
+        }
+    }
+
+    fn sgr(self) -> &'static str {
+        match self {
+            Level::Info => style::DIM,
+            Level::Warn => style::WARN,
+            Level::Error => style::ERROR,
+        }
+    }
+}
+
+/// Write one line from `source` at `level`.
+pub fn emit(level: Level, source: &str, message: &str) {
+    let stream = level.stream();
+    let label = label(std::process::id(), source);
+    let line = format_line(level, &label, message, style::enabled(stream));
+    match stream {
+        Stream::Stdout => {
+            let _ = writeln!(std::io::stdout().lock(), "{line}");
+        }
+        Stream::Stderr => {
+            let _ = writeln!(std::io::stderr().lock(), "{line}");
+        }
+    }
+}
+
+/// The `kino[<pid>] <source>:` tag.
+pub fn label(pid: u32, source: &str) -> String {
+    format!("kino[{pid}] {source}:")
+}
+
+/// The label styled by level, then the message as given.
+pub fn format_line(level: Level, label: &str, message: &str, color: bool) -> String {
+    format!("{} {message}", style::sgr(level.sgr(), label, color))
+}
+
+/// The Ruby entry point (Kino::Log): Ruby knows its ractor and thread,
+/// the native side knows the terminal.
+pub fn log_line(ruby: &Ruby, level: String, source: String, message: String) -> Result<(), Error> {
+    let level = Level::parse(&level).ok_or_else(|| {
+        Error::new(
+            ruby.exception_arg_error(),
+            format!("unknown log level {level:?}"),
+        )
+    })?;
+    emit(level, &source, &message);
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{format_line, label, Level};
+
+    #[test]
+    fn label_is_a_syslog_tag_plus_the_source() {
+        assert_eq!(label(4213, "main"), "kino[4213] main:");
+        assert_eq!(
+            label(4213, "worker-3/thread-2"),
+            "kino[4213] worker-3/thread-2:"
+        );
+    }
+
+    #[test]
+    fn plain_line_is_label_then_message() {
+        assert_eq!(
+            format_line(Level::Info, "kino[1] main:", "hello", false),
+            "kino[1] main: hello"
+        );
+    }
+
+    #[test]
+    fn color_styles_only_the_label_by_level() {
+        assert_eq!(
+            format_line(Level::Info, "kino[1] main:", "hello", true),
+            "\x1b[90mkino[1] main:\x1b[0m hello"
+        );
+        assert_eq!(
+            format_line(Level::Warn, "kino[1] main:", "careful", true),
+            "\x1b[33mkino[1] main:\x1b[0m careful"
+        );
+        assert_eq!(
+            format_line(Level::Error, "kino[1] main:", "broke", true),
+            "\x1b[91mkino[1] main:\x1b[0m broke"
+        );
+    }
+
+    #[test]
+    fn a_report_is_labelled_on_its_first_line_only() {
+        assert_eq!(
+            format_line(
+                Level::Error,
+                "kino[1] main:",
+                "500 GET / · X: y\n    a.rb:1",
+                false
+            ),
+            "kino[1] main: 500 GET / · X: y\n    a.rb:1"
+        );
+    }
+
+    #[test]
+    fn levels_parse_from_their_ruby_names() {
+        assert_eq!(Level::parse("info"), Some(Level::Info));
+        assert_eq!(Level::parse("warn"), Some(Level::Warn));
+        assert_eq!(Level::parse("error"), Some(Level::Error));
+        assert_eq!(Level::parse("debug"), None);
+    }
+}

data/ext/kino/src/queue.rs

@@ -117,11 +117,16 @@ fn admit(
 ) -> Result<RHash, Error> {
     server.served.fetch_add(1, Ordering::Relaxed);
     slot.served.fetch_add(1, Ordering::Relaxed);
-    slot.last_started_ms.store(crate::mono::mono_ms(), Ordering::Relaxed);
+    slot.last_started_ms
+        .store(crate::mono::mono_ms(), Ordering::Relaxed);
     slot.in_flight.fetch_add(1, Ordering::Relaxed);
-    server
-        .queue_histogram
-        .record(ctx.enqueued_at.elapsed().as_micros() as u64);
+    // One clock read serves the histogram and, for the access log, the
+    // request's queue wait and the start of its time in Ruby.
+    let now = std::time::Instant::now();
+    let wait = now.duration_since(ctx.enqueued_at);
+    server.queue_histogram.record(wait.as_micros() as u64);
+    ctx.wait = wait;
+    ctx.admitted_at = now;
     slot.current.lock().push(Arc::downgrade(&ctx.responder));
     // Wire the slot into the request so blocked body reads/writes are
     // interruptible the same way the queue pop is.

data/ext/kino/src/registry.rs

@@ -5,6 +5,7 @@
 
 use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
 use std::sync::{Arc, OnceLock, Weak};
+use std::time::{Duration, Instant};
 
 use parking_lot::{Mutex, RwLock};
 
@@ -32,6 +33,51 @@ pub type BoxedCtx = Box<RequestCtx>;
 /// Probed on every take; keys are our own ids, so ahash over SipHash.
 type HashMap<K, V> = std::collections::HashMap<K, V, ahash::RandomState>;
 
+/// What runs the server's I/O, taken out at shutdown. The default
+/// multi-thread runtime and sharded I/O carry different teardown state,
+/// so the shape stays explicit instead of parallel optional fields.
+#[derive(Default)]
+pub enum RuntimeHandle {
+    /// Not started yet, or already shut down.
+    #[default]
+    None,
+    MultiThread(tokio::runtime::Runtime),
+    /// The shards' final-teardown signal and every I/O thread (shards plus
+    /// the acceptor).
+    Shards {
+        shutdown_tx: tokio::sync::watch::Sender<bool>,
+        threads: Vec<std::thread::JoinHandle<()>>,
+    },
+}
+
+impl RuntimeHandle {
+    /// Stop the I/O side, giving in-flight work `timeout` to finish. A
+    /// thread that misses the deadline is abandoned rather than joined:
+    /// a wedged shard must not hang `Server#shutdown`, which promises to
+    /// return by its deadline.
+    pub fn shutdown(self, timeout: Duration) {
+        match self {
+            RuntimeHandle::None => {}
+            RuntimeHandle::MultiThread(runtime) => runtime.shutdown_timeout(timeout),
+            RuntimeHandle::Shards {
+                shutdown_tx,
+                threads,
+            } => {
+                let _ = shutdown_tx.send(true);
+                let deadline = Instant::now() + timeout;
+                for thread in threads {
+                    while !thread.is_finished() && Instant::now() < deadline {
+                        std::thread::sleep(Duration::from_millis(1));
+                    }
+                    if thread.is_finished() {
+                        let _ = thread.join();
+                    }
+                }
+            }
+        }
+    }
+}
+
 /// One per `Kino::Server`. Owns the tokio runtime, the request queue and the
 /// worker slots.
 pub struct ServerInner {
@@ -42,9 +88,9 @@ pub struct ServerInner {
     pub req_rx: flume::Receiver<BoxedCtx>,
     /// Signals the accept loop to stop. Watch channel: `true` = draining.
     pub shutdown_tx: tokio::sync::watch::Sender<bool>,
-    /// Runtime is kept so we can shut it down explicitly; in an Option so
-    /// `shutdown_runtime` can take ownership out of the Arc.
-    pub runtime: Mutex<Option<tokio::runtime::Runtime>>,
+    /// Runtime is kept so we can shut it down explicitly; `shutdown_runtime`
+    /// takes ownership out of the Arc.
+    pub runtime: Mutex<RuntimeHandle>,
     pub slots: RwLock<Vec<Arc<WorkerSlot>>>,
     pub in_flight: AtomicUsize,
     /// Requests handed to Ruby workers (admitted), and requests rejected
@@ -69,6 +115,8 @@ pub struct ServerInner {
     pub quarantine_replacements: AtomicU64,
     pub topology: Topology,
     pub https: bool,
+    /// The socket file of a `unix://` bind, removed at shutdown.
+    pub unix_path: Option<std::path::PathBuf>,
     /// Native access log sink (None unless log_requests is on).
     pub access_log: Option<crate::logsink::Sink>,
     /// Lane-dispatch mode: per-worker queues, awake-preferring dispatch.
@@ -116,8 +164,8 @@ pub const LANE_DEPTH: usize = 4;
 /// Fixed queue-wait bucket boundaries in microseconds (0.5ms .. 10s),
 /// ascending. Emitted in seconds. Not a knob (YAGNI).
 pub const QUEUE_BOUNDS_US: [u64; 14] = [
-    500, 1_000, 2_500, 5_000, 10_000, 25_000, 50_000, 100_000,
-    250_000, 500_000, 1_000_000, 2_500_000, 5_000_000, 10_000_000,
+    500, 1_000, 2_500, 5_000, 10_000, 25_000, 50_000, 100_000, 250_000, 500_000, 1_000_000,
+    2_500_000, 5_000_000, 10_000_000,
 ];
 
 /// Queue-wait histogram: per-bucket counts plus an overflow (the implicit
@@ -287,7 +335,7 @@ pub fn test_server(lanes: bool, queue_depth: usize) -> Arc<ServerInner> {
         req_tx: Mutex::new(Some(req_tx)),
         req_rx,
         shutdown_tx,
-        runtime: Mutex::new(None),
+        runtime: Mutex::new(RuntimeHandle::None),
         slots: RwLock::new(Vec::new()),
         in_flight: AtomicUsize::new(0),
         served: AtomicU64::new(0),
@@ -299,8 +347,14 @@ pub fn test_server(lanes: bool, queue_depth: usize) -> Arc<ServerInner> {
         state: std::sync::atomic::AtomicU8::new(STATE_BOOTING),
         respawns: AtomicU64::new(0),
         quarantine_replacements: AtomicU64::new(0),
-        topology: Topology { mode: "threaded".to_string(), workers: 0, threads: 0, batch: 1 },
+        topology: Topology {
+            mode: "threaded".to_string(),
+            workers: 0,
+            threads: 0,
+            batch: 1,
+        },
         https: false,
+        unix_path: None,
         access_log: None,
         lanes,
         lane_cursor: AtomicUsize::new(0),
@@ -314,6 +368,44 @@ mod tests {
     use super::*;
     use crate::request::test_ctx;
 
+    #[test]
+    fn shards_shutdown_joins_threads_that_observe_the_signal() {
+        let (shutdown_tx, rx) = tokio::sync::watch::channel(false);
+        let thread = std::thread::spawn(move || {
+            while !*rx.borrow() {
+                std::thread::sleep(Duration::from_millis(1));
+            }
+        });
+
+        let start = Instant::now();
+        RuntimeHandle::Shards {
+            shutdown_tx,
+            threads: vec![thread],
+        }
+        .shutdown(Duration::from_secs(5));
+
+        // The thread exits on the signal, so the join comes nowhere near
+        // the deadline.
+        assert!(start.elapsed() < Duration::from_secs(1));
+    }
+
+    #[test]
+    fn shards_shutdown_abandons_a_wedged_thread_at_the_deadline() {
+        let (shutdown_tx, _rx) = tokio::sync::watch::channel(false);
+        let wedged = std::thread::spawn(|| std::thread::sleep(Duration::from_secs(30)));
+
+        let start = Instant::now();
+        RuntimeHandle::Shards {
+            shutdown_tx,
+            threads: vec![wedged],
+        }
+        .shutdown(Duration::from_millis(50));
+
+        let elapsed = start.elapsed();
+        assert!(elapsed >= Duration::from_millis(50));
+        assert!(elapsed < Duration::from_secs(5));
+    }
+
     #[test]
     fn worker_registration_hands_out_sequential_slot_ids() {
         let server = test_server(false, 4);
@@ -417,9 +509,9 @@ mod tests {
     #[test]
     fn queue_histogram_buckets_by_wait() {
         let h = QueueHistogram::new();
-        h.record(400);        // <= 500 -> bucket 0
-        h.record(500);        // == 500 -> bucket 0 (inclusive)
-        h.record(600);        // (500, 1000] -> bucket 1
+        h.record(400); // <= 500 -> bucket 0
+        h.record(500); // == 500 -> bucket 0 (inclusive)
+        h.record(600); // (500, 1000] -> bucket 1
         h.record(20_000_000); // > last bound -> overflow
         let s = h.snapshot();
         assert_eq!(s.buckets[0], 2);

data/ext/kino/src/request.rs

@@ -44,6 +44,41 @@ pub struct RequestCtx {
     /// 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 {
@@ -233,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))
@@ -252,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(
@@ -306,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))
@@ -429,6 +471,10 @@ pub fn test_ctx() -> crate::registry::BoxedCtx {
         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/response.rs

@@ -115,10 +115,7 @@ pub fn plain_response(status: u16, message: &'static str) -> HyperResponse {
 mod tests {
     use super::*;
 
-    fn pair() -> (
-        Responder,
-        tokio::sync::oneshot::Receiver<HyperResponse>,
-    ) {
+    fn pair() -> (Responder, tokio::sync::oneshot::Receiver<HyperResponse>) {
         let (head_tx, head_rx) = tokio::sync::oneshot::channel();
         (Responder::new(head_tx), head_rx)
     }