UNPKG

@theia/core

Version:

Theia is a cloud & desktop IDE framework implemented in TypeScript.

576 lines (519 loc) • 28.7 kB
// ***************************************************************************** // Copyright (C) 2018 Ericsson 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 // ***************************************************************************** /* eslint-disable @typescript-eslint/no-explicit-any */ import { JSONValue } from '@lumino/coreutils'; import { inject, injectable, postConstruct, named } from 'inversify'; import { Disposable, DisposableCollection } from '../disposable.js'; import { Emitter, Event } from '../event.js'; import { Deferred } from '../promise-util.js'; import URI from '../uri.js'; import { PreferenceLanguageOverrideService } from './preference-language-override-service.js'; import { PreferenceProvider, PreferenceProviderDataChange, PreferenceProviderDataChanges, PreferenceResolveResult, PreferenceUtils } from './preference-provider.js'; import { PreferenceSchemaService } from './preference-schema.js'; import { PreferenceScope } from './preference-scope.js'; import { PreferenceConfigurations } from './preference-configurations.js'; import { deepFreeze } from '../objects.js'; import { unreachable } from '../types.js'; import { ILogger } from '../logger.js'; type AtLeastOneKey<T> = { [K in keyof T]: Pick<T, K> & Partial<Omit<T, K>> }[keyof T]; interface PreferenceGetOptionsRaw<T> { /** Value to return when no stored value exists for the preference. */ fallback: T | undefined; /** URI of the resource for which to retrieve the preference. */ resource: string | undefined; /** Language-override identifier (e.g. `'typescript'`). */ override: string | undefined; } /** * Options for {@link PreferenceService.get()}. At least one of the keys has to be present. */ export type PreferenceGetOptions<T> = AtLeastOneKey<PreferenceGetOptionsRaw<T>>; /** * Representation of a preference change. A preference value can be set to `undefined` for a specific scope. * This means that the value from a more general scope will be used. */ export interface PreferenceChange { readonly preferenceName: string; readonly scope: PreferenceScope; /** * URIs of the scopes in which this change applies. */ readonly domain?: string[]; /** * Tests wether the given resource is affected by the preference change. * @param resourceUri the uri of the resource to test. */ affects(resourceUri?: string, overrideIdentifier?: string): boolean; readonly affectedOverrides: readonly string[]; } export class PreferenceChangeImpl implements PreferenceChange { protected readonly change: PreferenceProviderDataChange; constructor(change: PreferenceProviderDataChange, readonly affectedOverrides: readonly string[]) { this.change = deepFreeze(change); } get preferenceName(): string { return this.change.preferenceName; } get scope(): PreferenceScope { return this.change.scope; } get domain(): string[] | undefined { return this.change.domain; } affects(resourceUri?: string, overrideIdentifier?: string): boolean { const resourcePath = resourceUri && new URI(resourceUri).path; const domain = this.change.domain; const affectsResource = !resourcePath || !domain || domain.some(uri => new URI(uri).path.relativity(resourcePath) >= 0); const affectsOverride = !overrideIdentifier || this.affectedOverrides.includes(overrideIdentifier); return affectsResource && affectsOverride; } } export type PreferenceChanges = PreferenceChange[]; export const PreferenceService = Symbol('PreferenceService'); /** * Service to manage preferences including, among others, getting and setting preference values as well * as listening to preference changes. * * Depending on your use case you might also want to look at {@link createPreferenceProxy} with which * you can easily create a typesafe schema-based interface for your preferences. Internally the proxy * uses the PreferenceService so both approaches are compatible. */ export interface PreferenceService extends Disposable { /** * Promise indicating whether the service successfully initialized. */ readonly ready: Promise<void>; /** * Indicates whether the service has successfully initialized. Will be `true` when {@link PreferenceService.ready the `ready` Promise} resolves. */ readonly isReady: boolean; /** * Retrieve the stored value for the given preference. * * @param preferenceName the preference identifier. * @param options optional lookup options. * - `fallback` – value to return when no stored value exists. * - `resource` – URI of the resource for which the preference is stored (enables per-resource values, e.g. `files.encoding`). * - `override` – language-override identifier (e.g. `'typescript'`). * * @returns the stored value when it exists, otherwise `options.fallback` (or `undefined` when no fallback is given). */ get(preferenceName: string, defaultValue: string): string; get(preferenceName: string, defaultValue: number): number; get(preferenceName: string, defaultValue: boolean): boolean; get<T extends string | number | boolean>(preferenceName: string, defaultValue: T): T; get<T extends unknown[]>(preferenceName: string, defaultValue: T): T; get<T>(preferenceName: string, options: PreferenceGetOptions<T> & { fallback: T }): T; get<T>(preferenceName: string, options?: PreferenceGetOptions<T>): T | undefined; /** * Sets the given preference to the given value. * * @param preferenceName the preference identifier. * @param value the new value of the preference. * @param scope the scope for which the value shall be set, i.e. user, workspace etc. * When the folder scope is specified a resourceUri must be provided. * @param resourceUri the uri of the resource for which the preference is stored. This used to store * a potentially different value for the same preference for different resources, for example `files.encoding`. * @param overrideIdentifier the identifier of the override to use. * * @returns a promise which resolves to `undefined` when setting the preference was successful. Otherwise it rejects * with an error. */ set(preferenceName: string, value: any, scope?: PreferenceScope, resourceUri?: string, overrideIdentifier?: string): Promise<void>; /** * Determines and applies the changes necessary to apply `value` to either the `resourceUri` supplied or the active session. * If there is no setting for the `preferenceName`, the change will be applied in user scope. * If there is a setting conflicting with the specified `value`, the change will be applied in the most specific scope with a conflicting value. * * @param preferenceName the identifier of the preference to modify. * @param value the value to which to set the preference. `undefined` will reset the preference to its default value. * @param resourceUri the uri of the resource to which the change is to apply. If none is provided, folder scope will be ignored. * @param overrideIdentifier the identifier of the override to use. */ updateValue(preferenceName: string, value: any, resourceUri?: string, overrideIdentifier?: string): Promise<void> /** * Registers a callback which will be called whenever a preference is changed. */ onPreferenceChanged: Event<PreferenceChange>; /** * Registers a callback which will be called whenever one or more preferences are changed. */ onPreferencesChanged: Event<PreferenceChanges>; /** * Retrieve the stored value for the given preference and resourceUri in all available scopes. * * @param preferenceName the preference identifier. * @param resourceUri the uri of the resource for which the preference is stored. * @param overrideIdentifier the identifier of the override to use. * Values for the override are returned where defined, values of the base preference otherwise. * * @return an object containing the value of the given preference for all scopes. */ inspect<T extends JSONValue>(preferenceName: string, resourceUri?: string, overrideIdentifier?: string): PreferenceInspection<T> | undefined; /** * For behavior, see {@link PreferenceService.inspect}. * * @returns the value in the scope specified. */ inspectInScope<T extends JSONValue>(preferenceName: string, scope: PreferenceScope, resourceUri?: string, overrideIdentifier?: string): T | undefined /** * Retrieve the stored value for the given preference and resourceUri. * * @param preferenceName the preference identifier. * @param defaultValue the value to return when no value for the given preference is stored. * @param resourceUri the uri of the resource for which the preference is stored. This used to retrieve * a potentially different value for the same preference for different resources, for example `files.encoding`. * @param overrideIdentifier the identifier of the override to use. * * @returns an object containing the value stored for the given preference and resourceUri when it exists, * otherwise the given default value. If determinable the object will also contain the uri of the configuration * resource in which the preference was stored. */ resolve<T>(preferenceName: string, defaultValue?: T, resourceUri?: string, overrideIdentifier?: string): PreferenceResolveResult<T>; /** * Returns the uri of the configuration resource for the given scope and optional resource uri. * * @param scope the PreferenceScope to query for. * @param resourceUri the optional uri of the resource-specific preference handling * @param sectionName the optional preference section to query for. * * @returns the uri of the configuration resource for the given scope and optional resource uri it it exists, * `undefined` otherwise. */ getConfigUri(scope: PreferenceScope, resourceUri?: string, sectionName?: string): URI | undefined; } /** * Return type of the {@link PreferenceService.inspect} call. */ export interface PreferenceInspection<T = JSONValue> { /** * The preference identifier. */ preferenceName: string, /** * Value in default scope. */ defaultValue: T | undefined, /** * Value in user scope. */ globalValue: T | undefined, /** * Value in workspace scope. */ workspaceValue: T | undefined, /** * Value in folder scope. */ workspaceFolderValue: T | undefined, /** * Value in session scope (in-memory, set via `--session-preference`). */ sessionValue?: T | undefined, /** * The value that is active, i.e. the value set in the lowest scope available. */ value: T | undefined; } export type PreferenceInspectionScope = keyof Omit<PreferenceInspection<unknown>, 'preferenceName'>; /** * We cannot load providers directly in the case if they depend on `PreferenceService` somehow. * It allows to load them lazily after DI is configured. */ export const PreferenceProviderProvider = Symbol('PreferenceProviderProvider'); export type PreferenceProviderProvider = (scope: PreferenceScope, uri?: URI) => PreferenceProvider | undefined; @injectable() export class PreferenceServiceImpl implements PreferenceService { protected readonly onPreferenceChangedEmitter = new Emitter<PreferenceChange>(); readonly onPreferenceChanged = this.onPreferenceChangedEmitter.event; protected readonly onPreferencesChangedEmitter = new Emitter<PreferenceChanges>(); readonly onPreferencesChanged = this.onPreferencesChangedEmitter.event; protected readonly toDispose = new DisposableCollection(this.onPreferenceChangedEmitter, this.onPreferencesChangedEmitter); @inject(PreferenceSchemaService) protected readonly schemaService: PreferenceSchemaService; @inject(PreferenceProviderProvider) protected readonly providerProvider: PreferenceProviderProvider; @inject(PreferenceConfigurations) protected readonly configurations: PreferenceConfigurations; @inject(PreferenceLanguageOverrideService) protected readonly preferenceOverrideService: PreferenceLanguageOverrideService; @inject(ILogger) @named('core:PreferenceServiceImpl') protected readonly logger: ILogger; protected readonly preferenceProviders = new Map<PreferenceScope, PreferenceProvider>(); protected async initializeProviders(): Promise<void> { try { for (const scope of this.schemaService.validScopes) { const provider = this.providerProvider(scope); if (provider) { this.preferenceProviders.set(scope, provider); this.toDispose.push(provider.onDidPreferencesChanged(changes => this.reconcilePreferences(changes) )); await provider.ready; } else { this.logger.warn(`No preference provider bound for ${PreferenceScope[scope]}`); } } this._ready.resolve(); this._isReady = true; } catch (e) { this._ready.reject(e); } } @postConstruct() protected init(): void { this.toDispose.push(Disposable.create(() => this._ready.reject(new Error('preference service is disposed')))); this.initializeProviders(); } dispose(): void { this.toDispose.dispose(); } protected readonly _ready = new Deferred<void>(); get ready(): Promise<void> { return this._ready.promise; } protected _isReady = false; get isReady(): boolean { return this._isReady; } protected getAffectedOverrides(change: PreferenceProviderDataChange): string[] { if (change.overrideIdentifier) { // changes to overrides never affect other overrides return [change.overrideIdentifier]; } const preference = this.schemaService.getSchemaProperty(change.preferenceName); // Non-overridable preferences apply in every language context. if (preference && !preference.overridable) { return [...this.schemaService.overrideIdentifiers]; } const affectedOverrides: string[] = []; for (const overrideId of this.schemaService.overrideIdentifiers) { if (!this.doHas(change.preferenceName, undefined, overrideId)) { affectedOverrides.push(overrideId); } } return affectedOverrides; } protected reconcilePreferences(changes: PreferenceProviderDataChanges): void { const changesToEmit: PreferenceChanges = []; for (const change of changes) { for (const scope of [...this.schemaService.validScopes].reverse()) { const provider = this.getProvider(scope); if (provider) { const scopeValue: JSONValue | undefined = provider.get(change.preferenceName, undefined, change.overrideIdentifier); if (scope > change.scope && scopeValue !== undefined) { const preference = this.schemaService.getSchemaProperty(change.preferenceName); if (!preference?.type || preference.type === 'object' || preference.type === 'array' || Array.isArray(preference.type) && preference.type.some(candidate => candidate === 'object' || candidate === 'array')) { // Merge object/array preferences changesToEmit.push(new PreferenceChangeImpl({ ...change }, this.getAffectedOverrides(change))); } break; } // Handle changes in the same scope if (scope === change.scope) { const hasNewValue = change.newValue !== undefined || scope === PreferenceScope.Default; const isResetToUndefined = change.newValue === undefined && scopeValue === undefined; // is reset to undefined (no default value) if (hasNewValue || isResetToUndefined) { changesToEmit.push(new PreferenceChangeImpl({ ...change }, this.getAffectedOverrides(change))); break; } } // Handle fallback to more general scope when preference is reset if (scope < change.scope && change.newValue === undefined && scopeValue !== undefined) { // preference is changed to `undefined`, use the value from a more general scope changesToEmit.push(new PreferenceChangeImpl({ ...change, scope }, this.getAffectedOverrides(change))); break; } } } } // emit the changes if (changesToEmit.length > 0) { this.onPreferencesChangedEmitter.fire(changesToEmit); } changesToEmit.forEach(change => this.onPreferenceChangedEmitter.fire(change)); } protected getProvider(scope: PreferenceScope): PreferenceProvider | undefined { return this.preferenceProviders.get(scope); } has(preferenceName: string, resourceUri?: string, overrideIdentifier?: string): boolean { return this.get(preferenceName, { resource: resourceUri, override: overrideIdentifier }) !== undefined; } get(preferenceName: string, defaultValue: string): string; get(preferenceName: string, defaultValue: number): number; get(preferenceName: string, defaultValue: boolean): boolean; get<T extends string | number | boolean>(preferenceName: string, defaultValue: T): T; get<T extends unknown[]>(preferenceName: string, defaultValue: T): T; get<T>(preferenceName: string, options: PreferenceGetOptions<T> & { fallback: T }): T; get<T>(preferenceName: string, options?: PreferenceGetOptions<T>): T | undefined; get<T>(preferenceName: string, optionsOrFallback?: PreferenceGetOptions<T> | string | number | boolean | T[]): T | undefined { let fallback: T | undefined; let resource: string | undefined; let override: string | undefined; if (typeof optionsOrFallback === 'string' || typeof optionsOrFallback === 'number' || typeof optionsOrFallback === 'boolean' || Array.isArray(optionsOrFallback)) { fallback = optionsOrFallback as T; } else if (optionsOrFallback) { ({ fallback, resource, override } = optionsOrFallback); } return this.resolve<T>(preferenceName, fallback, resource, override).value; } resolve<T>(preferenceName: string, defaultValue?: T, resourceUri?: string, overrideIdentifier?: string): PreferenceResolveResult<T> { const { value, configUri } = this.doResolve(preferenceName, defaultValue, resourceUri, overrideIdentifier); if (value === undefined && overrideIdentifier && this.schemaService.overrideIdentifiers.has(overrideIdentifier)) { return this.doResolve(preferenceName, defaultValue, resourceUri, undefined); } return { value, configUri }; } async set(preferenceName: string, value: any, scope: PreferenceScope | undefined, resourceUri?: string, overrideIdentifier?: string): Promise<void> { const resolvedScope = scope ?? (!resourceUri ? PreferenceScope.Workspace : PreferenceScope.Folder); if (resolvedScope === PreferenceScope.Folder && !resourceUri) { throw new Error('Unable to write to Folder Settings because no resource is provided.'); } const provider = this.getProvider(resolvedScope); if (provider && await provider.setPreference(preferenceName, value, resourceUri, overrideIdentifier)) { await this.evictSessionOverride(preferenceName, resolvedScope, overrideIdentifier); return; } throw new Error(`Unable to write to ${PreferenceScope[resolvedScope]} Settings.`); } /** * When a preference is written to a persistent scope, drop any in-memory session * override (set via `--session-preference`) for the same key so that the explicit * change takes effect for the remainder of the session. Without this, the session * scope would keep shadowing the user's change because it has higher precedence. * * Note: this fires for any write to a persistent scope, including programmatic * writes from extensions. Extensions that race with startup CLI overrides will * therefore clear them. This is intentional: a programmatic write is "explicit" * from the preference system's point of view, but consumers should be aware. * * Session preferences are global (no per-resource scoping), so `resourceUri` is * not threaded through. */ protected async evictSessionOverride(preferenceName: string, writtenScope: PreferenceScope, overrideIdentifier?: string): Promise<void> { if (writtenScope === PreferenceScope.Session || writtenScope === PreferenceScope.Default) { return; } const sessionProvider = this.getProvider(PreferenceScope.Session); if (sessionProvider && sessionProvider.get(preferenceName, undefined, overrideIdentifier) !== undefined) { // Passing `undefined` clears the value in the session provider. await sessionProvider.setPreference(preferenceName, undefined as unknown as JSONValue, undefined, overrideIdentifier); } } inspect<T extends JSONValue>(preferenceName: string, resourceUri?: string, overrideIdentifier?: string): PreferenceInspection<T> | undefined { const defaultValue = this.inspectInScope<T>(preferenceName, PreferenceScope.Default, resourceUri, overrideIdentifier); const globalValue = this.inspectInScope<T>(preferenceName, PreferenceScope.User, resourceUri, overrideIdentifier); const workspaceValue = this.inspectInScope<T>(preferenceName, PreferenceScope.Workspace, resourceUri, overrideIdentifier); const workspaceFolderValue = this.inspectInScope<T>(preferenceName, PreferenceScope.Folder, resourceUri, overrideIdentifier); const sessionValue = this.inspectInScope<T>(preferenceName, PreferenceScope.Session, resourceUri, overrideIdentifier); const valueApplied = sessionValue ?? workspaceFolderValue ?? workspaceValue ?? globalValue ?? defaultValue; return { preferenceName, defaultValue, globalValue, workspaceValue, workspaceFolderValue, sessionValue, value: valueApplied }; } inspectInScope<T extends JSONValue>(preferenceName: string, scope: PreferenceScope, resourceUri?: string, overrideIdentifier?: string): T | undefined { const value = this.doInspectInScope<T>(preferenceName, scope, resourceUri, overrideIdentifier); if (value === undefined && overrideIdentifier && this.schemaService.overrideIdentifiers.has(overrideIdentifier)) { return this.doInspectInScope<T>(preferenceName, scope, resourceUri, undefined); } return value; } protected getScopedValueFromInspection<T>(inspection: PreferenceInspection<T>, scope: PreferenceScope): T | undefined { switch (scope) { case PreferenceScope.Default: return inspection.defaultValue; case PreferenceScope.User: return inspection.globalValue; case PreferenceScope.Workspace: return inspection.workspaceValue; case PreferenceScope.Folder: return inspection.workspaceFolderValue; case PreferenceScope.Session: return inspection.sessionValue; } unreachable(scope, 'Not all PreferenceScope enum variants handled.'); } async updateValue(preferenceName: string, value: any, resourceUri?: string, overrideIdentifier?: string): Promise<void> { const inspection = this.inspect<any>(preferenceName, resourceUri, overrideIdentifier); if (inspection) { const scopesToChange = this.getScopesToChange(inspection, value); const isDeletion = value === undefined || ( scopesToChange.length === 1 && scopesToChange[0] === PreferenceScope.User && PreferenceUtils.deepEqual(value, inspection.defaultValue) ); const effectiveValue = isDeletion ? undefined : value; await Promise.all(scopesToChange.map(scope => this.set(preferenceName, effectiveValue, scope, resourceUri, overrideIdentifier))); } } protected getScopesToChange(inspection: PreferenceInspection<any>, intendedValue: any): PreferenceScope[] { if (PreferenceUtils.deepEqual(inspection.value, intendedValue)) { return []; } // Scopes in ascending order of scope breadth. const allScopes = [...this.schemaService.validScopes].reverse() // Default is read-only, and Session is populated only by `--session-preference`, // so neither is a valid target for a regular user edit. .filter(scope => scope !== PreferenceScope.Default && scope !== PreferenceScope.Session); const isScopeDefined = (scope: PreferenceScope) => this.getScopedValueFromInspection(inspection, scope) !== undefined; if (intendedValue === undefined) { return allScopes.filter(isScopeDefined); } return [allScopes.find(isScopeDefined) ?? PreferenceScope.User]; } protected doHas(preferenceName: string, resourceUri?: string, overrideIdentifier?: string): boolean { return this.doGet(preferenceName, undefined, resourceUri, overrideIdentifier) !== undefined; } protected doInspectInScope<T>(preferenceName: string, scope: PreferenceScope, resourceUri?: string, overrideIdentifier?: string): T | undefined { const provider = this.getProvider(scope); return provider && provider.get<T>(preferenceName, resourceUri, overrideIdentifier); } protected doGet<T>(preferenceName: string, defaultValue?: T, resourceUri?: string, overrideIdentifier?: string): T | undefined { return this.doResolve(preferenceName, defaultValue, resourceUri, overrideIdentifier).value; } protected doResolve<T>(preferenceName: string, defaultValue?: T, resourceUri?: string, overrideIdentifier?: string): PreferenceResolveResult<T> { const result: PreferenceResolveResult<T> = {}; for (const scope of this.schemaService.validScopes) { const provider = this.getProvider(scope); if (provider?.canHandleScope(scope)) { const { configUri, value } = provider.resolve<T>(preferenceName, resourceUri, overrideIdentifier); if (value !== undefined) { result.configUri = configUri; result.value = PreferenceUtils.merge(result.value as any, value as any) as any; } } } return { configUri: result.configUri, value: result.value !== undefined ? deepFreeze(result.value) : defaultValue }; } getConfigUri(scope: PreferenceScope, resourceUri?: string, sectionName: string = this.configurations.getConfigName()): URI | undefined { const provider = this.getProvider(scope); if (!provider || !this.configurations.isAnyConfig(sectionName)) { return undefined; } const configUri = provider.getConfigUri && provider.getConfigUri(resourceUri, sectionName); if (configUri) { return configUri; } return provider.getContainingConfigUri && provider.getContainingConfigUri(resourceUri, sectionName); } }