wireproto: define frame to represent progress updates
authorGregory Szorc <gregory.szorc@gmail.com>
Mon, 26 Mar 2018 10:50:36 -0700
changeset 37291 b0041036214e
parent 37290 cc5a040fe150
child 37292 3d0e2cd86e05
wireproto: define frame to represent progress updates Today, a long-running operation on a server may run without any sign of progress on the client. This can lead to the conclusion that the server has hung or the connection has dropped. In fact, connections can and do time out due to inactivity. And a long-running server operation can result in the connection dropping prematurely because no data is being sent! While we're inventing the new wire protocol, let's provide a mechanism for communicating progress on potentially expensive server-side events. We introduce a new frame type that conveys "progress" updates. This frame type essentially holds the data required to formulate a ``ui.progress()`` call. We only define the frame right now. Implementing it will be a bit of work since there is no analog to progress frames in the existing wire protocol. We'll need to teach the ui object to write to the wire protocol, etc. The use of a CBOR map may seem wasteful, as this will encode key names in every frame. This *is* wasteful. However, maps are extensible. And the intent is to always use compression via streams. Compression will make the overhead negligible since repeated strings will be mostly eliminated over the wire. Differential Revision: https://phab.mercurial-scm.org/D2902
mercurial/help/internals/wireprotocol.txt
mercurial/wireprotoframing.py
--- a/mercurial/help/internals/wireprotocol.txt	Wed Mar 28 15:05:39 2018 -0700
+++ b/mercurial/help/internals/wireprotocol.txt	Mon Mar 26 10:50:36 2018 -0700
@@ -740,6 +740,44 @@
 The last atom in the frame SHOULD end with a newline (``\n``). If it
 doesn't, clients MAY add a newline to facilitate immediate printing.
 
+Progress Update (``0x07``)
+--------------------------
+
+This frame holds the progress of an operation on the peer. Consumption
+of these frames allows clients to display progress bars, estimated
+completion times, etc.
+
+Each frame defines the progress of a single operation on the peer. The
+payload consists of a CBOR map with the following bytestring keys:
+
+topic
+   Topic name (string)
+pos
+   Current numeric position within the topic (integer)
+total
+   Total/end numeric position of this topic (unsigned integer)
+label (optional)
+   Unit label (string)
+item (optional)
+   Item name (string)
+
+Progress state is created when a frame is received referencing a
+*topic* that isn't currently tracked. Progress tracking for that
+*topic* is finished when a frame is received reporting the current
+position of that topic as ``-1``.
+
+Multiple *topics* may be active at any given time.
+
+Rendering of progress information is not mandated or governed by this
+specification: implementations MAY render progress information however
+they see fit, including not at all.
+
+The string data describing the topic SHOULD be static strings to
+facilitate receivers localizing that string data. The emitter
+MUST normalize all string data to valid UTF-8 and receivers SHOULD
+validate that received data conforms to UTF-8. The topic name
+SHOULD be ASCII.
+
 Stream Encoding Settings (``0x08``)
 -----------------------------------
 
--- a/mercurial/wireprotoframing.py	Wed Mar 28 15:05:39 2018 -0700
+++ b/mercurial/wireprotoframing.py	Mon Mar 26 10:50:36 2018 -0700
@@ -45,6 +45,7 @@
 FRAME_TYPE_BYTES_RESPONSE = 0x04
 FRAME_TYPE_ERROR_RESPONSE = 0x05
 FRAME_TYPE_TEXT_OUTPUT = 0x06
+FRAME_TYPE_PROGRESS = 0x07
 FRAME_TYPE_STREAM_SETTINGS = 0x08
 
 FRAME_TYPES = {
@@ -54,6 +55,7 @@
     b'bytes-response': FRAME_TYPE_BYTES_RESPONSE,
     b'error-response': FRAME_TYPE_ERROR_RESPONSE,
     b'text-output': FRAME_TYPE_TEXT_OUTPUT,
+    b'progress': FRAME_TYPE_PROGRESS,
     b'stream-settings': FRAME_TYPE_STREAM_SETTINGS,
 }
 
@@ -107,6 +109,7 @@
     FRAME_TYPE_BYTES_RESPONSE: FLAGS_BYTES_RESPONSE,
     FRAME_TYPE_ERROR_RESPONSE: FLAGS_ERROR_RESPONSE,
     FRAME_TYPE_TEXT_OUTPUT: {},
+    FRAME_TYPE_PROGRESS: {},
     FRAME_TYPE_STREAM_SETTINGS: {},
 }