@theia/filesystem 1.77.0-next.57 → 1.77.0-next.63

package/src/node/filesystem-watcher-service-impl.spec.ts

@@ -0,0 +1,272 @@
+// *****************************************************************************
+// Copyright (C) 2026 Ehab Younes and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import * as assert from 'assert';
+import { wait } from '@theia/core/lib/common/promise-util';
+import * as temp from 'temp';
+import * as fs from '@theia/core/shared/fs-extra';
+import { isWindows } from '@theia/core';
+import { FileUri } from '@theia/core/lib/node';
+import { DirectoryWatcherProvider, NodeDirectoryWatcher } from './nodejs-watcher/node-directory-watcher';
+import { NO_LOGGING, TempDir, WATCHER_TIMINGS as TIMINGS } from './test/watcher-test-helper';
+import { FileSystemWatcher, WatcherProvider } from './filesystem-watcher';
+import {
+    FileSystemWatcherServiceImpl, ParcelFileSystemWatcherServerOptions, ParcelFileSystemWatcherService, ParcelWatcher, RecursiveWatcherProvider
+} from './parcel-watcher/parcel-filesystem-service';
+import { WatchOptions } from '../common/filesystem-watcher-protocol';
+
+const track = temp.track();
+
+const RECURSIVE: Readonly<WatchOptions> = { ignored: [], recursive: true };
+const NON_RECURSIVE: Readonly<WatchOptions> = { ignored: [], recursive: false };
+
+/** Exposes what a provider allocated and who serves what, so a test can tell sharing from double-allocation. */
+interface TestProvider extends WatcherProvider {
+    readonly allocated: readonly FileSystemWatcher[];
+    watcherOf(watcherId: number): FileSystemWatcher | undefined;
+}
+
+class TestDirectoryProvider extends DirectoryWatcherProvider implements TestProvider {
+    get allocated(): readonly FileSystemWatcher[] {
+        return this.activeWatchers;
+    }
+
+    watcherOf(watcherId: number): FileSystemWatcher | undefined {
+        return this.watcherFor(watcherId);
+    }
+}
+
+class TestRecursiveProvider extends RecursiveWatcherProvider implements TestProvider {
+    get allocated(): readonly FileSystemWatcher[] {
+        return this.activeWatchers;
+    }
+
+    watcherOf(watcherId: number): FileSystemWatcher | undefined {
+        return this.watcherFor(watcherId);
+    }
+}
+
+function isTestProvider(provider: WatcherProvider): provider is TestProvider {
+    return provider instanceof TestDirectoryProvider || provider instanceof TestRecursiveProvider;
+}
+
+/** A temporary directory and a watcher service on it, one per test. */
+class Sandbox extends FileSystemWatcherServiceImpl {
+
+    /** The directory the requests of this test point into. */
+    readonly files = new TempDir(fs.realpathSync.native(temp.mkdirSync('filesystem-watcher-service')));
+
+    protected readonly requested: number[] = [];
+
+    constructor() {
+        super(NO_LOGGING);
+    }
+
+    get root(): string {
+        return this.files.root;
+    }
+
+    watch(fsPath: string, options: WatchOptions): Promise<number> {
+        return this.watchFileChanges(1, FileUri.create(fsPath).toString(), options)
+            .then(watcherId => (this.requested.push(watcherId), watcherId));
+    }
+
+    /** The watchers currently allocated, one per distinct key, across both providers. */
+    get allocated(): readonly FileSystemWatcher[] {
+        return this.testProviders.flatMap(provider => provider.allocated);
+    }
+
+    protected get testProviders(): TestProvider[] {
+        return this.providers.filter(isTestProvider);
+    }
+
+    /** The watcher serving a request, asked of whichever provider holds it. */
+    watcherOf(watcherId: number): FileSystemWatcher | undefined {
+        return this.testProviders.map(provider => provider.watcherOf(watcherId)).find(Boolean);
+    }
+
+    async release(): Promise<void> {
+        const outstanding = this.requested.splice(0).filter(watcherId => this.watcherOf(watcherId));
+        const allocated = this.allocated;
+        await Promise.all(outstanding.map(watcherId => this.unwatchFileChanges(watcherId)));
+        await Promise.all(allocated.map(watcher => watcher.whenDisposed));
+    }
+
+    protected override createProviders(options: ParcelFileSystemWatcherServerOptions): WatcherProvider[] {
+        return [
+            new TestRecursiveProvider(options, this.maybeClient, TIMINGS.deferredDisposalTimeout),
+            new TestDirectoryProvider(options, this.maybeClient, TIMINGS)
+        ];
+    }
+}
+
+describe('filesystem-watcher-service', function (): void {
+
+    this.timeout(20000);
+
+    let box: Sandbox;
+
+    beforeEach(() => {
+        box = new Sandbox();
+    });
+
+    afterEach(async () => {
+        await box.release();
+        track.cleanupSync();
+    });
+
+    describe('routing', () => {
+
+        it('keeps the deprecated service name usable by adopters', () => {
+            assert.strictEqual(ParcelFileSystemWatcherService, FileSystemWatcherServiceImpl);
+        });
+
+        it('serves a recursive request, and one that does not say, with the parcel watcher', async () => {
+
+            const recursive = await box.watch(box.root, RECURSIVE);
+            const unspecified = await box.watch(box.files.mkdir('other'), { ignored: [] });
+
+            assert.ok(box.watcherOf(recursive) instanceof ParcelWatcher);
+            assert.ok(box.watcherOf(unspecified) instanceof ParcelWatcher);
+        });
+
+        it('serves a non-recursive request with a directory watcher', async () => {
+
+            const watcherId = await box.watch(box.root, NON_RECURSIVE);
+
+            assert.ok(box.watcherOf(watcherId) instanceof NodeDirectoryWatcher);
+        });
+
+        it('keeps a recursive and a non-recursive request on the same path apart', async () => {
+
+            const recursive = await box.watch(box.root, RECURSIVE);
+            const nonRecursive = await box.watch(box.root, NON_RECURSIVE);
+
+            assert.notStrictEqual(box.watcherOf(recursive), box.watcherOf(nonRecursive));
+            assert.strictEqual(box.allocated.length, 2);
+        });
+    });
+
+    describe('sharing', () => {
+
+        it('shares one watcher between a directory and the files inside it', async () => {
+
+            const directory = await box.watch(box.root, NON_RECURSIVE);
+            const first = await box.watch(box.files.write('a.txt'), NON_RECURSIVE);
+            const second = await box.watch(box.files.write('b.txt'), NON_RECURSIVE);
+
+            assert.strictEqual(box.allocated.length, 1);
+            assert.strictEqual(box.watcherOf(directory), box.watcherOf(first));
+            assert.strictEqual(box.watcherOf(first), box.watcherOf(second));
+        });
+
+        it('shares one watcher between requests with different excludes', async () => {
+
+            await box.watch(box.root, { ignored: ['**/node_modules'], recursive: false });
+            await box.watch(box.root, NON_RECURSIVE);
+
+            assert.strictEqual(box.allocated.length, 1);
+        });
+
+        it('shares one watcher between a directory and a symbolic link to it', async () => {
+            const real = box.files.mkdir('real');
+            fs.symlinkSync(real, box.files.path('link'), isWindows ? 'junction' : 'dir');
+
+            const direct = await box.watch(real, NON_RECURSIVE);
+            const linked = await box.watch(box.files.path('link'), NON_RECURSIVE);
+
+            assert.strictEqual(box.allocated.length, 1);
+            assert.strictEqual(box.watcherOf(direct), box.watcherOf(linked));
+        });
+
+        it('shares one watcher between concurrent requests for the same directory', async () => {
+            const [first, second] = [box.files.write('a.txt'), box.files.write('b.txt')];
+
+            const [one, two] = await Promise.all([box.watch(first, NON_RECURSIVE), box.watch(second, NON_RECURSIVE)]);
+
+            assert.strictEqual(box.allocated.length, 1);
+            assert.strictEqual(box.watcherOf(one), box.watcherOf(two));
+        });
+
+        it('moves a watcher to the parent once its path turns out to be a file', async () => {
+            const pending = await box.watch(box.files.path('later.txt'), NON_RECURSIVE);
+            box.files.write('later.txt');
+            await (box.watcherOf(pending) as NodeDirectoryWatcher).whenStarted;
+
+            const directory = await box.watch(box.root, NON_RECURSIVE);
+
+            assert.strictEqual(box.allocated.length, 1);
+            assert.strictEqual(box.watcherOf(pending), box.watcherOf(directory));
+        });
+
+        it('merges two watchers whose paths turn out to be files in one directory', async () => {
+            const [one, two] = await Promise.all([
+                box.watch(box.files.path('a.txt'), NON_RECURSIVE),
+                box.watch(box.files.path('b.txt'), NON_RECURSIVE)
+            ]);
+            box.files.write('a.txt');
+            box.files.write('b.txt');
+            await Promise.all([one, two].map(watcherId => (box.watcherOf(watcherId) as NodeDirectoryWatcher).whenStarted));
+
+            assert.strictEqual(box.allocated.length, 1);
+            assert.strictEqual(box.watcherOf(one), box.watcherOf(two));
+
+            // The handles have to follow the merge, or the moved request would never be released.
+            const survivor = box.watcherOf(one) as NodeDirectoryWatcher;
+            await Promise.all([one, two].map(watcherId => box.unwatchFileChanges(watcherId)));
+            await survivor.whenDisposed;
+            assert.strictEqual(box.allocated.length, 0);
+        });
+
+        it('does not attach a request to a watcher that is already disposed', async () => {
+            const first = await box.watch(box.root, NON_RECURSIVE);
+            const disposed = box.watcherOf(first) as NodeDirectoryWatcher;
+            disposed.dispose();
+
+            const second = await box.watch(box.root, NON_RECURSIVE);
+
+            assert.notStrictEqual(box.watcherOf(second), disposed);
+            assert.strictEqual(box.allocated.length, 1);
+        });
+    });
+
+    describe('releasing', () => {
+
+        it('disposes a directory watcher once its last request is unwatched', async () => {
+            const first = await box.watch(box.root, NON_RECURSIVE);
+            const second = await box.watch(box.root, NON_RECURSIVE);
+            const watcher = box.watcherOf(first) as NodeDirectoryWatcher;
+
+            await box.unwatchFileChanges(first);
+            await wait(TIMINGS.deferredDisposalTimeout * 2);
+            assert.strictEqual(watcher.isDisposed, false, 'the remaining request must keep the watcher alive');
+
+            await box.unwatchFileChanges(second);
+            await watcher.whenDisposed;
+            assert.strictEqual(box.allocated.length, 0);
+        });
+
+        it('releases the client reference of a recursive watcher', async () => {
+            const watcherId = await box.watch(box.root, RECURSIVE);
+            const watcher = box.watcherOf(watcherId) as ParcelWatcher;
+
+            await box.unwatchFileChanges(watcherId);
+            await watcher.whenDisposed;
+
+            assert.strictEqual(box.allocated.length, 0);
+        });
+    });
+});

