Mercurial > public > mercurial-scm > hg
annotate mercurial/help/internals/wireprotocol.txt @ 37291:b0041036214e
wireproto: define frame to represent progress updates
Today, a long-running operation on a server may run without any sign
of progress on the client. This can lead to the conclusion that the
server has hung or the connection has dropped. In fact, connections
can and do time out due to inactivity. And a long-running server
operation can result in the connection dropping prematurely because
no data is being sent!
While we're inventing the new wire protocol, let's provide a mechanism
for communicating progress on potentially expensive server-side events.
We introduce a new frame type that conveys "progress" updates. This
frame type essentially holds the data required to formulate a
``ui.progress()`` call.
We only define the frame right now. Implementing it will be a bit of
work since there is no analog to progress frames in the existing
wire protocol. We'll need to teach the ui object to write to the
wire protocol, etc.
The use of a CBOR map may seem wasteful, as this will encode key
names in every frame. This *is* wasteful. However, maps are
extensible. And the intent is to always use compression via
streams. Compression will make the overhead negligible since repeated
strings will be mostly eliminated over the wire.
Differential Revision: https://phab.mercurial-scm.org/D2902
author | Gregory Szorc <gregory.szorc@gmail.com> |
---|---|
date | Mon, 26 Mar 2018 10:50:36 -0700 |
parents | 9bfcbe4f4745 |
children | 3d0e2cd86e05 |
rev | line source |
---|---|
29859
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). |
29860
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
12 |
35975
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
13 Handshake |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
14 ========= |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
15 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
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:
35883
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:
35883
diff
changeset
|
18 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
19 * Negotiating protocol/transport level options |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
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:
35883
diff
changeset
|
21 future requests |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
22 * Ensures the underlying transport channel is in a *clean* state |
29860
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
23 |
35975
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
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:
35883
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:
35883
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:
35883
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:
35883
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:
35883
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:
35883
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:
35883
diff
changeset
|
31 few round trips as possible. |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
32 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
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:
35883
diff
changeset
|
34 in the sections below. |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
35 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
36 HTTP Protocol |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
37 ============= |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
38 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
39 Handshake |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
40 --------- |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
41 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
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:
35883
diff
changeset
|
43 as soon as HTTP requests may be issued. |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
44 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
45 The server responds with a capabilities string, which the client parses to |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
46 learn about the server's abilities. |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
47 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
48 HTTP Version 1 Transport |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
49 ------------------------ |
29860
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
50 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
51 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:
29859
diff
changeset
|
52 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:
29859
diff
changeset
|
53 the ``cmd`` query string parameter. e.g. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
54 ``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:
29859
diff
changeset
|
55 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:
29859
diff
changeset
|
56 body. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
57 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
58 Command arguments can be sent multiple ways. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
59 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
60 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:
29859
diff
changeset
|
61 encoding (see Python's ``urllib.urlencode()``. However, many servers impose |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
62 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:
29859
diff
changeset
|
63 the server doesn't support other mechanisms. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
64 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
65 If the server supports the ``httpheader`` capability, command arguments can |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
66 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:
29859
diff
changeset
|
67 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:
29859
diff
changeset
|
68 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:
29859
diff
changeset
|
69 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:
29859
diff
changeset
|
70 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:
29859
diff
changeset
|
71 to ``1024``. The server reassembles the encoded arguments string by |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
72 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:
29859
diff
changeset
|
73 dictionary. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
74 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
75 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:
29859
diff
changeset
|
76 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:
29859
diff
changeset
|
77 requests. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
78 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
79 If the server supports the ``httppostargs`` capability, the client |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
80 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:
29859
diff
changeset
|
81 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:
29859
diff
changeset
|
82 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:
29859
diff
changeset
|
83 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:
29859
diff
changeset
|
84 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
85 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:
29859
diff
changeset
|
86 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:
29859
diff
changeset
|
87 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:
29859
diff
changeset
|
88 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:
29859
diff
changeset
|
89 ``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:
29859
diff
changeset
|
90 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
91 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:
29859
diff
changeset
|
92 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:
29859
diff
changeset
|
93 A ``Content-Length`` header is currently always sent. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
94 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
95 Example HTTP requests:: |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
96 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
97 GET /repo?cmd=capabilities |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
98 X-HgArg-1: foo=bar&baz=hello%20world |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
99 |
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
100 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:
29865
diff
changeset
|
101 ``httpmediatype`` server capability is present, the client should send |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
102 the newest mutually supported media type. If this capability is absent, |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
103 the client must assume the server only supports the |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
104 ``application/mercurial-0.1`` media type. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
105 |
29860
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
106 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:
29859
diff
changeset
|
107 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:
29859
diff
changeset
|
108 |
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
109 The ``application/mercurial-*`` media types indicate a generic Mercurial |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
110 data type. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
111 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
112 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:
29865
diff
changeset
|
113 predecessor of the format below. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
114 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
115 The ``application/mercurial-0.2`` media type is compression framed Mercurial |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
116 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:
29865
diff
changeset
|
117 format identifier that follows. Next are N bytes indicating the compression |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
118 format. e.g. ``zlib``. The remaining bytes are compressed according to that |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
119 compression format. The decompressed data behaves the same as with |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
120 ``application/mercurial-0.1``. |
29860
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
121 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
122 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:
29859
diff
changeset
|
123 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:
29859
diff
changeset
|
124 error. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
125 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
126 The ``application/hg-changegroup`` media type indicates a changegroup response |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
127 type. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
128 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
129 Clients also accept the ``text/plain`` media type. All other media |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
130 types should cause the client to error. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
131 |
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
132 Behavior of media types is further described in the ``Content Negotiation`` |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
133 section below. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
134 |
29860
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
135 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:
29859
diff
changeset
|
136 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:
29859
diff
changeset
|
137 |
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
138 A command returning a ``string`` response issues a |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
139 ``application/mercurial-0.*`` media type and the HTTP response body contains |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
140 the raw string value (after compression decoding, if used). A |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
141 ``Content-Length`` header is typically issued, but not required. |
29860
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
142 |
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
143 A command returning a ``stream`` response issues a |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
144 ``application/mercurial-0.*`` media type and the HTTP response is typically |
29860
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
145 using *chunked transfer* (``Transfer-Encoding: chunked``). |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
146 |
37047
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35976
diff
changeset
|
147 HTTP Version 2 Transport |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35976
diff
changeset
|
148 ------------------------ |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35976
diff
changeset
|
149 |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35976
diff
changeset
|
150 **Experimental - feature under active development** |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35976
diff
changeset
|
151 |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35976
diff
changeset
|
152 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:
35976
diff
changeset
|
153 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:
35976
diff
changeset
|
154 |
37048
fc5e261915b9
wireproto: require POST for all HTTPv2 requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37047
diff
changeset
|
155 Commands are triggered by sending HTTP POST requests against URLs of the |
37047
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35976
diff
changeset
|
156 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:
35976
diff
changeset
|
157 ``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:
35976
diff
changeset
|
158 is a named wire protocol command. |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35976
diff
changeset
|
159 |
37048
fc5e261915b9
wireproto: require POST for all HTTPv2 requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37047
diff
changeset
|
160 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:
37047
diff
changeset
|
161 405 response. |
fc5e261915b9
wireproto: require POST for all HTTPv2 requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37047
diff
changeset
|
162 |
37047
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35976
diff
changeset
|
163 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:
35976
diff
changeset
|
164 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:
35976
diff
changeset
|
165 available under the ``rw`` URL prefix. |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35976
diff
changeset
|
166 |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35976
diff
changeset
|
167 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:
35976
diff
changeset
|
168 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:
35976
diff
changeset
|
169 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:
35976
diff
changeset
|
170 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:
35976
diff
changeset
|
171 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:
35976
diff
changeset
|
172 (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:
35976
diff
changeset
|
173 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:
35976
diff
changeset
|
174 ``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:
35976
diff
changeset
|
175 RFC 7235. |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35976
diff
changeset
|
176 |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35976
diff
changeset
|
177 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:
35976
diff
changeset
|
178 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:
35976
diff
changeset
|
179 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:
35976
diff
changeset
|
180 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:
35976
diff
changeset
|
181 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:
35976
diff
changeset
|
182 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:
35976
diff
changeset
|
183 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:
35976
diff
changeset
|
184 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:
35976
diff
changeset
|
185 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:
35976
diff
changeset
|
186 |
fddcb51b5084
wireproto: define permissions-based routing of HTTPv2 wire protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35976
diff
changeset
|
187 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:
35976
diff
changeset
|
188 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:
35976
diff
changeset
|
189 |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
190 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:
37050
diff
changeset
|
191 (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:
37050
diff
changeset
|
192 body is 0 or more frames as defined by this protocol. |
37050
37d7a1d18b97
wireproto: define content negotiation for HTTPv2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37048
diff
changeset
|
193 |
37d7a1d18b97
wireproto: define content negotiation for HTTPv2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37048
diff
changeset
|
194 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:
37048
diff
changeset
|
195 ``Content-Type`` request and response headers. In addition, clients MUST |
37d7a1d18b97
wireproto: define content negotiation for HTTPv2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37048
diff
changeset
|
196 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:
37048
diff
changeset
|
197 requests. |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
198 TODO finalize the media type. For now, it is defined in wireprotoserver.py. |
37050
37d7a1d18b97
wireproto: define content negotiation for HTTPv2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37048
diff
changeset
|
199 |
37d7a1d18b97
wireproto: define content negotiation for HTTPv2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37048
diff
changeset
|
200 Servers receiving requests without an ``Accept`` header SHOULD respond with |
37d7a1d18b97
wireproto: define content negotiation for HTTPv2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37048
diff
changeset
|
201 an HTTP 406. |
37d7a1d18b97
wireproto: define content negotiation for HTTPv2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37048
diff
changeset
|
202 |
37d7a1d18b97
wireproto: define content negotiation for HTTPv2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37048
diff
changeset
|
203 Servers receiving requests with an invalid ``Content-Type`` header SHOULD |
37d7a1d18b97
wireproto: define content negotiation for HTTPv2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37048
diff
changeset
|
204 respond with an HTTP 415. |
37d7a1d18b97
wireproto: define content negotiation for HTTPv2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37048
diff
changeset
|
205 |
37059
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37057
diff
changeset
|
206 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:
37057
diff
changeset
|
207 *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:
37057
diff
changeset
|
208 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:
37057
diff
changeset
|
209 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:
37057
diff
changeset
|
210 HTTP access logs. |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37057
diff
changeset
|
211 |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37057
diff
changeset
|
212 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:
37057
diff
changeset
|
213 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:
37057
diff
changeset
|
214 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:
37057
diff
changeset
|
215 ``multirequest`` URL. (See below.) In addition, HTTP requests |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37057
diff
changeset
|
216 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:
37057
diff
changeset
|
217 ``multirequest`` URL. |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37057
diff
changeset
|
218 |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37057
diff
changeset
|
219 The ``multirequest`` command endpoints (``ro/multirequest`` and |
bbea991635d0
wireproto: service multiple command requests per HTTP request
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37057
diff
changeset
|
220 ``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:
37057
diff
changeset
|
221 *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:
37057
diff
changeset
|
222 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:
37057
diff
changeset
|
223 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:
37057
diff
changeset
|
224 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:
37057
diff
changeset
|
225 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:
37057
diff
changeset
|
226 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:
37057
diff
changeset
|
227 |
35975
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
228 SSH Protocol |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
229 ============ |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
230 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
231 Handshake |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
232 --------- |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
233 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
234 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:
35883
diff
changeset
|
235 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:
35883
diff
changeset
|
236 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:
35883
diff
changeset
|
237 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:
35883
diff
changeset
|
238 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:
35883
diff
changeset
|
239 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:
35883
diff
changeset
|
240 the connection and server are. |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
241 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
242 Preceding any response from client-issued commands, the server may print |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
243 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:
35883
diff
changeset
|
244 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:
35883
diff
changeset
|
245 such *banner* output will precede any Mercurial server output. So clients |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
246 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:
35883
diff
changeset
|
247 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:
35883
diff
changeset
|
248 wire protocol. This *banner* output should only be on stdout. However, |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
249 some servers may send output on stderr. |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
250 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
251 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:
35883
diff
changeset
|
252 having the value |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
253 ``0000000000000000000000000000000000000000-0000000000000000000000000000000000000000``. |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
254 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
255 The ``between`` command has been supported since the original Mercurial |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
256 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:
35883
diff
changeset
|
257 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:
35883
diff
changeset
|
258 followed by the value, which happens to be a newline). |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
259 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
260 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:
35883
diff
changeset
|
261 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
262 c: between\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
263 c: pairs 81\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
264 c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
265 s: 1\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
266 s: \n |
29860
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
267 |
35975
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
268 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:
35883
diff
changeset
|
269 ``between`` command. The response to this command allows clients to |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
270 discover server capabilities and settings. |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
271 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
272 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:
35883
diff
changeset
|
273 like:: |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
274 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
275 c: hello\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
276 c: between\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
277 c: pairs 81\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
278 c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
279 s: 324\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
280 s: capabilities: lookup changegroupsubset branchmap pushkey known getbundle ...\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
281 s: 1\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
282 s: \n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
283 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
284 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:
35883
diff
changeset
|
285 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
286 c: hello\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
287 c: between\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
288 c: pairs 81\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
289 c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
290 s: welcome to the server\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
291 s: if you find any issues, email someone@somewhere.com\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
292 s: 324\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
293 s: capabilities: lookup changegroupsubset branchmap pushkey known getbundle ...\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
294 s: 1\n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
295 s: \n |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
296 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
297 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:
35883
diff
changeset
|
298 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:
35883
diff
changeset
|
299 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:
35883
diff
changeset
|
300 trailing ``\n``. |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
301 |
35976
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
302 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:
35975
diff
changeset
|
303 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:
35975
diff
changeset
|
304 (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:
35975
diff
changeset
|
305 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:
35975
diff
changeset
|
306 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:
35975
diff
changeset
|
307 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:
35975
diff
changeset
|
308 server may satisfy that request immediately. |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
309 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
310 The upgrade line has the form: |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
311 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
312 upgrade <token> <transport capabilities> |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
313 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
314 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:
35975
diff
changeset
|
315 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:
35975
diff
changeset
|
316 denoting the client's transport capabilities. |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
317 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
318 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:
35975
diff
changeset
|
319 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:
35975
diff
changeset
|
320 client's MAC address.) |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
321 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
322 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:
35975
diff
changeset
|
323 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:
35975
diff
changeset
|
324 capabilities. The following capabilities are defined: |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
325 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
326 proto |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
327 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:
35975
diff
changeset
|
328 supports. e.g. ``ssh-v2``. |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
329 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
330 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:
35975
diff
changeset
|
331 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:
35975
diff
changeset
|
332 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:
35975
diff
changeset
|
333 and a non version 2 aware server: |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
334 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
335 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:
35975
diff
changeset
|
336 c: hello\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
337 c: between\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
338 c: pairs 81\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
339 c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
340 s: 0\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
341 s: 324\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
342 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:
35975
diff
changeset
|
343 s: 1\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
344 s: \n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
345 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
346 (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:
35975
diff
changeset
|
347 the unknown ``upgrade ..`` command/line.) |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
348 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
349 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:
35975
diff
changeset
|
350 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:
35975
diff
changeset
|
351 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
352 upgraded <token> <transport name>\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
353 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
354 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:
35975
diff
changeset
|
355 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:
35975
diff
changeset
|
356 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:
35975
diff
changeset
|
357 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:
35975
diff
changeset
|
358 of its ``upgrade ...`` request line. |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
359 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
360 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:
35975
diff
changeset
|
361 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:
35975
diff
changeset
|
362 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:
35975
diff
changeset
|
363 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:
35975
diff
changeset
|
364 handshake. |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
365 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
366 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:
35975
diff
changeset
|
367 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:
35975
diff
changeset
|
368 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:
35975
diff
changeset
|
369 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:
35975
diff
changeset
|
370 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:
35975
diff
changeset
|
371 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
372 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:
35975
diff
changeset
|
373 2 aware server: |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
374 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
375 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:
35975
diff
changeset
|
376 c: hello\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
377 c: between\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
378 c: pairs 81\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
379 c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
380 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:
35975
diff
changeset
|
381 s: <additional transport specific data> |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
382 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
383 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:
35975
diff
changeset
|
384 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:
35975
diff
changeset
|
385 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:
35975
diff
changeset
|
386 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:
35975
diff
changeset
|
387 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:
35975
diff
changeset
|
388 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:
35975
diff
changeset
|
389 originate from a *banner* message. |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
390 |
35975
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
391 SSH Version 1 Transport |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
392 ----------------------- |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
393 |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
394 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:
35883
diff
changeset
|
395 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:
35883
diff
changeset
|
396 SSH. |
29860
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
397 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
398 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:
29859
diff
changeset
|
399 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:
29859
diff
changeset
|
400 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:
29859
diff
changeset
|
401 a ``hg serve --stdio`` process on the remote server. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
402 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
403 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:
29859
diff
changeset
|
404 ``\n`` to the server. e.g. ``capabilities\n``. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
405 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
406 Command arguments are sent in the following format:: |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
407 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
408 <argument> <length>\n<value> |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
409 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
410 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:
29859
diff
changeset
|
411 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:
29859
diff
changeset
|
412 (``\n``) followed by the raw argument value. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
413 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
414 Dictionary arguments are encoded differently:: |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
415 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
416 <argument> <# elements>\n |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
417 <key1> <length1>\n<value1> |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
418 <key2> <length2>\n<value2> |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
419 ... |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
420 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
421 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:
29859
diff
changeset
|
422 encoded in chunks:: |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
423 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
424 <length>\n<data> |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
425 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
426 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:
29859
diff
changeset
|
427 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:
29859
diff
changeset
|
428 immediately. The special argument ``*`` in a command's definition indicates |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
429 that all argument names are allowed. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
430 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
431 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:
29859
diff
changeset
|
432 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:
29859
diff
changeset
|
433 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:
29859
diff
changeset
|
434 supplemented through the presence of *capabilities* advertised by the server. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
435 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
436 Each command has a defined expected response type. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
437 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
438 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:
29859
diff
changeset
|
439 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:
29859
diff
changeset
|
440 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:
29859
diff
changeset
|
441 ``0\n``). |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
442 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
443 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:
29859
diff
changeset
|
444 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
445 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:
29859
diff
changeset
|
446 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:
29859
diff
changeset
|
447 written to ``stdout``. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
448 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
449 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:
29859
diff
changeset
|
450 response. |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
451 |
b42c26b0a785
help: document wire protocol transport protocols
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29859
diff
changeset
|
452 The server terminates if it receives an empty command (a ``\n`` character). |
29863
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
453 |
35976
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
454 SSH Version 2 Transport |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
455 ----------------------- |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
456 |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
457 **Experimental and under development** |
35976
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
458 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
459 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:
35975
diff
changeset
|
460 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:
35975
diff
changeset
|
461 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:
35975
diff
changeset
|
462 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
463 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:
35975
diff
changeset
|
464 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:
35975
diff
changeset
|
465 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:
35975
diff
changeset
|
466 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
467 <integer length of value>\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
468 capabilities: ...\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
469 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
470 e.g. |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
471 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
472 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:
35975
diff
changeset
|
473 s: 240\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
474 s: capabilities: known getbundle batch ...\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
475 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
476 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:
35975
diff
changeset
|
477 1 of the SSH transport. |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
478 |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
479 Unified Frame-Based Protocol |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
480 ============================ |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
481 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
482 **Experimental and under development** |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
483 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
484 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:
37050
diff
changeset
|
485 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:
37050
diff
changeset
|
486 (works similarly on HTTP, SSH, etc). |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
487 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
488 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:
37050
diff
changeset
|
489 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:
37050
diff
changeset
|
490 for sending data and another for receiving. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
491 |
37288
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
492 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:
37129
diff
changeset
|
493 are conceptually similar to TCP packets. Higher-level functionality |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
494 is built on the exchange and processing of frames. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
495 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
496 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:
37129
diff
changeset
|
497 unidirectional grouping of frames. Streams facilitate two goals: |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
498 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:
37129
diff
changeset
|
499 streams below. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
500 |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
501 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:
37050
diff
changeset
|
502 the server, which issues replies to those requests. Server-initiated |
37057
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
503 messaging is not currently supported, but this specification carves |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
504 out room to implement it. |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
505 |
37057
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
506 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:
37055
diff
changeset
|
507 be logically grouped by their request ID. |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
508 |
37288
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
509 Frames begin with an 8 octet header followed by a variable length |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
510 payload:: |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
511 |
37288
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
512 +------------------------------------------------+ |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
513 | Length (24) | |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
514 +--------------------------------+---------------+ |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
515 | Request ID (16) | Stream ID (8) | |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
516 +------------------+-------------+---------------+ |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
517 | Stream Flags (8) | |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
518 +-----------+------+ |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
519 | Type (4) | |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
520 +-----------+ |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
521 | Flags (4) | |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
522 +===========+===================================================| |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
523 | Frame Payload (0...) ... |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
524 +---------------------------------------------------------------+ |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
525 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
526 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:
37050
diff
changeset
|
527 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:
37050
diff
changeset
|
528 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:
37050
diff
changeset
|
529 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:
37129
diff
changeset
|
530 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:
37129
diff
changeset
|
531 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:
37129
diff
changeset
|
532 the length is the output of that content encoding, not the input. |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
533 |
37057
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
534 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:
37055
diff
changeset
|
535 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:
37055
diff
changeset
|
536 client-initiated. Even numbered requests are server-initiated. This |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
537 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:
37055
diff
changeset
|
538 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:
37055
diff
changeset
|
539 response to client-initiated requests. Implementations are advised to |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
540 start ordering request identifiers at ``1`` and ``0``, increment by |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
541 ``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:
37055
diff
changeset
|
542 |
37288
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
543 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:
37129
diff
changeset
|
544 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:
37129
diff
changeset
|
545 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:
37129
diff
changeset
|
546 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:
37129
diff
changeset
|
547 client-initiated. Even numbered IDs are server-initiated. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
548 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
549 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:
37129
diff
changeset
|
550 See the section on streams below. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
551 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
552 The 4-bit ``Type`` field denotes the type of frame being sent. |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
553 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
554 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:
37050
diff
changeset
|
555 the frame. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
556 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
557 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:
37050
diff
changeset
|
558 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
559 Command Request (``0x01``) |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
560 -------------------------- |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
561 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
562 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:
37050
diff
changeset
|
563 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
564 The name of the command to run constitutes the entirety of the frame |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
565 payload. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
566 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
567 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:
37050
diff
changeset
|
568 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:
37050
diff
changeset
|
569 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
570 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:
37050
diff
changeset
|
571 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
572 0x01 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
573 End of command data. When set, the client will not send any command |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
574 arguments or additional command data. When set, the command has been |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
575 fully issued and the server has the full context to process the command. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
576 The next frame issued by the client is not part of this command. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
577 0x02 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
578 Command argument frames expected. When set, the client will send |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
579 *Command Argument* frames containing command argument data. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
580 0x04 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
581 Command data frames expected. When set, the client will send |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
582 *Command Data* frames containing a raw stream of data for this |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
583 command. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
584 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
585 The ``0x01`` flag is mutually exclusive with both the ``0x02`` and ``0x04`` |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
586 flags. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
587 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
588 Command Argument (``0x02``) |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
589 --------------------------- |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
590 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
591 This frame contains a named argument for a command. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
592 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
593 The 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:
37050
diff
changeset
|
594 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:
37050
diff
changeset
|
595 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
596 The payload consists of: |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
597 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
598 * A 16-bit little endian integer denoting the length of the |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
599 argument name. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
600 * A 16-bit little endian integer denoting the length of the |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
601 argument value. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
602 * N bytes of ASCII data containing the argument name. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
603 * N bytes of binary data containing the argument value. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
604 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
605 The payload MUST hold the entirety of the 32-bit header and the |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
606 argument name. The argument value MAY span multiple frames. If this |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
607 occurs, the appropriate frame flag should be set to indicate this. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
608 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
609 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:
37050
diff
changeset
|
610 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
611 0x01 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
612 Argument data continuation. When set, the data for this argument did |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
613 not fit in a single frame and the next frame will contain additional |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
614 argument data. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
615 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
616 0x02 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
617 End of arguments data. When set, the client will not send any more |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
618 command arguments for the command this frame is associated with. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
619 The next frame issued by the client will be command data or |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
620 belong to a separate request. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
621 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
622 Command Data (``0x03``) |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
623 ----------------------- |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
624 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
625 This frame contains raw data for a command. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
626 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
627 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:
37050
diff
changeset
|
628 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:
37050
diff
changeset
|
629 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:
37050
diff
changeset
|
630 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:
37050
diff
changeset
|
631 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:
37050
diff
changeset
|
632 of this data. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
633 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
634 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:
37050
diff
changeset
|
635 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:
37050
diff
changeset
|
636 is command specific. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
637 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
638 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:
37050
diff
changeset
|
639 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
640 0x01 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
641 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:
37050
diff
changeset
|
642 continues into a subsequent frame. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
643 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
644 0x02 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
645 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:
37050
diff
changeset
|
646 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:
37050
diff
changeset
|
647 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:
37050
diff
changeset
|
648 |
37055
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
649 Bytes Response Data (``0x04``) |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
650 ------------------------------ |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
651 |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
652 This frame contains raw bytes response data to an issued command. |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
653 |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
654 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:
37051
diff
changeset
|
655 |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
656 0x01 |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
657 Data continuation. When set, an additional frame containing raw |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
658 response data will follow. |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
659 0x02 |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
660 End of data. When sent, the response data has been fully sent and |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
661 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:
37051
diff
changeset
|
662 |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
663 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:
37051
diff
changeset
|
664 |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
665 Error Response (``0x05``) |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
666 ------------------------- |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
667 |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
668 An error occurred when processing a request. This could indicate |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
669 a protocol-level failure or an application level failure depending |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
670 on the flags for this message type. |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
671 |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
672 The payload for this type is an error message that should be |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
673 displayed to the user. |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
674 |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
675 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:
37051
diff
changeset
|
676 |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
677 0x01 |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
678 The error occurred at the transport/protocol level. If set, the |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
679 connection should be closed. |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
680 0x02 |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
681 The error occurred at the application level. e.g. invalid command. |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
682 |
37060
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
683 Human Output Side-Channel (``0x06``) |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
684 ------------------------------------ |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
685 |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
686 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:
37059
diff
changeset
|
687 people. Whereas most frames communicate machine readable data, this |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
688 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:
37059
diff
changeset
|
689 humans. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
690 |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
691 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:
37059
diff
changeset
|
692 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:
37059
diff
changeset
|
693 string, and labels to apply to that formatting string. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
694 |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
695 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:
37059
diff
changeset
|
696 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:
37059
diff
changeset
|
697 *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:
37059
diff
changeset
|
698 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:
37059
diff
changeset
|
699 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:
37059
diff
changeset
|
700 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:
37059
diff
changeset
|
701 their *native* settings. Similarly, the use of labels allows |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
702 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:
37059
diff
changeset
|
703 client's configured rendering settings. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
704 |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
705 Formatting strings are similar to ``printf()`` strings or how |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
706 Python's ``%`` operator works. The only supported formatting sequences |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
707 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:
37059
diff
changeset
|
708 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:
37059
diff
changeset
|
709 other 2-byte sequences beginning with ``%`` represent a literal |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
710 ``%`` followed by that character. However, future versions of the |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
711 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:
37059
diff
changeset
|
712 formatting strings with additional formatters, hence why ``%%`` is |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
713 required to represent the literal ``%``. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
714 |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
715 The raw frame consists of a series of data structures representing |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
716 textual atoms to print. Each atom begins with a struct defining the |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
717 size of the data that follows: |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
718 |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
719 * A 16-bit little endian unsigned integer denoting the length of the |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
720 formatting string. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
721 * An 8-bit unsigned integer denoting the number of label strings |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
722 that follow. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
723 * An 8-bit unsigned integer denoting the number of formatting string |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
724 arguments strings that follow. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
725 * An array of 8-bit unsigned integers denoting the lengths of |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
726 *labels* data. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
727 * An array of 16-bit unsigned integers denoting the lengths of |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
728 formatting strings. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
729 * The formatting string, encoded as UTF-8. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
730 * 0 or more ASCII strings defining labels to apply to this atom. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
731 * 0 or more UTF-8 strings that will be used as arguments to the |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
732 formatting string. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
733 |
37129
aaabd709df72
wireproto: review fixups
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
734 TODO use ASCII for formatting string. |
aaabd709df72
wireproto: review fixups
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
735 |
37060
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
736 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:
37059
diff
changeset
|
737 does not support spanning data across multiple frames. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
738 |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
739 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:
37059
diff
changeset
|
740 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:
37059
diff
changeset
|
741 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:
37059
diff
changeset
|
742 |
37291
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
743 Progress Update (``0x07``) |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
744 -------------------------- |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
745 |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
746 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
|
747 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
|
748 completion times, etc. |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
749 |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
750 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
|
751 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
|
752 |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
753 topic |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
754 Topic name (string) |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
755 pos |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
756 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
|
757 total |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
758 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
|
759 label (optional) |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
760 Unit label (string) |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
761 item (optional) |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
762 Item name (string) |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
763 |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
764 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
|
765 *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
|
766 *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
|
767 position of that topic as ``-1``. |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
768 |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
769 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
|
770 |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
771 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
|
772 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
|
773 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
|
774 |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
775 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
|
776 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
|
777 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
|
778 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
|
779 SHOULD be ASCII. |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
780 |
37288
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
781 Stream Encoding Settings (``0x08``) |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
782 ----------------------------------- |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
783 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
784 This frame type holds information defining the content encoding |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
785 settings for a *stream*. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
786 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
787 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:
37129
diff
changeset
|
788 passed on to applications. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
789 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
790 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:
37129
diff
changeset
|
791 ``Stream Flag`` set. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
792 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
793 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:
37129
diff
changeset
|
794 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:
37129
diff
changeset
|
795 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
796 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:
37129
diff
changeset
|
797 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:
37129
diff
changeset
|
798 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:
37129
diff
changeset
|
799 profile for supplemental settings definitions. See the section below |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
800 on defined encoding profiles. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
801 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
802 Stream States and Flags |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
803 ----------------------- |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
804 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
805 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:
37129
diff
changeset
|
806 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:
37129
diff
changeset
|
807 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:
37129
diff
changeset
|
808 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:
37129
diff
changeset
|
809 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:
37129
diff
changeset
|
810 state by default. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
811 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
812 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:
37129
diff
changeset
|
813 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:
37129
diff
changeset
|
814 are defined: |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
815 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
816 0x01 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
817 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:
37129
diff
changeset
|
818 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:
37129
diff
changeset
|
819 becomes ``open``. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
820 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
821 0x02 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
822 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:
37129
diff
changeset
|
823 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:
37129
diff
changeset
|
824 ``closed``. Any content encoding context associated with this stream |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
825 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:
37129
diff
changeset
|
826 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
827 0x04 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
828 Apply content encoding. When set, any content encoding settings |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
829 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:
37129
diff
changeset
|
830 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:
37129
diff
changeset
|
831 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
832 Streams |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
833 ------- |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
834 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
835 Streams - along with ``Request IDs`` - facilitate grouping of frames. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
836 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:
37129
diff
changeset
|
837 constitute are independent. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
838 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
839 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:
37129
diff
changeset
|
840 request a frame is associated with. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
841 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
842 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:
37129
diff
changeset
|
843 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:
37129
diff
changeset
|
844 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
845 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:
37129
diff
changeset
|
846 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:
37129
diff
changeset
|
847 server. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
848 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
849 There is no strict hierarchical relationship between ``Request IDs`` |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
850 and *streams*. A stream can contain frames having multiple |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
851 ``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:
37129
diff
changeset
|
852 span multiple streams. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
853 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
854 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:
37129
diff
changeset
|
855 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:
37129
diff
changeset
|
856 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:
37129
diff
changeset
|
857 zstandard compression operation and the receiving end may decompress |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
858 that payload to obtain the original data. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
859 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
860 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:
37129
diff
changeset
|
861 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:
37129
diff
changeset
|
862 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:
37129
diff
changeset
|
863 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:
37129
diff
changeset
|
864 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:
37129
diff
changeset
|
865 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:
37129
diff
changeset
|
866 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:
37129
diff
changeset
|
867 threads. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
868 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
869 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:
37129
diff
changeset
|
870 *worker thread* could perform potentially CPU bound work concurrently |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
871 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:
37129
diff
changeset
|
872 sub-protocol / stream level eliminates a potential resource constraint |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
873 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:
37129
diff
changeset
|
874 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:
37129
diff
changeset
|
875 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
876 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:
37129
diff
changeset
|
877 facilitates the use of advanced data compression techniques. For |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
878 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:
37129
diff
changeset
|
879 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:
37129
diff
changeset
|
880 compression settings to trade CPU for compression ratio accordingly. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
881 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
882 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:
37129
diff
changeset
|
883 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:
37129
diff
changeset
|
884 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:
37129
diff
changeset
|
885 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:
37129
diff
changeset
|
886 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:
37129
diff
changeset
|
887 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:
37129
diff
changeset
|
888 involving potentially expensive encoding overhead. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
889 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
890 Content Encoding Profiles |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
891 ------------------------- |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
892 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
893 Streams can have named content encoding *profiles* associated with |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
894 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:
37129
diff
changeset
|
895 settings and behavior. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
896 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
897 The following profiles are defined: |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
898 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
899 TBD |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
900 |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
901 Issuing Commands |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
902 ---------------- |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
903 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
904 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:
37050
diff
changeset
|
905 frames defining that command. This logical stream is composed of |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
906 1 ``Command Request`` frame, 0 or more ``Command Argument`` frames, |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
907 and 0 or more ``Command Data`` frames. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
908 |
37057
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
909 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:
37055
diff
changeset
|
910 the same ``Request ID``. |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
911 |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
912 Clients MAY send additional command requests without waiting on the |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
913 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:
37055
diff
changeset
|
914 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:
37055
diff
changeset
|
915 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:
37055
diff
changeset
|
916 fully received. |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
917 |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
918 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:
37055
diff
changeset
|
919 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:
37055
diff
changeset
|
920 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:
37055
diff
changeset
|
921 received, or MAY execute multiple commands concurrently. |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
922 |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
923 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:
37055
diff
changeset
|
924 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:
37055
diff
changeset
|
925 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:
37055
diff
changeset
|
926 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:
37055
diff
changeset
|
927 been received. |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
928 TODO think about whether we should express dependencies between commands |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
929 to avoid roundtrip latency. |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
930 |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
931 Argument frames are the recommended mechanism for transferring fixed |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
932 sets of parameters to a command. Data frames are appropriate for |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
933 transferring variable data. A similar comparison would be to HTTP: |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
934 argument frames are headers and the message body is data frames. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
935 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
936 It is recommended for servers to delay the dispatch of a command |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
937 until all argument frames for that command have been received. Servers |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
938 MAY impose limits on the maximum argument size. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
939 TODO define failure mechanism. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
940 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
941 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:
37050
diff
changeset
|
942 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:
37050
diff
changeset
|
943 |
29863
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
944 Capabilities |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
945 ============ |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
946 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
947 Servers advertise supported wire protocol features. This allows clients to |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
948 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:
29860
diff
changeset
|
949 specific argument. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
950 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
951 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:
29860
diff
changeset
|
952 space-delimited string of tokens/features. Some features are single words |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
953 like ``lookup`` or ``batch``. Others are complicated key-value pairs |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
954 advertising sub-features. e.g. ``httpheader=2048``. When complex, non-word |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
955 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:
29860
diff
changeset
|
956 Comma-delimited and ``x-www-form-urlencoded`` values are common. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
957 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
958 The following document capabilities defined by the canonical Mercurial server |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
959 implementation. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
960 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
961 batch |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
962 ----- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
963 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
964 Whether the server supports the ``batch`` command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
965 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
966 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:
29860
diff
changeset
|
967 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
968 branchmap |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
969 --------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
970 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
971 Whether the server supports the ``branchmap`` command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
972 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
973 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:
29860
diff
changeset
|
974 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
975 bundle2-exp |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
976 ----------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
977 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
978 Precursor to ``bundle2`` capability that was used before bundle2 was a |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
979 stable feature. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
980 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
981 This capability was introduced in Mercurial 3.0 behind an experimental |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
982 flag. This capability should not be observed in the wild. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
983 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
984 bundle2 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
985 ------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
986 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
987 Indicates whether the server supports the ``bundle2`` data exchange format. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
988 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
989 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:
29860
diff
changeset
|
990 list of keys or key-value pairs. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
991 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
992 A key is simply a URL encoded string. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
993 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
994 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:
29860
diff
changeset
|
995 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:
29860
diff
changeset
|
996 URL encoding. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
997 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
998 For example, say we have the values:: |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
999 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1000 {'HG20': [], 'changegroup': ['01', '02'], 'digests': ['sha1', 'sha512']} |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1001 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1002 We would first construct a string:: |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1003 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1004 HG20\nchangegroup=01,02\ndigests=sha1,sha512 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1005 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1006 We would then URL quote this string:: |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1007 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1008 HG20%0Achangegroup%3D01%2C02%0Adigests%3Dsha1%2Csha512 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1009 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1010 This capability was introduced in Mercurial 3.4 (released May 2015). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1011 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1012 changegroupsubset |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1013 ----------------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1014 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1015 Whether the server supports the ``changegroupsubset`` command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1016 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1017 This capability was introduced in Mercurial 0.9.2 (released December |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1018 2006). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1019 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1020 This capability was introduced at the same time as the ``lookup`` |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1021 capability/command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1022 |
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1023 compression |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1024 ----------- |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1025 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1026 Declares support for negotiating compression formats. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1027 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1028 Presence of this capability indicates the server supports dynamic selection |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1029 of compression formats based on the client request. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1030 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1031 Servers advertising this capability are required to support the |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1032 ``application/mercurial-0.2`` media type in response to commands returning |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1033 streams. Servers may support this media type on any command. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1034 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1035 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:
29865
diff
changeset
|
1036 supported compression formats. The order of the compression formats is in |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1037 server-preferred order, most preferred first. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1038 |
30761
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1039 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
|
1040 |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1041 bzip2 |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1042 bzip2 |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1043 none |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1044 uncompressed / raw data |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1045 zlib |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1046 zlib (no gzip header) |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1047 zstd |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1048 zstd |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1049 |
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1050 This capability was introduced in Mercurial 4.1 (released February 2017). |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1051 |
29863
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1052 getbundle |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1053 --------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1054 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1055 Whether the server supports the ``getbundle`` command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1056 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1057 This capability was introduced in Mercurial 1.9 (released July 2011). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1058 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1059 httpheader |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1060 ---------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1061 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1062 Whether the server supports receiving command arguments via HTTP request |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1063 headers. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1064 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1065 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:
29860
diff
changeset
|
1066 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:
29860
diff
changeset
|
1067 comma in the value, as this is reserved for future use. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1068 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1069 This capability was introduced in Mercurial 1.9 (released July 2011). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1070 |
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1071 httpmediatype |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1072 ------------- |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1073 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1074 Indicates which HTTP media types (``Content-Type`` header) the server is |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1075 capable of receiving and sending. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1076 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1077 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:
29865
diff
changeset
|
1078 support for media type and transmission direction. The following strings may |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1079 be present: |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1080 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1081 0.1rx |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1082 Indicates server support for receiving ``application/mercurial-0.1`` media |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1083 types. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1084 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1085 0.1tx |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1086 Indicates server support for sending ``application/mercurial-0.1`` media |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1087 types. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1088 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1089 0.2rx |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1090 Indicates server support for receiving ``application/mercurial-0.2`` media |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1091 types. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1092 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1093 0.2tx |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1094 Indicates server support for sending ``application/mercurial-0.2`` media |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1095 types. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1096 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1097 minrx=X |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1098 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:
29865
diff
changeset
|
1099 string like ``0.2``. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1100 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1101 This capability can be used by servers to limit connections from legacy |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1102 clients not using the latest supported media type. However, only clients |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1103 with knowledge of this capability will know to consult this value. This |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1104 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:
29865
diff
changeset
|
1105 when the server has locked out a legacy client. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1106 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1107 mintx=X |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1108 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:
29865
diff
changeset
|
1109 string like ``0.1``. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1110 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1111 Servers advertising support for the ``application/mercurial-0.2`` media type |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1112 should also advertise the ``compression`` capability. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1113 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1114 This capability was introduced in Mercurial 4.1 (released February 2017). |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1115 |
29863
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1116 httppostargs |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1117 ------------ |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1118 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1119 **Experimental** |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1120 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1121 Indicates that the server supports and prefers clients send command arguments |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1122 via a HTTP POST request as part of the request body. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1123 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1124 This capability was introduced in Mercurial 3.8 (released May 2016). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1125 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1126 known |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1127 ----- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1128 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1129 Whether the server supports the ``known`` command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1130 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1131 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:
29860
diff
changeset
|
1132 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1133 lookup |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1134 ------ |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1135 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1136 Whether the server supports the ``lookup`` command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1137 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1138 This capability was introduced in Mercurial 0.9.2 (released December |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1139 2006). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1140 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1141 This capability was introduced at the same time as the ``changegroupsubset`` |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1142 capability/command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1143 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1144 pushkey |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1145 ------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1146 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1147 Whether the server supports the ``pushkey`` and ``listkeys`` commands. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1148 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1149 This capability was introduced in Mercurial 1.6 (released July 2010). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1150 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1151 standardbundle |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1152 -------------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1153 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1154 **Unsupported** |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1155 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1156 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:
29860
diff
changeset
|
1157 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:
29860
diff
changeset
|
1158 capability. This capability should not be encountered in the wild. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1159 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1160 stream-preferred |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1161 ---------------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1162 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1163 If present the server prefers that clients clone using the streaming clone |
34393
fffd3369aa83
commands: rename clone --uncompressed to --stream and document
Gregory Szorc <gregory.szorc@gmail.com>
parents:
32133
diff
changeset
|
1164 protocol (``hg clone --stream``) rather than the standard |
29863
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1165 changegroup/bundle based protocol. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1166 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1167 This capability was introduced in Mercurial 2.2 (released May 2012). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1168 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1169 streamreqs |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1170 ---------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1171 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1172 Indicates whether the server supports *streaming clones* and the *requirements* |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1173 that clients must support to receive it. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1174 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1175 If present, the server supports the ``stream_out`` command, which transmits |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1176 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:
29860
diff
changeset
|
1177 cloning mechanism at the expense of more bandwidth used. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1178 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1179 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:
29860
diff
changeset
|
1180 *requirements*. These are requirements that impact the reading of data in |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1181 the ``.hg/store`` directory. An example value is |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1182 ``streamreqs=generaldelta,revlogv1`` indicating the server repo requires |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1183 the ``revlogv1`` and ``generaldelta`` requirements. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1184 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1185 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:
29860
diff
changeset
|
1186 ``stream`` capability instead of the ``streamreqs`` capability. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1187 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1188 This capability was introduced in Mercurial 1.7 (released November 2010). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1189 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1190 stream |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1191 ------ |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1192 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1193 Whether the server supports *streaming clones* from ``revlogv1`` repos. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1194 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1195 If present, the server supports the ``stream_out`` command, which transmits |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1196 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:
29860
diff
changeset
|
1197 cloning mechanism at the expense of more bandwidth used. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1198 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1199 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:
29860
diff
changeset
|
1200 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1201 When initially introduced, the value of the capability was the numeric |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1202 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:
29860
diff
changeset
|
1203 ``revlogv1``. This simple integer value wasn't powerful enough, so the |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1204 ``streamreqs`` capability was invented to handle cases where the repo |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1205 requirements have more than just ``revlogv1``. Newer servers omit the |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1206 ``=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:
29860
diff
changeset
|
1207 be implied by clients. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1208 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1209 unbundlehash |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1210 ------------ |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1211 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1212 Whether the ``unbundle`` commands supports receiving a hash of all the |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1213 heads instead of a list. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1214 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1215 For more, see the documentation for the ``unbundle`` command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1216 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1217 This capability was introduced in Mercurial 1.9 (released July 2011). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1218 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1219 unbundle |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1220 -------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1221 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1222 Whether the server supports pushing via the ``unbundle`` command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1223 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1224 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:
29860
diff
changeset
|
1225 July 2006). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1226 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1227 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:
29860
diff
changeset
|
1228 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:
29860
diff
changeset
|
1229 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:
29860
diff
changeset
|
1230 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:
29860
diff
changeset
|
1231 most preferred type. |
29864
f0d47aca1d47
help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29863
diff
changeset
|
1232 |
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1233 Content Negotiation |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1234 =================== |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1235 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1236 The wire protocol has some mechanisms to help peers determine what content |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1237 types and encoding the other side will accept. Historically, these mechanisms |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1238 have been built into commands themselves because most commands only send a |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1239 well-defined response type and only certain commands needed to support |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1240 functionality like compression. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1241 |
35975
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
1242 Currently, only the HTTP version 1 transport supports content negotiation |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
1243 at the protocol layer. |
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1244 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1245 HTTP requests advertise supported response formats via the ``X-HgProto-<N>`` |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1246 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:
29865
diff
changeset
|
1247 value to span multiple headers. This value consists of a list of |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1248 space-delimited parameters. Each parameter denotes a feature or capability. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1249 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1250 The following parameters are defined: |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1251 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1252 0.1 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1253 Indicates the client supports receiving ``application/mercurial-0.1`` |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1254 responses. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1255 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1256 0.2 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1257 Indicates the client supports receiving ``application/mercurial-0.2`` |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1258 responses. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1259 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1260 comp |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1261 Indicates compression formats the client can decode. Value is a list of |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1262 comma delimited strings identifying compression formats ordered from |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1263 most preferential to least preferential. e.g. ``comp=zstd,zlib,none``. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1264 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1265 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:
29865
diff
changeset
|
1266 is defined, as support for ``application/mercurial-0.2`` or greater is |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1267 required to use arbitrary compression formats. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1268 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1269 If this parameter is not advertised, the server interprets this as |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1270 equivalent to ``zlib,none``. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1271 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1272 Clients may choose to only send this header if the ``httpmediatype`` |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1273 server capability is present, as currently all server-side features |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1274 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:
29865
diff
changeset
|
1275 advertised via the ``httpmediatype`` capability. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1276 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1277 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:
29865
diff
changeset
|
1278 value of ``0.1``. This is compatible with legacy clients. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1279 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1280 A server receiving a request indicating support for multiple media type |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1281 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:
29865
diff
changeset
|
1282 may support all media types on all commands. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1283 |
29865
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1284 Commands |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1285 ======== |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1286 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1287 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:
29864
diff
changeset
|
1288 the canonical Mercurial server. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1289 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1290 batch |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1291 ----- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1292 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1293 Issue multiple commands while sending a single command request. The purpose |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1294 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:
29864
diff
changeset
|
1295 multiple round trips to the server therefore enabling commands to complete |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1296 quicker. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1297 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1298 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:
29864
diff
changeset
|
1299 execute. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1300 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1301 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:
29864
diff
changeset
|
1302 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:
29864
diff
changeset
|
1303 followed by an argument string. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1304 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1305 The argument string is a ``,`` delimited list of ``<key>=<value>`` values |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1306 corresponding to command arguments. Both the argument name and value are |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1307 escaped using a special substitution map:: |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1308 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1309 : -> :c |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1310 , -> :o |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1311 ; -> :s |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1312 = -> :e |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1313 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1314 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:
29864
diff
changeset
|
1315 ``;`` delimited list of responses for each requested command. Each value |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1316 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:
29864
diff
changeset
|
1317 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1318 If an error occurs, the generic error response may be sent. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1319 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1320 between |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1321 ------- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1322 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1323 (Legacy command used for discovery in old clients) |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1324 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1325 Obtain nodes between pairs of nodes. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1326 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1327 The ``pairs`` arguments contains a space-delimited list of ``-`` delimited |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1328 hex node pairs. e.g.:: |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1329 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1330 a072279d3f7fd3a4aa7ffa1a5af8efc573e1c896-6dc58916e7c070f678682bfe404d2e2d68291a18 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1331 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1332 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:
29864
diff
changeset
|
1333 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:
29864
diff
changeset
|
1334 A newline ``\n`` terminates each line, including the last one. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1335 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1336 branchmap |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1337 --------- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1338 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1339 Obtain heads in named branches. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1340 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1341 Accepts no arguments. Return type is a ``string``. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1342 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1343 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:
29864
diff
changeset
|
1344 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:
29864
diff
changeset
|
1345 e.g.:: |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1346 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1347 default a072279d3f7fd3a4aa7ffa1a5af8efc573e1c896 6dc58916e7c070f678682bfe404d2e2d68291a18 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1348 stable baae3bf31522f41dd5e6d7377d0edd8d1cf3fccc |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1349 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1350 There is no trailing newline. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1351 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1352 branches |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1353 -------- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1354 |
32133
435a3842ca3a
internals: document that "branches" is a legacy wire command
Siddharth Agarwal <sid0@fb.com>
parents:
30761
diff
changeset
|
1355 (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
|
1356 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
|
1357 |
29865
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1358 Obtain ancestor changesets of specific nodes back to a branch point. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1359 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1360 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:
29864
diff
changeset
|
1361 Instead, it is related to DAG branches. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1362 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1363 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:
29864
diff
changeset
|
1364 hex nodes. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1365 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1366 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:
29864
diff
changeset
|
1367 a DAG root or is a merge. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1368 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1369 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:
29864
diff
changeset
|
1370 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:
29864
diff
changeset
|
1371 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:
29864
diff
changeset
|
1372 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:
29864
diff
changeset
|
1373 node). |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1374 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1375 capabilities |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1376 ------------ |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1377 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1378 Obtain the capabilities string for the repo. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1379 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1380 Unlike the ``hello`` command, the capabilities string is not prefixed. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1381 There is no trailing newline. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1382 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1383 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:
29864
diff
changeset
|
1384 |
35883
0d8024be7166
internals: document when "hello" and "capabilities" commands were added
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35267
diff
changeset
|
1385 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:
35267
diff
changeset
|
1386 |
29865
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1387 changegroup |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1388 ----------- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1389 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1390 (Legacy command: use ``getbundle`` instead) |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1391 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1392 Obtain a changegroup version 1 with data for changesets that are |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1393 descendants of client-specified changesets. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1394 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1395 The ``roots`` arguments contains a list of space-delimited hex nodes. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1396 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1397 The server responds with a changegroup version 1 containing all |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1398 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:
29864
diff
changeset
|
1399 at the time of the request. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1400 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1401 The return type is a ``stream``. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1402 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1403 changegroupsubset |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1404 ----------------- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1405 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1406 (Legacy command: use ``getbundle`` instead) |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1407 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1408 Obtain a changegroup version 1 with data for changesetsets between |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1409 client specified base and head nodes. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1410 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1411 The ``bases`` argument contains a list of space-delimited hex nodes. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1412 The ``heads`` argument contains a list of space-delimited hex nodes. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1413 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1414 The server responds with a changegroup version 1 containing all |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1415 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:
29864
diff
changeset
|
1416 request. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1417 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1418 The return type is a ``stream``. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1419 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1420 clonebundles |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1421 ------------ |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1422 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1423 Obtains a manifest of bundle URLs available to seed clones. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1424 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1425 Each returned line contains a URL followed by metadata. See the |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1426 documentation in the ``clonebundles`` extension for more. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1427 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1428 The return type is a ``string``. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1429 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1430 getbundle |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1431 --------- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1432 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1433 Obtain a bundle containing repository data. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1434 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1435 This command accepts the following arguments: |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1436 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1437 heads |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1438 List of space-delimited hex nodes of heads to retrieve. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1439 common |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1440 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:
29864
diff
changeset
|
1441 server. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1442 obsmarkers |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1443 Boolean indicating whether to include obsolescence markers as part |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1444 of the response. Only works with bundle2. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1445 bundlecaps |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1446 Comma-delimited set of strings defining client bundle capabilities. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1447 listkeys |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1448 Comma-delimited list of strings of ``pushkey`` namespaces. For each |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1449 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:
29864
diff
changeset
|
1450 that namespace. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1451 cg |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1452 Boolean indicating whether changegroup data is requested. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1453 cbattempted |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1454 Boolean indicating whether the client attempted to use the *clone bundles* |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1455 feature before performing this request. |
35267
cb4dcd7fabe7
getbundle: add support for 'bookmarks' boolean argument
Boris Feld <boris.feld@octobus.net>
parents:
34930
diff
changeset
|
1456 bookmarks |
cb4dcd7fabe7
getbundle: add support for 'bookmarks' boolean argument
Boris Feld <boris.feld@octobus.net>
parents:
34930
diff
changeset
|
1457 Boolean indicating whether bookmark data is requested. |
34930
28baeab476cc
internal-doc: document the 'phases' parameters to 'getbundle'
Boris Feld <boris.feld@octobus.net>
parents:
34393
diff
changeset
|
1458 phases |
28baeab476cc
internal-doc: document the 'phases' parameters to 'getbundle'
Boris Feld <boris.feld@octobus.net>
parents:
34393
diff
changeset
|
1459 Boolean indicating whether phases data is requested. |
29865
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1460 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1461 The return type on success is a ``stream`` where the value is bundle. |
35975
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
1462 On the HTTP version 1 transport, the response is zlib compressed. |
29865
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1463 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1464 If an error occurs, a generic error response can be sent. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1465 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1466 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:
29864
diff
changeset
|
1467 bundle contains a changegroup with the nodes between the specified ``common`` |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1468 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:
29864
diff
changeset
|
1469 of the returned bundle can vary significantly. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1470 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1471 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:
29864
diff
changeset
|
1472 ``01`` response. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1473 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1474 If the ``bundlecaps`` provided by the client contain a value beginning |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1475 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:
29864
diff
changeset
|
1476 additional repository data, such as ``pushkey`` namespace values. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1477 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1478 heads |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1479 ----- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1480 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1481 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:
29864
diff
changeset
|
1482 by a newline. e.g. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1483 ``a9eeb3adc7ddb5006c088e9eda61791c777cbf7c 31f91a3da534dc849f0d6bfc00a395a97cf218a1\n`` |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1484 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1485 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:
29864
diff
changeset
|
1486 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1487 hello |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1488 ----- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1489 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1490 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:
29864
diff
changeset
|
1491 like format. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1492 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1493 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:
29864
diff
changeset
|
1494 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1495 capabilities: <value> |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1496 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1497 See above for more about the capabilities string. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1498 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1499 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:
29864
diff
changeset
|
1500 established. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1501 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1502 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:
29864
diff
changeset
|
1503 |
35883
0d8024be7166
internals: document when "hello" and "capabilities" commands were added
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35267
diff
changeset
|
1504 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:
35267
diff
changeset
|
1505 |
29865
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1506 listkeys |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1507 -------- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1508 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1509 List values in a specified ``pushkey`` namespace. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1510 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1511 The ``namespace`` argument defines the pushkey namespace to operate on. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1512 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1513 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:
29864
diff
changeset
|
1514 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1515 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:
29864
diff
changeset
|
1516 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:
29864
diff
changeset
|
1517 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1518 lookup |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1519 ------ |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1520 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1521 Try to resolve a value to a known repository revision. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1522 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1523 The ``key`` argument is converted from bytes to an |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1524 ``encoding.localstr`` instance then passed into |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1525 ``localrepository.__getitem__`` in an attempt to resolve it. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1526 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1527 The return type is a ``string``. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1528 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1529 Upon successful resolution, returns ``1 <hex node>\n``. On failure, |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1530 returns ``0 <error string>\n``. e.g.:: |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1531 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1532 1 273ce12ad8f155317b2c078ec75a4eba507f1fba\n |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1533 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1534 0 unknown revision 'foo'\n |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1535 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1536 known |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1537 ----- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1538 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1539 Determine whether multiple nodes are known. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1540 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1541 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:
29864
diff
changeset
|
1542 for existence. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1543 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1544 The return type is ``string``. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1545 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1546 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:
29864
diff
changeset
|
1547 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:
29864
diff
changeset
|
1548 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:
29864
diff
changeset
|
1549 will be present at byte offset N. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1550 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1551 There is no trailing newline. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1552 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1553 pushkey |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1554 ------- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1555 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1556 Set a value using the ``pushkey`` protocol. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1557 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1558 Accepts arguments ``namespace``, ``key``, ``old``, and ``new``, which |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1559 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:
29864
diff
changeset
|
1560 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:
29864
diff
changeset
|
1561 All arguments are string types. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1562 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1563 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:
29864
diff
changeset
|
1564 |
35975
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
1565 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:
35883
diff
changeset
|
1566 newline (``\n``) which indicates operation result. The server may send |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
1567 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:
35883
diff
changeset
|
1568 user. |
29865
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1569 |
35975
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
1570 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:
35883
diff
changeset
|
1571 newline followed by additional server output that should be displayed to |
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
1572 the user. This may include output from hooks, etc. |
29865
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1573 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1574 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:
29864
diff
changeset
|
1575 and there should be additional output to display to the user. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1576 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1577 stream_out |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1578 ---------- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1579 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1580 Obtain *streaming clone* data. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1581 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1582 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:
29864
diff
changeset
|
1583 whether the request was fulfilled properly. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1584 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1585 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:
29864
diff
changeset
|
1586 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:
29864
diff
changeset
|
1587 ``stream`` capability is set before making the request. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1588 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1589 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:
29864
diff
changeset
|
1590 repository to generate data. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1591 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1592 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:
29864
diff
changeset
|
1593 contains 2 space-delimited integers corresponding to the path count and |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1594 payload size, respectively:: |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1595 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1596 <path count> <payload size>\n |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1597 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1598 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:
29864
diff
changeset
|
1599 the size of the per-path header lines. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1600 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1601 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:
29864
diff
changeset
|
1602 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:
29864
diff
changeset
|
1603 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1604 <store path>\0<size>\n |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1605 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1606 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:
29864
diff
changeset
|
1607 ``<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:
29864
diff
changeset
|
1608 newline. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1609 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1610 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:
29864
diff
changeset
|
1611 reading after ``<path count>`` entries are consumed. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1612 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1613 unbundle |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1614 -------- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1615 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1616 Send a bundle containing data (usually changegroup data) to the server. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1617 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1618 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:
29864
diff
changeset
|
1619 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:
29864
diff
changeset
|
1620 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:
29864
diff
changeset
|
1621 too much work or a client transfers too much data. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1622 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1623 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:
29864
diff
changeset
|
1624 similarly to as if :hg:`unbundle` were called. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1625 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1626 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:
29864
diff
changeset
|
1627 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:
29864
diff
changeset
|
1628 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:
29864
diff
changeset
|
1629 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:
29864
diff
changeset
|
1630 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:
29864
diff
changeset
|
1631 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:
29864
diff
changeset
|
1632 is 1 fewer head. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1633 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1634 The encoding of the ``push response`` type varies by transport. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1635 |
35975
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
1636 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:
35883
diff
changeset
|
1637 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:
35883
diff
changeset
|
1638 e.g. ``1\n2``. So the full response might be ``0\n1\n2``. |
29865
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1639 |
35975
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
1640 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:
35883
diff
changeset
|
1641 of an integer result value followed by a newline (``\n``) followed by string |
29865
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1642 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:
29864
diff
changeset
|
1643 hooks, etc). |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1644 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1645 In some cases, the server may respond with a ``bundle2`` bundle. In this |
35975
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
1646 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:
35883
diff
changeset
|
1647 response is zlib compressed. |
29865
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1648 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1649 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:
29864
diff
changeset
|
1650 indicating the failure. |