microsoft / language-server-protocol Goto Github PK

The character field in a Position structure is defined as a zero-based character offset relative to the start of the line. In the case of non-ASCII source, I believe it should be clarified, as "character" doesn't have a universal definition. I'm guessing it's most likely UTF-16 code units, but it could just as easily be Unicode codepoints or something else. Mismatched units could lead to unfortunate errors in identifying ranges in the text.

The Find References section in protocol specification is a little ambiguous at the moment.

Here's what it says at the moment:

The references request is sent from the client to the server to resolve project-wide references for the symbol denoted by the given text document position.

Changed: In 2.0 the request uses TextDocumentPositionParams with proper textDocument and position properties. In 1.0 the uri of the referenced text document was inlined into the params object.

Request

• method: 'textDocument/references'
• param: ReferenceParams defined as follows:

interface ReferenceParams extends TextDocumentPositionParams {
    context: ReferenceContext
}

interface ReferenceContext {
    /**
     * Include the declaration of the current symbol.
     */
    includeDeclaration: boolean;
}

• error: code and message set in case an exception happens during the reference request.

It is unclear to me whether ReferenceParams is a parameter to 'textDocument/references' request or it is a response param.

It seems to me that this section is missing a Response subsection with a description of the response params, but I can not tell for sure...

Is the support for syntax highlighting supposed to use the document symbols request? Wouldn't it be reasonable to be able to request this for part of a document too (in case the file is huge and scanning all of it is prohibitive)?

It would be nice to have a standard way for the server to ask the client to open a URL in the browser.

This can be an addition to the existing window service. Somethink like this.

OpenBrowser Notification

The open browser notification is sent from a server to a client to ask the client to open a particular URL in the web browser.

Notification:

• method: 'window/openBrowser'
• params: OpenBrowserParams defined as follows:

interface OpenBrowserParams {
    /**
     * The URL to open.
     */
    url: string;
}

The current protocol requires that request and notifications send from the client to the server are processed in the same order as they are sent.

I couldn't find a way to tell through the protocol that the client should move the cursor to a certain position after applying a proposal.
Simple use case, would by applying a function call, where the cursor should sit between the parentheses afterwards. E.g. foo(|)

The protocol documentation misses the initializationOptions member in the InitializeParams type.

The initializationOptions member is present in the VSCode language server implementation: https://github.com/Microsoft/vscode-languageserver-node/blob/master/server/src/protocol.ts#L226

If I want to try some extensions to the protocol (and the server), is it simply by returning more values in ServerCapabilities? The specs don't say if the client should accept (and ignore) unknown values in that list.

I understood that when a document is opened it gets an initial version number, and subsequent calls to didChange get incremented version numbers.

As no other operations refer to this version, I am wondering what the purpose of it is.

I can imagine that when using the protocol with an HTTP server (REST) there might be missing messages or jeopardised orderings. But than all references should use the version, too.

It would be good if all the URIs passed into requests after workspace intialization we're defined to be relative. A lot of implementations I've looked at require an absolute path.

We're planning to use the language server APIs in a web-based editor and would like to make the implementations highly available. To do this, we'd like to have many language servers running on different servers and using root paths in temporary directories. If all the requests take in absolute URIs then the files that the language workspaces operate on have to be in the same place for every language server which is not ideal.

It would be nice if a location and a container of symbol are resolved later. In our case we have an index of symbols but it is missing information about locations, so to compute them we have to load models for all found symbols. I assume that locations are required for navigation and their can be computed on demand later. The same should be true for references.

It would be helpful to have a wiki page where we can list any efforts that are working on either a client side or a server side implementation of the protocol.
It's a key information to convince people to use this API and currently hard to find.
So far it seems like from your side vscode is the only client implementation and your JSON support is the only server implementation.
What else are people working on?

Hey! Firstly, I'd like to say great thanks for this protocol, I've been dreaming about this for a long time now and you guys finally designed a good one! I'm currently implementing a language server for the Haxe language using this.

Now I have a question about request cancellation. It's not clear whether how exactly the server should react to these notifications. Should it send any response back or just silently cancel the action and act like there was no request at all?

Please, clarify that in the specification!

Some languages require the file name to match the name of the class, interface, or other symbol that the file contains. Renaming a symbol should optionally allow its file to be renamed too.

I can't tell from the docs if this is supported somehow, but I think it would be useful: for operations that may take a long time, return periodically a partial response, so that the client can show something in the meantime.

There is something that might be it for completion (a CompletionList has an isIncomplete attribute, but it may mean something else), but this can apply for any operation: if the return value is a list, then it should be possible to return it in chunks. This also means that an operation can return results and still finally return an error - but the client still has something useful to work with (albeit incomplete).

Client capabilities should specify if this kind of responses should be used or not.