package/src/node/filesystem-watcher-service-impl.ts

@@ -0,0 +1,109 @@
+// *****************************************************************************
+// Copyright (C) 2017-2018 TypeFox and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { FileUri } from '@theia/core/lib/common/file-uri';
+import { FileSystemWatcherService, FileSystemWatcherServiceClient, WatchOptions } from '../common/filesystem-watcher-protocol';
+import { ResolvedWatchOptions, WatcherLogger, WatcherProvider } from './filesystem-watcher';
+import { DirectoryWatcherProvider } from './nodejs-watcher/node-directory-watcher';
+import { ParcelFileSystemWatcherServerOptions, RecursiveWatcherProvider } from './parcel-watcher/parcel-watcher';
+
+/** Routes each request to the first provider that can handle it. The provider picks the watcher that serves it. */
+export class FileSystemWatcherServiceImpl implements FileSystemWatcherService {
+
+    protected client: FileSystemWatcherServiceClient | undefined;
+
+    protected watcherId = 0;
+
+    protected readonly logger: WatcherLogger;
+
+    /** Checked in order. The first one whose `canHandle` returns `true` serves the request. */
+    protected readonly providers: readonly WatcherProvider[];
+
+    /**
+     * `this.client` is undefined until someone sets it.
+     */
+    protected readonly maybeClient: FileSystemWatcherServiceClient = {
+        onDidFilesChanged: event => this.client?.onDidFilesChanged(event),
+        onError: event => this.client?.onError(event),
+    };
+
+    constructor(options?: Partial<ParcelFileSystemWatcherServerOptions>) {
+        const resolved: ParcelFileSystemWatcherServerOptions = {
+            parcelOptions: {},
+            verbose: false,
+            info: (message, ...args) => console.info(message, ...args),
+            error: (message, ...args) => console.error(message, ...args),
+            ...options
+        };
+        this.logger = resolved;
+        this.providers = this.createProviders(resolved);
+    }
+
+    setClient(client: FileSystemWatcherServiceClient | undefined): void {
+        this.client = client;
+    }
+
+    /** Requests resolving to the same target share a watcher. */
+    async watchFileChanges(clientId: number, uri: string, options?: WatchOptions): Promise<number> {
+        const resolvedOptions = this.resolveWatchOptions(options);
+        const provider = this.providerFor(resolvedOptions);
+        const watcherId = this.watcherId++;
+        await provider.watch(watcherId, { clientId, path: FileUri.fsPath(uri), ignored: resolvedOptions.ignored });
+        return watcherId;
+    }
+
+    async unwatchFileChanges(watcherId: number): Promise<void> {
+        if (!this.providers.some(provider => provider.unwatch(watcherId))) {
+            console.warn(`tried to de-allocate a disposed watcher: watcherId=${watcherId}`);
+        }
+    }
+
+    /** `options` keeps the parcel shape that adopters already bind. Only the recursive provider reads `parcelOptions`. */
+    protected createProviders(options: ParcelFileSystemWatcherServerOptions): WatcherProvider[] {
+        return [
+            new RecursiveWatcherProvider(options, this.maybeClient),
+            new DirectoryWatcherProvider(options, this.maybeClient)
+        ];
+    }
+
+    protected providerFor(options: ResolvedWatchOptions): WatcherProvider {
+        const provider = this.providers.find(candidate => candidate.canHandle(options));
+        if (!provider) {
+            throw new Error(`No watcher provider takes options: ${JSON.stringify(options)}`);
+        }
+        return provider;
+    }
+
+    /**
+     * Return fully qualified options. Watchers created before `recursive` existed were always recursive.
+     */
+    protected resolveWatchOptions(options?: WatchOptions): ResolvedWatchOptions {
+        return {
+            ignored: options?.ignored ?? [],
+            recursive: options?.recursive ?? true
+        };
+    }
+
+    protected debug(message: string, ...params: unknown[]): void {
+        if (this.logger.verbose) {
+            this.logger.info(message, ...params);
+        }
+    }
+
+    dispose(): void {
+        // Singletons shouldn't be disposed...
+    }
+}

