kobako 0.28.0 → 0.30.0

data/crates/kobako-runtime/src/endpoint/invoke.rs

@@ -0,0 +1,194 @@
+//! Per-invocation I/O between the host and the guest: it frames what the guest
+//! is handed, writes the entry's downcall into a freshly allocated guest buffer,
+//! and reads the Outcome the downcall answered with.
+
+use kobako_transport::abi::FRAME_LEN_SIZE;
+use kobako_transport::envelope::{CompileReply, Downcall, Outcome, Preamble, Run, Snippet};
+
+use super::buffer::{
+    alloc_and_write, checked_payload_len, read_buffer, unpack_guest_buffer, ReadError, WriteError,
+};
+use super::{GuestInstance, SANDBOX_RUNTIME_NOT_KOBAKO};
+use crate::error::{InvokeError, SetupError, Trap};
+use crate::runtime::Entry;
+
+/// What the guest reads from stdin: the Preamble behind its length prefix. It
+/// carries the same 16 MiB cap as a downcall request: past it, the prefix
+/// would silently wrap.
+pub fn stdin_content(preamble: &Preamble) -> Result<Vec<u8>, &'static str> {
+    let preamble = preamble.encode();
+    checked_payload_len(preamble.len())?;
+    let mut content = Vec::with_capacity(FRAME_LEN_SIZE + preamble.len());
+    content.extend_from_slice(&(preamble.len() as u32).to_be_bytes());
+    content.extend_from_slice(&preamble);
+    Ok(content)
+}
+
+/// The downcall `entry` is.
+pub fn request_of(entry: Entry<'_>) -> Vec<u8> {
+    match entry {
+        Entry::Eval { source } => Downcall::Eval(source.to_vec()),
+        Entry::Run {
+            entrypoint,
+            payload,
+        } => Downcall::Run(Run {
+            entrypoint: entrypoint.to_owned(),
+            payload,
+        }),
+    }
+    .encode()
+}
+
+/// The downcall that asks the guest to compile its Preamble.
+pub fn compile_request() -> Vec<u8> {
+    Downcall::Compile.encode()
+}
+
+/// Write a request into a guest buffer, answering where. A missing or trapping
+/// allocator is an engine fault, a `Trap`; one that runs but returns 0 leaves
+/// the runtime intact, so it is a `SetupError`.
+pub fn write_request<G: GuestInstance>(
+    guest: &mut G,
+    envelope: &[u8],
+) -> Result<(i32, i32), InvokeError> {
+    let trap = |message: String| -> InvokeError { Trap::Other(message).into() };
+    let ptr = alloc_and_write(guest, envelope).map_err(|err| match err {
+        WriteError::OutOfMemory => {
+            SetupError::Intact("could not allocate input buffer (out of memory)".to_string()).into()
+        }
+        WriteError::TooLarge => trap("payload exceeds the 16 MiB limit".to_string()),
+        WriteError::Incompatible(message) => trap(message.to_string()),
+        WriteError::Trapped(e) => G::cap_trap(&e)
+            .unwrap_or_else(|| Trap::Other(format!("failed to allocate input buffer: {e}")))
+            .into(),
+        WriteError::OutOfBounds => {
+            trap("the input buffer lies outside the Sandbox's memory".to_string())
+        }
+    })?;
+    // The write has already held the length to the payload cap.
+    Ok((ptr as i32, envelope.len() as i32))
+}
+
+/// A guest that answered without an Outcome the envelope can frame — an
+/// empty answer included — has nothing left to attribute, so it is a
+/// `Trap` like every other way of failing to read the result.
+pub fn read_outcome<G: GuestInstance>(guest: &mut G, packed: u64) -> Result<Outcome, Trap> {
+    let bytes = read_answer(guest, packed)?;
+    Outcome::decode(&bytes).map_err(|_| {
+        Trap::Other(
+            if bytes.is_empty() {
+                "Sandbox exited without producing a result"
+            } else {
+                "Sandbox produced an unrecognised result"
+            }
+            .to_string(),
+        )
+    })
+}
+
+/// Held to the same 16 MiB bound as an Outcome; an answer that does not
+/// frame is a `Trap` the caller treats like any other failed compile.
+pub fn read_compile_reply<G: GuestInstance>(
+    guest: &mut G,
+    packed: u64,
+) -> Result<CompileReply, Trap> {
+    let bytes = read_answer(guest, packed)?;
+    CompileReply::decode(&bytes)
+        .map_err(|_| Trap::Other("Sandbox produced an unrecognised compile answer".to_string()))
+}
+
+fn read_answer<G: GuestInstance>(guest: &mut G, packed: u64) -> Result<Vec<u8>, Trap> {
+    let memory = guest
+        .memory()
+        .ok_or_else(|| Trap::Other(SANDBOX_RUNTIME_NOT_KOBAKO.to_string()))?;
+    let (ptr, len) = unpack_guest_buffer(packed);
+    read_buffer(memory, ptr, len).map_err(|err| {
+        Trap::Other(
+            match err {
+                ReadError::TooLarge => "result payload exceeds the 16 MiB limit",
+                ReadError::OutOfBounds => "the Sandbox result is out of bounds",
+            }
+            .to_string(),
+        )
+    })
+}
+
+/// What a compile answered, to replay in place of `preamble`'s source
+/// snippets, or `None` where nothing can be replayed.
+pub fn compiled_bytecodes(preamble: &Preamble, reply: CompileReply) -> Option<Vec<Vec<u8>>> {
+    match reply {
+        CompileReply::Ok(bytecodes) => {
+            one_per_source(preamble, bytecodes).filter(|bytecodes| replay_fits(preamble, bytecodes))
+        }
+        CompileReply::Error(_) | CompileReply::Unsupported(_) => None,
+    }
+}
+
+/// Each invocation sends the Preamble with every bytecode in place of its
+/// source, so an answer that would carry it past the payload cap would trap
+/// every invocation the source alone fits.
+fn replay_fits(preamble: &Preamble, bytecodes: &[Vec<u8>]) -> bool {
+    let mut replay = preamble.clone();
+    let sources = replay
+        .snippets
+        .entries
+        .iter_mut()
+        .filter(|entry| matches!(entry, Snippet::Source { .. }));
+    for (entry, body) in sources.zip(bytecodes) {
+        *entry = Snippet::Bytecode { body: body.clone() };
+    }
+    checked_payload_len(replay.encode().len()).is_ok()
+}
+
+/// A frontend replays each bytecode in place of one source snippet, in
+/// order, so an answer of any other length leaves nothing to replay.
+fn one_per_source(preamble: &Preamble, bytecodes: Vec<Vec<u8>>) -> Option<Vec<Vec<u8>>> {
+    let sources = preamble
+        .snippets
+        .entries
+        .iter()
+        .filter(|entry| matches!(entry, Snippet::Source { .. }))
+        .count();
+    (bytecodes.len() == sources).then_some(bytecodes)
+}
+
+#[cfg(test)]
+mod tests {
+    use kobako_transport::envelope::Snippets;
+
+    use super::*;
+
+    /// One source between two bytecode snippets: a compile answers one
+    /// bytecode for it.
+    fn one_source() -> Preamble {
+        let mut preamble = Preamble::default();
+        preamble.snippets = Snippets {
+            entries: vec![
+                Snippet::Bytecode { body: vec![0xaa] },
+                Snippet::Source {
+                    name: "Only".into(),
+                    body: "1".into(),
+                },
+                Snippet::Bytecode { body: vec![0xbb] },
+            ],
+        };
+        preamble
+    }
+
+    // @behavior WE-089
+    #[test]
+    fn a_compiled_answer_of_another_length_leaves_nothing_compiled() {
+        let preamble = one_source();
+
+        assert_eq!(
+            [
+                one_per_source(&preamble, Vec::new()),
+                one_per_source(&preamble, vec![vec![0x01], vec![0x02]]),
+                one_per_source(&preamble, vec![vec![0x01]]),
+            ],
+            [None, None, Some(vec![vec![0x01]])],
+            "a compiled answer through Driver#compile must be kept only when it carries one \
+             bytecode per source snippet"
+        );
+    }
+}

