fix(fspy): unify shared memory on a sparse temp file across all platforms (#576)

## Motivation

Codex CLI's and Claude Code's default sandboxes deny the primitives
fspy's Unix shared memory was built on. The macOS Seatbelt profile
denies `shm_open` (#563), and both sandboxes block Unix domain sockets,
which the Linux memfd broker depended on. Plain files in the temp
directory work under both sandboxes; the IPC lock file lives there
today.

This PR replaces all three platform backends with one file-backed
implementation, mapped through `memmap2` on every platform. The API has
three types, each one platform concept:

- `ShmKeeper` is the name. `create` returns it, it carries the
identifier (the backing file's absolute path), and dropping it removes
the file with `remove_file`.
- `ShmHandle` is the opened file. `create` returns one, so the creator
never looks its own file up by name, and `open` returns one to everybody
else. `map` can be called more than once.
- `Mapping` is the bytes. It keeps them alive until dropped and cannot
affect the name.

Removal works on every platform because modern Windows deletes with
POSIX semantics: the name goes away at once, [existing handles keep
working](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntddk/ns-ntddk-_file_disposition_information_ex),
and [mapped views keep the data
alive](https://learn.microsoft.com/en-us/windows/win32/api/memoryapi/nf-memoryapi-createfilemappingw).
CI probes on Windows Server confirmed both, with a live writable view
and with an open share-delete handle. The docs reserve the right to fail
the delete while a view is mapped, and Windows versions without POSIX
delete do fail it, so the keeper falls back to reopening the file with
`FILE_FLAG_DELETE_ON_CLOSE` and closing it. Unit tests pin the full
removal semantics: name gone with a live mapping, name gone with an open
handle, and the handle still mapping the same bytes afterwards.

Name removal is cleanup. The channel invalidates contents inside the
shared bytes, so nothing depends on removal timing. Backing files sit
directly in the system temp directory as `vite-task-fspy-<uuid>.shm`
with mode `0o600`; a shared subdirectory would belong to whichever user
created it first and lock everyone else out. The identifier is resolved
to an absolute path at creation, so a relative `TMPDIR` in the creating
process cannot mislead an opener with a different working directory.

There is no broker, no global object name, no tokio requirement, and no
hand-written mapping code: the Windows-specific parts shrink to the
sparse-file `FSCTL` and the creation flags.

If the keeper's process is killed, the file stays behind: on Unix for
the temp reaper, on Windows until a cleanup tool runs. It costs about as
much disk as the run wrote into it.

Refs #563.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: wan9chi

Cargo.lock

@@ -93,7 +93,6 @@ jsonc-parser = { version = "0.32.0", features = ["serde"] }
 libc = "0.2.185"
 libtest-mimic = "0.8.2"
 memmap2 = "0.9.11"
-memfd = "0.6.5"
 monostate = "1.0.2"
 napi = "3"
 napi-build = "2"

Cargo.toml

@@ -2,55 +2,22 @@
 
 mod shm_io;
 
-use std::{env::temp_dir, fs::File, io, mem::MaybeUninit, ops::Deref, path::PathBuf, sync::Arc};
+use std::{env::temp_dir, fs::File, io, ops::Deref, path::PathBuf};
 
-use fspy_shm::Shm;
+use fspy_shm::{Mapping, ShmKeeper};
 pub use shm_io::FrameMut;
 use shm_io::{ShmReader, ShmWriter};
 use tracing::debug;
 use uuid::Uuid;
-use wincode::{
-    SchemaRead, SchemaWrite,
-    config::Config,
-    error::{ReadResult, WriteResult},
-    io::{Reader, Writer},
-};
+use wincode::{SchemaRead, SchemaWrite};
 
 use super::NativeStr;
 
-/// wincode schema adapter for `Arc<str>`, which is a foreign type with unsized inner.
-pub(crate) struct ArcStrSchema;
-
-// SAFETY: Delegates to `str`'s SchemaWrite impl, preserving its size/write invariants.
-unsafe impl<C: Config> SchemaWrite<C> for ArcStrSchema {
-    type Src = Arc<str>;
-
-    fn size_of(src: &Self::Src) -> WriteResult<usize> {
-        <str as SchemaWrite<C>>::size_of(src)
-    }
-
-    fn write(writer: impl Writer, src: &Self::Src) -> WriteResult<()> {
-        <str as SchemaWrite<C>>::write(writer, src)
-    }
-}
-
-// SAFETY: Delegates to `&str`'s SchemaRead impl; dst is initialized on Ok.
-unsafe impl<'de, C: Config> SchemaRead<'de, C> for ArcStrSchema {
-    type Dst = Arc<str>;
-
-    fn read(mut reader: impl Reader<'de>, dst: &mut MaybeUninit<Self::Dst>) -> ReadResult<()> {
-        let s: &str = <&str as SchemaRead<'de, C>>::get(&mut reader)?;
-        dst.write(Arc::from(s));
-        Ok(())
-    }
-}
-
 /// Serializable configuration to create channel senders.
 #[derive(SchemaWrite, SchemaRead, Clone, Debug)]
 pub struct ChannelConf {
     lock_file_path: Box<NativeStr>,
-    #[wincode(with = "ArcStrSchema")]
-    shm_id: Arc<str>,
+    shm_id: Box<NativeStr>,
 }
 
 /// Creates a mpsc IPC channel with one receiver and a `ChannelConf` that can be passed around processes and used to create multiple senders
@@ -59,12 +26,15 @@ pub fn channel(capacity: usize) -> io::Result<(ChannelConf, Receiver)> {
     // Initialize the lock file with a unique name.
     let lock_file_path = temp_dir().join(format!("fspy_ipc_{}.lock", Uuid::new_v4()));
 
-    let shm = fspy_shm::create(capacity)?;
+    let (keeper, handle) = fspy_shm::create(capacity)?;
+    let mapping = handle.map()?;
 
-    let conf =
-        ChannelConf { lock_file_path: lock_file_path.as_os_str().into(), shm_id: shm.id().into() };
+    let conf = ChannelConf {
+        lock_file_path: lock_file_path.as_os_str().into(),
+        shm_id: keeper.id().into(),
+    };
 
-    let receiver = Receiver::new(lock_file_path, shm)?;
+    let receiver = Receiver::new(lock_file_path, keeper, mapping)?;
     Ok((conf, receiver))
 }
 
@@ -80,16 +50,17 @@ impl ChannelConf {
         let lock_file = File::open(self.lock_file_path.to_cow_os_str())?;
         lock_file.try_lock_shared()?;
 
-        let shm = fspy_shm::open(&self.shm_id)?;
-        // SAFETY: `shm` is a freshly opened shared memory region with valid pointer and size.
-        // Exclusive write access is ensured by the shared file lock held by this sender.
-        let writer = unsafe { ShmWriter::new(shm) };
+        let mapping = fspy_shm::open(&self.shm_id.to_cow_os_str())?.map()?;
+        // SAFETY: `mapping` is a freshly mapped shared memory region with valid
+        // pointer and size. Exclusive write access is ensured by the shared
+        // file lock held by this sender.
+        let writer = unsafe { ShmWriter::new(mapping) };
         Ok(Sender { writer, lock_file, lock_file_path: self.lock_file_path.clone() })
     }
 }
 
 pub struct Sender {
-    writer: ShmWriter<Shm>,
+    writer: ShmWriter<Mapping>,
     lock_file_path: Box<NativeStr>,
     lock_file: File,
 }
@@ -104,20 +75,13 @@ impl Drop for Sender {
 }
 
 impl Deref for Sender {
-    type Target = ShmWriter<Shm>;
+    type Target = ShmWriter<Mapping>;
 
     fn deref(&self) -> &Self::Target {
         &self.writer
     }
 }
 
-#[cfg_attr(
-    target_os = "windows",
-    expect(
-        clippy::non_send_fields_in_send_ty,
-        reason = "`Sender` holds a shared file lock that ensures there's no reader, so `shm` can be safely written to"
-    )
-)]
 /// SAFETY: `Sender` holds a shared file lock that ensures there's no reader, so `shm` can be safely written to.
 unsafe impl Send for Sender {}
 
@@ -129,16 +93,11 @@ unsafe impl Sync for Sender {}
 pub struct Receiver {
     lock_file_path: PathBuf,
     lock_file: File,
-    shm: Shm,
+    /// Keeps the backing file's name alive for as long as senders may attach.
+    _keeper: ShmKeeper,
+    mapping: Mapping,
 }
 
-#[cfg_attr(
-    target_os = "windows",
-    expect(
-        clippy::non_send_fields_in_send_ty,
-        reason = "Receiver doesn't read or write `shm`. It only passes it to `ReceiverLockGuard` under the lock"
-    )
-)]
 /// SAFETY: `Receiver` doesn't read or write `shm`. It only passes it to `ReceiverLockGuard` under the lock.
 unsafe impl Send for Receiver {}
 
