kino 0.5.0 → 0.6.0

data/doc/benchmarks.md

@@ -17,9 +17,21 @@ the deployment most apps run today.
   9R14 (Genoa), 16 GB RAM, Amazon Linux 2023, kernel 6.18. A realistic
   app-server size, deliberately: nobody provisions a 32-core box per
   app process.
-- Toolchain built on the box via mise: Ruby 4.0.5 (**YJIT enabled**,
-  `RUBY_YJIT_ENABLE=1` for every server), Rust 1.96, Kino compiled in
+- Toolchain built on the box via mise: Ruby 4.0.6 (**YJIT enabled**,
+  `RUBY_YJIT_ENABLE=1` for every server), Rust stable, Kino compiled in
   the release profile.
+- **2026-09 full re-measurement** (a fresh c7a.2xlarge): every number in
+  this document and the README was re-run on Ruby 4.0.6 / kernel 6.18 /
+  Puma 8.0.2, adding the sharded-I/O and HTTP/2 studies. Kino's numbers
+  reproduced within 1-3% across the board—including the /io slot
+  ceiling and the arena balloon, both intact. The one real shift: Puma
+  8.0.2 is faster than 7.x (142k plaintext, 61k /cpu), narrowing
+  ractor mode's /cpu lead to +25% (was +34%). Reversed-boot-order
+  re-runs reproduced within ~1%. A methodology trap worth recording:
+  a 5-second single-endpoint warmup understates memory badly (81 MB
+  where the full battery shows 137 MB) and hides the arena balloon
+  entirely—memory is only comparable after the full endpoint battery,
+  and /io numbers are only comparable at equal slot counts.
 - Load generator: wrk 4.2 on the same host, 8-second windows, 64
   connections (`bench/run.sh 8 64`). Same-host load generation costs
   both sides CPU equally; we verified the generator was not the
@@ -249,14 +261,17 @@ visible.
 
 | config | RSS | PSS |
 |---|---:|---:|
-| Kino :ractor 8×1 (default) | 151 | **148** |
-| Kino lanes 8×1 | 137 | **135** |
-| Kino :ractor 8×3 | 171 | **169** |
+| Kino :ractor 8×1 (default) | 137 | **135** |
+| Kino lanes 8×1 | 128 | **126** |
+| Kino :ractor 8×3 | 170 | **168** |
 | 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** |
+| Kino :threaded 8×3 (no arena cap) | 672 | **670**¹ |
+| Puma cluster 8×3 | 1,216 | **1,072** |
 
-The tiny app is ~7× lighter than the cluster in ractor mode, ~10× in
+(2026-09 re-measure; the 2026-06 numbers reproduced within a few MB on
+every row—the arena-capped threaded row to the megabyte.)
+
+The tiny app is ~8× 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
@@ -280,18 +295,19 @@ 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** |
+| Kino :threaded (one process) |  97 |  **95** |
+| Puma cluster 8×5 (preload) | 813 | **405** |
+| Puma cluster 8×5 (no preload) | 824 | **646** |
 
 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
+copy-on-write; RSS counts that shared framework once per worker (813 MB),
+PSS counts it once (405 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.
+re-measure. The 2026-09 run also split out preload: it now saves a
+third (405 vs 646 MB PSS)—worth turning on—but even preloaded, Ruby's
+GC dirties heap pages and breaks copy-on-write, so each worker keeps a
+large private heap. 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?")
 
@@ -376,27 +392,46 @@ 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.)
 
