|
|
**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.
|
|
|
|
