feat: add config cascade and config server listener

This makes it easier to write extensions that use configuration by exposing the current (optimistically synced with the client) configuration in one place.

Author: sqs

src/protocol/configuration.ts

@@ -109,15 +109,17 @@ export interface DidChangeConfigurationParams {
  * For example, the client might support configuring settings globally and per-user, and it is designed so that
  * user settings override global settings. Then there would be two subjects, one for global settings and one for
  * the user.
+ *
+ * @template S the settings type
  */
-export interface ConfigurationCascade {
+export interface ConfigurationCascade<C extends Settings = Settings> {
     /** The final settings, merged from all subjects in the cascade. */
-    merged: Settings
+    merged: C
 
     /**
      * The configuration subjects in the cascade, from lower to higher precedence.
      *
      * Extensions: The merged settings value usually suffices.
      */
-    subjects?: { settings: Settings }[]
+    subjects?: { settings: C }[]
 }

src/server/features/client.ts

@@ -2,7 +2,7 @@ import { Unsubscribable } from 'rxjs'
 import uuidv4 from 'uuid/v4'
 import { MessageType as RPCMessageType, NotificationType, RequestType } from '../../jsonrpc2/messages'
 import {
-    ClientCapabilities,
+    InitializeParams,
     Registration,
     RegistrationParams,
     RegistrationRequest,
@@ -211,7 +211,7 @@ export class RemoteClientImpl implements RemoteClient {
         return this._connection
     }
 
-    public initialize(_capabilities: ClientCapabilities): void {
+    public initialize(_params: InitializeParams): void {
         /* noop */
     }
 

src/server/features/common.ts

@@ -1,10 +1,11 @@
-import { ClientCapabilities, ServerCapabilities } from '../../protocol'
+import { Unsubscribable } from 'rxjs'
+import { InitializeParams, ServerCapabilities } from '../../protocol'
 import { IConnection } from '../server'
 
 /**
- *
+ * A proxy for values and methods that exist on the remote client.
  */
-export interface Remote {
+export interface Remote extends Partial<Unsubscribable> {
     /**
      * Attach the remote to the given connection.
      *
@@ -21,9 +22,9 @@ export interface Remote {
      * Called to initialize the remote with the given
      * client capabilities
      *
-     * @param capabilities The client capabilities
+     * @param params the initialization parameters from the client
      */
-    initialize(capabilities: ClientCapabilities): void
+    initialize(params: InitializeParams): void
 
     /**
      * Called to fill in the server capabilities this feature implements.

src/server/features/configuration.test.ts

@@ -0,0 +1,135 @@
+import assert from 'assert'
+import { NotificationHandler } from '../../jsonrpc2/handlers'
+import {
+    ConfigurationCascade,
+    ConfigurationUpdateParams,
+    ConfigurationUpdateRequest,
+    DidChangeConfigurationParams,
+    Settings,
+} from '../../protocol'
+import { IConnection } from '../server'
+import { RemoteConfiguration, setValueAtKeyPath } from './configuration'
+
+const EMPTY_MOCK_CONNECTION: IConnection = {
+    onDidChangeConfiguration: () => void 0,
+    sendRequest: () => Promise.resolve(void 0),
+} as any
+
+const FIXTURE_CONFIGURATION_CASCADE: ConfigurationCascade<Settings> = { merged: { a: 1 } }
+
+describe('RemoteConfigurationImpl', () => {
+    const create = (
+        connection: IConnection = EMPTY_MOCK_CONNECTION,
+        configurationCascade = FIXTURE_CONFIGURATION_CASCADE
+    ): RemoteConfiguration<Settings> => {
+        const remote = new RemoteConfiguration<Settings>()
+        remote.attach(connection)
+        remote.initialize({
+            root: null,
+            capabilities: {},
+            configurationCascade,
+            workspaceFolders: null,
+        })
+        return remote
+    }
+
+    it('initially reports an empty config', () => {
+        const remote = new RemoteConfiguration<Settings>()
+        assert.deepStrictEqual(remote.configuration.value, {} as Settings)
+    })
+
+    it('records the configuration value from initialize', () => {
+        const remote = create()
+        assert.deepStrictEqual(remote.configuration.value, { a: 1 } as Settings)
+    })
+
+    it('records the configuration value from client update notifications', () => {
+        let onDidChangeConfiguration: NotificationHandler<DidChangeConfigurationParams> | undefined
+        const remote = create({
+            ...EMPTY_MOCK_CONNECTION,
+            onDidChangeConfiguration: h => (onDidChangeConfiguration = h),
+        })
+        assert.ok(onDidChangeConfiguration)
+        onDidChangeConfiguration!({ configurationCascade: { merged: { b: 2 } } })
+        assert.deepStrictEqual(remote.configuration.value, { b: 2 } as Settings)
+    })
+
+    it('updateConfiguration edit is sent as request and reflected immediately', async () => {
+        const remote = create({
+            ...EMPTY_MOCK_CONNECTION,
+            sendRequest: async (type: any, params: any) => {
+                assert.strictEqual(type, ConfigurationUpdateRequest.type)
+                assert.deepStrictEqual(params, { path: ['b'], value: 2 } as ConfigurationUpdateParams)
+            },
+        })
+        const updated = remote.updateConfiguration(['b'], 2)
+        assert.deepStrictEqual(remote.configuration.value, { a: 1, b: 2 } as Settings)
+        await updated
+        assert.deepStrictEqual(remote.configuration.value, { a: 1, b: 2 } as Settings)
+    })
+
+    it('handles interleaved updateConfiguration and didChangeConfiguration (authoritative)', async () => {
+        let onDidChangeConfiguration: NotificationHandler<DidChangeConfigurationParams> | undefined
+        const remote = create({
+            ...EMPTY_MOCK_CONNECTION,
+            sendRequest: async (type: any, params: any) => {
+                assert.strictEqual(type, ConfigurationUpdateRequest.type)
+                assert.deepStrictEqual(params, { path: ['b'], value: 2 } as ConfigurationUpdateParams)
+            },
+            onDidChangeConfiguration: h => (onDidChangeConfiguration = h),
+        })
+        const updated = remote.updateConfiguration(['b'], 2)
+        assert.deepStrictEqual(remote.configuration.value, { a: 1, b: 2 } as Settings)
+        onDidChangeConfiguration!({ configurationCascade: { merged: { c: 3 } } })
+        await updated
+        assert.deepStrictEqual(remote.configuration.value, { c: 3 } as Settings)
+    })
+})
+
+describe('setValueAtKeyPath', () => {
+    it('overwrites the top level', () => assert.deepStrictEqual(setValueAtKeyPath({ a: 1 }, [], { b: 2 }), { b: 2 }))
+    it('overwrites an existing property', () => assert.deepStrictEqual(setValueAtKeyPath({ a: 1 }, ['a'], 2), { a: 2 }))
+    it('sets a new property', () => assert.deepStrictEqual(setValueAtKeyPath({ a: 1 }, ['b'], 2), { a: 1, b: 2 }))
+    it('sets a property overwriting an array', () => assert.deepStrictEqual(setValueAtKeyPath([1], ['a'], 2), { a: 2 }))
+    it('sets a property overwriting a primitive', () =>
+        assert.deepStrictEqual(setValueAtKeyPath(1 as any, ['a'], 2), { a: 2 }))
+    it('overwrites an existing nested property', () =>
+        assert.deepStrictEqual(setValueAtKeyPath({ a: { b: 1 } }, ['a', 'b'], 2), { a: { b: 2 } }))
+    it('deletes a property', () =>
+        assert.deepStrictEqual(setValueAtKeyPath({ a: 1, b: 2 }, ['a'], undefined), { b: 2 }))
+    it('sets a new nested property', () =>
+        assert.deepStrictEqual(setValueAtKeyPath({ a: { b: 1 } }, ['a', 'c'], 2), { a: { b: 1, c: 2 } }))
+    it('sets a new deeply nested property', () =>
+        assert.deepStrictEqual(setValueAtKeyPath({ a: { b: { c: 1 } } }, ['a', 'b', 'd'], 2), {
+            a: { b: { c: 1, d: 2 } },
+        }))
+    it('overwrites an object', () => assert.deepStrictEqual(setValueAtKeyPath({ a: { b: 1 } }, ['a'], 2), { a: 2 }))
+    it('sets a value that requires a new object', () =>
+        assert.deepStrictEqual(setValueAtKeyPath({}, ['a', 'b'], 1), { a: { b: 1 } }))
+
+    it('overwrites an existing index', () => assert.deepStrictEqual(setValueAtKeyPath([1], [0], 2), [2]))
+    it('inserts a new index', () => assert.deepStrictEqual(setValueAtKeyPath([1], [1], 2), [1, 2]))
+    it('inserts a new index at end', () => assert.deepStrictEqual(setValueAtKeyPath([1, 2], [-1], 3), [1, 2, 3]))
+    it('inserts an index overwriting an object', () => assert.deepStrictEqual(setValueAtKeyPath({ a: 1 }, [0], 2), [2]))
+    it('inserts an index overwriting a primitive', () =>
+        assert.deepStrictEqual(setValueAtKeyPath(1 as any, [0], 2), [2]))
+    it('overwrites an existing nested index', () =>
+        assert.deepStrictEqual(setValueAtKeyPath([1, [2]], [1, 0], 3), [1, [3]]))
+    it('deletes an index', () => assert.deepStrictEqual(setValueAtKeyPath([1, 2, 3], [1], undefined), [1, 3]))
+    it('sets a new nested index', () =>
+        assert.deepStrictEqual(setValueAtKeyPath([1, [1, 2, [1, 2, 3, 4]]], [1, 2, 3], 5), [1, [1, 2, [1, 2, 3, 5]]]))
+    it('inserts a new nested index at end', () =>
+        assert.deepStrictEqual(setValueAtKeyPath([1, [2]], [1, -1], 3), [1, [2, 3]]))
+    it('overwrites an array', () => assert.deepStrictEqual(setValueAtKeyPath([1, [2]], [1], 3), [1, 3]))
+    it('sets a value that requires a new array', () => assert.deepStrictEqual(setValueAtKeyPath([], [0, 0], 1), [[1]]))
+
+    it('sets a nested property (and does not modify input)', () => {
+        const input = { a: [{}, { b: [1, 2] }] }
+        const origInput = JSON.parse(JSON.stringify(input))
+        assert.deepStrictEqual(setValueAtKeyPath(input, ['a', 1, 'b', -1], { c: 3 }), {
+            a: [{}, { b: [1, 2, { c: 3 }] }],
+        })
+        assert.deepStrictEqual(input, origInput)
+    })
+    it('throws on invalid key type', () => assert.throws(() => setValueAtKeyPath({}, [true as any], {})))
+})

src/server/features/configuration.ts

@@ -0,0 +1,166 @@
+import { BehaviorSubject, Observable, Subscription, Unsubscribable } from 'rxjs'
+import { distinctUntilChanged, map } from 'rxjs/operators'
+import { Emitter, Event } from '../../jsonrpc2/events'
+import { InitializeParams, ServerCapabilities } from '../../protocol'
+import {
+    ConfigurationCascade,
+    ConfigurationUpdateParams,
+    ConfigurationUpdateRequest,
+    KeyPath,
+    Settings,
+} from '../../protocol/configuration'
+import { isEqual } from '../../util'
+import { IConnection } from '../server'
+import { Remote } from './common'
+
+/**
+ * A proxy for the client's configuration.
+ *
+ * @template C settings type
+ */
+export class RemoteConfiguration<C extends Settings> implements Remote, Unsubscribable {
+    private subscription = new Subscription()
+    private _connection?: IConnection
+    private _configurationCascade = new BehaviorSubject<ConfigurationCascade<C>>({ merged: {} as C })
+    private onChange = new Emitter<void>()
+
+    /**
+     * An observable of the configuration that emits whenever it changes (when the extension itself updates the
+     * configuration, or when the extension receives a workspace/didChangeConfiguration notification from the
+     * client).
+     *
+     * The current merged configuration is available in the `value` property of the returned object, for callers
+     * that want to access it directly without subscribing to the observable.
+     */
+    public get configuration(): Observable<Readonly<C>> & { value: Readonly<C> } {
+        const o: Observable<C> & { value: C } = Object.create(
+            this._configurationCascade.pipe(
+                map(({ merged }) => merged),
+                distinctUntilChanged((a, b) => isEqual(a, b))
+            )
+        )
+        o.value = this._configurationCascade.value.merged
+        return o
+    }
+
+    /**
+     * Emits when the configuration changes (when the extension itself updates the configuration, or when the
+     * extension receives a workspace/didChangeConfiguration notification from the client).
+     */
+    public readonly onDidChangeConfiguration: Event<void> = this.onChange.event
+
+    public attach(connection: IConnection): void {
+        this._connection = connection
+
+        // Listen for `workspace/didChangeConfiguration` notifications from the client.
+        this.subscription.add(
+            connection.onDidChangeConfiguration(params => {
+                this._configurationCascade.next(params.configurationCascade as ConfigurationCascade<C>)
+                this.onChange.fire(void 0)
+            })
+        )
+    }
+
+    public get connection(): IConnection {
+        if (!this._connection) {
+            throw new Error('Remote is not attached to a connection yet.')
+        }
+        return this._connection
+    }
+
+    public initialize(params: InitializeParams): void {
+        this._configurationCascade.next(params.configurationCascade as ConfigurationCascade<C>)
+        this.onChange.fire(void 0)
+    }
+
+    public fillServerCapabilities(_capabilities: ServerCapabilities): void {
+        /* noop */
+    }
+
+    /**
+     * Updates the configuration setting at the given key path to the given value. The local merged configuration
+     * is immediately updated to reflect the change (optimistically, even before the server acknowledges the
+     * update).
+     *
+     * Implementation: sends a configuration/update notification to the client.
+     *
+     * @param path the key path of the configuration setting to update
+     * @param value the value to insert
+     */
+    public updateConfiguration(path: KeyPath, value: any): Promise<void> {
+        // Optimistically apply configuration update locally. If this diverges from the server's state, a
+        // subsequent didChangeConfiguration notification will inform us.
+        const cur = this._configurationCascade.value
+        this._configurationCascade.next({ ...cur, merged: setValueAtKeyPath(cur.merged, path, value) })
+        this.onChange.fire(void 0)
+
+        return this.connection.sendRequest(ConfigurationUpdateRequest.type, {
+            path,
+            value,
+        } as ConfigurationUpdateParams)
+    }
+
+    public unsubscribe(): void {
+        this.subscription.unsubscribe()
+    }
+}
+
+/**
+ * Returns the source object with the given value inserted in the location specified by the key path. The source
+ * object is not modified. The key path indexes into the object successively for each element in the key path.
+ *
+ * If the value is `undefined`, the value at the key path is removed.
+ *
+ * This must behave identically to {@link module:jsonc-parser.setProperty}.
+ */
+export function setValueAtKeyPath(source: any, path: KeyPath, value: any): any {
+    if (path.length === 0) {
+        // Overwrite entire value.
+        return value
+    }
+
+    const root = [source]
+    let prev: any = root // maintain an lvalue that we can assign to
+    for (const [i, key] of path.entries()) {
+        const last = i === path.length - 1
+        const prevKey = i === 0 ? 0 : path[i - 1]
+        if (typeof key === 'string') {
+            if (last) {
+                if (value === undefined) {
+                    prev[prevKey] = { ...prev[prevKey] }
+                    delete prev[prevKey][key]
+                } else if (
+                    prev[prevKey] !== null &&
+                    typeof prev[prevKey] === 'object' &&
+                    !Array.isArray(prev[prevKey])
+                ) {
+                    prev[prevKey] = { ...prev[prevKey], [key]: value }
+                } else {
+                    prev[prevKey] = { [key]: value }
+                }
+            } else {
+                prev[prevKey] =
+                    prev[prevKey] !== null && typeof prev[prevKey] === 'object' && !Array.isArray(prev[prevKey])
+                        ? { ...prev[prevKey] }
+                        : {}
+            }
+        } else if (typeof key === 'number') {
+            if (last) {
+                const index = key === -1 ? prev[prevKey].length : key
+                const head = Array.isArray(prev[prevKey]) ? prev[prevKey].slice(0, index) : []
+                const tail = Array.isArray(prev[prevKey]) ? prev[prevKey].slice(index + 1) : []
+                if (value === undefined) {
+                    prev[prevKey] = [...head, ...tail]
+                } else {
+                    prev[prevKey] = [...head, value, ...tail]
+                }
+            } else {
+                prev[prevKey] = Array.isArray(prev[prevKey]) ? [...prev[prevKey]] : []
+            }
+        } else {
+            throw new Error(`invalid key in key path: ${key} (full key path: ${JSON.stringify(path)}`)
+        }
+        prev = prev[prevKey]
+    }
+    return root[0]
+}

src/server/features/console.ts

@@ -1,5 +1,5 @@
 import { Logger, MessageConnection } from '../../jsonrpc2/connection'
-import { ClientCapabilities, LogMessageNotification, MessageType, ServerCapabilities } from '../../protocol'
+import { InitializeParams, LogMessageNotification, MessageType, ServerCapabilities } from '../../protocol'
 import { IConnection } from '../server'
 import { Remote } from './common'
 
@@ -61,7 +61,7 @@ export class ConnectionLogger implements Logger, RemoteConsole {
         /* noop */
     }
 
-    public initialize(_capabilities: ClientCapabilities): void {
+    public initialize(_params: InitializeParams): void {
         /* noop */
     }