feat(extension): use new extension API handle (CXP + activateExtension)

BREAKING CHANGE: Extensions implemented using this package's `server` module must be ported to use the new `activateExtension` API and the `CXP` API handle type.

Author: sqs

src/client/client.integration.test.ts

@@ -1,15 +1,16 @@
 import * as assert from 'assert'
-import { MessageTransports } from '../jsonrpc2/connection'
+import { createMessageConnection, MessageConnection, MessageTransports } from '../jsonrpc2/connection'
 import { Trace } from '../jsonrpc2/trace'
 import { ClientCapabilities, InitializeParams, InitializeRequest, InitializeResult } from '../protocol'
-import { Connection as ServerConnection, createConnection as createServerConnection } from '../server/server'
 import { clientStateIsActive, getClientState } from '../test/helpers'
 import { createMessageTransports } from '../test/integration/helpers'
 import { Client, ClientState } from './client'
 
-const createClientTransportsForTestServer = (registerServer: (server: ServerConnection) => void): MessageTransports => {
+const createClientTransportsForTestServer = (
+    registerServer: (server: MessageConnection) => void
+): MessageTransports => {
     const [clientTransports, serverTransports] = createMessageTransports()
-    const serverConnection = createServerConnection(serverTransports)
+    const serverConnection = createMessageConnection(serverTransports)
     serverConnection.listen()
     registerServer(serverConnection)
     return clientTransports

src/environment/providers/command.ts

@@ -58,5 +58,5 @@ export function executeCommand(commands: CommandEntry[], params: ExecuteCommandP
     if (!command) {
         throw new Error(`command not found: ${JSON.stringify(params.command)}`)
     }
-    return command.run(...(params.arguments || []))
+    return Promise.resolve(command.run(...(params.arguments || [])))
 }

src/extension/api.ts

@@ -0,0 +1,217 @@
+import { Subscription } from 'rxjs'
+import { Context } from '../environment/context/context'
+import { MessageConnection } from '../jsonrpc2/connection'
+import { Settings } from '../protocol'
+import { URI } from '../types/textDocument'
+
+/**
+ * The CXP extension API, which extensions use to interact with the client.
+ *
+ * @template C the extension's settings
+ */
+export interface CXP<C = Settings> {
+    /**
+     * The root URI of the workspace in which this extension is running.
+     *
+     * TODO(sqs): Remove the strict association with the single initial root (support multi-root, changing roots,
+     * etc.).
+     */
+    root: URI | null
+
+    /**
+     * The configuration settings from the client.
+     */
+    configuration: Configuration<C>
+
+    /**
+     * The application windows on the client.
+     */
+    windows: Windows
+
+    /**
+     * Command registration and execution.
+     */
+    commands: Commands
+
+    /**
+     * Arbitrary key-value pairs that describe application state in a namespace shared by the client and all other
+     * extensions used by the client.
+     */
+    context: ExtensionContext
+
+    /** The underlying CXP connection to the client. */
+    readonly rawConnection: MessageConnection
+
+    /**
+     * Immediately stops the extension and closes the connection to the client.
+     */
+    close(): void
+}
+
+/**
+ * A stream of values that can be transformed (with {@link Observable#pipe}) and subscribed to (with
+ * {@link Observable#subscribe}).
+ *
+ * This is a subset of the {@link module:rxjs.Observable} interface, for simplicity and compatibility with future
+ * Observable standards.
+ *
+ * @template T The type of the values emitted by the {@link Observable}.
+ */
+export interface Observable<T> {
+    /**
+     * Registers callbacks that are called each time a certain event occurs in the stream of values.
+     *
+     * @param next Called when a new value is emitted in the stream.
+     * @param error Called when an error occurs (which also causes the observable to be closed).
+     * @param complete Called when the stream of values ends.
+     * @return A subscription that frees resources used by the subscription upon unsubscription.
+     */
+    subscribe(next?: (value: T) => void, error?: (error: any) => void, complete?: () => void): Subscription
+
+    /**
+     * Returns the underlying Observable value, for compatibility with other Observable implementations (such as
+     * RxJS).
+     *
+     * @internal
+     */
+    [Symbol.observable]?(): any
+}
+
+/**
+ * Configuration settings for a specific resource (such as a file, directory, or repository) or subject (such as a
+ * user or organization, depending on the client).
+ *
+ * It may be merged from the following sources of settings, in order:
+ *
+ * - Default settings
+ * - Global settings
+ * - Organization settings (for all organizations the user is a member of)
+ * - User settings
+ * - Client settings
+ * - Repository settings
+ * - Directory settings
+ *
+ * @template C configuration type
+ */
+export interface Configuration<C> extends Observable<C> {
+    /**
+     * Returns a value from the configuration.
+     *
+     * @template K Valid keys on the configuration object.
+     * @param key The name of the configuration property to get.
+     * @return The configuration value, or undefined.
+     */
+    get<K extends keyof C>(key: K): C[K] | undefined
+
+    /**
+     * Observes changes to the configuration values for the given keys.
+     *
+     * @template K Valid keys on the configuration object.
+     * @param keys The names of the configuration properties to observe.
+     * @return An observable that emits when any of the keys' values change (using deep comparison).
+     */
+    watch<K extends keyof C>(...keys: K[]): Observable<Pick<C, K>>
+
+    /**
+     * Updates the configuration value for the given key. The updated configuration value is sent to the client for
+     * persistence.
+     *
+     * @template K Valid keys on the configuration object.
+     * @param key The name of the configuration property to update.
+     * @param value The new value, or undefined to remove it.
+     * @return A promise that resolves when the client acknowledges the update.
+     */
+    update<K extends keyof C>(key: K, value: C[K] | undefined): Promise<void>
+
+    // TODO: Future plans:
+    //
+    // - add a way to read configuration from a specific scope (aka subject, but "scope" is probably a better word)
+    // - describe how configuration defaults are supported
+}
+
+/**
+ * The application windows on the client.
+ */
+export interface Windows extends Observable<Window[]> {
+    /**
+     * All application windows on the client.
+     */
+    all: Window[]
+
+    /**
+     * The active window, or `null` if there is no active window. The active window is the window that was
+     * focused most recently.
+     */
+    active: Window | null
+
+    /**
+     * Display a prompt and request text input from the user.
+     *
+     * @todo TODO!(sqs): always shows on the active window if any; how to pass this as a param?
+     *
+     * @param message The message to show.
+     * @param defaultValue The default value for the user input, or undefined for no default.
+     * @returns The user's input, or null if the user (or the client) canceled the input request.
+     */
+    showInputBox(message: string, defaultValue?: string): Promise<string | null>
+}
+
+/**
+ * The application window where the client is running.
+ */
+export interface Window {
+    /**
+     * Whether this window is the active window in the application. At most 1 window can be active.
+     */
+    readonly isActive: boolean
+
+    /**
+     * The active user interface component (such as a text editor) in this window, or null if there is no active
+     * component.
+     */
+    readonly activeComponent: Component | null
+}
+
+/**
+ * A user interface component in an application window (such as a text editor).
+ */
+export interface Component {
+    /**
+     * Whether this component is the active component in the application. At most 1 component can be active.
+     */
+    readonly isActive: boolean
+
+    /**
+     * The URI of the resource (such as a file) that this component is displaying, or null if there is none.
+     */
+    resource: URI | null
+}
+
+/**
+ * Command registration and execution.
+ */
+export interface Commands {
+    /**
+     * Registers a command with the given identifier. The command can be invoked by this extension's contributions
+     * (e.g., a contributed action that adds a toolbar item to invoke this command).
+     *
+     * @param command The unique identifier for the command.
+     * @param run The function to invoke for this command.
+     * @return A subscription that unregisters this command upon unsubscription.
+     */
+    register(command: string, run: (...args: any[]) => any): Subscription
+}
+
+/**
+ * Arbitrary key-value pairs that describe application state in a namespace shared by the client and all other
+ * extensions used by the client.
+ */
+export interface ExtensionContext {
+    /**
+     * Applies the given updates to the client's context, overwriting any existing values for the same key and
+     * deleting any keys whose value is `null`.
+     *
+     * @param updates New values for context keys (or deletions for keys if the value is `null`).
+     */
+    updateContext(updates: Context): void
+}

src/extension/server.test.ts src/extension/extension.test.ts

@@ -1,15 +1,13 @@
 import * as assert from 'assert'
 import { createConnection as createClientConnection } from '../client/connection'
-import { InitializeParams, InitializeRequest, InitializeResult } from '../protocol'
+import { InitializedNotification, InitializeParams, InitializeRequest, InitializeResult } from '../protocol'
 import { createMessageTransports } from '../test/integration/helpers'
-import { createConnection as createServerConnection } from './server'
+import { activateExtension } from './extension'
 
-describe('Connection', () => {
+describe('activateExtension', () => {
     it('initialize request parameters and result', async () => {
         const [clientTransports, serverTransports] = createMessageTransports()
-        const serverConnection = createServerConnection(serverTransports)
         const clientConnection = createClientConnection(clientTransports)
-        serverConnection.listen()
         clientConnection.listen()
 
         const initParams: InitializeParams = {
@@ -19,14 +17,19 @@ describe('Connection', () => {
             workspaceFolders: null,
         }
         const initResult: InitializeResult = {
-            capabilities: { contributions: { actions: [{ id: 'c', command: 'c' }] } },
+            capabilities: {
+                decorationProvider: true,
+                textDocumentSync: { openClose: true },
+            },
         }
 
-        serverConnection.onRequest(InitializeRequest.type, params => {
-            assert.deepStrictEqual(params, initParams)
-            return initResult
-        })
-        const result = await clientConnection.sendRequest(InitializeRequest.type, initParams)
+        const [, result] = await Promise.all([
+            activateExtension<{}>(serverTransports, () => void 0),
+            clientConnection.sendRequest(InitializeRequest.type, initParams).then(result => {
+                clientConnection.sendNotification(InitializedNotification.type, initParams)
+                return result
+            }),
+        ])
         assert.deepStrictEqual(result, initResult)
     })
 })

src/extension/extension.ts

@@ -0,0 +1,93 @@
+import { Subscription } from 'rxjs'
+import { createMessageConnection, Logger, MessageConnection, MessageTransports } from '../jsonrpc2/connection'
+import {
+    ConfigurationCascade,
+    InitializedNotification,
+    InitializeParams,
+    InitializeRequest,
+    InitializeResult,
+} from '../protocol'
+import { URI } from '../types/textDocument'
+import { Commands, Configuration, CXP, ExtensionContext, Observable, Window, Windows } from './api'
+import { createExtCommands } from './features/commands'
+import { createExtConfiguration } from './features/configuration'
+import { createExtContext } from './features/context'
+import { createExtWindows } from './features/windows'
+
+class ExtensionHandle<C> implements CXP<C> {
+    public readonly configuration: Configuration<C> & Observable<C>
+    public readonly windows: Windows & Observable<Window[]>
+    public readonly commands: Commands
+    public readonly context: ExtensionContext
+
+    private subscription = new Subscription()
+
+    constructor(public readonly rawConnection: MessageConnection, public readonly initializeParams: InitializeParams) {
+        this.subscription.add(this.rawConnection)
+
+        this.configuration = createExtConfiguration<C>(
+            this,
+            initializeParams.configurationCascade as ConfigurationCascade<C>
+        )
+        this.windows = createExtWindows(this)
+        this.commands = createExtCommands(this)
+        this.context = createExtContext(this)
+    }
+
+    public get root(): URI | null {
+        return this.initializeParams.root
+    }
+
+    public close(): void {
+        this.subscription.unsubscribe()
+    }
+}
+
+const consoleLogger: Logger = {
+    error(message: string): void {
+        console.error(message)
+    },
+    warn(message: string): void {
+        console.warn(message)
+    },
+    info(message: string): void {
+        console.info(message)
+    },
+    log(message: string): void {
+        console.log(message)
+    },
+}
+
+/**
+ * Activates a CXP extension by calling its `run` entrypoint function with the CXP API handle as the first
+ * argument.
+ *
+ * @template C the extension's settings
+ * @param transports The message reader and writer to use for communication with the client.
+ * @param run The extension's `run` entrypoint function.
+ * @return A promise that resolves when the extension's `run` function has been called.
+ */
+export function activateExtension<C>(
+    transports: MessageTransports,
+    run: (cxp: CXP<C>) => void | Promise<void>
+): Promise<void> {
+    const connection = createMessageConnection(transports, consoleLogger)
+    return new Promise<void>(resolve => {
+        let initializationParams!: InitializeParams
+        connection.onRequest(InitializeRequest.type, params => {
+            initializationParams = params
+            return {
+                capabilities: {
+                    textDocumentSync: { openClose: true },
+                    decorationProvider: true,
+                },
+            } as InitializeResult
+        })
+        connection.onNotification(InitializedNotification.type, () => {
+            run(new ExtensionHandle<C>(connection, initializationParams))
+            resolve()
+        })
+
+        connection.listen()
+    })
+}