feat: new extension API that only requires extensions to export 1 func

This makes it so that extension JS bundles are expected to merely export a single activate function. They are no longer bundled with the sourcegraph module, and they no longer know how to speak the RPC extension protocol themselves. The "extension host" knows how to invoke their activate function and inject the sourcegraph module (when it is imported).

The goal is to make it easier to write extensions. You just need to write them against a TypeScript API. Your extension itself is not responsible anymore for executing itself, communicating with the client, or knowing anything about its JavaScript execution environment.

For example, the following is now a valid extension:

```
import * as sourcegraph from 'sourcegraph'

export function activate(): void {
    sourcegraph.registerHoverProvider(['*'], {
        provideHover: () => ({
            contents: { value: ' Hello from an extension!' },
        }),
    })
}
```

When bundled, it will contain ONLY that `activate` function; the `sourcegraph` module is dynamically linked at runtime. This means the extension bundle is significantly smaller, and the extension author only needs to care about adhering to the TypeScript API (not about also bundling their extension with the latest version of the `sourcegraph` package for wire protocol compatibility).

Author: sqs

package.json

@@ -11,9 +11,9 @@
   "bugs": {
     "url": "https://github.com/sourcegraph/sourcegraph-extension-api/issues"
   },
-  "main": "module/index.js",
-  "module": "module/index.js",
-  "types": "module/index.d.ts",
+  "main": "lib/extension/index.js",
+  "module": "lib/extension/index.js",
+  "types": "lib/sourcegraph.d.ts",
   "files": [
     "lib",
     "module"
@@ -33,6 +33,7 @@
     "watch:typecheck": "tsc -p tsconfig.json -w",
     "watch:build:assets": "npm run build:assets && nodemon --watch src/protocol/contribution.ts --exec 'npm run build:assets || exit 1'",
     "watch:build:module": "tsc -p tsconfig.dist.json -w",
+    "watch:build:api": "nodemon --watch src/sourcegraph.d.ts --watch src/extension/index.js --ext ts,js --exec 'npm run build:api'",
     "watch:build": "concurrently --kill-others 'npm:watch:build:*'",
     "watch:test": "npm run test -- -w",
     "watch:cover": "nodemon --watch src/ --ext ts,js,json --watch package.json --exec 'npm run cover || exit 1'"

src/client/client.ts

@@ -1,4 +1,5 @@
 import { BehaviorSubject, Observable, Unsubscribable } from 'rxjs'
+import { DocumentSelector } from 'sourcegraph'
 import { MessageTransports } from '../jsonrpc2/connection'
 import {
     GenericNotificationHandler,
@@ -18,7 +19,6 @@ import {
     UnregistrationParams,
     UnregistrationRequest,
 } from '../protocol'
-import { DocumentSelector } from '../types/document'
 import { isFunction, tryCatchPromise } from '../util'
 import { Connection, createConnection } from './connection'
 import { CloseAction, DefaultErrorHandler, ErrorAction, ErrorHandler } from './errorHandler'
@@ -213,6 +213,8 @@ export class Client implements Unsubscribable {
                 connection.onRequest(RegistrationRequest.type, params => this.handleRegistrationRequest(params))
                 connection.onRequest(UnregistrationRequest.type, params => this.handleUnregistrationRequest(params))
 
+                connection.onRequest('ping', () => 'pong')
+
                 // Initialize static features.
                 for (const feature of this.features) {
                     if (!DynamicFeature.is(feature)) {

src/client/features/hover.test.ts

@@ -1,7 +1,7 @@
 import * as assert from 'assert'
+import { MarkupKind } from 'sourcegraph'
 import { TextDocumentHoverProviderRegistry } from '../../environment/providers/hover'
 import { ClientCapabilities } from '../../protocol'
-import { MarkupKind } from '../../types/markup'
 import { Client } from '../client'
 import { TextDocumentHoverFeature } from './hover'
 

src/client/features/hover.ts

@@ -1,4 +1,5 @@
 import { from, Observable, Unsubscribable } from 'rxjs'
+import { MarkupKind } from 'sourcegraph'
 import { ProvideTextDocumentHoverSignature } from '../../environment/providers/hover'
 import { FeatureProviderRegistry } from '../../environment/providers/registry'
 import {
@@ -7,8 +8,7 @@ import {
     TextDocumentPositionParams,
     TextDocumentRegistrationOptions,
 } from '../../protocol'
-import { Hover } from '../../types/hover'
-import { MarkupKind } from '../../types/markup'
+import { Hover } from '../../protocol/plainTypes'
 import { Client } from '../client'
 import { ensure, Feature } from './common'
 

src/client/features/location.ts

@@ -11,7 +11,7 @@ import {
     TextDocumentRegistrationOptions,
     TypeDefinitionRequest,
 } from '../../protocol'
-import { Location } from '../../types/location'
+import { Location } from '../../protocol/plainTypes'
 import { Client } from '../client'
 import { ensure, Feature } from './common'
 

src/client/features/textDocument.test.ts

@@ -1,5 +1,6 @@
 import * as assert from 'assert'
 import { BehaviorSubject, Subject } from 'rxjs'
+import { DocumentSelector } from 'sourcegraph'
 import { createObservableEnvironment, EMPTY_ENVIRONMENT, Environment } from '../../environment/environment'
 import { NotificationType } from '../../jsonrpc2/messages'
 import {
@@ -10,7 +11,6 @@ import {
     DidOpenTextDocumentParams,
     TextDocumentRegistrationOptions,
 } from '../../protocol'
-import { DocumentSelector } from '../../types/document'
 import { TextDocumentItem } from '../../types/textDocument'
 import { Client } from '../client'
 import {

src/client/features/textDocument.ts

@@ -1,5 +1,6 @@
 import { Observable, Subscription } from 'rxjs'
 import { bufferCount, filter, map } from 'rxjs/operators'
+import { DocumentSelector, TextDocument } from 'sourcegraph'
 import { MessageType as RPCMessageType, NotificationType } from '../../jsonrpc2/messages'
 import {
     ClientCapabilities,
@@ -9,8 +10,7 @@ import {
     DidOpenTextDocumentParams,
     TextDocumentRegistrationOptions,
 } from '../../protocol'
-import { DocumentSelector } from '../../types/document'
-import { match, TextDocument, TextDocumentItem } from '../../types/textDocument'
+import { match, TextDocumentItem } from '../../types/textDocument'
 import { Client } from '../client'
 import { DynamicFeature, ensure, RegistrationData } from './common'
 

src/environment/environment.ts

@@ -1,9 +1,9 @@
 import { Observable, of } from 'rxjs'
 import { distinctUntilChanged, map } from 'rxjs/operators'
+import { TextDocument } from 'sourcegraph'
 import { ConfigurationCascade } from '../protocol'
-import { Range } from '../types/range'
-import { Selection } from '../types/selection'
-import { TextDocument, TextDocumentItem } from '../types/textDocument'
+import { Range, Selection } from '../protocol/plainTypes'
+import { TextDocumentItem } from '../types/textDocument'
 import { isEqual } from '../util'
 import { Context, EMPTY_CONTEXT } from './context/context'
 import { Extension } from './extension'

src/environment/providers/hover.test.ts

@@ -1,8 +1,8 @@
 import * as assert from 'assert'
 import { of } from 'rxjs'
 import { TestScheduler } from 'rxjs/testing'
-import { Hover, HoverMerged } from '../../types/hover'
-import { MarkupKind } from '../../types/markup'
+import { Hover, MarkupKind } from 'sourcegraph'
+import { HoverMerged } from '../../types/hover'
 import { getHover, ProvideTextDocumentHoverSignature } from './hover'
 import { FIXTURE } from './registry.test'
 

src/environment/providers/hover.ts

@@ -1,7 +1,8 @@
 import { combineLatest, from, Observable } from 'rxjs'
 import { map, switchMap } from 'rxjs/operators'
 import { TextDocumentPositionParams, TextDocumentRegistrationOptions } from '../../protocol'
-import { Hover, HoverMerged } from '../../types/hover'
+import { Hover } from '../../protocol/plainTypes'
+import { HoverMerged } from '../../types/hover'
 import { FeatureProviderRegistry } from './registry'
 
 export type ProvideTextDocumentHoverSignature = (params: TextDocumentPositionParams) => Observable<Hover | null>

src/environment/providers/location.test.ts

@@ -1,7 +1,7 @@
 import * as assert from 'assert'
 import { of } from 'rxjs'
 import { TestScheduler } from 'rxjs/testing'
-import { Location } from '../../types/location'
+import { Location } from '../../protocol/plainTypes'
 import {
     getLocation,
     getLocations,

src/environment/providers/location.ts

@@ -1,8 +1,8 @@
 import { combineLatest, from, Observable } from 'rxjs'
 import { map, switchMap } from 'rxjs/operators'
 import { ReferenceParams, TextDocumentPositionParams, TextDocumentRegistrationOptions } from '../../protocol'
+import { Location } from '../../protocol/plainTypes'
 import { compact, flatten } from '../../util'
-import { Location } from '../../types/location'
 import { FeatureProviderRegistry } from './registry'
 import { flattenAndCompact } from './util'
 

src/extension/api/provider.ts

@@ -0,0 +1,67 @@
+import { Unsubscribable } from 'sourcegraph'
+import * as sourcegraph from 'sourcegraph'
+import uuidv4 from 'uuid/v4'
+import { MessageConnection } from '../../jsonrpc2/connection'
+import { MessageType as RPCMessageType } from '../../jsonrpc2/messages'
+import {
+    HoverRequest,
+    RegistrationParams,
+    RegistrationRequest,
+    TextDocumentPositionParams,
+    TextDocumentRegistrationOptions,
+    UnregistrationParams,
+    UnregistrationRequest,
+} from '../../protocol'
+import { Position } from '../../types/position'
+
+/**
+ * All `registerXyzProvider` functions in the Sourcegraph extension API.
+ */
+interface RegisterProviderFunctions extends Pick<typeof sourcegraph, 'registerHoverProvider'> {}
+
+/**
+ * Create all `registerXyzProvider` functions in the Sourcegraph extension API.
+ */
+export function createRegisterProviderFunctions(connection: MessageConnection): RegisterProviderFunctions {
+    return {
+        registerHoverProvider: (selector, provider) => {
+            connection.onRequest(HoverRequest.type, (params: TextDocumentPositionParams) =>
+                provider.provideHover(
+                    params.textDocument as sourcegraph.TextDocument,
+                    new Position(params.position.character, params.position.character)
+                )
+            )
+            return registerProvider<TextDocumentRegistrationOptions>(connection, HoverRequest.type, {
+                documentSelector: selector,
+                extensionID: '', // TODO(sqs): use provider ID
+            })
+        },
+    }
+}
+
+/**
+ * Registers a provider implemented by the extension with the client.
+ *
+ * @return An {@link Unsubscribable} that unregisters the provider.
+ */
+function registerProvider<RO>(
+    connection: MessageConnection,
+    type: RPCMessageType,
+    registerOptions: RO
+): Unsubscribable {
+    const id = uuidv4()
+    // TODO(sqs): handle errors in sendRequest calls
+    connection
+        .sendRequest(RegistrationRequest.type, {
+            registrations: [{ id, method: type.method, registerOptions }],
+        } as RegistrationParams)
+        .catch(err => console.error(err))
+    return {
+        unsubscribe: () =>
+            connection
+                .sendRequest(UnregistrationRequest.type, {
+                    unregisterations: [{ id, method: type.method }],
+                } as UnregistrationParams)
+                .catch(err => console.error(err)),
+    }
+}

src/extension/extensionHost.integration.test.ts

@@ -0,0 +1,115 @@
+import * as assert from 'assert'
+import { from } from 'rxjs'
+import { filter, map, switchMap, take } from 'rxjs/operators'
+import { MarkupKind } from 'sourcegraph'
+import * as sourcegraph from 'sourcegraph'
+import { Controller } from '../environment/controller'
+import { Environment } from '../environment/environment'
+import { clientStateIsActive } from '../test/helpers'
+import { createMessageTransports } from '../test/integration/helpers'
+import { HoverMerged } from '../types/hover'
+import { createExtensionHost } from './extensionHost'
+
+const FIXTURE_ENVIRONMENT: Environment<any, any> = {
+    component: {
+        document: { uri: 'file:///f', languageId: 'l', version: 1, text: '' },
+        selections: [],
+        visibleRanges: [],
+    },
+    extensions: [{ id: 'x' }],
+    configuration: {},
+    context: {},
+}
+
+describe('Extension host (integration)', () => {
+    interface TestContext {
+        clientController: Controller<any, any>
+        extensionHost: typeof sourcegraph
+    }
+
+    const clientIsActive = (clientController: Controller<any, any>): Promise<void> =>
+        clientController.clientEntries
+            .pipe(
+                filter(entries => entries.length > 0),
+                map(entries => entries[0]),
+                switchMap(entry => from(clientStateIsActive(entry.client))),
+                take(1)
+            )
+            .toPromise()
+
+    const ready = async ({ clientController, extensionHost }: TestContext): Promise<void> => {
+        await extensionHost.internal.sync()
+        await clientIsActive(clientController)
+    }
+
+    const create = async (): Promise<TestContext & { ready: Promise<void> }> => {
+        const [clientTransports, serverTransports] = createMessageTransports()
+
+        const clientController = new Controller({
+            clientOptions: () => ({ createMessageTransports: () => clientTransports }),
+        })
+        clientController.setEnvironment(FIXTURE_ENVIRONMENT)
+
+        const extensionHost = await createExtensionHost(serverTransports)
+        return { clientController, extensionHost, ready: ready({ clientController, extensionHost }) }
+    }
+
+    it('registers and unregisters a provider', async () => {
+        const { clientController, extensionHost, ready } = await create()
+
+        // Register the hover provider and call it.
+        const unsubscribe = extensionHost.registerHoverProvider(['*'], {
+            provideHover: () => ({ contents: { value: 'a', kind: MarkupKind.PlainText } }),
+        })
+        await ready
+        assert.deepStrictEqual(
+            await clientController.registries.textDocumentHover
+                .getHover({
+                    textDocument: { uri: 'file:///f' },
+                    position: { line: 1, character: 2 },
+                })
+                .pipe(take(1))
+                .toPromise(),
+            {
+                contents: [{ value: 'a', kind: MarkupKind.PlainText }],
+            } as HoverMerged
+        )
+
+        // Unregister the hover provider and ensure it's removed.
+        unsubscribe.unsubscribe()
+        await ready
+        assert.deepStrictEqual(
+            await clientController.registries.textDocumentHover
+                .getHover({
+                    textDocument: { uri: 'file:///f' },
+                    position: { line: 1, character: 2 },
+                })
+                .pipe(take(1))
+                .toPromise(),
+            null
+        )
+    })
+
+    it.skip('supports multiple hover providers', async () => {
+        const { clientController, extensionHost, ready } = await create()
+
+        extensionHost.registerHoverProvider(['*'], {
+            provideHover: () => ({ contents: { value: 'a', kind: MarkupKind.PlainText } }),
+        })
+        extensionHost.registerHoverProvider(['*'], {
+            provideHover: () => ({ contents: { value: 'b', kind: MarkupKind.PlainText } }),
+        })
+        await ready
+
+        const hover = await clientController.registries.textDocumentHover
+            .getHover({
+                textDocument: { uri: 'file:///f' },
+                position: { line: 1, character: 2 },
+            })
+            .pipe(take(1))
+            .toPromise()
+        assert.deepStrictEqual(hover, {
+            contents: [{ value: 'a', kind: MarkupKind.PlainText }, { value: 'b', kind: MarkupKind.PlainText }],
+        } as HoverMerged)
+    })
+})

src/extension/extensionHost.test.ts

@@ -0,0 +1,39 @@
+import * as assert from 'assert'
+import * as sourcegraph from 'sourcegraph'
+import { createConnection as createClientConnection } from '../client/connection'
+import {
+    InitializedNotification,
+    InitializeParams,
+    InitializeRequest,
+    InitializeResult,
+    RegistrationRequest,
+} from '../protocol'
+import { createMessageTransports } from '../test/integration/helpers'
+import { createExtensionHost } from './extensionHost'
+
+describe('createExtensionHost', () => {
+    it('initialize request parameters and result', async () => {
+        const [clientTransports, serverTransports] = createMessageTransports()
+        const clientConnection = createClientConnection(clientTransports)
+        clientConnection.listen()
+
+        const initParams: InitializeParams = {
+            capabilities: { decoration: true, experimental: { a: 1 } },
+            configurationCascade: { merged: {} },
+        }
+        const initResult: InitializeResult = {}
+
+        clientConnection.onRequest(RegistrationRequest.type, () => void 0)
+
+        const [, result] = await Promise.all([
+            createExtensionHost(serverTransports).then((extensionHost: typeof sourcegraph) => {
+                assert.ok(extensionHost)
+            }),
+            clientConnection.sendRequest(InitializeRequest.type, initParams).then(result => {
+                clientConnection.sendNotification(InitializedNotification.type, initParams)
+                return result
+            }),
+        ])
+        assert.deepStrictEqual(result, initResult)
+    })
+})