Progress support in LSP

[dbaeumer]

There are two distinct requests in LSP that ask for progress:

• one to report work done progress on requests so that clients can show a progress monitor
• one to report partial results on requests that are long running. For example workspace symbols or find all references.

The corresponding items are:

#70
#110
#182

There has been a long discussion in microsoft/vs-streamjsonrpc#139 on how to best do this in a homogeneous why in JSON-RPC and I propose that we implement the outcome of this issue in LSP as well.

The basic idea is as follows:

• clients indicate that they accept progress notifications from the server by adding a token property to the request params
• server use the $/progress notification and the provided token to report progress.

{
  "jsonrpc": "2.0",
  "method": "$/progress",
  "params": {
    "token": "the token provided in the request",
    "value": { "some": "value" }
  }
}

LSP should standardize the token property names used to indicate the progress types:

• workDone: to indicate that the client accepts work done progress.
• partialResult: to indicate that the client accepts partial result for a request.

Work Done

The value of the work done progress notification would be the same as for the window/progress/* notifications which support progress initiated from the server.

If the server supports progress it is supposed to send a first notification indicating the start.

export interface ProgressStart {

	kind: 'start';

	/**
	 * Mandatory title of the progress operation. Used to briefly inform about
	 * the kind of operation being performed.
	 *
	 * Examples: "Indexing" or "Linking dependencies".
	 */
	title: string;

	/**
	 * Controls if a cancel button should show to allow the user to cancel the
	 * long running operation. Clients that don't support cancellation are allowed
	 * to ignore the setting.
	 */
	cancellable?: boolean;

	/**
	 * Optional, more detailed associated progress message. Contains
	 * complementary information to the `title`.
	 *
	 * Examples: "3/25 files", "project/src/module2", "node_modules/some_dep".
	 * If unset, the previous progress message (if any) is still valid.
	 */
	message?: string;

	/**
	 * Optional progress percentage to display (value 100 is considered 100%).
	 * If not provided infinite progress is assumed and clients are allowed
	 * to ignore the `percentage` value in subsequent in report notifications.
	 *
	 * The value should be steadily rising. Clients are free to ignore values
	 * that are not following this rule.
	 */
	percentage?: number;
}

followed by many progress report messages:

export interface ProgressReport {

	kind: 'report';


	/**
	 * Optional, more detailed associated progress message. Contains
	 * complementary information to the `title`.
	 *
	 * Examples: "3/25 files", "project/src/module2", "node_modules/some_dep".
	 * If unset, the previous progress message (if any) is still valid.
	 */
	message?: string;

	/**
	 * Optional progress percentage to display (value 100 is considered 100%).
	 * If not provided infinite progress is assumed and clients are allowed
	 * to ignore the `percentage` value in subsequent in report notifications.
	 *
	 * The value should be steadily rising. Clients are free to ignore values
	 * that are not following this rule.
	 */
	percentage?: number;
}

an an optional done(end is implicit when the request sends a response):

export interface ProgressDoneParams {
    kind: 'done';
}

I would also adjust the proposed server initiated progress accordingly (e.g. having one one notification route with and an additional kind property). See https://github.com/Microsoft/vscode-languageserver-node/blob/master/protocol/src/protocol.progress.proposed.ts#L1

Partial Result

The value property of the partial result depends on the kind of request and needs to be specified on a request to request basis.

For example for the workspace/symbol request the value of a partial progress notification would be SymbolInformation[].

If a client accepts partial result for a request and the server sends partial result the final response must not carry any additional result data. The value should either be null or an empty data structure (e.g. empty array). The final response can of course still contain error information.

[olegtk]

this looks awesome! couple comments:

1. In Visual Studio there are some long running operation scenarios when Cancel button needs to be disabled dynamically as operation progresses and gets to the point of no cancellation (when side effects were incurred and cancelling would leave system in an inconsistent state). Would it be reasonable to include cancellable property to the ProgressReport too?
2. Also in some scenarios server can only provide incomplete results because of system state (e.g. when full result set is not yet available due to indexing) or there are too many results. It would be great if ProgressDoneParams allowed for servers to indicate such case and provide a reason why results are incomplete.

[tinaschrepfer]

Per our discussion regarding when errors occur during streaming progress, the decision is to keep current set of results reported thus far, but report an error/warning notification to user indicating something went wrong and results may be incomplete.

[sean-mcmanus]

Our C/C++ extension Find All References sends back references with types like "Possible Reference (confirmation in progress)" and we later update it to "Not a Reference", "Confirmed Reference", "Possible Reference (confirmation cancelled)", "Cannot confirm reference, etc.-- the API described here doesn't appear to allow partial results that overwrite all the existing results instead of just results that are accumulated. Could you add a progress support that supports this, such as via an "overwriteResult" progress type? We're (currently) okay with overwriting all the results and not just a subset of results that are potentially changeable and overwritable with better results later, but it's possible there could be future scenarios where this is not good, if there are too many results to overwrite -- I guess the "partialResult" could be used for stuff that is not overwritable and the "overwriteResult" could form at different set. There is another LSP request for "typed references" to match VS.

We currently implement our own "streaming" via causing a 2nd textDocument/references request that overwrites the previous results (when we want to update the results), but there are bugs, because this type of "hack" wasn't intentionally designed for, e.g. it breaks if the cursor is moved off an identifier (because it canceled out too early without sending us the LSP message), and also any popup menus get closed when the final results come in (caused by executing the references-view.find command).

[sean-mcmanus]

Ah, the details of a streaming textDocument/references were already discussed in https://github.com/microsoft/ms-lsp/issues/10 .

[dbaeumer]

Closing the issue. Corresponding support has been speced in dbaeumer/3.15 branch.