kino 0.3.0 → 0.4.0

data/ext/kino/src/control.rs

@@ -300,32 +300,9 @@ pub enum ControlBind {
 /// Claim the control address. Both arms bind synchronously so a
 /// conflict raises at boot, like the main listener.
 pub fn bind_control(addr: &str) -> std::io::Result<ControlBind> {
-    if let Some(path) = addr.strip_prefix("unix://") {
-        let path = std::path::PathBuf::from(path);
-        // A path that already exists is either a live listener (refuse: do
-        // not steal it) or a stale file left behind by a crashed process
-        // (safe to unlink and reclaim). Probe with a connect: a successful
-        // connect means someone is accepting on it right now.
-        match std::os::unix::net::UnixStream::connect(&path) {
-            Ok(_) => {
-                return Err(std::io::Error::new(
-                    std::io::ErrorKind::AddrInUse,
-                    "control socket is in use",
-                ));
-            }
-            Err(e) if e.kind() == std::io::ErrorKind::ConnectionRefused => {
-                match std::fs::remove_file(&path) {
-                    Ok(()) => {}
-                    Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
-                    Err(e) => return Err(e),
-                }
-            }
-            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
-            Err(e) => return Err(e),
-        }
-        let listener = std::os::unix::net::UnixListener::bind(&path)?;
-        listener.set_nonblocking(true)?;
-        Ok(ControlBind::Unix(listener, path))
+    if let Some(path) = crate::listen::unix_path(addr) {
+        let listener = crate::listen::bind_unix(path)?;
+        Ok(ControlBind::Unix(listener, path.to_path_buf()))
     } else {
         let listener = std::net::TcpListener::bind(addr)?;
         listener.set_nonblocking(true)?;
@@ -405,22 +382,28 @@ fn run(
 ) {
     let runtime = match tokio::runtime::Builder::new_current_thread().enable_all().build() {
         Ok(runtime) => runtime,
-        Err(e) => return crate::server::log_error(format!("control runtime failed: {e}")),
+        Err(e) => return native_error(format!("control runtime failed: {e}")),
     };
     runtime.block_on(async move {
         match bind {
             ControlBind::Tcp(listener, _) => match tokio::net::TcpListener::from_std(listener) {
                 Ok(listener) => serve(TcpOrUnix::Tcp(listener), server, token, stop_rx).await,
-                Err(e) => crate::server::log_error(format!("control listener failed: {e}")),
+                Err(e) => native_error(format!("control listener failed: {e}")),
             },
             ControlBind::Unix(listener, _) => match tokio::net::UnixListener::from_std(listener) {
                 Ok(listener) => serve(TcpOrUnix::Unix(listener), server, token, stop_rx).await,
-                Err(e) => crate::server::log_error(format!("control listener failed: {e}")),
+                Err(e) => native_error(format!("control listener failed: {e}")),
             },
         }
     });
 }
 
+/// A failure inside the native layer itself, reported as the "native"
+/// source: no Ruby ractor or thread spoke.
+fn native_error(message: String) {
+    crate::log::emit(crate::log::Level::Error, "native", &message);
+}
+
 enum TcpOrUnix {
     Tcp(tokio::net::TcpListener),
     Unix(tokio::net::UnixListener),

data/ext/kino/src/cpus.rs

@@ -0,0 +1,37 @@
+//! How many CPUs this process may actually use: the default worker count.
+//!
+//! `Etc.nprocessors` honours the affinity mask but not a cgroup CPU quota,
+//! so a container limited to two CPUs on a 64-core host would spawn 64
+//! workers. The standard library's `available_parallelism` reads both the
+//! mask and the cgroup v1/v2 quota on Linux (rounding a fractional quota
+//! up), which is also what tokio sizes its own pool by.
+
+use magnus::{Error, Ruby};
+
+/// The usable CPU count, never below one (a quota of 0.5 CPU still needs
+/// a worker; an unreadable count falls back to one rather than failing
+/// boot).
+pub fn available_parallelism(_ruby: &Ruby) -> Result<usize, Error> {
+    Ok(count())
+}
+
+fn count() -> usize {
+    std::thread::available_parallelism().map_or(1, |n| n.get())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::count;
+
+    #[test]
+    fn reports_at_least_one_cpu() {
+        assert!(count() >= 1);
+    }
+
+    #[test]
+    fn never_exceeds_what_the_os_reports_as_online() {
+        // A quota can only lower the count below the online CPUs; never raise it.
+        let online = std::thread::available_parallelism().map_or(1, |n| n.get());
+        assert!(count() <= online);
+    }
+}

data/ext/kino/src/lib.rs

@@ -4,9 +4,13 @@
 #[global_allocator]
 static GLOBAL: mimalloc::MiMalloc = mimalloc::MiMalloc;
 
+mod access_log;
 mod control;
+mod cpus;
 mod env_strings;
 mod gvl;
+mod listen;
+mod log;
 mod logsink;
 mod mono;
 mod pin;
@@ -62,8 +66,12 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
         function!(server::interrupt_all_workers, 1),
     )?;
     native.define_singleton_method("shutdown_runtime", function!(server::shutdown_runtime, 2))?;
-    native.define_singleton_method("log_error", function!(server::log_error, 1))?;
+    native.define_singleton_method("log_line", function!(log::log_line, 3))?;
     native.define_singleton_method("sleep_chunk", function!(timer::sleep_chunk, 1))?;
+    native.define_singleton_method(
+        "available_parallelism",
+        function!(cpus::available_parallelism, 0),
+    )?;
     native.define_singleton_method("log_device_open", function!(logsink::device_open, 1))?;
     native.define_singleton_method("log_device_write", function!(logsink::device_write, 2))?;
     native.define_singleton_method("log_device_close", function!(logsink::device_close, 1))?;
@@ -87,6 +95,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     request.define_method("write_chunk", method!(Request::write_chunk, 1))?;
     request.define_method("finish", method!(Request::finish, 0))?;
     request.define_method("abort", method!(Request::abort, 0))?;
+    request.define_method("timing", method!(Request::set_timing, 2))?;
 
     // Force-resolve the TypedData class cache on the main ractor: magnus
     // resolves it lazily on first wrap, and a racy first resolution from two

data/ext/kino/src/listen.rs

@@ -0,0 +1,134 @@
+//! Listening sockets for the main server and the control plane: a TCP
+//! `host:port`, or a `unix://path` domain socket (the usual shape behind
+//! nginx). Binding is synchronous so an address conflict surfaces at boot.
+
+use std::io;
+use std::os::unix::net::UnixListener;
+use std::path::{Path, PathBuf};
+
+/// The bind scheme that selects a unix domain socket; anything else is a
+/// TCP host.
+pub const UNIX_SCHEME: &str = "unix://";
+
+/// The socket path of a `unix://` bind, or None for a TCP host.
+pub fn unix_path(bind: &str) -> Option<&Path> {
+    bind.strip_prefix(UNIX_SCHEME).map(Path::new)
+}
+
+/// A bound, non-blocking listener of either kind.
+pub enum Listener {
+    Tcp(std::net::TcpListener),
+    Unix(UnixListener, PathBuf),
+}
+
+impl Listener {
+    /// Bind `bind:port` (TCP; a hostname resolves to its addresses and the
+    /// first that binds wins) or `unix://path`.
+    pub fn bind(bind: &str, port: u16) -> io::Result<Listener> {
+        match unix_path(bind) {
+            Some(path) => Ok(Listener::Unix(bind_unix(path)?, path.to_path_buf())),
+            None => {
+                let listener = std::net::TcpListener::bind((bind, port))?;
+                listener.set_nonblocking(true)?;
+                Ok(Listener::Tcp(listener))
+            }
+        }
+    }
+
+    /// The bound TCP port; 0 for a unix socket, which has none.
+    pub fn port(&self) -> io::Result<u16> {
+        match self {
+            Listener::Tcp(listener) => Ok(listener.local_addr()?.port()),
+            Listener::Unix(..) => Ok(0),
+        }
+    }
+}
+
+/// Bind a unix domain socket at `path`. A path that already exists is
+/// either a live listener (refuse: never steal it) or a stale file left
+/// behind by a crashed process (unlink and reclaim). A connect probe tells
+/// them apart: a successful connect means someone is accepting right now.
+pub fn bind_unix(path: &Path) -> io::Result<UnixListener> {
+    match std::os::unix::net::UnixStream::connect(path) {
+        Ok(_) => return Err(io::Error::new(io::ErrorKind::AddrInUse, "socket is in use")),
+        Err(e) if e.kind() == io::ErrorKind::ConnectionRefused => {
+            match std::fs::remove_file(path) {
+                Ok(()) => {}
+                Err(e) if e.kind() == io::ErrorKind::NotFound => {}
+                Err(e) => return Err(e),
+            }
+        }
+        Err(e) if e.kind() == io::ErrorKind::NotFound => {}
+        Err(e) => return Err(e),
+    }
+    let listener = UnixListener::bind(path)?;
+    listener.set_nonblocking(true)?;
+    Ok(listener)
+}
+
+/// Remove a socket file at shutdown; one that is already gone is fine.
+pub fn cleanup_unix(path: &Path) {
+    let _ = std::fs::remove_file(path);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{bind_unix, unix_path, Listener};
+    use std::path::PathBuf;
+
+    /// A socket path unique to this process and test. macOS caps sun_path
+    /// at 104 bytes, so the name stays short.
+    fn socket_path(name: &str) -> PathBuf {
+        let path = std::env::temp_dir().join(format!("kino-{}-{name}.sock", std::process::id()));
+        let _ = std::fs::remove_file(&path);
+        path
+    }
+
+    #[test]
+    fn unix_path_recognises_only_the_unix_scheme() {
+        assert_eq!(unix_path("unix:///run/kino.sock").unwrap().to_str(), Some("/run/kino.sock"));
+        assert!(unix_path("127.0.0.1").is_none());
+        assert!(unix_path("unix.example.com").is_none());
+    }
+
+    #[test]
+    fn binds_a_unix_socket_and_reports_no_port() {
+        let path = socket_path("bind");
+        let listener = Listener::bind(&format!("unix://{}", path.display()), 9292).unwrap();
+        assert!(matches!(listener, Listener::Unix(..)));
+        assert_eq!(listener.port().unwrap(), 0);
+        assert!(std::fs::metadata(&path).is_ok());
+        drop(listener);
+        let _ = std::fs::remove_file(&path);
+    }
+
+    #[test]
+    fn reclaims_a_stale_socket_file() {
+        let path = socket_path("stale");
+        // Dropping a listener closes the socket but leaves its file behind,
+        // exactly what a crashed process leaves.
+        drop(bind_unix(&path).unwrap());
+        assert!(std::fs::metadata(&path).is_ok());
+        let reclaimed = bind_unix(&path).unwrap();
+        drop(reclaimed);
+        let _ = std::fs::remove_file(&path);
+    }
+
+    #[test]
+    fn refuses_a_socket_someone_is_listening_on() {
+        let path = socket_path("live");
+        let live = bind_unix(&path).unwrap();
+        let err = bind_unix(&path).unwrap_err();
+        assert_eq!(err.kind(), std::io::ErrorKind::AddrInUse);
+        assert!(err.to_string().contains("in use"));
+        drop(live);
+        let _ = std::fs::remove_file(&path);
+    }
+
+    #[test]
+    fn binds_tcp_on_an_ephemeral_port() {
+        let listener = Listener::bind("127.0.0.1", 0).unwrap();
+        assert!(matches!(listener, Listener::Tcp(_)));
+        assert_ne!(listener.port().unwrap(), 0);
+    }
+}

data/ext/kino/src/log.rs

@@ -0,0 +1,144 @@
+//! 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

@@ -119,9 +119,13 @@ fn admit(
     slot.served.fetch_add(1, 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

@@ -69,6 +69,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.
@@ -301,6 +303,7 @@ pub fn test_server(lanes: bool, queue_depth: usize) -> Arc<ServerInner> {
         quarantine_replacements: AtomicU64::new(0),
         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),

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,
     })
 }