internals: extract wire protocol version 2 commands to standalone doc
wireprotocol.txt is a bit long and unwieldy. I think splitting it up
will help aid comprehension.
Let's start by extracting wire protocol version 2 commands to a
standalone document.
As part of the port, I munged with the section titles a bit and
expanded the TODO around node namespaces.
Differential Revision: https://phab.mercurial-scm.org/D4442
--- a/contrib/wix/help.wxs Thu Aug 23 13:46:39 2018 -0700
+++ b/contrib/wix/help.wxs Thu Aug 23 13:11:13 2018 -0700
@@ -51,6 +51,7 @@
<File Id="internals.requirements.txt" Name="requirements.txt" />
<File Id="internals.revlogs.txt" Name="revlogs.txt" />
<File Id="internals.wireprotocol.txt" Name="wireprotocol.txt" />
+ <File Id="internals.wireprotocolv2.txt" Name="wireprotocolv2.txt" />
</Component>
</Directory>
--- a/mercurial/help/internals/wireprotocol.txt Thu Aug 23 13:46:39 2018 -0700
+++ b/mercurial/help/internals/wireprotocol.txt Thu Aug 23 13:11:13 2018 -0700
@@ -1379,6 +1379,9 @@
This section contains a list of all wire protocol commands implemented by
the canonical Mercurial server.
+See :hg:`help internals.wireprotocolv2` for information on commands exposed
+to the frame-based protocol.
+
batch
-----
@@ -1750,164 +1753,3 @@
The server may also respond with a generic error type, which contains a string
indicating the failure.
-
-Frame-Based Protocol Commands
-=============================
-
-**Experimental and under active development**
-
-This section documents the wire protocol commands exposed to transports
-using the frame-based protocol. The set of commands exposed through
-these transports is distinct from the set of commands exposed to legacy
-transports.
-
-The frame-based protocol uses CBOR to encode command execution requests.
-All command arguments must be mapped to a specific or set of CBOR data
-types.
-
-The response to many commands is also CBOR. There is no common response
-format: each command defines its own response format.
-
-TODO require node type be specified, as N bytes of binary node value
-could be ambiguous once SHA-1 is replaced.
-
-branchmap
----------
-
-Obtain heads in named branches.
-
-Receives no arguments.
-
-The response is a map with bytestring keys defining the branch name.
-Values are arrays of bytestring defining raw changeset nodes.
-
-capabilities
-------------
-
-Obtain the server's capabilities.
-
-Receives no arguments.
-
-This command is typically called only as part of the handshake during
-initial connection establishment.
-
-The response is a map with bytestring keys defining server information.
-
-The defined keys are:
-
-commands
- A map defining available wire protocol commands on this server.
-
- Keys in the map are the names of commands that can be invoked. Values
- are maps defining information about that command. The bytestring keys
- are:
-
- args
- A map of argument names and their expected types.
-
- Types are defined as a representative value for the expected type.
- e.g. an argument expecting a boolean type will have its value
- set to true. An integer type will have its value set to 42. The
- actual values are arbitrary and may not have meaning.
- permissions
- An array of permissions required to execute this command.
-
-compression
- An array of maps defining available compression format support.
-
- The array is sorted from most preferred to least preferred.
-
- Each entry has the following bytestring keys:
-
- name
- Name of the compression engine. e.g. ``zstd`` or ``zlib``.
-
-framingmediatypes
- An array of bytestrings defining the supported framing protocol
- media types. Servers will not accept media types not in this list.
-
-rawrepoformats
- An array of storage formats the repository is using. This set of
- requirements can be used to determine whether a client can read a
- *raw* copy of file data available.
-
-heads
------
-
-Obtain DAG heads in the repository.
-
-The command accepts the following arguments:
-
-publiconly (optional)
- (boolean) If set, operate on the DAG for public phase changesets only.
- Non-public (i.e. draft) phase DAG heads will not be returned.
-
-The response is a CBOR array of bytestrings defining changeset nodes
-of DAG heads. The array can be empty if the repository is empty or no
-changesets satisfied the request.
-
-TODO consider exposing phase of heads in response
-
-known
------
-
-Determine whether a series of changeset nodes is known to the server.
-
-The command accepts the following arguments:
-
-nodes
- (array of bytestrings) List of changeset nodes whose presence to
- query.
-
-The response is a bytestring where each byte contains a 0 or 1 for the
-corresponding requested node at the same index.
-
-TODO use a bit array for even more compact response
-
-listkeys
---------
-
-List values in a specified ``pushkey`` namespace.
-
-The command receives the following arguments:
-
-namespace
- (bytestring) Pushkey namespace to query.
-
-The response is a map with bytestring keys and values.
-
-TODO consider using binary to represent nodes in certain pushkey namespaces.
-
-lookup
-------
-
-Try to resolve a value to a changeset revision.
-
-Unlike ``known`` which operates on changeset nodes, lookup operates on
-node fragments and other names that a user may use.
-
-The command receives the following arguments:
-
-key
- (bytestring) Value to try to resolve.
-
-On success, returns a bytestring containing the resolved node.
-
-pushkey
--------
-
-Set a value using the ``pushkey`` protocol.
-
-The command receives the following arguments:
-
-namespace
- (bytestring) Pushkey namespace to operate on.
-key
- (bytestring) The pushkey key to set.
-old
- (bytestring) Old value for this key.
-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.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/mercurial/help/internals/wireprotocolv2.txt Thu Aug 23 13:11:13 2018 -0700
@@ -0,0 +1,172 @@
+Wire Protocol Version 2
+=======================
+
+**Experimental and under active development**
+
+This section documents the wire protocol commands exposed to transports
+using the frame-based protocol. The set of commands exposed through
+these transports is distinct from the set of commands exposed to legacy
+transports.
+
+The frame-based protocol uses CBOR to encode command execution requests.
+All command arguments must be mapped to a specific or set of CBOR data
+types.
+
+The response to many commands is also CBOR. There is no common response
+format: each command defines its own response format.
+
+TODOs
+=====
+
+* Add "node namespace" support to each command. In order to support
+ SHA-1 hash transition, we want servers to be able to expose different
+ "node namespaces" for the same data. Every command operating on nodes
+ should specify which "node namespace" it is operating on and responses
+ should encode the "node namespace" accordingly.
+
+Commands
+========
+
+The sections below detail all commands available to wire protocol version
+2.
+
+branchmap
+---------
+
+Obtain heads in named branches.
+
+Receives no arguments.
+
+The response is a map with bytestring keys defining the branch name.
+Values are arrays of bytestring defining raw changeset nodes.
+
+capabilities
+------------
+
+Obtain the server's capabilities.
+
+Receives no arguments.
+
+This command is typically called only as part of the handshake during
+initial connection establishment.
+
+The response is a map with bytestring keys defining server information.
+
+The defined keys are:
+
+commands
+ A map defining available wire protocol commands on this server.
+
+ Keys in the map are the names of commands that can be invoked. Values
+ are maps defining information about that command. The bytestring keys
+ are:
+
+ args
+ A map of argument names and their expected types.
+
+ Types are defined as a representative value for the expected type.
+ e.g. an argument expecting a boolean type will have its value
+ set to true. An integer type will have its value set to 42. The
+ actual values are arbitrary and may not have meaning.
+ permissions
+ An array of permissions required to execute this command.
+
+compression
+ An array of maps defining available compression format support.
+
+ The array is sorted from most preferred to least preferred.
+
+ Each entry has the following bytestring keys:
+
+ name
+ Name of the compression engine. e.g. ``zstd`` or ``zlib``.
+
+framingmediatypes
+ An array of bytestrings defining the supported framing protocol
+ media types. Servers will not accept media types not in this list.
+
+rawrepoformats
+ An array of storage formats the repository is using. This set of
+ requirements can be used to determine whether a client can read a
+ *raw* copy of file data available.
+
+heads
+-----
+
+Obtain DAG heads in the repository.
+
+The command accepts the following arguments:
+
+publiconly (optional)
+ (boolean) If set, operate on the DAG for public phase changesets only.
+ Non-public (i.e. draft) phase DAG heads will not be returned.
+
+The response is a CBOR array of bytestrings defining changeset nodes
+of DAG heads. The array can be empty if the repository is empty or no
+changesets satisfied the request.
+
+TODO consider exposing phase of heads in response
+
+known
+-----
+
+Determine whether a series of changeset nodes is known to the server.
+
+The command accepts the following arguments:
+
+nodes
+ (array of bytestrings) List of changeset nodes whose presence to
+ query.
+
+The response is a bytestring where each byte contains a 0 or 1 for the
+corresponding requested node at the same index.
+
+TODO use a bit array for even more compact response
+
+listkeys
+--------
+
+List values in a specified ``pushkey`` namespace.
+
+The command receives the following arguments:
+
+namespace
+ (bytestring) Pushkey namespace to query.
+
+The response is a map with bytestring keys and values.
+
+TODO consider using binary to represent nodes in certain pushkey namespaces.
+
+lookup
+------
+
+Try to resolve a value to a changeset revision.
+
+Unlike ``known`` which operates on changeset nodes, lookup operates on
+node fragments and other names that a user may use.
+
+The command receives the following arguments:
+
+key
+ (bytestring) Value to try to resolve.
+
+On success, returns a bytestring containing the resolved node.
+
+pushkey
+-------
+
+Set a value using the ``pushkey`` protocol.
+
+The command receives the following arguments:
+
+namespace
+ (bytestring) Pushkey namespace to operate on.
+key
+ (bytestring) The pushkey key to set.
+old
+ (bytestring) Old value for this key.
+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.