dsh-pause-resume 0.1.0 → 0.2.0

package/lib/snapshot.js

@@ -1,93 +1,136 @@
-import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeSync } from 'node:fs'
-import { join } from 'node:path'
+import * as fs from 'node:fs'
+import { dirname, join } from 'node:path'
 
 /**
- * The one durable fact this plugin owns: a snapshot of the work a press stopped, plus a journal
- * of what the following restore already put back.
+ * The durable half of the pause button: one plan file, a per-plan restore journal, one archive per
+ * consumed plan, and the last restore record.
  *
- * Every write is temp-file + fsync + rename, so a reader never sees half a snapshot and a crash
- * leaves the previous complete one in place. Nothing here throws: a disk that cannot be written
- * is reported as `null`, and the caller decides to stay in its current phase instead of claiming
- * a state it could not record.
+ * Every write is temp file + fsync + rename + directory fsync, so a reader never sees half a plan
+ * and a crash leaves the previous complete file in place. Nothing here throws: a disk that cannot
+ * be written answers `null`, and the caller decides whether to stay in its current phase instead
+ * of claiming a state it could not record.
  */
-export function createStore(dir) {
-  const file = join(dir, 'snapshot.json')
-  const journal = join(dir, 'restore.jsonl')
-  const consumed = join(dir, 'last-restore.json')
-  let ready = false
-
-  function ensure() {
-    if (ready) return true
+
+const UNSAFE = /[^A-Za-z0-9._-]/gu
+
+let counter = 0
+
+function sanitize(value) {
+  const name = String(value ?? '').replace(UNSAFE, '_')
+  return name === '' ? '_' : name
+}
+
+function closeQuietly(fsv, fd) {
+  try {
+    fsv.closeSync(fd)
+  } catch {}
+}
+
+export function createStore(dir, options = {}) {
+  const fsv = options.fs ?? fs
+  const now = typeof options.now === 'function' ? options.now : Date.now
+  const log = typeof options.log === 'function' ? options.log : () => {}
+
+  const snapshotPath = join(dir, 'snapshot.json')
+  const journalDir = join(dir, 'journal')
+  const restoresDir = join(dir, 'restores')
+  const lastRestorePath = join(dir, 'last-restore.json')
+
+  const journalPath = (planId) => join(journalDir, `${sanitize(planId)}.jsonl`)
+
+  /** Flush a directory entry, so the rename that just happened survives a power loss too. */ // ui-copy-ignore
+  function syncDir(path) {
+    let fd = null
     try {
-      mkdirSync(dir, { recursive: true })
-      ready = true
-      return true
-    } catch {
-      return false
+      fd = fsv.openSync(path, 'r')
+      fsv.fsyncSync(fd)
+    } finally {
+      if (fd !== null) closeQuietly(fsv, fd)
     }
   }
 
-  function read() {
+  function atomicWrite(target, value) {
+    let body = null
     try {
-      const raw = readFileSync(file, 'utf8')
-      const parsed = JSON.parse(raw)
-      if (parsed === null || typeof parsed !== 'object') return null
-      if (parsed.version !== 1) return null
-      if (parsed.status !== 'paused' && parsed.status !== 'pausing') return null
-      return parsed
-    } catch {
-      return null
+      body = JSON.stringify(value)
+    } catch (error) {
+      log(`cannot serialize ${target}: ${error?.message ?? error}`)
+      return false
     }
-  }
-
-  function write(value) {
-    if (!ensure()) return null
-    const body = JSON.stringify({ ...value, version: 1 })
-    const tmp = `${file}.${process.pid}.tmp`
+    const tmp = `${target}.${process.pid}.${counter++}.tmp`
     let fd = null
+    let renamed = false
     try {
-      fd = openSync(tmp, 'w')
-      writeSync(fd, body)
-      fsyncSync(fd)
-      closeSync(fd)
+      fsv.mkdirSync(dirname(target), { recursive: true })
+      fd = fsv.openSync(tmp, 'w')
+      fsv.writeSync(fd, body)
+      fsv.fsyncSync(fd)
+      const opened = fd
       fd = null
-      renameSync(tmp, file)
-      return value
-    } catch {
-      if (fd !== null) {
+      fsv.closeSync(opened)
+      fsv.renameSync(tmp, target)
+      renamed = true
+      syncDir(dirname(target))
+      return true
+    } catch (error) {
+      log(`cannot write ${target}: ${error?.message ?? error}`)
+      return false
+    } finally {
+      if (fd !== null) closeQuietly(fsv, fd)
+      if (renamed === false) {
         try {
-          closeSync(fd)
+          fsv.rmSync(tmp, { force: true })
         } catch {}
       }
-      try {
-        rmSync(tmp, { force: true })
-      } catch {}
+    }
+  }
+
+  function read() {
+    let parsed = null
+    try {
+      parsed = JSON.parse(fsv.readFileSync(snapshotPath, 'utf8'))
+    } catch {
       return null
     }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return null
+    if (parsed.version !== 2) return null
+    if (parsed.status !== 'pausing' && parsed.status !== 'paused') return null
+    return parsed
+  }
+
+  function write(plan) {
+    if (plan === null || typeof plan !== 'object' || Array.isArray(plan)) return null
+    const record = { ...plan, version: 2 }
+    return atomicWrite(snapshotPath, record) ? record : null
   }
 
-  /** The snapshot is spent: the same press must not restore the same work twice. */
-  function consume(summary) {
-    if (!ensure()) return null
+  function appendJournal(planId, key) {
+    let line = null
     try {
-      const current = read()
-      const record = current === null ? { status: 'restored' } : { ...current, status: 'restored', restoredAt: new Date().toISOString(), summary }
-      const tmp = `${consumed}.${process.pid}.tmp`
-      writeSync(openSync(tmp, 'w'), JSON.stringify(record))
-      renameSync(tmp, consumed)
-    } catch {}
+      line = JSON.stringify({ k: key })
+    } catch {
+      return false
+    }
+    let fd = null
     try {
-      rmSync(file, { force: true })
-    } catch {}
-    return summary
+      fsv.mkdirSync(journalDir, { recursive: true })
+      fd = fsv.openSync(journalPath(planId), 'a')
+      fsv.writeSync(fd, `${line}\n`)
+      fsv.fsyncSync(fd)
+      return true
+    } catch (error) {
+      log(`cannot journal ${planId}: ${error?.message ?? error}`)
+      return false
+    } finally {
+      if (fd !== null) closeQuietly(fsv, fd)
+    }
   }
 
-  /** Journals are append-only lines of `{"k":"s:<id>"}`; a torn last line is dropped on read. */
-  function readJournal() {
+  function readJournal(planId) {
     const done = new Set()
     let raw = ''
     try {
-      raw = readFileSync(journal, 'utf8')
+      raw = fsv.readFileSync(journalPath(planId), 'utf8')
     } catch {
       return done
     }
@@ -96,38 +139,60 @@ export function createStore(dir) {
       try {
         const row = JSON.parse(line)
         if (typeof row?.k === 'string') done.add(row.k)
-      } catch {}
+      } catch {
+        // A torn last line is a write that never finished, not a key that was restored.
+      }
     }
     return done
   }
 
-  function appendJournal(key) {
-    if (!ensure()) return false
+  function clearJournal(planId) {
     try {
-      writeSync(openSync(journal, 'a'), `${JSON.stringify({ k: key })}\n`)
-      return true
-    } catch {
-      return false
-    }
+      fsv.rmSync(journalPath(planId), { force: true })
+    } catch {}
   }
 
-  function clearJournal() {
-    try {
-      rmSync(journal, { force: true })
-    } catch {}
+  /**
+   * The plan is spent: archive it, publish the record the UI reads, and only then remove it. A plan
+   * that could not be archived stays on disk, so the same work is never claimed twice.
+   */
+  function consume(plan, summary) {
+    const source = plan !== null && typeof plan === 'object' && !Array.isArray(plan) ? plan : {}
+    const archivePath = join(restoresDir, `${sanitize(source.planId)}.json`)
+    const record = { ...source, status: 'restored', restoredAt: new Date(now()).toISOString(), summary }
+    const archived = atomicWrite(archivePath, record)
+    const published = archived && atomicWrite(lastRestorePath, record)
+    if (published === false) {
+      log('cannot archive the restored plan: the snapshot stays')
+      return { ok: false, archivePath: null }
+    }
+    const current = read()
+    // Another press may have written a newer plan while this one restored; that one is not ours.
+    if (current !== null && current.planId === source.planId) {
+      try {
+        fsv.rmSync(snapshotPath, { force: true })
+      } catch {}
+    }
+    clearJournal(source.planId)
+    return { ok: true, archivePath }
   }
 
   function lastRestore() {
     try {
-      return JSON.parse(readFileSync(consumed, 'utf8'))
+      const parsed = JSON.parse(fsv.readFileSync(lastRestorePath, 'utf8'))
+      return parsed !== null && typeof parsed === 'object' ? parsed : null
     } catch {
       return null
     }
   }
 
   function hasSnapshot() {
-    return existsSync(file)
+    try {
+      return fsv.existsSync(snapshotPath) === true
+    } catch {
+      return false
+    }
   }
 
-  return { dir, file, read, write, consume, readJournal, appendJournal, clearJournal, lastRestore, hasSnapshot }
+  return { dir, snapshotPath, read, write, appendJournal, readJournal, clearJournal, consume, lastRestore, hasSnapshot }
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "dsh-pause-resume",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
-  "description": "One header button stops every running turn and goal, writes a snapshot, and puts the same work back on the next boot; the button's shape is the only status.",
+  "description": "One header button stops running turns, goals and jobs, writes a plan to disk, and restores that work after a restart or crash; the button shape is the only status.",
   "license": "MIT",
   "exports": {
     ".": "./index.js",