Mercurial > hg
annotate mercurial/help/internals/wireprotocol.txt @ 37487:68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Differential Revision: https://phab.mercurial-scm.org/D3181
author | Gregory Szorc <gregory.szorc@gmail.com> |
---|---|
date | Wed, 28 Mar 2018 16:00:02 -0700 |
parents | 6847542bb8d7 |
children | 3b99eb028859 |
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 |
37393
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
454 If the server announces support for the ``protocaps`` capability, the client |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
455 should issue a ``protocaps`` command after the initial handshake to annonunce |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
456 its own capabilities. The client capabilities are persistent. |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
457 |
35976
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
458 SSH Version 2 Transport |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
459 ----------------------- |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
460 |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
461 **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
|
462 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
463 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
|
464 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
|
465 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
|
466 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
467 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
|
468 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
|
469 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
|
470 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
471 <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
|
472 capabilities: ...\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
473 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
474 e.g. |
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 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
|
477 s: 240\n |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
478 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
|
479 |
48a3a9283f09
sshpeer: initial definition and implementation of new SSH protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35975
diff
changeset
|
480 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
|
481 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
|
482 |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
483 Unified Frame-Based Protocol |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
484 ============================ |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
485 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
486 **Experimental and under development** |
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 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
|
489 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
|
490 (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
|
491 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
492 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
|
493 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
|
494 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
|
495 |
37288
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
496 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
|
497 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
|
498 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
|
499 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
500 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
|
501 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
|
502 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
|
503 streams below. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
504 |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
505 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
|
506 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
|
507 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
|
508 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
|
509 |
37057
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
510 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
|
511 be logically grouped by their request ID. |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
512 |
37288
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
513 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
|
514 payload:: |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
515 |
37288
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 | Length (24) | |
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 | Request ID (16) | Stream ID (8) | |
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 | Stream Flags (8) | |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
522 +-----------+------+ |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
523 | Type (4) | |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
524 +-----------+ |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
525 | Flags (4) | |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
526 +===========+===================================================| |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
527 | Frame Payload (0...) ... |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
528 +---------------------------------------------------------------+ |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
529 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
530 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
|
531 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
|
532 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
|
533 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
|
534 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
|
535 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
|
536 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
|
537 |
37057
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
538 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
|
539 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
|
540 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
|
541 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
|
542 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
|
543 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
|
544 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
|
545 ``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
|
546 |
37288
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
547 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
|
548 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
|
549 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
|
550 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
|
551 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
|
552 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
553 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
|
554 See the section on streams below. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
555 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
556 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
|
557 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
558 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
|
559 the frame. |
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 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
|
562 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
563 Command Request (``0x01``) |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
564 -------------------------- |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
565 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
566 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
|
567 |
37292
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
568 The payload consists of a CBOR map defining the command request. The |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
569 bytestring keys of that map are: |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
570 |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
571 name |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
572 Name of the command that should be executed (bytestring). |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
573 args |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
574 Map of bytestring keys to various value types containing the named |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
575 arguments to this command. |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
576 |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
577 Each command defines its own set of argument names and their expected |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
578 types. |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
579 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
580 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
|
581 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
|
582 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
583 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
|
584 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
585 0x01 |
37292
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
586 New command request. When set, this frame represents the beginning |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
587 of a new request to run a command. The ``Request ID`` attached to this |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
588 frame MUST NOT be active. |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
589 0x02 |
37292
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
590 Command request continuation. When set, this frame is a continuation |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
591 from a previous command request frame for its ``Request ID``. This |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
592 flag is set when the CBOR data for a command request does not fit |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
593 in a single frame. |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
594 0x04 |
37292
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
595 Additional frames expected. When set, the command request didn't fit |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
596 into a single frame and additional CBOR data follows in a subsequent |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
597 frame. |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
598 0x08 |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
599 Command data frames expected. When set, command data frames are |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
600 expected to follow the final command request frame for this request. |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
601 |
37292
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
602 ``0x01`` MUST be set on the initial command request frame for a |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
603 ``Request ID``. |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
604 |
37292
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
605 ``0x01`` or ``0x02`` MUST be set to indicate this frame's role in |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
606 a series of command request frames. |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
607 |
37292
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
608 If command data frames are to be sent, ``0x10`` MUST be set on ALL |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
609 command request frames. |
37051
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 Command Data (``0x03``) |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
612 ----------------------- |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
613 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
614 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
|
615 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
616 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
|
617 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
|
618 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
|
619 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
|
620 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
|
621 of this data. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
622 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
623 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
|
624 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
|
625 is command specific. |
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 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
|
628 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
629 0x01 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
630 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
|
631 continues into a subsequent frame. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
632 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
633 0x02 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
634 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
|
635 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
|
636 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
|
637 |
37299
e9aadee698cf
wireproto: add frame flag to denote payloads as CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37292
diff
changeset
|
638 Response Data (``0x04``) |
e9aadee698cf
wireproto: add frame flag to denote payloads as CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37292
diff
changeset
|
639 ------------------------ |
37055
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
640 |
37299
e9aadee698cf
wireproto: add frame flag to denote payloads as CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37292
diff
changeset
|
641 This frame contains raw response data to an issued command. |
37055
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
642 |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
643 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
|
644 |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
645 0x01 |
37299
e9aadee698cf
wireproto: add frame flag to denote payloads as CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37292
diff
changeset
|
646 Data continuation. When set, an additional frame containing response data |
e9aadee698cf
wireproto: add frame flag to denote payloads as CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37292
diff
changeset
|
647 will follow. |
37055
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
648 0x02 |
37299
e9aadee698cf
wireproto: add frame flag to denote payloads as CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37292
diff
changeset
|
649 End of data. When set, the response data has been fully sent and |
37055
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
650 no additional frames for this response will be sent. |
37299
e9aadee698cf
wireproto: add frame flag to denote payloads as CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37292
diff
changeset
|
651 0x04 |
e9aadee698cf
wireproto: add frame flag to denote payloads as CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37292
diff
changeset
|
652 CBOR data. When set, the frame payload consists of CBOR data. |
37055
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 ``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
|
655 |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
656 Error Response (``0x05``) |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
657 ------------------------- |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
658 |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
659 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
|
660 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
|
661 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
|
662 |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
663 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
|
664 displayed to the user. |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
665 |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
666 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
|
667 |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
668 0x01 |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
669 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
|
670 connection should be closed. |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
671 0x02 |
61393f888dfe
wireproto: define and implement responses in framing protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37051
diff
changeset
|
672 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
|
673 |
37060
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
674 Human Output Side-Channel (``0x06``) |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
675 ------------------------------------ |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
676 |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
677 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
|
678 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
|
679 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
|
680 humans. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
681 |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
682 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
|
683 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
|
684 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
|
685 |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
686 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
|
687 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
|
688 *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
|
689 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
|
690 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
|
691 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
|
692 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
|
693 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
|
694 client's configured rendering settings. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
695 |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
696 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
|
697 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
|
698 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
|
699 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
|
700 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
|
701 ``%`` 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
|
702 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
|
703 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
|
704 required to represent the literal ``%``. |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
705 |
37319
36d17f37db91
wireproto: convert human output frames to CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37299
diff
changeset
|
706 The frame payload consists of a CBOR array of CBOR maps. Each map |
36d17f37db91
wireproto: convert human output frames to CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37299
diff
changeset
|
707 defines an *atom* of text data to print. Each *atom* has the following |
36d17f37db91
wireproto: convert human output frames to CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37299
diff
changeset
|
708 bytestring keys: |
37060
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
709 |
37319
36d17f37db91
wireproto: convert human output frames to CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37299
diff
changeset
|
710 msg |
36d17f37db91
wireproto: convert human output frames to CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37299
diff
changeset
|
711 (bytestring) The formatting string. Content MUST be ASCII. |
36d17f37db91
wireproto: convert human output frames to CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37299
diff
changeset
|
712 args (optional) |
36d17f37db91
wireproto: convert human output frames to CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37299
diff
changeset
|
713 Array of bytestrings defining arguments to the formatting string. |
36d17f37db91
wireproto: convert human output frames to CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37299
diff
changeset
|
714 labels (optional) |
36d17f37db91
wireproto: convert human output frames to CBOR
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37299
diff
changeset
|
715 Array of bytestrings defining labels to apply to this atom. |
37129
aaabd709df72
wireproto: review fixups
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37060
diff
changeset
|
716 |
37060
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
717 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
|
718 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
|
719 |
0a6c5cc09a88
wireproto: define human output side channel frame
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37059
diff
changeset
|
720 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
|
721 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
|
722 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
|
723 |
37291
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
724 Progress Update (``0x07``) |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
725 -------------------------- |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
726 |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
727 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
|
728 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
|
729 completion times, etc. |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
730 |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
731 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
|
732 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
|
733 |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
734 topic |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
735 Topic name (string) |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
736 pos |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
737 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
|
738 total |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
739 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
|
740 label (optional) |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
741 Unit label (string) |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
742 item (optional) |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
743 Item name (string) |
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 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
|
746 *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
|
747 *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
|
748 position of that topic as ``-1``. |
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 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
|
751 |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
752 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
|
753 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
|
754 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
|
755 |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
756 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
|
757 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
|
758 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
|
759 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
|
760 SHOULD be ASCII. |
b0041036214e
wireproto: define frame to represent progress updates
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37288
diff
changeset
|
761 |
37288
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
762 Stream Encoding Settings (``0x08``) |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
763 ----------------------------------- |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
764 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
765 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
|
766 settings for a *stream*. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
767 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
768 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
|
769 passed on to applications. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
770 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
771 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
|
772 ``Stream Flag`` set. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
773 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
774 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
|
775 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
|
776 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
777 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
|
778 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
|
779 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
|
780 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
|
781 on defined encoding profiles. |
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 Stream States and Flags |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
784 ----------------------- |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
785 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
786 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
|
787 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
|
788 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
|
789 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
|
790 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
|
791 state by default. |
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 ``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
|
794 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
|
795 are defined: |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
796 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
797 0x01 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
798 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
|
799 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
|
800 becomes ``open``. |
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 0x02 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
803 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
|
804 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
|
805 ``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
|
806 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
|
807 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
808 0x04 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
809 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
|
810 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
|
811 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
|
812 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
813 Streams |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
814 ------- |
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 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
|
817 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
|
818 constitute are independent. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
819 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
820 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
|
821 request a frame is associated with. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
822 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
823 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
|
824 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
|
825 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
826 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
|
827 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
|
828 server. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
829 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
830 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
|
831 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
|
832 ``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
|
833 span multiple streams. |
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 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
|
836 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
|
837 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
|
838 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
|
839 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
|
840 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
841 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
|
842 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
|
843 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
|
844 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
|
845 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
|
846 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
|
847 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
|
848 threads. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
849 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
850 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
|
851 *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
|
852 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
|
853 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
|
854 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
|
855 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
|
856 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
857 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
|
858 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
|
859 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
|
860 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
|
861 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
|
862 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
863 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
|
864 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
|
865 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
|
866 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
|
867 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
|
868 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
|
869 involving potentially expensive encoding overhead. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
870 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
871 Content Encoding Profiles |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
872 ------------------------- |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
873 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
874 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
|
875 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
|
876 settings and behavior. |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
877 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
878 The following profiles are defined: |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
879 |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
880 TBD |
9bfcbe4f4745
wireproto: add streams to frame-based protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37129
diff
changeset
|
881 |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
882 Issuing Commands |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
883 ---------------- |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
884 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
885 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
|
886 frames defining that command. This logical stream is composed of |
37292
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
887 1 or more ``Command Request`` frames and and 0 or more ``Command Data`` |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
888 frames. |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
889 |
37057
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
890 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
|
891 the same ``Request ID``. |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
892 |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
893 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
|
894 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
|
895 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
|
896 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
|
897 fully received. |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
898 |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
899 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
|
900 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
|
901 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
|
902 received, or MAY execute multiple commands concurrently. |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
903 |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
904 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
|
905 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
|
906 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
|
907 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
|
908 been received. |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
909 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
|
910 to avoid roundtrip latency. |
2ec1fb9de638
wireproto: add request IDs to frames
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37055
diff
changeset
|
911 |
37292
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
912 A command is defined by a command name, 0 or more command arguments, |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
913 and optional command data. |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
914 |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
915 Arguments are the recommended mechanism for transferring fixed sets of |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
916 parameters to a command. Data is appropriate for transferring variable |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
917 data. Thinking in terms of HTTP, arguments would be headers and data |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
918 would be the message body. |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
919 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
920 It is recommended for servers to delay the dispatch of a command |
37292
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
921 until all argument have been received. Servers MAY impose limits on the |
3d0e2cd86e05
wireproto: use CBOR for command requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37291
diff
changeset
|
922 maximum argument size. |
37051
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
923 TODO define failure mechanism. |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
924 |
40206e227412
wireproto: define and implement protocol for issuing requests
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37050
diff
changeset
|
925 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
|
926 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
|
927 |
29863
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
928 Capabilities |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
929 ============ |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
930 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
931 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
|
932 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
|
933 specific argument. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
934 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
935 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
|
936 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
|
937 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
|
938 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
|
939 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
|
940 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
|
941 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
942 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
|
943 implementation. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
944 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
945 batch |
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 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
948 Whether the server supports the ``batch`` command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
949 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
950 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
|
951 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
952 branchmap |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
953 --------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
954 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
955 Whether the server supports the ``branchmap`` command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
956 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
957 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
|
958 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
959 bundle2-exp |
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 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
962 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
|
963 stable feature. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
964 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
965 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
|
966 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
|
967 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
968 bundle2 |
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 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
|
972 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
973 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
|
974 list of keys or key-value pairs. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
975 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
976 A key is simply a URL encoded string. |
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 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
|
979 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
|
980 URL encoding. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
981 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
982 For example, say we have the values:: |
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 {'HG20': [], 'changegroup': ['01', '02'], 'digests': ['sha1', 'sha512']} |
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 We would first construct a string:: |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
987 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
988 HG20\nchangegroup=01,02\ndigests=sha1,sha512 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
989 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
990 We would then URL quote this string:: |
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 HG20%0Achangegroup%3D01%2C02%0Adigests%3Dsha1%2Csha512 |
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 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
|
995 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
996 changegroupsubset |
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 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
999 Whether the server supports the ``changegroupsubset`` command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1000 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1001 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
|
1002 2006). |
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 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
|
1005 capability/command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1006 |
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1007 compression |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1008 ----------- |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1009 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1010 Declares support for negotiating compression formats. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1011 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1012 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
|
1013 of compression formats based on the client request. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1014 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1015 Servers advertising this capability are required to support the |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1016 ``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
|
1017 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
|
1018 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1019 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
|
1020 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
|
1021 server-preferred order, most preferred first. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1022 |
30761
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1023 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
|
1024 |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1025 bzip2 |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1026 bzip2 |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1027 none |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1028 uncompressed / raw data |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1029 zlib |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1030 zlib (no gzip header) |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1031 zstd |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1032 zstd |
7283719e2bfd
util: declare wire protocol support of compression engines
Gregory Szorc <gregory.szorc@gmail.com>
parents:
30760
diff
changeset
|
1033 |
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1034 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
|
1035 |
29863
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1036 getbundle |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1037 --------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1038 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1039 Whether the server supports the ``getbundle`` command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1040 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1041 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
|
1042 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1043 httpheader |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1044 ---------- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1045 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1046 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
|
1047 headers. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1048 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1049 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
|
1050 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
|
1051 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
|
1052 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1053 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
|
1054 |
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1055 httpmediatype |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1056 ------------- |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1057 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1058 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
|
1059 capable of receiving and sending. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1060 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1061 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
|
1062 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
|
1063 be present: |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1064 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1065 0.1rx |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1066 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
|
1067 types. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1068 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1069 0.1tx |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1070 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
|
1071 types. |
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 0.2rx |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1074 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
|
1075 types. |
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 0.2tx |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1078 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
|
1079 types. |
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 minrx=X |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1082 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
|
1083 string like ``0.2``. |
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 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
|
1086 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
|
1087 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
|
1088 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
|
1089 when the server has locked out a legacy client. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1090 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1091 mintx=X |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1092 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
|
1093 string like ``0.1``. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1094 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1095 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
|
1096 should also advertise the ``compression`` capability. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1097 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1098 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
|
1099 |
29863
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1100 httppostargs |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1101 ------------ |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1102 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1103 **Experimental** |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1104 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1105 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
|
1106 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
|
1107 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1108 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
|
1109 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1110 known |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1111 ----- |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1112 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1113 Whether the server supports the ``known`` command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1114 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1115 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
|
1116 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1117 lookup |
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 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1120 Whether the server supports the ``lookup`` command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1121 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1122 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
|
1123 2006). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1124 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1125 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
|
1126 capability/command. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1127 |
37393
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1128 protocaps |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1129 --------- |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1130 |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1131 Whether the server supports the ``protocaps`` command for SSH V1 transport. |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1132 |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1133 This capability was introduced in Mercurial 4.6. |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1134 |
29863
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1135 pushkey |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1136 ------- |
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 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
|
1139 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1140 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
|
1141 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1142 standardbundle |
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 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1145 **Unsupported** |
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 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
|
1148 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
|
1149 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
|
1150 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1151 stream-preferred |
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 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
|
1155 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
|
1156 changegroup/bundle based protocol. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1157 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1158 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
|
1159 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1160 streamreqs |
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 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
|
1164 that clients must support to receive it. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1165 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1166 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
|
1167 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
|
1168 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
|
1169 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1170 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
|
1171 *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
|
1172 the ``.hg/store`` directory. An example value is |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1173 ``streamreqs=generaldelta,revlogv1`` indicating the server repo requires |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1174 the ``revlogv1`` and ``generaldelta`` requirements. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1175 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1176 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
|
1177 ``stream`` capability instead of the ``streamreqs`` capability. |
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 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
|
1180 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1181 stream |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1182 ------ |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1183 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1184 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
|
1185 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1186 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
|
1187 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
|
1188 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
|
1189 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1190 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
|
1191 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1192 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
|
1193 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
|
1194 ``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
|
1195 ``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
|
1196 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
|
1197 ``=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
|
1198 be implied by clients. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1199 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1200 unbundlehash |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1201 ------------ |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1202 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1203 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
|
1204 heads instead of a list. |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1205 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1206 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
|
1207 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1208 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
|
1209 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1210 unbundle |
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 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1213 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
|
1214 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1215 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
|
1216 July 2006). |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1217 |
2435ba6c82e6
help: document wire protocol capabilities
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29860
diff
changeset
|
1218 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
|
1219 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
|
1220 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
|
1221 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
|
1222 most preferred type. |
29864
f0d47aca1d47
help: document wire protocol "handshake" protocol
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29863
diff
changeset
|
1223 |
30760
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1224 Content Negotiation |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1225 =================== |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1226 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1227 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
|
1228 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
|
1229 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
|
1230 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
|
1231 functionality like compression. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1232 |
35975
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
1233 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
|
1234 at the protocol layer. |
30760
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 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
|
1237 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
|
1238 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
|
1239 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
|
1240 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1241 The following parameters are defined: |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1242 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1243 0.1 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1244 Indicates the client supports receiving ``application/mercurial-0.1`` |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1245 responses. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1246 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1247 0.2 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1248 Indicates the client supports receiving ``application/mercurial-0.2`` |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1249 responses. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1250 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1251 comp |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1252 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
|
1253 comma delimited strings identifying compression formats ordered from |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1254 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
|
1255 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1256 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
|
1257 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
|
1258 required to use arbitrary compression formats. |
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 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
|
1261 equivalent to ``zlib,none``. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1262 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1263 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
|
1264 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
|
1265 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
|
1266 advertised via the ``httpmediatype`` capability. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1267 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1268 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
|
1269 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
|
1270 |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1271 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
|
1272 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
|
1273 may support all media types on all commands. |
753b9d43ca81
internals: document compression negotiation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29865
diff
changeset
|
1274 |
29865
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1275 Commands |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1276 ======== |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1277 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1278 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
|
1279 the canonical Mercurial server. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1280 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1281 batch |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1282 ----- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1283 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1284 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
|
1285 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
|
1286 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
|
1287 quicker. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1288 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1289 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
|
1290 execute. |
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 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
|
1293 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
|
1294 followed by an argument string. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1295 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1296 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
|
1297 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
|
1298 escaped using a special substitution map:: |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1299 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1300 : -> :c |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1301 , -> :o |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1302 ; -> :s |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1303 = -> :e |
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 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
|
1306 ``;`` 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
|
1307 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
|
1308 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1309 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
|
1310 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1311 between |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1312 ------- |
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 (Legacy command used for discovery in old clients) |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1315 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1316 Obtain nodes between pairs of nodes. |
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 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
|
1319 hex node pairs. e.g.:: |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1320 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1321 a072279d3f7fd3a4aa7ffa1a5af8efc573e1c896-6dc58916e7c070f678682bfe404d2e2d68291a18 |
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 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
|
1324 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
|
1325 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
|
1326 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1327 branchmap |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1328 --------- |
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 Obtain heads in named branches. |
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 Accepts no arguments. Return type is a ``string``. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1333 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1334 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
|
1335 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
|
1336 e.g.:: |
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 default a072279d3f7fd3a4aa7ffa1a5af8efc573e1c896 6dc58916e7c070f678682bfe404d2e2d68291a18 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1339 stable baae3bf31522f41dd5e6d7377d0edd8d1cf3fccc |
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 There is no trailing newline. |
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 branches |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1344 -------- |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1345 |
32133
435a3842ca3a
internals: document that "branches" is a legacy wire command
Siddharth Agarwal <sid0@fb.com>
parents:
30761
diff
changeset
|
1346 (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
|
1347 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
|
1348 |
29865
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1349 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
|
1350 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1351 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
|
1352 Instead, it is related to DAG 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 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
|
1355 hex nodes. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1356 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1357 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
|
1358 a DAG root or is a merge. |
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 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
|
1361 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
|
1362 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
|
1363 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
|
1364 node). |
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 capabilities |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1367 ------------ |
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 Obtain the capabilities string for the repo. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1370 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1371 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
|
1372 There is no trailing newline. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1373 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1374 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
|
1375 |
35883
0d8024be7166
internals: document when "hello" and "capabilities" commands were added
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35267
diff
changeset
|
1376 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
|
1377 |
29865
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1378 changegroup |
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 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1381 (Legacy command: use ``getbundle`` instead) |
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 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
|
1384 descendants of client-specified changesets. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1385 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1386 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
|
1387 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1388 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
|
1389 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
|
1390 at the time of the request. |
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 The return type is a ``stream``. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1393 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1394 changegroupsubset |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1395 ----------------- |
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 (Legacy command: use ``getbundle`` instead) |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1398 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1399 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
|
1400 client specified base and head nodes. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1401 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1402 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
|
1403 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
|
1404 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1405 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
|
1406 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
|
1407 request. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1408 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1409 The return type is a ``stream``. |
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 clonebundles |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1412 ------------ |
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 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
|
1415 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1416 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
|
1417 documentation in the ``clonebundles`` extension for more. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1418 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1419 The return type is a ``string``. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1420 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1421 getbundle |
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 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1424 Obtain a bundle containing repository data. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1425 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1426 This command accepts the following arguments: |
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 heads |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1429 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
|
1430 common |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1431 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
|
1432 server. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1433 obsmarkers |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1434 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
|
1435 of the response. Only works with bundle2. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1436 bundlecaps |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1437 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
|
1438 listkeys |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1439 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
|
1440 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
|
1441 that namespace. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1442 cg |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1443 Boolean indicating whether changegroup data is requested. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1444 cbattempted |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1445 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
|
1446 feature before performing this request. |
35267
cb4dcd7fabe7
getbundle: add support for 'bookmarks' boolean argument
Boris Feld <boris.feld@octobus.net>
parents:
34930
diff
changeset
|
1447 bookmarks |
cb4dcd7fabe7
getbundle: add support for 'bookmarks' boolean argument
Boris Feld <boris.feld@octobus.net>
parents:
34930
diff
changeset
|
1448 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
|
1449 phases |
28baeab476cc
internal-doc: document the 'phases' parameters to 'getbundle'
Boris Feld <boris.feld@octobus.net>
parents:
34393
diff
changeset
|
1450 Boolean indicating whether phases data is requested. |
29865
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1451 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1452 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
|
1453 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
|
1454 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1455 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
|
1456 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1457 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
|
1458 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
|
1459 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
|
1460 of the returned bundle can vary significantly. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1461 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1462 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
|
1463 ``01`` response. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1464 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1465 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
|
1466 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
|
1467 additional repository data, such as ``pushkey`` namespace values. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1468 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1469 heads |
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 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1472 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
|
1473 by a newline. e.g. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1474 ``a9eeb3adc7ddb5006c088e9eda61791c777cbf7c 31f91a3da534dc849f0d6bfc00a395a97cf218a1\n`` |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1475 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1476 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
|
1477 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1478 hello |
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 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
|
1482 like format. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1483 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1484 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
|
1485 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1486 capabilities: <value> |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1487 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1488 See above for more about the capabilities string. |
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 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
|
1491 established. |
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 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
|
1494 |
35883
0d8024be7166
internals: document when "hello" and "capabilities" commands were added
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35267
diff
changeset
|
1495 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
|
1496 |
29865
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1497 listkeys |
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 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1500 List values in a specified ``pushkey`` namespace. |
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 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
|
1503 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1504 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
|
1505 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1506 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
|
1507 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
|
1508 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1509 lookup |
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 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1512 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
|
1513 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1514 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
|
1515 ``encoding.localstr`` instance then passed into |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1516 ``localrepository.__getitem__`` in an attempt to resolve it. |
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 The return type is a ``string``. |
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 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
|
1521 returns ``0 <error string>\n``. e.g.:: |
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 1 273ce12ad8f155317b2c078ec75a4eba507f1fba\n |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1524 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1525 0 unknown revision 'foo'\n |
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 known |
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 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1530 Determine whether multiple nodes are known. |
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 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
|
1533 for existence. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1534 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1535 The return type is ``string``. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1536 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1537 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
|
1538 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
|
1539 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
|
1540 will be present at byte offset N. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1541 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1542 There is no trailing newline. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1543 |
37393
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1544 protocaps |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1545 --------- |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1546 |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1547 Notify the server about the client capabilities in the SSH V1 transport |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1548 protocol. |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1549 |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1550 The ``caps`` argument is a space-delimited list of capabilities. |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1551 |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1552 The server will reply with the string ``OK``. |
afcfdf53e4b5
wireproto: provide accessors for client capabilities
Joerg Sonnenberger <joerg@bec.de>
parents:
37319
diff
changeset
|
1553 |
29865
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1554 pushkey |
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 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1557 Set a value using the ``pushkey`` protocol. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1558 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1559 Accepts arguments ``namespace``, ``key``, ``old``, and ``new``, which |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1560 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
|
1561 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
|
1562 All arguments are string types. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1563 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1564 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
|
1565 |
35975
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
1566 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
|
1567 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
|
1568 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
|
1569 user. |
29865
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1570 |
35975
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
1571 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
|
1572 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
|
1573 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
|
1574 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1575 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
|
1576 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
|
1577 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1578 stream_out |
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 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1581 Obtain *streaming clone* data. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1582 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1583 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
|
1584 whether the request was fulfilled properly. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1585 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1586 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
|
1587 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
|
1588 ``stream`` capability is set before making the request. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1589 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1590 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
|
1591 repository to generate data. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1592 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1593 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
|
1594 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
|
1595 payload size, respectively:: |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1596 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1597 <path count> <payload size>\n |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1598 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1599 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
|
1600 the size of the per-path header lines. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1601 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1602 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
|
1603 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
|
1604 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1605 <store path>\0<size>\n |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1606 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1607 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
|
1608 ``<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
|
1609 newline. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1610 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1611 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
|
1612 reading after ``<path count>`` entries are consumed. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1613 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1614 unbundle |
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 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1617 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
|
1618 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1619 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
|
1620 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
|
1621 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
|
1622 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
|
1623 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1624 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
|
1625 similarly to as if :hg:`unbundle` were called. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1626 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1627 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
|
1628 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
|
1629 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
|
1630 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
|
1631 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
|
1632 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
|
1633 is 1 fewer head. |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1634 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1635 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
|
1636 |
35975
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
1637 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
|
1638 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
|
1639 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
|
1640 |
35975
40d94ea51402
internals: refactor wire protocol documentation
Gregory Szorc <gregory.szorc@gmail.com>
parents:
35883
diff
changeset
|
1641 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
|
1642 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
|
1643 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
|
1644 hooks, etc). |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1645 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1646 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
|
1647 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
|
1648 response is zlib compressed. |
29865
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1649 |
80c11c1a64bf
help: document wire protocol commands
Gregory Szorc <gregory.szorc@gmail.com>
parents:
29864
diff
changeset
|
1650 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
|
1651 indicating the failure. |
37485
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1652 |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1653 Frame-Based Protocol Commands |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1654 ============================= |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1655 |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1656 **Experimental and under active development** |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1657 |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1658 This section documents the wire protocol commands exposed to transports |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1659 using the frame-based protocol. The set of commands exposed through |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1660 these transports is distinct from the set of commands exposed to legacy |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1661 transports. |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1662 |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1663 The frame-based protocol uses CBOR to encode command execution requests. |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1664 All command arguments must be mapped to a specific or set of CBOR data |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1665 types. |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1666 |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1667 The response to many commands is also CBOR. There is no common response |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1668 format: each command defines its own response format. |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1669 |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1670 TODO require node type be specified, as N bytes of binary node value |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1671 could be ambiguous once SHA-1 is replaced. |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1672 |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1673 heads |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1674 ----- |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1675 |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1676 Obtain DAG heads in the repository. |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1677 |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1678 The command accepts the following arguments: |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1679 |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1680 publiconly (optional) |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1681 (boolean) If set, operate on the DAG for public phase changesets only. |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1682 Non-public (i.e. draft) phase DAG heads will not be returned. |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1683 |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1684 The response is a CBOR array of bytestrings defining changeset nodes |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1685 of DAG heads. The array can be empty if the repository is empty or no |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1686 changesets satisfied the request. |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1687 |
0b7475ea38cf
wireproto: port heads command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37393
diff
changeset
|
1688 TODO consider exposing phase of heads in response |
37486
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1689 |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1690 known |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1691 ----- |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1692 |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1693 Determine whether a series of changeset nodes is known to the server. |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1694 |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1695 The command accepts the following arguments: |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1696 |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1697 nodes |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1698 (array of bytestrings) List of changeset nodes whose presence to |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1699 query. |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1700 |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1701 The response is a bytestring where each byte contains a 0 or 1 for the |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1702 corresponding requested node at the same index. |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1703 |
6847542bb8d7
wireproto: port keep command to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37485
diff
changeset
|
1704 TODO use a bit array for even more compact response |
37487
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1705 |
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1706 listkeys |
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1707 -------- |
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1708 |
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1709 List values in a specified ``pushkey`` namespace. |
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1710 |
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1711 The command receives the following arguments: |
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1712 |
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1713 namespace |
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1714 (bytestring) Pushkey namespace to query. |
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1715 |
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1716 The response is a map with bytestring keys and values. |
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1717 |
68915b9f8e96
wireproto: port listkeys commands to wire protocol v2
Gregory Szorc <gregory.szorc@gmail.com>
parents:
37486
diff
changeset
|
1718 TODO consider using binary to represent nodes in certain pushkey namespaces. |