@aws/language-server-runtimes

Language Server Runtimes

Language Server Runtimes is a JSON-RPC based protocol for interactions between servers and clients (typically embedded in development tools). The JSON-RPC protocol follows the version utilized in the LSP Specification - 3.17, for compatibility. A subset of LSP version 3.17 is supported (see LSP) plus an additional set of request and response types (see Features).

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.

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 are a set of language features provided by an LSP.

Project structure

The project source code is split into next directories:

• /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

LSP

The server runtime implementation acts as a proxy for LSP methods, which means it supports all LSP methods. In addition to that, it can extend the LSP method to support custom capabilities.

Feature Specification

Method	Support	Notes
onInlineCompletion	Yes	Provide list of inline completion suggestions from the Server
onExecuteCommand	Yes	Executes a custom command provided by the Server. Servers are advised to document custom commands they support in the package README.

LSP Extensions

Method Name	Method	Params	Method Type	Response Type	Notes
getConfigurationFromServer	aws/getConfigurationFromServer	GetConfigurationFromServerParams	Request	LSPAny	Retrieves configuration from the server for a specified section
onInlineCompletionWithReferences	aws/textDocument/inlineCompletionWithReferences	InlineCompletionWithReferencesParams	Request	InlineCompletionListWithReferences	Provides list of inline completion suggestions from the Server with references for each of its suggestion
onLogInlineCompletionSessionResults	aws/logInlineCompletionSessionResults	LogInlineCompletionSessionResultsParams	Notification	n/a	Logs the results from inline completion suggestions from the Server

Auth

The runtime supports two types of credentials: IAM credentials and Bearer tokens (e.g. Builder ID). These credentials should be available to destinations in plaintext.

// IAM Credentials data
export interface IamCredentials {
    accessKeyId: string
    secretAccessKey: string
    sessionToken?: string
}

// Bearer Token data
export interface BearerCredentials {
    token: string
}

Destinations are responsible for managing credentials state, refreshing and updating them on the runtime when their state changes.

Initialization

The runtimes by default support authentication with both types of credentials, without the need of a prior agreement or handshake with the client. If the client supports a specific type of credentials, the corresponding LSP update method can be called directly. For cases when passing plaintext credentials is not suitable (e.g. standalone runtimes), they can be encrypted before being sent to the server (see Encryption).

Feature Specification

The following table outlines custom LSP methods are supported by servers for authentication:

Description	Method	Params	Method type	Response Type
Send IAM Credentials	aws/credentials/iam/update	UpdateCredentialsPayload	Request	ResponseMessage
Send Bearer token	aws/credentials/token/update	UpdateCredentialsPayload	Request	ResponseMessage
Delete IAM credentials	aws/credentials/iam/delete	n/a	Notification	n/a
Delete bearer token	aws/credentials/token/delete	n/a	Notification	n/a

export type Credentials = IamCredentials | BearerCredentials

// Credentials provided to the server by the server's host
export interface UpdateCredentialsPayload {
    // Plaintext IamCredentials/BearerCredentials or JSON blob of encrypted credentials
    data: string | Credentials
    // If the payload is encrypted
    // Defaults to false if undefined or null
    encrypted?: boolean
}

Get Connection Metadata

Server Auth feature supports storing extra Auth connection data in the server. Get connection metadata is request that server sends to client in order to obtain new connection information. Server expects client to provide metadata specified in ConnectionMetadata interface.

Description	Method	Params	Method type	Response Type
Get Connection Metadata	aws/credentials/getConnectionMetadata	n/a	Request	ConnectionMetadata

export interface ConnectionMetadata {
    sso?: SsoProfileData
}

export interface SsoProfileData {
    startUrl?: string
}

Telemetry

Initialization

The runtimes by default supports the telemetry feature, allowing servers to send metrics to destinations. Additional option to disable this feature during initialization as well as during an ongoing session is currently in plan.

Feature Specification

The telemetry notification is sent from the server to the client to ask the client to log a telemetry event. AWS Runtimes using Telemetry feature will send metric events with default LSP telemetry notification with specified payload interface. Telemetry notifications are specified as follow:

Description	Method	Params	Method type	Response Type
Send telemetry event	telemetry/event	MetricEvent	Notification	n/a

export type MetricEvent = {
    name: string
    data?: any
    result?: ResultType
    errorData?: ErrorData
}

Logging

Design TBD

Initialization

TBD

Feature Specification

TBD

Chat

The runtime defines Chat interface that allow runtime server implementors to define handlers for chat events to enable conversational experiences. Chat data types are mostly modeled after mynah-ui, an event driven UI library designed for chat experiences. mynah-ui is the suggested UI library to be used on the destination. However the Chat interface is generic enough to be compatible with other UI approaches

Initialization

The runtime supports chat by default

Feature Specification

Description	Method	Params	Method type	Response Type
Send chat prompt	aws/chat/sendChatPrompt	ChatParams	Request	ChatResult
End conversation	aws/chat/endChat	EndChatParams	Request	EndChatResult
Send chat quick action	aws/chat/sendChatQuickAction	QuickActionParams	Request	ChatResult
Send chat UI ready event	aws/chat/ready	n/a	Notification	n/a
Send chat vote event	aws/chat/vote	VoteParams	Notification	n/a
Send chat feedback event	aws/chat/feedback	FeedbackParams	Notification	n/a
Send tab add event	aws/chat/tabAdd	TabAddParams	Notification	n/a
Send active tab change event	aws/chat/tabChange	TabChangeParams	Notification	n/a
Send tab remove event	aws/chat/tabRemove	TabRemoveParams	Notification	n/a
Send insert to cursor position event	aws/chat/insertToCursorPosition	InsertToCursorPositionParams	Notification	n/a
Send copy code to clipboard event	aws/chat/copyCodeToClipboard	CopyCodeToClipboardParams	Notification	n/a
Send link click event	aws/chat/linkClick	LinkClickParams	Notification	n/a
Send info link click event	aws/chat/infoLinkClick	InfoLinkClickParams	Notification	n/a
Send source link click event	aws/chat/sourceLinkClick	SourceLinkClickParams	Notification	n/a
Send followup chat item click event	aws/chat/followUpClick	FollowUpClickParams	Notification	n/a

