@matter/nodejs 0.17.3 → 0.17.4-alpha.0-20260621-81ba50a6a

package/dist/cjs/fs/lock-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lock-utils.d.ts","sourceRoot":"","sources":["../../../src/fs/lock-utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAuBH;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAoBzG"}
+{"version":3,"file":"lock-utils.d.ts","sourceRoot":"","sources":["../../../src/fs/lock-utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAsEH;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CA0BzG"}

package/dist/cjs/fs/lock-utils.js

@@ -23,6 +23,7 @@ __export(lock_utils_exports, {
 module.exports = __toCommonJS(lock_utils_exports);
 var import_general = require("@matter/general");
 var import_node_crypto = require("node:crypto");
+var import_node_fs = require("node:fs");
 var import_promises = require("node:fs/promises");
 var import_node_path = require("node:path");
 /**
@@ -34,6 +35,34 @@ const logger = import_general.Logger.get("NodeJsDirectoryLock");
 const LOCK_FILE = "matter.lock";
 const PID_FILE = "matter.pid";
 const PROCESS_TOKEN = (0, import_node_crypto.randomBytes)(8).toString("hex");
+const activeLocks = /* @__PURE__ */ new Set();
+let exitHandlerInstalled = false;
+function trackLock(lock) {
+  activeLocks.add(lock);
+  if (!exitHandlerInstalled) {
+    exitHandlerInstalled = true;
+    process.on("exit", removeOrphanedLocks);
+  }
+}
+function removeOrphanedLocks() {
+  for (const { lockPath, pidPath, name } of activeLocks) {
+    try {
+      logger.warn(
+        `Storage "${name}" was not closed before process exit; removing orphaned lock.`,
+        "Please close any opened storage during shutdown."
+      );
+    } catch {
+    }
+    unlinkSyncSafe(lockPath);
+    unlinkSyncSafe(pidPath);
+  }
+}
+function unlinkSyncSafe(path) {
+  try {
+    (0, import_node_fs.unlinkSync)(path);
+  } catch {
+  }
+}
 async function acquireDirectoryLock(dirPath, dirName) {
   const lockPath = (0, import_node_path.resolve)(dirPath, LOCK_FILE);
   const pidPath = (0, import_node_path.resolve)(dirPath, PID_FILE);
@@ -41,16 +70,19 @@ async function acquireDirectoryLock(dirPath, dirName) {
     return async () => {
     };
   }
-  await acquireLock(lockPath, pidPath);
+  await acquireLock(lockPath, pidPath, dirName);
   await (0, import_promises.writeFile)(pidPath, `${process.pid} ${PROCESS_TOKEN}`);
+  const tracked = { lockPath, pidPath, name: dirName };
+  trackLock(tracked);
   logger.debug("Acquired storage lock for", dirName, "pid", process.pid);
   return async () => {
-    await safeUnlink(pidPath);
     await safeUnlink(lockPath);
+    await safeUnlink(pidPath);
+    activeLocks.delete(tracked);
     logger.debug("Released storage lock for", dirName);
   };
 }
-async function acquireLock(lockPath, pidPath) {
+async function acquireLock(lockPath, pidPath, dirName) {
   try {
     const fd = await (0, import_promises.open)(lockPath, "wx");
     await fd.close();
@@ -59,8 +91,9 @@ async function acquireLock(lockPath, pidPath) {
       throw error;
     }
     const info = await readLockInfo(pidPath);
-    if (isStale(info)) {
-      logger.info("Cleaning stale storage lock");
+    const reason = staleReason(info);
+    if (reason !== void 0) {
+      logger.info("Cleaning stale storage lock for", dirName, "-", reason);
       await safeUnlink(pidPath);
       await safeUnlink(lockPath);
       try {
@@ -79,21 +112,21 @@ async function acquireLock(lockPath, pidPath) {
     }
   }
 }
-function isStale(info) {
+function staleReason(info) {
   if (info === void 0) {
-    return true;
+    return "no PID file (owner crashed before writing it)";
   }
   if (info.pid === process.pid) {
-    return info.token !== PROCESS_TOKEN;
+    return info.token !== PROCESS_TOKEN ? `PID ${info.pid} reused (token mismatch)` : void 0;
   }
   try {
     process.kill(info.pid, 0);
-    return false;
+    return void 0;
   } catch (error) {
     if (error.code === "ESRCH") {
-      return true;
+      return `owner process ${info.pid} no longer exists`;
     }
-    return false;
+    return void 0;
   }
 }
 async function readLockInfo(pidPath) {

package/dist/cjs/fs/lock-utils.js.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../../../src/fs/lock-utils.ts"],
-  "mappings": "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",
+  "mappings": "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",
   "names": ["fsOpen"]
 }

package/dist/esm/fs/lock-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lock-utils.d.ts","sourceRoot":"","sources":["../../../src/fs/lock-utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAuBH;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAoBzG"}
+{"version":3,"file":"lock-utils.d.ts","sourceRoot":"","sources":["../../../src/fs/lock-utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAsEH;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CA0BzG"}

package/dist/esm/fs/lock-utils.js

@@ -5,12 +5,41 @@
  */
 import { Logger, StorageLockError } from "@matter/general";
 import { randomBytes } from "node:crypto";
+import { unlinkSync } from "node:fs";
 import { open as fsOpen, readFile, stat, unlink, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 const logger = Logger.get("NodeJsDirectoryLock");
 const LOCK_FILE = "matter.lock";
 const PID_FILE = "matter.pid";
 const PROCESS_TOKEN = randomBytes(8).toString("hex");
+const activeLocks = /* @__PURE__ */ new Set();
+let exitHandlerInstalled = false;
+function trackLock(lock) {
+  activeLocks.add(lock);
+  if (!exitHandlerInstalled) {
+    exitHandlerInstalled = true;
+    process.on("exit", removeOrphanedLocks);
+  }
+}
+function removeOrphanedLocks() {
+  for (const { lockPath, pidPath, name } of activeLocks) {
+    try {
+      logger.warn(
+        `Storage "${name}" was not closed before process exit; removing orphaned lock.`,
+        "Please close any opened storage during shutdown."
+      );
+    } catch {
+    }
+    unlinkSyncSafe(lockPath);
+    unlinkSyncSafe(pidPath);
+  }
+}
+function unlinkSyncSafe(path) {
+  try {
+    unlinkSync(path);
+  } catch {
+  }
+}
 async function acquireDirectoryLock(dirPath, dirName) {
   const lockPath = resolve(dirPath, LOCK_FILE);
   const pidPath = resolve(dirPath, PID_FILE);
@@ -18,16 +47,19 @@ async function acquireDirectoryLock(dirPath, dirName) {
     return async () => {
     };
   }
-  await acquireLock(lockPath, pidPath);
+  await acquireLock(lockPath, pidPath, dirName);
   await writeFile(pidPath, `${process.pid} ${PROCESS_TOKEN}`);
+  const tracked = { lockPath, pidPath, name: dirName };
+  trackLock(tracked);
   logger.debug("Acquired storage lock for", dirName, "pid", process.pid);
   return async () => {
-    await safeUnlink(pidPath);
     await safeUnlink(lockPath);
+    await safeUnlink(pidPath);
+    activeLocks.delete(tracked);
     logger.debug("Released storage lock for", dirName);
   };
 }
-async function acquireLock(lockPath, pidPath) {
+async function acquireLock(lockPath, pidPath, dirName) {
   try {
     const fd = await fsOpen(lockPath, "wx");
     await fd.close();
@@ -36,8 +68,9 @@ async function acquireLock(lockPath, pidPath) {
       throw error;
     }
     const info = await readLockInfo(pidPath);
-    if (isStale(info)) {
-      logger.info("Cleaning stale storage lock");
+    const reason = staleReason(info);
+    if (reason !== void 0) {
+      logger.info("Cleaning stale storage lock for", dirName, "-", reason);
       await safeUnlink(pidPath);
       await safeUnlink(lockPath);
       try {
@@ -56,21 +89,21 @@ async function acquireLock(lockPath, pidPath) {
     }
   }
 }
-function isStale(info) {
+function staleReason(info) {
   if (info === void 0) {
-    return true;
+    return "no PID file (owner crashed before writing it)";
   }
   if (info.pid === process.pid) {
-    return info.token !== PROCESS_TOKEN;
+    return info.token !== PROCESS_TOKEN ? `PID ${info.pid} reused (token mismatch)` : void 0;
   }
   try {
     process.kill(info.pid, 0);
-    return false;
+    return void 0;
   } catch (error) {
     if (error.code === "ESRCH") {
-      return true;
+      return `owner process ${info.pid} no longer exists`;
     }
-    return false;
+    return void 0;
   }
 }
 async function readLockInfo(pidPath) {

package/dist/esm/fs/lock-utils.js.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../../../src/fs/lock-utils.ts"],
-  "mappings": "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",
+  "mappings": "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",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@matter/nodejs",
-    "version": "0.17.3",
+    "version": "0.17.4-alpha.0-20260621-81ba50a6a",
     "description": "Node.js platform support for matter.js",
     "keywords": [
         "iot",
@@ -38,16 +38,16 @@
         "#*": "./src/*"
     },
     "dependencies": {
-        "@matter/general": "0.17.3",
-        "@matter/node": "0.17.3",
-        "@matter/protocol": "0.17.3",
-        "@matter/types": "0.17.3"
+        "@matter/general": "0.17.4-alpha.0-20260621-81ba50a6a",
+        "@matter/node": "0.17.4-alpha.0-20260621-81ba50a6a",
+        "@matter/protocol": "0.17.4-alpha.0-20260621-81ba50a6a",
+        "@matter/types": "0.17.4-alpha.0-20260621-81ba50a6a"
     },
     "devDependencies": {
-        "@matter/model": "0.17.3",
-        "@matter/protocol": "0.17.3",
-        "@matter/testing": "0.17.3",
-        "@project-chip/matter.js": "0.17.3",
+        "@matter/model": "0.17.4-alpha.0-20260621-81ba50a6a",
+        "@matter/protocol": "0.17.4-alpha.0-20260621-81ba50a6a",
+        "@matter/testing": "0.17.4-alpha.0-20260621-81ba50a6a",
+        "@project-chip/matter.js": "0.17.4-alpha.0-20260621-81ba50a6a",
         "@types/bytebuffer": "^5.0.49"
     },
     "files": [

package/src/fs/lock-utils.ts

@@ -6,6 +6,7 @@
 
 import { Logger, StorageLockError } from "@matter/general";
 import { randomBytes } from "node:crypto";
+import { unlinkSync } from "node:fs";
 import { open as fsOpen, readFile, stat, unlink, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 
@@ -25,6 +26,52 @@ interface LockInfo {
     token?: string;
 }
 
+interface ActiveLock {
+    lockPath: string;
+    pidPath: string;
+    name: string;
+}
+
+/**
+ * Locks held by this process that have not yet been released.  A `process.exit` backstop removes the files for any
+ * survivors so a caller that forgets to close storage does not orphan a lock that blocks the next startup.
+ */
+const activeLocks = new Set<ActiveLock>();
+let exitHandlerInstalled = false;
+
+function trackLock(lock: ActiveLock) {
+    activeLocks.add(lock);
+    if (!exitHandlerInstalled) {
+        exitHandlerInstalled = true;
+        // 'exit' is synchronous-only, so cleanup is limited to unlinking the lock files; it cannot flush storage.
+        process.on("exit", removeOrphanedLocks);
+    }
+}
+
+function removeOrphanedLocks() {
+    for (const { lockPath, pidPath, name } of activeLocks) {
+        // Cleanup is the critical action; logging is advisory and must not prevent it if the logger throws
+        try {
+            logger.warn(
+                `Storage "${name}" was not closed before process exit; removing orphaned lock.`,
+                "Please close any opened storage during shutdown.",
+            );
+        } catch {
+            // ignore
+        }
+        unlinkSyncSafe(lockPath);
+        unlinkSyncSafe(pidPath);
+    }
+}
+
+function unlinkSyncSafe(path: string) {
+    try {
+        unlinkSync(path);
+    } catch {
+        // Best-effort cleanup during exit
+    }
+}
+
 /**
  * Acquire an exclusive lock on a directory using O_EXCL and a PID file for stale-lock detection.
  *
@@ -40,19 +87,25 @@ export async function acquireDirectoryLock(dirPath: string, dirName: string): Pr
         return async () => {};
     }
 
-    await acquireLock(lockPath, pidPath);
+    await acquireLock(lockPath, pidPath, dirName);
     await writeFile(pidPath, `${process.pid} ${PROCESS_TOKEN}`);
 
+    const tracked: ActiveLock = { lockPath, pidPath, name: dirName };
+    trackLock(tracked);
+
     logger.debug("Acquired storage lock for", dirName, "pid", process.pid);
 
     return async () => {
-        await safeUnlink(pidPath);
+        // Remove the lock (the gate) first: if the second unlink fails, a leftover pid file is harmless (the next
+        // start reacquires and overwrites it), whereas a leftover lock file would force stale detection
         await safeUnlink(lockPath);
+        await safeUnlink(pidPath);
+        activeLocks.delete(tracked);
         logger.debug("Released storage lock for", dirName);
     };
 }
 
-async function acquireLock(lockPath: string, pidPath: string) {
+async function acquireLock(lockPath: string, pidPath: string, dirName: string) {
     try {
         const fd = await fsOpen(lockPath, "wx");
         await fd.close();
@@ -63,9 +116,10 @@ async function acquireLock(lockPath: string, pidPath: string) {
 
         // Lock file exists — check if the owning process is still alive
         const info = await readLockInfo(pidPath);
+        const reason = staleReason(info);
 
-        if (isStale(info)) {
-            logger.info("Cleaning stale storage lock");
+        if (reason !== undefined) {
+            logger.info("Cleaning stale storage lock for", dirName, "-", reason);
             await safeUnlink(pidPath);
             await safeUnlink(lockPath);
 
@@ -88,34 +142,30 @@ async function acquireLock(lockPath: string, pidPath: string) {
 }
 
 /**
- * A lock is stale if:
- *
- * - There is no PID file (crash between lock creation and PID write)
- * - The owning process no longer exists
- * - The PID matches ours but the token differs (PID reuse, e.g. Docker container restart)
+ * Returns why a lock is stale, or `undefined` if it is held by a live owner.  The reason is logged so the cause of a
+ * reclaim (and any failure to release) is visible in the storage logs.
  */
-function isStale(info: LockInfo | undefined): boolean {
+function staleReason(info: LockInfo | undefined): string | undefined {
     if (info === undefined) {
-        return true;
+        return "no PID file (owner crashed before writing it)";
     }
 
     if (info.pid === process.pid) {
         // Same PID — check whether it's actually us via the token.  If the token matches, the lock is held by another
         // call site in this process.  If it differs (or is missing from an old-format file), the PID was reused.
-        return info.token !== PROCESS_TOKEN;
+        return info.token !== PROCESS_TOKEN ? `PID ${info.pid} reused (token mismatch)` : undefined;
     }
 
     try {
         process.kill(info.pid, 0);
-        // Process exists and we have permission to signal it — lock is not stale
-        return false;
+        // Process exists and we have permission to signal it (or EPERM below) — lock is not stale
+        return undefined;
     } catch (error) {
         if ((error as NodeJS.ErrnoException).code === "ESRCH") {
-            // Process does not exist — lock is stale
-            return true;
+            return `owner process ${info.pid} no longer exists`;
         }
         // EPERM — process exists but we can't signal it — lock is not stale
-        return false;
+        return undefined;
     }
 }