data/crates/kobako-runtime/src/endpoint/memory_cap.rs

@@ -0,0 +1,238 @@
+//! The per-invocation memory cap: only the growth past the linear-memory size
+//! captured at invocation entry is charged, so the image's initial allocation
+//! is outside the budget.
+
+/// The budget one invocation's memory grows against.
+///
+/// `memory_limit` bounds per-invocation growth (`None` disables it).
+/// `baseline` is the linear-memory size captured at invocation entry by
+/// `MemoryCap::activate`; only the growth past `baseline` is charged against
+/// `memory_limit`, so the mruby image's initial allocation and any high-water
+/// mark left by prior invocations on the same Sandbox do not consume the
+/// budget. An Engine also asks about the module's declared initial allocation
+/// at instantiation time, so the cap stays dormant until `MemoryCap::activate`
+/// arms it for one invocation.
+#[derive(Debug, Clone, Copy)]
+pub struct MemoryCap {
+    memory_limit: Option<usize>,
+    baseline: usize,
+    cap_active: bool,
+    peak: usize,
+}
+
+impl MemoryCap {
+    pub fn new(memory_limit: Option<usize>) -> Self {
+        Self {
+            memory_limit,
+            baseline: 0,
+            cap_active: false,
+            peak: 0,
+        }
+    }
+
+    /// The cap stays dormant until armed, because the module's declared
+    /// initial memory is allocated during instantiation and must pass.
+    pub fn activate(&mut self, baseline: usize) {
+        self.baseline = baseline;
+        self.cap_active = true;
+        self.peak = 0;
+    }
+
+    pub fn deactivate(&mut self) {
+        self.cap_active = false;
+    }
+
+    /// A grow the cap rejects never updates the peak, so the reported value
+    /// never exceeds `memory_limit`.
+    pub fn peak(&self) -> usize {
+        self.peak
+    }
+
+    /// Charge a growth to `desired` bytes, refusing one past `memory_limit`.
+    pub fn charge(&mut self, desired: usize) -> Result<(), MemoryLimitExceeded> {
+        if !self.cap_active {
+            return Ok(());
+        }
+        let delta = desired.saturating_sub(self.baseline);
+        if let Some(limit) = self.memory_limit {
+            if delta > limit {
+                return Err(MemoryLimitExceeded::new(desired, limit));
+            }
+        }
+        if delta > self.peak {
+            self.peak = delta;
+        }
+        Ok(())
+    }
+}
+
+/// A growth past the per-invocation memory cap. An Engine ends the invocation
+/// with it, and a Wasm Driver finds it again to classify the failure as a
+/// memory-limit `Trap`. Callers use the `Display` impl below — no field is
+/// read directly — so the inner state stays private.
+#[derive(Debug)]
+pub struct MemoryLimitExceeded {
+    desired: usize,
+    limit: usize,
+}
+
+impl MemoryLimitExceeded {
+    pub fn new(desired: usize, limit: usize) -> Self {
+        Self { desired, limit }
+    }
+}
+
+impl std::fmt::Display for MemoryLimitExceeded {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "memory usage exceeded memory_limit: \
+             requested={} bytes, limit={} bytes",
+            self.desired, self.limit
+        )
+    }
+}
+
+impl std::error::Error for MemoryLimitExceeded {}
+
+#[cfg(test)]
+mod tests {
+    //! The pure delta arithmetic, so a regression that breaks the baseline
+    //! accounting (dropping the `baseline` subtraction, or letting `activate`
+    //! carry stale state across invocations) is caught without an Engine.
+    use super::MemoryCap;
+
+    fn assert_charged(cap: &mut MemoryCap, desired: usize, what: &str) {
+        assert!(
+            cap.charge(desired).is_ok(),
+            "{what} through MemoryCap::charge must be allowed"
+        );
+    }
+
+    fn assert_refused(cap: &mut MemoryCap, desired: usize, what: &str) {
+        assert!(
+            cap.charge(desired).is_err(),
+            "{what} through MemoryCap::charge must be refused"
+        );
+    }
+
+    // @behavior S-113
+    #[test]
+    fn a_growth_before_the_cap_is_armed_is_not_bounded() {
+        let mut cap = MemoryCap::new(Some(1 << 20));
+        assert_charged(&mut cap, 100 << 20, "a 100 MiB growth before activate");
+    }
+
+    // @behavior S-114
+    #[test]
+    fn a_growth_within_the_limit_is_allowed() {
+        let mut cap = MemoryCap::new(Some(1 << 20));
+        cap.activate(2 << 20);
+        assert_charged(
+            &mut cap,
+            (2 << 20) + (1 << 19),
+            "a 512 KiB growth past a 2 MiB baseline under a 1 MiB limit",
+        );
+    }
+
+    // @behavior S-121
+    #[test]
+    fn a_growth_past_the_limit_is_refused() {
+        let mut cap = MemoryCap::new(Some(1 << 20));
+        cap.activate(2 << 20);
+        assert_refused(
+            &mut cap,
+            4 << 20,
+            "a 2 MiB growth past a 2 MiB baseline under a 1 MiB limit",
+        );
+    }
+
+    // @behavior S-008
+    #[test]
+    fn each_activation_charges_from_its_own_baseline() {
+        let mut cap = MemoryCap::new(Some(1 << 20));
+        cap.activate(2 << 20);
+        assert_charged(&mut cap, 3 << 20, "a 1 MiB growth in the first invocation");
+        cap.activate(3 << 20);
+        assert_charged(
+            &mut cap,
+            4 << 20,
+            "a 1 MiB growth in the second invocation, past the first one's residue",
+        );
+    }
+
+    // @behavior S-009
+    #[test]
+    fn a_cap_without_a_limit_allows_any_growth() {
+        let mut cap = MemoryCap::new(None);
+        cap.activate(0);
+        assert_charged(&mut cap, 100 << 20, "a 100 MiB growth with no limit");
+    }
+
+    // @behavior S-116
+    #[test]
+    fn the_peak_is_zero_before_any_growth() {
+        let cap = MemoryCap::new(Some(1 << 20));
+        assert_eq!(
+            cap.peak(),
+            0,
+            "a new cap through MemoryCap::peak must report 0"
+        );
+    }
+
+    // @behavior S-115
+    #[test]
+    fn the_peak_is_the_highest_growth_past_the_baseline() {
+        let mut cap = MemoryCap::new(Some(1 << 20));
+        cap.activate(2 << 20);
+        assert_charged(&mut cap, (2 << 20) + (1 << 18), "a 256 KiB growth");
+        assert_charged(&mut cap, (2 << 20) + (1 << 19), "a 512 KiB growth");
+        assert_charged(&mut cap, (2 << 20) + (1 << 17), "a 128 KiB growth");
+        assert_eq!(
+            cap.peak(),
+            1 << 19,
+            "growths of 256, 512, and 128 KiB through MemoryCap::peak must report 512 KiB"
+        );
+    }
+
+    // @behavior S-062
+    #[test]
+    fn a_refused_growth_leaves_the_peak_alone() {
+        let mut cap = MemoryCap::new(Some(1 << 20));
+        cap.activate(2 << 20);
+        assert_charged(&mut cap, (2 << 20) + (1 << 19), "a 512 KiB growth");
+        assert_refused(&mut cap, 4 << 20, "a 2 MiB growth under a 1 MiB limit");
+        assert_eq!(
+            cap.peak(),
+            1 << 19,
+            "a refused 2 MiB growth through MemoryCap::peak must leave 512 KiB reported"
+        );
+    }
+
+    // @behavior S-117
+    #[test]
+    fn each_activation_resets_the_peak() {
+        let mut cap = MemoryCap::new(Some(1 << 20));
+        cap.activate(2 << 20);
+        assert_charged(&mut cap, (2 << 20) + (1 << 19), "a 512 KiB growth");
+        cap.activate(3 << 20);
+        assert_eq!(
+            cap.peak(),
+            0,
+            "a second activate through MemoryCap::peak must report 0"
+        );
+    }
+
+    // @behavior S-118
+    #[test]
+    fn a_cap_without_a_limit_still_reports_its_peak() {
+        let mut cap = MemoryCap::new(None);
+        cap.activate(1 << 20);
+        assert_charged(&mut cap, 5 << 20, "a 4 MiB growth with no limit");
+        assert_eq!(
+            cap.peak(),
+            4 << 20,
+            "a 4 MiB growth with no limit through MemoryCap::peak must report 4 MiB"
+        );
+    }
+}

