You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Add support to report progress for a running request #70
Go with the pattern of HTTP 202 Accepted. You send a request, and get back a response instantly stating the request has been "accepted". You can then do more requests with a different method, like $/progess (similar to cancel), passing the message ID of the initial request as a param, and get progress reports back.
Go with a pattern similar to HTTP 102 Processing (WebDAV). You send a request, and before the actual response comes in, the server can decide to continuously send a Progress header, and finally the actual Content-Length header and response body.
Add a new notification window/progress that is sent from the server to the client.
Params:
interfaceProgressParams{/** a unique identifier to associate multiple progress notifications with the same progress */id: string|number;/** * an optional request ID, indicating that this is the progress of a specific request from the client * if set, the client can use the information to present a progress indicator in the context of the action that triggered the request * if not set, the progress is treated as arbitrary progress for an arbitrary async operation (for example indexing) and the client can show it in a general location, like a status bar */requestId?: number|string;/** number that ranges from zero to total */status: number;/** * optional total number that status is relative to. * If set, the client can choose to display this next to the progress indicator. * If not set, assumed to be 1. */total?: number;/** * optional label for the progress. * If the client decides to use it, it should be displayed together with the progress status */label?: string;}
It can be used to report progress for requests:
-> textDocument/references request (id 1)
<- window/progress notification (progress id 1, request id 1, status 0.5)
<- window/progress notification (progress id 1, request id 1, status 1)
<- textDocument/references response (id 1)
It can also be used to report progress for file indexing for example:
<- window/progress notification (progress id 2, status 1, total 1264, label "indexing file hello.php")
<- window/progress notification (progress id 2, status 134, total 1264, label "indexing file world.php")
<- window/progress notification (progress id 2, status 1264, total 1264, label "indexing file whatever.php")
A progress indicator should be hidden by the client once a progress with status == total comes in.
Should we have some feedback from the client to server if it was able to process a certain progress status?
Imagine, like in the indexing, that the server floods the client with tons of progress status messages. If the system is not fast enough, we may have the situation where the server is notifying for progress status 1000 while the client still handles status 50 and has 950 more in the message queue.
The above situation can be mitigated if the server sends a new progress status only if the client was able to handle the previous one. This way the server will send only a fraction of all possible progress statuses, being gentle to the client.
Well the notifications are like events, they don't get a response. The client can choose the handle them or not. In a way they are like UDP, we just send out how the progress is going. The server needs to make sure he only handles the newest one, similar like if you sent the current time over UDP every second, or doing VoIP. A client would not queue these, but just discard messages he could not handle.
Using a request/response scheme for this would be unneeded overhead for this, the server needs to generate a unique ID for every request and map the responses back once they come in. You avoid that with notifications, as there is no real "result" from the client in this case and the server is not interested in whether the client could handle the notification.
Although it is just a notification it can really cause a lot of overhead. Even just discarding the notifications can be expensive if the messages are thousands per second.
I like the idea of utilizing the ClientCapabilities. Perhaps, the client can tell the server about the granularity of the progress information that makes sense to be sent. For example, if the client displays the progress in percentages then no more than 100 notifications are really necessary (instead of tens of thousands).
Sure, but using request/response would add even more overhead.
The number is not really important, it's the rate - in our use case, when we index 1000 files, I would send 1000 progress notifications, and that would be okay because it would be over a timespan of over a minute.
I doubt any server would have so granular progress indications for something simple like a references request that it would be a problem. For example, if the server knows he needs to iterate x ASTs, he can send a progress notification after every iterated AST. Basically I would shift that responsibility to the server, he should be responsible for not spamming notifications after every CPU tick (that would be bad for the server performance too, not just the client)
Sure, but using request/response would add even more overhead.
If we can take advantage of the ClientCapabilities then request/response would not be necessary anymore.
The number is not really important, it's the rate - in our use case, when we index 1000 files, I would send 1000 progress notifications, and that would be okay because it would be over a timespan of over a minute.
It is exactly the rate that worries me. At the moment, on my machine, the PHP Language Server indexes ~ 150 files per seconds. It's too much to send a progress notification 150 times per second.
It is exactly the rate that worries me. At the moment, on my machine, the PHP Language Server indexes ~ 150 files per seconds. It's too much to send a progress notification 150 times per second.
Actually, we already send those. We send a logMessage notification for each file. Haven't noticed any problems with this really, but we could easily choose to report only every 10th file or so.
Actually, we already send those. We send a logMessage notification for each file. Haven't noticed any problems with this really, but we could easily choose to report only every 10th file or so.
I did some performance measurements. The test case was the PHP language server to index its own source code. The performance penalty of sending a logMessage for each file is around 3%. This is on the server side. There should be an additional performance penalty on the client side that I cannot measure right now.
We can have a long debate if this performance penalty is significant or not. For other use cases with other language servers, the performance penalty of such intensive progress reporting can be significantly lower or higher. Also, different users have different perception what performance penalty is acceptable or not.
This is why most software solutions make logging configurable. You can switch it and off. You can set the a log level (like only error messages, but no warnings and info messages). BTW, this is something we miss in the LSP - the client should be able to tell if logging is desired and at what level.
Same for progress reporting - the client should be able to tell if progress reporting is desired and at what rate. Some clients may want a progress progress not more frequently than 1 seconds, others than 100 ms, or 10 ms. There could be clients that want it all, or not at all.
It should not be a big deal to incorporate such progress reporting rate in the ClientCapablities and have servers respecting it.
I did some performance measurements. The test case was the PHP language server to index its own source code. The performance penalty of sending a logMessage for each file is around 3%. This is on the server side
For the record, PHP is not the fastest, and my implementation probably isn't either.
Same for progress reporting - the client should be able to tell if progress reporting is desired and at what rate. Some clients may want a progress progress not more frequently than 1 seconds, others than 100 ms, or 10 ms. There could be clients that want it all, or not at all.
I'm all for having a flag in ClientCapabilities to enable/disable progress reports.
It should not be a big deal to incorporate such progress reporting rate in the ClientCapablities and have servers respecting it.
It complicates the implementation a bit. For basic progress reporting, we just have to increment a counter together and report it with total after each parse. With rate limiting, we have to hold a timestamp of the last progress report, measure if the difference, and only report if the difference is greater than the rate limit.
Proposal for ClientCapabilities in that case:
interfaceClientCapabilities{/** * The client provides support for window/progress notifications * If a number, specifies a rate limit as the minimum number of milliseconds between two progress notifications. * If true, there is no rate limit. */progressProvider?: boolean|number;}
How about using an additional ProgressOptions interface like CompletionOptions is used for the completionProvider?
/** * Progress reporting options. */interfaceProgressOptions{/** * The minimum number of milliseconds between two progress notifications. */rateLimit?: number;}interfaceClientCapabilities{/** * The client can process window/progress notifications. */progressProvider?: ProgressOptions;}
This way it is easy to extend the protocol with additional options without breaking compatibility. It will also avoid the issue described in #39.
For people following along I sent out a PR implementing a very minimal window/progress spec #245. It was inspired by what is in this issue and the newly available progress API for vscode extensions. It is currently marked as closed, but if others are interested in it it may be appropriate to re-open.
To spark/further current discussion on the feature, I pushed a PR with Keegan Carruthers-Smith (@keegancsmith)'s proposed protocol extension and a reference client implementation for it in microsoft/vscode-languageserver-node#261.
Please tell me your thoughts, also how to improve upon it or maybe if it'd be feasible to include it in the protocol itself.
Reacted by Keegan Carruthers-Smith and Alexey Alekhin
I merged in Igor Matuszewski (@Xanewok) work for progress into the vscode libraries as a proposed API. While implementing cancel support I separated the notification into start, report, done and cancel. Mainly because it was very hard to descibe in which cases which property combinations were valid. Was a lot easier having separate literals per request. The currently implemented proposal looks like this:
Reporting server task progress
Many tools are capable of performing some background task processing or data streaming. From a UX point of view, it's good to report both the fact that the tool is performing some background work, but also report the progress being made for it. To realize that and to provide a simple proposal based on which the feature can be later improved, the following additions are proposed:
Client Capabilities:
The client sets the following capability if it is supporting notifying task progress.
The window/progress/start notification is sent from the server to the client to ask the client to start progress.
Notification:
method: 'window/progress/start'
params: ProgressStartParams defined as follows:
exportinterfaceProgressStartParams{/** * A unique identifier to associate multiple progress notifications with * the same progress. */id: string;/** * 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;}
Progress Report Notification
The window/progress/report notification is sent from the server to the client to report progress for a previously started progress.
Notification:
method: 'window/progress/report'
params: ProgressReportParams defined as follows:
exportinterfaceProgressReportParams{/** * A unique identifier to associate multiple progress notifications with the same progress. */id: string;/** * 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 infinite progress was indicated in the start notification client * are allowed to ignore the value. In addition the value should be steadily * rising. Clients are free to ignore values that are not following this rule. */percentage?: number;}
Progress Done Notification
The window/progress/done notification is sent from the server to the client to stop a previously started progress.
Notification:
method: 'window/progress/done'
params: ProgressDoneParams defined as follows:
exportinterfaceProgressDoneParams{/** * A unique identifier to associate multiple progress notifications with the same progress. */id: string;}
Progress Cancel Notification
The window/progress/cancel notification is sent from the client to the server to inform the server that the user has pressed the
cancel button on the progress UX. A server receiving a cancel request must still close a progress using the done notification.
Notification:
method: 'window/progress/cancel'
params: ProgressCancelParams defined as follows:
exportinterfaceProgressCancelParams{/** * A unique identifier to associate multiple progress notifications with the same progress. */id: string;}
dbaumer Should we be using this progress mechanism for the LSP server to indicate a long-running process of generating diagnostics? Or should that await some future LSP message?
Context: Users have a keen wish to know when a long-running diagnostic-generating operation has finished. I imagine that progress-of-computing-diagnostics would naturally be surfaced in the UI with in the "Issues" tab itself, or within the "issues count" icons that appear in the status bar. I don't know if you expect these progress messages to typically be surfaced elsewhere...
Lucian Wischik (@ljw1004) since publish diagnostics is a push model the server should make use of the new API if wanted. If we find out that the server needs to define a location we can add something later on.
What I am also working on is to support progress per request so that the client can upfront decide where to best render the UI.
Activity
felixfbecker commentedon Sep 19, 2016
Moving my suggestions here
I see two possibilities here
$/progess(similar to cancel), passing the message ID of the initial request as a param, and get progress reports back.Progressheader, and finally the actualContent-Lengthheader and response body.felixfbecker commentedon Nov 4, 2016
Proposal
Add a new notification
window/progressthat is sent from the server to the client.Params:
It can be used to report progress for requests:
It can also be used to report progress for file indexing for example:
A progress indicator should be hidden by the client once a progress with status == total comes in.
kaloyan-raev commentedon Nov 4, 2016
Should we have some feedback from the client to server if it was able to process a certain progress status?
Imagine, like in the indexing, that the server floods the client with tons of progress status messages. If the system is not fast enough, we may have the situation where the server is notifying for progress status 1000 while the client still handles status 50 and has 950 more in the message queue.
The above situation can be mitigated if the server sends a new progress status only if the client was able to handle the previous one. This way the server will send only a fraction of all possible progress statuses, being gentle to the client.
felixfbecker commentedon Nov 4, 2016
Well the notifications are like events, they don't get a response. The client can choose the handle them or not. In a way they are like UDP, we just send out how the progress is going. The server needs to make sure he only handles the newest one, similar like if you sent the current time over UDP every second, or doing VoIP. A client would not queue these, but just discard messages he could not handle.
Using a request/response scheme for this would be unneeded overhead for this, the server needs to generate a unique ID for every request and map the responses back once they come in. You avoid that with notifications, as there is no real "result" from the client in this case and the server is not interested in whether the client could handle the notification.
felixfbecker commentedon Nov 4, 2016
Of course
ClientCapabilitiesshould be extended so a server can save sending these notifications if the client has no use for it.kaloyan-raev commentedon Nov 4, 2016
Although it is just a notification it can really cause a lot of overhead. Even just discarding the notifications can be expensive if the messages are thousands per second.
I like the idea of utilizing the
ClientCapabilities. Perhaps, the client can tell the server about the granularity of the progress information that makes sense to be sent. For example, if the client displays the progress in percentages then no more than 100 notifications are really necessary (instead of tens of thousands).felixfbecker commentedon Nov 4, 2016
Sure, but using request/response would add even more overhead.
The number is not really important, it's the rate - in our use case, when we index 1000 files, I would send 1000 progress notifications, and that would be okay because it would be over a timespan of over a minute.
I doubt any server would have so granular progress indications for something simple like a references request that it would be a problem. For example, if the server knows he needs to iterate x ASTs, he can send a progress notification after every iterated AST. Basically I would shift that responsibility to the server, he should be responsible for not spamming notifications after every CPU tick (that would be bad for the server performance too, not just the client)
kaloyan-raev commentedon Nov 4, 2016
If we can take advantage of the ClientCapabilities then request/response would not be necessary anymore.
It is exactly the rate that worries me. At the moment, on my machine, the PHP Language Server indexes ~ 150 files per seconds. It's too much to send a progress notification 150 times per second.
felixfbecker commentedon Nov 4, 2016
Actually, we already send those. We send a
logMessagenotification for each file. Haven't noticed any problems with this really, but we could easily choose to report only every 10th file or so.kaloyan-raev commentedon Nov 7, 2016
I did some performance measurements. The test case was the PHP language server to index its own source code. The performance penalty of sending a
logMessagefor each file is around 3%. This is on the server side. There should be an additional performance penalty on the client side that I cannot measure right now.We can have a long debate if this performance penalty is significant or not. For other use cases with other language servers, the performance penalty of such intensive progress reporting can be significantly lower or higher. Also, different users have different perception what performance penalty is acceptable or not.
This is why most software solutions make logging configurable. You can switch it and off. You can set the a log level (like only error messages, but no warnings and info messages). BTW, this is something we miss in the LSP - the client should be able to tell if logging is desired and at what level.
Same for progress reporting - the client should be able to tell if progress reporting is desired and at what rate. Some clients may want a progress progress not more frequently than 1 seconds, others than 100 ms, or 10 ms. There could be clients that want it all, or not at all.
It should not be a big deal to incorporate such progress reporting rate in the ClientCapablities and have servers respecting it.
felixfbecker commentedon Nov 7, 2016
For the record, PHP is not the fastest, and my implementation probably isn't either.
I'm all for having a flag in
ClientCapabilitiesto enable/disable progress reports.It complicates the implementation a bit. For basic progress reporting, we just have to increment a counter together and report it with total after each parse. With rate limiting, we have to hold a timestamp of the last progress report, measure if the difference, and only report if the difference is greater than the rate limit.
Proposal for
ClientCapabilitiesin that case:kaloyan-raev commentedon Nov 7, 2016
How about using an additional
ProgressOptionsinterface likeCompletionOptionsis used for thecompletionProvider?This way it is easy to extend the protocol with additional options without breaking compatibility. It will also avoid the issue described in #39.
28 remaining items
keegancsmith commentedon May 18, 2017
For people following along I sent out a PR implementing a very minimal
window/progressspec #245. It was inspired by what is in this issue and the newly available progress API for vscode extensions. It is currently marked as closed, but if others are interested in it it may be appropriate to re-open.Xanewok commentedon Oct 9, 2017
To spark/further current discussion on the feature, I pushed a PR with Keegan Carruthers-Smith (@keegancsmith)'s proposed protocol extension and a reference client implementation for it in microsoft/vscode-languageserver-node#261.
Please tell me your thoughts, also how to improve upon it or maybe if it'd be feasible to include it in the protocol itself.
dbaeumer commentedon Apr 15, 2019
I merged in Igor Matuszewski (@Xanewok) work for progress into the vscode libraries as a proposed API. While implementing cancel support I separated the notification into start, report, done and cancel. Mainly because it was very hard to descibe in which cases which property combinations were valid. Was a lot easier having separate literals per request. The currently implemented proposal looks like this:
Reporting server task progress
Many tools are capable of performing some background task processing or data streaming. From a UX point of view, it's good to report both the fact that the tool is performing some background work, but also report the progress being made for it. To realize that and to provide a simple proposal based on which the feature can be later improved, the following additions are proposed:
Client Capabilities:
The client sets the following capability if it is supporting notifying task progress.
Progress Start Notification
The
window/progress/startnotification is sent from the server to the client to ask the client to start progress.Notification:
ProgressStartParamsdefined as follows:Progress Report Notification
The
window/progress/reportnotification is sent from the server to the client to report progress for a previously started progress.Notification:
ProgressReportParamsdefined as follows:Progress Done Notification
The
window/progress/donenotification is sent from the server to the client to stop a previously started progress.Notification:
ProgressDoneParamsdefined as follows:Progress Cancel Notification
The
window/progress/cancelnotification is sent from the client to the server to inform the server that the user has pressed thecancel button on the progress UX. A server receiving a cancel request must still close a progress using the done notification.
Notification:
ProgressCancelParamsdefined as follows:ljw1004 commentedon Apr 15, 2019
dbaumer Should we be using this progress mechanism for the LSP server to indicate a long-running process of generating diagnostics? Or should that await some future LSP message?
Context: Users have a keen wish to know when a long-running diagnostic-generating operation has finished. I imagine that progress-of-computing-diagnostics would naturally be surfaced in the UI with in the "Issues" tab itself, or within the "issues count" icons that appear in the status bar. I don't know if you expect these progress messages to typically be surfaced elsewhere...
dbaeumer commentedon Apr 15, 2019
Lucian Wischik (@ljw1004) since publish diagnostics is a push model the server should make use of the new API if wanted. If we find out that the server needs to define a location we can add something later on.
What I am also working on is to support progress per request so that the client can upfront decide where to best render the UI.
dbaeumer commentedon Apr 15, 2019
I published next versions of the VS Code LSP protocol, client and server libs that have support for progress.
Remove EventFileValidation
Remove EventFileValidation (#1579)
dbaeumer commentedon Jul 3, 2019
Please see also #786
Remove EventFileValidation (#1579)
dbaeumer commentedon Sep 20, 2019
Closing the issue. Corresponding support has been speced in dbaeumer/3.15 branch.