+## Sharded I/O (`io_shards true`)
+
+`bench/studies.sh 8 64 shards`, ractor 8×3, 2026-09 reference box:
+
+| case (/plaintext) | req/s |
+|---|---:|
+| shared tokio runtime (baseline) | 193,461 |
+| io_shards, default shard count | 195,436 |
+| io_shards, `io_threads 2` | 170,509 |
+| io_shards, `io_threads 4` | 196,298 |
+| io_shards, `io_threads 8` | 199,657 |
+
+On 8 cores the shards buy +1-3%, best at `io_threads 8` (the
+half-the-cores default is close behind; 2 shards choke on accept
+handoff). The design removes work-stealing and cross-thread wakeups,
+so the win scales with scheduler contention—expect more on boxes with
+more cores and connections, and measure on your own core count.
+
 ## Logging costs
 
 Measured at full plaintext saturation (one log line per request—rates
 that no real deployment logs at; treat these as worst-case ceilings, not
 typical costs):
 
-| case (8×3, same session) | req/s |
+| case (8×3, same session, 2026-09) | req/s |
 |---|---:|
-| 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×)** |
+| threaded, no logging | 213,166 |
+| threaded, `log_requests true` (native access log) | 173,501 (−19%) |
+| ractor, access log off / on | 191,152 / 163,777 (−14%) |
+| app logs 1 line/req via shared `::Logger` (file) | **90,175** |
+| app logs 1 line/req via `Kino::Logger` (file) | **154,653 (1.7×)** |
 
 The shared-`::Logger` cost is the mutex: 24 worker threads serialize
 through one lock plus a write syscall per line. `Kino::Logger` hands the
 formatted line to a lock-free channel and returns—the remaining cost vs
 not logging at all is Ruby-side formatting, which no device can remove.
-(In the Docker environment the same comparison showed 8.5×—overlay-fs
-write latency punished the synchronous logger far harder than this box's
-NVMe does. The ranking is environment-independent; the multiple is not.)
+(The multiple moves with the environment: 2.4× on the 2026-06 box,
+1.7× on the 2026-09 one, 8.5× under Docker, where overlay-fs write
+latency punished the synchronous logger hardest. The ranking is
+environment-independent; the multiple is not.)
 
 One trade-off worth knowing: the sink **never blocks** request threads,
 so at absurd rates against a slow disk it drops lines once its 8192-line
@@ -408,6 +443,65 @@ Puma comparison note: request logging is opt-in there too (`--quiet` is
 the default, `-v/--log-requests` enables it)—Kino's default-off
 `log_requests` matches the ecosystem's standard behavior.
 
