kino 0.3.0 → 0.4.0

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};
@@ -78,15 +79,23 @@ pub fn server_start(ruby: &Ruby, config: magnus::RHash) -> Result<(u64, u16, Opt
         }
     };
 
-    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")?;
@@ -128,6 +137,7 @@ pub fn server_start(ruby: &Ruby, config: magnus::RHash) -> Result<(u64, u16, Opt
         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),
@@ -137,8 +147,7 @@ pub fn server_start(ruby: &Ruby, config: magnus::RHash) -> Result<(u64, u16, Opt
 
     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,
@@ -182,8 +191,59 @@ pub fn server_start(ruby: &Ruby, config: magnus::RHash) -> Result<(u64, u16, Opt
 /// 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,
@@ -202,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.
@@ -228,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
+                }
             }
         });
     }
@@ -310,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
@@ -378,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,
@@ -393,7 +454,11 @@ async fn handle_request(
         slot: None,
         pin_slab: server.pin_slab.clone(),
         responder,
-        enqueued_at: std::time::Instant::now(),
+        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,
@@ -472,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))
@@ -651,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(())
 }
@@ -665,12 +737,6 @@ 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,
 /// respawns, lane_depths]. lane_depths is nil unless lane dispatch is on.
 #[allow(clippy::type_complexity)]

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");
+    }
 }

data/lib/kino/cli.rb

@@ -100,14 +100,14 @@ module Kino
       end.join
     end
 
-    # One-line stats dump (the SIGUSR1 handler's output). Excludes
+    # One-line stats dump (what the SIGUSR1 handler logs). Excludes
     # worker_status: it's an array with one entry per execution slot, and
     # printing it inline would break the one-line contract (see /stats for
     # per-worker detail).
     # @param stats [Hash{Symbol => Object}] see {Kino::Server#stats}
     # @return [String]
     def stats_line(stats)
