@theia/plugin-ext 1.76.0-next.7 → 1.77.0-next.0

package/src/plugin/telemetry-ext.spec.ts

@@ -15,47 +15,188 @@
 // *****************************************************************************
 
 import * as chai from 'chai';
+import { TelemetryLevel } from '@theia/telemetry/lib/common/telemetry-types';
 import { TelemetryExtImpl } from './telemetry-ext';
 
 const expect = chai.expect;
 
-describe('TelemetryLogger', () => {
+describe('TelemetryExtImpl', () => {
     const sender = {
         sendEventData: () => { },
         sendErrorData: () => { }
     };
 
-    it('reflects the current telemetry enabled state', () => {
+    interface Expectation {
+        isTelemetryEnabled: boolean;
+        isUsageEnabled: boolean;
+        isErrorsEnabled: boolean;
+    }
+
+    const expectations: Record<TelemetryLevel, Expectation> = {
+        off: { isTelemetryEnabled: false, isUsageEnabled: false, isErrorsEnabled: false },
+        crash: { isTelemetryEnabled: false, isUsageEnabled: false, isErrorsEnabled: false },
+        error: { isTelemetryEnabled: false, isUsageEnabled: false, isErrorsEnabled: true },
+        all: { isTelemetryEnabled: true, isUsageEnabled: true, isErrorsEnabled: true }
+    };
+
+    for (const level of ['off', 'crash', 'error', 'all'] as const) {
+        const expected = expectations[level];
+
+        it(`derives the enablement states from telemetry level '${level}'`, () => {
+            const telemetry = new TelemetryExtImpl();
+            telemetry.$onDidChangeTelemetryLevel(level);
+            const logger = telemetry.createTelemetryLogger(sender);
+
+            expect(telemetry.level).to.equal(level);
+            expect(telemetry.isTelemetryEnabled).to.equal(expected.isTelemetryEnabled);
+            expect(logger.isUsageEnabled).to.equal(expected.isUsageEnabled);
+            expect(logger.isErrorsEnabled).to.equal(expected.isErrorsEnabled);
+        });
+
+        it(`applies telemetry level '${level}' to loggers created before the level arrived`, () => {
+            const telemetry = new TelemetryExtImpl();
+            const logger = telemetry.createTelemetryLogger(sender);
+            telemetry.$onDidChangeTelemetryLevel(level);
+
+            expect(logger.isUsageEnabled).to.equal(expected.isUsageEnabled);
+            expect(logger.isErrorsEnabled).to.equal(expected.isErrorsEnabled);
+        });
+    }
+
+    it('only fires onDidChangeTelemetryEnabled when the boolean it reports changes', () => {
+        const telemetry = new TelemetryExtImpl();
+        const fired: boolean[] = [];
+        telemetry.onDidChangeTelemetryEnabled(enabled => fired.push(enabled));
+
+        telemetry.$onDidChangeTelemetryLevel('crash');
+        telemetry.$onDidChangeTelemetryLevel('error');
+        telemetry.$onDidChangeTelemetryLevel('all');
+        telemetry.$onDidChangeTelemetryLevel('off');
+
+        expect(fired).to.deep.equal([true, false]);
+    });
+
+    it('fires onDidChangeEnableStates once per transition that changes an enablement state', () => {
         const telemetry = new TelemetryExtImpl();
         const logger = telemetry.createTelemetryLogger(sender);
+        let changes = 0;
+        logger.onDidChangeEnableStates(() => changes++);
 
-        expect(logger.telemetryEnabled).to.equal(false);
-        expect(logger.isUsageEnabled).to.equal(false);
-        expect(logger.isErrorsEnabled).to.equal(false);
+        telemetry.$onDidChangeTelemetryLevel('crash'); // off -> crash: both stay false
+        expect(changes).to.equal(0);
 
-        telemetry.isTelemetryEnabled = true;
+        telemetry.$onDidChangeTelemetryLevel('error'); // errors become enabled
+        expect(changes).to.equal(1);
 
-        expect(logger.telemetryEnabled).to.equal(true);
-        expect(logger.isUsageEnabled).to.equal(true);
-        expect(logger.isErrorsEnabled).to.equal(true);
+        telemetry.$onDidChangeTelemetryLevel('all'); // usage becomes enabled
+        expect(changes).to.equal(2);
 
-        telemetry.isTelemetryEnabled = false;
+        telemetry.$onDidChangeTelemetryLevel('off');
+        expect(changes).to.equal(3);
+    });
 
-        expect(logger.telemetryEnabled).to.equal(false);
+    it('stops following the level once the logger is disposed', () => {
+        const telemetry = new TelemetryExtImpl();
+        const logger = telemetry.createTelemetryLogger(sender);
+        let changes = 0;
+        logger.onDidChangeEnableStates(() => changes++);
+
+        logger.dispose();
+        telemetry.$onDidChangeTelemetryLevel('all');
         expect(logger.isUsageEnabled).to.equal(false);
-        expect(logger.isErrorsEnabled).to.equal(false);
+
+        logger.isUsageEnabled = true;
+        expect(changes).to.equal(0);
+    });
+
+    it('logs rather than propagates a sender that fails to flush on disposal', async () => {
+        const telemetry = new TelemetryExtImpl();
+        const logged: unknown[] = [];
+        const consoleError = console.error;
+        console.error = (...args: unknown[]) => { logged.push(args); };
+        try {
+            telemetry.createTelemetryLogger({ ...sender, flush: () => { throw new Error('boom'); } }).dispose();
+            telemetry.createTelemetryLogger({ ...sender, flush: () => Promise.reject(new Error('boom')) }).dispose();
+            await new Promise(resolve => setTimeout(resolve, 0));
+        } finally {
+            console.error = consoleError;
+        }
+
+        expect(logged).to.have.lengthOf(2);
     });
 
-    it('emits enable-state changes when telemetry is toggled', () => {
+    it('ignores a repeated telemetry level', () => {
         const telemetry = new TelemetryExtImpl();
         const logger = telemetry.createTelemetryLogger(sender);
         let changes = 0;
-
         logger.onDidChangeEnableStates(() => changes++);
 
-        telemetry.isTelemetryEnabled = true;
-        telemetry.isTelemetryEnabled = false;
+        telemetry.$onDidChangeTelemetryLevel('all');
+        telemetry.$onDidChangeTelemetryLevel('all');
 
-        expect(changes).to.equal(2);
+        expect(changes).to.equal(1);
+    });
+});
+
+describe('TelemetryLogger', () => {
+
+    interface RecordingSender {
+        events: string[];
+        errors: Error[];
+        sendEventData(eventName: string): void;
+        sendErrorData(error: Error): void;
+    }
+
+    function createSender(): RecordingSender {
+        const events: string[] = [];
+        const errors: Error[] = [];
+        return {
+            events,
+            errors,
+            sendEventData: (eventName: string) => events.push(eventName),
+            sendErrorData: (error: Error) => errors.push(error)
+        };
+    }
+
+    it('delivers errors but suppresses usage at telemetry level \'error\'', () => {
+        const telemetry = new TelemetryExtImpl();
+        telemetry.$onDidChangeTelemetryLevel('error');
+        const sender = createSender();
+        const logger = telemetry.createTelemetryLogger(sender);
+
+        logger.logUsage('usage-event');
+        logger.logError('error-event');
+        logger.logError(new Error('boom'));
+
+        expect(sender.events).to.deep.equal(['error-event']);
+        expect(sender.errors).to.have.lengthOf(1);
+    });
+
+    it('suppresses usage that a plugin re-enables while the telemetry level forbids it', () => {
+        const telemetry = new TelemetryExtImpl();
+        telemetry.$onDidChangeTelemetryLevel('off');
+        const sender = createSender();
+        const logger = telemetry.createTelemetryLogger(sender);
+
+        logger.isUsageEnabled = true;
+        logger.isErrorsEnabled = true;
+        logger.logUsage('usage-event');
+        logger.logError('error-event');
+
+        expect(sender.events).to.be.empty;
+    });
+
+    it('refuses to let a plugin assign the telemetry level of its logger', () => {
+        const telemetry = new TelemetryExtImpl();
+        telemetry.$onDidChangeTelemetryLevel('off');
+        const sender = createSender();
+        const logger = telemetry.createTelemetryLogger(sender);
+
+        expect(Reflect.set(logger, 'level', 'all')).to.be.false;
+        logger.logUsage('usage-event');
+
+        expect(logger.level).to.equal('off');
+        expect(logger.isUsageEnabled).to.be.false;
+        expect(sender.events).to.be.empty;
     });
 });

package/src/plugin/telemetry-ext.ts

@@ -14,33 +14,54 @@
 // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
 
 import { Event, Emitter } from '@theia/core/lib/common/event';
+import { Disposable } from '@theia/core/lib/common/disposable';
 import { cloneAndChange } from '@theia/core';
+import { injectable } from '@theia/core/shared/inversify';
+import { TelemetryLevel, isKindAllowedByLevel } from '@theia/telemetry/lib/common/telemetry-types';
+import { TelemetryExt } from '../common/plugin-api-rpc';
 import { mixin } from '../common/types';
 import { TelemetryTrustedValue, TelemetryLoggerOptions } from './types-impl';
 
-export class TelemetryExtImpl {
+/**
+ * Holds the telemetry level the user consented to and hands it to the loggers plugins create.
+ *
+ * @experimental
+ */
+@injectable()
+export class TelemetryExtImpl implements TelemetryExt {
 
-    _isTelemetryEnabled: boolean = false; // telemetry not activated by default
+    protected currentLevel: TelemetryLevel = 'off';
     private readonly onDidChangeTelemetryEnabledEmitter = new Emitter<boolean>();
     readonly onDidChangeTelemetryEnabled: Event<boolean> = this.onDidChangeTelemetryEnabledEmitter.event;
+    private readonly onDidChangeTelemetryLevelEmitter = new Emitter<TelemetryLevel>();
+    protected readonly onDidChangeTelemetryLevel: Event<TelemetryLevel> = this.onDidChangeTelemetryLevelEmitter.event;
 
-    get isTelemetryEnabled(): boolean {
-        return this._isTelemetryEnabled;
+    get level(): TelemetryLevel {
+        return this.currentLevel;
     }
 
-    set isTelemetryEnabled(isTelemetryEnabled: boolean) {
-        if (this._isTelemetryEnabled !== isTelemetryEnabled) {
-            this._isTelemetryEnabled = isTelemetryEnabled;
-            this.onDidChangeTelemetryEnabledEmitter.fire(this._isTelemetryEnabled);
+    $onDidChangeTelemetryLevel(level: TelemetryLevel): void {
+        this.setLevel(level);
+    }
+
+    setLevel(level: TelemetryLevel): void {
+        if (this.currentLevel === level) {
+            return;
         }
+        const wasTelemetryEnabled = this.isTelemetryEnabled;
+        this.currentLevel = level;
+        this.onDidChangeTelemetryLevelEmitter.fire(level);
+        if (this.isTelemetryEnabled !== wasTelemetryEnabled) {
+            this.onDidChangeTelemetryEnabledEmitter.fire(this.isTelemetryEnabled);
+        }
+    }
+
+    get isTelemetryEnabled(): boolean {
+        return isKindAllowedByLevel(this.currentLevel, 'usage');
     }
 
     createTelemetryLogger(sender: TelemetrySender, options?: TelemetryLoggerOptions | undefined): TelemetryLogger {
-        const logger = new TelemetryLogger(sender, this._isTelemetryEnabled, options);
-        this.onDidChangeTelemetryEnabled(isEnabled => {
-            logger.telemetryEnabled = isEnabled;
-        });
-        return logger;
+        return new TelemetryLogger(sender, this.currentLevel, this.onDidChangeTelemetryLevel, options);
     }
 }
 
@@ -49,30 +70,36 @@ export class TelemetryLogger {
     readonly options: TelemetryLoggerOptions | undefined;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     readonly commonProperties: Record<string, any>;
-    private _telemetryEnabled: boolean;
+    private _level: TelemetryLevel;
 
     private readonly onDidChangeEnableStatesEmitter: Emitter<TelemetryLogger> = new Emitter();
     readonly onDidChangeEnableStates: Event<TelemetryLogger> = this.onDidChangeEnableStatesEmitter.event;
     private _isUsageEnabled: boolean;
     private _isErrorsEnabled: boolean;
+    private readonly levelSubscription: Disposable;
 
-    constructor(sender: TelemetrySender, telemetryEnabled: boolean, options?: TelemetryLoggerOptions) {
+    constructor(sender: TelemetrySender, level: TelemetryLevel, onDidChangeTelemetryLevel: Event<TelemetryLevel>, options?: TelemetryLoggerOptions) {
         this.sender = sender;
         this.options = options;
         this.commonProperties = this.getCommonProperties();
-        this._telemetryEnabled = telemetryEnabled;
-        this._isErrorsEnabled = telemetryEnabled;
-        this._isUsageEnabled = telemetryEnabled;
+        this._level = level;
+        this._isErrorsEnabled = isKindAllowedByLevel(level, 'error');
+        this._isUsageEnabled = isKindAllowedByLevel(level, 'usage');
+        this.levelSubscription = onDidChangeTelemetryLevel(next => this.applyLevel(next));
     }
 
-    get telemetryEnabled(): boolean {
-        return this._telemetryEnabled;
+    /**
+     * The telemetry level the user consented to. Must stay read-only: the object handed to a plugin is proxied with a
+     * `get` trap only, so a setter here would let the plugin raise its own gate.
+     */
+    get level(): TelemetryLevel {
+        return this._level;
     }
 
-    set telemetryEnabled(telemetryEnabled: boolean) {
-        if (this._telemetryEnabled !== telemetryEnabled) {
-            this._telemetryEnabled = telemetryEnabled;
-            this.updateEnableStates(telemetryEnabled, telemetryEnabled);
+    private applyLevel(level: TelemetryLevel): void {
+        if (this._level !== level) {
+            this._level = level;
+            this.updateEnableStates(isKindAllowedByLevel(level, 'usage'), isKindAllowedByLevel(level, 'error'));
         }
     }
 
@@ -108,7 +135,7 @@ export class TelemetryLogger {
 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     logUsage(eventName: string, data?: Record<string, any | TelemetryTrustedValue<any>>): void {
-        if (!this.telemetryEnabled || !this.isUsageEnabled) {
+        if (!isKindAllowedByLevel(this._level, 'usage') || !this.isUsageEnabled) {
             return;
         }
         this.logEvent(eventName, data);
@@ -116,7 +143,7 @@ export class TelemetryLogger {
 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     logError(eventNameOrException: string | Error, data?: Record<string, any | TelemetryTrustedValue<any>>): void {
-        if (!this.telemetryEnabled || !this.isErrorsEnabled || !this.sender) {
+        if (!isKindAllowedByLevel(this._level, 'error') || !this.isErrorsEnabled || !this.sender) {
             // no sender available or error shall not be sent
             return;
         }
@@ -128,14 +155,17 @@ export class TelemetryLogger {
     }
 
     dispose(): void {
-        if (this.sender?.flush) {
-            let tempSender: TelemetrySender | undefined = this.sender;
-            this.sender = undefined;
-            Promise.resolve(tempSender.flush!()).then(tempSender = undefined);
-        } else {
-            this.sender = undefined;
+        this.levelSubscription.dispose();
+        this.onDidChangeEnableStatesEmitter.dispose();
+        const sender = this.sender;
+        this.sender = undefined;
+        const reportFlushFailure = (error: unknown): void => console.error('Failed to flush the telemetry sender.', error);
+        try {
+            Promise.resolve(sender?.flush?.()).catch(reportFlushFailure);
+        } catch (error) {
+            reportFlushFailure(error);
         }
-    };
+    }
 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     private logEvent(eventName: string, data?: Record<string, any>): void {

package/src/plugin-ext-frontend-only-module.ts

@@ -0,0 +1,34 @@
+// *****************************************************************************
+// Copyright (C) 2026 Robert Jandow
+//
+// 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 { ContainerModule } from '@theia/core/shared/inversify';
+import { HostedPluginServer, PluginServer } from './common/plugin-protocol';
+import { BrowserOnlyHostedPluginServer } from './hosted/browser-only/browser-only-hosted-plugin-server';
+import { PluginPathsService } from './main/common/plugin-paths-protocol';
+import { BrowserOnlyPluginPathsService } from './hosted/browser-only/browser-only-plugin-paths-service';
+import { BrowserOnlyPluginServer } from './hosted/browser-only/browser-only-plugin-server';
+import { BrowserOnlyPluginFileServiceContribution, BrowserOnlyPluginFileSystemProvider } from './hosted/browser-only/browser-only-plugin-file-system-provider';
+import { FileServiceContribution } from '@theia/filesystem/lib/browser/file-service';
+
+export default new ContainerModule((bind, unbind, isBound, rebind) => {
+    rebind(HostedPluginServer).to(BrowserOnlyHostedPluginServer).inSingletonScope();
+    rebind(PluginServer).to(BrowserOnlyPluginServer).inSingletonScope();
+    rebind(PluginPathsService).to(BrowserOnlyPluginPathsService).inSingletonScope();
+
+    bind(BrowserOnlyPluginFileSystemProvider).toSelf().inSingletonScope();
+    bind(BrowserOnlyPluginFileServiceContribution).toSelf().inSingletonScope();
+    bind(FileServiceContribution).toService(BrowserOnlyPluginFileServiceContribution);
+});