@stonyx/utils 0.2.3-beta.26 → 0.2.3-beta.27

package/README.md

@@ -75,10 +75,16 @@ Creates a file at the given path.
 
 #### `updateFile(filePath, data, options={})`
 
-Updates a file atomically by writing to a temporary file first.
+Updates a file atomically by writing to a sibling swap file first, then renaming it over the target. Throws if the file does not exist.
 
 * `options.json` — boolean, serialize as JSON.
 
+**Concurrency: last writer wins.** Concurrent `updateFile` calls on the same path are safe — each uses a swap file unique to its process and call, so neither caller's swap file can collide with the other's. The rename-time `ENOENT` and the silent cross-caller byte clobber of [#44](https://github.com/abofs/stonyx-utils/issues/44) are both gone. (`updateFile` still throws `ENOENT` from its own precondition when the target does not exist — that is the documented contract above, and it is unrelated to concurrency.) Calls are not serialized: the surviving value is whichever caller renames last.
+
+**File mode is preserved; other inode metadata is not.** The swap file is created with the target's permission bits and `chmod`ed to them before the rename, so a `0600` file stays `0600`. The `chmod` addresses the open file descriptor rather than the swap path, so it cannot be redirected onto another file by anyone who can write to the directory. ACLs, extended attributes, hard links and ownership are *not* carried across — the target necessarily gets a new inode.
+
+**Swap files after abnormal termination.** Cleanup runs on every failure path `updateFile` controls, but a process killed between the write and the rename leaves a `<path>.temp-<pid>-<token>` sibling behind, and no module ships a sweeper. This is a deliberate trade against the previous whole-second swap name, which was reused — and reuse is exactly the collision that caused #44, so uniqueness has to win. Be precise about what that costs: the old name only ever collapsed two orphans that were abandoned within the *same whole second*, so at any ordinary crash cadence it reclaimed nothing either (measured: five crashes 1200 ms apart leave five orphans under both names). The accumulation uniqueness genuinely adds is confined to a sub-second crash loop. Consumers that persist into a directory they scan, sync or commit should sweep or ignore `*.temp-*` siblings of their targets; an app that runs `git add` over its data directory will otherwise commit one.
+
 #### `copyFile(sourcePath, targetPath, options={})`
 
 Copies a file from source to target.

package/dist/file.d.ts

@@ -23,6 +23,42 @@ interface FileImportMeta {
     path: string;
 }
 export declare function createFile(filePath: string, data: string | Record<string, unknown>, options?: FileOptions): Promise<void>;
+/**
+ * Atomically replace the contents of an existing file.
+ *
+ * Writes to a swap file that is a **sibling** of the target — so `rename` stays
+ * on one filesystem and therefore stays atomic — then renames it over the
+ * target. The swap name carries `process.pid` and a short random token rather
+ * than a timestamp: a whole-second token collided between concurrent callers,
+ * which made one caller throw `ENOENT` and the other silently persist bytes it
+ * had not written (abofs/stonyx-utils#44).
+ *
+ * Concurrency contract: **last writer wins**. Unique swap names remove the
+ * `ENOENT` and the byte-level clobber, but overlapping calls on one path still
+ * race on which value lands last. `updateFile` does not serialize, and callers
+ * needing a serialization guarantee must supply their own — an in-process queue
+ * would not provide one across processes anyway.
+ *
+ * The target's mode is read before the write and reapplied to the swap file, so
+ * the rename does not widen a deliberately restrictive file (a `0600` database
+ * would otherwise become `0666 & ~umask`). It is applied to the open file
+ * *descriptor*, never to the swap path: a path-based `chmod` follows symlinks,
+ * so an attacker holding write access to the directory could hijack the swap
+ * path mid-write and have the mode land on a file of their choosing. Other
+ * inode-bound metadata — ACLs, extended attributes, hard links, ownership — is
+ * *not* carried across; the target gets a new inode by construction.
+ *
+ * `rename` is atomic against concurrent *readers*, not against power loss:
+ * there is no `fsync`, so this is namespace atomicity, not crash durability.
+ * If the target is a symlink it is replaced by a regular file — the link's
+ * destination is never written through.
+ *
+ * Swap files are cleaned up on every failure path this function controls, but
+ * a process killed between the write and the rename leaves a permanently
+ * distinct `<path>.temp-<pid>-<token>` sibling that nothing reclaims. No
+ * sweeper ships with this module; `*.temp-*` siblings of a target are safe for
+ * a consumer to delete.
+ */
 export declare function updateFile(filePath: string, data: string | Record<string, unknown>, options?: FileOptions): Promise<void>;
 interface CopyFileOptions {
     overwrite?: boolean;

package/dist/file.js

@@ -1,9 +1,9 @@
-import { getTimestamp } from './date.js';
 import { kebabCaseToCamelCase } from './string.js';
 import { objToJson } from './object.js';
 import fs from 'fs';
 import { promises as fsp } from 'fs';
 import path from 'path';
+import { randomBytes } from 'crypto';
 function isNodeError(error) {
     return error instanceof Error && 'code' in error;
 }
@@ -17,12 +17,125 @@ export async function createFile(filePath, data, options = {}) {
         throw error instanceof Error ? error : new Error(String(error));
     }
 }
+/**
+ * Atomically replace the contents of an existing file.
+ *
+ * Writes to a swap file that is a **sibling** of the target — so `rename` stays
+ * on one filesystem and therefore stays atomic — then renames it over the
+ * target. The swap name carries `process.pid` and a short random token rather
+ * than a timestamp: a whole-second token collided between concurrent callers,
+ * which made one caller throw `ENOENT` and the other silently persist bytes it
+ * had not written (abofs/stonyx-utils#44).
+ *
+ * Concurrency contract: **last writer wins**. Unique swap names remove the
+ * `ENOENT` and the byte-level clobber, but overlapping calls on one path still
+ * race on which value lands last. `updateFile` does not serialize, and callers
+ * needing a serialization guarantee must supply their own — an in-process queue
+ * would not provide one across processes anyway.
+ *
+ * The target's mode is read before the write and reapplied to the swap file, so
+ * the rename does not widen a deliberately restrictive file (a `0600` database
+ * would otherwise become `0666 & ~umask`). It is applied to the open file
+ * *descriptor*, never to the swap path: a path-based `chmod` follows symlinks,
+ * so an attacker holding write access to the directory could hijack the swap
+ * path mid-write and have the mode land on a file of their choosing. Other
+ * inode-bound metadata — ACLs, extended attributes, hard links, ownership — is
+ * *not* carried across; the target gets a new inode by construction.
+ *
+ * `rename` is atomic against concurrent *readers*, not against power loss:
+ * there is no `fsync`, so this is namespace atomicity, not crash durability.
+ * If the target is a symlink it is replaced by a regular file — the link's
+ * destination is never written through.
+ *
+ * Swap files are cleaned up on every failure path this function controls, but
+ * a process killed between the write and the rename leaves a permanently
+ * distinct `<path>.temp-<pid>-<token>` sibling that nothing reclaims. No
+ * sweeper ships with this module; `*.temp-*` siblings of a target are safe for
+ * a consumer to delete.
+ */
 export async function updateFile(filePath, data, options = {}) {
     try {
+        filePath = path.resolve(filePath);
         await fsp.access(filePath);
-        const swapFile = `${filePath}.temp-${getTimestamp()}`;
-        await fsp.writeFile(swapFile, options.json ? objToJson(data) : String(data), 'utf8');
-        await fsp.rename(swapFile, filePath);
+        // The swap file becomes the target's inode, so it has to carry the target's
+        // permission bits or a routine save silently widens them.
+        const { mode } = await fsp.stat(filePath);
+        const targetMode = mode & 0o7777;
+        // pid + random token, never a timestamp: the swap name is a uniqueness
+        // token, and whole seconds cannot discriminate between concurrent callers.
+        // The token is deliberately short — a full 36-char UUID pushed the name
+        // overhead to 48 characters and made ~210-character basenames fail
+        // ENAMETOOLONG on a 255-byte NAME_MAX. 6 CSPRNG bytes as base64url is 8
+        // characters carrying 48 bits, where the first 8 hex characters of a UUID
+        // would be the same width but only 32 bits; at 32 bits a 1000-sample
+        // distinctness check collides about once in 8,600 runs. `wx` below makes
+        // any residual collision loud rather than corrupting.
+        const swapFile = `${filePath}.temp-${process.pid}-${randomBytes(6).toString('base64url')}`;
+        // Which stage failed, so the catch can tell "the open collided" from "the
+        // open succeeded and something later failed" — see the catch.
+        let created = false;
+        try {
+            // `wx` turns any residual name collision into a loud EEXIST rather than a
+            // silent overwrite of another caller's swap bytes. `mode` here is masked
+            // by the umask, so it only narrows — the fchmod below sets the exact bits.
+            //
+            // The open is deliberately separate from the write. Everything after this
+            // line addresses the *descriptor*, never the path again, so an attacker
+            // with write access to the directory cannot redirect it: unlinking the
+            // swap path and replacing it with a symlink after this point leaves the
+            // handle bound to the original inode. `fsp.chmod(swapFile, ...)` on the
+            // path did not have that property — it followed such a symlink and
+            // widened an arbitrary victim file with this process's privileges
+            // (abofs/stonyx-utils#45, Phase 3 HIGH-3).
+            const handle = await fsp.open(swapFile, 'wx', targetMode);
+            created = true;
+            try {
+                await handle.writeFile(options.json ? objToJson(data) : String(data), 'utf8');
+                // fchmod(2) on the descriptor, not chmod(2) on the path. Needed at all
+                // because the `mode` above is umask-masked and therefore only narrows:
+                // a 0666 target would come back 0644 under the usual 022.
+                await handle.chmod(targetMode);
+            }
+            catch (writeError) {
+                await handle.close().catch(() => { });
+                throw writeError;
+            }
+            // Not in a `finally`: a close failure is a write failure (the flush can
+            // land here), so it has to surface rather than be swallowed — which is
+            // what `fsp.writeFile` did when it owned this close.
+            await handle.close();
+            await fsp.rename(swapFile, filePath);
+        }
+        catch (swapError) {
+            // Leave no orphan behind, and never let the cleanup mask the real error.
+            //
+            // Exactly one case is not ours to remove: the `wx` open lost a race, so
+            // the swap file is another writer's and unlinking it would reintroduce
+            // #44.
+            //
+            // The stage is the half that decides it, and only because `created` is
+            // set the instant the `wx` open returns. That is the sole reading of the
+            // stage that means "this call owns the path": a flag set after the write
+            // instead would answer "did the write finish?", and an ENOSPC mid-write
+            // would take the skip path and reinstate the orphaned partial payload
+            // this PR exists to close. Splitting `writeFile` into an `open` and a
+            // write is what makes the correct reading expressible at all.
+            //
+            // The code half is kept as a narrowing guard, not because the stage is
+            // insufficient. Measured: mutating this to `!created` alone survives the
+            // suite, because `O_EXCL` cannot create and then fail, so a false
+            // `created` means no file exists and the unlink would be a no-op anyway.
+            // It earns its place by refusing to widen if the open and the write are
+            // ever re-merged — and note that the code alone does *not* hold up:
+            // mutating to the code alone reds `an EEXIST raised after the swap file
+            // was created is still cleaned up`, because `rename` surfaces EEXIST on
+            // Windows and some network filesystems and that file is one we created.
+            const lostTheOpenRace = !created && isNodeError(swapError) && swapError.code === 'EEXIST';
+            if (!lostTheOpenRace) {
+                await fsp.unlink(swapFile).catch(() => { });
+            }
+            throw swapError;
+        }
     }
     catch (error) {
         throw error instanceof Error ? error : new Error(String(error));

package/package.json

@@ -3,7 +3,7 @@
   "keywords": [
     "stonyx-module"
   ],
-  "version": "0.2.3-beta.26",
+  "version": "0.2.3-beta.27",
   "description": "Utils module for Stonyx Framework",
   "repository": {
     "type": "git",