kobako 0.27.0 → 0.29.0

data/crates/kobako-wasmtime/src/ambient.rs

@@ -1,6 +1,7 @@
-//! Denial of guest ambient authority at the WASI layer — the one grant
-//! that separates the hermetic rung from permissive;
-//! `frames::install_wasi_frames` wires these sources on `Hermetic` only.
+//! The guest's time and entropy at the WASI layer — the one ambient
+//! authority that separates the hermetic rung from permissive. `Wasi::new`
+//! wires the frozen sources on `Hermetic` and the live clock on
+//! `Permissive`; `Clocks` is what the guest's waits pass on under either.
 //!
 //! `wasmtime-wasi`'s `WasiCtxBuilder` defaults the guest's `wasi:clocks` to
 //! the host wall / monotonic clock and `wasi:random` to a fresh per-context
@@ -8,7 +9,7 @@
 //! (`build_config/wasi.rb`), but a future libc-backed gem would silently
 //! obtain real time and host entropy — a covert timing channel and a
 //! nondeterminism source the hermetic posture deliberately excludes
-//! (docs/security-model.md).
+//! (docs/guides/security.md).
 //! Pinning the clocks to the Unix epoch and the RNG to a constant stream
 //! makes that denial a property of the host, not merely of the gem allowlist.
 //!
@@ -16,7 +17,7 @@
 //! wasmtime epoch interruption against a host `Instant`, never the guest's
 //! frozen `wasi:clocks/monotonic-clock`.
 
-use std::time::Duration;
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 
 use wasmtime_wasi::random::Deterministic;
 use wasmtime_wasi::{HostMonotonicClock, HostWallClock};
@@ -53,6 +54,64 @@ pub(crate) fn deterministic_rng() -> Deterministic {
     Deterministic::new(vec![0])
 }
 
