Refactor project structure

README.md

@@ -4,17 +4,18 @@ Language Server Runtimes is a JSON-RPC based protocol for interactions between s
 
 Language Server Runtimes supports a number of host environments that each have their own underlying transport mechanisms and environment considerations, which must also support JSON-RPC communication. To see the differences between host environments, see [Runtime Host Environments](README.md#runtime-host-environments).
 
-### Terminology
+## Terminology
 
 The server runtime will provide “Features” which refers to the Language Server Runtimes core feature (eg. LSP, Logging, etc). These features will be injected on top of the Server business logic implementation at build time. [Capabilities](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#capabilities) are a set of language features provided by an LSP.
 
-### Server initialization flow and features negotiation
-
-Language Server Runtimes uses LSP abstracts to create a JSON-RPC connection between client and server. We use the `Initialize` LSP lifecycle method to provide initialization options to the server.
+## Project structure
+The project source code is split into next directories:
 
-Features will be instantiated and configured during execution of the `Initialize` flow of the main connection.
-
-Client will send the `Initialize` LSP request with custom options to configure features in the optional [`InitializeParams.initializationOptions`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#initializeParams) property. The configuration passed here will influence implementation details of different capabilities defined below. `initializationOptions` can be processed by the runtime and used to initialize features according to their implementation details. For information on which options are used, please see Initilization sections in each feature.
+- `/src`: This directory contains all the source code of the project.
+  - `/protocol`: JSON-RPC-based Runtime protocol implementation in Typescript, which defines the communication between Runtime and Runtime Clients (e.g. AWS Toolkit extension).
+  - `/runtimes`: implementation of several runtimes (standalone, webworker) and features, that are exposed to Runtime Servers developed by Server implementors.
+  - `/server-interface`: defines interfaces of features, that Runtime provides to Runtime Servers implementors.
+  - `/testing`: testing helper for Server implementors.
 
 ## Features
 
@@ -137,6 +138,14 @@ TBD
 
 Servers typically run as processes or web workers. Details are provided below on how to initialize each type of server runtime.
 
+### Server initialization flow and features negotiation
+
+Language Server Runtimes uses LSP abstracts to create a JSON-RPC connection between client and server. We use the `Initialize` LSP lifecycle method to provide initialization options to the server.
+
+Features will be instantiated and configured during execution of the `Initialize` flow of the main connection.
+
+Client will send the `Initialize` LSP request with custom options to configure features in the optional [`InitializeParams.initializationOptions`](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#initializeParams) property. The configuration passed here will influence implementation details of different capabilities defined below. `initializationOptions` can be processed by the runtime and used to initialize features according to their implementation details. For information on which options are used, please see Initilization sections in each feature.
+
 ### Standalone Server
 
 Features and modes can be communicated to the server at startup through command line arguments. Implementation detail of the Standalone Server is that it can be started with a special `--set-credentials-encryption-key` argument to enter special flow for accepting encryption options as an argument before starting the main LSP connection.

package.json

@@ -2,7 +2,13 @@
     "name": "@aws/language-server-runtimes",
     "version": "0.1.1",
     "description": "Runtimes to host Language Servers for AWS",
-    "main": "out/runtimes/index.js",
+    "files": [
+        "out",
+        "protocol",
+        "runtimes",
+        "server-interface",
+        "testing"
+    ],
     "repository": {
         "type": "git",
         "url": "https://github.com/aws/language-server-runtimes"
@@ -25,7 +31,9 @@
         "jose": "^5.2.3",
         "rxjs": "^7.8.1",
         "vscode-languageserver": "^9.0.1",
-        "vscode-languageserver-textdocument": "^1.0.11"
+        "vscode-languageserver-protocol": "^3.17.5",
+        "vscode-languageserver-textdocument": "^1.0.11",
+        "vscode-languageserver-types": "^3.17.5"
     },
     "devDependencies": {
         "@types/mocha": "^10.0.1",

protocol/package.json

@@ -0,0 +1,6 @@
+{
+    "name": "@amzn/language-server-runtimes-impl",
+    "private": true,
+    "description": "Helper file to flatten import paths in dependant packages",
+    "main": "../out/runtimes/index.js"
+}

runtimes/package.json

@@ -0,0 +1,6 @@
+{
+    "name": "@amzn/language-server-runtimes-protocol",
+    "private": true,
+    "description": "Helper file to flatten import paths in dependant packages",
+    "main": "../out/protocol/index.js"
+}

server-interface/package.json

@@ -0,0 +1,6 @@
+{
+    "name": "@amzn/language-server-runtimes-server-interface",
+    "private": true,
+    "description": "Helper file to flatten import paths in dependant packages",
+    "main": "../out/server-interface/index.js"
+}

src/protocol/README.md

@@ -0,0 +1,6 @@
+## AWS Language Servers Runtimes Protocol
+
+Implementation of AWS Language Servers Runtimes Protocol, which defines a protocol for communication between Servers and Clients.
+It is modelled after LSP, and provides several custom extensions to enable custom AWS Language Server Runtimes features.
+
+Protocol specification can be found in main [README](https://github.com/aws/language-server-runtimes/blob/main/README.md).

src/protocol/auth.ts

@@ -0,0 +1,49 @@
+import { ProtocolRequestType, ProtocolNotificationType0, ProtocolRequestType0 } from './lsp'
+
+export type IamCredentials = {
+    readonly accessKeyId: string
+    readonly secretAccessKey: string
+    readonly sessionToken?: string
+}
+
+export type BearerCredentials = {
+    readonly token: string
+}
+
+export interface SsoProfileData {
+    startUrl?: string
+}
+
+export interface ConnectionMetadata {
+    sso?: SsoProfileData
+}
+
+export interface UpdateCredentialsParams {
+    // Plaintext Credentials (for browser based environments) or encrypted JWT token
+    data: IamCredentials | BearerCredentials | string
+    // If the payload is encrypted
+    // Defaults to false if undefined or null
+    encrypted?: boolean
+}
+
+export const iamCredentialsUpdateRequestType = new ProtocolRequestType<UpdateCredentialsParams, null, void, void, void>(
+    'aws/credentials/iam/update'
+)
+
+export const iamCredentialsDeleteNotificationType = new ProtocolNotificationType0<void>('aws/credentials/iam/delete')
+
+export const bearerCredentialsUpdateRequestType = new ProtocolRequestType<
+    UpdateCredentialsParams,
+    null,
+    void,
+    void,
+    void
+>('aws/credentials/token/update')
+
+export const bearerCredentialsDeleteNotificationType = new ProtocolNotificationType0<void>(
+    'aws/credentials/token/delete'
+)
+
+export const getConnectionMetadataRequestType = new ProtocolRequestType0<ConnectionMetadata, never, void, void>(
+    'aws/credentials/getConnectionMetadata'
+)

src/protocol/index.ts

@@ -0,0 +1,2 @@
+export * from './lsp'
+export * from './auth'

src/features/lsp/inline-completions/protocolExtensions.ts → src/protocol/inlineCompletionWithReferences.ts

@@ -4,7 +4,7 @@ import {
     InlineCompletionRegistrationOptions,
     ProtocolNotificationType,
     ProtocolRequestType,
-} from 'vscode-languageserver'
+} from './lsp'
 
 export type InlineCompletionWithReferencesParams = InlineCompletionParams & {
     // No added parameters

src/features/lsp/inline-completions/futureProtocol.ts → src/protocol/inlineCompletions.ts

@@ -2,9 +2,9 @@ import {
     InlineCompletionItem,
     InlineCompletionList,
     InlineCompletionParams,
-    InlineCompletionRegistrationOptions,
     ProtocolRequestType,
-} from 'vscode-languageserver'
+    InlineCompletionRegistrationOptions,
+} from './lsp'
 
 /**
  * inlineCompletionRequestType defines the custom method that the language client

src/protocol/lsp.ts

@@ -0,0 +1,12 @@
+export { TextDocument, Position } from 'vscode-languageserver-textdocument'
+
+// LSP protocol is a core dependency for LSP feature provided by runtimes.
+// Since we aim to provide whole range of LSP specification for Clients and Capabilities,
+// we re-exporting whole LSP protocol for usage.
+// Scoping it down is not practical due to large surface of protocol and types relationship.
+// It will be limiting implementors, if they choose to type their code with more specific types from LSP.
+export * from 'vscode-languageserver-protocol'
+
+// Custom Runtimes LSP extensions
+export * from './inlineCompletions'
+export * from './inlineCompletionWithReferences'

src/runtimes/README.md

@@ -0,0 +1,15 @@
+## AWS Language Server Runtimes Implementation
+
+Implementation of AWS Language Server runtimes and Runtimes features.
+
+Each runtime implements a LSP server and opens communication channel with client over LSP connection. Runtime initialised all registered Capabilities.
+
+Runtime sets up message passing, that translates Runtimes Protocol messages to a function calls to Capabilities features, defined in Server and server features interfaces.
+
+Runtime implementation acts as a intermediate layer between Runtime Client and a Runtime Servers, injected into runtime at build time.
+The runtime implements message passing between Client application and injected Servers, and interface with both by predefined APIs:
+* **Runtime Protocol**: a protocol to define communication between Runtime and Client application (e.g. Runtime<->AWS Toolkit extension). It uses LSP (and JSON-RPC) connection as a transport.
+* **Runtime Server Interface**: defines an interface of the Server and features exposed to Runtime Server developers (e.g. Runtime<->AWS CodeWhisperer server).
+
+
+See main project [README](https://github.com/aws/language-server-runtimes/blob/main/README.md) for more detailed explanation of the architecture.