author | Pulkit Goyal <7895pulkit@gmail.com> |
Mon, 18 Jun 2018 16:07:46 +0530 | |
changeset 38377 | fb4813304c5f |
parent 37726 | 0c184ca594bb |
child 39458 | dc61a67c1fc0 |
permissions | -rw-r--r-- |
29865
a1092e2d70a3
help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
1 |
The Mercurial wire protocol is a request-response based protocol |
a1092e2d70a3
help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
2 |
with multiple wire representations. |
a1092e2d70a3
help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
3 |
|
a1092e2d70a3
help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
4 |
Each request is modeled as a command name, a dictionary of arguments, and |
a1092e2d70a3
help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
5 |
optional raw input. Command arguments and their types are intrinsic |
a1092e2d70a3
help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
6 |
properties of commands. So is the response type of the command. This means |
a1092e2d70a3
help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
7 |
clients can't always send arbitrary arguments to servers and servers can't |
a1092e2d70a3
help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
8 |
return multiple response types. |
a1092e2d70a3
help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
9 |
|
a1092e2d70a3
help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
10 |
The protocol is synchronous and does not support multiplexing (concurrent |
a1092e2d70a3
help: internals topic for wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
diff
changeset
|
11 |
commands). |
29866
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
12 |
|
36014
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
13 |
Handshake |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
14 |
========= |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
15 |
|
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
16 |
It is required or common for clients to perform a *handshake* when connecting |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
17 |
to a server. The handshake serves the following purposes: |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
18 |
|
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
19 |
* Negotiating protocol/transport level options |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
20 |
* Allows the client to learn about server capabilities to influence |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
21 |
future requests |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
22 |
* Ensures the underlying transport channel is in a *clean* state |
29866
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
23 |
|
36014
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
24 |
An important goal of the handshake is to allow clients to use more modern |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
25 |
wire protocol features. By default, clients must assume they are talking |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
26 |
to an old version of Mercurial server (possibly even the very first |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
27 |
implementation). So, clients should not attempt to call or utilize modern |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
28 |
wire protocol features until they have confirmation that the server |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
29 |
supports them. The handshake implementation is designed to allow both |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
30 |
ends to utilize the latest set of features and capabilities with as |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
31 |
few round trips as possible. |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
32 |
|
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
33 |
The handshake mechanism varies by transport and protocol and is documented |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
34 |
in the sections below. |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
35 |
|
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
36 |
HTTP Protocol |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
37 |
============= |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
38 |
|
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
39 |
Handshake |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
40 |
--------- |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
41 |
|
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
42 |
The client sends a ``capabilities`` command request (``?cmd=capabilities``) |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
43 |
as soon as HTTP requests may be issued. |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
44 |
|
37557
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
45 |
By default, the server responds with a version 1 capabilities string, which |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
46 |
the client parses to learn about the server's abilities. The ``Content-Type`` |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
47 |
for this response is ``application/mercurial-0.1`` or |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
48 |
``application/mercurial-0.2`` depending on whether the client advertised |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
49 |
support for version ``0.2`` in its request. (Clients aren't supposed to |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
50 |
advertise support for ``0.2`` until the capabilities response indicates |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
51 |
the server's support for that media type. However, a client could |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
52 |
conceivably cache this metadata and issue the capabilities request in such |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
53 |
a way to elicit an ``application/mercurial-0.2`` response.) |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
54 |
|
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
55 |
Clients wishing to switch to a newer API service may send an |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
56 |
``X-HgUpgrade-<X>`` header containing a space-delimited list of API service |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
57 |
names the client is capable of speaking. The request MUST also include an |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
58 |
``X-HgProto-<X>`` header advertising a known serialization format for the |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
59 |
response. ``cbor`` is currently the only defined serialization format. |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
60 |
|
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
61 |
If the request contains these headers, the response ``Content-Type`` MAY |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
62 |
be for a different media type. e.g. ``application/mercurial-cbor`` if the |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
63 |
client advertises support for CBOR. |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
64 |
|
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
65 |
The response MUST be deserializable to a map with the following keys: |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
66 |
|
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
67 |
apibase |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
68 |
URL path to API services, relative to the repository root. e.g. ``api/``. |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
69 |
|
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
70 |
apis |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
71 |
A map of API service names to API descriptors. An API descriptor contains |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
72 |
more details about that API. In the case of the HTTP Version 2 Transport, |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
73 |
it will be the normal response to a ``capabilities`` command. |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
74 |
|
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
75 |
Only the services advertised by the client that are also available on |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
76 |
the server are advertised. |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
77 |
|
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
78 |
v1capabilities |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
79 |
The capabilities string that would be returned by a version 1 response. |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
80 |
|
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
81 |
The client can then inspect the server-advertised APIs and decide which |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
82 |
API to use, including continuing to use the HTTP Version 1 Transport. |
36014
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
83 |
|
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
84 |
HTTP Version 1 Transport |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
85 |
------------------------ |
29866
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
86 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
87 |
Commands are issued as HTTP/1.0 or HTTP/1.1 requests. Commands are |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
88 |
sent to the base URL of the repository with the command name sent in |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
89 |
the ``cmd`` query string parameter. e.g. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
90 |
``https://example.com/repo?cmd=capabilities``. The HTTP method is ``GET`` |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
91 |
or ``POST`` depending on the command and whether there is a request |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
92 |
body. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
93 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
94 |
Command arguments can be sent multiple ways. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
95 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
96 |
The simplest is part of the URL query string using ``x-www-form-urlencoded`` |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
97 |
encoding (see Python's ``urllib.urlencode()``. However, many servers impose |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
98 |
length limitations on the URL. So this mechanism is typically only used if |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
99 |
the server doesn't support other mechanisms. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
100 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
101 |
If the server supports the ``httpheader`` capability, command arguments can |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
102 |
be sent in HTTP request headers named ``X-HgArg-<N>`` where ``<N>`` is an |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
103 |
integer starting at 1. A ``x-www-form-urlencoded`` representation of the |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
104 |
arguments is obtained. This full string is then split into chunks and sent |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
105 |
in numbered ``X-HgArg-<N>`` headers. The maximum length of each HTTP header |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
106 |
is defined by the server in the ``httpheader`` capability value, which defaults |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
107 |
to ``1024``. The server reassembles the encoded arguments string by |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
108 |
concatenating the ``X-HgArg-<N>`` headers then URL decodes them into a |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
109 |
dictionary. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
110 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
111 |
The list of ``X-HgArg-<N>`` headers should be added to the ``Vary`` request |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
112 |
header to instruct caches to take these headers into consideration when caching |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
113 |
requests. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
114 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
115 |
If the server supports the ``httppostargs`` capability, the client |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
116 |
may send command arguments in the HTTP request body as part of an |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
117 |
HTTP POST request. The command arguments will be URL encoded just like |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
118 |
they would for sending them via HTTP headers. However, no splitting is |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
119 |
performed: the raw arguments are included in the HTTP request body. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
120 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
121 |
The client sends a ``X-HgArgs-Post`` header with the string length of the |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
122 |
encoded arguments data. Additional data may be included in the HTTP |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
123 |
request body immediately following the argument data. The offset of the |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
124 |
non-argument data is defined by the ``X-HgArgs-Post`` header. The |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
125 |
``X-HgArgs-Post`` header is not required if there is no argument data. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
126 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
127 |
Additional command data can be sent as part of the HTTP request body. The |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
128 |
default ``Content-Type`` when sending data is ``application/mercurial-0.1``. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
129 |
A ``Content-Length`` header is currently always sent. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
130 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
131 |
Example HTTP requests:: |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
132 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
133 |
GET /repo?cmd=capabilities |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
134 |
X-HgArg-1: foo=bar&baz=hello%20world |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
135 |
|
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
136 |
The request media type should be chosen based on server support. If the |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
137 |
``httpmediatype`` server capability is present, the client should send |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
138 |
the newest mutually supported media type. If this capability is absent, |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
139 |
the client must assume the server only supports the |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
140 |
``application/mercurial-0.1`` media type. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
141 |
|
29866
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
142 |
The ``Content-Type`` HTTP response header identifies the response as coming |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
143 |
from Mercurial and can also be used to signal an error has occurred. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
144 |
|
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
145 |
The ``application/mercurial-*`` media types indicate a generic Mercurial |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
146 |
data type. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
147 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
148 |
The ``application/mercurial-0.1`` media type is raw Mercurial data. It is the |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
149 |
predecessor of the format below. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
150 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
151 |
The ``application/mercurial-0.2`` media type is compression framed Mercurial |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
152 |
data. The first byte of the payload indicates the length of the compression |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
153 |
format identifier that follows. Next are N bytes indicating the compression |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
154 |
format. e.g. ``zlib``. The remaining bytes are compressed according to that |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
155 |
compression format. The decompressed data behaves the same as with |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
156 |
``application/mercurial-0.1``. |
29866
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
157 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
158 |
The ``application/hg-error`` media type indicates a generic error occurred. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
159 |
The content of the HTTP response body typically holds text describing the |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
160 |
error. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
161 |
|
37557
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
162 |
The ``application/mercurial-cbor`` media type indicates a CBOR payload |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
163 |
and should be interpreted as identical to ``application/cbor``. |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
164 |
|
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
165 |
Behavior of media types is further described in the ``Content Negotiation`` |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
166 |
section below. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
167 |
|
29866
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
168 |
Clients should issue a ``User-Agent`` request header that identifies the client. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
169 |
The server should not use the ``User-Agent`` for feature detection. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
170 |
|
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
171 |
A command returning a ``string`` response issues a |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
172 |
``application/mercurial-0.*`` media type and the HTTP response body contains |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
173 |
the raw string value (after compression decoding, if used). A |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
174 |
``Content-Length`` header is typically issued, but not required. |
29866
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
175 |
|
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
176 |
A command returning a ``stream`` response issues a |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
177 |
``application/mercurial-0.*`` media type and the HTTP response is typically |
29866
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
178 |
using *chunked transfer* (``Transfer-Encoding: chunked``). |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
179 |
|
37050
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
180 |
HTTP Version 2 Transport |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
181 |
------------------------ |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
182 |
|
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
183 |
**Experimental - feature under active development** |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
184 |
|
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
185 |
Version 2 of the HTTP protocol is exposed under the ``/api/*`` URL space. |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
186 |
It's final API name is not yet formalized. |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
187 |
|
37051
fc5e261915b9
wireproto: require POST for all HTTPv2 requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
188 |
Commands are triggered by sending HTTP POST requests against URLs of the |
37050
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
189 |
form ``<permission>/<command>``, where ``<permission>`` is ``ro`` or |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
190 |
``rw``, meaning read-only and read-write, respectively and ``<command>`` |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
191 |
is a named wire protocol command. |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
192 |
|
37051
fc5e261915b9
wireproto: require POST for all HTTPv2 requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
193 |
Non-POST request methods MUST be rejected by the server with an HTTP |
fc5e261915b9
wireproto: require POST for all HTTPv2 requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
194 |
405 response. |
fc5e261915b9
wireproto: require POST for all HTTPv2 requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
195 |
|
37050
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
196 |
Commands that modify repository state in meaningful ways MUST NOT be |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
197 |
exposed under the ``ro`` URL prefix. All available commands MUST be |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
198 |
available under the ``rw`` URL prefix. |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
199 |
|
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
200 |
Server adminstrators MAY implement blanket HTTP authentication keyed |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
201 |
off the URL prefix. For example, a server may require authentication |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
202 |
for all ``rw/*`` URLs and let unauthenticated requests to ``ro/*`` |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
203 |
URL proceed. A server MAY issue an HTTP 401, 403, or 407 response |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
204 |
in accordance with RFC 7235. Clients SHOULD recognize the HTTP Basic |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
205 |
(RFC 7617) and Digest (RFC 7616) authentication schemes. Clients SHOULD |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
206 |
make an attempt to recognize unknown schemes using the |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
207 |
``WWW-Authenticate`` response header on a 401 response, as defined by |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
208 |
RFC 7235. |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
209 |
|
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
210 |
Read-only commands are accessible under ``rw/*`` URLs so clients can |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
211 |
signal the intent of the operation very early in the connection |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
212 |
lifecycle. For example, a ``push`` operation - which consists of |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
213 |
various read-only commands mixed with at least one read-write command - |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
214 |
can perform all commands against ``rw/*`` URLs so that any server-side |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
215 |
authentication requirements are discovered upon attempting the first |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
216 |
command - not potentially several commands into the exchange. This |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
217 |
allows clients to fail faster or prompt for credentials as soon as the |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
218 |
exchange takes place. This provides a better end-user experience. |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
219 |
|
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
220 |
Requests to unknown commands or URLS result in an HTTP 404. |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
221 |
TODO formally define response type, how error is communicated, etc. |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36015
diff
changeset
|
222 |
|
37054
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
223 |
HTTP request and response bodies use the *Unified Frame-Based Protocol* |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
224 |
(defined below) for media exchange. The entirety of the HTTP message |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
225 |
body is 0 or more frames as defined by this protocol. |
37053
37d7a1d18b97
wireproto: define content negotiation for HTTPv2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
226 |
|
37d7a1d18b97
wireproto: define content negotiation for HTTPv2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
227 |
Clients and servers MUST advertise the ``TBD`` media type via the |
37d7a1d18b97
wireproto: define content negotiation for HTTPv2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
228 |
``Content-Type`` request and response headers. In addition, clients MUST |
37d7a1d18b97
wireproto: define content negotiation for HTTPv2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
229 |
advertise this media type value in their ``Accept`` request header in all |
37d7a1d18b97
wireproto: define content negotiation for HTTPv2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
230 |
requests. |
37054
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
231 |
TODO finalize the media type. For now, it is defined in wireprotoserver.py. |
37053
37d7a1d18b97
wireproto: define content negotiation for HTTPv2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
232 |
|
37d7a1d18b97
wireproto: define content negotiation for HTTPv2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
233 |
Servers receiving requests without an ``Accept`` header SHOULD respond with |
37d7a1d18b97
wireproto: define content negotiation for HTTPv2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
234 |
an HTTP 406. |
37d7a1d18b97
wireproto: define content negotiation for HTTPv2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
235 |
|
37d7a1d18b97
wireproto: define content negotiation for HTTPv2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
236 |
Servers receiving requests with an invalid ``Content-Type`` header SHOULD |
37d7a1d18b97
wireproto: define content negotiation for HTTPv2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
237 |
respond with an HTTP 415. |
37d7a1d18b97
wireproto: define content negotiation for HTTPv2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
238 |
|
37062
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
239 |
The command to run is specified in the POST payload as defined by the |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
240 |
*Unified Frame-Based Protocol*. This is redundant with data already |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
241 |
encoded in the URL. This is by design, so server operators can have |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
242 |
better understanding about server activity from looking merely at |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
243 |
HTTP access logs. |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
244 |
|
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
245 |
In most circumstances, the command specified in the URL MUST match |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
246 |
the command specified in the frame-based payload or the server will |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
247 |
respond with an error. The exception to this is the special |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
248 |
``multirequest`` URL. (See below.) In addition, HTTP requests |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
249 |
are limited to one command invocation. The exception is the special |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
250 |
``multirequest`` URL. |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
251 |
|
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
252 |
The ``multirequest`` command endpoints (``ro/multirequest`` and |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
253 |
``rw/multirequest``) are special in that they allow the execution of |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
254 |
*any* command and allow the execution of multiple commands. If the |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
255 |
HTTP request issues multiple commands across multiple frames, all |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
256 |
issued commands will be processed by the server. Per the defined |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
257 |
behavior of the *Unified Frame-Based Protocol*, commands may be |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
258 |
issued interleaved and responses may come back in a different order |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
259 |
than they were issued. Clients MUST be able to deal with this. |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
260 |
|
36014
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
261 |
SSH Protocol |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
262 |
============ |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
263 |
|
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
264 |
Handshake |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
265 |
--------- |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
266 |
|
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
267 |
For all clients, the handshake consists of the client sending 1 or more |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
268 |
commands to the server using version 1 of the transport. Servers respond |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
269 |
to commands they know how to respond to and send an empty response (``0\n``) |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
270 |
for unknown commands (per standard behavior of version 1 of the transport). |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
271 |
Clients then typically look for a response to the newest sent command to |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
272 |
determine which transport version to use and what the available features for |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
273 |
the connection and server are. |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
274 |
|
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
275 |
Preceding any response from client-issued commands, the server may print |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
276 |
non-protocol output. It is common for SSH servers to print banners, message |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
277 |
of the day announcements, etc when clients connect. It is assumed that any |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
278 |
such *banner* output will precede any Mercurial server output. So clients |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
279 |
must be prepared to handle server output on initial connect that isn't |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
280 |
in response to any client-issued command and doesn't conform to Mercurial's |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
281 |
wire protocol. This *banner* output should only be on stdout. However, |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
282 |
some servers may send output on stderr. |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
283 |
|
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
284 |
Pre 0.9.1 clients issue a ``between`` command with the ``pairs`` argument |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
285 |
having the value |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
286 |
``0000000000000000000000000000000000000000-0000000000000000000000000000000000000000``. |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
287 |
|
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
288 |
The ``between`` command has been supported since the original Mercurial |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
289 |
SSH server. Requesting the empty range will return a ``\n`` string response, |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
290 |
which will be encoded as ``1\n\n`` (value length of ``1`` followed by a newline |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
291 |
followed by the value, which happens to be a newline). |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
292 |
|
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
293 |
For pre 0.9.1 clients and all servers, the exchange looks like:: |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
294 |
|
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
295 |
c: between\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
296 |
c: pairs 81\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
297 |
c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
298 |
s: 1\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
299 |
s: \n |
29866
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
300 |
|
36014
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
301 |
0.9.1+ clients send a ``hello`` command (with no arguments) before the |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
302 |
``between`` command. The response to this command allows clients to |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
303 |
discover server capabilities and settings. |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
304 |
|
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
305 |
An example exchange between 0.9.1+ clients and a ``hello`` aware server looks |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
306 |
like:: |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
307 |
|
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
308 |
c: hello\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
309 |
c: between\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
310 |
c: pairs 81\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
311 |
c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
312 |
s: 324\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
313 |
s: capabilities: lookup changegroupsubset branchmap pushkey known getbundle ...\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
314 |
s: 1\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
315 |
s: \n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
316 |
|
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
317 |
And a similar scenario but with servers sending a banner on connect:: |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
318 |
|
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
319 |
c: hello\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
320 |
c: between\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
321 |
c: pairs 81\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
322 |
c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
323 |
s: welcome to the server\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
324 |
s: if you find any issues, email someone@somewhere.com\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
325 |
s: 324\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
326 |
s: capabilities: lookup changegroupsubset branchmap pushkey known getbundle ...\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
327 |
s: 1\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
328 |
s: \n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
329 |
|
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
330 |
Note that output from the ``hello`` command is terminated by a ``\n``. This is |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
331 |
part of the response payload and not part of the wire protocol adding a newline |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
332 |
after responses. In other words, the length of the response contains the |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
333 |
trailing ``\n``. |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
334 |
|
36015
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
335 |
Clients supporting version 2 of the SSH transport send a line beginning |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
336 |
with ``upgrade`` before the ``hello`` and ``between`` commands. The line |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
337 |
(which isn't a well-formed command line because it doesn't consist of a |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
338 |
single command name) serves to both communicate the client's intent to |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
339 |
switch to transport version 2 (transports are version 1 by default) as |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
340 |
well as to advertise the client's transport-level capabilities so the |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
341 |
server may satisfy that request immediately. |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
342 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
343 |
The upgrade line has the form: |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
344 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
345 |
upgrade <token> <transport capabilities> |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
346 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
347 |
That is the literal string ``upgrade`` followed by a space, followed by |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
348 |
a randomly generated string, followed by a space, followed by a string |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
349 |
denoting the client's transport capabilities. |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
350 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
351 |
The token can be anything. However, a random UUID is recommended. (Use |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
352 |
of version 4 UUIDs is recommended because version 1 UUIDs can leak the |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
353 |
client's MAC address.) |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
354 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
355 |
The transport capabilities string is a URL/percent encoded string |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
356 |
containing key-value pairs defining the client's transport-level |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
357 |
capabilities. The following capabilities are defined: |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
358 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
359 |
proto |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
360 |
A comma-delimited list of transport protocol versions the client |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
361 |
supports. e.g. ``ssh-v2``. |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
362 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
363 |
If the server does not recognize the ``upgrade`` line, it should issue |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
364 |
an empty response and continue processing the ``hello`` and ``between`` |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
365 |
commands. Here is an example handshake between a version 2 aware client |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
366 |
and a non version 2 aware server: |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
367 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
368 |
c: upgrade 2e82ab3f-9ce3-4b4e-8f8c-6fd1c0e9e23a proto=ssh-v2 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
369 |
c: hello\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
370 |
c: between\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
371 |
c: pairs 81\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
372 |
c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
373 |
s: 0\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
374 |
s: 324\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
375 |
s: capabilities: lookup changegroupsubset branchmap pushkey known getbundle ...\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
376 |
s: 1\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
377 |
s: \n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
378 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
379 |
(The initial ``0\n`` line from the server indicates an empty response to |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
380 |
the unknown ``upgrade ..`` command/line.) |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
381 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
382 |
If the server recognizes the ``upgrade`` line and is willing to satisfy that |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
383 |
upgrade request, it replies to with a payload of the following form: |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
384 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
385 |
upgraded <token> <transport name>\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
386 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
387 |
This line is the literal string ``upgraded``, a space, the token that was |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
388 |
specified by the client in its ``upgrade ...`` request line, a space, and the |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
389 |
name of the transport protocol that was chosen by the server. The transport |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
390 |
name MUST match one of the names the client specified in the ``proto`` field |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
391 |
of its ``upgrade ...`` request line. |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
392 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
393 |
If a server issues an ``upgraded`` response, it MUST also read and ignore |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
394 |
the lines associated with the ``hello`` and ``between`` command requests |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
395 |
that were issued by the server. It is assumed that the negotiated transport |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
396 |
will respond with equivalent requested information following the transport |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
397 |
handshake. |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
398 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
399 |
All data following the ``\n`` terminating the ``upgraded`` line is the |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
400 |
domain of the negotiated transport. It is common for the data immediately |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
401 |
following to contain additional metadata about the state of the transport and |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
402 |
the server. However, this isn't strictly speaking part of the transport |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
403 |
handshake and isn't covered by this section. |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
404 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
405 |
Here is an example handshake between a version 2 aware client and a version |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
406 |
2 aware server: |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
407 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
408 |
c: upgrade 2e82ab3f-9ce3-4b4e-8f8c-6fd1c0e9e23a proto=ssh-v2 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
409 |
c: hello\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
410 |
c: between\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
411 |
c: pairs 81\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
412 |
c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
413 |
s: upgraded 2e82ab3f-9ce3-4b4e-8f8c-6fd1c0e9e23a ssh-v2\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
414 |
s: <additional transport specific data> |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
415 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
416 |
The client-issued token that is echoed in the response provides a more |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
417 |
resilient mechanism for differentiating *banner* output from Mercurial |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
418 |
output. In version 1, properly formatted banner output could get confused |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
419 |
for Mercurial server output. By submitting a randomly generated token |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
420 |
that is then present in the response, the client can look for that token |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
421 |
in response lines and have reasonable certainty that the line did not |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
422 |
originate from a *banner* message. |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
423 |
|
36014
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
424 |
SSH Version 1 Transport |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
425 |
----------------------- |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
426 |
|
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
427 |
The SSH transport (version 1) is a custom text-based protocol suitable for |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
428 |
use over any bi-directional stream transport. It is most commonly used with |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
429 |
SSH. |
29866
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
430 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
431 |
A SSH transport server can be started with ``hg serve --stdio``. The stdin, |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
432 |
stderr, and stdout file descriptors of the started process are used to exchange |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
433 |
data. When Mercurial connects to a remote server over SSH, it actually starts |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
434 |
a ``hg serve --stdio`` process on the remote server. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
435 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
436 |
Commands are issued by sending the command name followed by a trailing newline |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
437 |
``\n`` to the server. e.g. ``capabilities\n``. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
438 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
439 |
Command arguments are sent in the following format:: |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
440 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
441 |
<argument> <length>\n<value> |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
442 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
443 |
That is, the argument string name followed by a space followed by the |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
444 |
integer length of the value (expressed as a string) followed by a newline |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
445 |
(``\n``) followed by the raw argument value. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
446 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
447 |
Dictionary arguments are encoded differently:: |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
448 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
449 |
<argument> <# elements>\n |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
450 |
<key1> <length1>\n<value1> |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
451 |
<key2> <length2>\n<value2> |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
452 |
... |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
453 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
454 |
Non-argument data is sent immediately after the final argument value. It is |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
455 |
encoded in chunks:: |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
456 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
457 |
<length>\n<data> |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
458 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
459 |
Each command declares a list of supported arguments and their types. If a |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
460 |
client sends an unknown argument to the server, the server should abort |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
461 |
immediately. The special argument ``*`` in a command's definition indicates |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
462 |
that all argument names are allowed. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
463 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
464 |
The definition of supported arguments and types is initially made when a |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
465 |
new command is implemented. The client and server must initially independently |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
466 |
agree on the arguments and their types. This initial set of arguments can be |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
467 |
supplemented through the presence of *capabilities* advertised by the server. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
468 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
469 |
Each command has a defined expected response type. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
470 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
471 |
A ``string`` response type is a length framed value. The response consists of |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
472 |
the string encoded integer length of a value followed by a newline (``\n``) |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
473 |
followed by the value. Empty values are allowed (and are represented as |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
474 |
``0\n``). |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
475 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
476 |
A ``stream`` response type consists of raw bytes of data. There is no framing. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
477 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
478 |
A generic error response type is also supported. It consists of a an error |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
479 |
message written to ``stderr`` followed by ``\n-\n``. In addition, ``\n`` is |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
480 |
written to ``stdout``. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
481 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
482 |
If the server receives an unknown command, it will send an empty ``string`` |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
483 |
response. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
484 |
|
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
485 |
The server terminates if it receives an empty command (a ``\n`` character). |
29867
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
486 |
|
37393
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
487 |
If the server announces support for the ``protocaps`` capability, the client |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
488 |
should issue a ``protocaps`` command after the initial handshake to annonunce |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
489 |
its own capabilities. The client capabilities are persistent. |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
490 |
|
36015
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
491 |
SSH Version 2 Transport |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
492 |
----------------------- |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
493 |
|
37054
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
494 |
**Experimental and under development** |
36015
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
495 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
496 |
Version 2 of the SSH transport behaves identically to version 1 of the SSH |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
497 |
transport with the exception of handshake semantics. See above for how |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
498 |
version 2 of the SSH transport is negotiated. |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
499 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
500 |
Immediately following the ``upgraded`` line signaling a switch to version |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
501 |
2 of the SSH protocol, the server automatically sends additional details |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
502 |
about the capabilities of the remote server. This has the form: |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
503 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
504 |
<integer length of value>\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
505 |
capabilities: ...\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
506 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
507 |
e.g. |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
508 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
509 |
s: upgraded 2e82ab3f-9ce3-4b4e-8f8c-6fd1c0e9e23a ssh-v2\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
510 |
s: 240\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
511 |
s: capabilities: known getbundle batch ...\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
512 |
|
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
513 |
Following capabilities advertisement, the peers communicate using version |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
514 |
1 of the SSH transport. |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
36014
diff
changeset
|
515 |
|
37054
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
516 |
Unified Frame-Based Protocol |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
517 |
============================ |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
518 |
|
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
519 |
**Experimental and under development** |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
520 |
|
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
521 |
The *Unified Frame-Based Protocol* is a communications protocol between |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
522 |
Mercurial peers. The protocol aims to be mostly transport agnostic |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
523 |
(works similarly on HTTP, SSH, etc). |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
524 |
|
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
525 |
To operate the protocol, a bi-directional, half-duplex pipe supporting |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
526 |
ordered sends and receives is required. That is, each peer has one pipe |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
527 |
for sending data and another for receiving. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
528 |
|
37288
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
529 |
All data is read and written in atomic units called *frames*. These |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
530 |
are conceptually similar to TCP packets. Higher-level functionality |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
531 |
is built on the exchange and processing of frames. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
532 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
533 |
All frames are associated with a *stream*. A *stream* provides a |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
534 |
unidirectional grouping of frames. Streams facilitate two goals: |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
535 |
content encoding and parallelism. There is a dedicated section on |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
536 |
streams below. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
537 |
|
37054
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
538 |
The protocol is request-response based: the client issues requests to |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
539 |
the server, which issues replies to those requests. Server-initiated |
37060
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
540 |
messaging is not currently supported, but this specification carves |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
541 |
out room to implement it. |
37054
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
542 |
|
37060
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
543 |
All frames are associated with a numbered request. Frames can thus |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
544 |
be logically grouped by their request ID. |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
545 |
|
37288
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
546 |
Frames begin with an 8 octet header followed by a variable length |
37054
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
547 |
payload:: |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
548 |
|
37288
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
549 |
+------------------------------------------------+ |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
550 |
| Length (24) | |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
551 |
+--------------------------------+---------------+ |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
552 |
| Request ID (16) | Stream ID (8) | |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
553 |
+------------------+-------------+---------------+ |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
554 |
| Stream Flags (8) | |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
555 |
+-----------+------+ |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
556 |
| Type (4) | |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
557 |
+-----------+ |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
558 |
| Flags (4) | |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
559 |
+===========+===================================================| |
37054
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
560 |
| Frame Payload (0...) ... |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
561 |
+---------------------------------------------------------------+ |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
562 |
|
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
563 |
The length of the frame payload is expressed as an unsigned 24 bit |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
564 |
little endian integer. Values larger than 65535 MUST NOT be used unless |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
565 |
given permission by the server as part of the negotiated capabilities |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
566 |
during the handshake. The frame header is not part of the advertised |
37288
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
567 |
frame length. The payload length is the over-the-wire length. If there |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
568 |
is content encoding applied to the payload as part of the frame's stream, |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
569 |
the length is the output of that content encoding, not the input. |
37054
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
570 |
|
37060
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
571 |
The 16-bit ``Request ID`` field denotes the integer request identifier, |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
572 |
stored as an unsigned little endian integer. Odd numbered requests are |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
573 |
client-initiated. Even numbered requests are server-initiated. This |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
574 |
refers to where the *request* was initiated - not where the *frame* was |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
575 |
initiated, so servers will send frames with odd ``Request ID`` in |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
576 |
response to client-initiated requests. Implementations are advised to |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
577 |
start ordering request identifiers at ``1`` and ``0``, increment by |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
578 |
``2``, and wrap around if all available numbers have been exhausted. |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
579 |
|
37288
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
580 |
The 8-bit ``Stream ID`` field denotes the stream that the frame is |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
581 |
associated with. Frames belonging to a stream may have content |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
582 |
encoding applied and the receiver may need to decode the raw frame |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
583 |
payload to obtain the original data. Odd numbered IDs are |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
584 |
client-initiated. Even numbered IDs are server-initiated. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
585 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
586 |
The 8-bit ``Stream Flags`` field defines stream processing semantics. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
587 |
See the section on streams below. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
588 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
589 |
The 4-bit ``Type`` field denotes the type of frame being sent. |
37054
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
590 |
|
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
591 |
The 4-bit ``Flags`` field defines special, per-type attributes for |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
592 |
the frame. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
593 |
|
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
594 |
The sections below define the frame types and their behavior. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
595 |
|
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
596 |
Command Request (``0x01``) |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
597 |
-------------------------- |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
598 |
|
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
599 |
This frame contains a request to run a command. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
600 |
|
37292
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
601 |
The payload consists of a CBOR map defining the command request. The |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
602 |
bytestring keys of that map are: |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
603 |
|
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
604 |
name |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
605 |
Name of the command that should be executed (bytestring). |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
606 |
args |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
607 |
Map of bytestring keys to various value types containing the named |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
608 |
arguments to this command. |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
609 |
|
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
610 |
Each command defines its own set of argument names and their expected |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
611 |
types. |
37054
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
612 |
|
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
613 |
This frame type MUST ONLY be sent from clients to servers: it is illegal |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
614 |
for a server to send this frame to a client. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
615 |
|
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
616 |
The following flag values are defined for this type: |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
617 |
|
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
618 |
0x01 |
37292
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
619 |
New command request. When set, this frame represents the beginning |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
620 |
of a new request to run a command. The ``Request ID`` attached to this |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
621 |
frame MUST NOT be active. |
37054
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
622 |
0x02 |
37292
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
623 |
Command request continuation. When set, this frame is a continuation |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
624 |
from a previous command request frame for its ``Request ID``. This |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
625 |
flag is set when the CBOR data for a command request does not fit |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
626 |
in a single frame. |
37054
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
627 |
0x04 |
37292
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
628 |
Additional frames expected. When set, the command request didn't fit |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
629 |
into a single frame and additional CBOR data follows in a subsequent |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
630 |
frame. |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
631 |
0x08 |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
632 |
Command data frames expected. When set, command data frames are |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
633 |
expected to follow the final command request frame for this request. |
37054
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
634 |
|
37292
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
635 |
``0x01`` MUST be set on the initial command request frame for a |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
636 |
``Request ID``. |
37054
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
637 |
|
37292
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
638 |
``0x01`` or ``0x02`` MUST be set to indicate this frame's role in |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
639 |
a series of command request frames. |
37054
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
640 |
|
37723
e8fba6d578f0
wireprotov2: change frame type value for command data
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37722
diff
changeset
|
641 |
If command data frames are to be sent, ``0x08`` MUST be set on ALL |
37292
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
642 |
command request frames. |
37054
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
643 |
|
37723
e8fba6d578f0
wireprotov2: change frame type value for command data
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37722
diff
changeset
|
644 |
Command Data (``0x02``) |
37054
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
645 |
----------------------- |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
646 |
|
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
647 |
This frame contains raw data for a command. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
648 |
|
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
649 |
Most commands can be executed by specifying arguments. However, |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
650 |
arguments have an upper bound to their length. For commands that |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
651 |
accept data that is beyond this length or whose length isn't known |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
652 |
when the command is initially sent, they will need to stream |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
653 |
arbitrary data to the server. This frame type facilitates the sending |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
654 |
of this data. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
655 |
|
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
656 |
The payload of this frame type consists of a stream of raw data to be |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
657 |
consumed by the command handler on the server. The format of the data |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
658 |
is command specific. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
659 |
|
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
660 |
The following flag values are defined for this type: |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
661 |
|
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
662 |
0x01 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
663 |
Command data continuation. When set, the data for this command |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
664 |
continues into a subsequent frame. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
665 |
|
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
666 |
0x02 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
667 |
End of data. When set, command data has been fully sent to the |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
668 |
server. The command has been fully issued and no new data for this |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
669 |
command will be sent. The next frame will belong to a new command. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
670 |
|
37724
deff7cf7eefd
wireprotov2: change frame type and name for command response
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37723
diff
changeset
|
671 |
Command Response Data (``0x03``) |
deff7cf7eefd
wireprotov2: change frame type and name for command response
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37723
diff
changeset
|
672 |
-------------------------------- |
37058
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37054
diff
changeset
|
673 |
|
37722
89a16704114c
wireprotov2: define response data as CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37657
diff
changeset
|
674 |
This frame contains response data to an issued command. |
89a16704114c
wireprotov2: define response data as CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37657
diff
changeset
|
675 |
|
37725
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
676 |
Response data ALWAYS consists of a series of 1 or more CBOR encoded |
37722
89a16704114c
wireprotov2: define response data as CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37657
diff
changeset
|
677 |
values. A CBOR value may be using indefinite length encoding. And the |
89a16704114c
wireprotov2: define response data as CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37657
diff
changeset
|
678 |
bytes constituting the value may span several frames. |
37058
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37054
diff
changeset
|
679 |
|
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37054
diff
changeset
|
680 |
The following flag values are defined for this type: |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37054
diff
changeset
|
681 |
|
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37054
diff
changeset
|
682 |
0x01 |
37299
e9aadee698cf
wireproto: add frame flag to denote payloads as CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37292
diff
changeset
|
683 |
Data continuation. When set, an additional frame containing response data |
e9aadee698cf
wireproto: add frame flag to denote payloads as CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37292
diff
changeset
|
684 |
will follow. |
37058
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37054
diff
changeset
|
685 |
0x02 |
37299
e9aadee698cf
wireproto: add frame flag to denote payloads as CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37292
diff
changeset
|
686 |
End of data. When set, the response data has been fully sent and |
37058
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37054
diff
changeset
|
687 |
no additional frames for this response will be sent. |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37054
diff
changeset
|
688 |
|
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37054
diff
changeset
|
689 |
The ``0x01`` flag is mutually exclusive with the ``0x02`` flag. |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37054
diff
changeset
|
690 |
|
37726
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
691 |
Error Occurred (``0x05``) |
37058
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37054
diff
changeset
|
692 |
------------------------- |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37054
diff
changeset
|
693 |
|
37726
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
694 |
Some kind of error occurred. |
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
695 |
|
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
696 |
There are 3 general kinds of failures that can occur: |
37058
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37054
diff
changeset
|
697 |
|
37726
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
698 |
* Command error encountered before any response issued |
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
699 |
* Command error encountered after a response was issued |
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
700 |
* Protocol or stream level error |
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
701 |
|
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
702 |
This frame type is used to capture the latter cases. (The general |
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
703 |
command error case is handled by the leading CBOR map in |
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
704 |
``Command Response`` frames.) |
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
705 |
|
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
706 |
The payload of this frame contains a CBOR map detailing the error. That |
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
707 |
map has the following bytestring keys: |
37058
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37054
diff
changeset
|
708 |
|
37726
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
709 |
type |
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
710 |
(bytestring) The overall type of error encountered. Can be one of the |
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
711 |
following values: |
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
712 |
|
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
713 |
protocol |
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
714 |
A protocol-level error occurred. This typically means someone |
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
715 |
is violating the framing protocol semantics and the server is |
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
716 |
refusing to proceed. |
37058
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37054
diff
changeset
|
717 |
|
37726
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
718 |
server |
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
719 |
A server-level error occurred. This typically indicates some kind of |
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
720 |
logic error on the server, likely the fault of the server. |
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
721 |
|
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
722 |
command |
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
723 |
A command-level error, likely the fault of the client. |
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
724 |
|
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
725 |
message |
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
726 |
(array of maps) A richly formatted message that is intended for |
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
727 |
human consumption. See the ``Human Output Side-Channel`` frame |
0c184ca594bb
wireprotov2: change behavior of error frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37725
diff
changeset
|
728 |
section for a description of the format of this data structure. |
37058
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37054
diff
changeset
|
729 |
|
37063
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
730 |
Human Output Side-Channel (``0x06``) |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
731 |
------------------------------------ |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
732 |
|
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
733 |
This frame contains a message that is intended to be displayed to |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
734 |
people. Whereas most frames communicate machine readable data, this |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
735 |
frame communicates textual data that is intended to be shown to |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
736 |
humans. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
737 |
|
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
738 |
The frame consists of a series of *formatting requests*. Each formatting |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
739 |
request consists of a formatting string, arguments for that formatting |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
740 |
string, and labels to apply to that formatting string. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
741 |
|
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
742 |
A formatting string is a printf()-like string that allows variable |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
743 |
substitution within the string. Labels allow the rendered text to be |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
744 |
*decorated*. Assuming use of the canonical Mercurial code base, a |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
745 |
formatting string can be the input to the ``i18n._`` function. This |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
746 |
allows messages emitted from the server to be localized. So even if |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
747 |
the server has different i18n settings, people could see messages in |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
748 |
their *native* settings. Similarly, the use of labels allows |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
749 |
decorations like coloring and underlining to be applied using the |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
750 |
client's configured rendering settings. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
751 |
|
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
752 |
Formatting strings are similar to ``printf()`` strings or how |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
753 |
Python's ``%`` operator works. The only supported formatting sequences |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
754 |
are ``%s`` and ``%%``. ``%s`` will be replaced by whatever the string |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
755 |
at that position resolves to. ``%%`` will be replaced by ``%``. All |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
756 |
other 2-byte sequences beginning with ``%`` represent a literal |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
757 |
``%`` followed by that character. However, future versions of the |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
758 |
wire protocol reserve the right to allow clients to opt in to receiving |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
759 |
formatting strings with additional formatters, hence why ``%%`` is |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
760 |
required to represent the literal ``%``. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
761 |
|
37319
36d17f37db91
wireproto: convert human output frames to CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37299
diff
changeset
|
762 |
The frame payload consists of a CBOR array of CBOR maps. Each map |
36d17f37db91
wireproto: convert human output frames to CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37299
diff
changeset
|
763 |
defines an *atom* of text data to print. Each *atom* has the following |
36d17f37db91
wireproto: convert human output frames to CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37299
diff
changeset
|
764 |
bytestring keys: |
37063
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
765 |
|
37319
36d17f37db91
wireproto: convert human output frames to CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37299
diff
changeset
|
766 |
msg |
36d17f37db91
wireproto: convert human output frames to CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37299
diff
changeset
|
767 |
(bytestring) The formatting string. Content MUST be ASCII. |
36d17f37db91
wireproto: convert human output frames to CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37299
diff
changeset
|
768 |
args (optional) |
36d17f37db91
wireproto: convert human output frames to CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37299
diff
changeset
|
769 |
Array of bytestrings defining arguments to the formatting string. |
36d17f37db91
wireproto: convert human output frames to CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37299
diff
changeset
|
770 |
labels (optional) |
36d17f37db91
wireproto: convert human output frames to CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37299
diff
changeset
|
771 |
Array of bytestrings defining labels to apply to this atom. |
37132
aaabd709df72
wireproto: review fixups
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37063
diff
changeset
|
772 |
|
37063
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
773 |
All data to be printed MUST be encoded into a single frame: this frame |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
774 |
does not support spanning data across multiple frames. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
775 |
|
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
776 |
All textual data encoded in these frames is assumed to be line delimited. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
777 |
The last atom in the frame SHOULD end with a newline (``\n``). If it |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
778 |
doesn't, clients MAY add a newline to facilitate immediate printing. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37062
diff
changeset
|
779 |
|
37291
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
780 |
Progress Update (``0x07``) |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
781 |
-------------------------- |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
782 |
|
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
783 |
This frame holds the progress of an operation on the peer. Consumption |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
784 |
of these frames allows clients to display progress bars, estimated |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
785 |
completion times, etc. |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
786 |
|
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
787 |
Each frame defines the progress of a single operation on the peer. The |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
788 |
payload consists of a CBOR map with the following bytestring keys: |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
789 |
|
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
790 |
topic |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
791 |
Topic name (string) |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
792 |
pos |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
793 |
Current numeric position within the topic (integer) |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
794 |
total |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
795 |
Total/end numeric position of this topic (unsigned integer) |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
796 |
label (optional) |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
797 |
Unit label (string) |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
798 |
item (optional) |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
799 |
Item name (string) |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
800 |
|
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
801 |
Progress state is created when a frame is received referencing a |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
802 |
*topic* that isn't currently tracked. Progress tracking for that |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
803 |
*topic* is finished when a frame is received reporting the current |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
804 |
position of that topic as ``-1``. |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
805 |
|
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
806 |
Multiple *topics* may be active at any given time. |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
807 |
|
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
808 |
Rendering of progress information is not mandated or governed by this |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
809 |
specification: implementations MAY render progress information however |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
810 |
they see fit, including not at all. |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
811 |
|
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
812 |
The string data describing the topic SHOULD be static strings to |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
813 |
facilitate receivers localizing that string data. The emitter |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
814 |
MUST normalize all string data to valid UTF-8 and receivers SHOULD |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
815 |
validate that received data conforms to UTF-8. The topic name |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
816 |
SHOULD be ASCII. |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
817 |
|
37288
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
818 |
Stream Encoding Settings (``0x08``) |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
819 |
----------------------------------- |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
820 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
821 |
This frame type holds information defining the content encoding |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
822 |
settings for a *stream*. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
823 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
824 |
This frame type is likely consumed by the protocol layer and is not |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
825 |
passed on to applications. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
826 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
827 |
This frame type MUST ONLY occur on frames having the *Beginning of Stream* |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
828 |
``Stream Flag`` set. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
829 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
830 |
The payload of this frame defines what content encoding has (possibly) |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
831 |
been applied to the payloads of subsequent frames in this stream. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
832 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
833 |
The payload begins with an 8-bit integer defining the length of the |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
834 |
encoding *profile*, followed by the string name of that profile, which |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
835 |
must be an ASCII string. All bytes that follow can be used by that |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
836 |
profile for supplemental settings definitions. See the section below |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
837 |
on defined encoding profiles. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
838 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
839 |
Stream States and Flags |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
840 |
----------------------- |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
841 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
842 |
Streams can be in two states: *open* and *closed*. An *open* stream |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
843 |
is active and frames attached to that stream could arrive at any time. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
844 |
A *closed* stream is not active. If a frame attached to a *closed* |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
845 |
stream arrives, that frame MUST have an appropriate stream flag |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
846 |
set indicating beginning of stream. All streams are in the *closed* |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
847 |
state by default. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
848 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
849 |
The ``Stream Flags`` field denotes a set of bit flags for defining |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
850 |
the relationship of this frame within a stream. The following flags |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
851 |
are defined: |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
852 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
853 |
0x01 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
854 |
Beginning of stream. The first frame in the stream MUST set this |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
855 |
flag. When received, the ``Stream ID`` this frame is attached to |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
856 |
becomes ``open``. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
857 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
858 |
0x02 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
859 |
End of stream. The last frame in a stream MUST set this flag. When |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
860 |
received, the ``Stream ID`` this frame is attached to becomes |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
861 |
``closed``. Any content encoding context associated with this stream |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
862 |
can be destroyed after processing the payload of this frame. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
863 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
864 |
0x04 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
865 |
Apply content encoding. When set, any content encoding settings |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
866 |
defined by the stream should be applied when attempting to read |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
867 |
the frame. When not set, the frame payload isn't encoded. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
868 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
869 |
Streams |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
870 |
------- |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
871 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
872 |
Streams - along with ``Request IDs`` - facilitate grouping of frames. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
873 |
But the purpose of each is quite different and the groupings they |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
874 |
constitute are independent. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
875 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
876 |
A ``Request ID`` is essentially a tag. It tells you which logical |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
877 |
request a frame is associated with. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
878 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
879 |
A *stream* is a sequence of frames grouped for the express purpose |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
880 |
of applying a stateful encoding or for denoting sub-groups of frames. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
881 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
882 |
Unlike ``Request ID``s which span the request and response, a stream |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
883 |
is unidirectional and stream IDs are independent from client to |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
884 |
server. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
885 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
886 |
There is no strict hierarchical relationship between ``Request IDs`` |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
887 |
and *streams*. A stream can contain frames having multiple |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
888 |
``Request IDs``. Frames belonging to the same ``Request ID`` can |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
889 |
span multiple streams. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
890 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
891 |
One goal of streams is to facilitate content encoding. A stream can |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
892 |
define an encoding to be applied to frame payloads. For example, the |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
893 |
payload transmitted over the wire may contain output from a |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
894 |
zstandard compression operation and the receiving end may decompress |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
895 |
that payload to obtain the original data. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
896 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
897 |
The other goal of streams is to facilitate concurrent execution. For |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
898 |
example, a server could spawn 4 threads to service a request that can |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
899 |
be easily parallelized. Each of those 4 threads could write into its |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
900 |
own stream. Those streams could then in turn be delivered to 4 threads |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
901 |
on the receiving end, with each thread consuming its stream in near |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
902 |
isolation. The *main* thread on both ends merely does I/O and |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
903 |
encodes/decodes frame headers: the bulk of the work is done by worker |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
904 |
threads. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
905 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
906 |
In addition, since content encoding is defined per stream, each |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
907 |
*worker thread* could perform potentially CPU bound work concurrently |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
908 |
with other threads. This approach of applying encoding at the |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
909 |
sub-protocol / stream level eliminates a potential resource constraint |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
910 |
on the protocol stream as a whole (it is common for the throughput of |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
911 |
a compression engine to be smaller than the throughput of a network). |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
912 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
913 |
Having multiple streams - each with their own encoding settings - also |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
914 |
facilitates the use of advanced data compression techniques. For |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
915 |
example, a transmitter could see that it is generating data faster |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
916 |
and slower than the receiving end is consuming it and adjust its |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
917 |
compression settings to trade CPU for compression ratio accordingly. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
918 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
919 |
While streams can define a content encoding, not all frames within |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
920 |
that stream must use that content encoding. This can be useful when |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
921 |
data is being served from caches and being derived dynamically. A |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
922 |
cache could pre-compressed data so the server doesn't have to |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
923 |
recompress it. The ability to pick and choose which frames are |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
924 |
compressed allows servers to easily send data to the wire without |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
925 |
involving potentially expensive encoding overhead. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
926 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
927 |
Content Encoding Profiles |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
928 |
------------------------- |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
929 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
930 |
Streams can have named content encoding *profiles* associated with |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
931 |
them. A profile defines a shared understanding of content encoding |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
932 |
settings and behavior. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
933 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
934 |
The following profiles are defined: |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
935 |
|
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
936 |
TBD |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37132
diff
changeset
|
937 |
|
37725
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
938 |
Command Protocol |
37054
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
939 |
---------------- |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
940 |
|
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
941 |
A client can request that a remote run a command by sending it |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
942 |
frames defining that command. This logical stream is composed of |
37292
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
943 |
1 or more ``Command Request`` frames and and 0 or more ``Command Data`` |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
944 |
frames. |
37054
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
945 |
|
37060
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
946 |
All frames composing a single command request MUST be associated with |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
947 |
the same ``Request ID``. |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
948 |
|
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
949 |
Clients MAY send additional command requests without waiting on the |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
950 |
response to a previous command request. If they do so, they MUST ensure |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
951 |
that the ``Request ID`` field of outbound frames does not conflict |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
952 |
with that of an active ``Request ID`` whose response has not yet been |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
953 |
fully received. |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
954 |
|
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
955 |
Servers MAY respond to commands in a different order than they were |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
956 |
sent over the wire. Clients MUST be prepared to deal with this. Servers |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
957 |
also MAY start executing commands in a different order than they were |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
958 |
received, or MAY execute multiple commands concurrently. |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
959 |
|
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
960 |
If there is a dependency between commands or a race condition between |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
961 |
commands executing (e.g. a read-only command that depends on the results |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
962 |
of a command that mutates the repository), then clients MUST NOT send |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
963 |
frames issuing a command until a response to all dependent commands has |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
964 |
been received. |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
965 |
TODO think about whether we should express dependencies between commands |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
966 |
to avoid roundtrip latency. |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37058
diff
changeset
|
967 |
|
37292
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
968 |
A command is defined by a command name, 0 or more command arguments, |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
969 |
and optional command data. |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
970 |
|
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
971 |
Arguments are the recommended mechanism for transferring fixed sets of |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
972 |
parameters to a command. Data is appropriate for transferring variable |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
973 |
data. Thinking in terms of HTTP, arguments would be headers and data |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
974 |
would be the message body. |
37054
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
975 |
|
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
976 |
It is recommended for servers to delay the dispatch of a command |
37292
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
977 |
until all argument have been received. Servers MAY impose limits on the |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
978 |
maximum argument size. |
37054
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
979 |
TODO define failure mechanism. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
980 |
|
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
981 |
Servers MAY dispatch to commands immediately once argument data |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
982 |
is available or delay until command data is received in full. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37053
diff
changeset
|
983 |
|
37725
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
984 |
Once a ``Command Request`` frame is sent, a client must be prepared to |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
985 |
receive any of the following frames associated with that request: |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
986 |
``Command Response``, ``Error Response``, ``Human Output Side-Channel``, |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
987 |
``Progress Update``. |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
988 |
|
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
989 |
The *main* response for a command will be in ``Command Response`` frames. |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
990 |
The payloads of these frames consist of 1 or more CBOR encoded values. |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
991 |
The first CBOR value on the first ``Command Response`` frame is special |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
992 |
and denotes the overall status of the command. This CBOR map contains |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
993 |
the following bytestring keys: |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
994 |
|
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
995 |
status |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
996 |
(bytestring) A well-defined message containing the overall status of |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
997 |
this command request. The following values are defined: |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
998 |
|
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
999 |
ok |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
1000 |
The command was received successfully and its response follows. |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
1001 |
error |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
1002 |
There was an error processing the command. More details about the |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
1003 |
error are encoded in the ``error`` key. |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
1004 |
|
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
1005 |
error (optional) |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
1006 |
A map containing information about an encountered error. The map has the |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
1007 |
following keys: |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
1008 |
|
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
1009 |
message |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
1010 |
(array of maps) A message describing the error. The message uses the |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
1011 |
same format as those in the ``Human Output Side-Channel`` frame. |
3ea8323d6f95
wireprotov2: change command response protocol to include a leading map
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37724
diff
changeset
|
1012 |
|
29867
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1013 |
Capabilities |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1014 |
============ |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1015 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1016 |
Servers advertise supported wire protocol features. This allows clients to |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1017 |
probe for server features before blindly calling a command or passing a |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1018 |
specific argument. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1019 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1020 |
The server's features are exposed via a *capabilities* string. This is a |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1021 |
space-delimited string of tokens/features. Some features are single words |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1022 |
like ``lookup`` or ``batch``. Others are complicated key-value pairs |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1023 |
advertising sub-features. e.g. ``httpheader=2048``. When complex, non-word |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1024 |
values are used, each feature name can define its own encoding of sub-values. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1025 |
Comma-delimited and ``x-www-form-urlencoded`` values are common. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1026 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1027 |
The following document capabilities defined by the canonical Mercurial server |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1028 |
implementation. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1029 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1030 |
batch |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1031 |
----- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1032 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1033 |
Whether the server supports the ``batch`` command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1034 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1035 |
This capability/command was introduced in Mercurial 1.9 (released July 2011). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1036 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1037 |
branchmap |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1038 |
--------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1039 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1040 |
Whether the server supports the ``branchmap`` command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1041 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1042 |
This capability/command was introduced in Mercurial 1.3 (released July 2009). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1043 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1044 |
bundle2-exp |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1045 |
----------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1046 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1047 |
Precursor to ``bundle2`` capability that was used before bundle2 was a |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1048 |
stable feature. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1049 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1050 |
This capability was introduced in Mercurial 3.0 behind an experimental |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1051 |
flag. This capability should not be observed in the wild. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1052 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1053 |
bundle2 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1054 |
------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1055 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1056 |
Indicates whether the server supports the ``bundle2`` data exchange format. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1057 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1058 |
The value of the capability is a URL quoted, newline (``\n``) delimited |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1059 |
list of keys or key-value pairs. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1060 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1061 |
A key is simply a URL encoded string. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1062 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1063 |
A key-value pair is a URL encoded key separated from a URL encoded value by |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1064 |
an ``=``. If the value is a list, elements are delimited by a ``,`` after |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1065 |
URL encoding. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1066 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1067 |
For example, say we have the values:: |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1068 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1069 |
{'HG20': [], 'changegroup': ['01', '02'], 'digests': ['sha1', 'sha512']} |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1070 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1071 |
We would first construct a string:: |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1072 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1073 |
HG20\nchangegroup=01,02\ndigests=sha1,sha512 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1074 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1075 |
We would then URL quote this string:: |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1076 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1077 |
HG20%0Achangegroup%3D01%2C02%0Adigests%3Dsha1%2Csha512 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1078 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1079 |
This capability was introduced in Mercurial 3.4 (released May 2015). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1080 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1081 |
changegroupsubset |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1082 |
----------------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1083 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1084 |
Whether the server supports the ``changegroupsubset`` command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1085 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1086 |
This capability was introduced in Mercurial 0.9.2 (released December |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1087 |
2006). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1088 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1089 |
This capability was introduced at the same time as the ``lookup`` |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1090 |
capability/command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1091 |
|
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1092 |
compression |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1093 |
----------- |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1094 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1095 |
Declares support for negotiating compression formats. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1096 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1097 |
Presence of this capability indicates the server supports dynamic selection |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1098 |
of compression formats based on the client request. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1099 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1100 |
Servers advertising this capability are required to support the |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1101 |
``application/mercurial-0.2`` media type in response to commands returning |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1102 |
streams. Servers may support this media type on any command. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1103 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1104 |
The value of the capability is a comma-delimited list of strings declaring |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1105 |
supported compression formats. The order of the compression formats is in |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1106 |
server-preferred order, most preferred first. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1107 |
|
30761
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1108 |
The identifiers used by the official Mercurial distribution are: |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1109 |
|
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1110 |
bzip2 |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1111 |
bzip2 |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1112 |
none |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1113 |
uncompressed / raw data |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1114 |
zlib |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1115 |
zlib (no gzip header) |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1116 |
zstd |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1117 |
zstd |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1118 |
|
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1119 |
This capability was introduced in Mercurial 4.1 (released February 2017). |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1120 |
|
29867
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1121 |
getbundle |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1122 |
--------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1123 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1124 |
Whether the server supports the ``getbundle`` command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1125 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1126 |
This capability was introduced in Mercurial 1.9 (released July 2011). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1127 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1128 |
httpheader |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1129 |
---------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1130 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1131 |
Whether the server supports receiving command arguments via HTTP request |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1132 |
headers. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1133 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1134 |
The value of the capability is an integer describing the max header |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1135 |
length that clients should send. Clients should ignore any content after a |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1136 |
comma in the value, as this is reserved for future use. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1137 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1138 |
This capability was introduced in Mercurial 1.9 (released July 2011). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1139 |
|
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1140 |
httpmediatype |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1141 |
------------- |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1142 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1143 |
Indicates which HTTP media types (``Content-Type`` header) the server is |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1144 |
capable of receiving and sending. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1145 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1146 |
The value of the capability is a comma-delimited list of strings identifying |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1147 |
support for media type and transmission direction. The following strings may |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1148 |
be present: |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1149 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1150 |
0.1rx |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1151 |
Indicates server support for receiving ``application/mercurial-0.1`` media |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1152 |
types. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1153 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1154 |
0.1tx |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1155 |
Indicates server support for sending ``application/mercurial-0.1`` media |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1156 |
types. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1157 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1158 |
0.2rx |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1159 |
Indicates server support for receiving ``application/mercurial-0.2`` media |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1160 |
types. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1161 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1162 |
0.2tx |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1163 |
Indicates server support for sending ``application/mercurial-0.2`` media |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1164 |
types. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1165 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1166 |
minrx=X |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1167 |
Minimum media type version the server is capable of receiving. Value is a |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1168 |
string like ``0.2``. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1169 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1170 |
This capability can be used by servers to limit connections from legacy |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1171 |
clients not using the latest supported media type. However, only clients |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1172 |
with knowledge of this capability will know to consult this value. This |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1173 |
capability is present so the client may issue a more user-friendly error |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1174 |
when the server has locked out a legacy client. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1175 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1176 |
mintx=X |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1177 |
Minimum media type version the server is capable of sending. Value is a |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1178 |
string like ``0.1``. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1179 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1180 |
Servers advertising support for the ``application/mercurial-0.2`` media type |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1181 |
should also advertise the ``compression`` capability. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1182 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1183 |
This capability was introduced in Mercurial 4.1 (released February 2017). |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1184 |
|
29867
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1185 |
httppostargs |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1186 |
------------ |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1187 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1188 |
**Experimental** |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1189 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1190 |
Indicates that the server supports and prefers clients send command arguments |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1191 |
via a HTTP POST request as part of the request body. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1192 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1193 |
This capability was introduced in Mercurial 3.8 (released May 2016). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1194 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1195 |
known |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1196 |
----- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1197 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1198 |
Whether the server supports the ``known`` command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1199 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1200 |
This capability/command was introduced in Mercurial 1.9 (released July 2011). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1201 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1202 |
lookup |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1203 |
------ |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1204 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1205 |
Whether the server supports the ``lookup`` command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1206 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1207 |
This capability was introduced in Mercurial 0.9.2 (released December |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1208 |
2006). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1209 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1210 |
This capability was introduced at the same time as the ``changegroupsubset`` |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1211 |
capability/command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1212 |
|
37498
aacfca6f9767
wireproto: support for pullbundles
Joerg Sonnenberger <joerg@bec.de>
parents:
37488
diff
changeset
|
1213 |
partial-pull |
aacfca6f9767
wireproto: support for pullbundles
Joerg Sonnenberger <joerg@bec.de>
parents:
37488
diff
changeset
|
1214 |
------------ |
aacfca6f9767
wireproto: support for pullbundles
Joerg Sonnenberger <joerg@bec.de>
parents:
37488
diff
changeset
|
1215 |
|
aacfca6f9767
wireproto: support for pullbundles
Joerg Sonnenberger <joerg@bec.de>
parents:
37488
diff
changeset
|
1216 |
Indicates that the client can deal with partial answers to pull requests |
aacfca6f9767
wireproto: support for pullbundles
Joerg Sonnenberger <joerg@bec.de>
parents:
37488
diff
changeset
|
1217 |
by repeating the request. |
aacfca6f9767
wireproto: support for pullbundles
Joerg Sonnenberger <joerg@bec.de>
parents:
37488
diff
changeset
|
1218 |
|
aacfca6f9767
wireproto: support for pullbundles
Joerg Sonnenberger <joerg@bec.de>
parents:
37488
diff
changeset
|
1219 |
If this parameter is not advertised, the server will not send pull bundles. |
aacfca6f9767
wireproto: support for pullbundles
Joerg Sonnenberger <joerg@bec.de>
parents:
37488
diff
changeset
|
1220 |
|
aacfca6f9767
wireproto: support for pullbundles
Joerg Sonnenberger <joerg@bec.de>
parents:
37488
diff
changeset
|
1221 |
This client capability was introduced in Mercurial 4.6. |
aacfca6f9767
wireproto: support for pullbundles
Joerg Sonnenberger <joerg@bec.de>
parents:
37488
diff
changeset
|
1222 |
|
37393
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1223 |
protocaps |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1224 |
--------- |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1225 |
|
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1226 |
Whether the server supports the ``protocaps`` command for SSH V1 transport. |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1227 |
|
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1228 |
This capability was introduced in Mercurial 4.6. |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1229 |
|
29867
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1230 |
pushkey |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1231 |
------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1232 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1233 |
Whether the server supports the ``pushkey`` and ``listkeys`` commands. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1234 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1235 |
This capability was introduced in Mercurial 1.6 (released July 2010). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1236 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1237 |
standardbundle |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1238 |
-------------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1239 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1240 |
**Unsupported** |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1241 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1242 |
This capability was introduced during the Mercurial 0.9.2 development cycle in |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1243 |
2006. It was never present in a release, as it was replaced by the ``unbundle`` |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1244 |
capability. This capability should not be encountered in the wild. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1245 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1246 |
stream-preferred |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1247 |
---------------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1248 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1249 |
If present the server prefers that clients clone using the streaming clone |
34394
fffd3369aa83
commands: rename clone --uncompressed to --stream and document
Gregory Szorc <gregory.szorc@gmail.com>
parents:
32186
diff
changeset
|
1250 |
protocol (``hg clone --stream``) rather than the standard |
29867
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1251 |
changegroup/bundle based protocol. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1252 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1253 |
This capability was introduced in Mercurial 2.2 (released May 2012). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1254 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1255 |
streamreqs |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1256 |
---------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1257 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1258 |
Indicates whether the server supports *streaming clones* and the *requirements* |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1259 |
that clients must support to receive it. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1260 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1261 |
If present, the server supports the ``stream_out`` command, which transmits |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1262 |
raw revlogs from the repository instead of changegroups. This provides a faster |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1263 |
cloning mechanism at the expense of more bandwidth used. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1264 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1265 |
The value of this capability is a comma-delimited list of repo format |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1266 |
*requirements*. These are requirements that impact the reading of data in |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1267 |
the ``.hg/store`` directory. An example value is |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1268 |
``streamreqs=generaldelta,revlogv1`` indicating the server repo requires |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1269 |
the ``revlogv1`` and ``generaldelta`` requirements. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1270 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1271 |
If the only format requirement is ``revlogv1``, the server may expose the |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1272 |
``stream`` capability instead of the ``streamreqs`` capability. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1273 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1274 |
This capability was introduced in Mercurial 1.7 (released November 2010). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1275 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1276 |
stream |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1277 |
------ |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1278 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1279 |
Whether the server supports *streaming clones* from ``revlogv1`` repos. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1280 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1281 |
If present, the server supports the ``stream_out`` command, which transmits |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1282 |
raw revlogs from the repository instead of changegroups. This provides a faster |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1283 |
cloning mechanism at the expense of more bandwidth used. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1284 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1285 |
This capability was introduced in Mercurial 0.9.1 (released July 2006). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1286 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1287 |
When initially introduced, the value of the capability was the numeric |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1288 |
revlog revision. e.g. ``stream=1``. This indicates the changegroup is using |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1289 |
``revlogv1``. This simple integer value wasn't powerful enough, so the |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1290 |
``streamreqs`` capability was invented to handle cases where the repo |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1291 |
requirements have more than just ``revlogv1``. Newer servers omit the |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1292 |
``=1`` since it was the only value supported and the value of ``1`` can |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1293 |
be implied by clients. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1294 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1295 |
unbundlehash |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1296 |
------------ |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1297 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1298 |
Whether the ``unbundle`` commands supports receiving a hash of all the |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1299 |
heads instead of a list. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1300 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1301 |
For more, see the documentation for the ``unbundle`` command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1302 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1303 |
This capability was introduced in Mercurial 1.9 (released July 2011). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1304 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1305 |
unbundle |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1306 |
-------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1307 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1308 |
Whether the server supports pushing via the ``unbundle`` command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1309 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1310 |
This capability/command has been present since Mercurial 0.9.1 (released |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1311 |
July 2006). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1312 |
|
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1313 |
Mercurial 0.9.2 (released December 2006) added values to the capability |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1314 |
indicating which bundle types the server supports receiving. This value is a |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1315 |
comma-delimited list. e.g. ``HG10GZ,HG10BZ,HG10UN``. The order of values |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1316 |
reflects the priority/preference of that type, where the first value is the |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29866
diff
changeset
|
1317 |
most preferred type. |
29868
f0d47aca1d47
help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29867
diff
changeset
|
1318 |
|
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1319 |
Content Negotiation |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1320 |
=================== |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1321 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1322 |
The wire protocol has some mechanisms to help peers determine what content |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1323 |
types and encoding the other side will accept. Historically, these mechanisms |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1324 |
have been built into commands themselves because most commands only send a |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1325 |
well-defined response type and only certain commands needed to support |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1326 |
functionality like compression. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1327 |
|
36014
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
1328 |
Currently, only the HTTP version 1 transport supports content negotiation |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
1329 |
at the protocol layer. |
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1330 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1331 |
HTTP requests advertise supported response formats via the ``X-HgProto-<N>`` |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1332 |
request header, where ``<N>`` is an integer starting at 1 allowing the logical |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1333 |
value to span multiple headers. This value consists of a list of |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1334 |
space-delimited parameters. Each parameter denotes a feature or capability. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1335 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1336 |
The following parameters are defined: |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1337 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1338 |
0.1 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1339 |
Indicates the client supports receiving ``application/mercurial-0.1`` |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1340 |
responses. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1341 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1342 |
0.2 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1343 |
Indicates the client supports receiving ``application/mercurial-0.2`` |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1344 |
responses. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1345 |
|
37557
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
1346 |
cbor |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
1347 |
Indicates the client supports receiving ``application/mercurial-cbor`` |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
1348 |
responses. |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
1349 |
|
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
1350 |
(Only intended to be used with version 2 transports.) |
734515aca84d
wireproto: define and implement HTTP handshake to upgrade protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37554
diff
changeset
|
1351 |
|
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1352 |
comp |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1353 |
Indicates compression formats the client can decode. Value is a list of |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1354 |
comma delimited strings identifying compression formats ordered from |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1355 |
most preferential to least preferential. e.g. ``comp=zstd,zlib,none``. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1356 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1357 |
This parameter does not have an effect if only the ``0.1`` parameter |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1358 |
is defined, as support for ``application/mercurial-0.2`` or greater is |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1359 |
required to use arbitrary compression formats. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1360 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1361 |
If this parameter is not advertised, the server interprets this as |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1362 |
equivalent to ``zlib,none``. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1363 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1364 |
Clients may choose to only send this header if the ``httpmediatype`` |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1365 |
server capability is present, as currently all server-side features |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1366 |
consulting this header require the client to opt in to new protocol features |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1367 |
advertised via the ``httpmediatype`` capability. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1368 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1369 |
A server that doesn't receive an ``X-HgProto-<N>`` header should infer a |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1370 |
value of ``0.1``. This is compatible with legacy clients. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1371 |
|
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1372 |
A server receiving a request indicating support for multiple media type |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1373 |
versions may respond with any of the supported media types. Not all servers |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1374 |
may support all media types on all commands. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29869
diff
changeset
|
1375 |
|
29869
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1376 |
Commands |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1377 |
======== |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1378 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1379 |
This section contains a list of all wire protocol commands implemented by |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1380 |
the canonical Mercurial server. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1381 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1382 |
batch |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1383 |
----- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1384 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1385 |
Issue multiple commands while sending a single command request. The purpose |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1386 |
of this command is to allow a client to issue multiple commands while avoiding |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1387 |
multiple round trips to the server therefore enabling commands to complete |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1388 |
quicker. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1389 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1390 |
The command accepts a ``cmds`` argument that contains a list of commands to |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1391 |
execute. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1392 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1393 |
The value of ``cmds`` is a ``;`` delimited list of strings. Each string has the |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1394 |
form ``<command> <arguments>``. That is, the command name followed by a space |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1395 |
followed by an argument string. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1396 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1397 |
The argument string is a ``,`` delimited list of ``<key>=<value>`` values |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1398 |
corresponding to command arguments. Both the argument name and value are |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1399 |
escaped using a special substitution map:: |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1400 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1401 |
: -> :c |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1402 |
, -> :o |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1403 |
; -> :s |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1404 |
= -> :e |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1405 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1406 |
The response type for this command is ``string``. The value contains a |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1407 |
``;`` delimited list of responses for each requested command. Each value |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1408 |
in this list is escaped using the same substitution map used for arguments. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1409 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1410 |
If an error occurs, the generic error response may be sent. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1411 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1412 |
between |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1413 |
------- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1414 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1415 |
(Legacy command used for discovery in old clients) |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1416 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1417 |
Obtain nodes between pairs of nodes. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1418 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1419 |
The ``pairs`` arguments contains a space-delimited list of ``-`` delimited |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1420 |
hex node pairs. e.g.:: |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1421 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1422 |
a072279d3f7fd3a4aa7ffa1a5af8efc573e1c896-6dc58916e7c070f678682bfe404d2e2d68291a18 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1423 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1424 |
Return type is a ``string``. Value consists of lines corresponding to each |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1425 |
requested range. Each line contains a space-delimited list of hex nodes. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1426 |
A newline ``\n`` terminates each line, including the last one. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1427 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1428 |
branchmap |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1429 |
--------- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1430 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1431 |
Obtain heads in named branches. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1432 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1433 |
Accepts no arguments. Return type is a ``string``. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1434 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1435 |
Return value contains lines with URL encoded branch names followed by a space |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1436 |
followed by a space-delimited list of hex nodes of heads on that branch. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1437 |
e.g.:: |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1438 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1439 |
default a072279d3f7fd3a4aa7ffa1a5af8efc573e1c896 6dc58916e7c070f678682bfe404d2e2d68291a18 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1440 |
stable baae3bf31522f41dd5e6d7377d0edd8d1cf3fccc |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1441 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1442 |
There is no trailing newline. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1443 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1444 |
branches |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1445 |
-------- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1446 |
|
32186
435a3842ca3a
internals: document that "branches" is a legacy wire command
Siddharth Agarwal <sid0@fb.com>
parents:
30761
diff
changeset
|
1447 |
(Legacy command used for discovery in old clients. Clients with ``getbundle`` |
435a3842ca3a
internals: document that "branches" is a legacy wire command
Siddharth Agarwal <sid0@fb.com>
parents:
30761
diff
changeset
|
1448 |
use the ``known`` and ``heads`` commands instead.) |
435a3842ca3a
internals: document that "branches" is a legacy wire command
Siddharth Agarwal <sid0@fb.com>
parents:
30761
diff
changeset
|
1449 |
|
29869
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1450 |
Obtain ancestor changesets of specific nodes back to a branch point. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1451 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1452 |
Despite the name, this command has nothing to do with Mercurial named branches. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1453 |
Instead, it is related to DAG branches. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1454 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1455 |
The command accepts a ``nodes`` argument, which is a string of space-delimited |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1456 |
hex nodes. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1457 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1458 |
For each node requested, the server will find the first ancestor node that is |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1459 |
a DAG root or is a merge. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1460 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1461 |
Return type is a ``string``. Return value contains lines with result data for |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1462 |
each requested node. Each line contains space-delimited nodes followed by a |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1463 |
newline (``\n``). The 4 nodes reported on each line correspond to the requested |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1464 |
node, the ancestor node found, and its 2 parent nodes (which may be the null |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1465 |
node). |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1466 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1467 |
capabilities |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1468 |
------------ |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1469 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1470 |
Obtain the capabilities string for the repo. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1471 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1472 |
Unlike the ``hello`` command, the capabilities string is not prefixed. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1473 |
There is no trailing newline. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1474 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1475 |
This command does not accept any arguments. Return type is a ``string``. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1476 |
|
35923
0d8024be7166
internals: document when "hello" and "capabilities" commands were added
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35276
diff
changeset
|
1477 |
This command was introduced in Mercurial 0.9.1 (released July 2006). |
0d8024be7166
internals: document when "hello" and "capabilities" commands were added
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35276
diff
changeset
|
1478 |
|
29869
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1479 |
changegroup |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1480 |
----------- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1481 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1482 |
(Legacy command: use ``getbundle`` instead) |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1483 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1484 |
Obtain a changegroup version 1 with data for changesets that are |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1485 |
descendants of client-specified changesets. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1486 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1487 |
The ``roots`` arguments contains a list of space-delimited hex nodes. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1488 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1489 |
The server responds with a changegroup version 1 containing all |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1490 |
changesets between the requested root/base nodes and the repo's head nodes |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1491 |
at the time of the request. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1492 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1493 |
The return type is a ``stream``. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1494 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1495 |
changegroupsubset |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1496 |
----------------- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1497 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1498 |
(Legacy command: use ``getbundle`` instead) |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1499 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1500 |
Obtain a changegroup version 1 with data for changesetsets between |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1501 |
client specified base and head nodes. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1502 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1503 |
The ``bases`` argument contains a list of space-delimited hex nodes. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1504 |
The ``heads`` argument contains a list of space-delimited hex nodes. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1505 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1506 |
The server responds with a changegroup version 1 containing all |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1507 |
changesets between the requested base and head nodes at the time of the |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1508 |
request. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1509 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1510 |
The return type is a ``stream``. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1511 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1512 |
clonebundles |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1513 |
------------ |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1514 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1515 |
Obtains a manifest of bundle URLs available to seed clones. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1516 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1517 |
Each returned line contains a URL followed by metadata. See the |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1518 |
documentation in the ``clonebundles`` extension for more. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1519 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1520 |
The return type is a ``string``. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1521 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1522 |
getbundle |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1523 |
--------- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1524 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1525 |
Obtain a bundle containing repository data. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1526 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1527 |
This command accepts the following arguments: |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1528 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1529 |
heads |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1530 |
List of space-delimited hex nodes of heads to retrieve. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1531 |
common |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1532 |
List of space-delimited hex nodes that the client has in common with the |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1533 |
server. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1534 |
obsmarkers |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1535 |
Boolean indicating whether to include obsolescence markers as part |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1536 |
of the response. Only works with bundle2. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1537 |
bundlecaps |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1538 |
Comma-delimited set of strings defining client bundle capabilities. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1539 |
listkeys |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1540 |
Comma-delimited list of strings of ``pushkey`` namespaces. For each |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1541 |
namespace listed, a bundle2 part will be included with the content of |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1542 |
that namespace. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1543 |
cg |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1544 |
Boolean indicating whether changegroup data is requested. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1545 |
cbattempted |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1546 |
Boolean indicating whether the client attempted to use the *clone bundles* |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1547 |
feature before performing this request. |
35276
cb4dcd7fabe7
getbundle: add support for 'bookmarks' boolean argument
Boris Feld <boris.feld@octobus.net>
parents:
34930
diff
changeset
|
1548 |
bookmarks |
cb4dcd7fabe7
getbundle: add support for 'bookmarks' boolean argument
Boris Feld <boris.feld@octobus.net>
parents:
34930
diff
changeset
|
1549 |
Boolean indicating whether bookmark data is requested. |
34930
28baeab476cc
internal-doc: document the 'phases' parameters to 'getbundle'
Boris Feld <boris.feld@octobus.net>
parents:
34394
diff
changeset
|
1550 |
phases |
28baeab476cc
internal-doc: document the 'phases' parameters to 'getbundle'
Boris Feld <boris.feld@octobus.net>
parents:
34394
diff
changeset
|
1551 |
Boolean indicating whether phases data is requested. |
29869
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1552 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1553 |
The return type on success is a ``stream`` where the value is bundle. |
36014
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
1554 |
On the HTTP version 1 transport, the response is zlib compressed. |
29869
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1555 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1556 |
If an error occurs, a generic error response can be sent. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1557 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1558 |
Unless the client sends a false value for the ``cg`` argument, the returned |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1559 |
bundle contains a changegroup with the nodes between the specified ``common`` |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1560 |
and ``heads`` nodes. Depending on the command arguments, the type and content |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1561 |
of the returned bundle can vary significantly. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1562 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1563 |
The default behavior is for the server to send a raw changegroup version |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1564 |
``01`` response. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1565 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1566 |
If the ``bundlecaps`` provided by the client contain a value beginning |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1567 |
with ``HG2``, a bundle2 will be returned. The bundle2 data may contain |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1568 |
additional repository data, such as ``pushkey`` namespace values. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1569 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1570 |
heads |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1571 |
----- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1572 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1573 |
Returns a list of space-delimited hex nodes of repository heads followed |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1574 |
by a newline. e.g. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1575 |
``a9eeb3adc7ddb5006c088e9eda61791c777cbf7c 31f91a3da534dc849f0d6bfc00a395a97cf218a1\n`` |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1576 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1577 |
This command does not accept any arguments. The return type is a ``string``. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1578 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1579 |
hello |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1580 |
----- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1581 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1582 |
Returns lines describing interesting things about the server in an RFC-822 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1583 |
like format. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1584 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1585 |
Currently, the only line defines the server capabilities. It has the form:: |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1586 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1587 |
capabilities: <value> |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1588 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1589 |
See above for more about the capabilities string. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1590 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1591 |
SSH clients typically issue this command as soon as a connection is |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1592 |
established. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1593 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1594 |
This command does not accept any arguments. The return type is a ``string``. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1595 |
|
35923
0d8024be7166
internals: document when "hello" and "capabilities" commands were added
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35276
diff
changeset
|
1596 |
This command was introduced in Mercurial 0.9.1 (released July 2006). |
0d8024be7166
internals: document when "hello" and "capabilities" commands were added
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35276
diff
changeset
|
1597 |
|
29869
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1598 |
listkeys |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1599 |
-------- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1600 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1601 |
List values in a specified ``pushkey`` namespace. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1602 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1603 |
The ``namespace`` argument defines the pushkey namespace to operate on. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1604 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1605 |
The return type is a ``string``. The value is an encoded dictionary of keys. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1606 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1607 |
Key-value pairs are delimited by newlines (``\n``). Within each line, keys and |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1608 |
values are separated by a tab (``\t``). Keys and values are both strings. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1609 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1610 |
lookup |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1611 |
------ |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1612 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1613 |
Try to resolve a value to a known repository revision. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1614 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1615 |
The ``key`` argument is converted from bytes to an |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1616 |
``encoding.localstr`` instance then passed into |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1617 |
``localrepository.__getitem__`` in an attempt to resolve it. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1618 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1619 |
The return type is a ``string``. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1620 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1621 |
Upon successful resolution, returns ``1 <hex node>\n``. On failure, |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1622 |
returns ``0 <error string>\n``. e.g.:: |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1623 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1624 |
1 273ce12ad8f155317b2c078ec75a4eba507f1fba\n |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1625 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1626 |
0 unknown revision 'foo'\n |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1627 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1628 |
known |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1629 |
----- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1630 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1631 |
Determine whether multiple nodes are known. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1632 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1633 |
The ``nodes`` argument is a list of space-delimited hex nodes to check |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1634 |
for existence. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1635 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1636 |
The return type is ``string``. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1637 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1638 |
Returns a string consisting of ``0``s and ``1``s indicating whether nodes |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1639 |
are known. If the Nth node specified in the ``nodes`` argument is known, |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1640 |
a ``1`` will be returned at byte offset N. If the node isn't known, ``0`` |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1641 |
will be present at byte offset N. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1642 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1643 |
There is no trailing newline. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1644 |
|
37393
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1645 |
protocaps |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1646 |
--------- |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1647 |
|
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1648 |
Notify the server about the client capabilities in the SSH V1 transport |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1649 |
protocol. |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1650 |
|
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1651 |
The ``caps`` argument is a space-delimited list of capabilities. |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1652 |
|
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1653 |
The server will reply with the string ``OK``. |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1654 |
|
29869
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1655 |
pushkey |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1656 |
------- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1657 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1658 |
Set a value using the ``pushkey`` protocol. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1659 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1660 |
Accepts arguments ``namespace``, ``key``, ``old``, and ``new``, which |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1661 |
correspond to the pushkey namespace to operate on, the key within that |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1662 |
namespace to change, the old value (which may be empty), and the new value. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1663 |
All arguments are string types. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1664 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1665 |
The return type is a ``string``. The value depends on the transport protocol. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1666 |
|
36014
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
1667 |
The SSH version 1 transport sends a string encoded integer followed by a |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
1668 |
newline (``\n``) which indicates operation result. The server may send |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
1669 |
additional output on the ``stderr`` stream that should be displayed to the |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
1670 |
user. |
29869
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1671 |
|
36014
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
1672 |
The HTTP version 1 transport sends a string encoded integer followed by a |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
1673 |
newline followed by additional server output that should be displayed to |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
1674 |
the user. This may include output from hooks, etc. |
29869
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1675 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1676 |
The integer result varies by namespace. ``0`` means an error has occurred |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1677 |
and there should be additional output to display to the user. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1678 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1679 |
stream_out |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1680 |
---------- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1681 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1682 |
Obtain *streaming clone* data. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1683 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1684 |
The return type is either a ``string`` or a ``stream``, depending on |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1685 |
whether the request was fulfilled properly. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1686 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1687 |
A return value of ``1\n`` indicates the server is not configured to serve |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1688 |
this data. If this is seen by the client, they may not have verified the |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1689 |
``stream`` capability is set before making the request. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1690 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1691 |
A return value of ``2\n`` indicates the server was unable to lock the |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1692 |
repository to generate data. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1693 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1694 |
All other responses are a ``stream`` of bytes. The first line of this data |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1695 |
contains 2 space-delimited integers corresponding to the path count and |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1696 |
payload size, respectively:: |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1697 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1698 |
<path count> <payload size>\n |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1699 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1700 |
The ``<payload size>`` is the total size of path data: it does not include |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1701 |
the size of the per-path header lines. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1702 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1703 |
Following that header are ``<path count>`` entries. Each entry consists of a |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1704 |
line with metadata followed by raw revlog data. The line consists of:: |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1705 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1706 |
<store path>\0<size>\n |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1707 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1708 |
The ``<store path>`` is the encoded store path of the data that follows. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1709 |
``<size>`` is the amount of data for this store path/revlog that follows the |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1710 |
newline. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1711 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1712 |
There is no trailer to indicate end of data. Instead, the client should stop |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1713 |
reading after ``<path count>`` entries are consumed. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1714 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1715 |
unbundle |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1716 |
-------- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1717 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1718 |
Send a bundle containing data (usually changegroup data) to the server. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1719 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1720 |
Accepts the argument ``heads``, which is a space-delimited list of hex nodes |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1721 |
corresponding to server repository heads observed by the client. This is used |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1722 |
to detect race conditions and abort push operations before a server performs |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1723 |
too much work or a client transfers too much data. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1724 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1725 |
The request payload consists of a bundle to be applied to the repository, |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1726 |
similarly to as if :hg:`unbundle` were called. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1727 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1728 |
In most scenarios, a special ``push response`` type is returned. This type |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1729 |
contains an integer describing the change in heads as a result of the |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1730 |
operation. A value of ``0`` indicates nothing changed. ``1`` means the number |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1731 |
of heads remained the same. Values ``2`` and larger indicate the number of |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1732 |
added heads minus 1. e.g. ``3`` means 2 heads were added. Negative values |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1733 |
indicate the number of fewer heads, also off by 1. e.g. ``-2`` means there |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1734 |
is 1 fewer head. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1735 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1736 |
The encoding of the ``push response`` type varies by transport. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1737 |
|
36014
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
1738 |
For the SSH version 1 transport, this type is composed of 2 ``string`` |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
1739 |
responses: an empty response (``0\n``) followed by the integer result value. |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
1740 |
e.g. ``1\n2``. So the full response might be ``0\n1\n2``. |
29869
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1741 |
|
36014
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
1742 |
For the HTTP version 1 transport, the response is a ``string`` type composed |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
1743 |
of an integer result value followed by a newline (``\n``) followed by string |
29869
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1744 |
content holding server output that should be displayed on the client (output |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1745 |
hooks, etc). |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1746 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1747 |
In some cases, the server may respond with a ``bundle2`` bundle. In this |
36014
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
1748 |
case, the response type is ``stream``. For the HTTP version 1 transport, the |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35923
diff
changeset
|
1749 |
response is zlib compressed. |
29869
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1750 |
|
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1751 |
The server may also respond with a generic error type, which contains a string |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29868
diff
changeset
|
1752 |
indicating the failure. |
37485
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1753 |
|
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1754 |
Frame-Based Protocol Commands |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1755 |
============================= |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1756 |
|
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1757 |
**Experimental and under active development** |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1758 |
|
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1759 |
This section documents the wire protocol commands exposed to transports |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1760 |
using the frame-based protocol. The set of commands exposed through |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1761 |
these transports is distinct from the set of commands exposed to legacy |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1762 |
transports. |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1763 |
|
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1764 |
The frame-based protocol uses CBOR to encode command execution requests. |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1765 |
All command arguments must be mapped to a specific or set of CBOR data |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1766 |
types. |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1767 |
|
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1768 |
The response to many commands is also CBOR. There is no common response |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1769 |
format: each command defines its own response format. |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1770 |
|
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1771 |
TODO require node type be specified, as N bytes of binary node value |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1772 |
could be ambiguous once SHA-1 is replaced. |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1773 |
|
37488
3b99eb028859
wireproto: port branchmap to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37487
diff
changeset
|
1774 |
branchmap |
3b99eb028859
wireproto: port branchmap to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37487
diff
changeset
|
1775 |
--------- |
3b99eb028859
wireproto: port branchmap to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37487
diff
changeset
|
1776 |
|
3b99eb028859
wireproto: port branchmap to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37487
diff
changeset
|
1777 |
Obtain heads in named branches. |
3b99eb028859
wireproto: port branchmap to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37487
diff
changeset
|
1778 |
|
3b99eb028859
wireproto: port branchmap to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37487
diff
changeset
|
1779 |
Receives no arguments. |
3b99eb028859
wireproto: port branchmap to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37487
diff
changeset
|
1780 |
|
3b99eb028859
wireproto: port branchmap to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37487
diff
changeset
|
1781 |
The response is a map with bytestring keys defining the branch name. |
3b99eb028859
wireproto: port branchmap to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37487
diff
changeset
|
1782 |
Values are arrays of bytestring defining raw changeset nodes. |
3b99eb028859
wireproto: port branchmap to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37487
diff
changeset
|
1783 |
|
37533
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1784 |
capabilities |
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1785 |
------------ |
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1786 |
|
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1787 |
Obtain the server's capabilities. |
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1788 |
|
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1789 |
Receives no arguments. |
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1790 |
|
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1791 |
This command is typically called only as part of the handshake during |
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1792 |
initial connection establishment. |
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1793 |
|
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1794 |
The response is a map with bytestring keys defining server information. |
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1795 |
|
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1796 |
The defined keys are: |
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1797 |
|
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1798 |
commands |
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1799 |
A map defining available wire protocol commands on this server. |
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1800 |
|
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1801 |
Keys in the map are the names of commands that can be invoked. Values |
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1802 |
are maps defining information about that command. The bytestring keys |
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1803 |
are: |
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1804 |
|
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1805 |
args |
37535
69e46c1834ac
wireproto: define and expose types of wire command arguments
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37533
diff
changeset
|
1806 |
A map of argument names and their expected types. |
69e46c1834ac
wireproto: define and expose types of wire command arguments
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37533
diff
changeset
|
1807 |
|
69e46c1834ac
wireproto: define and expose types of wire command arguments
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37533
diff
changeset
|
1808 |
Types are defined as a representative value for the expected type. |
69e46c1834ac
wireproto: define and expose types of wire command arguments
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37533
diff
changeset
|
1809 |
e.g. an argument expecting a boolean type will have its value |
69e46c1834ac
wireproto: define and expose types of wire command arguments
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37533
diff
changeset
|
1810 |
set to true. An integer type will have its value set to 42. The |
69e46c1834ac
wireproto: define and expose types of wire command arguments
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37533
diff
changeset
|
1811 |
actual values are arbitrary and may not have meaning. |
37533
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1812 |
permissions |
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1813 |
An array of permissions required to execute this command. |
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1814 |
|
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1815 |
compression |
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1816 |
An array of maps defining available compression format support. |
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1817 |
|
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1818 |
The array is sorted from most preferred to least preferred. |
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1819 |
|
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1820 |
Each entry has the following bytestring keys: |
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1821 |
|
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1822 |
name |
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1823 |
Name of the compression engine. e.g. ``zstd`` or ``zlib``. |
df4985497986
wireproto: implement capabilities for wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37498
diff
changeset
|
1824 |
|
37653
b2fa1591fb44
wireproto: add media type to version 2 capabilities response
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37557
diff
changeset
|
1825 |
framingmediatypes |
b2fa1591fb44
wireproto: add media type to version 2 capabilities response
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37557
diff
changeset
|
1826 |
An array of bytestrings defining the supported framing protocol |
b2fa1591fb44
wireproto: add media type to version 2 capabilities response
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37557
diff
changeset
|
1827 |
media types. Servers will not accept media types not in this list. |
b2fa1591fb44
wireproto: add media type to version 2 capabilities response
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37557
diff
changeset
|
1828 |
|
37657
23c4ddda7bbe
wireproto: expose repository formats via capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37653
diff
changeset
|
1829 |
rawrepoformats |
23c4ddda7bbe
wireproto: expose repository formats via capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37653
diff
changeset
|
1830 |
An array of storage formats the repository is using. This set of |
23c4ddda7bbe
wireproto: expose repository formats via capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37653
diff
changeset
|
1831 |
requirements can be used to determine whether a client can read a |
23c4ddda7bbe
wireproto: expose repository formats via capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37653
diff
changeset
|
1832 |
*raw* copy of file data available. |
23c4ddda7bbe
wireproto: expose repository formats via capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37653
diff
changeset
|
1833 |
|
37485
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1834 |
heads |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1835 |
----- |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1836 |
|
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1837 |
Obtain DAG heads in the repository. |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1838 |
|
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1839 |
The command accepts the following arguments: |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1840 |
|
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1841 |
publiconly (optional) |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1842 |
(boolean) If set, operate on the DAG for public phase changesets only. |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1843 |
Non-public (i.e. draft) phase DAG heads will not be returned. |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1844 |
|
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1845 |
The response is a CBOR array of bytestrings defining changeset nodes |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1846 |
of DAG heads. The array can be empty if the repository is empty or no |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1847 |
changesets satisfied the request. |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1848 |
|
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1849 |
TODO consider exposing phase of heads in response |
37486
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1850 |
|
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1851 |
known |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1852 |
----- |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1853 |
|
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1854 |
Determine whether a series of changeset nodes is known to the server. |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1855 |
|
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1856 |
The command accepts the following arguments: |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1857 |
|
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1858 |
nodes |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1859 |
(array of bytestrings) List of changeset nodes whose presence to |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1860 |
query. |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1861 |
|
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1862 |
The response is a bytestring where each byte contains a 0 or 1 for the |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1863 |
corresponding requested node at the same index. |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1864 |
|
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1865 |
TODO use a bit array for even more compact response |
37487
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1866 |
|
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1867 |
listkeys |
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1868 |
-------- |
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1869 |
|
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1870 |
List values in a specified ``pushkey`` namespace. |
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1871 |
|
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1872 |
The command receives the following arguments: |
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1873 |
|
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1874 |
namespace |
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1875 |
(bytestring) Pushkey namespace to query. |
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1876 |
|
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1877 |
The response is a map with bytestring keys and values. |
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1878 |
|
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1879 |
TODO consider using binary to represent nodes in certain pushkey namespaces. |
37537
be5d4749edc0
wireproto: port pushkey command to wire protocol version 2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37535
diff
changeset
|
1880 |
|
37538
89fed81bbb6c
wireproto: port lookup to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37537
diff
changeset
|
1881 |
lookup |
89fed81bbb6c
wireproto: port lookup to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37537
diff
changeset
|
1882 |
------ |
89fed81bbb6c
wireproto: port lookup to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37537
diff
changeset
|
1883 |
|
89fed81bbb6c
wireproto: port lookup to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37537
diff
changeset
|
1884 |
Try to resolve a value to a changeset revision. |
89fed81bbb6c
wireproto: port lookup to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37537
diff
changeset
|
1885 |
|
89fed81bbb6c
wireproto: port lookup to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37537
diff
changeset
|
1886 |
Unlike ``known`` which operates on changeset nodes, lookup operates on |
89fed81bbb6c
wireproto: port lookup to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37537
diff
changeset
|
1887 |
node fragments and other names that a user may use. |
89fed81bbb6c
wireproto: port lookup to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37537
diff
changeset
|
1888 |
|
89fed81bbb6c
wireproto: port lookup to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37537
diff
changeset
|
1889 |
The command receives the following arguments: |
89fed81bbb6c
wireproto: port lookup to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37537
diff
changeset
|
1890 |
|
89fed81bbb6c
wireproto: port lookup to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37537
diff
changeset
|
1891 |
key |
89fed81bbb6c
wireproto: port lookup to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37537
diff
changeset
|
1892 |
(bytestring) Value to try to resolve. |
89fed81bbb6c
wireproto: port lookup to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37537
diff
changeset
|
1893 |
|
89fed81bbb6c
wireproto: port lookup to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37537
diff
changeset
|
1894 |
On success, returns a bytestring containing the resolved node. |
89fed81bbb6c
wireproto: port lookup to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37537
diff
changeset
|
1895 |
|
37537
be5d4749edc0
wireproto: port pushkey command to wire protocol version 2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37535
diff
changeset
|
1896 |
pushkey |
be5d4749edc0
wireproto: port pushkey command to wire protocol version 2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37535
diff
changeset
|
1897 |
------- |
be5d4749edc0
wireproto: port pushkey command to wire protocol version 2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37535
diff
changeset
|
1898 |
|
be5d4749edc0
wireproto: port pushkey command to wire protocol version 2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37535
diff
changeset
|
1899 |
Set a value using the ``pushkey`` protocol. |
be5d4749edc0
wireproto: port pushkey command to wire protocol version 2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37535
diff
changeset
|
1900 |
|
be5d4749edc0
wireproto: port pushkey command to wire protocol version 2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37535
diff
changeset
|
1901 |
The command receives the following arguments: |
be5d4749edc0
wireproto: port pushkey command to wire protocol version 2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37535
diff
changeset
|
1902 |
|
be5d4749edc0
wireproto: port pushkey command to wire protocol version 2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37535
diff
changeset
|
1903 |
namespace |
be5d4749edc0
wireproto: port pushkey command to wire protocol version 2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37535
diff
changeset
|
1904 |
(bytestring) Pushkey namespace to operate on. |
be5d4749edc0
wireproto: port pushkey command to wire protocol version 2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37535
diff
changeset
|
1905 |
key |
be5d4749edc0
wireproto: port pushkey command to wire protocol version 2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37535
diff
changeset
|
1906 |
(bytestring) The pushkey key to set. |
be5d4749edc0
wireproto: port pushkey command to wire protocol version 2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37535
diff
changeset
|
1907 |
old |
be5d4749edc0
wireproto: port pushkey command to wire protocol version 2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37535
diff
changeset
|
1908 |
(bytestring) Old value for this key. |
be5d4749edc0
wireproto: port pushkey command to wire protocol version 2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37535
diff
changeset
|
1909 |
new |
be5d4749edc0
wireproto: port pushkey command to wire protocol version 2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37535
diff
changeset
|
1910 |
(bytestring) New value for this key. |
be5d4749edc0
wireproto: port pushkey command to wire protocol version 2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37535
diff
changeset
|
1911 |
|
be5d4749edc0
wireproto: port pushkey command to wire protocol version 2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37535
diff
changeset
|
1912 |
TODO consider using binary to represent nodes is certain pushkey namespaces. |
be5d4749edc0
wireproto: port pushkey command to wire protocol version 2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37535
diff
changeset
|
1913 |
TODO better define response type and meaning. |