@photostructure/fs-metadata 1.0.1 → 1.2.0

package/src/volume_metadata.ts

@@ -1,8 +1,12 @@
 // src/volume_metadata.ts
 
+import type { Stats } from "node:fs";
+import { realpath } from "node:fs/promises";
+import { dirname } from "node:path";
 import { mapConcurrent, withTimeout } from "./async";
 import { debug } from "./debuglog";
 import { WrappedError } from "./error";
+import { statAsync } from "./fs";
 import { getLabelFromDevDisk, getUuidFromDevDisk } from "./linux/dev_disk";
 import { getLinuxMtabMetadata } from "./linux/mount_points";
 import {
@@ -11,8 +15,8 @@ import {
 } from "./linux/mtab";
 import { compactValues } from "./object";
 import { IncludeSystemVolumesDefault, optionsWithDefaults } from "./options";
-import { normalizePath } from "./path";
-import { isLinux, isWindows } from "./platform";
+import { isAncestorOrSelf, normalizePath } from "./path";
+import { isLinux, isMacOS, isWindows } from "./platform";
 import { extractRemoteInfo, isRemoteFsType } from "./remote_info";
 import { isBlank, isNotBlank } from "./string";
 import { assignSystemVolume } from "./system_volume";
@@ -153,6 +157,117 @@ async function _getVolumeMetadata(
   return compactValues(result) as VolumeMetadata;
 }
 
+/**
+ * Get volume metadata for an arbitrary file or directory path.
+ *
+ * Unlike {@link getVolumeMetadataImpl}, this accepts any path — not just mount
+ * points. It resolves symlinks and correctly handles macOS APFS firmlinks
+ * (e.g. `/Users` → `/System/Volumes/Data`), mirroring what `df` does.
+ *
+ * On macOS, the native `fstatfs()` call returns `f_mntonname` (the canonical
+ * mount point), exposed here as `mountName`. This is used to resolve firmlinks
+ * without `stat().dev`, which does NOT follow firmlinks.
+ *
+ * On Linux and Windows, `stat().dev` device IDs are reliable (no firmlinks),
+ * so mount point discovery uses device ID + path prefix matching.
+ */
+export async function getVolumeMetadataForPathImpl(
+  pathname: string,
+  opts: Options,
+  nativeFn: NativeBindingsFn,
+): Promise<VolumeMetadata> {
+  if (isBlank(pathname)) {
+    throw new TypeError("Invalid pathname: got " + JSON.stringify(pathname));
+  }
+
+  // realpath() resolves POSIX symlinks. APFS firmlinks are NOT resolved by
+  // realpath(), but fstatfs() follows them — handled below.
+  const resolved = await realpath(pathname);
+
+  // getVolumeMetadataImpl requires a directory path, not a file.
+  const resolvedStat = await statAsync(resolved);
+  const dir = resolvedStat.isDirectory() ? resolved : dirname(resolved);
+
+  if (isMacOS) {
+    // On macOS, native fstatfs() sets mountName = f_mntonname, which is the
+    // canonical mount point even through APFS firmlinks. Probe the dir to get
+    // it, then re-query with the canonical mount point so the result has
+    // mountPoint set correctly.
+    const probe = await getVolumeMetadataImpl(
+      { ...opts, mountPoint: dir },
+      nativeFn,
+    );
+    const canonicalMountPoint = isNotBlank(probe.mountName)
+      ? probe.mountName
+      : dir;
+    if (canonicalMountPoint === dir) return probe;
+    return getVolumeMetadataImpl(
+      { ...opts, mountPoint: canonicalMountPoint },
+      nativeFn,
+    );
+  }
+
+  // Linux/Windows: stat().dev is reliable (no firmlinks). Find the mount point
+  // by comparing device IDs, using path prefix as a tiebreaker for bind mounts
+  // or GIO mounts that share the same device id.
+  const mountPoint = await findMountPointByDeviceId(
+    resolved,
+    resolvedStat,
+    opts,
+    nativeFn,
+  );
+
+  return getVolumeMetadataImpl({ ...opts, mountPoint }, nativeFn);
+}
+
+/**
+ * Find the mount point for a resolved path using device ID matching.
+ * Used on Linux and Windows where stat().dev is reliable (no firmlinks).
+ *
+ * Compares device IDs of mount points against the target path's device ID,
+ * using path prefix as a tiebreaker for bind mounts or GIO mounts that share
+ * the same device id. The longest prefix match wins.
+ */
+export async function findMountPointByDeviceId(
+  resolved: string,
+  resolvedStat: Stats,
+  opts: Options,
+  nativeFn: NativeBindingsFn,
+): Promise<string> {
+  const targetDev = resolvedStat.dev;
+  const mountPoints = await getVolumeMountPointsImpl(
+    { ...opts, includeSystemVolumes: true },
+    nativeFn,
+  );
+
+  const prefixMatches: string[] = [];
+  const deviceMatches: string[] = [];
+
+  await Promise.all(
+    mountPoints.map(async ({ mountPoint }) => {
+      try {
+        const mpDev = (await statAsync(mountPoint)).dev;
+        if (mpDev !== targetDev) return;
+        if (isAncestorOrSelf(mountPoint, resolved)) {
+          prefixMatches.push(mountPoint);
+        } else {
+          deviceMatches.push(mountPoint);
+        }
+      } catch {
+        // skip inaccessible mount points
+      }
+    }),
+  );
+
+  const candidates = prefixMatches.length > 0 ? prefixMatches : deviceMatches;
+  if (candidates.length === 0) {
+    throw new Error(
+      "No mount point found for path: " + JSON.stringify(resolved),
+    );
+  }
+  return candidates.reduce((a, b) => (a.length >= b.length ? a : b));
+}
+
 export async function getAllVolumeMetadataImpl(
   opts: Required<Options> & {
     includeSystemVolumes?: boolean;

package/src/windows/system_volume.h

@@ -18,7 +18,12 @@
 
 namespace FSMeta {
 
-inline bool IsSystemVolume(const std::wstring &drive) {
+// Check if a drive is a system volume using SHGetFolderPathW (Windows dir)
+// and optionally FILE_SUPPORTS_SYSTEM_PATHS/FILES volume flags.
+//
+// volumeFlags: if non-zero, uses pre-fetched flags to avoid a redundant
+// GetVolumeInformationW call. Pass 0 to have this function query flags itself.
+inline bool IsSystemVolume(const std::wstring &drive, DWORD volumeFlags = 0) {
   WCHAR systemRoot[MAX_PATH];
   if (SUCCEEDED(
           SHGetFolderPathW(nullptr, CSIDL_WINDOWS, nullptr, 0, systemRoot))) {
@@ -33,22 +38,22 @@ inline bool IsSystemVolume(const std::wstring &drive) {
   }
 
   // Modern volume properties check
-  DWORD volumeFlags = 0;
-  wchar_t fileSystemName[MAX_PATH + 1] = {0};
-
-  if (GetVolumeInformationW(drive.c_str(), nullptr, 0, nullptr, nullptr,
-                            &volumeFlags, fileSystemName, MAX_PATH)) {
-
-    // Check for modern system volume indicators
-    if ((volumeFlags & FILE_SUPPORTS_SYSTEM_PATHS) ||
-        (volumeFlags & FILE_SUPPORTS_SYSTEM_FILES)) {
-      DEBUG_LOG("[IsSystemVolume] %ls has system volume flags (0x%08X)",
-                drive.c_str(), volumeFlags);
-      return true;
+  if (volumeFlags == 0) {
+    wchar_t fileSystemName[MAX_PATH + 1] = {0};
+    if (!GetVolumeInformationW(drive.c_str(), nullptr, 0, nullptr, nullptr,
+                               &volumeFlags, fileSystemName, MAX_PATH)) {
+      DEBUG_LOG("[IsSystemVolume] %ls GetVolumeInformationW failed: %lu",
+                drive.c_str(), GetLastError());
+      DEBUG_LOG("[IsSystemVolume] %ls is not a system volume", drive.c_str());
+      return false;
     }
-  } else {
-    DEBUG_LOG("[IsSystemVolume] %ls GetVolumeInformationW failed: %lu",
-              drive.c_str(), GetLastError());
+  }
+
+  if ((volumeFlags & FILE_SUPPORTS_SYSTEM_PATHS) ||
+      (volumeFlags & FILE_SUPPORTS_SYSTEM_FILES)) {
+    DEBUG_LOG("[IsSystemVolume] %ls has system volume flags (0x%08X)",
+              drive.c_str(), volumeFlags);
+    return true;
   }
 
   DEBUG_LOG("[IsSystemVolume] %ls is not a system volume", drive.c_str());

package/src/windows/volume_metadata.cpp

@@ -110,6 +110,7 @@ public:
   const char *getVolumeName() const { return volumeName; }
   const char *getFileSystem() const { return fstype; }
   DWORD getSerialNumber() const { return serialNumber; }
+  DWORD getFlags() const { return fsFlags; }
 };
 
 // RAII wrapper for disk space information
@@ -165,17 +166,13 @@ private:
         return; // Don't try to get additional info for non-healthy drives
       }
 
-      std::wstring widePath = SecurityUtils::SafeStringToWide(mountPoint);
-      metadata.isSystemVolume = IsSystemVolume(widePath.c_str());
-
-      DEBUG_LOG("[GetVolumeMetadata] %s {isSystemVolume: %s}",
-                mountPoint.c_str(), metadata.isSystemVolume ? "true" : "false");
-
-      // Get volume information
+      // Get volume information first so we can reuse its flags for
+      // IsSystemVolume, avoiding a redundant GetVolumeInformationW call.
       VolumeInfo volInfo(mountPoint);
       if (volInfo.isValid()) {
         metadata.label = volInfo.getVolumeName();
         metadata.fstype = volInfo.getFileSystem();
+        metadata.isReadOnly = (volInfo.getFlags() & FILE_READ_ONLY_VOLUME) != 0;
         DEBUG_LOG("[GetVolumeMetadata] %s {label: %s, fstype: %s}",
                   mountPoint.c_str(), metadata.label.c_str(),
                   metadata.fstype.c_str());
@@ -207,6 +204,15 @@ private:
         }
       }
 
+      // Check system volume using pre-fetched flags from VolumeInfo to
+      // avoid a redundant GetVolumeInformationW call.
+      std::wstring widePath = SecurityUtils::SafeStringToWide(mountPoint);
+      metadata.isSystemVolume =
+          IsSystemVolume(widePath, volInfo.isValid() ? volInfo.getFlags() : 0);
+
+      DEBUG_LOG("[GetVolumeMetadata] %s {isSystemVolume: %s}",
+                mountPoint.c_str(), metadata.isSystemVolume ? "true" : "false");
+
       // Check if drive is remote
       metadata.remote = (GetDriveTypeA(mountPoint.c_str()) == DRIVE_REMOTE);
       DEBUG_LOG("[GetVolumeMetadata] %s {remote: %s}", mountPoint.c_str(),

package/src/windows/volume_mount_points.cpp

@@ -84,21 +84,25 @@ public:
         mp.mountPoint = paths[i];
         mp.status = DriveStatusToString(statuses[i]);
 
+        std::wstring widePath = SecurityUtils::SafeStringToWide(paths[i]);
+        DWORD fsFlags = 0;
+
         if (statuses[i] == DriveStatus::Healthy) {
           WCHAR fsName[MAX_PATH + 1] = {0};
 
-          if (GetVolumeInformationW(
-                  SecurityUtils::SafeStringToWide(paths[i]).c_str(), nullptr, 0,
-                  nullptr, nullptr, nullptr, fsName, MAX_PATH)) {
+          if (GetVolumeInformationW(widePath.c_str(), nullptr, 0, nullptr,
+                                    nullptr, &fsFlags, fsName, MAX_PATH)) {
             mp.fstype = WideToUtf8(fsName);
+            mp.isReadOnly = (fsFlags & FILE_READ_ONLY_VOLUME) != 0;
             DEBUG_LOG("[GetVolumeMountPoints] drive %s filesystem: %s",
                       paths[i].c_str(), mp.fstype.c_str());
           }
-        }
 
-        // Check if this is a system volume
-        mp.isSystemVolume =
-            IsSystemVolume(SecurityUtils::SafeStringToWide(paths[i]));
+          // Only check system volume for healthy drives — IsSystemVolume
+          // may call GetVolumeInformationW, which hangs on dead drives and
+          // would defeat the async timeout protection from CheckDriveStatus.
+          mp.isSystemVolume = IsSystemVolume(widePath, fsFlags);
+        }
         mountPoints_.push_back(std::move(mp));
       }