annotate mercurial/help/internals/wireprotocol.txt @ 37291:b0041036214e

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