kino 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 129f2e9c0c20ba89c1f2f1e854d32f2b746858546b0c6fdb1a88a3fcb14e05cf
-  data.tar.gz: 66b465f2e5989e621487752d0b4dac48a9da0857b5290effaac9af803bd315e2
+  metadata.gz: 96ea3372ae6524dd1243f75354485613d0e49c38005f870bc83c57a46034e579
+  data.tar.gz: c71ac26d45838d6d5ad573e929ad72612f970799a50686b55324304e65a8daae
 SHA512:
-  metadata.gz: ac6656c0cd168c5c43dd5d1585b639b93f2489b5e017cbdd297c383c19d083c391cd7ac60034dbcd825bc525b42d7a966f884aa9d03eb0185e7bf8b5539a7781
-  data.tar.gz: 4392ca122bb8d865eec08393a6f339343bb2f5fac209b82e845ec6319d04f71a7a309a70d5d6518a70d70fc701c50dbd482646250b4d46f3e0d313e497bf4e3d
+  metadata.gz: 5f918bd194f00189487a4229f9cffd6005a4b60c6357b21acb6d06e496b9d27ba4487002f8a7fea28f8e2f21324353d3e2fc175e9fcf04906b581d4f2c5309f9
+  data.tar.gz: 30b42185d524fc97c4f16f13e27573215ff25d5af6f91881ae91a3c8450945c3d380130aec7acf897d19e2707df5a387f62cdcca9513aa34a148960dff5f420b

data/CHANGELOG.md

@@ -1,3 +1,48 @@
+## [0.4.0] - 2026-08-22
+
+- Rack handler: `rails server -u kino` and `rackup -s kino` boot Kino
+  through `Rackup::Handler::Kino`, reading the same config file as the
+  `kino` CLI with the host's flags on top; `rackup -s kino --help` lists
+  the `-O` options (Workers, Threads, Mode, Config).
+- The config file is also looked up at `config/kino.rb` (the Rails
+  layout) when there is no `kino.rb`, by the CLI and the handler alike.
+- `Kino::Server#run` serves an already built server the way
+  `Kino::Server.run` does (banner, signal traps, block until shutdown),
+  and syncs stdout there so the banner is never held back by block
+  buffering under a pipe, whichever entry point booted the server.
+- `workers` now defaults to `Kino.available_parallelism`, the CPUs the
+  process may actually use: the affinity mask and, in a container, the
+  cgroup CPU quota (a pod limited to 2 CPUs on a 64-core node gets 2
+  workers, not 64). `Etc.nprocessors` only ever saw the mask.
+- `bind "unix:///path/to.sock"` listens on a unix domain socket, the
+  usual shape behind nginx: a stale socket file is reclaimed, a live one
+  is refused, and the file is removed on shutdown. `port` is unused on
+  it and TLS is rejected (terminate TLS at the proxy). Requests arriving
+  over the socket report `REMOTE_ADDR` 127.0.0.1.
+- `Kino::Server#url`, `#control_url`, and `#unix?` report where a started
+  server and its control plane listen.
+- The access log is two records per request: an arrival line queued
+  before the app runs (a hang shows as an arrow with no answer) and a
+  status-tinted completion line with a timing breakdown of `ruby`,
+  `kino`, and `wait`, the `ruby` part carrying the GC pause and objects
+  allocated where one request at a time can own the VM's counters
+  (`:threaded`, or `:ractor` with `workers 1`). Local timestamps with
+  their UTC offset; a blank line between requests. The former one-line
+  format is gone.
+- A failed request is reported as `500 GET /path · Class: message (site)`
+  followed by its backtrace relative to the working directory, the app's
+  own frames first, the rest folded into `… N more`.
+- Every line Kino logs about itself (draining, a crash and its respawn,
+  hook failures, quarantine, the USR1 stats line, `rack.errors`) reads
+  `kino[<pid>] <source>: message`, the source naming the worker that
+  spoke (`worker-3`, `worker-3/thread-2`) or `main`; worker ractors and
+  threads now carry those names. The label is dim, yellow, or red by
+  level on color terminals. `Kino::Log.info`, `.warn`, and `.error` are
+  public, for hooks.
+- The startup banner lists the Ruby build with its JIT and parser flags,
+  the environment, the topology, the pid, and the control-plane address
+  when one is bound.
+
 ## [0.3.0] - 2026-08-13
 
 - Queue-time histogram: `/metrics` exposes `kino_request_queue_seconds`, a

