dsh-usage-badge 0.1.5 → 0.1.7

package/lib/index.js

@@ -22,7 +22,8 @@ import { join } from 'node:path'
 
 import { createCacheStore } from './cache-store.js'
 import { createAggregator, mergeRecords, resolveDshHome } from './fold.js'
-import { SyncEngine, acquireLock, readSyncDocument, releaseLock, safeDeviceId } from './sync.js'
+import { SyncEngine, acquireLock, lockIsStale, readLock, readSyncDocument, releaseLock, safeDeviceId } from './sync.js'
+import { normalizeWebdavUrl } from './webdav.js'
 import { describeCalendar, loadBundledTable, resolveHolidayRules } from './holidays.js'
 import { OFFICIAL_SOURCES, applyOfficialPricing, fetchOfficialPricing } from './official-pricing.js'
 import {
@@ -89,6 +90,16 @@ export const PRICING_PUSH_DELAY_MS = 3000
 /** How long after startup the first automatic sync runs, when sync is enabled. */
 export const STARTUP_SYNC_DELAY_MS = 8000
 
+/**
+ * How long a sync on the way out may take before it is told to stop.
+ *
+ * The application's whole teardown gets 5 s (`PROCESS_SHUTDOWN_TIMEOUT_MS`), and this plugin is one of
+ * several things being disposed — so it takes most of that and leaves the rest alone. Long enough for a
+ * real sync against a reachable server (a few hundred milliseconds for a month of changes), short enough
+ * that quitting never feels stuck.
+ */
+export const EXIT_SYNC_BUDGET_MS = 3500
+
 /**
  * How long the panel waits for a status read before it is told the answer is not ready.
  *
@@ -454,6 +465,23 @@ function readPricing(paths) {
 }
 
 /** Read a request body, bounded. An oversized one is a 413, not a server error. */
+/**
+ * Read a JSON request body, reporting a malformed one as the caller's mistake.
+ *
+ * A bare `JSON.parse` throws a `SyntaxError` with no status, which the route wrapper can only answer with a
+ * 500 — and a 500 for a body the client got wrong sends whoever is debugging it looking at the host.
+ */
+async function readJsonBody(req) {
+  const text = (await readBody(req)) || '{}'
+  try {
+    return JSON.parse(text)
+  } catch (error) {
+    const bad = new Error(`the request body is not JSON: ${error?.message ?? error}`)
+    bad.statusCode = 400
+    throw bad
+  }
+}
+
 function readBody(req) {
   return new Promise((resolvePromise, rejectPromise) => {
     const chunks = []
@@ -648,6 +676,7 @@ export function apply(ctx) {
    * forgotten key away from putting a credential in an HTTP response.
    */
   function safeSyncConfig(config = {}) {
+    const ha1 = String(config.ha1 ?? '')
     return {
       enabled: Boolean(config.enabled),
       url: String(config.url ?? ''),
@@ -658,8 +687,15 @@ export function apply(ctx) {
       deviceLabel: String(config.deviceLabel ?? ''),
       windowYears: Number(config.windowYears) || 0,
       instanceId: String(config.instanceId ?? ''),
-      hasCredential: Boolean(config.ha1 || config.passwordHash || config.password),
-      credentialPrefix: config.ha1 ? `${String(config.ha1).slice(0, 6)}…` : '',
+      // Defaults are `true`, so an existing `sync.json` that predates these fields reads as "both on" —
+      // which is what the design promises: sync, once switched on, keeps itself current.
+      onStart: config.onStart !== false,
+      onExit: config.onExit !== false,
+      hasCredential: Boolean(ha1),
+      // Only a real HA1 counts. `password` and `passwordHash` are fields an older build could leave behind,
+      // and `connect()` cannot use either — claiming a credential exists would enable 立即同步 and then
+      // fail with "no WebDAV credential is configured" the moment it was pressed.
+      credentialPrefix: ha1.length >= 16 ? `${ha1.slice(0, 6)}…` : '',
     }
   }
 
@@ -692,28 +728,64 @@ export function apply(ctx) {
     }
   }
 
+  /**
+   * Every piece of work that talks to the server goes through one queue.
+   *
+   * The owner lock keeps two **processes** apart; inside one process it cannot, because the host holds it for
+   * its whole life. Without this, 立即同步 and the automatic price push run as two independent chains: a run's
+   * `PROPFIND` and a push's `GET pricing.json` would already be interleaving on the wire (measured), and both
+   * mutate the same `engine.state` and rewrite `sync.json`, so whichever finishes last decides what the panel
+   * says about the other.
+   */
+  function enqueue(instance, work) {
+    const next = (instance.chain ?? Promise.resolve()).then(work, work)
+    // The chain must survive a rejection — neither breaking on it nor leaving it unhandled.
+    instance.chain = next.then(
+      () => {},
+      () => {},
+    )
+    return next
+  }
+
   async function syncStatus() {
-    // Reading the status must not create anything either, so an untouched install answers with the
-    // sensible defaults rather than acquiring a lock it has no intention of using.
+    // Reading the status must not create anything: someone opening the tab to see what it says has not
+    // decided to use sync yet. So the system (and with it the lock and `sync.json`) is only created by an
+    // action that actually decides something — save, test, run — and this branch answers from the files on
+    // disk plus a **read** of the lock.
     if (!system) {
       const document = readSyncDocument(dataDir, log)
+      const state = document.state ?? {}
+      const pulled = {}
+      for (const context of Object.keys(state.held ?? {})) {
+        const device = context.split('/')[0]
+        pulled[device] = (pulled[device] ?? 0) + 1
+      }
+      // Whose lock is it? Answering "may this instance write" takes no writing: `readLock` looks, and this
+      // mirrors exactly what `acquireLock` would decide — **any** live lock blocks, including one this same
+      // pid holds, because that is the answer `acquireLock` gives and the panel must not promise a write the
+      // engine would then refuse. A stale lock is not a block: it would be taken over.
+      const owner = readLock(dataDir)
+      const blocking = owner && !lockIsStale(owner) ? owner : null
       return {
-        config: safeSyncConfig({ ...document, hasCredential: Boolean(document.ha1 || document.passwordHash || document.password) }),
-        writable: true,
-        lock: null,
+        config: safeSyncConfig(document),
+        writable: !blocking,
+        lock: blocking ? { reason: `this data directory is open by another DSH instance (pid ${blocking.pid} on ${blocking.hostname || 'this host'})`, owner: blocking, pid: process.pid } : null,
         running: false,
         last: {
-          result: document.state?.lastResult || 'never',
-          message: document.state?.message ?? '',
-          at: Number(document.state?.lastSyncAt) || 0,
+          result: state.lastResult || 'never',
+          message: state.message ?? '',
+          at: Number(state.lastSyncAt) || 0,
         },
-        collision: document.state?.collision ?? null,
-        remoteDevices: {},
+        collision: state.collision ?? null,
+        // From the persisted state, so a home that has published before still shows what it published —
+        // none of this needs the lock.
+        remoteDevices: pulled,
         // `null` rather than `{}`: nothing has asked the server yet, and an empty map would read as "there
         // are no other devices".
         remoteKnown: false,
         remoteError: null,
-        published: {},
+        remoteDevicesOnServer: null,
+        published: state.published ?? {},
         conflictFiles: conflictFiles(),
         paths: { sync: join(dataDir, 'sync.json'), pricing: pricingPath },
       }
@@ -757,7 +829,7 @@ export function apply(ctx) {
   function runSync() {
     const instance = syncSystem()
     if (!instance.running) {
-      instance.running = (async () => {
+      instance.running = enqueue(instance, async () => {
         if (!instance.engine.store) {
           // The cache is read-only here (another instance holds the lock, a permission problem, a newer
           // schema). The sync would publish a history this process cannot even fold, so it declines
@@ -794,7 +866,7 @@ export function apply(ctx) {
           return { result: 'failed', message: String(error?.message ?? error), at: 0 }
         }
         // Nothing to release: the lock belongs to the system and lives as long as this process does.
-      })()
+      })
         .then((result) => {
           instance.last = { result: result.result, message: result.message, at: result.at ?? 0 }
           return result
@@ -863,11 +935,9 @@ export function apply(ctx) {
       pricingPushTimer = null
       const instance = syncSystem()
       if (!instance.lock?.acquired || !instance.engine.store) return
-      // Chained onto the same queue as a full run, so an edit landing mid-sync waits rather than
-      // interleaving PUTs with it. The result is recorded like any other outcome: an edit whose publish
-      // failed is exactly the thing the person would otherwise never learn about.
-      instance.pushing = (instance.pushing ?? Promise.resolve())
-        .then(() => instance.engine.pushPricing({ lock: instance.lock, instanceId: instance.instanceId }))
+      // Onto the **same** queue as a full run, so an edit landing mid-sync waits for it instead of
+      // interleaving its PUTs and its `sync.json` write with the run's.
+      instance.pushing = enqueue(instance, () => instance.engine.pushPricing({ lock: instance.lock, instanceId: instance.instanceId }))
         .then((result) => {
           log(`pricing pushed after an edit: ${result.result} — ${result.status}`)
           instance.last = { result: result.result, message: `prices: ${result.status}`, at: result.result === 'ok' ? Number(instance.engine.state.lastSyncAt) || 0 : instance.last?.at ?? 0 }
@@ -895,6 +965,10 @@ export function apply(ctx) {
   function scheduleStartupSync(delayMs = delayFor('DSH_USAGE_BADGE_STARTUP_SYNC_MS', STARTUP_SYNC_DELAY_MS)) {
     const configured = readSyncDocument(dataDir, log)
     if (!configured.enabled || !configured.url || !configured.ha1) return
+    if (configured.onStart === false) {
+      log('startup sync is switched off')
+      return
+    }
     const timer = setTimeout(() => {
       startupSyncTimer = null
       const instance = syncSystem()
@@ -909,6 +983,56 @@ export function apply(ctx) {
   }
   let startupSyncTimer = null
 
+  /**
+   * A last sync on the way out, awaited — but only for as long as there is time.
+   *
+   * DSH gives the whole application teardown **5 seconds** (`PROCESS_SHUTDOWN_TIMEOUT_MS` in the runtime)
+   * before it exits the host process outright, and the desktop then waits up to 10 more for the child to go.
+   * So the chain that reaches this function is: desktop asks the host to shut down → the host awaits its own
+   * disposal → cordis disposes this plugin's effects, awaiting what they return. Returning a promise here is
+   * what makes the sync happen at all instead of being cut off mid-request.
+   *
+   * The budget is what keeps that promise from becoming a slow quit: past it the run is told to stop at its
+   * next step boundary (nothing half-written — uploads go through a temporary name and the manifest is
+   * written last) and the disposal returns. A sync that did not finish is reported as such, not pretended.
+   */
+  async function syncOnExit() {
+    // Read the configuration from disk when this session never touched sync: a home configured in an earlier
+    // session, quit without opening the panel, still has to sync. Creating the system here is also what takes
+    // the lock — and the store is still open at this point (the disposer closes it afterwards).
+    const document = system?.engine?.config ?? readSyncDocument(dataDir, log)
+    if (!document.enabled || !document.url || !document.ha1) return
+    if (document.onExit === false) {
+      log('exit sync is switched off')
+      return
+    }
+    const instance = syncSystem()
+    if (!instance.engine.store) return
+    if (!instance.lock?.acquired) {
+      log(`exit sync skipped: ${instance.lock?.reason ?? 'no lock'}`)
+      return
+    }
+    const budget = delayFor('DSH_USAGE_BADGE_EXIT_SYNC_MS', EXIT_SYNC_BUDGET_MS)
+    if (budget <= 0) {
+      // A zero budget means "there is no time for this" — the switch a test or a debugging session uses.
+      log('exit sync skipped: no time budget')
+      return
+    }
+    let timer = null
+    const deadline = new Promise((resolve) => {
+      timer = setTimeout(() => resolve('deadline'), budget)
+      timer.unref?.()
+    })
+    const outcome = await Promise.race([runSync().then((result) => result ?? 'done', () => 'failed'), deadline])
+    clearTimeout(timer)
+    if (outcome === 'deadline') {
+      instance.engine.abort()
+      log(`exit sync did not finish within ${budget}ms; it stops at its next step boundary`)
+      return
+    }
+    log(`exit sync: ${instance.last?.result ?? outcome} — ${instance.last?.message ?? ''}`)
+  }
+
   async function warm() {
     try {
       const status = await refreshOnce()
@@ -1018,7 +1142,7 @@ export function apply(ctx) {
           sendJson(res, 403, { error: 'config writes are accepted from loopback clients only' })
           return
         }
-        const patch = JSON.parse((await readBody(req)) || '{}')
+        const patch = await readJsonBody(req)
         commitPricing(mergeConfig(readRawPricing(pricingPaths).raw, patch))
         log('pricing config updated')
         sendJson(res, 200, { ok: true, effective: pricing, calendar: describeCalendar(rules) })
@@ -1039,7 +1163,7 @@ export function apply(ctx) {
           sendJson(res, 403, { error: 'config writes are accepted from loopback clients only' })
           return
         }
-        const body = JSON.parse((await readBody(req)) || '{}')
+        const body = await readJsonBody(req)
         // Apply the copy the user was looking at, reusing the recent fetch rather
         // than pulling a possibly different page under them.
         const parsed = await officialPricing(body.source ?? 'zh-cn')
@@ -1072,14 +1196,15 @@ export function apply(ctx) {
       // plus a `hasCredential` flag, so the state of "is one configured" is visible without the secret
       // leaving the host half.
       if (route === '/sync' && req.method === 'GET') {
-        // Loopback only, like every other sync route. The answer names the server and the account, and
-        // reading it *is* engaging with sync — this is where the system comes into being, and with it the
-        // owner lock. A page that never opens this tab still touches nothing.
+        // Loopback only, like every other sync route: the answer names the server and the account.
+        //
+        // **And it creates nothing.** Opening the tab is looking, not deciding — so this no longer takes the
+        // lock or writes `sync.json`; the system comes into being when something is saved, tested or run.
+        // `writable` is still answered honestly, by reading the lock file rather than writing one.
         if (!isLoopback(req)) {
           sendJson(res, 403, { error: 'the sync status is visible to loopback clients only' })
           return
         }
-        syncSystem()
         let body
         try {
           body = await withTimeout(syncStatus(), STATUS_TIMEOUT_MS, 'reading the sync status')
@@ -1097,11 +1222,16 @@ export function apply(ctx) {
           return
         }
         const instance = syncSystem()
-        const patch = JSON.parse((await readBody(req)) || '{}')
+        const patch = await readJsonBody(req)
         const config = {}
-        for (const field of ['enabled', 'url', 'username', 'allowInsecureTls', 'deviceLabel', 'deviceId', 'realm']) {
+        for (const field of ['enabled', 'url', 'username', 'deviceLabel', 'deviceId', 'realm']) {
           if (patch[field] !== undefined) config[field] = patch[field]
         }
+        // The switches, coerced: a panel sends booleans, but a hand-written request may send 0/1, and a
+        // stored `"false"` string would otherwise read as *on* (it is not `false`).
+        for (const field of ['allowInsecureTls', 'onStart', 'onExit']) {
+          if (patch[field] !== undefined) config[field] = patch[field] !== false && patch[field] !== 'false' && patch[field] !== 0
+        }
         if (patch.windowYears !== undefined) config.windowYears = Math.max(0, Math.min(50, Number(patch.windowYears) || 0))
         if (typeof patch.deviceId === 'string' && patch.deviceId !== '') {
           try {
@@ -1132,12 +1262,19 @@ export function apply(ctx) {
           config.ha1 = patch.ha1.toLowerCase()
         }
         if (typeof config.url === 'string' && config.url !== '') {
-          try {
-            new URL(config.url)
-          } catch {
-            sendJson(res, 400, { error: `the WebDAV URL is not a URL: ${config.url}` })
+          // The **same** judgement the client makes, from the same function. A copy here is what let the
+          // route accept a query string, embedded credentials and `ftp:` — addresses the client refuses —
+          // so the panel stored one, showed it, and the sync could not run at all. Two copies of a rule
+          // drift; one copy cannot.
+          const judged = normalizeWebdavUrl(config.url)
+          if (!judged.ok) {
+            sendJson(res, 400, { error: judged.reason })
             return
           }
+          // The trailing slash is **added** rather than demanded: someone typing `host:port` means the
+          // collection at that address. The panel stores what this returns, so the field ends up showing
+          // the address that will actually be used instead of the one that was typed.
+          config.url = judged.url
         }
         instance.engine.save({ config })
         log(`sync configuration updated (${instance.engine.config.enabled ? 'on' : 'off'}, device ${instance.engine.config.deviceId})`)
@@ -1151,8 +1288,13 @@ export function apply(ctx) {
           sendJson(res, 403, { error: 'sync writes are accepted from loopback clients only' })
           return
         }
+        // The client is kept across the catch so a **failure** can still report the realm the server
+        // announced. That realm is the missing piece when someone's server does not use `WebDAV`: the
+        // password was hashed against the default, so nothing can work until it is re-hashed against the
+        // real one — and without this the panel had no way to learn it.
+        let client = null
         try {
-          const client = syncSystem().engine.connect()
+          client = syncSystem().engine.connect()
           const options = await client.options()
           const devices = await syncSystem().engine.discover(client)
           sendJson(res, 200, {
@@ -1164,7 +1306,7 @@ export function apply(ctx) {
             warning: client.insecureWarning ?? null,
           })
         } catch (error) {
-          sendJson(res, 200, { ok: false, error: String(error?.message ?? error) })
+          sendJson(res, 200, { ok: false, error: String(error?.message ?? error), realm: client?.challenge?.realm ?? null })
         }
         return
       }
@@ -1198,23 +1340,52 @@ export function apply(ctx) {
     // asynchronous, and a value read after it would be whatever the environment holds by then — which a
     // test that sets an override for exactly this mount would already have taken away.
     const startupDelay = delayFor('DSH_USAGE_BADGE_STARTUP_SYNC_MS', STARTUP_SYNC_DELAY_MS)
+    // Unloading before the first fold finishes used to schedule the first sync *after* the unload: the
+    // callback ran anyway, took the lock back, and synced through a store that had already been closed
+    // (`statement has been finalized`), leaving a lock file behind for a host that was gone.
+    let disposed = false
     void warm().then(() => {
+      if (disposed) return
       scheduleStartupSync(startupDelay)
       // Fire and forget: this only fills in what the server holds, for the panel's next read.
       void refreshRemoteDevices()
     })
-    return () => {
+    // The disposer is **async on purpose**, and everything below depends on the order:
+    //
+    //   1. stop automatic work that would fire into a process that is going away;
+    //   2. sync once, while the store is still open (a sync reads it) and while we still own the lock;
+    //   3. hand the lock back and close the store.
+    //
+    // Returning a promise is what makes step 2 real: DSH awaits the host's teardown, cordis awaits what an
+    // effect's disposer returns, and the runtime force-exits only after 5 s. So this is not "fire and hope";
+    // it is synchronised with the shutdown — and bounded, so a slow server cannot hold up quitting.
+    return async () => {
+      disposed = true
       // Any pending automatic work is dropped on unload: a push that fires while the host is going away
       // would write state for a process that no longer exists.
       if (pricingPushTimer) clearTimeout(pricingPushTimer)
       if (startupSyncTimer) clearTimeout(startupSyncTimer)
-      // **And the lock is handed back.** Not releasing it leaves `host.lock` naming this dead process,
-      // and a re-mount inside the same process — a hot reload, or a test mounting the same home twice —
-      // is then refused by this plugin's own lock, for a pid that is very much alive: its own.
+      if (system?.running) log('unloading while a sync is in flight; it stops at its next step boundary')
+      try {
+        await syncOnExit()
+      } catch (error) {
+        log(`exit sync failed: ${error?.message ?? error}`)
+      }
+      // **And the lock is handed back.** Not releasing it leaves `host.lock` naming this dead process, and a
+      // re-mount inside the same process — a hot reload, or a test mounting the same home twice — is then
+      // refused by this plugin's own lock, for a pid that is very much alive: its own.
+      //
+      // `engine.release()` alone is not enough: a run in flight was handed the host's lock object, and the
+      // engine only releases one it acquired itself (`ownsLock`), so unloading mid-run would leave the file
+      // behind. `releaseLock` checks the pid, so this can only ever remove our own.
       if (system) {
         system.syncAbort = true
+        // Stops a run at its next step boundary. Requests already on the wire finish; the phases that would
+        // touch the store do not start.
+        system.engine.abort()
         system.engine.release()
       }
+      releaseLock(dataDir)
       aggregator.close()
     }
   }, 'usage-badge: warm the fold, schedule the first sync, and close the cache on unload')