kino 0.1.0 → 0.1.2

data/doc/benchmarks.md

@@ -27,9 +27,29 @@ the deployment most apps run today.
   plaintext 26-37% lower while leaving Puma's number unchanged.
 - Identical app for every server (`bench/bench_app.rb`), Ractor-shareable
   so Kino's `:ractor` mode can run it unmodified.
-- Topology held equal: Puma 8 forked workers × 3 threads vs Kino
-  8 workers × 3 threads in one process.
-- Follow-up studies (`bench/studies.sh`): CPU recipe, topology sweep,
+- Topology: each server at its shipped defaults—Puma 8 forked workers
+  × 3 threads (24 slots) vs Kino 8 workers in one process (× 1 thread
+  in ractor modes, the default since 0.1.1; × 3 threads in threaded
+  mode). Equal-topology numbers (Kino at 8×3) are in the studies below.
+- The headline tables also carry an io-tuned column (`workers 32,
+  threads 1`)—not a default, labeled as such—because the /io rows are
+  a slot-count story (see below).
+- The dataset spans four identical c7a.2xlarge boxes: the original
+  measurements, a re-measure at the 0.1.1 defaults, the headline sweep,
+  and a final full re-validation (every table re-run from scratch).
+  Equal-config throughput reproduced across boxes within ~1-2%.
+- **Memory is reported as PSS (proportional set size), not RSS.** A Puma
+  cluster forks N workers that share the Ruby VM and gem code
+  copy-on-write; summing each worker's RSS counts those shared pages up
+  to N times and overstates the cluster's real footprint. PSS divides
+  every shared page across the processes mapping it, so it reflects the
+  unique physical memory the cluster occupies—the only fair basis for
+  comparing one process against a fork-per-core cluster. We read it from
+  `/proc/<pid>/smaps_rollup` over the whole process tree, cross-checked
+  against `ps` (RSS) and `smem` (PSS). Kino serves from one process, so
+  its RSS ≈ PSS; the correction only moves Puma. (`bench/studies.sh`
+  reports both columns.)
+- Follow-up studies (`bench/studies.sh`): CPU tuning, topology sweep,
   /io worker scaling, logging costs, and memory—run in the same session
   as the headline tables.
 - The harness waits for the port to be genuinely free between targets.
@@ -45,42 +65,55 @@ the deployment most apps run today.
 
 ## Reading the headline tables
 
