kino 0.1.0

data/ext/kino/src/env_strings.rs

@@ -0,0 +1,318 @@
+//! One-time cache of frozen Ruby strings for the per-request env hash.
+//!
+//! Frozen strings are Ractor-shareable, so a single cache built on the main
+//! ractor at init serves every worker ractor forever. Frozen Hash keys are
+//! also stored without the dup `Hash#[]=` does for unfrozen string keys.
+//! This removes the bulk of per-request allocations: every static key, the
+//! method/protocol/scheme values, and the `HTTP_*` names of all common
+//! request headers.
+//!
+//! `Opaque<RString>` is magnus's sanctioned way to keep Ruby values in
+//! statics (it is Send + Sync); GC registration makes them immortal. Built
+//! once, with the GVL held, on the main ractor; read-only afterwards.
+
+use std::net::IpAddr;
+use std::sync::OnceLock;
+
+use magnus::value::Opaque;
+use magnus::{gc, prelude::*, RString, Ruby, Value};
+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>;
+
+pub struct EnvStrings {
+    // keys
+    pub request_method: Opaque<RString>,
+    pub script_name: Opaque<RString>,
+    pub path_info: Opaque<RString>,
+    pub query_string: Opaque<RString>,
+    pub server_protocol: Opaque<RString>,
+    pub server_name: Opaque<RString>,
+    pub server_port: Opaque<RString>,
+    pub remote_addr: Opaque<RString>,
+    pub content_type: Opaque<RString>,
+    pub content_length: Opaque<RString>,
+    pub rack_url_scheme: Opaque<RString>,
+    pub rack_input: Opaque<RString>,
+    pub rack_errors: Opaque<RString>,
+    pub kino_request: Opaque<RString>,
+    // values
+    pub empty: Opaque<RString>,
+    pub http: Opaque<RString>,
+    pub https: Opaque<RString>,
+    pub http10: Opaque<RString>,
+    pub http11: 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.
+    /// 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 addrs: Mutex<lru::LruCache<IpAddr, CachedStr, ahash::RandomState>>,
+    /// 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>>>,
+    pub null_input: RwLock<Option<Opaque<Value>>>,
+}
+
+const HOST_CACHE_CAP: usize = 256;
+const ADDR_CACHE_CAP: usize = 1024;
+
+/// A frozen RString rooted via BoxValue (GC-registered address; unregisters
+/// on Drop, so LRU eviction actually frees the string).
+///
+/// SAFETY of Send + Sync: the contents are frozen Ruby strings (therefore
+/// Ractor-shareable), and creation, reads, and drops all happen while the
+/// calling thread holds its GVL (native method context) AND the owning
+/// cache Mutex; readers root the value into a live env Hash before
+/// releasing the lock, so an eviction on another ractor can never free a
+/// string that a reader still holds unrooted.
+pub struct CachedStr(magnus::value::BoxValue<RString>);
+unsafe impl Send for CachedStr {}
+unsafe impl Sync for CachedStr {}
+
+impl CachedStr {
+    fn new(ruby: &Ruby, s: &str) -> Self {
+        let string = ruby.str_new(s);
+        string.freeze();
+        CachedStr(magnus::value::BoxValue::new(string))
+    }
+
+    fn get(&self) -> RString {
+        *self.0
+    }
+}
+
+static ENV_STRINGS: OnceLock<EnvStrings> = OnceLock::new();
+
+const COMMON_METHODS: &[&str] = &[
+    "GET", "HEAD", "POST", "PUT", "DELETE", "PATCH", "OPTIONS", "TRACE", "CONNECT",
+];
+
+/// Headers worth pre-caching: hyper lowercases names, so these match the
+/// wire form of essentially all browser/proxy/SDK traffic.
+const COMMON_HEADERS: &[&str] = &[
+    "host",
+    "connection",
+    "user-agent",
+    "accept",
+    "accept-encoding",
+    "accept-language",
+    "accept-charset",
+    "cookie",
+    "referer",
+    "origin",
+    "authorization",
+    "cache-control",
+    "pragma",
+    "expect",
+    "forwarded",
+    "via",
+    "range",
+    "te",
+    "dnt",
+    "upgrade-insecure-requests",
+    "if-none-match",
+    "if-modified-since",
+    "if-match",
+    "if-unmodified-since",
+    "if-range",
+    "x-forwarded-for",
+    "x-forwarded-proto",
+    "x-forwarded-host",
+    "x-forwarded-port",
+    "x-real-ip",
+    "x-request-id",
+    "x-requested-with",
+    "x-csrf-token",
+    "x-api-key",
+    "content-encoding",
+    "content-language",
+    "sec-fetch-dest",
+    "sec-fetch-mode",
+    "sec-fetch-site",
+    "sec-fetch-user",
+    "sec-ch-ua",
+    "sec-ch-ua-mobile",
+    "sec-ch-ua-platform",
+    "keep-alive",
+];
+
+pub fn cgi_name(lower: &str) -> String {
+    let mut key = String::with_capacity(5 + lower.len());
+    key.push_str("HTTP_");
+    for ch in lower.chars() {
+        key.push(match ch {
+            '-' => '_',
+            c => c.to_ascii_uppercase(),
+        });
+    }
+    key
+}
+
+fn frozen(ruby: &Ruby, s: &str) -> Opaque<RString> {
+    let string = ruby.str_new(s);
+    string.freeze();
+    gc::register_mark_object(string);
+    Opaque::from(string)
+}
+
+/// Build the cache. Main ractor, GVL held, before any worker exists.
+pub fn init(ruby: &Ruby) {
+    let methods = COMMON_METHODS
+        .iter()
+        .map(|m| (*m, frozen(ruby, m)))
+        .collect::<HashMap<_, _>>();
+    let header_names = COMMON_HEADERS
+        .iter()
+        .map(|h| (*h, frozen(ruby, &cgi_name(h))))
+        .collect::<HashMap<_, _>>();
+
+    let strings = EnvStrings {
+        request_method: frozen(ruby, "REQUEST_METHOD"),
+        script_name: frozen(ruby, "SCRIPT_NAME"),
+        path_info: frozen(ruby, "PATH_INFO"),
+        query_string: frozen(ruby, "QUERY_STRING"),
+        server_protocol: frozen(ruby, "SERVER_PROTOCOL"),
+        server_name: frozen(ruby, "SERVER_NAME"),
+        server_port: frozen(ruby, "SERVER_PORT"),
+        remote_addr: frozen(ruby, "REMOTE_ADDR"),
+        content_type: frozen(ruby, "CONTENT_TYPE"),
+        content_length: frozen(ruby, "CONTENT_LENGTH"),
+        rack_url_scheme: frozen(ruby, "rack.url_scheme"),
+        rack_input: frozen(ruby, "rack.input"),
+        rack_errors: frozen(ruby, "rack.errors"),
+        kino_request: frozen(ruby, "kino.request"),
+        empty: frozen(ruby, ""),
+        http: frozen(ruby, "http"),
+        https: frozen(ruby, "https"),
+        http10: frozen(ruby, "HTTP/1.0"),
+        http11: frozen(ruby, "HTTP/1.1"),
+        methods,
+        header_names,
+        hosts: Mutex::new(lru::LruCache::with_hasher(
+            std::num::NonZeroUsize::new(HOST_CACHE_CAP).unwrap(),
+            ahash::RandomState::new(),
+        )),
+        addrs: Mutex::new(lru::LruCache::with_hasher(
+            std::num::NonZeroUsize::new(ADDR_CACHE_CAP).unwrap(),
+            ahash::RandomState::new(),
+        )),
+        errors_stream: RwLock::new(None),
+        null_input: RwLock::new(None),
+    };
+    let _ = ENV_STRINGS.set(strings);
+}
+
+pub fn get() -> &'static EnvStrings {
+    ENV_STRINGS.get().expect("env_strings::init not called")
+}
+
+/// Called once from lib/kino.rb (main ractor) with the frozen,
+/// Ractor-shareable singletons the Ruby layer owns.
+pub fn register_defaults(
+    ruby: &Ruby,
+    errors: Value,
+    null_input: Value,
+) -> Result<(), magnus::Error> {
+    for value in [errors, null_input] {
+        if !value.is_frozen() {
+            return Err(magnus::Error::new(
+                ruby.exception_arg_error(),
+                "register_defaults expects frozen objects",
+            ));
+        }
+    }
+    gc::register_mark_object(errors);
+    gc::register_mark_object(null_input);
+    let s = get();
+    *s.errors_stream.write() = Some(Opaque::from(errors));
+    *s.null_input.write() = Some(Opaque::from(null_input));
+    Ok(())
+}
+
+/// Set SERVER_NAME/SERVER_PORT on `env` from the LRU host cache, building
+/// (and caching) frozen values on miss. The aset happens UNDER the cache
+/// lock; see CachedStr's safety contract.
+pub fn set_host_env(
+    ruby: &Ruby,
+    env: magnus::RHash,
+    host: &[u8],
+    make: impl FnOnce() -> (String, u16),
+) -> Result<(), magnus::Error> {
+    let s = get();
+    let mut hosts = s.hosts.lock();
+    let (name, port) = match hosts.get(host) {
+        Some((name, port)) => (name.get(), port.get()),
+        None => {
+            let (name_s, port_n) = make();
+            let entry = (
+                CachedStr::new(ruby, &name_s),
+                CachedStr::new(ruby, &port_n.to_string()),
+            );
+            let values = (entry.0.get(), entry.1.get());
+            hosts.put(host.to_vec(), entry); // may evict + free an old pair
+            values
+        }
+    };
+    env.aset(ruby.get_inner(s.server_name), name)?;
+    env.aset(ruby.get_inner(s.server_port), port)?;
+    Ok(())
+}
+
+/// Set REMOTE_ADDR on `env` from the LRU peer-IP cache; same locking
+/// contract as set_host_env.
+pub fn set_addr_env(ruby: &Ruby, env: magnus::RHash, ip: IpAddr) -> Result<(), magnus::Error> {
+    let s = get();
+    let mut addrs = s.addrs.lock();
+    let value = match addrs.get(&ip) {
+        Some(cached) => cached.get(),
+        None => {
+            let entry = CachedStr::new(ruby, &ip.to_string());
+            let value = entry.get();
+            addrs.put(ip, entry);
+            value
+        }
+    };
+    env.aset(ruby.get_inner(s.remote_addr), value)?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{cgi_name, COMMON_HEADERS, COMMON_METHODS};
+
+    #[test]
+    fn cgi_names() {
+        assert_eq!(cgi_name("x-request-id"), "HTTP_X_REQUEST_ID");
+        assert_eq!(cgi_name("host"), "HTTP_HOST");
+        assert_eq!(cgi_name(""), "HTTP_");
+        assert_eq!(cgi_name("sec-ch-ua"), "HTTP_SEC_CH_UA");
+    }
+
+    // The cache is keyed by hyper's lowercase wire form; one uppercase
+    // entry would silently never hit.
+    #[test]
+    fn common_headers_are_lowercase_and_unique() {
+        let mut seen = std::collections::HashSet::new();
+        for header in COMMON_HEADERS {
+            assert_eq!(*header, header.to_ascii_lowercase(), "{header} must be lowercase");
+            assert!(seen.insert(*header), "{header} listed twice");
+        }
+    }
+
+    #[test]
+    fn common_methods_are_uppercase_and_unique() {
+        let mut seen = std::collections::HashSet::new();
+        for method in COMMON_METHODS {
+            assert_eq!(*method, method.to_ascii_uppercase(), "{method} must be uppercase");
+            assert!(seen.insert(*method), "{method} listed twice");
+        }
+    }
+}

