fix(storage): write atomically via temp+rename and report write failures

Author: antfubot

packages/devframe/src/node/__tests__/storage.test.ts

@@ -40,4 +40,67 @@ describe('createStorage', () => {
       fs.rmSync(dir, { recursive: true, force: true })
     }
   })
+
+  it('writes atomically via temp file + rename', async () => {
+    const dir = fs.mkdtempSync(join(os.tmpdir(), 'devframe-storage-'))
+    const filepath = join(dir, 'state.json')
+
+    try {
+      const state = createStorage({
+        filepath,
+        initialValue: { count: 1 },
+        debounce: 0,
+      })
+
+      state.mutate((draft) => {
+        draft.count = 2
+      })
+
+      await wait(20)
+
+      // no leftover temp file
+      const entries = fs.readdirSync(dir)
+      expect(entries).toEqual(['state.json'])
+
+      const saved = JSON.parse(fs.readFileSync(filepath, 'utf-8'))
+      expect(saved).toEqual({ count: 2 })
+    }
+    finally {
+      fs.rmSync(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('reports a write failure instead of throwing', async () => {
+    const dir = fs.mkdtempSync(join(os.tmpdir(), 'devframe-storage-'))
+    const filepath = join(dir, 'state.json')
+
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const renameSpy = vi.spyOn(fs, 'renameSync').mockImplementation(() => {
+      throw new Error('EACCES: permission denied')
+    })
+
+    try {
+      const state = createStorage({
+        filepath,
+        initialValue: { count: 1 },
+        debounce: 0,
+      })
+
+      expect(() => {
+        state.mutate((draft) => {
+          draft.count = 2
+        })
+      }).not.toThrow()
+
+      await wait(20)
+
+      expect(errorSpy).toHaveBeenCalled()
+      expect(fs.existsSync(filepath)).toBe(false)
+    }
+    finally {
+      renameSpy.mockRestore()
+      errorSpy.mockRestore()
+      fs.rmSync(dir, { recursive: true, force: true })
+    }
+  })
 })

packages/devframe/src/node/diagnostics.ts

@@ -64,5 +64,9 @@ export const diagnostics = defineDiagnostics({
         `Scoped RPC registration for namespace "${p.namespace}" received an already-namespaced function name "${p.name}".`,
       fix: 'A scoped context auto-namespaces ids. Pass a bare name without a ":" separator (e.g. `register({ name: "get-cwd" })`), or use the unscoped `ctx.base.rpc.register` for a fully-qualified name.',
     },
+    DF0035: {
+      why: (p: { filepath: string }) => `Failed to persist storage file: ${p.filepath}`,
+      fix: 'Check that the storage directory is writable and has free space.',
+    },
   },
 })

packages/devframe/src/node/storage.ts

@@ -1,4 +1,5 @@
 import fs from 'node:fs'
+import process from 'node:process'
 import { destr } from 'destr'
 import { createSharedState } from 'devframe/utils/shared-state'
 import { dirname } from 'pathe'
@@ -39,8 +40,16 @@ export function createStorage<T extends object>(options: CreateStorageOptions<T>
   state.on(
     'updated',
     debounce((newState) => {
-      fs.mkdirSync(dirname(options.filepath), { recursive: true })
-      fs.writeFileSync(options.filepath, `${JSON.stringify(newState, null, 2)}\n`)
+      try {
+        const dir = dirname(options.filepath)
+        fs.mkdirSync(dir, { recursive: true })
+        const tmp = `${options.filepath}.${process.pid}.tmp`
+        fs.writeFileSync(tmp, `${JSON.stringify(newState, null, 2)}\n`)
+        fs.renameSync(tmp, options.filepath) // atomic replace on same filesystem
+      }
+      catch (error) {
+        diagnostics.DF0035({ filepath: options.filepath, cause: error }, { method: 'error' })
+      }
     }, debounceTime),
   )