export interface ChatPrompt {
    prompt?: string
    escapedPrompt?: string
    command?: string
}

export interface ChatParams {
    tabId: string
    prompt: ChatPrompt
    partialResultToken?: ProgressToken
}

export interface ChatResult {
    body?: string
    messageId?: string
    canBeVoted?: boolean // requires messageId to be filled to show vote thumbs
    relatedContent?: {
        title?: string
        content: SourceLink[]
    }
    followUp?: {
        text?: string
        options?: ChatItemAction[]
    }
    codeReference?: ReferenceTrackerInformation[]
}

Complete Chat parameter and result interfaces can be found in chat.ts

Identity Management

The Identity Management feature is designed to centralize the management of authentication and identity-related functionality. The APIs consist of:

• Listing and managing user profiles and SSO sessions
• Obtaining valid SSO access tokens, handling the PKCE login flow as needed
• Controlling the lifetime and notifications for active SSO tokens
• Invalidating cached SSO tokens

Feature Specification

Description	Method	Params	Method type	Response Type
List profiles	aws/identity/listProfiles	ListProfilesParams	Request	ListProfilesResult
Update profiles	aws/identity/updateProfile	UpdateProfileParams	Request	UpdateProfileResult
Get SSO token	aws/identity/getSsoToken	GetSsoTokenParams	Request	GetSsoTokenResult
Invalidate SSO token	aws/identity/invalidateSsoToken	InvalidateSsoTokenParams	Request	InvalidateSsoTokenResult
Update SSO Token Management config	aws/identity/updateSsoTokenManagement	UpdateSsoTokenManagementParams	Request	UpdateSsoTokenManagementResult
SSO token changed	aws/identity/ssoTokenChanged	SsoTokenChangedParams	Notification	n/a

Complete Identity Management parameter and result interfaces can be found in identity-management.ts

Notification

The notification feature can be used to send custom customer-facing notifications to clients. Notifications can contain actions, like show URL, but also followup actions, like request customer acknowledgement. When customer reacts to followup actions, asynchronous notification is expected to be sent from client to server to notify server about this.

Notifications should be used in rare / exceptional cases that require customer attention (like some change happened or action recommended), but are not blocking the main flow. Clients can decide to throttle notifications, if too many are sent.

Consider using LSP ShowMessage notification instead, if your notification does not require actions or followup actions.

Feature Specification

Description	Method	Params	Method type	Response Type
Show notification to customer	aws/window/showNotification	NotificationParams	Notification	n/a
Send notification followup back to server	aws/window/notificationFollowup	NotificationFollowupParams	Notification	n/a

Runtime Host Environments

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 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.

server-standalone.exe

# Server options
[--stdio] - uses stdio as the communication channel (https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#implementationConsiderations)
[--set-credentials-encryption-key] - signal to server to invoke a flow for accepting encryption key before starting main server initialisation.

[--version] - server returns its version

...
# We can define extra options, e.g. extra transport modes to provide compatibility with different clients are also possible.
[--pipe] - use pipes (Windows) or socket files (Linux, Mac) as the communication channel. The pipe / socket file name is passed as the next arg or with —pipe=.
[--socket] - uses a socket as the communication channel. The port is passed as next arg or with —port=.
[--node-ipc] - use node IPC communication between the client and the server. This is only supported if both client and server run under node.

Server startup diagram:

Encryption

Runtimes support the passing of encrypted credentials over LSP with stdio as transport. Encryption options must be sent to the runtime over stdin before the LSP initalization starts. Currently, runtimes support AES symmetric encryption with 256 bit keys.

The following steps outline how to enable encrypted credentials:

1. Create a random 256 bit (32 byte) encryption key.
2. Pass the --set-credentials-encryption-key command line argument to the server process at launch. This will signal to the server that the client wants to enable encryption and will wait for the encryption options during the next 5 seconds.
3. Immediately send a JSON blob over stdin with the information in the script below, followed by the new line /n character, which will signal the end of transmission to the runtime. If LSP initialization continues, encryption options have been validated and saved. If the client fails to send encryption options during the first 5 seconds or the JSON object is invalid, the process will exit with status code 10.

{
    "version": "1.0",
    "key": "<base64 encoded encryption key>",
    "mode": "JWT"
}

1. After LSP initialization is complete, destinations should send credentials over LSP and are responsible for keeping them updated.

To send encrypted credentials, the UpdateCredentialsPayload parameters should be sent over the corresponding aws/credentials/${type}/update method.

UpdateCredentialsPayload specification:

1. - encrypted: set to true ;
2. - data: string value representing the encrypted JWT token. Encryption must be done with { alg: 'dir', enc: 'A256GCM' } parameters. The payload to be encrypted must contain data field with the credentials.
3. Clients can set nbf/exp claims on the JWT token, which will be validated on the runtime side. A clockTolerance of 60 seconds is allowed when verifying the claims.

// JWT payload to be encrypted
{
   "data": <credentials>
}

WebWorker

TBD

Security

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.