@shawnstack/quickforge 1.7.10 → 1.7.12

package/server/sqlite/share-repository.mjs

@@ -1,5 +1,5 @@
 import { createHash, randomBytes } from 'node:crypto'
-import { getSqliteStorage } from './database.mjs'
+import { getSqliteStorage, runSharedSqliteQuickCheck } from './database.mjs'
 
 // F10 share storage: `share_sessions` (strictly mapped columns + `extra_json`
 // for opaque/unknown fields) and `share_tokens` (independent token table with
@@ -301,7 +301,36 @@ function attachTokens(records, tokenRows) {
   }))
 }
 
-function insertShareRow(database, record, revision, createdAt, updatedAt) {
+const SHARE_SESSION_UPSERT_SQL = `
+  INSERT INTO share_sessions (${SHARE_COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  ON CONFLICT(share_id) DO UPDATE SET
+    session_id = excluded.session_id,
+    permission = excluded.permission,
+    title_snapshot = excluded.title_snapshot,
+    scope = excluded.scope,
+    project_id = excluded.project_id,
+    password_hash = excluded.password_hash,
+    password_salt = excluded.password_salt,
+    password_version = excluded.password_version,
+    auth_version = excluded.auth_version,
+    allow_cloud_usage = excluded.allow_cloud_usage,
+    created_at = excluded.created_at,
+    updated_at = excluded.updated_at,
+    expires_at = excluded.expires_at,
+    revoked_at = excluded.revoked_at,
+    superseded_at = excluded.superseded_at,
+    access_count = excluded.access_count,
+    last_accessed_at = excluded.last_accessed_at,
+    created_from_host = excluded.created_from_host,
+    last_updated_from_host = excluded.last_updated_from_host,
+    revision = excluded.revision,
+    record_digest = excluded.record_digest,
+    deleted_at = excluded.deleted_at,
+    extra_json = excluded.extra_json
+`
+
+// The optional statement lets the cutover replaceAll reuse one precompiled upsert.
+function insertShareRow(database, record, revision, createdAt, updatedAt, statement = null) {
   const extra = {}
   for (const [key, value] of Object.entries(record)) {
     if (!KNOWN_FIELDS.has(key) && !['revision', 'deletedAt'].includes(key)) extra[key] = value
@@ -317,33 +346,8 @@ function insertShareRow(database, record, revision, createdAt, updatedAt) {
     record.createdFromHost ?? null, record.lastUpdatedFromHost ?? null,
     revision, shareRecordDigest(record), record.deletedAt ?? null, JSON.stringify(extra),
   ]
-  database.prepare(`
-    INSERT INTO share_sessions (${SHARE_COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    ON CONFLICT(share_id) DO UPDATE SET
-      session_id = excluded.session_id,
-      permission = excluded.permission,
-      title_snapshot = excluded.title_snapshot,
-      scope = excluded.scope,
-      project_id = excluded.project_id,
-      password_hash = excluded.password_hash,
-      password_salt = excluded.password_salt,
-      password_version = excluded.password_version,
-      auth_version = excluded.auth_version,
-      allow_cloud_usage = excluded.allow_cloud_usage,
-      created_at = excluded.created_at,
-      updated_at = excluded.updated_at,
-      expires_at = excluded.expires_at,
-      revoked_at = excluded.revoked_at,
-      superseded_at = excluded.superseded_at,
-      access_count = excluded.access_count,
-      last_accessed_at = excluded.last_accessed_at,
-      created_from_host = excluded.created_from_host,
-      last_updated_from_host = excluded.last_updated_from_host,
-      revision = excluded.revision,
-      record_digest = excluded.record_digest,
-      deleted_at = excluded.deleted_at,
-      extra_json = excluded.extra_json
-  `).run(...values)
+  const insert = statement ?? database.prepare(SHARE_SESSION_UPSERT_SQL)
+  insert.run(...values)
 }
 
 function replaceTokens(database, shareId, tokens) {
@@ -354,18 +358,21 @@ function replaceTokens(database, shareId, tokens) {
   }
 }
 
-function enqueueShareMirror(database, record, operation, updatedAt) {
+const ENQUEUE_SHARE_MIRROR_SQL = `
+  INSERT INTO share_json_mirror_queue (share_id, operation, share_json, attempts, last_error, updated_at)
+  VALUES (?, ?, ?, 0, NULL, ?)
+  ON CONFLICT(share_id) DO UPDATE SET
+    operation = excluded.operation,
+    share_json = excluded.share_json,
+    attempts = 0,
+    last_error = NULL,
+    updated_at = excluded.updated_at
+`
+
+function enqueueShareMirror(database, record, operation, updatedAt, statement = null) {
   const stored = record ? { ...record, revision: undefined, deletedAt: undefined } : null
-  database.prepare(`
-    INSERT INTO share_json_mirror_queue (share_id, operation, share_json, attempts, last_error, updated_at)
-    VALUES (?, ?, ?, 0, NULL, ?)
-    ON CONFLICT(share_id) DO UPDATE SET
-      operation = excluded.operation,
-      share_json = excluded.share_json,
-      attempts = 0,
-      last_error = NULL,
-      updated_at = excluded.updated_at
-  `).run(
+  const insert = statement ?? database.prepare(ENQUEUE_SHARE_MIRROR_SQL)
+  insert.run(
     record?.id || record,
     operation,
     operation === 'upsert' ? (stored ? recordJson(stored) : null) : null,
@@ -716,10 +723,12 @@ export function createShareRepository(storageHandle, { now = () => new Date().to
     const timestamp = now()
     return storage.transaction((database) => {
       database.exec('DELETE FROM share_sessions; DELETE FROM share_tokens; DELETE FROM share_json_mirror_queue;')
+      const insertSession = database.prepare(SHARE_SESSION_UPSERT_SQL)
+      const insertMirror = database.prepare(ENQUEUE_SHARE_MIRROR_SQL)
       for (const record of records) {
-        insertShareRow(database, { ...record, updatedAt: record.updatedAt || timestamp }, 1, record.createdAt || timestamp, record.updatedAt || timestamp)
+        insertShareRow(database, { ...record, updatedAt: record.updatedAt || timestamp }, 1, record.createdAt || timestamp, record.updatedAt || timestamp, insertSession)
         replaceTokens(database, record.id, record.tokens)
-        enqueueShareMirror(database, { ...record, revision: 1 }, 'upsert', timestamp)
+        enqueueShareMirror(database, { ...record, revision: 1 }, 'upsert', timestamp, insertMirror)
       }
       const digest = shareSnapshotDigest(records)
       if (expectedCount !== undefined && records.length !== expectedCount) throw new Error('Share replace count verification failed')
@@ -750,10 +759,12 @@ export function createShareRepository(storageHandle, { now = () => new Date().to
     ))
   }
 
-  function verifyIntegrity({ quickCheck = false } = {}) {
+  function verifyIntegrity({ quickCheck = false, forceQuickCheck = false } = {}) {
     if (quickCheck) {
-      const result = storage.prepare('PRAGMA quick_check').all().map((row) => row.quick_check)
-      if (result.length !== 1 || result[0] !== 'ok') throw new Error(`SQLite quick_check failed: ${result.join(', ')}`)
+      // Shared quick_check gate (process cache + marker cadence) — see
+      // runSharedSqliteQuickCheck in database.mjs; `forceQuickCheck` is the
+      // manual-maintenance escape hatch that always runs a real scan.
+      runSharedSqliteQuickCheck(storage, { force: forceQuickCheck === true })
     }
     const rows = storage.prepare(`SELECT ${SHARE_COLUMNS} FROM share_sessions`).all()
     let invalidRecords = 0

package/server/startup-state.mjs

@@ -0,0 +1,107 @@
+import { readScheduledRunsState } from './scheduled-runs-cutover.mjs'
+import { readSessionStorageState } from './session-state-service.mjs'
+import { readShareStorageState } from './share-service.mjs'
+import { readLanAccessStorageState } from './lan-access-service.mjs'
+
+// P1 startup maintenance window: the HTTP server listens before the storage
+// migration/initialization chain completes. This module owns the process-wide
+// startup state shared by server/index.mjs (maintenance gate, /api/health and
+// /api/migration-status) and its tests.
+
+export const STARTUP_STATES = Object.freeze({
+  MIGRATING: 'migrating',
+  READY: 'ready',
+  FAILED: 'failed',
+})
+
+// Read-only endpoints that stay reachable while the maintenance gate refuses
+// every other /api/* route, so CLI/Desktop clients can observe progress.
+export const MAINTENANCE_API_WHITELIST = Object.freeze([
+  '/api/health',
+  '/api/migration-status',
+])
+
+// The server process starts in 'migrating' at module evaluation; the startup
+// chain moves it to 'ready' (all domains initialized) or 'failed'.
+let startupState = STARTUP_STATES.MIGRATING
+let startupError = null
+
+export function getStartupState() {
+  return startupState
+}
+
+export function getStartupError() {
+  return startupError
+}
+
+export function setStartupState(state, errorMessage = null) {
+  startupState = state
+  startupError = state === STARTUP_STATES.FAILED
+    ? (errorMessage || 'Startup failed')
+    : null
+}
+
+// Actionable recovery guidance appended to startup errors (fail-closed
+// startup, review §5.1). The original exception text stays intact; the
+// guidance is an additional multi-line paragraph shown verbatim by the
+// frontend failed page (whitespace-pre-wrap).
+export const STARTUP_RECOVERY_GUIDANCE = [
+  'Recovery guidance:',
+  '1. Stop all QuickForge processes so the data files are not locked.',
+  '2. Diagnose offline: node server/maintenance/downgrade-session-state-v1.mjs --dry-run',
+  '3. Export a backup: node server/maintenance/export-session-state-v1.mjs <output-path>',
+  '4. Follow the recovery runbook: docs/architecture/session-storage-recovery-runbook.zh-CN.md',
+].join('\n')
+
+export function withStartupRecoveryGuidance(errorMessage) {
+  return `${errorMessage || 'Startup failed'}\n\n${STARTUP_RECOVERY_GUIDANCE}`
+}
+
+// Test helper: restore the module-evaluation defaults.
+export function resetStartupState() {
+  startupState = STARTUP_STATES.MIGRATING
+  startupError = null
+}
+
+// Maintenance gate for /api/* routes. Returns null when the request may be
+// dispatched, or the maintenance refusal payload ({status, state}) otherwise.
+export function resolveMaintenanceGate(method, pathname) {
+  const state = getStartupState()
+  if (state === STARTUP_STATES.READY) return null
+  if (!pathname || !pathname.startsWith('/api/')) return null
+  if (method === 'GET' && MAINTENANCE_API_WHITELIST.includes(pathname)) return null
+  return { status: 503, state }
+}
+
+function readDomain(read) {
+  try {
+    return read()
+  } catch (error) {
+    // A domain whose storage is not initialized yet (or whose state table
+    // cannot be read) must not fail the whole status endpoint; report the
+    // error name so the UI can still render the remaining domains.
+    return { phase: 'unknown', error: error?.name || 'Error' }
+  }
+}
+
+// Aggregated migration status across the four storage domains. `storage` is
+// optional (scheduled-runs accepts an injected handle; the other domains read
+// the process-wide SQLite storage internally).
+export function readMigrationStatus(storage) {
+  const state = getStartupState()
+  const status = {
+    ok: true,
+    state,
+    domains: {
+      scheduledRuns: readDomain(() => readScheduledRunsState(storage)),
+      // Storage v2: the session domain is SQLite-authoritative by
+      // construction; readSessionStorageState reports the constant
+      // authoritative phase with a live session count.
+      sessionState: readDomain(() => readSessionStorageState()),
+      share: readDomain(() => readShareStorageState()),
+      lanAccess: readDomain(() => readLanAccessStorageState()),
+    },
+  }
+  if (state === STARTUP_STATES.FAILED) status.startupError = getStartupError()
+  return status
+}