data/ext/kino/src/gvl.rs

@@ -0,0 +1,103 @@
+//! Releasing the GVL (per-ractor VM lock) around blocking Rust calls.
+//!
+//! magnus does not wrap `rb_thread_call_without_gvl`, so this is the one
+//! module that talks to rb-sys directly. Everything blocking (queue pops,
+//! body reads/writes) must go through `without_gvl` so other Ruby threads
+//! in the same ractor keep running and the VM can interrupt us via the UBF.
+
+use std::ffi::c_void;
+
+/// An unblock function: called by the Ruby VM from another thread when it
+/// needs to interrupt the blocking region (Thread#kill, VM shutdown, ...).
+/// Implementations must be async-signal-safe in spirit: no locks, no Ruby
+/// API. A single lock-free channel send is the intended use.
+pub struct Ubf {
+    pub func: unsafe extern "C" fn(*mut c_void),
+    pub data: *mut c_void,
+}
+
+unsafe extern "C" fn trampoline<F, R>(arg: *mut c_void) -> *mut c_void
+where
+    F: FnOnce() -> R,
+{
+    let slot = unsafe { &mut *(arg as *mut (Option<F>, Option<R>)) };
+    let f = slot.0.take().expect("without_gvl trampoline called twice");
+    slot.1 = Some(f());
+    std::ptr::null_mut()
+}
+
+/// Run `f` with the GVL released. Blocks the current Ruby thread but lets
+/// every other Ruby thread (in this ractor) run in parallel.
+///
+/// `f` MUST NOT touch any Ruby API. If `ubf` fires, `f` is responsible for
+/// noticing (e.g. a message on an interrupt channel) and returning promptly;
+/// pending VM interrupts are then delivered once we're back in Ruby.
+pub fn without_gvl<F, R>(f: F, ubf: Option<Ubf>) -> R
+where
+    F: FnOnce() -> R,
+{
+    let mut slot: (Option<F>, Option<R>) = (Some(f), None);
+    let (ubf_func, ubf_data) = match ubf {
+        Some(u) => (Some(u.func), u.data),
+        None => (None, std::ptr::null_mut()),
+    };
+    unsafe {
+        rb_sys::rb_thread_call_without_gvl(
+            Some(trampoline::<F, R>),
+            &mut slot as *mut _ as *mut c_void,
+            ubf_func,
+            ubf_data,
+        );
+    }
+    slot.1.expect("without_gvl block did not run")
+}
+
+/// The standard UBF used across this crate: `data` points at an `AtomicBool`
+/// owned by a `WorkerSlot` kept alive by the caller's stack frame (an Arc
+/// clone held across the blocking call). The blocked region polls the flag
+/// between bounded waits, so a store here unblocks it within one tick.
+pub unsafe extern "C" fn ubf_interrupt(data: *mut c_void) {
+    let flag = unsafe { &*(data as *const std::sync::atomic::AtomicBool) };
+    flag.store(true, std::sync::atomic::Ordering::SeqCst);
+}
+
+/// The crate's one blocking idiom: release the GVL and run `attempt` in a
+/// loop (`Some(T)` finishes, `None` means "tick elapsed, go around"), and
+/// wake within a tick when `flag` is raised (by the VM's UBF or by
+/// interrupt_all_workers). Returns None on interruption. `attempt` must
+/// bound each wait (recv_timeout-style) and must not touch the Ruby API.
+pub fn interruptible<T>(
+    flag: &std::sync::atomic::AtomicBool,
+    mut attempt: impl FnMut() -> Option<T>,
+) -> Option<T> {
+    use std::sync::atomic::Ordering;
+
+    without_gvl(
+        || loop {
+            if flag.load(Ordering::SeqCst) {
+                return None;
+            }
+            if let Some(result) = attempt() {
+                return Some(result);
+            }
+        },
+        Some(Ubf {
+            func: ubf_interrupt,
+            data: flag as *const _ as *mut c_void,
+        }),
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use std::sync::atomic::{AtomicBool, Ordering};
+
+    #[test]
+    fn ubf_sets_the_interrupt_flag() {
+        let flag = AtomicBool::new(false);
+        unsafe {
+            super::ubf_interrupt(&flag as *const _ as *mut std::ffi::c_void);
+        }
+        assert!(flag.load(Ordering::SeqCst));
+    }
+}

data/ext/kino/src/lib.rs

@@ -0,0 +1,90 @@
+// All Rust-side allocations (request/response buffers, hyper, tokio,
+// channels) go through mimalloc: ~+10% plaintext throughput on Linux over
+// glibc malloc, no downside measured elsewhere.
+#[global_allocator]
+static GLOBAL: mimalloc::MiMalloc = mimalloc::MiMalloc;
+
+mod env_strings;
+mod gvl;
+mod logsink;
+mod queue;
+mod registry;
+mod request;
+mod response;
+mod server;
+mod style;
+mod test_support;
+mod timer;
+mod tls;
+
+use magnus::{function, method, prelude::*, Error, Ruby};
+
+use crate::request::Request;
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    // Must come before any method definition: methods defined while this
+    // flag is unset raise Ractor::UnsafeError when called from a non-main
+    // ractor, and worker ractors are this gem's entire reason to exist.
+    unsafe { rb_sys::rb_ext_ractor_safe(true) };
+
+    let module = ruby.define_module("Kino")?;
+
+    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("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))?;
+    native.define_singleton_method("server_stats", function!(server::server_stats, 1))?;
+    native.define_singleton_method("abort_inflight", function!(server::abort_inflight, 2))?;
+    native.define_singleton_method(
+        "abort_all_inflight",
+        function!(server::abort_all_inflight, 1),
+    )?;
+    native.define_singleton_method(
+        "interrupt_all_workers",
+        function!(server::interrupt_all_workers, 1),
+    )?;
+    native.define_singleton_method("shutdown_runtime", function!(server::shutdown_runtime, 2))?;
+    native.define_singleton_method("log_error", function!(server::log_error, 1))?;
+    native.define_singleton_method("sleep_chunk", function!(timer::sleep_chunk, 1))?;
+    native.define_singleton_method("log_device_open", function!(logsink::device_open, 1))?;
+    native.define_singleton_method("log_device_write", function!(logsink::device_write, 2))?;
+    native.define_singleton_method("log_device_close", function!(logsink::device_close, 1))?;
+    native.define_singleton_method(
+        "register_defaults",
+        function!(env_strings::register_defaults, 2),
+    )?;
+
+    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_one",
+        method!(queue::respond_and_take_one, 5),
+    )?;
+    request.define_method("read_body", method!(Request::read_body, 1))?;
+    request.define_method("send_simple", method!(crate::request::respond_simple, 3))?;
+    request.define_method("send_headers", method!(Request::send_headers, 2))?;
+    request.define_method("write_chunk", method!(Request::write_chunk, 1))?;
+    request.define_method("finish", method!(Request::finish, 0))?;
+    request.define_method("abort", method!(Request::abort, 0))?;
+
+    // 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.
+    let _ = <Request as magnus::TypedData>::class(ruby);
+
+    // Frozen env key/value cache: built once here (main ractor, GVL held),
+    // shared by every worker ractor afterwards.
+    env_strings::init(ruby);
+
+    native.define_singleton_method("_test_channel_create", function!(test_support::create, 1))?;
+    native.define_singleton_method("_test_push", function!(test_support::push, 2))?;
+    native.define_singleton_method("_test_take", function!(test_support::take, 1))?;
+    native.define_singleton_method("_test_close", function!(test_support::close, 1))?;
+
+    Ok(())
+}

