Mercurial > hg
view mercurial/help/internals/wireprotocolv2.txt @ 39461:7df9ae38c75c
help: add internals.wireprotocolv2 to the table, and remove redundant header
author | Yuya Nishihara <yuya@tcha.org> |
---|---|
date | Thu, 06 Sep 2018 21:55:30 +0900 |
parents | dc61a67c1fc0 |
children | 9c2c77c73f23 |
line wrap: on
line source
**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.