data/crates/kobako-runtime/src/endpoint.rs

@@ -0,0 +1,166 @@
+//! The host ABI endpoint: everything the kobako ABI asks of a host that no
+//! Engine decides, so a Wasm Driver for any Engine implements `GuestInstance`
+//! over its own memory and exports, and links `__kobako_upcall` to
+//! `dispatch::handle`.
+//!
+//! Only this endpoint and its guest counterpart read or write an envelope's
+//! bytes.
+
+mod buffer;
+mod capture;
+mod dispatch;
+mod invoke;
+mod memory_cap;
+
+use std::fmt::Display;
+
+use kobako_transport::abi::ABI_VERSION;
+
+use crate::error::{SetupError, Trap};
+
+pub use capture::{clip_capture, pipe_capacity};
+pub use dispatch::{handle, Calls, UpcallEnd, ABANDONED};
+pub use invoke::{
+    compile_request, compiled_bytecodes, read_compile_reply, read_outcome, request_of,
+    stdin_content, write_request,
+};
+pub use memory_cap::{MemoryCap, MemoryLimitExceeded};
+
+/// For a required guest export that is absent or mistyped, wherever it is
+/// looked up. Names neither the export nor a frontend's artifact path;
+/// what a caller can do is rebuild the runtime.
+pub const RUNTIME_INCOMPATIBLE: &str =
+    "the Sandbox runtime is incompatible; rebuild it against the kobako version in use";
+
+/// Accept a Guest Binary only when the ABI version it reports is the host's;
+/// `None` means it exports none. Only rebuilding the artifact fixes either
+/// refusal, so both are `Dead` and say so.
+pub fn verify_abi_version(reported: Option<u32>) -> Result<(), SetupError> {
+    match reported {
+        None => Err(SetupError::Dead(format!(
+            "the Guest Binary does not export __kobako_abi_version; \
+             rebuild it against ABI version {ABI_VERSION}"
+        ))),
+        Some(version) if version != ABI_VERSION => Err(SetupError::Dead(format!(
+            "the Guest Binary reports ABI version {version}, but this host \
+             implements ABI version {ABI_VERSION}; rebuild the Guest Binary \
+             against the host's version"
+        ))),
+        Some(_) => Ok(()),
+    }
+}
+
+/// For the "the loaded Wasm module is not a Kobako-shaped runtime at all"
+/// failure mode, such as an instance with no `memory` export.
+const SANDBOX_RUNTIME_NOT_KOBAKO: &str =
+    "the loaded Wasm module is not a Kobako-compatible runtime";
+
+/// One guest instance as the endpoint drives it: what a Wasm Driver gives it of an
+/// Engine, from the invocation body and from inside `__kobako_upcall` alike.
+/// A method answering `None` names an export the module does not have.
+pub trait GuestInstance {
+    /// What a call into the guest raises, kept as it is so an invocation ends
+    /// with its own kind.
+    type Fault: Display;
+
+    /// The state of the Calls open on this instance.
+    fn calls(&mut self) -> &mut Calls<Self::Fault>;
+
+    /// The guest's linear memory.
+    fn memory(&mut self) -> Option<&mut [u8]>;
+
+    /// Allocate `len` bytes through `__kobako_alloc`, answering the address,
+    /// or 0 where the guest has none to give.
+    fn alloc(&mut self, len: u32) -> Option<Result<u32, Self::Fault>>;
+
+    /// Call `__kobako_downcall` with a request at `ptr`, answering the packed
+    /// `(ptr, len)` of its answer.
+    fn downcall(&mut self, ptr: i32, len: i32) -> Option<Result<u64, Self::Fault>>;
+
+    /// The cap `fault` carries, if one of the invocation's caps fired, which
+    /// names itself rather than the step it fired during.
+    fn cap_trap(fault: &Self::Fault) -> Option<Trap>;
+}
+
+#[cfg(test)]
+mod tests {
+    //! Witness that the endpoint needs nothing of an Engine: an instance made
+    //! of a plain buffer drives a whole request and upcall through it.
+    use kobako_transport::abi::unpack_ptr_len;
+    use kobako_transport::envelope::Reply;
+
+    use super::*;
+
+    /// An instance holding a buffer and a bump allocator.
+    struct InMemory {
+        memory: Vec<u8>,
+        next: u32,
+        calls: Calls<String>,
+    }
+
+    impl GuestInstance for InMemory {
+        type Fault = String;
+
+        fn calls(&mut self) -> &mut Calls<String> {
+            &mut self.calls
+        }
+
+        fn memory(&mut self) -> Option<&mut [u8]> {
+            Some(&mut self.memory)
+        }
+
+        fn alloc(&mut self, len: u32) -> Option<Result<u32, String>> {
+            let ptr = self.next;
+            self.next += len;
+            Some(Ok(ptr))
+        }
+
+        fn downcall(&mut self, _ptr: i32, _len: i32) -> Option<Result<u64, String>> {
+            None
+        }
+
+        fn cap_trap(_fault: &String) -> Option<Trap> {
+            None
+        }
+    }
+
+    fn instance() -> InMemory {
+        InMemory {
+            memory: vec![0; 1024],
+            next: 16,
+            calls: Calls::default(),
+        }
+    }
+
+    // @behavior RT-191
+    #[test]
+    fn a_request_lands_in_guest_memory_through_any_instance() {
+        let mut guest = instance();
+        let answered = write_request(&mut guest, b"request").ok();
+        assert_eq!(
+            (answered, &guest.memory[16..23]),
+            (Some((16, 7)), &b"request"[..]),
+            "endpoint::write_request through an instance of a plain buffer must write the \
+             request at the address its allocator answers"
+        );
+    }
+
+    // A tag the host does not serve needs no handler bound to be answered.
+    // @behavior RT-191
+    #[test]
+    fn an_upcall_answers_through_any_instance() {
+        let mut guest = instance();
+        let request = b"not a call";
+        guest.memory[..request.len()].copy_from_slice(request);
+        let packed = handle(&mut guest, 0, request.len() as i32)
+            .ok()
+            .expect("the upcall must answer");
+        let (ptr, len) = unpack_ptr_len(packed as u64);
+        let reply = Reply::decode(&guest.memory[ptr as usize..(ptr + len) as usize]);
+        assert!(
+            matches!(reply, Ok(Reply::Unsupported(_))),
+            "endpoint::handle through an instance of a plain buffer must write the answer to a \
+             request under an unserved tag back into guest memory"
+        );
+    }
+}