data/Cargo.lock

@@ -42,7 +42,7 @@ version = "0.72.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "993776b509cfb49c750f11b8f07a46fa23e0a1386ffc01fb1e7d343efc387895"
 dependencies = [
- "bitflags",
+ "bitflags 2.13.1",
  "cexpr",
  "clang-sys",
  "itertools",
@@ -54,6 +54,12 @@ dependencies = [
  "syn 2.0.119",
 ]
 
+[[package]]
+name = "bitflags"
+version = "1.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
+
 [[package]]
 name = "bitflags"
 version = "2.13.1"
@@ -108,6 +114,37 @@ dependencies = [
  "libloading",
 ]
 
+[[package]]
+name = "defmt"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e2953bfe4f93bbd20cc71198842756f77d161884c99ebbabc41d80231ded88d1"
+dependencies = [
+ "bitflags 1.3.2",
+ "defmt-macros",
+]
+
+[[package]]
+name = "defmt-macros"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bad9c72e7ca2137e0dc3813245a0d282fd6daad32fd800af018306a9169b5fe8"
+dependencies = [
+ "defmt-parser",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "defmt-parser"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "10d60334b3b2e7c9d91ef8150abfb6fa4c1c39ebbcf4a81c2e346aad939fee3e"
+dependencies = [
+ "thiserror",
+]
+
 [[package]]
 name = "either"
 version = "1.17.0"
@@ -321,6 +358,43 @@ version = "1.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 
+[[package]]
+name = "jiff"
+version = "0.2.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "668b7183bd07af9a4885f5c35b0cc5c83c4607a913c16b7e17291832910d2dcc"
+dependencies = [
+ "defmt",
+ "jiff-core",
+ "jiff-static",
+ "log",
+ "portable-atomic",
+ "portable-atomic-util",
+ "serde_core",
+ "windows-link",
+]
+
+[[package]]
+name = "jiff-core"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7feca88439efe53da3754500c1851dedf3cb36c524dd5cf8225cc0794de95d09"
+dependencies = [
+ "defmt",
+]
+
+[[package]]
+name = "jiff-static"
+version = "0.2.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3a69dcb3a21cfb32ce1cd056169337ca284af0766dd766e7878819b251a49204"
+dependencies = [
+ "jiff-core",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
 [[package]]
 name = "js-sys"
 version = "0.3.104"
@@ -333,16 +407,16 @@ dependencies = [
 
 [[package]]
 name = "kino"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "ahash",
  "bytes",
  "flume",
  "http",
  "http-body-util",
- "httpdate",
  "hyper",
  "hyper-util",
+ "jiff",
  "lru",
  "magnus",
  "mimalloc",
@@ -510,6 +584,21 @@ version = "0.2.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
 
+[[package]]
+name = "portable-atomic"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
+
+[[package]]
+name = "portable-atomic-util"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a106d1259c23fac8e543272398ae0e3c0b8d33c88ed73d0cc71b0f1d902618"
+dependencies = [
+ "portable-atomic",
+]
+
 [[package]]
 name = "proc-macro2"
 version = "1.0.107"
@@ -576,7 +665,7 @@ version = "0.5.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
 dependencies = [
- "bitflags",
+ "bitflags 2.13.1",
 ]
 
 [[package]]
@@ -690,6 +779,26 @@ version = "0.3.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1bc711410fbe7399f390ca1c3b60ad0f53f80e95c5eb935e52268a0e2cd49acc"
 
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
 [[package]]
 name = "shell-words"
 version = "1.1.1"
@@ -761,6 +870,26 @@ dependencies = [
  "unicode-ident",
 ]
 
+[[package]]
+name = "thiserror"
+version = "2.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec86235f5fcc2a73650310756d2ac5b138a5780bbbdfae3eeccec992c435ba4f"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bc04cd3e1236dd4a98afca4569f2deb3f120e5422a4023be2cb683f8486292af"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
 [[package]]
 name = "tokio"
 version = "1.53.1"

data/README.md

@@ -196,6 +196,12 @@ bundle exec kino           # picks up config.ru + kino.rb, serves on :9292
 (After a standalone `gem install`, the `kino` command works without
 `bundle exec`.)
 
+Prefer your framework's own command? Kino ships a Rack handler, so
+`rails server -u kino` and `rackup -s kino` boot it too. They read the
+same `kino.rb` (or `config/kino.rb`), the host's `-p`/`-b` flags win over
+the file, and `rackup -s kino -O Workers=4 -O Mode=threaded` reaches the
+rest (`rackup -s kino --help` lists them).
+
 No Rust compiler needed: released versions ship precompiled native gems
 for Linux (x86_64/aarch64, glibc and musl) and macOS (arm64). On other
 platforms the gem compiles at install time; that needs a Rust toolchain,
@@ -218,9 +224,9 @@ Or embedded, with everything spelled out:
 
 ```ruby
 server = Kino::Server.new(app,
-  bind: "127.0.0.1",
+  bind: "127.0.0.1",          # or "unix:///run/kino.sock" behind a proxy
   port: 9292,                 # 0 = ephemeral; read back via server.port
-  workers: Etc.nprocessors,   # ractors (parallelism)
+  workers: Kino.available_parallelism, # ractors (parallelism); the default
   threads: 1,                 # per worker; ractor default 1, threaded default 3
   mode: :auto,                # :auto | :ractor | :threaded
   queue_depth: 1024,          # bounded queue; overflow → 503
@@ -255,8 +261,10 @@ server.shutdown               # graceful: drain → deadline → abort straggler
 
 ## Config file and CLI
 
-Settings can live in a Puma-style Ruby DSL file. Precedence: explicit
-kwargs and CLI flags > config file > defaults.
+Settings can live in a Puma-style Ruby DSL file: `kino.rb` in the
+working directory, or `config/kino.rb` (the Rails layout), is picked up
+automatically; `-C PATH` names any other. Precedence: explicit kwargs
+and CLI flags > config file > defaults.
 
 ```ruby
 # kino.rb
@@ -374,11 +382,11 @@ server.stats
 # plus lane_depths: [...] when lane dispatch is on
 ```
 
-From the outside, `kill -USR1 <pid>` prints the same snapshot as one line
+From the outside, `kill -USR1 <pid>` logs the same snapshot as one line
 (pair it with `pidfile` to find the pid):
 
 ```
-Kino stats: mode=:ractor lanes=false workers=8 threads=1 batch=1 respawns=0 queued=0 in_flight=2 served=1041 rejected=0 timeouts=0
+kino[4213] main: stats mode=:ractor lanes=false workers=8 threads=1 batch=1 respawns=0 queued=0 in_flight=2 served=1041 rejected=0 timeouts=0
 ```
 
 For pull-based monitoring, `control_bind "127.0.0.1:9293"` (or a
@@ -422,16 +430,28 @@ box). There are two native pieces. Both write through a lock-free
 channel to a Rust flusher thread, so request threads never take a log
 mutex and never make a write syscall:
 
-- **Access log** (`log_requests true`): one line per request to stdout,
-  including the 503s that never reach your app. Recommended in
-  development; cheap enough for production. On color terminals the
-  lines are tinted by status class: 2xx green, 3xx yellow, 4xx maroon,
-  5xx bright red:
+- **Access log** (`log_requests true`): two records per request to
+  stdout, including the 503s that never reach your app. The arrival line
+  is queued before the app runs, so a request that hangs shows as an
+  arrow with no answer; the completion line carries the status, the
+  total, and a timing breakdown: `ruby` is the time the request spent in
+  Ruby (with the GC pause and the objects allocated during it), `kino`
+  the server's own overhead, `wait` the queue time before a worker took
+  it. Recommended in development; cheap enough for production. On color
+  terminals the completion line is tinted by status class: 2xx green,
+  3xx yellow, 4xx maroon, 5xx bright red:
 
   ```
-  127.0.0.1 [Tue, 10 Jun 2026 13:39:56 GMT] "GET / HTTP/1.1" 200 0.1ms
+  2026-08-22 14:03:11 +0300 → GET /users?q=1  from 127.0.0.1
+  2026-08-22 14:03:11 +0300 ← 200 GET /users?q=1  12.4ms (ruby 9.1ms [gc 0.8ms; 1.5k obj]; kino 3.2ms; wait 0.1ms)
   ```
 
+  The GC and allocation figures come from the VM's process-wide
+  counters, so they appear only where one request at a time can own
+  them: in `:threaded` mode, or in `:ractor` mode with `workers 1`.
+  Parallel ractors would bill each other's work, so there the breakdown
+  is `(ruby; kino; wait)` alone.
+
 - **`Kino::Logger`**: a `::Logger` over the same async sink, for your
   app's own logging (`Kino::Logger.new("log/production.log")`, or no
   argument for stdout). The raw IO-like device is `Kino::Logger::Device`,
@@ -473,6 +493,27 @@ lines/s), the sink drops lines instead of blocking request threads.
 These trade-offs are measured in
 [doc/benchmarks.md](doc/benchmarks.md#logging-costs).
 
+**Server lines.** Everything Kino says about itself (draining, a crash
+and its respawn, a hook that raised, quarantine, the stats line,
+`rack.errors`) reads `kino[<pid>] <source>: message`, the source being
+the worker that spoke, `worker-3` (or `worker-3/thread-2` in a
+multi-threaded ractor), or `main`. On color terminals the label is dim
+for notes, yellow for warnings, red for errors; the message stays plain.
+A failed request gets a report instead of a bare backtrace: the request
+line, the error, and where it raised in your code, then the trace with
+your frames first, relative to the working directory, and the rest
+folded:
+
+```
+kino[4213] worker-2: 500 GET /boom · RuntimeError: kaboom (app.rb:12:in 'explode')
+    app.rb:12:in 'explode'
+    /usr/lib/ruby/gems/4.0.0/gems/rack-3.2.7/lib/rack/builder.rb:...
+    … 38 more
+```
+
+Hooks can log through the same channel with `Kino::Log.info`, `.warn`,
+and `.error`; it is safe inside worker ractors.
+
 ## Timer waits
 
 `Kino.sleep(seconds)` is a high-resolution sleep on the OS clock with
@@ -491,8 +532,9 @@ optional in Rack 3.
 
 ## Rails
 
-Rails (edge) runs on Kino today in `:threaded` mode; see
-`examples/rails-hello`. Ractor-mode Rails is blocked upstream. The exact
+Rails (edge) runs on Kino today in `:threaded` mode (`rails server -u
+kino`, or the `kino` CLI); see `examples/rails-hello`. Ractor-mode Rails
+is blocked upstream. The exact
 blockers, the `Ruby::Box` findings, and what would unlock it are written
 up in [doc/rails-on-ractors.md](doc/rails-on-ractors.md). The example
 ships a probe script that re-tests against whatever Rails you bundle.

data/exe/kino

@@ -9,10 +9,6 @@
 # process-global bits an executable owns.
 
 Warning[:experimental] = false
-# Startup output must land immediately even when stdout is a pipe or file
-# (process supervisors, `kino > server.log`); block buffering would hold
-# the banner back until exit.
-$stdout.sync = true
 
 # Running from a git checkout (no installed gem, no bundler context):
 # prefer the checkout's own lib so `require "kino"` resolves.

data/ext/kino/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kino"
-version = "0.3.0"
+version = "0.4.0"
 edition = "2021"
 authors = ["Yaroslav Markin <yaroslav@markin.net>"]
 license = "MIT"
@@ -26,7 +26,9 @@ hyper-util = { version = "0.1", features = ["server", "tokio", "http1"] }
 http = "1"
 http-body-util = "0.1"
 bytes = "1"
-httpdate = "1"
+# Local-time stamps for the access log: the system zone only (no bundled
+# tzdb, no serde), which keeps the dependency tree to jiff itself.
+jiff = { version = "0.2", default-features = false, features = ["std", "tz-system", "tzdb-zoneinfo"] }
 # ring (not the default aws-lc-rs) as the rustls crypto provider: it
 # cross-compiles cleanly in rb-sys-dock containers, while aws-lc-sys wants
 # cmake and a per-target C toolchain.

data/ext/kino/src/access_log.rs

@@ -0,0 +1,245 @@
+//! The access log: two records per request on the async sink, so neither
+//! costs the request path a write syscall. An arrival line is queued as
+//! soon as the request head is parsed, before the app sees it, so a hang
+//! shows as an arrow with no answer; a status-tinted completion line
+//! follows the response head with the total and a timing breakdown:
+//!
+//! ```text
+//! 2026-08-22 14:03:11 +0300 → GET /users?q=1  from 127.0.0.1
+//! 2026-08-22 14:03:11 +0300 ← 200 GET /users?q=1  12.4ms (ruby 9.1ms [gc 0.8ms; 1.5k obj]; kino 3.2ms; wait 0.1ms)
+//! ```
+//!
+//! `ruby` is the time the request spent in a Ruby worker (admit to
+//! response head), with the GC pause and objects allocated during the app
+//! call when the worker measured them; `kino` is the server's own
+//! overhead (total minus ruby minus wait); `wait` is the queue time before
+//! a worker took the request. A blank line sets one request apart from
+//! the next.
+
+use std::fmt::Write as _;
+use std::net::IpAddr;
+use std::time::Duration;
+
+use crate::style::{self, Stream};
+
+/// Per-request timing, measured on the way through and riding the
+/// response as an extension so the intake side can log it.
+#[derive(Clone, Copy, Debug)]
+pub struct Timing {
+    /// Queue wait before a worker took the request.
+    pub wait: Duration,
+    /// Admit to response head: the request's time in Ruby.
+    pub ruby: Duration,
+    /// GC pause and objects allocated during the app call, when measured.
+    /// Left out where the VM's process-wide counters cannot be attributed
+    /// to one request (parallel ractors).
+    pub gc: Option<(Duration, u64)>,
+}
+
+/// The arrival record, stamped and styled for stdout.
+pub fn arrival(method: &str, target: &str, ip: IpAddr) -> String {
+    let color = style::enabled(Stream::Stdout);
+    let record = style::sgr(style::BOLD_WHITE, &arrival_line(method, target, ip), color);
+    stamped(&record, color)
+}
+
+/// The completion record, stamped, tinted by status class, followed by the
+/// dimmed breakdown when timing was measured (a 503 or 504 never reached a
+/// worker, so it has none). Ends with an extra newline: with the sink's
+/// own, that leaves the blank line after the record.
+pub fn completion(
+    status: u16,
+    method: &str,
+    target: &str,
+    total: Duration,
+    timing: Option<Timing>,
+) -> String {
+    let color = style::enabled(Stream::Stdout);
+    let record = completion_line(status, method, target, total);
+    let record = match style::status_sgr(status) {
+        Some(code) => style::sgr(code, &record, color),
+        None => record,
+    };
+    let mut line = stamped(&record, color);
+    if let Some(timing) = timing {
+        line.push(' ');
+        if color {
+            let _ = write!(line, "\x1b[{}m", style::DIM);
+        }
+        write_breakdown(&mut line, total, &timing);
+        if color {
+            line.push_str("\x1b[0m");
+        }
+    }
+    line.push('\n');
+    line
+}
+
+/// Prefix a record with the local timestamp, dimmed when coloring so it
+/// recedes behind the arrow and status.
+fn stamped(record: &str, color: bool) -> String {
+    format!("{} {record}", style::sgr(style::DIM, &now_stamp(), color))
+}
+
+/// The local wall clock as `2026-08-22 14:03:11 +0300`: date, time, and
+/// the numeric UTC offset, so a log file is unambiguous across machines.
+fn now_stamp() -> String {
+    jiff::Zoned::now()
+        .strftime("%Y-%m-%d %H:%M:%S %z")
+        .to_string()
+}
+
+/// `→ METHOD target  from IP`.
+fn arrival_line(method: &str, target: &str, ip: IpAddr) -> String {
+    format!("\u{2192} {method} {target}  from {ip}")
+}
+
+/// `← STATUS METHOD target  N.Nms`.
+fn completion_line(status: u16, method: &str, target: &str, total: Duration) -> String {
+    format!(
+        "\u{2190} {status} {method} {target}  {:.1}ms",
+        millis(total)
+    )
+}
+
+/// Append the breakdown straight into the line buffer (no string of its
+/// own): `(ruby N.Nms [gc N.Nms; N obj]; kino N.Nms; wait N.Nms)`, the gc
+/// bracket only when measured. `kino` floors at zero: at sub-millisecond
+/// totals clock granularity can make the parts exceed the whole.
+fn write_breakdown(out: &mut String, total: Duration, timing: &Timing) {
+    let kino = total
+        .saturating_sub(timing.ruby)
+        .saturating_sub(timing.wait);
+    let _ = write!(out, "(ruby {:.1}ms", millis(timing.ruby));
+    if let Some((gc, allocs)) = timing.gc {
+        let _ = write!(out, " [gc {:.1}ms; ", millis(gc));
+        write_count(out, allocs);
+        out.push_str(" obj]");
+    }
+    let _ = write!(
+        out,
+        "; kino {:.1}ms; wait {:.1}ms)",
+        millis(kino),
+        millis(timing.wait)
+    );
+}
+
+fn millis(d: Duration) -> f64 {
+    d.as_secs_f64() * 1000.0
+}
+
+/// A humanized count: `523`, `1.5k`, `52k`.
+fn write_count(out: &mut String, n: u64) {
+    if n < 1000 {
+        let _ = write!(out, "{n}");
+    } else if n < 10_000 {
+        let _ = write!(out, "{:.1}k", n as f64 / 1000.0);
+    } else {
+        let _ = write!(out, "{}k", n / 1000);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{arrival_line, completion_line, now_stamp, write_breakdown, write_count, Timing};
+    use std::net::{IpAddr, Ipv4Addr};
+    use std::time::Duration;
+
+    fn breakdown(total: Duration, timing: &Timing) -> String {
+        let mut out = String::new();
+        write_breakdown(&mut out, total, timing);
+        out
+    }
+
+    fn count(n: u64) -> String {
+        let mut out = String::new();
+        write_count(&mut out, n);
+        out
+    }
+
+    #[test]
+    fn arrival_line_carries_method_target_and_ip() {
+        let ip = IpAddr::V4(Ipv4Addr::new(203, 0, 113, 5));
+        assert_eq!(
+            arrival_line("GET", "/users?q=1", ip),
+            "\u{2192} GET /users?q=1  from 203.0.113.5"
+        );
+    }
+
+    #[test]
+    fn completion_line_carries_status_target_and_total() {
+        assert_eq!(
+            completion_line(200, "GET", "/users", Duration::from_millis(12)),
+            "\u{2190} 200 GET /users  12.0ms"
+        );
+    }
+
+    #[test]
+    fn breakdown_splits_the_total_into_ruby_kino_and_wait() {
+        let timing = Timing {
+            wait: Duration::from_micros(100),
+            ruby: Duration::from_millis(41),
+            gc: Some((Duration::from_micros(9_700), 52_000)),
+        };
+        // kino = total - ruby - wait = 45.2 - 41.0 - 0.1 = 4.1ms.
+        assert_eq!(
+            breakdown(Duration::from_micros(45_200), &timing),
+            "(ruby 41.0ms [gc 9.7ms; 52k obj]; kino 4.1ms; wait 0.1ms)"
+        );
+    }
+
+    #[test]
+    fn breakdown_leaves_out_the_gc_bracket_when_not_measured() {
+        let timing = Timing {
+            wait: Duration::from_millis(1),
+            ruby: Duration::from_millis(2),
+            gc: None,
+        };
+        assert_eq!(
+            breakdown(Duration::from_millis(4), &timing),
+            "(ruby 2.0ms; kino 1.0ms; wait 1.0ms)"
+        );
+    }
+
+    #[test]
+    fn breakdown_floors_kino_at_zero() {
+        let timing = Timing {
+            wait: Duration::from_millis(1),
+            ruby: Duration::from_millis(40),
+            gc: Some((Duration::ZERO, 10)),
+        };
+        assert_eq!(
+            breakdown(Duration::from_millis(40), &timing),
+            "(ruby 40.0ms [gc 0.0ms; 10 obj]; kino 0.0ms; wait 1.0ms)"
+        );
+    }
+
+    #[test]
+    fn count_humanizes_allocation_counts() {
+        assert_eq!(count(0), "0");
+        assert_eq!(count(523), "523");
+        assert_eq!(count(1500), "1.5k");
+        assert_eq!(count(52_000), "52k");
+    }
+
+    #[test]
+    fn timestamp_is_date_time_and_numeric_offset() {
+        // `YYYY-MM-DD HH:MM:SS +HHMM`, e.g. `2026-08-22 14:03:11 +0300`.
+        let ts = now_stamp();
+        let (datetime, offset) = ts.rsplit_once(' ').expect("offset field");
+        let (date, time) = datetime.split_once(' ').expect("date and time");
+        assert_eq!(date.len(), 10, "date {date}");
+        assert_eq!(&date[4..5], "-");
+        assert_eq!(time.len(), 8, "time {time}");
+        assert_eq!(&time[2..3], ":");
+        assert_eq!(offset.len(), 5, "offset {offset}");
+        assert!(matches!(&offset[0..1], "+" | "-"));
+        assert!(offset[1..].bytes().all(|b| b.is_ascii_digit()));
+    }
+
+    #[test]
+    fn completion_ends_with_the_blank_line_newline() {
+        let line = super::completion(200, "GET", "/", Duration::from_millis(1), None);
+        assert!(line.ends_with("\u{2190} 200 GET /  1.0ms\n") || line.ends_with("1.0ms\x1b[0m\n"));
+    }
+}