Skip to content

Add support to report progress for a running request #70

Closed

Description

No description provided.

Activity

  1. added this to the milestone on Sep 19, 2016
  2. felixfbecker commented on Sep 19, 2016

    @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.
  3. felixfbecker commented on Nov 4, 2016

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

  4. kaloyan-raev commented on Nov 4, 2016

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

  5. felixfbecker commented on Nov 4, 2016

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

  6. felixfbecker commented on Nov 4, 2016

    @felixfbecker

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

  7. kaloyan-raev commented on Nov 4, 2016

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

  8. felixfbecker commented on Nov 4, 2016

    @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)

  9. kaloyan-raev commented on Nov 4, 2016

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

  10. felixfbecker commented on Nov 4, 2016

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

  11. kaloyan-raev commented on Nov 7, 2016

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

  12. felixfbecker commented on Nov 7, 2016

    @felixfbecker

    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:

    interface ClientCapabilities {
      /**
        * 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;
    }
  13. kaloyan-raev commented on Nov 7, 2016

    @kaloyan-raev

    How about using an additional ProgressOptions interface like CompletionOptions is used for the completionProvider?

    /**
     * Progress reporting options.
     */
    interface ProgressOptions {
      /**
       * The minimum number of milliseconds between two progress notifications.
       */
      rateLimit?: number;
    }
    
    interface ClientCapabilities {
      /**
       * 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.

  14. 28 remaining items

  15. keegancsmith commented on May 18, 2017

    @keegancsmith

    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.

  16. Xanewok commented on Oct 9, 2017

    @Xanewok
    Contributor

    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.

  17. dbaeumer commented on Apr 15, 2019

    @dbaeumer
    MemberAuthor

    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.

    	/**
    	 * Window specific client capabilities.
    	 */
    	window?: {
    		/**
    		 * Whether client supports handling progress notifications.
    		 */
    		progress?: boolean;
    	}
    Progress Start Notification

    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:
    export interface ProgressStartParams {
    
    	/**
    	 * 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:
    export interface ProgressReportParams {
    
    	/**
    	 * 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:
    export interface ProgressDoneParams {
    	/**
    	 * 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:
    export interface ProgressCancelParams {
    	/**
    	 * A unique identifier to associate multiple progress notifications with the same progress.
    	 */
    	id: string;
    }
  18. ljw1004 commented on Apr 15, 2019

    @ljw1004
    Contributor

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

  19. dbaeumer commented on Apr 15, 2019

    @dbaeumer
    MemberAuthor

    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.

  20. dbaeumer commented on Apr 15, 2019

    @dbaeumer
    MemberAuthor

    I published next versions of the VS Code LSP protocol, client and server libs that have support for progress.

  21. added a commit that references this issue on Jun 11, 2019
  22. dbaeumer commented on Jul 3, 2019

    @dbaeumer
    MemberAuthor

    Please see also #786

  23. dbaeumer commented on Sep 20, 2019

    @dbaeumer
    MemberAuthor

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

  24. locked and limited conversation to collaborators on Nov 4, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

feature-requestRequest for new features or functionalityhelp wantedIssues identified as good community contribution opportunities

Type

No type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions

    ⌂ 换网址