perf(fspy): use sparse Windows shared memory

Co-authored-by: GPT-5.6 <gpt-5.6@openai.com>

Author: wan9chi

CHANGELOG.md

@@ -4,6 +4,7 @@
 - **Fixed** Failures while waiting for a started task process to exit no longer incorrectly say the process failed to spawn ([#515](https://github.com/voidzero-dev/vite-task/pull/515)).
 - **Fixed** Missing env vars requested through `@voidzero-dev/vite-task-client` now return `undefined` instead of `null`, preserving Vite production `NODE_ENV` semantics when builds run through `vp run` ([#508](https://github.com/voidzero-dev/vite-task/pull/508)).
 - **Fixed** Linux file-access tracking no longer consumes the `/dev/shm` mount used by containers and Kubernetes runners ([#353](https://github.com/voidzero-dev/vite-task/issues/353)).
+- **Improved** Windows file-access tracking now uses sparse temporary backing files, avoiding an upfront 4 GiB disk allocation per task.
 - **Fixed** Windows builds no longer hang on CI when a `node_modules/.bin` `.cmd` shim is routed through PowerShell: the npm/pnpm/yarn `.ps1` wrappers read stdin and block forever on a non-TTY pipe, so the PowerShell rewrite is now skipped when stdin is not an interactive terminal, falling back to the `.cmd` (which never reads stdin) ([#491](https://github.com/voidzero-dev/vite-task/pull/491)).
 - **Added** First-party support for caching `vite build` with zero cache config, giving Vite projects correct cache hits out of the box ([vitejs/vite#22453](https://github.com/vitejs/vite/pull/22453)).
 - **Added** Support for specifying tasks from dependency packages in `dependsOn`, such as `dependsOn: [{ "task": "build", "from": "dependencies" }]` ([#479](https://github.com/voidzero-dev/vite-task/pull/479)).

crates/fspy_shm/Cargo.toml

@@ -24,6 +24,8 @@ windows-sys = { workspace = true, features = [
   "Win32_Foundation",
   "Win32_Security",
   "Win32_Storage_FileSystem",
+  "Win32_System_IO",
+  "Win32_System_Ioctl",
   "Win32_System_Memory",
 ] }
 

crates/fspy_shm/src/lib.rs

@@ -199,7 +199,9 @@ mod tests {
         write_byte(&owner, 0, 17);
         drop(owner);
 
-        // Windows keeps the named object alive while an opened view exists.
+        // POSIX shm_unlink removes the name immediately. On Windows,
+        // an existing mapped view keeps the named kernel object alive; fspy's
+        // lock file, rather than this low-level mapping API, rejects late senders.
         #[cfg(not(target_os = "windows"))]
         assert!(open(&id, SIZE).is_err());
         assert_eq!(read_byte(&opened, 0), 17);

crates/fspy_shm/src/windows/mod.rs

@@ -19,8 +19,13 @@ const BACKING_DIR: &str = "vite-task-fspy";
 pub struct Shm {
     id: String,
     view: MappedView,
-    _mapping: OwnedHandle,
-    backing_file: BackingFile,
+    _mapping: Option<OwnedHandle>,
+    // Owner mappings keep this file alive until their view and mapping handle drop.
+    #[cfg_attr(
+        not(test),
+        expect(dead_code, reason = "the file is retained only for RAII cleanup")
+    )]
+    backing_file: Option<File>,
 }
 
 /// A newly created shared-memory mapping.
@@ -29,7 +34,7 @@ pub struct CreatedShm {
     pub shm: Shm,
 }
 
-/// Creates a file-backed named mapping of `size` bytes.
+/// Creates a sparse, temporary file-backed named mapping of `size` bytes.
 ///
 /// # Errors
 ///
@@ -52,14 +57,14 @@ fn create_with(size: usize, mut next_name: impl FnMut() -> String) -> io::Result
 
 fn create_named(id: &str, size: u64) -> io::Result<Option<Shm>> {
     let path = backing_path(id)?;
-    let backing_file = match BackingFile::create(path) {
+    let backing_file = match create_backing_file(&path) {
         Ok(file) => file,
         Err(error) if error.kind() == io::ErrorKind::AlreadyExists => return Ok(None),
         Err(error) => return Err(error),
     };
-    backing_file.file.set_len(size)?;
+    initialize_backing_file(&backing_file, size)?;
 
-    let mapping = match sys::create_file_mapping(&backing_file.file, id)? {
+    let mapping = match sys::create_file_mapping(&backing_file, id)? {
         CreatedMapping::Created(mapping) => mapping,
         CreatedMapping::AlreadyExists => return Ok(None),
     };
@@ -68,29 +73,28 @@ fn create_named(id: &str, size: u64) -> io::Result<Option<Shm>> {
     })?;
     let view = MappedView::new(&mapping, len)?;
 
-    Ok(Some(Shm { id: id.to_owned(), view, _mapping: mapping, backing_file }))
+    Ok(Some(Shm {
+        id: id.to_owned(),
+        view,
+        _mapping: Some(mapping),
+        backing_file: Some(backing_file),
+    }))
 }
 
 /// Opens the named mapping identified by `id`.
 ///
 /// # Errors
 ///
-/// Returns an error if the identifier is invalid, the owner has torn down the
-/// mapping, or its backing file has a different size.
+/// Returns an error if the identifier is invalid, the mapping is unavailable,
+/// or `size` cannot be mapped from it.
 pub fn open(id: &str, size: usize) -> io::Result<Shm> {
-    let expected_size = valid_size(size)?;
-    let path = backing_path(id)?;
-    let backing_file = BackingFile::open(path)?;
-    if backing_file.file.metadata()?.len() != expected_size {
-        return Err(io::Error::new(
-            io::ErrorKind::InvalidData,
-            "shared-memory backing file has an unexpected size",
-        ));
-    }
+    valid_size(size)?;
+    validate_id(id)?;
 
     let mapping = sys::open_file_mapping(id)?;
     let view = MappedView::new(&mapping, size)?;
-    Ok(Shm { id: id.to_owned(), view, _mapping: mapping, backing_file })
+    drop(mapping);
+    Ok(Shm { id: id.to_owned(), view, _mapping: None, backing_file: None })
 }
 
 fn valid_size(size: usize) -> io::Result<u64> {
@@ -109,83 +113,37 @@ fn backing_dir() -> PathBuf {
 }
 
 fn backing_path(id: &str) -> io::Result<PathBuf> {
+    let suffix = validate_id(id)?;
+    Ok(backing_dir().join(format!("{suffix}.shm")))
+}
+
+fn validate_id(id: &str) -> io::Result<&str> {
     let suffix = id.strip_prefix(NAME_PREFIX).ok_or_else(invalid_id)?;
     let uuid = Uuid::parse_str(suffix).map_err(|_| invalid_id())?;
     if uuid.hyphenated().to_string() != suffix {
         return Err(invalid_id());
     }
-    Ok(backing_dir().join(format!("{suffix}.shm")))
+    Ok(suffix)
 }
 
 fn invalid_id() -> io::Error {
     io::Error::new(io::ErrorKind::InvalidInput, "invalid Windows shared-memory identifier")
 }
 
-struct BackingFile {
-    file: File,
-    owner_path: Option<PathBuf>,
-}
-
-impl BackingFile {
-    fn create(path: PathBuf) -> io::Result<Self> {
-        let file = OpenOptions::new()
-            .read(true)
-            .write(true)
-            .create_new(true)
-            .share_mode(sys::SHARE_ALL)
-            .attributes(sys::TEMPORARY)
-            .open(&path)?;
-        Ok(Self { file, owner_path: Some(path) })
-    }
-
-    fn open(path: PathBuf) -> io::Result<Self> {
-        let file = OpenOptions::new()
-            .read(true)
-            .write(true)
-            .share_mode(sys::SHARE_ALL)
-            .attributes(sys::TEMPORARY)
-            .open(path)?;
-        Ok(Self { file, owner_path: None })
-    }
-
-    fn unlink(&mut self) {
-        let Some(path) = self.owner_path.take() else {
-            return;
-        };
-
-        let deletion_file = OpenOptions::new()
-            .access_mode(sys::DELETE_ACCESS)
-            .share_mode(sys::SHARE_ALL)
-            .attributes(sys::DELETE_ON_CLOSE)
-            .open(&path);
-        if let Ok(deletion_file) = deletion_file {
-            let deleted_path = deleted_path(&path);
-            if fs::rename(&path, deleted_path).is_err() {
-                let _ = fs::remove_file(&path);
-            }
-            drop(deletion_file);
-        } else {
-            let _ = fs::remove_file(path);
-        }
-    }
-}
-
-impl Drop for BackingFile {
-    fn drop(&mut self) {
-        self.unlink();
-    }
-}
-
-fn deleted_path(path: &Path) -> PathBuf {
-    path.with_extension(format!("deleted-{}", Uuid::new_v4()))
+fn create_backing_file(path: &Path) -> io::Result<File> {
+    OpenOptions::new()
+        .read(true)
+        .write(true)
+        .create_new(true)
+        .share_mode(sys::SHARE_ALL)
+        .attributes(sys::TEMPORARY)
+        .custom_flags(sys::DELETE_ON_CLOSE)
+        .open(path)
 }
 
-impl Drop for Shm {
-    fn drop(&mut self) {
-        // Remove the public backing-file name before the mapping handle drops,
-        // preventing opens that begin after owner teardown.
-        self.backing_file.unlink();
-    }
+fn initialize_backing_file(file: &File, size: u64) -> io::Result<()> {
+    sys::set_sparse(file)?;
+    file.set_len(size)
 }
 
 #[expect(clippy::len_without_is_empty, reason = "shared-memory mappings are always non-empty")]
@@ -240,7 +198,7 @@ mod tests {
     }
 
     #[test]
-    fn malformed_ids_and_size_mismatches_are_rejected() {
+    fn malformed_ids_and_invalid_sizes_are_rejected() {
         for id in [
             "vite-task-fspy-not-local",
             r"Local\vite-task-fspy-not-a-uuid",
@@ -252,8 +210,7 @@ mod tests {
 
         let owner = create(SIZE).unwrap().shm;
         assert_eq!(open(owner.id(), 0).err().unwrap().kind(), io::ErrorKind::InvalidInput);
-        assert_eq!(open(owner.id(), SIZE / 2).err().unwrap().kind(), io::ErrorKind::InvalidData);
-        assert_eq!(open(owner.id(), SIZE + 1).err().unwrap().kind(), io::ErrorKind::InvalidData);
+        assert!(open(owner.id(), SIZE + 1).is_err());
     }
 
     #[test]
@@ -262,10 +219,10 @@ mod tests {
         let collision_name = format!("{NAME_PREFIX}{}", Uuid::new_v4());
         let raw_backing_name = format!("{NAME_PREFIX}{}", Uuid::new_v4());
         let raw_backing_path = backing_path(&raw_backing_name).unwrap();
-        let raw_backing = BackingFile::create(raw_backing_path).unwrap();
-        raw_backing.file.set_len(SIZE as u64).unwrap();
+        let raw_backing = create_backing_file(&raw_backing_path).unwrap();
+        initialize_backing_file(&raw_backing, SIZE as u64).unwrap();
         let collision_mapping =
-            match sys::create_file_mapping(&raw_backing.file, &collision_name).unwrap() {
+            match sys::create_file_mapping(&raw_backing, &collision_name).unwrap() {
                 CreatedMapping::Created(mapping) => mapping,
                 CreatedMapping::AlreadyExists => panic!("random test mapping name collided"),
             };
@@ -282,7 +239,16 @@ mod tests {
     }
 
     #[test]
-    fn owner_cleanup_removes_backing_file_after_existing_views_close() {
+    fn sender_opens_the_named_mapping_without_a_backing_file() {
+        let owner = create(SIZE).unwrap().shm;
+        let opened = open(owner.id(), SIZE).unwrap();
+
+        assert!(owner.backing_file.is_some());
+        assert!(opened.backing_file.is_none());
+    }
+
+    #[test]
+    fn owner_cleanup_deletes_backing_file_and_preserves_existing_views() {
         let owner = create(SIZE).unwrap().shm;
         let id = owner.id().to_owned();
         let path = backing_path(&id).unwrap();
@@ -292,12 +258,12 @@ mod tests {
         drop(owner);
 
         assert!(!path.exists());
-        assert!(open(&id, SIZE).is_err());
         // SAFETY: The mapping remains live and no other test access is concurrent.
         unsafe { opened.as_ptr().write(17) };
         // SAFETY: The preceding write is complete and the mapping remains live.
         assert_eq!(unsafe { opened.as_ptr().read() }, 17);
         drop(opened);
+        assert!(open(&id, SIZE).is_err());
 
         let suffix = id.strip_prefix(NAME_PREFIX).unwrap();
         assert!(
@@ -309,12 +275,34 @@ mod tests {
         );
     }
 
+    #[test]
+    fn sparse_failure_does_not_extend_the_file() {
+        fs::create_dir_all(backing_dir()).unwrap();
+        let id = format!("{NAME_PREFIX}{}", Uuid::new_v4());
+        let path = backing_path(&id).unwrap();
+        File::create(&path).unwrap();
+        let read_only =
+            OpenOptions::new().read(true).share_mode(sys::SHARE_ALL).open(&path).unwrap();
+
+        assert!(initialize_backing_file(&read_only, 4 * 1024 * 1024 * 1024).is_err());
+        assert_eq!(read_only.metadata().unwrap().len(), 0);
+
+        drop(read_only);
+        fs::remove_file(path).unwrap();
+    }
+
     #[cfg(target_pointer_width = "64")]
     #[test]
-    fn four_gib_mapping_supports_endpoint_access() {
+    fn four_gib_mapping_is_sparse_and_supports_endpoint_access() {
         const PRODUCTION_SIZE: usize = 4 * 1024 * 1024 * 1024;
+        const MAX_ENDPOINT_ALLOCATION: u64 = 16 * 1024 * 1024;
 
         let owner = create(PRODUCTION_SIZE).unwrap().shm;
+        let backing_file = owner.backing_file.as_ref().unwrap();
+        let (logical_size, initial_allocation) = sys::file_sizes(backing_file).unwrap();
+        assert_eq!(logical_size, PRODUCTION_SIZE as u64);
+        assert!(initial_allocation < MAX_ENDPOINT_ALLOCATION);
+
         let opened = open(owner.id(), PRODUCTION_SIZE).unwrap();
         // SAFETY: Both endpoint indexes are within the exact mapped length and
         // accesses are synchronized within this test.
@@ -324,5 +312,9 @@ mod tests {
             assert_eq!(opened.as_ptr().read(), 17);
             assert_eq!(opened.as_ptr().add(PRODUCTION_SIZE - 1).read(), 29);
         }
+
+        let (logical_size, endpoint_allocation) = sys::file_sizes(backing_file).unwrap();
+        assert_eq!(logical_size, PRODUCTION_SIZE as u64);
+        assert!(endpoint_allocation < MAX_ENDPOINT_ALLOCATION);
     }
 }