Add support to report progress for a running request

[dbaeumer]

[felixfbecker]

Moving my suggestions here

I see two possibilities here

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

[felixfbecker]

Proposal

Add a new notification window/progress that is sent from the server to the client.
Params:

interface ProgressParams {

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

[kaloyan-raev]

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]

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]

Of course ClientCapabilities should be extended so a server can save sending these notifications if the client has no use for it.

[kaloyan-raev]

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]

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]

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.

[felixfbecker]

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.

[kaloyan-raev]

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.