-      dim("Kino stats: #{stats.except(:worker_status).map { |k, v| "#{k}=#{v.inspect}" }.join(" ")}")
+      "stats #{stats.except(:worker_status).map { |k, v| "#{k}=#{v.inspect}" }.join(" ")}"
     end
 
     # The two banner halves around Server#start: credits before, the ready
@@ -119,15 +119,27 @@ module Kino
       puts dim("\nKino #{VERSION} presents:")
     end
 
+    # The ready block: what this process is (Ruby build with its JIT and
+    # parser flags, environment, topology, pid) and where it listens.
     # @param server [Kino::Server] a started server
     # @return [void]
     def action!(server)
-      puts dim("- mode:      #{server.mode}")
-      puts dim("- listening: http#{"s" if server.tls?}://#{server.bind}:#{server.port}")
+      stats = server.stats
+      puts dim("- ruby:      #{RUBY_DESCRIPTION}")
+      puts dim("- env:       #{ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"}")
+      puts dim("- mode:      #{server.mode}, #{count(stats[:workers], "worker")} × #{count(stats[:threads], "thread")}")
+      puts dim("- pid:       #{Process.pid}")
+      puts dim("- listening: #{server.url}")
+      puts dim("- control:   #{server.control_url}") if server.control_url
       puts dim("- Ctrl-C to drain and stop")
       puts "\n#{bold("Action!")}\n\n"
     end
 
+    # "1 worker", "8 workers".
+    def count(number, noun)
+      "#{number} #{noun}#{"s" unless number == 1}"
+    end
+
     # Roll credits when the process ends: normal exit or crash (at_exit
     # also runs after an uncaught exception; only a force-exit skips it).
     # @return [void]
@@ -200,7 +212,7 @@ module Kino
     def option_parser(options)
       OptionParser.new do |opts|
         opts.banner = "Usage: kino [options] [rackup file (default: config.ru)]"
-        opts.on("-C", "--config FILE", "Config file (default: kino.rb if present)") { |v| options[:config_file] = v }
+        opts.on("-C", "--config FILE", "Config file (default: kino.rb, then config/kino.rb)") { |v| options[:config_file] = v }
         opts.on("--init [PATH]", "Write a commented sample config (default: kino.rb) and exit") do |v|
           options[:init_path] = v || "kino.rb"
         end
@@ -236,14 +248,13 @@ module Kino
       require "kino"
       require "rack"
 
-      config_file = options[:config_file]
-      config_file ||= ("kino.rb" if File.exist?("kino.rb"))
+      config_file = options[:config_file] || Configuration.default_path
 
       config = Configuration.new
       config.load_file(config_file) if config_file
       config.merge!(options[:overrides])
       # Default port 9292 when neither the file nor a flag chose one.
-      config.set(:port, 9292) unless config.set?(:port)
+      config.set(:port, Configuration::DEFAULT_SERVING_PORT) unless config.set?(:port)
       config
     end
 
@@ -252,6 +263,6 @@ module Kino
     end
 
     private_class_method :print_help, :option_parser, :write_sample,
-      :resolve_config, :serve
+      :resolve_config, :serve, :count
   end
 end

data/lib/kino/configuration.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "etc"
-
 module Kino
   # Server settings with Puma-style precedence:
   #   explicit Server.new kwargs > config file DSL > defaults.
@@ -11,7 +9,7 @@ module Kino
     DEFAULTS = {
       bind: "127.0.0.1",
       port: 0,
-      workers: nil, # resolved to Etc.nprocessors in #to_h
+      workers: nil, # resolved to Kino.available_parallelism in #to_h
       threads: nil, # resolved per mode in Server: 1 in :ractor, 3 in :threaded
       mode: :auto,
       queue_depth: 1024,
@@ -45,6 +43,21 @@ module Kino
     # Source template for {.sample}.
     SAMPLE_TEMPLATE = File.expand_path("templates/kino.rb.tt", __dir__)
 
+    # Where the `kino` CLI and the Rack handler look for a config file when
+    # none is named: the project root first, then the Rails-style config/.
+    DEFAULT_PATHS = %w[kino.rb config/kino.rb].freeze
+
+    # The port the CLI and the Rack handler serve on when neither a flag
+    # nor the file chose one (Server.new itself defaults to an ephemeral
+    # port, for embedding).
+    DEFAULT_SERVING_PORT = 9292
+
+    # The first of {DEFAULT_PATHS} that exists in the working directory.
+    # @return [String, nil]
+    def self.default_path
+      DEFAULT_PATHS.find { |path| File.exist?(path) }
+    end
+
     # The fully-commented sample config (see `kino --init`).
     # @return [String]
     def self.sample
@@ -113,7 +126,7 @@ module Kino
     # @return [Hash{Symbol => Object}] every setting, defaults filled in
     def to_h
       SETTINGS.to_h { |key| [key, self[key]] }.tap do |h|
-        h[:workers] ||= Etc.nprocessors
+        h[:workers] ||= Kino.available_parallelism
       end
     end
 
@@ -146,7 +159,9 @@ module Kino
         @config = config
       end
 
-      # Address to listen on ("0.0.0.0" accepts non-local connections).
+      # Address to listen on: a host ("0.0.0.0" accepts non-local
+      # connections), or "unix:///path/to.sock" for a unix domain socket
+      # (then `port` is unused).
       def bind(host) = @config.set(:bind, host)
 
       # Port to listen on; 0 picks an ephemeral port.

data/lib/kino/errors_stream.rb

@@ -2,17 +2,18 @@
 
 module Kino
   # @private
-  # rack.errors: stateless writer into the native logger. Frozen singleton,
+  # rack.errors: stateless writer into the server log (one line per
+  # call, labelled like every other line Kino writes). Frozen singleton,
   # which also makes it Ractor-shareable; one instance serves all workers.
   class ErrorsStream
     def puts(message)
-      Native.log_error(message.to_s)
+      Log.error(message.to_s.chomp)
       nil
     end
 
     def write(message)
       message = message.to_s
-      Native.log_error(message)
+      Log.error(message.chomp)
       message.bytesize
     end
 

data/lib/kino/hook_fire.rb

@@ -4,9 +4,8 @@ module Kino
   # @private
   # Fires a lifecycle hook and turns a raise into a logged line instead of
   # letting it escape. Stateless and touches only its arguments plus
-  # Native.log_error (already called from inside worker ractors today), so
-  # it is safe to call from worker context: no main-ractor state is
-  # captured.
+  # Kino::Log (safe inside worker ractors), so it is safe to call from
+  # worker context: no main-ractor state is captured.
   module HookFire
     module_function
 
@@ -16,7 +15,7 @@ module Kino
       begin
         hook.call(*args)
       rescue => e
-        Native.log_error("#{name} hook raised #{e.class}: #{e.message}")
+        Log.error("#{name} hook raised #{e.class}: #{e.message}")
       end
     end
   end