Files
dashcaddy/dashcaddy-api/src/managers/state-manager.js
T
Hermes 6b7ca4b3e9 [grade=A urn:ump:qszwspay7vhx7wcpqekkkidni3ehhgidvze5qk2y22fvg2wqz3ja] fix(DC-170): reliability batch — hangs, atomicity, fail-closed, SW (audit batch 6)
8 reliability fixes across 8 files (AUDIT-2026-10-27.md findings
9/11/12/13/14/16/20 + calendar credential item):

- dns.js check-update/update HANGS: bare returns + empty else/catch
  branches left requests hanging until client timeout; every path now
  answers (502 with message); upstream JSON.parse wrapped (non-JSON ->
  502)
- calendar.js ICS fetch timeout actually applies: fetchT ignores
  opts.timeout (undici) — was running at 5s default, not the intended
  15s; now timeoutMs third arg
- calendar.js PUT /sources: updating pass no longer nulls the stored
  token (and vice versa) — existing credential record loaded, only the
  provided field overwritten
- state-manager.js ATOMIC WRITES: _atomicWrite = tmp file + fs.rename
  (POSIX-atomic); write()/update() no longer truncate-then-write the
  live file (crash mid-write corrupted services.json/config.json with
  no recovery path). Test mock extended to the tmp+rename contract
- dashboard-ws.js auth fallback FAIL-CLOSED: missing authVerifier used
  to accept any non-empty session cookie (DC-061 footgun on unwired
  boot paths); now rejects + loud CRITICAL log
- middleware.js tailscale gate: new tailscale.failClosed config (default
  off = unchanged); when set, outages/errors deny (503) instead of
  silently disabling the gate; fail-open path now logs the exact key
- sw.js: offline fallback actually works ((await match) || (await
  match) — old Promise||Promise was always truthy); only 2xx cached
  (5xx pages were stored and served as the app shell); install is
  per-URL tolerant (one bad asset kept the stale SW alive forever)
- config/settings.js GET /config (public): corrupt config.json degrades
  to {setupComplete:false, corrupt:true} instead of 500 on every load

SCOPE CORRECTION: audit finding #10 (7 reversed-arg errorResponse
sites) was a FALSE POSITIVE — those files alias message-first error();
see lesson #14. Full suite 173/173 suites, 3740/3740 tests.
2026-10-29 01:46:13 -07:00

258 lines
7.5 KiB
JavaScript