+These tables all run the **tiny synthetic Ractor-shareable app**. The real
+Rails app is not Ractor-shareable and runs only in threaded fallback—a
+separate story with separate numbers, in [its own section](#rails).
+
 - **Plaintext/10k**: Kino's tokio front-end clears the fork cluster by
-  1.4-2× (lanes plaintext 241,501 vs Puma 117,838 = 2.05×; the smallest
-  margin is threaded /10k at 1.44×). The cross-ractor handoff shows up
-  as ractor (201k) trailing threaded (218k) on trivial handlers—nothing
-  in them needs parallel Ruby—and lane dispatch reverses that (241k).
-- **CPU (recursive fib)**: ractor mode does **5× its own GVL-bound
-  threaded mode** (66,735 vs 13,298)—that's the entire point of
-  ractors—and beats the fork cluster outright: +15% with stock
-  defaults, +21% with lanes (70,373 vs 58,207).
-- **Memory**: serving the same loaded bench app, Kino held **57 MB
-  (ractor) / 50 MB (threaded)** where the 8-worker cluster held
-  **1,078 MB**—a fork per core pays one full copy of the VM, the app,
-  and its YJIT-compiled code per worker. On the Rails hello-world:
-  Kino 97 MB vs cluster 797 MB.
+  1.5-2.1× (lanes plaintext 250,222 vs Puma 118,176 = 2.12×; the
+  smallest margin is threaded /10k at 1.50×). At the old 3-thread
+  topology the cross-ractor handoff showed up as ractor trailing
+  threaded on trivial handlers; the 1-thread default reverses that
+  (ractor 230k vs threaded 217k) and lanes widen it (250k).
+- **CPU (recursive fib)**: ractor mode does **5.8× its own GVL-bound
+  threaded mode** (77,999 vs 13,429)—that's the entire point of
+  ractors—and beats the fork cluster outright: +34% with stock
+  defaults (+22% with lanes, 70,885 vs 58,006). Even the io-tuned
+  `workers 32` topology stays ahead of the cluster on CPU (66,100).
+- **Memory (PSS)**: after the full endpoint battery, the tiny app costs
+  Kino **148 MB** in ractor mode (107 MB threaded) against the 8-worker
+  cluster's **1,068 MB**—~7-10× lighter, because a trivial app is almost
+  all private per-worker heap that copy-on-write can't share. The real
+  Rails app narrows this to ~4× (its framework *is* shared CoW); both are
+  in [Memory under load](#memory-under-load-and-the-glibc-arena-footgun).
 - **I/O (5 ms wait)**: all dispatch models tie within ~4% at equal slot
-  counts; the lever that matters is slot count, see
-  [below](#why-io-lags-in-ractor-mode-on-linux).
+  counts, so the default columns show the ractor modes behind on /io
+  (8 slots vs the cluster's 24), and the `workers 32` column shows the
+  same engine winning (+25%, +34% via `Kino.sleep`) once it has more
+  slots than the cluster. The lever is slot count, and Kino slots are
+  cheap: see [below](#why-io-lags-in-ractor-mode-on-linux).
 
 ## CPU-bound tuning
 
-On real hardware, Kino's stock defaults already lead the cluster on
-pure CPU—same-session studies run:
+On real hardware, Kino's stock defaults lead the cluster on pure
+CPU—and the old tuning recipe is now obsolete. Same-session studies
+run:
 
 | config | /cpu req/s |
 |---|---:|
-| Puma cluster (reference) | 58,376 |
-| Kino `workers 8, threads 3`, tokio auto (default) | 68,257 |
-| Kino `workers 8, threads 1, tokio_threads 1` (recipe) | 68,629 |
-
-The tuned recipe is a wash (+0.5%)—and it still costs plaintext
-(112,815 vs ~200k) and /io (1,532, 8 slots): on this hardware there is
-no reason to use it. **This is a finding that changed with the
-environment**: in the earlier Docker-on-Mac runs the recipe was worth
-+12%, because tokio threads and wake churn competed for oversubscribed
-virtualized cores. If you deploy into a constrained/virtualized
-environment, the recipe may still pay; measure there.
+| Puma cluster (reference) | 58,189 |
+| Kino `workers 8, threads 3` (the default before 0.1.1) | 67,394 |
+| Kino `workers 8, threads 1, tokio_threads 1` (the old recipe) | 68,600 |
+| Kino `workers 8, threads 1`, tokio auto (**the default**) | **77,999** |
+
+The `threads 1` half of the old recipe became the default; the
+`tokio_threads 1` half now *costs* −12% on /cpu (and still costs
+plaintext: 108,523 vs 230k). Don't pin tokio threads. **The recipe's
+history is an environment story**: in the earlier Docker-on-Mac runs it
+was worth +12%, because tokio threads and wake churn competed for
+oversubscribed virtualized cores; on dedicated cores the same pin
+starves the I/O front-end instead. If you deploy into a
+constrained/virtualized environment, measure there.
 
 Two findings that survived the environment change:
 
@@ -99,8 +132,9 @@ Parallelism for CPU-bound Ruby comes from ractors or forks, nothing else.
 
 ## Why /io lags in ractor mode on Linux
 
-On bare metal the gap is small: ractor /io 4,527 vs threaded 4,715
-(−4%). In Docker it was −18%, and a pure-Ruby probe there measured
+On bare metal the gap is small at equal slot counts: ractor /io 4,530
+vs threaded 4,709 (−4%, both at 8×3). In Docker it was −18%, and a
+pure-Ruby probe there measured
 `sleep(0.005)` waking +2.3-2.8 ms late inside ractors vs +1.8 ms on the
 main ractor—non-main-ractor timer wakeups are coarser in Ruby 4.0, but
 how much that costs depends heavily on the kernel/virtualization stack.
@@ -110,14 +144,19 @@ A follow-up probe showed `IO.select`-style waits are tighter than
 **Mitigation 1—`Kino.sleep`:** releases the GVL and waits on the OS
 clock directly (chunked, so `Thread#kill`/shutdown stay responsive). The
 `/io_native` endpoint (same 5 ms wait via `Kino.sleep` when available)
-erases the remaining ractor gap on this box: 4,714 vs 4,527 plain sleep.
-
-**Mitigation 2—add workers; they're nearly free.** Wait-bound
-throughput is simply `slots ÷ effective wait`, and Kino's slots cost ~a
-thread each, not a forked process: `workers 32, threads 1` measured
-**5,922 /io (+27% over the 24-thread cluster's 4,672) and 6,254
-/io_native (+34%)**, still one small process. A fork cluster buying the
-same 32 slots pays for them in full copies of the app.
+erases the remaining ractor gap on this box: 4,721 vs 4,530 plain sleep.
+
+**Mitigation 2—add workers; they're nearly free.** The headline tables
+show default ractor-mode /io at 1,552: that's 8 slots (the 1-thread
+default) against the cluster's 24, because wait-bound throughput is
+simply `slots ÷ effective wait`. Kino's slots cost ~a thread each, not
+a forked process: the `workers 32, threads 1` column measured **5,888
+/io (+25% over the 24-thread cluster's 4,693) and 6,274 /io_native
+(+34%)**, still one small process, and still +14% ahead of the cluster
+on pure CPU. Its cost is the CPU-light rows (183k plaintext vs 230k at
+8×1: 32 ractors oversubscribe 8 cores). A fork cluster buying the same
+32 slots pays for them in full copies of the app; Kino pays in
+scheduler churn only where the cores are already saturated.
 
 ## The ractor-pool-wrapper comparison
 
@@ -127,11 +166,11 @@ already run. `bench/ractor_wrapper.rb` is that experiment, benchmarked on
 Puma and Falcon—not as a comparison of those servers, but to measure
 what the Rack-level hop itself costs (c7a.2xlarge, same session):
 
-| endpoint   | Kino :ractor | Puma + wrapper | Falcon + wrapper |
-|------------|-------------:|---------------:|-----------------:|
-| /plaintext |      201,472 |         19,425 |          100,624 |
-| /cpu (fib) |       66,735 |         17,106 |           49,083 |
-| /io (5 ms) |        4,527 |          1,447 |            1,549 |
+| endpoint   | Kino :ractor (8×3) | Puma + wrapper | Falcon + wrapper |
+|------------|-------------------:|---------------:|-----------------:|
+| /plaintext |            193,826 |         19,480 |           99,776 |
+| /cpu (fib) |             68,061 |         17,755 |           48,721 |
+| /io (5 ms) |              4,530 |          1,454 |            1,549 |
 
 Inside the Rack contract, the wrapper must reduce the env to a shareable
 subset, copy it to the worker ractor, copy the response back, and hold a
@@ -146,18 +185,26 @@ the Rack contract—which is the experiment this gem exists to run.
 
 ## Rails
 
-The example app (`examples/rails-hello`, edge Rails, production mode,
-8 workers × 5 threads) on the same box:
-
-| | req/s | RSS under load |
-|---|---:|---:|
-| Kino `:threaded` (one process) | 2,298 | **97 MB** |
-| Puma cluster (8 workers) | 11,923 | 797 MB |
-
-This is the honest version of the Rails story: in threaded mode Kino is
-one GVL-bound process, so the fork cluster outruns it ~5× by using all
-8 cores—at 8× the memory. Rails-on-Ractors is interesting precisely
-because it would close that throughput gap at the one-process memory
+Rails is **not Ractor-shareable**, so Kino can only serve it in
+`:threaded` fallback—this whole section is one GVL-bound Kino process,
+never ractor mode. The example app (`examples/rails-hello`, edge Rails,
+production mode, 8 workers × 5 threads) on the same box:
+
+| | req/s | RSS | PSS |
+|---|---:|---:|---:|
+| Kino `:threaded` (one process) |  2,637 |  97 MB | **92 MB** |
+| Puma cluster (8 workers) | 12,138 | 794 MB | **389 MB** |
+
+This is the honest version of the Rails story. In threaded mode Kino is
+one GVL-bound process, so the fork cluster outruns it ~4.6× by using all
+8 cores—at ~4× the memory by PSS. The metric matters here: Puma's RSS
+(794 MB) counts the shared Rails framework once per worker; PSS (389 MB)
+counts it once, and that is the fair figure (the README's headline used
+to read 8× off RSS). Preloading barely moves it—389 MB with
+`preload_app!` vs 400 MB without—because Ruby's GC dirties most heap
+pages, breaking copy-on-write, so even a preloaded cluster keeps a
+private heap per worker. Rails-on-Ractors is interesting precisely
+because it would close the throughput gap at the one-process memory
 cost; the upstream blockers are documented in
 [rails-on-ractors.md](rails-on-ractors.md).
 
@@ -190,6 +237,62 @@ needs its `disable_initial_exec_tls` build flag just to load (dlopen +
 initial-exec TLS = `cannot allocate memory in static TLS block`)—one
 more reason to prefer mimalloc in dlopen'd extensions.
 
+## Memory under load (and the glibc arena footgun)
+
+All figures are **PSS** (see [Methodology](#methodology)) after the full
+endpoint battery (8 s each of /plaintext, /10k, /cpu, /io—a "warmed
+production process", not a fresh boot, which measures ~26 MB for every
+Kino mode). RSS is shown alongside so the copy-on-write correction is
+visible.
+
+### The tiny synthetic app
+
+| config | RSS | PSS |
+|---|---:|---:|
+| Kino :ractor 8×1 (default) | 151 | **148** |
+| Kino lanes 8×1 | 137 | **135** |
+| Kino :ractor 8×3 | 171 | **169** |
+| Kino :threaded 8×3 (`MALLOC_ARENA_MAX=2`) | 109 | **107** |
+| Kino :threaded 8×3 (no arena cap) | 668 | **666**¹ |
+| Puma cluster 8×3 | 1,213 | **1,068** |
+
+The tiny app is ~7× lighter than the cluster in ractor mode, ~10× in
+arena-capped threaded mode. RSS ≈ PSS for every Kino row (one process,
+nothing to share) and within ~12% for Puma here: a trivial app has almost
+no shared state, so Puma's footprint is ~1,051 MB of *private* per-worker
+heap plus only ~18 MB shared (which RSS counts 8×). This is the case where
+copy-on-write does **not** rescue the cluster—there is nothing to
+share—so the RSS and PSS numbers nearly agree. (The old "80 MB / 15×"
+figure was a lighter, plaintext-only load; the honest full-battery ractor
+figure is ~148 MB, i.e. ~7×.)
+
+¹ Not a leak: glibc malloc arena bloat. One 8-second /10k round takes
+threaded mode from ~70 MB to ~670 MB and it never returns—24 threads
+churning 10 KB strings through one process heap is the textbook glibc
+arena-fragmentation case (the reason Rails ops set `MALLOC_ARENA_MAX=2`;
+Heroku ships that default). With the cap the same battery ends at 107 MB
+PSS, throughput unchanged. Ractor mode sidesteps the worst of it without
+any env tweak—objects live in per-ractor heaps.
+
+### Rails (threaded fallback)
+
+Here copy-on-write **does** matter, which is exactly why PSS is mandatory:
+
+| config | RSS | PSS |
+|---|---:|---:|
+| Kino :threaded (one process) |  97 |  **92** |
+| Puma cluster 8×3 (preload) | 794 | **389** |
+
+Puma serves the same Rails framework from 8 forks that share it
+copy-on-write; RSS counts that shared framework once per worker (794 MB),
+PSS counts it once (389 MB). The fair ratio is **~4×**, not the ~8× a
+naive RSS sum reports—this is the correction that prompted the whole
+re-measure. Preload barely helps (389 vs 400 MB without): Ruby's GC
+dirties most heap pages, breaking copy-on-write, so even a preloaded
+cluster keeps a large private heap per worker. That is why "CoW should
+make a fork cluster nearly free" is only half true—it shares the code,
+not the live object heap.
+
 ## Run-to-run variance (a.k.a. "is this a regression?")
 
 Rule of thumb from chasing this twice: never compare numbers from
@@ -197,21 +300,33 @@ different sessions; interleave A/B rounds in one session instead. The
 Docker-on-Mac environment swung ±10% on /cpu between sessions with the
 VM's mood; the dedicated c7a box is far steadier (same-session repeats
 land within ~1-2%), but the discipline stays—every comparative claim in
-these docs comes from same-session pairs.
+these docs comes from same-session pairs. Cross-box repeatability got
+its own test: the dataset was measured across four identical
+c7a.2xlarge boxes, and equal-config throughput numbers matched within
+~1-2% (loaded-memory measurements swing more with heap-growth
+timing—treat them as ballpark). The same discipline caught the recurring
+threaded-plaintext fluke twice: once 28% low on an earlier box, and again
+in the final re-validation (170k, where three interleaved re-runs put it
+back at 217k). Suspect cells get re-measured, not published.
 
 ## Topology notes
 
-Measured on c7a.2xlarge, plaintext, ractor mode, same session: `8×3`
-(workers×threads) = 199,470, `8×1` = **232,469 (+17%)**, `16×1` =
-214,284. Threads inside one ractor share its lock, so every request
-handled by a 3-thread ractor pays a lock handoff that a 1-thread ractor
-doesn't (`perf` in the earlier Docker sessions attributed ~10% of cycles
-to `rb_native_mutex_unlock`/`thread_sched_wakeup_next_thread` at 8×3;
-the +17% reproduces exactly on real hardware). Threads-per-ractor exist
-for handlers that block on I/O; if yours don't, run `threads 1` and let
-workers = cores do the parallelism. (16×1 being worse than 8×1 also says
-the shared MPMC queue is *not* the bottleneck—8 extra parked consumers
-just add scheduler churn.)
+Measured on c7a.2xlarge, plaintext, ractor mode, same session (three
+interleaved rounds, medians): `8×3` (workers×threads) = 198,478, `8×1`
+= **229,966 (+16%)**, `16×1` = 214,391. Threads inside one ractor share
+its lock, so every request handled by a 3-thread ractor pays a lock
+handoff that a 1-thread ractor doesn't (`perf` in the earlier Docker
+sessions attributed ~10% of cycles to
+`rb_native_mutex_unlock`/`thread_sched_wakeup_next_thread` at 8×3; the
+gain reproduced on two separate boxes, +16-17% each). **This is why
+`threads` defaults to 1 in ractor mode since 0.1.1** (/cpu gains +16%
+the same way: 77,999 vs 67,394). The trade-off is /io at low worker
+counts: 1,552 at 8×1 vs 4,530 at 8×3—threads-per-ractor exist for
+handlers that block on I/O. If yours wait a lot, raise `workers`
+instead (32×1 beats even the 24-slot cluster, see above); slots are
+cheap. (16×1 being worse than 8×1 on plaintext also says the shared
+MPMC queue is *not* the bottleneck—8 extra parked consumers just add
+scheduler churn.)
 
 ## What profiling tried and rejected
 
@@ -239,23 +354,27 @@ safeguards: lane depth is capped at 4, and workers steal from siblings
 before parking (plus on every park tick), so a slow request can't strand
 its lane's backlog.
 
-Same-session A/B on c7a.2xlarge (ractor mode):
+Same-session A/B on c7a.2xlarge, ractor mode at the default topology
+(8×1):
 
 | endpoint | shared queue | lanes | delta |
 |----------|-------------:|------:|------:|
-| /plaintext | 201,472 | **241,501** | **+20%** |
-| /10k | 156,635 | 183,564 | +17% |
-| /cpu | 66,735 | 70,373 | +5% |
-| /io | 4,527 | 4,530 | flat |
-
-On this hardware lanes make ractor mode the fastest Kino configuration
-outright—+11% over threaded mode's plaintext, where the shared queue
-trails it. (On loopback-bound macOS, lanes lose a few percent instead;
-see the secondary table below.) It stays opt-in for now because overload
-semantics differ from the shared queue (`queue_depth` doesn't apply;
-capacity is lanes × 4 with brief dispatcher retries up to
-`queue_timeout` before the 503), and crash semantics, stealing fairness,
-and drain behavior have spec coverage but not production mileage.
+| /plaintext | 229,534 | **250,222** | **+9%** |
+| /10k | 178,083 | 189,862 | +7% |
+| /cpu | **77,999** | 70,885 | −9% |
+| /io | 1,552 | 1,551 | flat |
+
+Lanes' margin shrank with the move to 1-thread workers (at the old 8×3
+it was +21% plaintext: 240,193 vs 199,032 in the same session)—most of
+the futex pain lanes were built to avoid came from thread handoffs
+inside each ractor, and the new default removes those for everyone. At
+the default, lanes still post the fastest plaintext/10k of any Kino
+configuration, but plain shared-queue now takes /cpu. It stays opt-in because overload semantics differ from the
+shared queue (`queue_depth` doesn't apply; capacity is lanes × 4 with
+brief dispatcher retries up to `queue_timeout` before the 503), and
+crash semantics, stealing fairness, and drain behavior have spec
+coverage but not production mileage. (On loopback-bound macOS, lanes
+lose a few percent instead; see the secondary table below.)
 
 ## Logging costs
 
@@ -265,11 +384,11 @@ typical costs):
 
 | case (8×3, same session) | req/s |
 |---|---:|
-| threaded, no logging | 217,113 |
-| threaded, `log_requests true` (native access log) | 193,200 (−11%) |
-| ractor, access log off / on | 198,624 / 183,565 (−8%) |
-| app logs 1 line/req via shared `::Logger` (file) | **62,962** |
-| app logs 1 line/req via `Kino::Logger` (file) | **150,810 (2.4×)** |
+| threaded, no logging | 219,168 |
+| threaded, `log_requests true` (native access log) | 193,998 (−11%) |
+| ractor, access log off / on | 197,596 / 181,050 (−8%) |
+| app logs 1 line/req via shared `::Logger` (file) | **62,961** |
+| app logs 1 line/req via `Kino::Logger` (file) | **149,519 (2.4×)** |
 
 The shared-`::Logger` cost is the mutex: 24 worker threads serialize
 through one lock plus a write syscall per line. `Kino::Logger` hands the

data/doc/rails-on-ractors.md

@@ -7,10 +7,11 @@
 Rails 8.2.0.alpha boots and serves with `mode :threaded` (see the
 example's `kino.rb`; just `bundle exec kino` in that directory). Measured
 on the hello-world (c7a.2xlarge, 8 cores, production mode, 8×5):
-~2.3k req/s in 97 MB, single process. The 8-worker Puma cluster reaches
-~11.9k in 797 MB by parallelizing across forks—Rails-on-Ractors is
-interesting precisely because it could offer that ~5× parallelism at
-~1/8th of the memory.
+~2.6k req/s in 92 MB PSS, single process. The 8-worker Puma cluster
+reaches ~12.1k by parallelizing across forks, at 389 MB PSS (794 MB RSS,
+but its forks share the framework copy-on-write, so PSS is the fair
+figure)—Rails-on-Ractors is interesting precisely because it could offer
+that ~4.6× parallelism at ~1/4th of the memory.
 
 Pair it with production-style Rails settings: eager load, no code
 reloading, database pool ≥ workers × threads, logger to stdout or another

data/doc/why-kino.md

@@ -15,8 +15,8 @@ deep-copies it, and sockets cannot cross at all.
 
 We measured what the "obvious" workaround costs. The ractor-pool wrapper
 experiment (reduce the env to a shareable subset, copy it to a worker
-over a `Ractor::Port`, copy the response back) runs at **19k req/s where
-Kino does 201k** on the same hardware—see the
+over a `Ractor::Port`, copy the response back) runs at **19.5k req/s
+where Kino does 194k** on the same hardware—see the
 [wrapper comparison](benchmarks.md#the-ractor-pool-wrapper-comparison).
 Copying at the Rack layer eats the entire ractor dividend. Dispatch has
 to live below the Rack contract.
@@ -78,12 +78,12 @@ objects; Rust sees one queue and one registry.
 
 With the dispatch cost eliminated, Ractors deliver the thing they were
 built for—a lock per ractor instead of one GVL—and each layer is
-visible in the [benchmarks](benchmarks.md): `/cpu` at 66.7k req/s in
-ractor mode vs **13.3k threaded (5×, the GVL ceiling)**, matching the
-fork cluster's CPU parallelism while holding **57 MB against the
-cluster's 1,078 MB**, because eight ractors share one VM, one Rust
-front-end, one queue, and one JIT, where eight forks each pay full
-price.
+visible in the [benchmarks](benchmarks.md): `/cpu` at 78.0k req/s in
+ractor mode vs **13.4k threaded (5.8×, the GVL ceiling)**, beating the
+fork cluster's CPU parallelism by +34% while holding **~148 MB against
+the cluster's ~1,068 MB** (by PSS, on the bench app), because eight
+ractors share one VM, one Rust front-end, one queue, and one JIT, where
+eight forks each pay full price.
 
 The cleanest proof of the design is the threaded fallback itself: it
 reuses ~95% of the same machinery, because the Rust core is

data/ext/kino/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kino"
-version = "0.1.0"
+version = "0.1.2"
 edition = "2021"
 authors = ["Yaroslav Markin <yaroslav@markin.net>"]
 license = "MIT"

data/ext/kino/src/registry.rs

@@ -41,6 +41,9 @@ pub struct ServerInner {
     /// 0 = no request timeout; otherwise the response head must arrive
     /// within this many ms or the client gets a 504.
     pub request_timeout_ms: u64,
+    /// 0 = unlimited; otherwise the max request-body bytes accepted before a
+    /// 413 (truthful Content-Length) or a mid-stream abort (chunked/lying).
+    pub max_body_size: usize,
     pub timeouts: AtomicU64,
     pub https: bool,
     /// Native access log sink (None unless log_requests is on).
@@ -180,6 +183,7 @@ pub fn test_server(lanes: bool, queue_depth: usize) -> Arc<ServerInner> {
         rejected: AtomicU64::new(0),
         queue_timeout_ms: 10,
         request_timeout_ms: 0,
+        max_body_size: 0,
         timeouts: AtomicU64::new(0),
         https: false,
         access_log: None,

data/ext/kino/src/request.rs

@@ -25,6 +25,12 @@ pub struct RequestCtx {
     /// Request body, streamed from hyper through a bounded channel: hyper is
     /// only polled as Ruby consumes, so inbound backpressure is free.
     pub body_rx: flume::Receiver<Bytes>,
+    /// Set by the body forwarder when the body exceeded max_body_size: turns
+    /// the next read into an error instead of a (truncated) clean EOF.
+    pub body_overflow: Arc<std::sync::atomic::AtomicBool>,
+    /// Set by the body forwarder when the client stalled past the idle
+    /// deadline: the next read raises so the worker reclaims its slot.
+    pub body_timeout: Arc<std::sync::atomic::AtomicBool>,
     /// When a frame is bigger than read_body's max_len, the rest waits here.
     pub leftover: Option<Bytes>,
     /// The owning worker slot (set at admit time, queue.rs); its interrupt
@@ -62,6 +68,20 @@ fn interrupted_error(ruby: &Ruby) -> Error {
     )
 }
 
+fn body_too_large_error(ruby: &Ruby) -> Error {
+    Error::new(
+        ruby.exception_runtime_error(),
+        "Kino: request body exceeded max_body_size",
+    )
+}
+
+fn body_timeout_error(ruby: &Ruby) -> Error {
+    Error::new(
+        ruby.exception_runtime_error(),
+        "Kino: request body read timed out",
+    )
+}
+
 fn invalid_response(ruby: &Ruby, e: impl std::fmt::Display) -> Error {
     Error::new(
         ruby.exception_runtime_error(),
@@ -238,7 +258,17 @@ impl Request {
                 });
                 match outcome {
                     Some(Some(bytes)) => bytes,
-                    Some(None) => return Ok(None), // EOF
+                    Some(None) => {
+                        // Disconnected: a clean EOF, unless the forwarder
+                        // abandoned the body (too large, or the client stalled).
+                        if ctx.body_overflow.load(std::sync::atomic::Ordering::Relaxed) {
+                            return Err(body_too_large_error(ruby));
+                        }
+                        if ctx.body_timeout.load(std::sync::atomic::Ordering::Relaxed) {
+                            return Err(body_timeout_error(ruby));
+                        }
+                        return Ok(None); // EOF
+                    }
                     None => return Err(interrupted_error(ruby)),
                 }
             }
@@ -363,6 +393,8 @@ pub fn test_ctx() -> crate::registry::BoxedCtx {
         local_addr: "127.0.0.1:9292".parse().expect("static addr"),
         https: false,
         body_rx,
+        body_overflow: Arc::new(std::sync::atomic::AtomicBool::new(false)),
+        body_timeout: Arc::new(std::sync::atomic::AtomicBool::new(false)),
         leftover: None,
         slot: None,
         responder: Arc::new(Responder::new(head_tx)),