+## HTTP/2
+
+`bench/h2.sh`, Linux only (on macOS run it under Docker; the 2026-09
+numbers below are from the c7a.2xlarge reference box). Every lane is
+measured with h2load so the generator is identical everywhere: h2
+lanes run 8 connections × 8 concurrent streams, h1 lanes 64
+connections—the same total in-flight. Servers without native h2 get
+the standard pattern instead: nginx terminating h2 and proxying
+HTTP/1.1 upstream over keep-alive. One labeled run (kino ractor 8×3,
+falcon `--count 8`, puma `-w 8 -t 3:3`, 5 s/lane); re-run the whole
+script for close calls, per the variance section.
+
+| target (h2 unless noted) | /plaintext | /10k | /big-cookie | /upload (64 KB) |
+|---|---:|---:|---:|---:|
+| kino h2c | 207,461 | 150,105 | 195,093 | 26,304 |
+| kino h1 cleartext (same boot) | 116,082 | 97,634 | 110,614 | 24,338 |
+| kino h2 TLS | 164,044 | 116,617 | 154,301 | 19,226 |
+| kino h1 TLS (same boot) | 80,789 | 69,942 | 76,654 | 17,210 |
+| falcon TLS (native h2) | 55,637 | 37,541 | 49,151 | 18,838 |
+| nginx h2 → puma h1 | 81,234 | 57,891 | 51,332 | 1,247 |
+| nginx h2 → kino h1 | 109,219 | 66,634 | 54,996 | 1,217 |
+
+What the numbers say:
+
+- **Native h2 beats h1 on the same server by +79% cleartext and +103%
+  over TLS** on /plaintext: the same 64 in-flight requests ride 8
+  connections instead of 64, so frames batch into fewer, larger
+  syscalls—and TLS amplifies it, since h1's 64 connections each pay
+  crypto per record. The `/big-cookie` lane (a ~2 KB cookie per
+  request) shows HPACK on top: the cookie crosses the wire once per
+  connection, not once per request, and holds 94% of bare-plaintext
+  throughput where h1 loses 5%.
+- **Native h2 beats proxied h2 by +50%** with the *same backend*: the
+  nginx→kino-h1 lane is the proxy-cost control, and the extra hop,
+  re-parse, and re-serialize cost ~55k req/s on /plaintext.
+- **Uploads run at h1 parity**—but only after a fix this lane
+  caught: h2 delivers bodies as 16 KB DATA frames, and `read_body`
+  originally crossed the GVL once per chunk, halving upload
+  throughput. It now drains every queued chunk per crossing
+  (doc/architecture.md), and a knob sweep over hyper's h2 codec
+  (frame size, adaptive/bigger windows) moved nothing afterwards.
+  nginx's h2 upload collapse (~1.5k) is its default-config
+  request-body flow control; tune `http2_body_preread_size`/buffering
+  before drawing conclusions there.
+- falcon lands at roughly a third of kino-h2-TLS on fast handlers and
+  slightly behind on uploads. Single-run caveat: the nginx lanes
+  showed ±20% swings between runs in the Docker environment; on the
+  reference box the kino-vs-kino and kino-vs-proxy ratios reproduced
+  across runs, the nginx lanes remain the noisiest.
+- **Header-value interning** (user-agent, accept-*, sec-ch-*: one
+  frozen string instead of a fresh allocation per request) was
+  measured with a realistic 11-header browser set on /plaintext,
+  using the within-boot header cost (bare vs with-headers) as the
+  drift-resistant metric: over h2 that cost fell from ~16% to ~12-13%
+  (~+3-5% throughput on the headers lane); h1's smaller header cost
+  stayed within noise. The effect the tiny app understates: 6-8 fewer
+  string allocations per request is GC pressure a real app feels more
+  than this one does.
+
 ## Hot-path notes
 
 For the curious, the dispatch-path work behind the numbers: a try-pop

data/ext/kino/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kino"
-version = "0.5.0"
+version = "0.6.0"
 edition = "2021"
 authors = ["Yaroslav Markin <yaroslav@markin.net>"]
 license = "MIT"
@@ -21,8 +21,8 @@ smallvec = "1"
 lru = "0.18"
 mimalloc = { version = "0.1", default-features = false }
 tokio = { version = "1.45", features = ["rt-multi-thread", "net", "time", "sync", "io-util", "macros"] }
-hyper = { version = "1.6", features = ["http1", "server"] }
-hyper-util = { version = "0.1", features = ["server", "tokio", "http1"] }
+hyper = { version = "1.6", features = ["http1", "http2", "server"] }
+hyper-util = { version = "0.1", features = ["server", "server-auto", "tokio", "http1", "http2"] }
 http = "1"
 http-body-util = "0.1"
 bytes = "1"
@@ -49,3 +49,8 @@ rb-sys-env = "0.2.2"
 # undefined (the host process provides them at runtime); feature
 # unification turns this on only for `cargo test`.
 rb-sys = { version = "0.9", features = ["link-ruby"] }
+# The protocol tests drive the server end of a duplex pipe with hyper's
+# own client, and pause the clock to test timeouts; feature unification
+# enables both only for `cargo test`.
+hyper = { version = "1.6", features = ["client"] }
+tokio = { version = "1.45", features = ["test-util"] }

data/ext/kino/src/env_strings.rs

@@ -21,6 +21,7 @@ use parking_lot::{Mutex, RwLock};
 /// These maps are probed several times per request; ahash beats the
 /// DoS-resistant default since every key here is our own static data.
 type HashMap<K, V> = std::collections::HashMap<K, V, ahash::RandomState>;
