@camerontaylor/paseo-server 0.8.0-fork.1

package/dist/server/server/file-observer/index.d.ts

@@ -0,0 +1,43 @@
+export type FileChangeType = "create" | "update" | "delete";
+export interface FileChange {
+    path: string;
+    type: FileChangeType;
+}
+export interface FileObserverOptions {
+    ignore?: string[];
+}
+export type FileObserverCallback = (error: Error | null, events: FileChange[]) => void;
+export interface FileObserverSubscription {
+    updateIgnore(paths: string[]): Promise<void>;
+    unsubscribe(): Promise<void>;
+}
+export interface FileObserverDiagnostics {
+    activeObservationCount: number;
+    nativeHandleCount: number;
+    nativeTrackedFileCount: number;
+    pendingEventCount: number;
+    pendingReconciliationWorkCount: number;
+    reconciliationInFlightCount: number;
+    reconciliationCount: number;
+    scopedReconciliationCount: number;
+    fullReconciliationCount: number;
+    reconciliationFailureCount: number;
+    observerFailureCount: number;
+    directoryLimitFailureCount: number;
+    nativeEventCount: number;
+    nativeChangeEventCount: number;
+    nativeRenameEventCount: number;
+    nativePathlessEventCount: number;
+    nativeClassificationCount: number;
+    nativeShallowScanCount: number;
+    lastReconciliationDurationMs: number;
+    maxReconciliationDurationMs: number;
+}
+export interface FileObserver {
+    subscribe(directory: string, callback: FileObserverCallback, options?: FileObserverOptions): Promise<FileObserverSubscription>;
+    getDiagnostics(): FileObserverDiagnostics;
+    close(): Promise<void>;
+}
+export type SubscribeToFileChanges = FileObserver["subscribe"];
+export declare function createFileObserver(): FileObserver;
+//# sourceMappingURL=index.d.ts.map

package/dist/server/server/file-observer/index.js

