Merge pull request #185 from Travisun/feat/desktop-bootloader

feat(desktop): bootloader hook chain for startup and shutdown

Author: Travisun

apps/desktop/electron/bootloader-register.cjs

@@ -0,0 +1,100 @@
+/**
+ * Register desktop boot / shutdown hooks (wired from main.cjs).
+ * @param {ReturnType<import('./bootloader.cjs').createBootloader>} boot
+ * @param {object} deps
+ */
+'use strict'
+
+const { SIDECAR_GRACEFUL_MS } = require('./sidecar-supervisor.cjs')
+
+/**
+ * @param {ReturnType<import('./bootloader.cjs').createBootloader>} boot
+ * @param {{
+ *   initResolvedPorts: () => Promise<boolean>
+ *   tryQuickPendingUpdate: () => Promise<boolean>
+ *   tryDeferredPendingUpdate: () => Promise<void>
+ *   startSidecarHealthWatchdog: () => void
+ *   startScheduleReconcilePoll: () => void
+ *   initUpdater: () => void
+ *   maybeBootstrapOfflineModelDownloads: () => void
+ *   requestNotificationPermission: () => void
+ *   stopScheduleReconcilePoll: () => void
+ *   stopSidecarAndWait: (ms?: number) => Promise<void>
+ *   disposeTranslation: () => Promise<void> | void
+ *   destroyTray: () => void
+ *   intentionalSidecarStopRef: { current: boolean }
+ *   stopSidecarSupervision: () => void
+ * }} deps
+ */
+function registerDesktopBootloader(boot, deps) {
+  boot.clear()
+
+  boot.registerBootCritical(
+    'resolve-ports',
+    async () => {
+      const ok = await deps.initResolvedPorts()
+      if (!ok) {
+        throw new Error('无法解析本地 API 端口')
+      }
+    },
+    { timeoutMs: 20_000, required: true },
+  )
+
+  boot.registerBootCritical(
+    'pending-update-quick',
+    async (ctx) => {
+      const installing = await deps.tryQuickPendingUpdate()
+      if (installing) {
+        ctx.quittingForUpdate = true
+      }
+    },
+    { timeoutMs: 8_000, required: false },
+  )
+
+  boot.registerBootDeferred('sidecar-health-watchdog', async () => {
+    deps.startSidecarHealthWatchdog()
+  })
+
+  boot.registerBootDeferred('schedule-reconcile', async () => {
+    deps.startScheduleReconcilePoll()
+  })
+
+  boot.registerBootDeferred('updater-init', async () => {
+    deps.initUpdater()
+  })
+
+  boot.registerBootDeferred('translation-bootstrap', async () => {
+    deps.maybeBootstrapOfflineModelDownloads()
+  })
+
+  boot.registerBootDeferred('notification-permission', async () => {
+    deps.requestNotificationPermission()
+  })
+
+  boot.registerBootDeferred('pending-update-deferred', async () => {
+    await deps.tryDeferredPendingUpdate()
+  })
+
+  // Registration order = shutdown reverse (LIFO).
+  boot.registerShutdown('tray', async () => {
+    deps.destroyTray()
+  }, { timeoutMs: 2_000 })
+
+  boot.registerShutdown('translation', async () => {
+    await deps.disposeTranslation()
+  }, { timeoutMs: 4_000 })
+
+  boot.registerShutdown('sidecar', async () => {
+    deps.intentionalSidecarStopRef.current = true
+    deps.stopSidecarSupervision()
+    await deps.stopSidecarAndWait(SIDECAR_GRACEFUL_MS)
+  }, { timeoutMs: SIDECAR_GRACEFUL_MS + 3_000 })
+
+  boot.registerShutdown('schedule-poll', async () => {
+    deps.stopScheduleReconcilePoll()
+  }, { timeoutMs: 2_000 })
+}
+
+module.exports = {
+  registerDesktopBootloader,
+}

apps/desktop/electron/bootloader.cjs

