Mercurial > public > mercurial-scm > hg-stable
diff 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
| author | Gregory Szorc <gregory.szorc@gmail.com> |
|---|---|
| date | Mon, 08 Oct 2018 18:17:12 -0700 |
| parents | 30f70d11c224 |
| children | 46a40bce3ae0 |
line wrap: on
line diff
--- a/mercurial/help/internals/wireprotocolv2.txt Mon Oct 08 17:54:14 2018 -0700 +++ b/mercurial/help/internals/wireprotocolv2.txt Mon Oct 08 18:17:12 2018 -0700 @@ -144,22 +144,15 @@ 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. +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. - The roots array may be empty. The heads array must be defined. - -nodes - (array of bytestrings) Changelog revisions to request explicitly. + Data will be sent for the union of all revisions resolved by all + revision specifiers. -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. + Only revision specifiers operating on changeset revisions are allowed. fields (set of bytestring) Which data associated with changelog revisions to @@ -178,10 +171,6 @@ 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: @@ -238,13 +227,6 @@ ``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 @@ -540,3 +522,40 @@ 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.