data/crates/kobako-runtime/src/filesystem/bind/fid.rs

@@ -0,0 +1,82 @@
+//! The host directories a Bind keeps open, each a descriptor of the host's
+//! own. A dentry holds the one above it, so keeping one for every dentry would
+//! spend a descriptor per level of depth, which no table of a guest's counts.
+//! A directory the guest holds open keeps its own; the rest are kept up to a
+//! bound, the oldest let go and walked to again when asked, as 9p walks to a
+//! dentry it holds no fid for.
+
+use std::num::NonZeroUsize;
+use std::sync::{Arc, Mutex, MutexGuard, PoisonError, Weak};
+
+use cap_std::fs::Dir;
+use lru::LruCache;
+
+use crate::vfs::Dentry;
+
+/// The most directories a Bind keeps open for walks.
+const MAX_CACHED_FIDS: NonZeroUsize = NonZeroUsize::new(64).expect("the bound is not zero");
+
+/// A directory, and the dentry it was walked to for.
+type CachedFid = (Weak<Dentry>, Arc<Dir>);
+
+/// Directories a Bind walked to, by the address of the dentry naming each.
+/// Each entry holds that dentry's allocation, so no other can take its address.
+pub(super) struct FidCache(Mutex<LruCache<usize, CachedFid>>);
+
+impl Default for FidCache {
+    fn default() -> Self {
+        Self(Mutex::new(LruCache::new(MAX_CACHED_FIDS)))
+    }
+}
+
+fn key(dentry: &Dentry) -> usize {
+    std::ptr::from_ref(dentry) as usize
+}
+
+impl FidCache {
+    fn entries(&self) -> MutexGuard<'_, LruCache<usize, CachedFid>> {
+        self.0.lock().unwrap_or_else(PoisonError::into_inner)
+    }
+
+    /// The directory kept for `dentry`, now the most recently asked.
+    pub(super) fn get(&self, dentry: &Dentry) -> Option<Arc<Dir>> {
+        self.entries().get(&key(dentry)).map(|(_, dir)| dir.clone())
+    }
+
+    /// Keep `dir` for `dentry`, letting go of the oldest past the bound.
+    pub(super) fn put(&self, dentry: &Dentry, dir: &Arc<Dir>) {
+        let entry = (Arc::downgrade(&dentry.get()), dir.clone());
+        self.entries().put(key(dentry), entry);
+    }
+
+    /// How many directories are kept.
+    #[cfg(all(test, unix))]
+    pub(super) fn len(&self) -> usize {
+        self.entries().len()
+    }
+}
+
+/// The host directory a guest holds open on a dentry, kept on it for as long
+/// as the guest holds it, as 9p keeps a fid in `d_fsdata`.
+#[derive(Default)]
+pub(super) struct OpenDirFid(Mutex<Weak<Dir>>);
+
+impl OpenDirFid {
+    /// The directory on `dentry`, while a guest holds it open.
+    pub(super) fn get(dentry: &Dentry) -> Option<Arc<Dir>> {
+        let kept = dentry.fsdata().get()?.clone().downcast::<Self>().ok()?;
+        let dir = kept.0.lock().unwrap_or_else(PoisonError::into_inner);
+        dir.upgrade()
+    }
+
+    /// `dir` is held open on `dentry` from now on.
+    pub(super) fn set(dentry: &Dentry, dir: &Arc<Dir>) {
+        let kept = dentry
+            .fsdata()
+            .get_or_init(|| Arc::new(Self::default()))
+            .clone();
+        if let Ok(kept) = kept.downcast::<Self>() {
+            *kept.0.lock().unwrap_or_else(PoisonError::into_inner) = Arc::downgrade(dir);
+        }
+    }
+}