package/src/node/filesystem-watcher.ts

@@ -0,0 +1,197 @@
+// *****************************************************************************
+// Copyright (C) 2026 Ehab Younes and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { Deferred } from '@theia/core/lib/common/promise-util';
+import { CancellationTokenSource } from '@theia/core/lib/common/cancellation';
+import { WatchOptions } from '../common/filesystem-watcher-protocol';
+
+/** How a watcher reports what it is doing. */
+export interface WatcherLogger {
+    verbose: boolean;
+    info: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+}
+
+/** A single client request served by a {@link FileSystemWatcher}. */
+export interface WatchRequest {
+    /** Client to route the changes of this request to. */
+    readonly clientId: number;
+    /** Path as requested by the client. Change URIs are built from it, never from the real path. */
+    readonly path: string;
+    /** Exclude patterns of this request alone. */
+    readonly ignored: readonly string[];
+}
+
+/** A watch shared by every request that resolves to the same target. Implementations decide whether it recurses. */
+export interface FileSystemWatcher {
+    /** A disposed watcher released its resources and must not be given further requests. */
+    readonly isDisposed: boolean;
+    /** Resolves once this watcher disposed itself. Never rejects. */
+    readonly whenDisposed: Promise<void>;
+    /** Serves `request` until {@link removeRequest} is called with the same `watcherId`. */
+    addRequest(watcherId: number, request: WatchRequest): void;
+    /** Releases a request. The watcher disposes itself once it has none left. */
+    removeRequest(watcherId: number): void;
+}
+
+/** Handles disposal and logging for a watcher. Subclasses decide how to observe the file system. */
+export abstract class AbstractFileSystemWatcher implements FileSystemWatcher {
+
+    private static debugIdSequence = 0;
+
+    private readonly debugId = AbstractFileSystemWatcher.debugIdSequence++;
+    private readonly disposalDeferred = new Deferred<void>();
+    private readonly disposal = new CancellationTokenSource();
+
+    readonly whenDisposed = this.disposalDeferred.promise;
+
+    constructor(
+        /** Path this watcher was asked about; the subclass decides what it resolves to. */
+        protected readonly target: string,
+        private readonly logger: WatcherLogger
+    ) { }
+
+    get isDisposed(): boolean {
+        return this.disposal.token.isCancellationRequested;
+    }
+
+    abstract addRequest(watcherId: number, request: WatchRequest): void;
+    abstract removeRequest(watcherId: number): void;
+
+    /**
+     * Marks this watcher disposed.
+     * @returns `false` if it already was, in which case the caller must not clean up again.
+     */
+    protected markDisposed(): boolean {
+        if (this.isDisposed) {
+            return false;
+        }
+        this.disposal.cancel();
+        this.disposalDeferred.resolve();
+        return true;
+    }
+
+    /** Logs as-is. Unlike {@link info} it is not prefixed, since these messages name their own path. */
+    protected error(message: string, ...params: unknown[]): void {
+        this.logger.error(message, ...params);
+    }
+
+    protected info(prefix: string, ...params: unknown[]): void {
+        this.logger.info(`${prefix} ${this.constructor.name}(${this.debugId} at "${this.target}"):`, ...params);
+    }
+
+    protected debug(prefix: string, ...params: unknown[]): void {
+        if (this.logger.verbose) {
+            this.info(prefix, ...params);
+        }
+    }
+}
+
+export type ResolvedWatchOptions = Required<WatchOptions>;
+
+/** Serves either recursive or non-recursive requests, and decides which watcher serves each one. */
+export interface WatcherProvider {
+    /** @returns `true` if this provider serves requests made with these options. */
+    canHandle(options: ResolvedWatchOptions): boolean;
+    /** Serves `request` under `watcherId`, on a watcher shared with requests resolving to the same target. */
+    watch(watcherId: number, request: WatchRequest): Promise<void>;
+    /**
+     * Releases the request registered under `watcherId`.
+     * @returns `true` if this provider served the request.
+     */
+    unwatch(watcherId: number): boolean;
+}
+
+/** A {@link WatcherProvider} that keeps one watcher per target. Subclasses decide which key a target maps to. */
+export abstract class AbstractWatcherProvider implements WatcherProvider {
+
+    private readonly watchersByTarget = new Map<string, FileSystemWatcher>();
+    /** The watcher that serves each request, by `watcherId`. */
+    private readonly watchersByRequest = new Map<number, FileSystemWatcher>();
+
+    /** Every watcher this provider currently has open. */
+    protected get activeWatchers(): readonly FileSystemWatcher[] {
+        return Array.from(this.watchersByTarget.values());
+    }
+
+    abstract canHandle(options: ResolvedWatchOptions): boolean;
+    abstract watch(watcherId: number, request: WatchRequest): Promise<void>;
+
+    unwatch(watcherId: number): boolean {
+        const watcher = this.watchersByRequest.get(watcherId);
+        if (!watcher) {
+            return false;
+        }
+        this.watchersByRequest.delete(watcherId);
+        watcher.removeRequest(watcherId);
+        return true;
+    }
+
+    /** The watcher serving a request, if this provider has one. */
+    protected watcherFor(watcherId: number): FileSystemWatcher | undefined {
+        return this.watchersByRequest.get(watcherId);
+    }
+
+    /** Puts a request on a watcher and records which one, so {@link unwatch} finds it again. */
+    protected serve(watcherId: number, watcher: FileSystemWatcher, request: WatchRequest): void {
+        watcher.addRequest(watcherId, request);
+        this.assign(watcherId, watcher);
+    }
+
+    /** Records the watcher of a request that reached it without {@link serve}, such as through a re-key. */
+    protected assign(watcherId: number, watcher: FileSystemWatcher): void {
+        this.watchersByRequest.set(watcherId, watcher);
+    }
+
+    /**
+     * Returns the watcher under `watcherKey`, or creates one. A disposed watcher stays in the map until a later
+     * promise callback removes it, so it is replaced here rather than handed a new request.
+     */
+    protected getOrCreateWatcher<T extends FileSystemWatcher>(watcherKey: string, create: () => T): T {
+        const existing = this.watchersByTarget.get(watcherKey);
+        if (existing && !existing.isDisposed) {
+            return existing as T;
+        }
+        const watcher = create();
+        this.watchersByTarget.set(watcherKey, watcher);
+        watcher.whenDisposed.then(() => {
+            if (this.watchersByTarget.get(watcherKey) === watcher) {
+                this.watchersByTarget.delete(watcherKey);
+            }
+            // Requests it handed to another watcher already point there, so drop only the ones still on it.
+            for (const [watcherId, serving] of this.watchersByRequest) {
+                if (serving === watcher) {
+                    this.watchersByRequest.delete(watcherId);
+                }
+            }
+        });
+        return watcher;
+    }
+
+    /** @returns `true` if `watcher` is the one registered under `watcherKey`. */
+    protected isRegisteredAs(watcher: FileSystemWatcher, watcherKey: string): boolean {
+        return this.watchersByTarget.get(watcherKey) === watcher;
+    }
+
+    /** Forgets every key a watcher is registered under, so that it can be registered under another. */
+    protected unregisterWatcher(watcher: FileSystemWatcher): void {
+        for (const [watcherKey, registered] of this.watchersByTarget) {
+            if (registered === watcher) {
+                this.watchersByTarget.delete(watcherKey);
+            }
+        }
+    }
+}