@@ -154,9 +113,9 @@ impl Drop for Receiver {
 }
 
 impl Receiver {
-    fn new(lock_file_path: PathBuf, shm: Shm) -> io::Result<Self> {
+    fn new(lock_file_path: PathBuf, keeper: ShmKeeper, mapping: Mapping) -> io::Result<Self> {
         let lock_file = File::create(&lock_file_path)?;
-        Ok(Self { lock_file_path, lock_file, shm })
+        Ok(Self { lock_file_path, lock_file, _keeper: keeper, mapping })
     }
 
     /// Lock the shared memory for unique read access.
@@ -170,7 +129,7 @@ impl Receiver {
         self.lock_file.lock()?;
         // SAFETY: The exclusive file lock is held, so no writers can access the shared memory.
         // The lock ensures all prior writes are visible to this thread.
-        let reader = ShmReader::new(unsafe { self.shm.as_slice() });
+        let reader = ShmReader::new(unsafe { self.mapping.as_slice() });
         Ok(ReceiverLockGuard { reader, lock_file: &self.lock_file })
     }
 }

crates/fspy_shared/src/ipc/channel/mod.rs

@@ -9,7 +9,7 @@ use std::{
 };
 
 use bytemuck::must_cast;
-use fspy_shm::Shm;
+use fspy_shm::Mapping;
 use wincode::{SchemaWrite, Serialize as _, config::DefaultConfig};
 
 // `ShmWriter` writes headers using atomic operations to prevent partial writes due to crashes,
@@ -28,7 +28,7 @@ pub trait AsRawSlice {
     fn as_raw_slice(&self) -> *mut [u8];
 }
 
-impl AsRawSlice for Shm {
+impl AsRawSlice for Mapping {
     fn as_raw_slice(&self) -> *mut [u8] {
         slice_from_raw_parts_mut(self.as_ptr(), self.len())
     }
@@ -672,31 +672,24 @@ mod tests {
 
         const SHM_SIZE: usize = 1024 * 1024;
 
-        // On Linux, `fspy_shm::create` spawns the mapping's broker onto the
-        // ambient tokio runtime, which serves the child processes' opens.
-        #[cfg(target_os = "linux")]
-        let runtime = tokio::runtime::Builder::new_multi_thread()
-            .worker_threads(1)
-            .enable_io()
-            .enable_time()
-            .build()
-            .unwrap();
-        #[cfg(target_os = "linux")]
-        let _guard = runtime.enter();
-
-        let shm = fspy_shm::create(SHM_SIZE).unwrap();
-        let shm_name = shm.id().to_owned();
+        let (keeper, handle) = fspy_shm::create(SHM_SIZE).unwrap();
+        let shm_name = keeper.id().to_str().expect("test temp dir is UTF-8").to_owned();
+        // Map before the children run. Windows keeps views coherent while they
+        // exist at the same time; a view created after every writer exited can
+        // observe the file before the writers' dirty pages reach it.
+        let mapping = handle.map().unwrap();
 
         let children: Vec<Child> = (0..CHILD_COUNT)
             .map(|child_index| {
                 let cmd = command_for_fn!(
                     (shm_name.clone(), child_index),
                     |(shm_name, child_index): (String, usize)| {
-                        let shm = fspy_shm::open(&shm_name).unwrap();
-                        // SAFETY: `shm` is a freshly opened shared memory region with a valid
-                        // pointer and size. Concurrent write access is safe because `ShmWriter`
-                        // uses atomic operations.
-                        let writer = unsafe { ShmWriter::new(shm) };
+                        let mapping =
+                            fspy_shm::open(std::ffi::OsStr::new(&shm_name)).unwrap().map().unwrap();
+                        // SAFETY: `mapping` is a freshly mapped shared memory region with a
+                        // valid pointer and size. Concurrent write access is safe because
+                        // `ShmWriter` uses atomic operations.
+                        let writer = unsafe { ShmWriter::new(mapping) };
                         for i in 0..FRAME_COUNT_EACH_CHILD {
                             let frame_data = std::format!("{child_index} {i}");
                             assert!(writer.try_write_frame(frame_data.as_bytes()));
@@ -714,7 +707,7 @@ mod tests {
 
         // SAFETY: All child processes have exited (waited above), so no concurrent writers exist.
         // The shared memory is valid and fully written.
-        let shm = unsafe { shm.as_slice() };
+        let shm = unsafe { mapping.as_slice() };
         let reader = ShmReader::new(shm);
         let frames = reader.iter_frames().map(BStr::new).collect::<FxHashSet<&BStr>>();
         assert_eq!(frames.len(), CHILD_COUNT * FRAME_COUNT_EACH_CHILD);

crates/fspy_shared/src/ipc/channel/shm_io.rs

@@ -7,37 +7,21 @@ license.workspace = true
 publish = false
 rust-version.workspace = true
 
-[target.'cfg(target_os = "linux")'.dependencies]
+[dependencies]
 memmap2 = { workspace = true }
-memfd = { workspace = true }
-passfd = { workspace = true, features = ["async"] }
-nix = { workspace = true, features = ["fs", "socket", "user"] }
-tokio = { workspace = true, features = ["macros", "net", "rt", "time"] }
-tokio-util = { workspace = true }
-tracing = { workspace = true }
-uuid = { workspace = true, features = ["v4"] }
-
-[target.'cfg(target_os = "macos")'.dependencies]
-base64 = { workspace = true }
-memmap2 = { workspace = true }
-nix = { workspace = true, features = ["fs", "mman"] }
 uuid = { workspace = true, features = ["v4"] }
 
 [target.'cfg(target_os = "windows")'.dependencies]
-uuid = { workspace = true, features = ["v4"] }
 windows-sys = { workspace = true, features = [
   "Win32_Foundation",
-  "Win32_Security",
   "Win32_Storage_FileSystem",
   "Win32_System_IO",
   "Win32_System_Ioctl",
-  "Win32_System_Memory",
 ] }
 
 [dev-dependencies]
 ctor = { workspace = true }
 subprocess_test = { workspace = true }
-tokio = { workspace = true, features = ["macros", "rt-multi-thread"] }
 
 [lints]
 workspace = true