# HG changeset patch
# User Gregory Szorc <gregory.szorc@gmail.com>
# Date 1522086636 25200
# Node ID b0041036214e526643f394459d6bf44d39dd84f3
# Parent  cc5a040fe1502393439f0c0e5ae92330bef07625
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

diff -r cc5a040fe150 -r b0041036214e mercurial/help/internals/wireprotocol.txt
--- 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``)
 -----------------------------------
 
diff -r cc5a040fe150 -r b0041036214e mercurial/wireprotoframing.py
--- 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: {},
 }