data/ext/kino/src/logsink.rs

@@ -0,0 +1,155 @@
+//! Asynchronous log sink: callers push complete lines onto a lock-free
+//! channel and return immediately; one dedicated flusher thread batches
+//! them into the output. This removes the two per-line costs of a classic
+//! Ruby Logger device (the cross-thread mutex and the write syscall)
+//! from request threads. Shared by the native access log and
+//! Kino::Logger::Device.
+//!
+//! Durability: the flusher flushes after each drained batch, and dropping
+//! the last Sender makes it drain everything and exit; a graceful
+//! shutdown loses nothing. A hard crash can lose the tail of the buffer,
+//! the standard async-logging trade-off.
+
+use std::io::Write;
+
+pub struct Sink {
+    tx: flume::Sender<String>,
+}
+
+impl Sink {
+    /// `out` is taken by the flusher thread (stdout lock, File, ...).
+    pub fn new<W: Write + Send + 'static>(mut out: W) -> Sink {
+        let (tx, rx) = flume::bounded::<String>(8192);
+        std::thread::Builder::new()
+            .name("kino-log".to_string())
+            .spawn(move || {
+                fn put<W: Write>(out: &mut W, line: &str) {
+                    let _ = out.write_all(line.as_bytes());
+                    let _ = out.write_all(b"\n");
+                }
+                // Block for the first line, then drain whatever else is
+                // queued before flushing once: batching under load,
+                // prompt output when quiet.
+                while let Ok(line) = rx.recv() {
+                    put(&mut out, &line);
+                    while let Ok(line) = rx.try_recv() {
+                        put(&mut out, &line);
+                    }
+                    let _ = out.flush();
+                }
+                let _ = out.flush();
+            })
+            .expect("failed to spawn log flusher thread");
+        Sink { tx }
+    }
+
+    /// Queue one line (without trailing newline). Never blocks the caller:
+    /// when the channel is full the line is dropped; backpressure on the
+    /// request path is exactly what an async log must not create.
+    pub fn write_line(&self, line: String) {
+        let _ = self.tx.try_send(line);
+    }
+}
+
+// --- Ruby-facing log devices (Kino::Logger::Device) -------------------
+//
+// A device is just a Sink in a registry, addressed by id from Ruby. The
+// flusher thread exits when the device is closed (sender dropped).
+
+use std::sync::OnceLock;
+
+type DeviceMap = parking_lot::Mutex<std::collections::HashMap<u64, Sink, ahash::RandomState>>;
+
+static DEVICES: OnceLock<DeviceMap> = OnceLock::new();
+static NEXT_DEVICE_ID: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1);
+
+fn devices() -> &'static DeviceMap {
+    DEVICES.get_or_init(|| parking_lot::Mutex::new(std::collections::HashMap::default()))
+}
+
+/// Open a device: nil/empty path = stdout, otherwise append-create the
+/// file. Returns the device id.
+pub fn device_open(ruby: &magnus::Ruby, path: Option<String>) -> Result<u64, magnus::Error> {
+    let sink = match path.as_deref() {
+        None | Some("") => Sink::new(std::io::stdout()),
+        Some(p) => {
+            let file = std::fs::OpenOptions::new()
+                .create(true)
+                .append(true)
+                .open(p)
+                .map_err(|e| {
+                    magnus::Error::new(
+                        ruby.exception_runtime_error(),
+                        format!("Kino::Logger::Device: cannot open {p}: {e}"),
+                    )
+                })?;
+            Sink::new(file)
+        }
+    };
+    let id = NEXT_DEVICE_ID.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
+    devices().lock().insert(id, sink);
+    Ok(id)
+}
+
+/// Queue a message on a device. The trailing newline (Logger adds one) is
+/// trimmed because the sink writes line-wise.
+pub fn device_write(
+    _ruby: &magnus::Ruby,
+    id: u64,
+    mut message: String,
+) -> Result<(), magnus::Error> {
+    if let Some(sink) = devices().lock().get(&id) {
+        // Trim in place: no second allocation per line.
+        message.truncate(message.trim_end_matches('\n').len());
+        sink.write_line(message);
+    }
+    Ok(())
+}
+
+/// Close a device: drops the sink, which makes the flusher drain its
+/// queue and exit. Writes after close are silently ignored.
+pub fn device_close(_ruby: &magnus::Ruby, id: u64) -> Result<(), magnus::Error> {
+    devices().lock().remove(&id);
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::Sink;
+    use std::io::Write;
+    use std::sync::Arc;
+    use std::time::{Duration, Instant};
+
+    #[derive(Clone, Default)]
+    struct SharedBuf(Arc<parking_lot::Mutex<Vec<u8>>>);
+
+    impl Write for SharedBuf {
+        fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
+            self.0.lock().extend_from_slice(buf);
+            Ok(buf.len())
+        }
+
+        fn flush(&mut self) -> std::io::Result<()> {
+            Ok(())
+        }
+    }
+
+    #[test]
+    fn sink_writes_lines_and_drains_on_drop() {
+        let buf = SharedBuf::default();
+        let sink = Sink::new(buf.clone());
+
+        sink.write_line("first".to_string());
+        sink.write_line("second".to_string());
+        drop(sink); // sender gone: the flusher drains everything and exits
+
+        let deadline = Instant::now() + Duration::from_secs(2);
+        loop {
+            if *buf.0.lock() == b"first\nsecond\n" {
+                break;
+            }
+            assert!(Instant::now() < deadline, "flusher never drained");
+            std::thread::sleep(Duration::from_millis(5));
+        }
+    }
+}