+/// The host's monotonic clock read from a fixed origin. The guest's
+/// `clock_time_get` and a wait it subscribes to share it, so both agree on
+/// what an instant means.
+#[derive(Clone, Copy)]
+pub(crate) struct LiveMonotonicClock {
+    origin: Instant,
+}
+
+impl LiveMonotonicClock {
+    pub(crate) fn new() -> Self {
+        Self {
+            origin: Instant::now(),
+        }
+    }
+}
+
+impl HostMonotonicClock for LiveMonotonicClock {
+    fn resolution(&self) -> u64 {
+        1
+    }
+
+    fn now(&self) -> u64 {
+        u64::try_from(self.origin.elapsed().as_nanos()).unwrap_or(u64::MAX)
+    }
+}
+
+/// The clocks the guest observes. A wait it subscribes to passes on the
+/// same clocks: frozen ones never advance, so the wait ends at once.
+#[derive(Clone, Copy)]
+pub(crate) enum Clocks {
+    Frozen,
+    Live(LiveMonotonicClock),
+}
+
+impl Clocks {
+    pub(crate) fn monotonic_now(&self) -> u64 {
+        match self {
+            Self::Frozen => FrozenMonotonicClock.now(),
+            Self::Live(clock) => clock.now(),
+        }
+    }
+
+    pub(crate) fn wall_now(&self) -> u64 {
+        let since_epoch = match self {
+            Self::Frozen => FrozenWallClock.now(),
+            Self::Live(_) => SystemTime::now()
+                .duration_since(UNIX_EPOCH)
+                .unwrap_or(Duration::ZERO),
+        };
+        u64::try_from(since_epoch.as_nanos()).unwrap_or(u64::MAX)
+    }
+
+    /// Whether a wait on these clocks takes host time.
+    pub(crate) fn advances(&self) -> bool {
+        matches!(self, Self::Live(_))
+    }
+}
+
 #[cfg(test)]
 mod tests {
     //! Pin the frozen-clock contract: the guest must observe no real wall

data/crates/kobako-wasmtime/src/cache.rs

@@ -1,8 +1,8 @@
 //! Process-wide caches for the wasmtime `Engine` and compiled
 //! `Module`, plus the on-disk compiled-artifact cache.
 //!
-//! SPEC.md "Code Organization" forbids exposing wasm engine types to
-//! the Host App or downstream gems. To amortise Engine creation and
+//! Wasm engine types stay hidden from the Host App and downstream
+//! gems. To amortise Engine creation and
 //! Module JIT compilation across multiple sandbox constructions, the
 //! driver keeps a process-scope shared Engine and a per-path Module
 //! cache. Both are transparent to frontends, which construct a
@@ -10,21 +10,22 @@
 //!
 //! Across processes, the Cranelift compile cost is amortised by a
 //! best-effort `.cwasm` disk cache keyed by the SHA-256 of the Guest
-//! Binary bytes; every cache failure falls
-//! back to in-process compilation.
+//! Binary bytes and the engine that compiles them; every cache failure
+//! falls back to in-process compilation.
 //!
-//! Concurrency: under Ruby's GVL only one thread can execute Rust code
-//! at a time, so the Mutex is held briefly during HashMap insert/lookup
-//! and serves to satisfy `Sync` bounds rather than to arbitrate real
-//! contention.
+//! Concurrency: the Mutex is held only for the HashMap lookup and insert,
+//! never across a compile, so threads building Drivers at once do not
+//! wait on each other. Two concurrent misses on one path both compile,
+//! and the later insert wins with an equivalent Module.
 
 use std::collections::HashMap;
 use std::fmt::Write as _;
 use std::fs;
+use std::hash::{DefaultHasher, Hash, Hasher};
 use std::path::{Path, PathBuf};
 use std::sync::{Mutex, OnceLock};
 use std::thread;
-use std::time::{Duration, SystemTime};
+use std::time::Duration;
 
 use sha2::{Digest, Sha256};
 use wasmtime::{Config as WtConfig, Engine as WtEngine, Module as WtModule};
@@ -43,21 +44,10 @@ static MODULE_CACHE: OnceLock<Mutex<HashMap<PathBuf, WtModule>>> = OnceLock::new
 /// 10 ms across the whole process).
 const EPOCH_TICK: Duration = Duration::from_millis(10);
 
-/// Return the process-wide wasmtime Engine, building it on first call.
-///
-/// Enables the wasm exceptions proposal so `kobako.wasm` (which uses
-/// `try_table` / `exnref` / `tag` for mruby's setjmp-via-new-EH path)
-/// can be loaded. The mruby wasi build config uses
-/// `-mllvm -wasm-use-legacy-eh=false`, which generates new-style
-/// exception handling instructions in the wasm32 object files;
-/// wasmtime must have the proposal enabled to parse and JIT those
-/// instructions.
-///
-/// Also enables `epoch_interruption(true)` so every Store can install an
-/// `epoch_deadline_callback` for the per-run wall-clock cap
-/// cap. The first call spawns the process-singleton ticker
-/// thread that drives `engine.increment_epoch()` at `EPOCH_TICK`
-/// cadence; subsequent calls reuse the same engine and ticker.
+/// The exceptions proposal is on because the mruby wasi build emits
+/// new-style exception handling (`-mllvm -wasm-use-legacy-eh=false`) for
+/// its setjmp path. Epoch interruption backs the wall-clock cap, driven by
+/// one process-wide ticker thread.
 pub(crate) fn shared_engine() -> Result<&'static WtEngine, SetupError> {
     if let Some(engine) = SHARED_ENGINE.get() {
         return Ok(engine);
@@ -72,11 +62,6 @@ pub(crate) fn shared_engine() -> Result<&'static WtEngine, SetupError> {
     Ok(engine)
 }
 
-/// Spawn the process-singleton epoch ticker. The thread holds a clone of
-/// the shared Engine (`wasmtime::Engine` is reference-counted internally)
-/// and ticks the epoch counter at `EPOCH_TICK` cadence. Idempotent
-/// across reentrant calls to `shared_engine` because `OnceLock`
-/// gates the spawn.
 fn spawn_epoch_ticker(engine: WtEngine) {
     static TICKER_SPAWNED: OnceLock<()> = OnceLock::new();
     TICKER_SPAWNED.get_or_init(|| {
@@ -90,11 +75,8 @@ fn spawn_epoch_ticker(engine: WtEngine) {
     });
 }
 
-/// Look up `path` in the per-path Module cache, compiling and inserting
-/// the artifact on a miss. Returns `SetupError::ModuleNotBuilt`
-/// (boundary → `Kobako::ModuleNotBuiltError`) when the file is missing —
-/// the headline error for the common pre-build state on a fresh clone
-/// before `rake compile`.
+/// A missing file answers `SetupError::ModuleNotBuilt`, the common state of
+/// a fresh clone before `rake compile`.
 pub(crate) fn cached_module(path: &Path) -> Result<WtModule, SetupError> {
     let cache = MODULE_CACHE.get_or_init(|| Mutex::new(HashMap::new()));
 
@@ -109,7 +91,7 @@ pub(crate) fn cached_module(path: &Path) -> Result<WtModule, SetupError> {
 
     if !path.exists() {
         return Err(SetupError::ModuleNotBuilt(format!(
-            "Sandbox runtime not found at {}; run `bundle exec rake wasm:build` to build it",
+            "Sandbox runtime not found at {}",
             path.display()
         )));
     }
@@ -121,7 +103,7 @@ pub(crate) fn cached_module(path: &Path) -> Result<WtModule, SetupError> {
         ))
     })?;
     let engine = shared_engine()?;
-    let artifact = artifact_path(&bytes);
+    let artifact = artifact_path(engine, &bytes);
     let module = match artifact.as_deref().and_then(|p| load_artifact(engine, p)) {
         Some(module) => module,
         None => {
@@ -143,81 +125,120 @@ pub(crate) fn cached_module(path: &Path) -> Result<WtModule, SetupError> {
 /// Retention window for unused cache entries. A hit refreshes the
 /// artifact's mtime, so only entries no process has loaded for the
 /// whole window are removed by `prune_stale`.
+#[cfg(unix)]
 const ARTIFACT_TTL: Duration = Duration::from_secs(30 * 24 * 60 * 60);
 
-/// Compute the disk-cache location for a Guest Binary's compiled
-/// artifact: `$XDG_CACHE_HOME/kobako` (falling back to
-/// `~/.cache/kobako`) `/<sha256 of the wasm bytes>-<crate version>.cwasm`.
-/// Content addressing makes a rebuilt Guest Binary a new cache entry
-/// rather than an invalidation problem; the crate-version segment keeps
-/// two installed kobako-wasmtime versions (each pinning its own
-/// wasmtime) from sharing a key and recompile-thrashing each other's
-/// entry. wasmtime
-/// itself rejects an artifact produced by an incompatible wasmtime
-/// version or Config at deserialize time. Returns `None` when no home
-/// directory is available — the caller then just compiles in-process.
-fn artifact_path(wasm_bytes: &[u8]) -> Option<PathBuf> {
+/// Content addressing makes a rebuilt Guest Binary a new entry rather than
+/// an invalidation problem. The engine segment names the wasmtime release
+/// and Config that compiled the artifact, because wasmtime's own
+/// deserialize check compares only the major version: without it, an
+/// artifact from a release with a since-fixed miscompile would load
+/// under the patched one.
+fn artifact_path(engine: &WtEngine, wasm_bytes: &[u8]) -> Option<PathBuf> {
     let base = std::env::var_os("XDG_CACHE_HOME")
         .map(PathBuf::from)
         .or_else(|| std::env::var_os("HOME").map(|home| PathBuf::from(home).join(".cache")))?;
     let digest = Sha256::digest(wasm_bytes);
-    let mut name = String::with_capacity(80);
+    let mut name = String::with_capacity(96);
     for byte in digest {
         let _ = write!(name, "{:02x}", byte);
     }
-    let _ = write!(name, "-{}.cwasm", env!("CARGO_PKG_VERSION"));
+    let _ = write!(name, "-{:016x}.cwasm", engine_key(engine));
     Some(base.join("kobako").join(name))
 }
 
-/// Best-effort load of a previously serialized compiled artifact.
-/// Any failure — absent file, truncated bytes, wasmtime version or
-/// Config mismatch — returns `None` and the caller recompiles. A hit
-/// refreshes the file's mtime so `prune_stale`'s retention window
-/// measures time since last use, not since creation.
+/// wasmtime's hash of everything an artifact's compatibility depends on,
+/// its full release version included. `DefaultHasher::new` is unseeded,
+/// so every process of one build derives the same key.
+fn engine_key(engine: &WtEngine) -> u64 {
+    let mut hasher = DefaultHasher::new();
+    engine.precompile_compatibility_hash().hash(&mut hasher);
+    hasher.finish()
+}
+
+/// A hit refreshes the file's mtime, so the retention window measures time
+/// since last use rather than since creation.
+#[cfg(unix)]
 fn load_artifact(engine: &WtEngine, artifact: &Path) -> Option<WtModule> {
-    if !artifact.exists() || !artifact.parent().is_some_and(dir_is_private) {
-        return None;
-    }
-    // SAFETY: `Module::deserialize_file` trusts the artifact bytes.
-    // `dir_is_private` just verified the cache directory is owned by
-    // the current user and writable by no one else, so only files this
-    // module wrote are loaded, addressed by the content hash of the
-    // Guest Binary being constructed — the artifact carries exactly
-    // the trust of `data/kobako.wasm`.
-    let module = unsafe { WtModule::deserialize_file(engine, artifact) }.ok()?;
-    let _ = fs::File::options()
-        .append(true)
-        .open(artifact)
-        .and_then(|f| f.set_modified(SystemTime::now()));
-    Some(module)
+    use rustix::fs::{openat, Mode, OFlags};
+    let dir = open_private_dir(artifact.parent()?)?;
+    let flags = OFlags::RDONLY | OFlags::NOFOLLOW | OFlags::CLOEXEC;
+    let file = fs::File::from(openat(&dir, artifact.file_name()?, flags, Mode::empty()).ok()?);
+    let _ = file.set_modified(std::time::SystemTime::now());
+    // SAFETY: `Module::deserialize_open_file` trusts the artifact bytes
+    // and needs them unchanged while the Module lives. The file was
+    // opened through the directory `open_private_dir` checked, which only
+    // the current user can write, so it is an artifact this module
+    // stored, addressed by the content hash of the Guest Binary being
+    // constructed — it carries exactly that binary's trust.
+    unsafe { WtModule::deserialize_open_file(engine, file) }.ok()
 }
 
-/// Best-effort write of a freshly compiled artifact. The temp-file +
-/// rename pair keeps concurrent processes from observing a partial
-/// write; every failure is swallowed because the cache is purely an
-/// optimisation. A successful write also triggers `prune_stale` so the
-/// cache directory cannot grow without bound across Guest Binary
-/// rebuilds.
+/// The temp-file and rename pair keeps concurrent processes from observing
+/// a partial write, and syncing the bytes before the rename keeps a crash
+/// from leaving the artifact's name over blocks never written, which the
+/// unsafe deserialize would trust. Failures are swallowed because the
+/// cache is only an optimisation, and pruning on write keeps the
+/// directory bounded across rebuilds.
+#[cfg(unix)]
 fn store_artifact(module: &WtModule, artifact: &Path) {
+    use rustix::fs::{fsync, renameat};
+    use std::io::Write as _;
+    let (Some(dir), Some(name)) = (artifact.parent(), artifact.file_name()) else {
+        return;
+    };
     let Ok(bytes) = module.serialize() else {
         return;
     };
-    let Some(dir) = artifact.parent() else { return };
-    if create_cache_dir(dir).is_err() || !dir_is_private(dir) {
+    if create_cache_dir(dir).is_err() {
         return;
     }
-    let tmp = artifact.with_extension(format!("tmp{}", std::process::id()));
-    if fs::write(&tmp, bytes).is_err() {
+    let Some(dir) = open_private_dir(dir) else {
+        return;
+    };
+    let Some((tmp, mut file)) = create_temp(&dir, name) else {
+        return;
+    };
+    if file
+        .write_all(&bytes)
+        .and_then(|()| file.sync_all())
+        .is_err()
+    {
         return;
     }
-    if fs::rename(&tmp, artifact).is_ok() {
-        prune_stale(dir, artifact);
+    if renameat(&dir, &tmp, &dir, name).is_ok() {
+        let _ = fsync(&dir);
+        prune_stale(&dir, name);
     }
 }
 
-/// Create the cache directory owner-only (`0700`) on Unix so no other
-/// local user can plant an artifact the unsafe deserialize would
-/// trust; elsewhere fall back to default permissions.
+/// A temp file no other writer shares: two threads of one process storing
+/// the same artifact at once would otherwise write into one file, and a
+/// reader could load the interleaved bytes the unsafe deserialize trusts.
+#[cfg(unix)]
+fn create_temp(dir: &rustix::fd::OwnedFd, name: &std::ffi::OsStr) -> Option<(PathBuf, fs::File)> {
+    use rustix::fs::{openat, Mode, OFlags};
+    use std::sync::atomic::{AtomicU64, Ordering};
+    static NEXT_TEMP: AtomicU64 = AtomicU64::new(0);
+    let serial = NEXT_TEMP.fetch_add(1, Ordering::Relaxed);
+    let tmp = Path::new(name).with_extension(format!("tmp{}.{serial}", std::process::id()));
+    let flags = OFlags::WRONLY | OFlags::CREATE | OFlags::EXCL | OFlags::NOFOLLOW | OFlags::CLOEXEC;
+    let fd = openat(dir, &tmp, flags, Mode::RUSR | Mode::WUSR).ok()?;
+    Some((tmp, fs::File::from(fd)))
+}
+
+/// The disk cache trusts its directory's owner, which only Unix reports,
+/// so elsewhere every process compiles the Guest Binary itself.
+#[cfg(not(unix))]
+fn load_artifact(_engine: &WtEngine, _artifact: &Path) -> Option<WtModule> {
+    None
+}
+
+#[cfg(not(unix))]
+fn store_artifact(_module: &WtModule, _artifact: &Path) {}
+
+/// Create the cache directory owner-only (`0700`) so no other local user
+/// can plant an artifact the unsafe deserialize would trust.
 #[cfg(unix)]
 fn create_cache_dir(dir: &Path) -> std::io::Result<()> {
     use std::os::unix::fs::DirBuilderExt;
@@ -227,61 +248,117 @@ fn create_cache_dir(dir: &Path) -> std::io::Result<()> {
         .create(dir)
 }
 
-#[cfg(not(unix))]
-fn create_cache_dir(dir: &Path) -> std::io::Result<()> {
-    fs::create_dir_all(dir)
-}
-
-/// Returns whether the cache directory upholds the trust the unsafe
-/// deserialize relies on: owned by the current effective user and
-/// writable by no one else. A pre-existing directory another user owns
-/// or can write to — e.g. under a shared `XDG_CACHE_HOME` — fails here
-/// and both disk-cache tiers are skipped.
+/// The cache directory as one descriptor, once it upholds the trust the
+/// unsafe deserialize relies on: a directory rather than a link in its
+/// place, owned by the current effective user and writable by no one
+/// else. Every later step goes through the descriptor, so a path swapped
+/// after the check reaches nothing. One that fails — another user's,
+/// under a shared `XDG_CACHE_HOME`, say — skips both disk-cache tiers.
 #[cfg(unix)]
-fn dir_is_private(dir: &Path) -> bool {
-    use std::os::unix::fs::MetadataExt;
-    let Ok(meta) = fs::metadata(dir) else {
-        return false;
-    };
-    // SAFETY: `geteuid` reads process state and has no preconditions.
-    meta.uid() == unsafe { libc::geteuid() } && meta.mode() & 0o022 == 0
-}
-
-#[cfg(not(unix))]
-fn dir_is_private(_dir: &Path) -> bool {
-    true
+fn open_private_dir(dir: &Path) -> Option<rustix::fd::OwnedFd> {
+    use rustix::fs::{fstat, open, Mode, OFlags};
+    let flags = OFlags::RDONLY | OFlags::DIRECTORY | OFlags::NOFOLLOW | OFlags::CLOEXEC;
+    let fd = open(dir, flags, Mode::empty()).ok()?;
+    let stat = fstat(&fd).ok()?;
+    let owned = stat.st_uid == rustix::process::geteuid().as_raw();
+    (owned && stat.st_mode & 0o022 == 0).then_some(fd)
 }
 
-/// Remove every cache entry (`.cwasm` artifacts and crash-leftover
-/// `.tmp*` files) whose mtime sits past `ARTIFACT_TTL`, except the
-/// just-written `keep`. Live temp files are seconds old and never
-/// qualify; foreign file names are left untouched.
-fn prune_stale(dir: &Path, keep: &Path) {
-    let Ok(entries) = fs::read_dir(dir) else {
+/// Live temp files are seconds old and never qualify; foreign file names
+/// are left untouched.
+#[cfg(unix)]
+fn prune_stale(dir: &rustix::fd::OwnedFd, keep: &std::ffi::OsStr) {
+    use rustix::fs::{statat, unlinkat, AtFlags, Dir};
+    use std::os::unix::ffi::OsStrExt;
+    use std::time::{SystemTime, UNIX_EPOCH};
+    let Ok(mut entries) = Dir::read_from(dir) else {
         return;
     };
-    for entry in entries.flatten() {
-        let path = entry.path();
-        if path == keep || !cache_entry_name(&path) {
+    while let Some(Ok(entry)) = entries.read() {
+        let name = entry.file_name();
+        if name.to_bytes() == keep.as_bytes() || !name.to_str().is_ok_and(cache_entry_name) {
             continue;
         }
-        let stale = entry
-            .metadata()
-            .and_then(|meta| meta.modified())
+        let stale = statat(dir, name, AtFlags::SYMLINK_NOFOLLOW)
             .ok()
-            .and_then(|mtime| mtime.elapsed().ok())
+            .and_then(|stat| u64::try_from(stat.st_mtime).ok())
+            .and_then(|secs| {
+                SystemTime::now()
+                    .duration_since(UNIX_EPOCH + Duration::from_secs(secs))
+                    .ok()
+            })
             .is_some_and(|age| age > ARTIFACT_TTL);
         if stale {
-            let _ = fs::remove_file(&path);
+            let _ = unlinkat(dir, name, AtFlags::empty());
         }
     }
 }
 
-/// Returns whether `path` carries a file name this cache wrote — a
-/// `.cwasm` artifact or a `.tmp*` leftover.
-fn cache_entry_name(path: &Path) -> bool {
-    let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
-        return false;
-    };
+#[cfg(unix)]
+fn cache_entry_name(name: &str) -> bool {
     name.ends_with(".cwasm") || name.contains(".tmp")
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use wasmtime::ModuleVersionStrategy;
+
+    fn engine_with(version: &str) -> WtEngine {
+        let mut config = WtConfig::new();
+        config
+            .module_version(ModuleVersionStrategy::Custom(version.into()))
+            .expect("a short version string is accepted");
+        WtEngine::new(&config).expect("engine")
+    }
+
+    fn entry_name(engine: &WtEngine) -> PathBuf {
+        let path = artifact_path(engine, b"\0asm").expect("a cache root");
+        PathBuf::from(path.file_name().expect("an entry name"))
+    }
+
+    // A custom module version stands in for another wasmtime release:
+    // wasmtime's compatibility hash covers its full version the same way.
+    // @behavior RT-108
+    #[test]
+    fn an_artifact_from_another_engine_release_is_never_the_entry_read() {
+        assert_ne!(
+            entry_name(&engine_with("49.0.3")),
+            entry_name(&engine_with("49.0.4")),
+            "a Guest Binary cached by one engine release must not be the entry another release reads"
+        );
+    }
+
+    // Two writers in one process take temp files in turn; each must get a
+    // file of its own rather than reopen the other's.
+    // @behavior RT-113
+    #[cfg(unix)]
+    #[test]
+    fn two_writers_of_one_artifact_never_share_a_temp_file() {
+        let root = std::env::temp_dir().join(format!("kobako-temp-{}", std::process::id()));
+        create_cache_dir(&root).expect("a scratch directory");
+        let dir = open_private_dir(&root).expect("a private directory");
+        let name = std::ffi::OsStr::new("entry.cwasm");
+        let first = create_temp(&dir, name).map(|(path, _)| path);
+        let second = create_temp(&dir, name).map(|(path, _)| path);
+        fs::remove_dir_all(&root).expect("the scratch directory removed");
+        let (first, second) = (
+            first.expect("a temp file"),
+            second.expect("a second temp file"),
+        );
+        assert_ne!(
+            first, second,
+            "two stores of one artifact in one process must each write a temp file of their own"
+        );
+    }
+
+    // @behavior RT-108
+    #[test]
+    fn engines_of_one_release_and_config_share_the_entry() {
+        assert_eq!(
+            entry_name(&engine_with("49.0.4")),
+            entry_name(&engine_with("49.0.4")),
+            "two engines of one release and Config must read the entry either of them cached"
+        );
+    }
+}

data/crates/kobako-wasmtime/src/capture.rs

@@ -7,10 +7,8 @@
 //! channel) so a regression that only breaks one channel cannot sneak
 //! through the test that pins them.
 
-/// Translate a per-channel byte cap into the MemoryOutputPipe capacity:
-/// `cap + 1` (saturated against `usize::MAX`) when a cap is set so the
-/// "wrote exactly cap" and "exceeded cap" cases stay distinguishable;
-/// `usize::MAX` when the channel is uncapped.
+/// One byte past the cap, so "wrote exactly cap" and "exceeded cap" stay
+/// distinguishable.
 pub(crate) fn pipe_capacity(cap: Option<usize>) -> usize {
     match cap {
         Some(c) => c.saturating_add(1),
@@ -18,13 +16,8 @@ pub(crate) fn pipe_capacity(cap: Option<usize>) -> usize {
     }
 }
 
-/// Pure clipping core shared by the snapshot readback: given the
-/// unclipped pipe snapshot (owned — truncated in place, so the readback
-/// costs one copy out of the pipe, not two), return the bytes Ruby
-/// should observe plus the truncation flag. `truncated` is `true` only
-/// when the snapshot strictly exceeded the cap — this is the "wrote
-/// `cap + 1` bytes into a `cap + 1`-sized pipe" case; "wrote exactly
-/// `cap` bytes" stays `false`.
+/// Takes the snapshot by value and truncates in place, so the readback
+/// costs one copy out of the pipe rather than two.
 pub(crate) fn clip_capture(mut raw: Vec<u8>, cap: Option<usize>) -> (Vec<u8>, bool) {
     match cap {
         Some(c) if raw.len() > c => {