push.rocks/smartwatch
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(watchers/watcher.node): Improve Node watcher robustness: inode tracking, ENOSPC detection, enhanced health checks and temp-file handling

Browse Source
This commit is contained in:
Jürgen Kunz
2025-12-08 19:31:48 +00:00
parent 913c14bfcf
commit 0c236d44d3
4 changed files with 92 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
ts/00_commitinfo_data.ts
View File

@@ -3,6 +3,6 @@
*/
export const commitinfo = {
name: '@push.rocks/smartwatch',
version: '6.1.0',
version: '6.1.1',
description: 'A cross-runtime file watcher with glob pattern support for Node.js, Deno, and Bun.'
}

70
ts/watchers/watcher.node.ts
View File

@@ -19,6 +19,10 @@ export class NodeWatcher implements IWatcher {
private restartAttempts: Map<string, number> = new Map();
private healthCheckInterval: NodeJS.Timeout | null = null;
// Inode tracking - detect when directories are replaced (atomic saves, etc.)
// fs.watch watches the inode, not the path. If inode changes, we need to restart.
private watchedInodes: Map<string, bigint> = new Map();
// Configuration constants
private static readonly MAX_RETRIES = 3;
private static readonly INITIAL_RESTART_DELAY = 1000;
@@ -91,21 +95,47 @@ export class NodeWatcher implements IWatcher {
/**
* Start periodic health checks to detect silent failures
* Checks for:
* 1. Path no longer exists
* 2. Inode changed (directory was replaced - fs.watch watches inode, not path!)
*/
private startHealthCheck(): void {
console.log('[smartwatch] Starting health check (every 30s)');
this.healthCheckInterval = setInterval(async () => {
console.log(`[smartwatch] Health check: ${this.watchers.size} watchers active`);
for (const [basePath] of this.watchers) {
const stats = await this.statSafe(basePath);
if (!stats && this._isWatching) {
console.error(`[smartwatch] Health check failed: ${basePath} no longer exists`);
this.safeEmit({
type: 'error',
path: basePath,
error: new Error('Watched path no longer exists')
});
this.restartWatcher(basePath, new Error('Watched path disappeared'));
try {
const stats = await fs.promises.stat(basePath);
const currentInode = stats.ino;
const previousInode = this.watchedInodes.get(basePath);
if (!stats) {
console.error(`[smartwatch] Health check failed: ${basePath} no longer exists`);
this.safeEmit({
type: 'error',
path: basePath,
error: new Error('Watched path no longer exists')
});
this.restartWatcher(basePath, new Error('Watched path disappeared'));
} else if (previousInode !== undefined && BigInt(currentInode) !== previousInode) {
// CRITICAL: Inode changed! fs.watch is now watching a stale inode.
// This happens when the directory is replaced (atomic operations, git checkout, etc.)
console.warn(`[smartwatch] Inode changed for ${basePath}: ${previousInode} -> ${currentInode}`);
console.warn('[smartwatch] fs.watch watches inode, not path - restarting watcher');
this.restartWatcher(basePath, new Error('Inode changed - directory was replaced'));
}
} catch (error: any) {
if (error.code === 'ENOENT') {
console.error(`[smartwatch] Health check failed: ${basePath} no longer exists`);
this.restartWatcher(basePath, new Error('Watched path disappeared'));
} else if (error.code === 'ENOSPC') {
// inotify watch limit exceeded - critical system issue
console.error(`[smartwatch] ENOSPC: inotify watch limit exceeded!`);
console.error('[smartwatch] Fix: echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p');
this.safeEmit({ type: 'error', path: basePath, error });
} else {
console.error(`[smartwatch] Health check error for ${basePath}:`, error);
}
}
}
}, NodeWatcher.HEALTH_CHECK_INTERVAL);
@@ -196,6 +226,7 @@ export class NodeWatcher implements IWatcher {
// Clear restart tracking state
this.restartDelays.clear();
this.restartAttempts.clear();
this.watchedInodes.clear();
console.log('[smartwatch] Watcher stopped');
}
@@ -215,6 +246,10 @@ export class NodeWatcher implements IWatcher {
}
if (stats.isDirectory()) {
// Store inode for health check - fs.watch watches inode, not path!
// If inode changes (directory replaced), watcher becomes stale
this.watchedInodes.set(watchPath, BigInt(stats.ino));
// Watch the directory with recursive option (Node.js 20+ supports this on all platforms)
const watcher = fs.watch(
watchPath,
@@ -226,8 +261,15 @@ export class NodeWatcher implements IWatcher {
}
);
watcher.on('error', (error) => {
watcher.on('error', (error: NodeJS.ErrnoException) => {
console.error(`[smartwatch] FSWatcher error event on ${watchPath}:`, error);
// Detect inotify watch limit exceeded - common cause of "stops working"
if (error.code === 'ENOSPC') {
console.error('[smartwatch] CRITICAL: inotify watch limit exceeded!');
console.error('[smartwatch] Fix with: echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p');
}
this.safeEmit({ type: 'error', path: watchPath, error });
if (this._isWatching) {
this.restartWatcher(watchPath, error);
@@ -261,8 +303,14 @@ export class NodeWatcher implements IWatcher {
): void {
const fullPath = path.join(basePath, filename);
// Skip temporary files created by editors (atomic saves)
// Skip temporary files - but ONLY pure temp files, not the target of atomic writes
// Atomic writes: editor writes to file.tmp.xxx then renames to file
// We need to detect the final file, so only skip files that ARE temp files
// and haven't been renamed to the real file yet
if (this.isTemporaryFile(fullPath)) {
// For temp files, we still want to track if they get renamed TO a real file
// The 'rename' event fires for both source and target, so we'll catch the real file
console.log(`[smartwatch] Skipping temp file event: ${filename}`);
return;
}