+type HashSet<K> = std::collections::HashSet<K, ahash::RandomState>;
 
 pub struct EnvStrings {
     // keys
@@ -44,17 +45,25 @@ pub struct EnvStrings {
     pub https: Opaque<RString>,
     pub http10: Opaque<RString>,
     pub http11: Opaque<RString>,
+    pub http2: Opaque<RString>,
     pub methods: HashMap<&'static str, Opaque<RString>>,
     /// lowercase header name -> frozen "HTTP_<UPPER>" key
     pub header_names: HashMap<&'static str, Opaque<RString>>,
-    /// Host-header bytes -> frozen (SERVER_NAME, SERVER_PORT) values, and
-    /// peer IP -> frozen REMOTE_ADDR value. Real traffic has low
-    /// cardinality on both, so these kill 3 string allocations per request.
+    /// Host-header or :authority bytes -> frozen host values, and peer
+    /// IP -> frozen REMOTE_ADDR value. Real traffic has low cardinality
+    /// on both, so these kill 3 string allocations per request.
     /// LRU-bounded: entries are BoxValue-rooted (registered with the GC on
     /// insert, UNregistered on eviction-drop), so a rotating-host attack
     /// recycles cache slots instead of leaking immortal strings.
-    pub hosts: Mutex<lru::LruCache<Vec<u8>, (CachedStr, CachedStr), ahash::RandomState>>,
+    pub hosts: Mutex<lru::LruCache<Vec<u8>, HostEntry, ahash::RandomState>>,
     pub addrs: Mutex<lru::LruCache<IpAddr, CachedStr, ahash::RandomState>>,
+    /// Interned values of low-cardinality headers (see
+    /// [`INTERNABLE_VALUES`]): value bytes -> frozen RString, shared
+    /// across headers that happen to carry the same bytes. Same rooting
+    /// and locking contract as `hosts`/`addrs`.
+    pub values: Mutex<lru::LruCache<Vec<u8>, CachedStr, ahash::RandomState>>,
+    /// The names whose values go through the `values` cache.
+    pub internable: HashSet<&'static str>,
     /// Ractor-shareable defaults provided by the Ruby layer at boot:
     /// the frozen rack.errors writer and the frozen null rack.input.
     pub errors_stream: RwLock<Option<Opaque<Value>>>,
@@ -63,6 +72,53 @@ pub struct EnvStrings {
 
 const HOST_CACHE_CAP: usize = 256;
 const ADDR_CACHE_CAP: usize = 1024;
+const VALUE_CACHE_CAP: usize = 512;
+
+/// Values longer than this are never interned: past it the memcpy into
+/// a fresh Ruby string is cheap relative to the bytes themselves, and
+/// unbounded keys would let one client fill the cache with garbage.
+const VALUE_INTERN_MAX_LEN: usize = 512;
+
+/// Headers whose values are effectively enums or per-install constants
+/// (a browser resends the same UA, accept-*, and sec-ch-* on every
+/// request), so caching kills an allocation + copy per header per
+/// request: the env-side analogue of what HPACK does on the wire.
+/// Deliberately absent: `cookie` and `authorization` (per-user
+/// cardinality would churn the cache, and secrets should not outlive
+/// their request in an evict-to-free cache), `referer`/`x-request-id`
+/// and friends (unbounded cardinality).
+const INTERNABLE_VALUES: &[&str] = &[
+    "user-agent",
+    "accept",
+    "accept-encoding",
+    "accept-language",
+    "cache-control",
+    "dnt",
+    "origin",
+    "pragma",
+    "priority",
+    "sec-ch-ua",
+    "sec-ch-ua-mobile",
+    "sec-ch-ua-platform",
+    "sec-fetch-dest",
+    "sec-fetch-mode",
+    "sec-fetch-site",
+    "sec-fetch-user",
+    "upgrade-insecure-requests",
+    "x-requested-with",
+];
+
+/// One hosts-cache entry: the frozen SERVER_NAME/SERVER_PORT pair, plus
+/// the frozen full authority ("host[:port]" as sent) used as the
+/// HTTP_HOST value for requests that carry the name in the URI (the h2
+/// :authority pseudo-header) rather than a Host header. Lazily filled:
+/// Host-header entries and the NUL-prefixed socket-fallback entries
+/// never allocate it.
+pub struct HostEntry {
+    name: CachedStr,
+    port: CachedStr,
+    host: Option<CachedStr>,
+}
 
 /// A frozen RString rooted via BoxValue (GC-registered address; unregisters
 /// on Drop, so LRU eviction actually frees the string).
@@ -84,6 +140,16 @@ impl CachedStr {
         CachedStr(magnus::value::BoxValue::new(string))
     }
 
+    /// Header values are bytes on the wire (not guaranteed UTF-8), so
+    /// they cache as the same binary strings `str_from_slice` builds on
+    /// the uncached path; interning must not change the encoding an
+    /// app observes.
+    fn new_from_slice(ruby: &Ruby, bytes: &[u8]) -> Self {
+        let string = ruby.str_from_slice(bytes);
+        string.freeze();
+        CachedStr(magnus::value::BoxValue::new(string))
+    }
+
     fn get(&self) -> RString {
         *self.0
     }
@@ -142,6 +208,8 @@ const COMMON_HEADERS: &[&str] = &[
     "sec-ch-ua-mobile",
     "sec-ch-ua-platform",
     "keep-alive",
+    "priority",
+    "alt-used",
 ];
 
 pub fn cgi_name(lower: &str) -> String {
@@ -194,6 +262,7 @@ pub fn init(ruby: &Ruby) {
         https: frozen(ruby, "https"),
         http10: frozen(ruby, "HTTP/1.0"),
         http11: frozen(ruby, "HTTP/1.1"),
+        http2: frozen(ruby, "HTTP/2"),
         methods,
         header_names,
         hosts: Mutex::new(lru::LruCache::with_hasher(
@@ -204,6 +273,11 @@ pub fn init(ruby: &Ruby) {
             std::num::NonZeroUsize::new(ADDR_CACHE_CAP).unwrap(),
             ahash::RandomState::new(),
         )),
+        values: Mutex::new(lru::LruCache::with_hasher(
+            std::num::NonZeroUsize::new(VALUE_CACHE_CAP).unwrap(),
+            ahash::RandomState::new(),
+        )),
+        internable: INTERNABLE_VALUES.iter().copied().collect(),
         errors_stream: RwLock::new(None),
         null_input: RwLock::new(None),
     };
@@ -249,20 +323,98 @@ pub fn set_host_env(
     let s = get();
     let mut hosts = s.hosts.lock();
     let (name, port) = match hosts.get(host) {
-        Some((name, port)) => (name.get(), port.get()),
+        Some(entry) => (entry.name.get(), entry.port.get()),
         None => {
             let (name_s, port_n) = make();
-            let entry = (
-                CachedStr::new(ruby, &name_s),
-                CachedStr::new(ruby, &port_n.to_string()),
+            let entry = HostEntry {
+                name: CachedStr::new(ruby, &name_s),
+                port: CachedStr::new(ruby, &port_n.to_string()),
+                host: None,
+            };
+            let values = (entry.name.get(), entry.port.get());
+            hosts.put(host.to_vec(), entry); // may evict + free an old entry
+            values
+        }
+    };
+    env.aset(ruby.get_inner(s.server_name), name)?;
+    env.aset(ruby.get_inner(s.server_port), port)?;
+    Ok(())
+}
+
+/// Set SERVER_NAME/SERVER_PORT *and* HTTP_HOST on `env` from the URI
+/// authority (every h2 request via :authority; also h1 absolute-form).
+/// HTTP_HOST is set here because such requests carry no Host header for
+/// the header loop to surface. Same cache and locking contract as
+/// [`set_host_env`]; an entry first created by a Host header upgrades in
+/// place, gaining the full-authority string on first use.
+pub fn set_authority_env(
+    ruby: &Ruby,
+    env: magnus::RHash,
+    authority: &str,
+    make: impl FnOnce() -> (String, u16),
+) -> Result<(), magnus::Error> {
+    let s = get();
+    let mut hosts = s.hosts.lock();
+    let (name, port, host) = match hosts.get_mut(authority.as_bytes()) {
+        Some(entry) => {
+            if entry.host.is_none() {
+                entry.host = Some(CachedStr::new(ruby, authority));
+            }
+            (
+                entry.name.get(),
+                entry.port.get(),
+                entry.host.as_ref().expect("just filled").get(),
+            )
+        }
+        None => {
+            let (name_s, port_n) = make();
+            let entry = HostEntry {
+                name: CachedStr::new(ruby, &name_s),
+                port: CachedStr::new(ruby, &port_n.to_string()),
+                host: Some(CachedStr::new(ruby, authority)),
+            };
+            let values = (
+                entry.name.get(),
+                entry.port.get(),
+                entry.host.as_ref().expect("just built").get(),
             );
-            let values = (entry.0.get(), entry.1.get());
-            hosts.put(host.to_vec(), entry); // may evict + free an old pair
+            hosts.put(authority.as_bytes().to_vec(), entry);
             values
         }
     };
     env.aset(ruby.get_inner(s.server_name), name)?;
     env.aset(ruby.get_inner(s.server_port), port)?;
+    let host_key = *s.header_names.get("host").expect("host is a common header");
+    env.aset(ruby.get_inner(host_key), host)?;
+    Ok(())
+}
+
+/// Set one header's value on `env` under `key`: through the interned
+/// value cache when the header qualifies (low-cardinality name, bounded
+/// length), else a fresh per-request string. The cached aset happens
+/// under the cache lock; see CachedStr's safety contract.
+pub fn set_value_env(
+    ruby: &Ruby,
+    env: magnus::RHash,
+    key: RString,
+    name: &str,
+    value: &[u8],
+) -> Result<(), magnus::Error> {
+    let s = get();
+    if value.len() > VALUE_INTERN_MAX_LEN || !s.internable.contains(name) {
+        return env.aset(key, ruby.str_from_slice(value));
+    }
+    let mut values = s.values.lock();
+    let cached = match values.get(value) {
+        Some(cached) => cached.get(),
+        None => {
+            let entry = CachedStr::new_from_slice(ruby, value);
+            let string = entry.get();
+            values.put(value.to_vec(), entry); // may evict + free an old value
+            string
+        }
+    };
+    env.aset(key, cached)?;
     Ok(())
 }
 

data/ext/kino/src/lib.rs

@@ -41,8 +41,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     let native = module.define_module("Native")?;
     native.define_singleton_method("server_start", function!(server::server_start, 1))?;
     native.define_singleton_method("register_worker", function!(server::register_worker, 1))?;
-    native.define_singleton_method("take_one", function!(queue::take_one, 2))?;
-    native.define_singleton_method("take_batch", function!(queue::take_batch, 3))?;
+    native.define_singleton_method("worker", function!(queue::worker, 2))?;
     native.define_singleton_method("stop_accepting", function!(server::stop_accepting, 1))?;
     native.define_singleton_method("close_queue", function!(server::close_queue, 1))?;
     native.define_singleton_method("queue_stats", function!(server::queue_stats, 1))?;
@@ -84,11 +83,15 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     native.define_class("PinKeeper", ruby.class_object())?;
     native.define_singleton_method("pin_keeper", function!(server::pin_keeper, 1))?;
 
+    let worker = native.define_class("Worker", ruby.class_object())?;
+    worker.define_method("take_one", method!(queue::Worker::take_one, 0))?;
+    worker.define_method("take_batch", method!(queue::Worker::take_batch, 1))?;
+
     let request = native.define_class("Request", ruby.class_object())?;
-    request.define_method("respond_and_take", method!(queue::respond_and_take, 6))?;
+    request.define_method("respond_and_take", method!(queue::respond_and_take, 5))?;
     request.define_method(
         "respond_and_take_one",
-        method!(queue::respond_and_take_one, 5),
+        method!(queue::respond_and_take_one, 4),
     )?;
     request.define_method("read_body", method!(Request::read_body, 1))?;
     request.define_method("send_simple", method!(crate::request::respond_simple, 3))?;
@@ -98,10 +101,11 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     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
-    // worker ractors is the failure mode we must rule out.
+    // Force-resolve the TypedData class caches on the main ractor: magnus
+    // resolves them lazily on first wrap, and a racy first resolution from
+    // two worker ractors is the failure mode we must rule out.
     let _ = <Request as magnus::TypedData>::class(ruby);
+    let _ = <queue::Worker as magnus::TypedData>::class(ruby);
 
     // Frozen env key/value cache: built once here (main ractor, GVL held),
     // shared by every worker ractor afterwards.

data/ext/kino/src/queue.rs

@@ -138,54 +138,73 @@ fn admit(
     Ok(env)
 }
 
-type Checkout = (Arc<ServerInner>, Arc<WorkerSlot>, BoxedCtx);
+/// Per-worker native handle: the registry lookup and slot resolution are
+/// paid once at worker boot instead of on every take. Created inside the
+/// worker thread/ractor that uses it (like Request handles), so ownership
+/// is correct by construction. Holds the server weakly: after teardown the
+/// upgrade fails, which is the same clean shutdown signal the per-take
+/// registry lookup used to give.
+#[magnus::wrap(class = "Kino::Native::Worker", free_immediately)]
+pub struct Worker {
+    server: std::sync::Weak<ServerInner>,
+    slot: Arc<WorkerSlot>,
+}
 
-fn checkout(ruby: &Ruby, server_id: u64, worker_id: usize) -> Result<Option<Checkout>, Error> {
+/// Resolve a (server, worker) pair into a Worker handle; nil when the
+/// server is already gone (the caller treats that as shutdown).
+pub fn worker(ruby: &Ruby, server_id: u64, worker_id: usize) -> Result<Option<Worker>, Error> {
     let Some(server) = registry::try_get(server_id) else {
-        return Ok(None); // server torn down → clean shutdown signal
+        return Ok(None);
     };
     let slot = server.slot(ruby, worker_id)?;
+    Ok(Some(Worker {
+        server: Arc::downgrade(&server),
+        slot,
+    }))
+}
 
-    // The previous batch is fully answered once the worker comes back.
-    slot.current.lock().clear();
-    slot.in_flight.store(0, Ordering::Relaxed);
-    slot.interrupted.store(false, Ordering::SeqCst);
+impl Worker {
+    fn checkout(&self) -> Result<Option<(Arc<ServerInner>, BoxedCtx)>, Error> {
+        let Some(server) = self.server.upgrade() else {
+            return Ok(None); // server torn down → clean shutdown signal
+        };
 
-    Ok(block_take(&server, &slot)?.map(|ctx| (server, slot, ctx)))
-}
+        // The previous batch is fully answered once the worker comes back.
+        self.slot.current.lock().clear();
+        self.slot.in_flight.store(0, Ordering::Relaxed);
+        self.slot.interrupted.store(false, Ordering::SeqCst);
 
-/// Take one request; returns its env Hash (request handle inside under
-/// "kino.request") or nil on shutdown. The batch-of-one hot path: no
-/// arrays allocated at all.
-pub fn take_one(ruby: &Ruby, server_id: u64, worker_id: usize) -> Result<Option<RHash>, Error> {
-    match checkout(ruby, server_id, worker_id)? {
-        Some((server, slot, ctx)) => Ok(Some(admit(ruby, &server, &slot, ctx)?)),
-        None => Ok(None),
+        Ok(block_take(&server, &self.slot)?.map(|ctx| (server, ctx)))
     }
-}
 
-/// Take up to `max` requests: block for the first, drain the rest
-/// non-blocking (they only batch when the queue is already deep).
-/// Returns nil on shutdown; otherwise an Array of env Hashes.
-pub fn take_batch(
-    ruby: &Ruby,
-    server_id: u64,
-    worker_id: usize,
-    max: usize,
-) -> Result<Option<RArray>, Error> {
-    let Some((server, slot, first)) = checkout(ruby, server_id, worker_id)? else {
-        return Ok(None);
-    };
+    /// Take one request; returns its env Hash (request handle inside under
+    /// "kino.request") or nil on shutdown. The batch-of-one hot path: no
+    /// arrays allocated at all.
+    pub fn take_one(ruby: &Ruby, rb_self: &Worker) -> Result<Option<RHash>, Error> {
+        match rb_self.checkout()? {
+            Some((server, ctx)) => Ok(Some(admit(ruby, &server, &rb_self.slot, ctx)?)),
+            None => Ok(None),
+        }
+    }
 
-    let batch = ruby.ary_new_capa(max.max(1));
-    batch.push(admit(ruby, &server, &slot, first)?)?;
-    for _ in 1..max {
-        match server.req_rx.try_recv() {
-            Ok(ctx) => batch.push(admit(ruby, &server, &slot, ctx)?)?,
-            Err(_) => break,
+    /// Take up to `max` requests: block for the first, drain the rest
+    /// non-blocking (they only batch when the queue is already deep).
+    /// Returns nil on shutdown; otherwise an Array of env Hashes.
+    pub fn take_batch(ruby: &Ruby, rb_self: &Worker, max: usize) -> Result<Option<RArray>, Error> {
+        let Some((server, first)) = rb_self.checkout()? else {
+            return Ok(None);
+        };
+
+        let batch = ruby.ary_new_capa(max.max(1));
+        batch.push(admit(ruby, &server, &rb_self.slot, first)?)?;
+        for _ in 1..max {
+            match server.req_rx.try_recv() {
+                Ok(ctx) => batch.push(admit(ruby, &server, &rb_self.slot, ctx)?)?,
+                Err(_) => break,
+            }
         }
+        Ok(Some(batch))
     }
-    Ok(Some(batch))
 }
 
 /// The fused hot path: answer `request` (complete response in one shot)
@@ -194,28 +213,25 @@ pub fn take_batch(
 pub fn respond_and_take_one(
     ruby: &Ruby,
     request: &Request,
-    server_id: u64,
-    worker_id: usize,
+    worker: magnus::typed_data::Obj<Worker>,
     status: u16,
     headers: RHash,
     body: RString,
 ) -> Result<Option<RHash>, Error> {
     crate::request::respond_simple(ruby, request, status, headers, body)?;
-    take_one(ruby, server_id, worker_id)
+    Worker::take_one(ruby, &worker)
 }
 
 /// Batch variant of the fused call.
-#[allow(clippy::too_many_arguments)]
 pub fn respond_and_take(
     ruby: &Ruby,
     request: &Request,
-    server_id: u64,
-    worker_id: usize,
+    worker: magnus::typed_data::Obj<Worker>,
     max: usize,
     status: u16,
     headers: RHash,
     body: RString,
 ) -> Result<Option<RArray>, Error> {
     crate::request::respond_simple(ruby, request, status, headers, body)?;
-    take_batch(ruby, server_id, worker_id, max)
+    Worker::take_batch(ruby, &worker, max)
 }