@theia/filesystem 1.77.0-next.1 → 1.77.0-next.108

package/src/node/file-change-collection.spec.ts

@@ -16,8 +16,8 @@
 
 import * as assert from 'assert';
 import { FileUri } from '@theia/core/lib/common/file-uri';
-import { FileChangeCollection } from './file-change-collection';
-import { FileChangeType } from '../common/files';
+import { FileChangeCollection } from './file-change-collection.js';
+import { FileChangeType } from '../common/files.js';
 
 describe('FileChangeCollection', () => {
 

package/src/node/file-change-collection.ts

@@ -14,7 +14,7 @@
 // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
 // *****************************************************************************
 
-import { FileChange, FileChangeType } from '../common/filesystem-watcher-protocol';
+import { FileChange, FileChangeType } from '../common/filesystem-watcher-protocol.js';
 
 /**
  * A file change collection guarantees that only one change is reported for each URI.

package/src/node/filesystem-backend-module.ts

@@ -17,32 +17,33 @@
 import * as path from 'path';
 import { ContainerModule, interfaces } from '@theia/core/shared/inversify';
 import { ConnectionHandler, RpcConnectionHandler, ILogger } from '@theia/core/lib/common';
-import { FileSystemWatcherServer, FileSystemWatcherService } from '../common/filesystem-watcher-protocol';
-import { FileSystemWatcherServerClient } from './filesystem-watcher-client';
-import { ParcelFileSystemWatcherService, ParcelFileSystemWatcherServerOptions } from './parcel-watcher/parcel-filesystem-service';
-import { NodeFileUploadService } from './upload/node-file-upload-service';
-import { ParcelWatcherOptions } from './parcel-watcher/parcel-options';
-import { DiskFileSystemProvider } from './disk-file-system-provider';
+import { FileSystemWatcherServer, FileSystemWatcherService } from '../common/filesystem-watcher-protocol.js';
+import { FileSystemWatcherServerClient } from './filesystem-watcher-client.js';
+import { FileSystemWatcherServiceImpl } from './filesystem-watcher-service-impl.js';
+import { ParcelFileSystemWatcherServerOptions } from './parcel-watcher/parcel-watcher.js';
+import { NodeFileUploadService } from './upload/node-file-upload-service.js';
+import { ParcelWatcherOptions } from './parcel-watcher/parcel-options.js';
+import { DiskFileSystemProvider } from './disk-file-system-provider.js';
 import {
     remoteFileSystemPath, RemoteFileSystemServer, RemoteFileSystemClient, FileSystemProviderServer, RemoteFileSystemProxyFactory
-} from '../common/remote-file-system-provider';
-import { FileSystemProvider } from '../common/files';
+} from '../common/remote-file-system-provider.js';
+import { FileSystemProvider } from '../common/files.js';
 import { EncodingService } from '@theia/core/lib/common/encoding-service';
 import { BackendApplicationContribution, IPCConnectionProvider } from '@theia/core/lib/node';
 import { RpcProxyFactory, ConnectionErrorHandler } from '@theia/core';
-import { FileSystemWatcherServiceDispatcher } from './filesystem-watcher-dispatcher';
-import { bindFileSystemPreferences } from '../common';
+import { FileSystemWatcherServiceDispatcher } from './filesystem-watcher-dispatcher.js';
+import { bindFileSystemPreferences } from '../common/index.js';
 
 export const WATCHER_SINGLE_THREADED = process.argv.includes('--no-cluster');
 export const WATCHER_VERBOSE = process.argv.includes('--watcher-verbose');
 
 export const FileSystemWatcherServiceProcessOptions = Symbol('FileSystemWatcherServiceProcessOptions');
 /**
- * Options to control the way the `ParcelFileSystemWatcherService` process is spawned.
+ * Options to control the way the `FileSystemWatcherServiceImpl` process is spawned.
  */
 export interface FileSystemWatcherServiceProcessOptions {
     /**
-     * Path to the script that will run the `ParcelFileSystemWatcherService` in a new process.
+     * Path to the script that will run the `FileSystemWatcherServiceImpl` in a new process.
      */
     entryPoint: string;
 }
@@ -76,7 +77,7 @@ export function bindFileSystemWatcherServer(bind: interfaces.Bind): void {
     bind(FileSystemWatcherServer).toService(FileSystemWatcherServerClient);
 
     bind<FileSystemWatcherServiceProcessOptions>(FileSystemWatcherServiceProcessOptions).toDynamicValue(ctx => ({
-        entryPoint: path.join(__dirname, 'parcel-watcher'),
+        entryPoint: path.join(import.meta.dirname, 'parcel-watcher'),
     })).inSingletonScope();
     bind<ParcelFileSystemWatcherServerOptions>(ParcelFileSystemWatcherServerOptions).toDynamicValue(ctx => {
         const logger = ctx.container.get<ILogger>(ILogger);
@@ -102,7 +103,7 @@ export function bindFileSystemWatcherServer(bind: interfaces.Bind): void {
 export function createParcelFileSystemWatcherService(ctx: interfaces.Context): FileSystemWatcherService {
     const options = ctx.container.get<ParcelFileSystemWatcherServerOptions>(ParcelFileSystemWatcherServerOptions);
     const dispatcher = ctx.container.get<FileSystemWatcherServiceDispatcher>(FileSystemWatcherServiceDispatcher);
-    const server = new ParcelFileSystemWatcherService(options);
+    const server = new FileSystemWatcherServiceImpl(options);
     server.setClient(dispatcher);
     return server;
 }

package/src/node/filesystem-watcher-client.ts

@@ -15,8 +15,8 @@
 // *****************************************************************************
 
 import { injectable, inject } from '@theia/core/shared/inversify';
-import { FileSystemWatcherServer, WatchOptions, FileSystemWatcherClient, FileSystemWatcherService } from '../common/filesystem-watcher-protocol';
-import { FileSystemWatcherServiceDispatcher } from './filesystem-watcher-dispatcher';
+import { FileSystemWatcherServer, WatchOptions, FileSystemWatcherClient, FileSystemWatcherService } from '../common/filesystem-watcher-protocol.js';
+import { FileSystemWatcherServiceDispatcher } from './filesystem-watcher-dispatcher.js';
 
 /**
  * Wraps the watcher singleton service for each frontend.

package/src/node/filesystem-watcher-dispatcher.ts

@@ -18,7 +18,7 @@ import { injectable, inject, named } from '@theia/core/shared/inversify';
 import {
     FileSystemWatcherClient, FileSystemWatcherServiceClient,
     DidFilesChangedParams, FileSystemWatcherErrorParams
-} from '../common/filesystem-watcher-protocol';
+} from '../common/filesystem-watcher-protocol.js';
 import { ILogger } from '@theia/core';
 /**
  * This component routes watch events to the right clients.

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.js';
+import { NO_LOGGING, TempDir, WATCHER_TIMINGS as TIMINGS } from './test/watcher-test-helper.js';
+import { FileSystemWatcher, WatcherProvider } from './filesystem-watcher.js';
+import {
+    FileSystemWatcherServiceImpl, ParcelFileSystemWatcherServerOptions, ParcelFileSystemWatcherService, ParcelWatcher, RecursiveWatcherProvider
+} from './parcel-watcher/parcel-filesystem-service.js';
+import { WatchOptions } from '../common/filesystem-watcher-protocol.js';
+
+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.js';
+import { ResolvedWatchOptions, WatcherLogger, WatcherProvider } from './filesystem-watcher.js';
+import { DirectoryWatcherProvider } from './nodejs-watcher/node-directory-watcher.js';
+import { ParcelFileSystemWatcherServerOptions, RecursiveWatcherProvider } from './parcel-watcher/parcel-watcher.js';
+
+/** 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...
+    }
+}