dsh-pause-resume 0.1.0 → 0.3.0

package/lib/heartbeat.js

@@ -1,95 +1,245 @@
-import { mkdirSync, openSync, closeSync, fsyncSync, readFileSync, renameSync, writeSync } from 'node:fs'
+import * as fs from 'node:fs'
 import { join } from 'node:path'
 
 /**
  * Crash residue without reading logs.
  *
- * A snapshot only exists because a person pressed the button. A crash has no press, so this file
- * answers the other half: which sessions had a turn running a few seconds ago. It is written on a
- * timer from the same list the button already reads, and only when the set changes.
+ * A plan only exists because a person pressed the button. A crash has no press, so this file
+ * answers the other half: which sessions had a turn running a few seconds ago. It is written from
+ * the same list the button already reads, coalesced, and only when the set changes.
  *
  * The file carries the id of the process that wrote it. The same process reloading the plugin (HMR)
  * therefore sees its own heartbeat and nothing to restore, while a new process sees the previous
- * one's and offers ▶.
+ * one's and offers resume. `stop()` deliberately leaves the last heartbeat in place: it is the
+ * evidence the next process reads.
  */
-export function createHeartbeat({ dir, bootId, intervalMs = 5000, listRunning, now = () => Date.now(), log = () => {} }) {
+
+const DEBOUNCE_MS = 150
+
+let counter = 0
+
+function closeQuietly(fsv, fd) {
+  try {
+    fsv.closeSync(fd)
+  } catch {}
+}
+
+export function createHeartbeat({ dir, bootId, intervalMs = 5000, listRunning, now = () => Date.now(), fs: fsImpl = fs, log = () => {} }) {
   const file = join(dir, 'running.json')
   let timer = null
-  let last = ''
+  let noteTimer = null
   let residue = null
+  let captured = false
+  let started = false
   let stopped = false
+  let pending = []
+  let lastWritten = ''
+
+  function noteError(message) {
+    try {
+      log(message)
+    } catch {}
+  }
+
+  function normalize(ids) {
+    const rows = []
+    const seen = new Set()
+    if (Array.isArray(ids)) {
+      for (const item of ids) {
+        const sessionId = typeof item === 'string' ? item : item?.sessionId
+        if (typeof sessionId !== 'string' || sessionId === '' || seen.has(sessionId)) continue
+        seen.add(sessionId)
+        rows.push({ sessionId })
+      }
+    }
+    rows.sort((a, b) => (a.sessionId < b.sessionId ? -1 : a.sessionId > b.sessionId ? 1 : 0))
+    return rows
+  }
+
+  function serialize(rows) {
+    return JSON.stringify(rows)
+  }
+
+  function dirty() {
+    return serialize(pending) !== lastWritten
+  }
 
-  function write(sessions) {
-    const body = JSON.stringify({ version: 1, bootId, updatedAt: now(), sessions })
+  /** Flush a directory entry, so the rename that just happened survives a power loss too. */ // ui-copy-ignore
+  function syncDir(path) {
+    if (process.platform === 'win32') return // ui-copy-ignore
+    let fd = null
     try {
-      mkdirSync(dir, { recursive: true })
-      const tmp = `${file}.${process.pid}.tmp`
-      const fd = openSync(tmp, 'w')
-      try {
-        writeSync(fd, body)
-        fsyncSync(fd)
-      } finally {
-        closeSync(fd)
+      fd = fsImpl.openSync(path, 'r')
+      fsImpl.fsyncSync(fd)
+    } catch (error) {
+      // Some filesystems refuse a directory fsync after a rename that already landed. The record is
+      // published either way; only the power-loss guarantee is weaker, so this is not a failure.
+      const code = error?.code
+      if (code !== 'EPERM' && code !== 'EACCES' && code !== 'ENOTSUP' && code !== 'EINVAL' && code !== 'ENOSYS' && code !== 'EBADF' && code !== 'EISDIR') {
+        noteError(`cannot flush ${path}: ${error?.message ?? error}`)
       }
-      renameSync(tmp, file)
+    } finally {
+      if (fd !== null) closeQuietly(fsImpl, fd)
+    }
+  }
+
+  function persist(rows) {
+    let body = ''
+    try {
+      body = JSON.stringify({ version: 2, bootId, updatedAt: now(), sessions: rows })
+    } catch (error) {
+      noteError(`cannot record running sessions: ${error?.message ?? error}`)
+      return false
+    }
+    const tmp = `${file}.${process.pid}.${counter++}.tmp`
+    let fd = null
+    let renamed = false
+    try {
+      fsImpl.mkdirSync(dir, { recursive: true })
+      fd = fsImpl.openSync(tmp, 'w')
+      fsImpl.writeSync(fd, body)
+      fsImpl.fsyncSync(fd)
+      const opened = fd
+      fd = null
+      fsImpl.closeSync(opened)
+      fsImpl.renameSync(tmp, file)
+      renamed = true
+      syncDir(dir)
+      lastWritten = serialize(rows)
       return true
     } catch (error) {
-      log(`cannot record running sessions: ${error?.message ?? error}`)
+      noteError(`cannot record running sessions: ${error?.message ?? error}`)
       return false
+    } finally {
+      if (fd !== null) closeQuietly(fsImpl, fd)
+      if (renamed === false) {
+        try {
+          fsImpl.rmSync(tmp, { force: true })
+        } catch {}
+      }
     }
   }
 
-  /** Claims the previous process's heartbeat once, at start, before this process overwrites it. */
-  function capture() {
+  /**
+   * Read the previous process's record without claiming it. The caller has to read this before
+   * `start()` overwrites the file, and turning it into a durable plan may take a moment: a read that
+   * also claimed would leave the very next read empty if that write failed.
+   */
+  function peek() {
+    if (residue !== null) return residue
+    let parsed = null
     try {
-      const parsed = JSON.parse(readFileSync(file, 'utf8'))
-      if (parsed === null || typeof parsed !== 'object' || parsed.version !== 1) return null
-      if (typeof parsed.bootId === 'string' && parsed.bootId === bootId) return null
-      const sessions = Array.isArray(parsed.sessions) ? parsed.sessions.filter((row) => typeof row?.sessionId === 'string') : []
-      if (sessions.length === 0) return null
-      residue = { sessions, at: typeof parsed.updatedAt === 'number' ? parsed.updatedAt : null }
-      return residue
+      parsed = JSON.parse(fsImpl.readFileSync(file, 'utf8'))
     } catch {
       return null
     }
+    if (parsed === null || typeof parsed !== 'object') return null
+    if (typeof parsed.bootId === 'string' && parsed.bootId === bootId) return null
+    const sessions = normalize(parsed.sessions)
+    if (sessions.length === 0) return null
+    residue = { sessions, at: typeof parsed.updatedAt === 'number' ? parsed.updatedAt : null }
+    return residue
+  }
+
+  /** Claims the previous process's heartbeat exactly once, before this process overwrites it. */
+  function capture() {
+    if (captured) return residue
+    captured = true
+    return peek()
+  }
+
+  function writePending() {
+    return dirty() ? persist(pending) : true
+  }
+
+  /**
+   * Read the running set and record it. A listing that throws keeps the previous set; a dirty set
+   * left behind by a failed write is retried on the next tick.
+   */
+  function refresh(force = false) {
+    const apply = (ids) => {
+      if (ids !== null) pending = normalize(ids)
+      if (stopped === true && force !== true) return true
+      return writePending()
+    }
+    let value = null
+    try {
+      value = typeof listRunning === 'function' ? listRunning() : pending
+    } catch (error) {
+      noteError(`cannot list running sessions: ${error?.message ?? error}`)
+      return Promise.resolve(apply(null))
+    }
+    if (value !== null && typeof value?.then === 'function') {
+      return Promise.resolve(value).then(
+        (ids) => apply(ids),
+        (error) => {
+          noteError(`cannot list running sessions: ${error?.message ?? error}`)
+          return apply(null)
+        },
+      )
+    }
+    return Promise.resolve(apply(value))
+  }
+
+  /** Event hooks report a changed set: write once, after a burst, and never block the caller. */
+  function note(sessionIds) {
+    pending = normalize(sessionIds)
+    if (stopped === true || dirty() === false || noteTimer !== null) return
+    noteTimer = setTimeout(() => {
+      noteTimer = null
+      void flush()
+    }, DEBOUNCE_MS)
+    if (typeof noteTimer.unref === 'function') noteTimer.unref()
   }
 
-  async function tick() {
-    if (stopped || residue !== null) return
-    let sessions
+  function flush() {
     try {
-      sessions = await listRunning()
+      return Promise.resolve(writePending())
     } catch (error) {
-      log(`cannot list running sessions: ${error?.message ?? error}`)
-      return
+      noteError(`cannot record running sessions: ${error?.message ?? error}`)
+      return Promise.resolve(false)
     }
-    const body = JSON.stringify(sessions.map((sessionId) => ({ sessionId })))
-    if (body === last) return
-    last = body
-    write(sessions.map((sessionId) => ({ sessionId })))
   }
 
   function start() {
-    if (stopped || timer !== null) return
+    if (started) return
+    started = true
+    stopped = false
     capture()
-    void tick()
-    timer = setInterval(() => void tick(), intervalMs)
+    void refresh()
+    timer = setInterval(() => {
+      void refresh()
+    }, intervalMs)
     if (typeof timer.unref === 'function') timer.unref()
   }
 
+  function stop() {
+    stopped = true
+    if (timer !== null) {
+      clearInterval(timer)
+      timer = null
+    }
+    if (noteTimer !== null) {
+      clearTimeout(noteTimer)
+      noteTimer = null
+    }
+  }
+
   /** The residue was restored: from here on the heartbeat describes this process again. */
   function release() {
     residue = null
-    last = ''
-    write([])
+    void refresh(true)
   }
 
-  function stop() {
-    stopped = true
-    if (timer !== null) clearInterval(timer)
-    timer = null
-    if (residue === null) write([])
+  return {
+    note,
+    peek,
+    start,
+    stop,
+    release,
+    flush,
+    get residue() {
+      return residue
+    },
   }
-
-  return { start, stop, release, get residue() { return residue } }
 }