comparison mercurial/help/internals/wireprotocolv2.txt @ 40176:41263df08109

wireprotov2: change how revisions are specified to changesetdata

Right now, we have a handful of arguments for specifying the revisions
whose data should be returned. Defining how all these arguments
interact when various combinations are present is difficult.

This commit establishes a new, generic mechanism for specifying
revisions. Instead of a hodgepodge of arguments defining things, we
have a list of dicts that specify revision selectors. The final set
of revisions is a union of all these selectors.

We implement support for specifying revisions based on:

* An explicit list of changeset revisions
* An explicit list of changeset revisions plus ancestry depth
* A DAG range between changeset roots and heads

If you squint hard enough, this problem has already been solved by
revsets. But I'm reluctant to expose revsets to the wire protocol
because that would require servers to implement a revset parser.
Plus there are security and performance implications: the set
of revision selectors needs to be narrowly and specifically tailored
for what is appropriate to be executing on a server. Perhaps there
would be a way for us to express the "parse tree" of a revset
query, for example. I'm not sure. We can explore this space another
time. For now, the new mechanism should bring sufficient flexibility
while remaining relatively simple.

The selector "types" are prefixed with "changeset" because I plan
to add manifest and file-flavored selectors as well. This will enable
us to e.g. select file revisions based on a range of changeset
revisions.

Differential Revision: https://phab.mercurial-scm.org/D4979

40175:6c42409691ec

Obtain various data related to changesets.

The command accepts the following arguments:

noderange
   (array of arrays of bytestrings) An array of 2 elements, each being an
   array of node bytestrings. The first array denotes the changelog revisions
   that are already known to the client. The second array denotes the changelog
   revision DAG heads to fetch. The argument essentially defines a DAG range
   bounded by root and head nodes to fetch.

   The roots array may be empty. The heads array must be defined.

nodes
   (array of bytestrings) Changelog revisions to request explicitly.

nodesdepth
   (unsigned integer) Number of ancestor revisions of elements in ``nodes``
   to also fetch. When defined, for each element in ``nodes``, DAG ancestors
   will be walked until at most N total revisions are emitted.

fields
   (set of bytestring) Which data associated with changelog revisions to
   fetch. The following values are recognized:

      The phase state of a revision.

   revision
      The raw, revision data for the changelog entry. The hash of this data
      will match the revision's node value.

The server resolves the set of revisions relevant to the request by taking
the union of the ``noderange`` and ``nodes`` arguments. At least one of these
arguments must be defined.

The response bytestream starts with a CBOR map describing the data that follows.
This map has the following bytestring keys:

totalitems

phase (optional)
   (bytestring) The phase that a revision is in. Recognized values are
   ``secret``, ``draft``, and ``public``. Only present if ``phase`` data
   is being requested.

If nodes are requested via ``noderange``, they will be emitted in DAG order,
parents always before children.

If nodes are requested via ``nodes``, they will be emitted in requested order.

Nodes from ``nodes`` are emitted before nodes from ``noderange``.

The set of changeset revisions emitted may not match the exact set of
changesets requested. Furthermore, the set of keys present on each
map may vary. This is to facilitate emitting changeset updates as well
as new revisions.

new
   (bytestring) New value for this key.

TODO consider using binary to represent nodes is certain pushkey namespaces.
TODO better define response type and meaning.

40176:41263df08109

Obtain various data related to changesets.

The command accepts the following arguments:

revisions
   (array of maps) Specifies revisions whose data is being requested. Each
   value in the array is a map describing revisions. See the
   *Revisions Specifiers* section below for the format of this map.

   Data will be sent for the union of all revisions resolved by all
   revision specifiers.

   Only revision specifiers operating on changeset revisions are allowed.

fields
   (set of bytestring) Which data associated with changelog revisions to
   fetch. The following values are recognized:

      The phase state of a revision.

   revision
      The raw, revision data for the changelog entry. The hash of this data
      will match the revision's node value.

The response bytestream starts with a CBOR map describing the data that follows.
This map has the following bytestring keys:

totalitems

phase (optional)
   (bytestring) The phase that a revision is in. Recognized values are
   ``secret``, ``draft``, and ``public``. Only present if ``phase`` data
   is being requested.

The set of changeset revisions emitted may not match the exact set of
changesets requested. Furthermore, the set of keys present on each
map may vary. This is to facilitate emitting changeset updates as well
as new revisions.

new
   (bytestring) New value for this key.

TODO consider using binary to represent nodes is certain pushkey namespaces.
TODO better define response type and meaning.

Revision Specifiers
===================

A *revision specifier* is a map that evaluates to a set of revisions.

A *revision specifier* has a ``type`` key that defines the revision
selection type to perform. Other keys in the map are used in a
type-specific manner.

The following types are defined:

changesetexplicit
   An explicit set of enumerated changeset revisions.

   The ``nodes`` key MUST contain an array of full binary nodes, expressed
   as bytestrings.

changesetexplicitdepth
   Like ``changesetexplicit``, but contains a ``depth`` key defining the
   unsigned integer number of ancestor revisions to also resolve. For each
   value in ``nodes``, DAG ancestors will be walked until up to N total
   revisions from that ancestry walk are present in the final resolved set.

changesetdagrange
   Defines revisions via a DAG range of changesets on the changelog.

   The ``roots`` key MUST contain an array of full, binary node values
   representing the *root* revisions.

   The ``heads`` key MUST contain an array of full, binary nodes values
   representing the *head* revisions.

   The DAG range between ``roots`` and ``heads`` will be resolved and all
   revisions between will be used. Nodes in ``roots`` are not part of the
   resolved set. Nodes in ``heads`` are. The ``roots`` array may be empty.
   The ``heads`` array MUST be defined.