/**
* State Manager - Thread-safe file operations with locking
*
* Prevents data corruption when multiple API requests modify state files concurrently.
* Uses file-based locking with automatic retry and timeout handling.
*
* @module state-manager
*/
const lockfile = require('proper-lockfile');
const fs = require('fs').promises;
const fsSync = require('fs');
const path = require('path');
class StateManager {
/**
* Create a StateManager instance
* @param {string} filePath - Path to the state file (e.g., services.json)
* @param {Object} options - Configuration options
* @param {number} options.lockTimeout - Max time to wait for lock (ms)
* @param {number} options.lockRetries - Number of lock acquisition retries
* @param {number} options.lockRetryInterval - Time between retries (ms)
*/
constructor(filePath, options = {}) {
this.filePath = filePath;
this.lockOptions = {
retries: {
retries: options.lockRetries || 10,
minTimeout: options.lockRetryInterval || 100,
maxTimeout: (options.lockRetryInterval || 100) * 3
},
stale: options.lockTimeout || 30000 // 30 seconds
};
// Ensure file exists
this._ensureFileExists();
}
/**
* Atomic write (DC-170): serialize to a temp file in the same directory,
* then rename over the live file. rename(2) is atomic on POSIX, so a crash
* mid-write can no longer leave a truncated JSON file behind (the old
* truncate-then-write corrupted services.json/config.json unrecoverably —
* read() only special-cases ENOENT). Caller must hold the file lock.
*/
async _atomicWrite(data) {
const tmpPath = `${this.filePath}.tmp-${process.pid}-${Date.now()}`;
await fs.writeFile(tmpPath, JSON.stringify(data, null, 2), 'utf8');
try {
await fs.rename(tmpPath, this.filePath);
} catch (err) {
try { await fs.unlink(tmpPath); } catch (_) { /* best effort */ }
throw err;
}
}
/**
* Ensure the state file exists, create with empty array if not
* @private
*/
_ensureFileExists() {
if (!fsSync.existsSync(this.filePath)) {
const dir = path.dirname(this.filePath);
if (!fsSync.existsSync(dir)) {
fsSync.mkdirSync(dir, { recursive: true });
}
fsSync.writeFileSync(this.filePath, '[]', 'utf8');
}
}
/**
* Read the state file (no locking required for read-only operations)
* @returns {Promise<any>} Parsed JSON data
* @throws {Error} If file doesn't exist or JSON is invalid
*/
async read() {
try {
const content = await fs.readFile(this.filePath, 'utf8');
return JSON.parse(content);
} catch (error) {
if (error.code === 'ENOENT') {
// File doesn't exist — recreate without locking (no file to lock)
this._ensureFileExists();
return [];
}
throw new Error(`Failed to read state file: ${error.message}`);
}
}
/**
* Write data to the state file (with locking)
* @param {any} data - Data to write (will be JSON.stringify'd)
* @returns {Promise<void>}
* @throws {Error} If lock cannot be acquired or write fails
*/
async write(data) {
let release;
try {
// Acquire lock
release = await lockfile.lock(this.filePath, this.lockOptions);
// Write data atomically (DC-170): truncate-then-write on the live file
// corrupted services.json/config.json on crash mid-write with no recovery
// path (read() only special-cases ENOENT). tmp + rename is atomic on POSIX.
await this._atomicWrite(data);
} catch (error) {
if (error.code === 'ELOCKED') {
throw new Error('State file is locked by another process. Try again.');
}
throw new Error(`Failed to write state file: ${error.message}`);
} finally {
// Always release lock
if (release) {
try {
await release();
} catch (e) {
// Lock release failure (non-critical, lock will expire via stale timeout)
}
}
}
}
/**
* Update the state file using a callback function (atomic operation)
* This is the recommended method for most operations.
*
* @param {Function} updateFn - Function that receives current data and returns updated data
* @returns {Promise<any>} The updated data
* @throws {Error} If lock cannot be acquired or update fails
*
* @example
* // Add a new service
* await stateManager.update(services => {
* services.push({ id: 'new-service', name: 'New Service' });
* return services;
* });
*
* @example
* // Remove a service
* await stateManager.update(services => {
* return services.filter(s => s.id !== 'old-service');
* });
*/
async update(updateFn) {
let release;
try {
// Acquire lock
release = await lockfile.lock(this.filePath, this.lockOptions);
// Read current data
const content = await fs.readFile(this.filePath, 'utf8');
const currentData = JSON.parse(content);
// Apply update function
const updatedData = await updateFn(currentData);
// Write updated data atomically (DC-170, same rationale as write())
await this._atomicWrite(updatedData);
return updatedData;
} catch (error) {
if (error.code === 'ELOCKED') {
throw new Error('State file is locked by another process. Try again.');
}
throw new Error(`Failed to update state file: ${error.message}`);
} finally {
// Always release lock
if (release) {
try {
await release();
} catch (e) {
// Lock release failure (non-critical, lock will expire via stale timeout)
}
}
}
}
/**
* Check if the state file is currently locked
* @returns {Promise<boolean>} True if locked, false otherwise
*/
async isLocked() {
try {
return await lockfile.check(this.filePath);
} catch (error) {
return false;
}
}
/**
* Forcefully unlock the state file (use with caution!)
* Only use this if a lock is stuck due to a crashed process.
* @returns {Promise<void>}
*/
async forceUnlock() {
try {
await lockfile.unlock(this.filePath);
} catch (error) {
// Ignore errors if file wasn't locked
if (error.code !== 'ENOTACQUIRED') {
throw error;
}
}
}
/**
* Add an item to the state array (convenience method)
* @param {any} item - Item to add
* @returns {Promise<any>} Updated array
*/
async addItem(item) {
return await this.update(items => {
items.push(item);
return items;
});
}
/**
* Remove an item from the state array by ID (convenience method)
* @param {string} id - ID of item to remove
* @returns {Promise<any>} Updated array
*/
async removeItem(id) {
return await this.update(items => {
return items.filter(item => item.id !== id);
});
}
/**
* Update an item in the state array by ID (convenience method)
* @param {string} id - ID of item to update
* @param {Object} updates - Properties to update
* @returns {Promise<any>} Updated array
*/
async updateItem(id, updates) {
return await this.update(items => {
return items.map(item => {
if (item.id === id) {
return { ...item, ...updates };
}
return item;
});
});
}
/**
* Find an item in the state array by ID (convenience method)
* @param {string} id - ID of item to find
* @returns {Promise<any|null>} Found item or null
*/
async findItem(id) {
const items = await this.read();
return items.find(item => item.id === id) || null;
}
}
module.exports = StateManager;