@@ -0,0 +1,160 @@
+/**
+ * Desktop boot / shutdown hook runner.
+ * Pure Node — no electron at module load.
+ *
+ * - Critical boot hooks: sequential, block UI until done (per-hook timeout).
+ * - Deferred boot hooks: fire-and-forget after shell ready; never block quit.
+ * - Shutdown hooks: sequential LIFO registration order, global deadline anti-deadlock.
+ */
+'use strict'
+
+/** Default per critical boot hook budget (sidecar cold start on Windows). */
+const BOOT_CRITICAL_DEFAULT_MS = 90_000
+
+/** Per deferred hook is not awaited; this is only for logging. */
+const BOOT_DEFERRED_LABEL = 'deferred'
+
+/** Must exceed SIDECAR_GRACEFUL_MS + SIDECAR_HARD_EXTRA_MS (~16.5s). */
+const SHUTDOWN_GLOBAL_MS = 20_000
+
+/** Single shutdown hook soft budget before skip. */
+const SHUTDOWN_HOOK_DEFAULT_MS = 16_000
+
+/**
+ * @param {Promise<unknown>} promise
+ * @param {number} ms
+ * @param {string} label
+ */
+function withTimeout(promise, ms, label) {
+  if (!Number.isFinite(ms) || ms <= 0) {
+    return Promise.resolve(promise)
+  }
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`Hook timeout: ${label} (${ms}ms)`))
+    }, ms)
+    Promise.resolve(promise).then(
+      (value) => {
+        clearTimeout(timer)
+        resolve(value)
+      },
+      (err) => {
+        clearTimeout(timer)
+        reject(err)
+      },
+    )
+  })
+}
+
+/**
+ * @returns {{
+ *   registerBootCritical: (name: string, run: (ctx: object) => Promise<void> | void, opts?: { timeoutMs?: number, required?: boolean }) => void
+ *   registerBootDeferred: (name: string, run: (ctx: object) => Promise<void> | void) => void
+ *   registerShutdown: (name: string, run: (ctx: object) => Promise<void> | void, opts?: { timeoutMs?: number }) => void
+ *   runBootCritical: (ctx?: object) => Promise<void>
+ *   runBootDeferred: (ctx?: object) => void
+ *   runShutdown: (ctx?: object) => Promise<void>
+ *   clear: () => void
+ * }}
+ */
+function createBootloader() {
+  /** @type {Array<{ name: string, run: Function, timeoutMs: number, required: boolean }>} */
+  const bootCritical = []
+  /** @type {Array<{ name: string, run: Function }>} */
+  const bootDeferred = []
+  /** @type {Array<{ name: string, run: Function, timeoutMs: number }>} */
+  const shutdownHooks = []
+
+  return {
+    registerBootCritical(name, run, opts = {}) {
+      bootCritical.push({
+        name,
+        run,
+        timeoutMs: opts.timeoutMs ?? BOOT_CRITICAL_DEFAULT_MS,
+        required: opts.required !== false,
+      })
+    },
+
+    registerBootDeferred(name, run) {
+      bootDeferred.push({ name, run })
+    },
+
+    registerShutdown(name, run, opts = {}) {
+      shutdownHooks.push({
+        name,
+        run,
+        timeoutMs: opts.timeoutMs ?? SHUTDOWN_HOOK_DEFAULT_MS,
+      })
+    },
+
+    async runBootCritical(ctx = {}) {
+      for (const hook of bootCritical) {
+        const started = Date.now()
+        console.log(`[boot] critical → ${hook.name}`)
+        try {
+          await withTimeout(Promise.resolve().then(() => hook.run(ctx)), hook.timeoutMs, hook.name)
+          console.log(`[boot] critical ✓ ${hook.name} (${Date.now() - started}ms)`)
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err)
+          console.error(`[boot] critical ✗ ${hook.name}: ${msg}`)
+          if (hook.required) {
+            throw err instanceof Error ? err : new Error(msg)
+          }
+        }
+      }
+    },
+
+    runBootDeferred(ctx = {}) {
+      for (const hook of bootDeferred) {
+        void Promise.resolve()
+          .then(() => hook.run(ctx))
+          .then(() => {
+            console.log(`[boot] ${BOOT_DEFERRED_LABEL} ✓ ${hook.name}`)
+          })
+          .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err)
+            console.warn(`[boot] ${BOOT_DEFERRED_LABEL} ✗ ${hook.name}: ${msg}`)
+          })
+      }
+    },
+
+    async runShutdown(ctx = {}) {
+      const deadline = Date.now() + SHUTDOWN_GLOBAL_MS
+      console.log('[shutdown] begin')
+      // LIFO — last registered runs first (UI-adjacent before infrastructure).
+      const chain = [...shutdownHooks].reverse()
+      for (const hook of chain) {
+        const remaining = deadline - Date.now()
+        if (remaining <= 0) {
+          console.warn(`[shutdown] global deadline (${SHUTDOWN_GLOBAL_MS}ms); skip ${hook.name}`)
+          break
+        }
+        const budget = Math.min(hook.timeoutMs, remaining)
+        const started = Date.now()
+        console.log(`[shutdown] → ${hook.name}`)
+        try {
+          await withTimeout(Promise.resolve().then(() => hook.run(ctx)), budget, hook.name)
+          console.log(`[shutdown] ✓ ${hook.name} (${Date.now() - started}ms)`)
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err)
+          console.warn(`[shutdown] ✗ ${hook.name}: ${msg}`)
+        }
+      }
+      console.log('[shutdown] end')
+    },
+
+    clear() {
+      bootCritical.length = 0
+      bootDeferred.length = 0
+      shutdownHooks.length = 0
+    },
+  }
+}
+
+module.exports = {
+  createBootloader,
+  withTimeout,
+  BOOT_CRITICAL_DEFAULT_MS,
+  SHUTDOWN_GLOBAL_MS,
+  SHUTDOWN_HOOK_DEFAULT_MS,
+}