For cases where there are a (potentially) large number of results or a large response message add the ability to break the results into smaller sets.

I'm trying to implement CodeLens and CodeAction for Eclipse IDE. I see it uses commands. Such commands seem to be references to existing command handlers, however the protocol doesn't define those commands and which part of the application is supposed to define/handle them.
An explanation about it in the protocol.md file would be welcome, or maybe just an example of how VSCode deals with it.

Mainly for debugging purpose -seems like my invocations of didChange are not correct-, I'd like to retrieve the current state of the file for the language server. I didn't find a method to do that directly. Can one of the current operations be used for that?

The spec for cancelling requests doesn't specify how the server indicates to the client that a response reflects a canceled request.

For example, a client sends request 1 and then cancels request 1. The server sends a response for request 1 and should provide either a complete response to 1 (because the cancellation request was ignored or came in after the response was complete) or provide indication that the processing of request 1 was in fact canceled. But the latter bit is not spec'd out. How can the client discern between a complete result, a general error, and a mere cancellation in the response message?

Actually, all requests could have an optional range parameter (in case they don't already), so that both server processing and network chatter can be minimised. Often, the client is just interested in information about the chunk of code that is currently visible in the editor.

Description of ClientCapabilities is missing

The doc doesn't say how one knows that a completion item is incomplete and a resolve is required.Is it sent always when an item is selected? Is it sent when some field is null?

I know lexical coloring is something that should be done on the client. However as this information is fully declarative (TextMate language grammars) we could serve the initial configuration from a language server instead of putting it into the extension json.

The reason is that I would like to define and package one language server and use it in many different editors as is. I.e. without the need to do some editor specific plumbing for every editor. Today only VSCode understands this protocol, but we should try to make it more widely used in order to leverage its full potential. I.e. we are working on a client for Che and on a server side implementation with Xtext.

For servers that only target vscode It could be simply ignored and turned off through the server capabilities.

In the case if a language server provides support for several languages (Xtext does it) then server capabilities should be configured per a language.

For example different triggered characters could be used by different languages to trigger content assist, signature help and so on.

protocol.d.ts has the following for a completion request

export declare namespace CompletionRequest {
    const type: RequestType <TextDocumentPosition, CompletionItem[] | CompletionList, void >;
}

Protocol spec currently only specifies CompletionItem[] as response type.

As discussed and noted in issue #18, there might be something wrong with the document highlight spec (see #18 (comment) and below).

Furthermore, the wording of the spec does not tell me what this feature is for (apparently something like 'mark occurrences'), so, it's unclear to me at the moment.

The distinction between read/write/text is unclear to me, too. What is it useful for exactly? (Would be good to know so that I know how to map it to my language.)

And, the vscode apparently also expects a collection of elements as return value, as noted by @cdietrich:

export interface DocumentHighlightProvider {
  provideDocumentHighlights(model: editor.IReadOnlyModel, position: Position, token: CancellationToken): DocumentHighlight[] | Thenable<DocumentHighlight[]>;
}

I have some questions about this protocol and how is meant to be implementated.

1. Must it run locally along the IDE?
2. Should the LS accept different IDE sessions on a single instance?
3. I saw that vscode uses IPC for communication, is there a hard requirement/specification for the protocol or can we use WebSockets e.x.?
4. If yes to 1. and it can run remotely, does the protocol provide any security mechanism?

Many languages require building an index database for an efficient calculation of code completion, validation, highlighting, etc.

The language server protocol currently does not describe how the communication between the client and the server should happen. Thus, every server-client pair take their own approach. For example the Crane PHP language server uses custom message requests and notifications, while the Eclipse Java language server seems to trigger the indexing as part of the initialize request.

Please, consider specifying:

• How the client request the server to (re-)build the index.
• How the client tells the server which files are included and excluded for indexing.
• How the server reports progress to the client.
• How the server notifies the client that the index is complete.
• How the server notifies the client for any errors.

Based on the current version of the protocol, I got the idea, that it's basically impossible to transfer information about multiple text cursors.

Are there any plans for supporting multiple text cursors?

It seems like 'rangeLength' is redundant, as it can be computed from the 'range'. Should be deprecated.

Why are there two different requests? Couldn't the range parameter be optional, with missing=whole document?

Alternatively, it would help to clarify that it's out of scope and link to how current clients do it. Although it seems that it's somewhat in scope, given that shutdown and exit are implemented commands.
Especially: who is responsible for starting a language server (per user? per project? per workspace?)

Like WebStorm and VS does: eg. Symbol is a type or parameter or namespace or unresolved ...

Textmate based grammars are hard to do this. Since we did support Diagnostics, why not support semantic highlighting?

There a few versions of the JSON RPC. While I assume it's 2.0, it would be nice if this was explicitly stated.

The specification is targetting programming languages. The same issues though appear in case of remote editing of any "stylised" document - from markup text files (DocOnce, CommonMark, AsciiDoc, etc.) up to full-featured "office" solutions like LibreOffice, Microsoft Office, etc.

Wouldn't it make sense to accommodate wording throughout the specification to make it applicable to other editing scenarios (mentioned above) as well?

Out of the rename operation, I couldn't find an operation for refactorings. I would expect something like

path: /refactorings
params: TextDocumentIdentifier, Range
result: Refactoring[] with Refactoring={String title, WorkspaceEdit[]}

is there already an operation I missed, which is meant to support that?

How does the client requests that a command be executed? I can't see a request for that...

Also, as specified, code actions (that use commands) seem to be related to markers - can they be used everywhere?

From the current specification it's not clear to me how the server should handle simultaneous access of multiple clients editing the same buffer.

Could you please clarify how is this situation handled?

Location of a symbol for "goto definition" isn't always the word on a given location, so it makes sense to also return optional Range value in response, similar to Hover, so IDEs can highlight the actual symbol that represents a reference, not just a single word.

Here's an example from my experience:

using package.Module.Type;

Here package.Module.Type is the atomic symbol, language doesn't return positions for concrete words here, but for the whole type path instead. However VS Code underlines each word separately, which can be a little confusing to the user, since each of them will point to the same position.

Hence it would be nice to be able to indicate a real symbol's position for highlighting in the IDE.

It seems this protocol has similarities to the Chrome Remote Debugging protocol.

Does it make sense for the repo to have a protocol.json file ? e.g https://cs.chromium.org/chromium/src/third_party/WebKit/Source/platform/v8_inspector/js_protocol.json

This means different language servers implement the protocol and maintain a protocol.json file which can be queried if the API is compatible and has any breaking changes.

The protocol.json can then be used to automatically generate code for a client or server implementation in languages other than typescript.

e.g I can consume protocol.json and automatically generate a Java class for java language service interface.

Same for PHP, python and the rest. Code generation on both client and server can benefit.

When exactly should this notification be sent? Will this notification with a file marked as FileChangeType.Changed always be sent alongside a DidChangeTextDocumentNotification? Or should the DidChangeWatchedFiles Notification with a FileChangeType.Changed only be sent for changes to files made outside of the language server? As in, when we get a DidChangeWatchedFiles we should reset the files we are watching because they have changed externally.

https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#didchangetextdocument-notification

The definition of TextDocumentContentChangeEvent is a bit unclear. Is the range inclusive at the start and end? Only at the start? What is rangeLength used for?

I started to implement a 2.0 version of the protocol. High level the changes are:

• alignment of the protocol with the VSCode exension API. As a result the properties of a request param object conform to parameters in the API. So for example if the VSCode extension API takes a text document has the first parameter the corresponding parameter literal in the JSON RPC protocol now has a property textDocument.
• consistent support for language identifiers. This means that the language ID is passed to the server via the open notification. Further references to the text document don't transfer this informaiton anymore.
• support for version numbers on documents. The initial version number is send to the server via the open notification. Document change notification do carry information about VSCode's version number as well.

I moved to version 2.0 since especially the first item makes the changes incompatible with the 1.0 version. However I think they are worthwhile the change and easy to adopt since they are mostly JSON literal changes.

The document here describes the changes. It uses a New / Changed annotation to highlight the changes (see below).

Feedback to the new version is highly welcome.

I am experimenting with implementing a Language Server Hover Service and i stumbled over the definition of the Position Parameter in that service.

e.g. if i hover on (the middle of) the second character i get requested with Position {line: 0, character: 2}
although position says character is zero based

Unless I'm misunderstanding, weren't simple URIs replaced with TextDocumentIdentifiers elsewhere? Then I'd say that it should be dine even here.

CompletionItem has a single TextEdit; it would be nice to allow multiple TextEdits.

Example: In the context of a Java file, the CompletionItem of a type (class, interface, etc.) could include an additional text edit to add an import declaration for that type if necessary.

It looks like that for me -- maybe they could be merged in one request? That would also allow defining other scopes (all open documents, or other subset of the workspace).

Some parts of the protocol cannot be implemented properly in statically typed languages such as Java. Examples:

• Completion Request response result: CompletionItem[] | CompletionList
• Hover: type MarkedString = string | { language: string; value: string };

Of course this can be handled during the conversion between JSON and the specific Java data structures. But wouldn't it be better to drop some flexibility in favor of more explicit typing, so this kind of conversion would not be necessary? For example, with a JSON library such as Gson most of the protocol parsing and serialization can be done with the generic capabilities of the library, but ambiguities such as those mentioned above require to implement special cases for the respective types.

Why is this needed? Surely any server could query the operating system for this information?