Mercurial > hg-stable
changeset 39458:dc61a67c1fc0
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
| author | Gregory Szorc <gregory.szorc@gmail.com> |
|---|---|
| date | Thu, 23 Aug 2018 13:11:13 -0700 |
| parents | c734a5c82f38 |
| children | ab20ee07b82d |
| files | contrib/wix/help.wxs mercurial/help/internals/wireprotocol.txt mercurial/help/internals/wireprotocolv2.txt |
| diffstat | 3 files changed, 176 insertions(+), 161 deletions(-) [+] |
line wrap: on
line diff
--- 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.