@@ -0,0 +1,114 @@
+import { resolve } from "node:path";
+import { createLinuxBackend } from "./internal/linux.js";
+import { createNativeRecursiveBackend } from "./internal/native-recursive.js";
+import { createManagedObservation } from "./internal/observation.js";
+import { createObserverPaths } from "./internal/paths.js";
+export function createFileObserver() {
+    const platform = process.platform;
+    const paths = createObserverPaths(platform);
+    const createBackend = platform === "darwin" || platform === "win32"
+        ? (host) => createNativeRecursiveBackend(host, paths)
+        : (host) => createLinuxBackend(host, paths);
+    return new FileObserverService(createBackend, paths);
+}
+class FileObserverService {
+    constructor(createBackend, paths) {
+        this.createBackend = createBackend;
+        this.paths = paths;
+        this.state = {
+            status: "open",
+            observations: new Set(),
+            metrics: createObserverMetrics(),
+        };
+        this.closePromise = null;
+    }
+    async subscribe(directory, callback, options = {}) {
+        if (this.state.status === "closed")
+            throw new Error("File observer is closed");
+        const state = this.state;
+        let observation;
+        observation = createManagedObservation({
+            root: resolve(directory),
+            callback,
+            options,
+            paths: this.paths,
+            metrics: state.metrics,
+            createBackend: this.createBackend,
+            onClosed: () => state.observations.delete(observation),
+        });
+        await observation.start();
+        if (this.closePromise) {
+            await observation.close();
+            throw new Error("File observer is closed");
+        }
+        state.observations.add(observation);
+        return observation.subscription();
+    }
+    getDiagnostics() {
+        if (this.state.status === "closed")
+            return emptyDiagnostics();
+        const { observations, metrics } = this.state;
+        let nativeHandleCount = 0;
+        let nativeTrackedFileCount = 0;
+        let pendingEventCount = 0;
+        let pendingReconciliationWorkCount = 0;
+        let reconciliationInFlightCount = 0;
+        for (const observation of observations) {
+            const diagnostics = observation.getDiagnostics();
+            nativeHandleCount += diagnostics.nativeHandleCount;
+            nativeTrackedFileCount += diagnostics.nativeTrackedFileCount;
+            pendingEventCount += diagnostics.pendingEventCount;
+            pendingReconciliationWorkCount += diagnostics.pendingReconciliationWorkCount;
+            reconciliationInFlightCount += Number(diagnostics.reconciliationInFlight);
+        }
+        return {
+            activeObservationCount: observations.size,
+            nativeHandleCount,
+            nativeTrackedFileCount,
+            pendingEventCount,
+            pendingReconciliationWorkCount,
+            reconciliationInFlightCount,
+            ...metrics,
+        };
+    }
+    close() {
+        if (this.closePromise)
+            return this.closePromise;
+        if (this.state.status === "closed")
+            return Promise.resolve();
+        const observations = [...this.state.observations];
+        this.state = { status: "closed" };
+        this.closePromise = Promise.allSettled(observations.map((observation) => observation.close())).then(() => undefined);
+        return this.closePromise;
+    }
+}
+function createObserverMetrics() {
+    return {
+        reconciliationCount: 0,
+        scopedReconciliationCount: 0,
+        fullReconciliationCount: 0,
+        reconciliationFailureCount: 0,
+        observerFailureCount: 0,
+        directoryLimitFailureCount: 0,
+        nativeEventCount: 0,
+        nativeChangeEventCount: 0,
+        nativeRenameEventCount: 0,
+        nativePathlessEventCount: 0,
+        nativeClassificationCount: 0,
+        nativeShallowScanCount: 0,
+        lastReconciliationDurationMs: 0,
+        maxReconciliationDurationMs: 0,
+    };
+}
+function emptyDiagnostics() {
+    return {
+        activeObservationCount: 0,
+        nativeHandleCount: 0,
+        nativeTrackedFileCount: 0,
+        pendingEventCount: 0,
+        pendingReconciliationWorkCount: 0,
+        reconciliationInFlightCount: 0,
+        ...createObserverMetrics(),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/server/server/file-observer/internal/contracts.d.ts

@@ -0,0 +1,26 @@
+import type { FileChangeType, FileObserverDiagnostics } from "../index.js";
+export interface ObserverMetrics extends Omit<FileObserverDiagnostics, "activeObservationCount" | "nativeHandleCount" | "nativeTrackedFileCount" | "pendingEventCount" | "pendingReconciliationWorkCount" | "reconciliationInFlightCount"> {
+}
+export interface BackendDiagnostics {
+    nativeHandleCount: number;
+    nativeTrackedFileCount: number;
+    pendingReconciliationWorkCount: number;
+    reconciliationInFlight: boolean;
+}
+export interface ObservationBackend {
+    start(): Promise<void>;
+    updateIgnore(): Promise<void>;
+    close(): Promise<void>;
+    getDiagnostics(): BackendDiagnostics;
+}
+export interface ObservationHost {
+    root: string;
+    metrics: ObserverMetrics;
+    isActive(): boolean;
+    isIgnored(path: string): boolean;
+    isPathInside(root: string, path: string): boolean;
+    queueEvent(type: FileChangeType, path: string): void;
+    fail(error: Error): void;
+}
+export type CreateObservationBackend = (host: ObservationHost) => ObservationBackend;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/server/server/file-observer/internal/contracts.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contracts.js.map

package/dist/server/server/file-observer/internal/linux.d.ts

@@ -0,0 +1,4 @@
+import type { ObservationBackend, ObservationHost } from "./contracts.js";
+import type { ObserverPaths } from "./paths.js";
+export declare function createLinuxBackend(host: ObservationHost, paths: ObserverPaths): ObservationBackend;
+//# sourceMappingURL=linux.d.ts.map

package/dist/server/server/file-observer/internal/linux.js

@@ -0,0 +1,260 @@
+import { watch } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { isMissingPathError, toError } from "./paths.js";
+const MAX_WATCHED_DIRECTORIES = 5000;
+const RECONCILIATION_DELAY_MS = 50;
+export function createLinuxBackend(host, paths) {
+    return new LinuxBackend(host, paths);
+}
+class LinuxBackend {
+    constructor(host, paths) {
+        this.host = host;
+        this.paths = paths;
+        this.watchers = new Map();
+        this.classifications = new Set();
+        this.pendingScopes = new Set();
+        this.reconcileTail = Promise.resolve();
+        this.queueDepth = 0;
+        this.inFlight = false;
+        this.timer = null;
+        this.closePromise = null;
+    }
+    async start() {
+        this.watchDirectory(this.host.root);
+        await this.enqueue([this.host.root]);
+    }
+    async updateIgnore() {
+        for (const [directory, watcher] of this.watchers) {
+            if (directory !== this.host.root && this.host.isIgnored(directory)) {
+                watcher.close();
+                this.watchers.delete(directory);
+            }
+        }
+        this.cancelQueued();
+        await this.enqueue([this.host.root]);
+    }
+    close() {
+        if (this.closePromise)
+            return this.closePromise;
+        this.cancelQueued();
+        for (const watcher of this.watchers.values())
+            watcher.close();
+        this.watchers.clear();
+        this.closePromise = this.finishClose();
+        return this.closePromise;
+    }
+    getDiagnostics() {
+        return {
+            nativeHandleCount: this.watchers.size,
+            nativeTrackedFileCount: 0,
+            pendingReconciliationWorkCount: this.pendingScopes.size +
+                this.classifications.size +
+                this.queueDepth +
+                Number(this.timer !== null),
+            reconciliationInFlight: this.inFlight,
+        };
+    }
+    async finishClose() {
+        await this.reconcileTail;
+        await Promise.allSettled(this.classifications);
+        for (const watcher of this.watchers.values())
+            watcher.close();
+        this.watchers.clear();
+    }
+    watchDirectory(directory) {
+        if (!this.host.isActive() || this.watchers.has(directory) || this.host.isIgnored(directory)) {
+            return;
+        }
+        if (this.watchers.size >= MAX_WATCHED_DIRECTORIES) {
+            this.host.metrics.directoryLimitFailureCount += 1;
+            throw new Error(`Recursive file observation exceeded ${MAX_WATCHED_DIRECTORIES} directories under ${this.host.root}`);
+        }
+        const watcher = watch(directory, (eventType, filename) => {
+            if (!this.host.isActive())
+                return;
+            const path = filename ? resolve(directory, filename.toString()) : directory;
+            if (!this.host.isIgnored(path)) {
+                if (eventType === "change")
+                    this.host.queueEvent("update", path);
+                else
+                    this.classify(path);
+            }
+            if (eventType === "rename" || !filename)
+                this.requestReconcile(path);
+        });
+        this.attachWatcher(directory, watcher);
+    }
+    attachWatcher(directory, watcher) {
+        watcher.on("error", (error) => {
+            if (!this.host.isActive())
+                return;
+            if (this.paths.isExpectedWatchDisappearance(error)) {
+                watcher.close();
+                if (this.watchers.get(directory) === watcher)
+                    this.watchers.delete(directory);
+                if (directory === this.host.root) {
+                    this.host.fail(toError(error));
+                    return;
+                }
+                this.requestReconcile(directory);
+                return;
+            }
+            this.host.fail(toError(error));
+        });
+        this.watchers.set(directory, watcher);
+    }
+    requestReconcile(scope) {
+        if (!this.host.isActive())
+            return;
+        this.pendingScopes.add(scope);
+        if (this.timer)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            const scopes = [...this.pendingScopes];
+            this.pendingScopes.clear();
+            void this.enqueue(scopes).catch((error) => this.host.fail(toError(error)));
+        }, RECONCILIATION_DELAY_MS);
+        this.timer.unref();
+    }
+    enqueue(scopes) {
+        this.queueDepth += 1;
+        const result = this.reconcileTail
+            .then(() => this.run(scopes))
+            .finally(() => {
+            this.queueDepth -= 1;
+        });
+        this.reconcileTail = result.catch(() => undefined);
+        return result;
+    }
+    async run(scopes) {
+        if (!this.host.isActive())
+            return;
+        this.inFlight = true;
+        const startedAt = performance.now();
+        try {
+            await this.reconcile(this.paths.collapse(scopes));
+        }
+        catch (error) {
+            this.host.metrics.reconciliationFailureCount += 1;
+            throw error;
+        }
+        finally {
+            const durationMs = performance.now() - startedAt;
+            this.host.metrics.reconciliationCount += 1;
+            this.host.metrics.scopedReconciliationCount += 1;
+            this.host.metrics.lastReconciliationDurationMs = durationMs;
+            this.host.metrics.maxReconciliationDurationMs = Math.max(this.host.metrics.maxReconciliationDurationMs, durationMs);
+            this.inFlight = false;
+        }
+    }
+    async reconcile(scopes) {
+        for (const scope of scopes) {
+            const snapshot = await this.scan(scope);
+            if (!this.host.isActive())
+                return;
+            for (const directory of snapshot.directories) {
+                if (!this.watchSnapshotDirectory(directory))
+                    snapshot.directories.delete(directory);
+            }
+            for (const path of snapshot.filesDiscoveredBeforeCoverage) {
+                this.host.queueEvent("create", path);
+            }
+            for (const [directory, watcher] of this.watchers) {
+                const disappeared = directory !== this.host.root &&
+                    this.host.isPathInside(scope, directory) &&
+                    !snapshot.directories.has(directory);
+                if (!disappeared)
+                    continue;
+                watcher.close();
+                this.watchers.delete(directory);
+                this.host.queueEvent("delete", directory);
+            }
+        }
+    }
+    watchSnapshotDirectory(directory) {
+        try {
+            this.watchDirectory(directory);
+            return true;
+        }
+        catch (error) {
+            if (!this.paths.isExpectedWatchDisappearance(error) || directory === this.host.root) {
+                throw error;
+            }
+            return false;
+        }
+    }
+    async scan(scope) {
+        let scopeStats;
+        try {
+            scopeStats = await stat(scope);
+        }
+        catch (error) {
+            if (!isMissingPathError(error) || scope === this.host.root)
+                throw error;
+            return { directories: new Set(), filesDiscoveredBeforeCoverage: new Set() };
+        }
+        if (!scopeStats.isDirectory()) {
+            return { directories: new Set(), filesDiscoveredBeforeCoverage: new Set() };
+        }
+        const directories = new Set([scope]);
+        const filesDiscoveredBeforeCoverage = new Set();
+        const pending = [scope];
+        while (pending.length > 0 && this.host.isActive()) {
+            const directory = pending.pop();
+            if (!directory)
+                continue;
+            let entries;
+            try {
+                entries = await readdir(directory, { withFileTypes: true });
+            }
+            catch (error) {
+                if (!isMissingPathError(error))
+                    throw error;
+                if (directory === this.host.root && this.host.isActive())
+                    throw error;
+                continue;
+            }
+            for (const entry of entries) {
+                const child = resolve(directory, entry.name);
+                if (this.host.isIgnored(child))
+                    continue;
+                if (!entry.isDirectory()) {
+                    if (!this.watchers.has(directory))
+                        filesDiscoveredBeforeCoverage.add(child);
+                    continue;
+                }
+                directories.add(child);
+                if (directories.size > MAX_WATCHED_DIRECTORIES) {
+                    this.host.metrics.directoryLimitFailureCount += 1;
+                    throw new Error(`Recursive file observation exceeded ${MAX_WATCHED_DIRECTORIES} directories under ${this.host.root}`);
+                }
+                pending.push(child);
+            }
+        }
+        return { directories, filesDiscoveredBeforeCoverage };
+    }
+    classify(path) {
+        this.host.metrics.nativeClassificationCount += 1;
+        let classification;
+        classification = stat(path)
+            .then(() => this.host.queueEvent("create", path))
+            .catch((error) => {
+            if (isMissingPathError(error)) {
+                this.host.queueEvent("delete", path);
+                return;
+            }
+            this.host.fail(toError(error));
+        })
+            .finally(() => this.classifications.delete(classification));
+        this.classifications.add(classification);
+    }
+    cancelQueued() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        this.pendingScopes.clear();
+    }
+}
+//# sourceMappingURL=linux.js.map

package/dist/server/server/file-observer/internal/native-recursive.d.ts

@@ -0,0 +1,9 @@
+import type { ObservationBackend, ObservationHost } from "./contracts.js";
+import type { ObserverPaths } from "./paths.js";
+type WatchDirectory = (root: string, listener: (eventType: string, filename: string | null) => void) => {
+    close(): void;
+    on(event: "error", listener: (error: Error) => void): unknown;
+};
+export declare function createNativeRecursiveBackend(host: ObservationHost, paths: ObserverPaths, observe?: WatchDirectory): ObservationBackend;
+export {};
+//# sourceMappingURL=native-recursive.d.ts.map