##// END OF EJS Templates
wireproto: port keep command to wire protocol v2...
Gregory Szorc -
r37504:6847542b default
parent child Browse files
Show More
@@ -0,0 +1,121 b''
1 $ . $TESTDIR/wireprotohelpers.sh
2
3 $ hg init server
4 $ enablehttpv2 server
5 $ cd server
6 $ hg debugdrawdag << EOF
7 > C D
8 > |/
9 > B
10 > |
11 > A
12 > EOF
13
14 $ hg log -T '{rev}:{node} {desc}\n'
15 3:be0ef73c17ade3fc89dc41701eb9fc3a91b58282 D
16 2:26805aba1e600a82e93661149f2313866a221a7b C
17 1:112478962961147124edd43549aedd1a335e44bf B
18 0:426bada5c67598ca65036d57d9e4b64b0c1ce7a0 A
19
20 $ hg serve -p $HGPORT -d --pid-file hg.pid -E error.log
21 $ cat hg.pid > $DAEMON_PIDS
22
23 No arguments returns something reasonable
24
25 $ sendhttpv2peer << EOF
26 > command known
27 > EOF
28 creating http peer for wire protocol version 2
29 sending known command
30 s> POST /api/exp-http-v2-0001/ro/known HTTP/1.1\r\n
31 s> Accept-Encoding: identity\r\n
32 s> accept: application/mercurial-exp-framing-0003\r\n
33 s> content-type: application/mercurial-exp-framing-0003\r\n
34 s> content-length: 20\r\n
35 s> host: $LOCALIP:$HGPORT\r\n (glob)
36 s> user-agent: Mercurial debugwireproto\r\n
37 s> \r\n
38 s> \x0c\x00\x00\x01\x00\x01\x01\x11\xa1DnameEknown
39 s> makefile('rb', None)
40 s> HTTP/1.1 200 OK\r\n
41 s> Server: testing stub value\r\n
42 s> Date: $HTTP_DATE$\r\n
43 s> Content-Type: application/mercurial-exp-framing-0003\r\n
44 s> Transfer-Encoding: chunked\r\n
45 s> \r\n
46 s> 9\r\n
47 s> \x01\x00\x00\x01\x00\x02\x01F
48 s> @
49 s> \r\n
50 received frame(size=1; request=1; stream=2; streamflags=stream-begin; type=bytes-response; flags=eos|cbor)
51 s> 0\r\n
52 s> \r\n
53 response: []
54
55 Single known node works
56
57 $ sendhttpv2peer << EOF
58 > command known
59 > nodes eval:[b'\x42\x6b\xad\xa5\xc6\x75\x98\xca\x65\x03\x6d\x57\xd9\xe4\xb6\x4b\x0c\x1c\xe7\xa0']
60 > EOF
61 creating http peer for wire protocol version 2
62 sending known command
63 s> POST /api/exp-http-v2-0001/ro/known HTTP/1.1\r\n
64 s> Accept-Encoding: identity\r\n
65 s> accept: application/mercurial-exp-framing-0003\r\n
66 s> content-type: application/mercurial-exp-framing-0003\r\n
67 s> content-length: 54\r\n
68 s> host: $LOCALIP:$HGPORT\r\n (glob)
69 s> user-agent: Mercurial debugwireproto\r\n
70 s> \r\n
71 s> .\x00\x00\x01\x00\x01\x01\x11\xa2Dargs\xa1Enodes\x81TBk\xad\xa5\xc6u\x98\xcae\x03mW\xd9\xe4\xb6K\x0c\x1c\xe7\xa0DnameEknown
72 s> makefile('rb', None)
73 s> HTTP/1.1 200 OK\r\n
74 s> Server: testing stub value\r\n
75 s> Date: $HTTP_DATE$\r\n
76 s> Content-Type: application/mercurial-exp-framing-0003\r\n
77 s> Transfer-Encoding: chunked\r\n
78 s> \r\n
79 s> a\r\n
80 s> \x02\x00\x00\x01\x00\x02\x01F
81 s> A1
82 s> \r\n
83 received frame(size=2; request=1; stream=2; streamflags=stream-begin; type=bytes-response; flags=eos|cbor)
84 s> 0\r\n
85 s> \r\n
86 response: [b'1']
87
88 Multiple nodes works
89
90 $ sendhttpv2peer << EOF
91 > command known
92 > nodes eval:[b'\x42\x6b\xad\xa5\xc6\x75\x98\xca\x65\x03\x6d\x57\xd9\xe4\xb6\x4b\x0c\x1c\xe7\xa0', b'00000000000000000000', b'\x11\x24\x78\x96\x29\x61\x14\x71\x24\xed\xd4\x35\x49\xae\xdd\x1a\x33\x5e\x44\xbf']
93 > EOF
94 creating http peer for wire protocol version 2
95 sending known command
96 s> POST /api/exp-http-v2-0001/ro/known HTTP/1.1\r\n
97 s> Accept-Encoding: identity\r\n
98 s> accept: application/mercurial-exp-framing-0003\r\n
99 s> content-type: application/mercurial-exp-framing-0003\r\n
100 s> content-length: 96\r\n
101 s> host: $LOCALIP:$HGPORT\r\n (glob)
102 s> user-agent: Mercurial debugwireproto\r\n
103 s> \r\n
104 s> X\x00\x00\x01\x00\x01\x01\x11\xa2Dargs\xa1Enodes\x83TBk\xad\xa5\xc6u\x98\xcae\x03mW\xd9\xe4\xb6K\x0c\x1c\xe7\xa0T00000000000000000000T\x11$x\x96)a\x14q$\xed\xd45I\xae\xdd\x1a3^D\xbfDnameEknown
105 s> makefile('rb', None)
106 s> HTTP/1.1 200 OK\r\n
107 s> Server: testing stub value\r\n
108 s> Date: $HTTP_DATE$\r\n
109 s> Content-Type: application/mercurial-exp-framing-0003\r\n
110 s> Transfer-Encoding: chunked\r\n
111 s> \r\n
112 s> c\r\n
113 s> \x04\x00\x00\x01\x00\x02\x01F
114 s> C101
115 s> \r\n
116 received frame(size=4; request=1; stream=2; streamflags=stream-begin; type=bytes-response; flags=eos|cbor)
117 s> 0\r\n
118 s> \r\n
119 response: [b'101']
120
121 $ cat error.log
@@ -1,1688 +1,1704 b''
1 The Mercurial wire protocol is a request-response based protocol
1 The Mercurial wire protocol is a request-response based protocol
2 with multiple wire representations.
2 with multiple wire representations.
3
3
4 Each request is modeled as a command name, a dictionary of arguments, and
4 Each request is modeled as a command name, a dictionary of arguments, and
5 optional raw input. Command arguments and their types are intrinsic
5 optional raw input. Command arguments and their types are intrinsic
6 properties of commands. So is the response type of the command. This means
6 properties of commands. So is the response type of the command. This means
7 clients can't always send arbitrary arguments to servers and servers can't
7 clients can't always send arbitrary arguments to servers and servers can't
8 return multiple response types.
8 return multiple response types.
9
9
10 The protocol is synchronous and does not support multiplexing (concurrent
10 The protocol is synchronous and does not support multiplexing (concurrent
11 commands).
11 commands).
12
12
13 Handshake
13 Handshake
14 =========
14 =========
15
15
16 It is required or common for clients to perform a *handshake* when connecting
16 It is required or common for clients to perform a *handshake* when connecting
17 to a server. The handshake serves the following purposes:
17 to a server. The handshake serves the following purposes:
18
18
19 * Negotiating protocol/transport level options
19 * Negotiating protocol/transport level options
20 * Allows the client to learn about server capabilities to influence
20 * Allows the client to learn about server capabilities to influence
21 future requests
21 future requests
22 * Ensures the underlying transport channel is in a *clean* state
22 * Ensures the underlying transport channel is in a *clean* state
23
23
24 An important goal of the handshake is to allow clients to use more modern
24 An important goal of the handshake is to allow clients to use more modern
25 wire protocol features. By default, clients must assume they are talking
25 wire protocol features. By default, clients must assume they are talking
26 to an old version of Mercurial server (possibly even the very first
26 to an old version of Mercurial server (possibly even the very first
27 implementation). So, clients should not attempt to call or utilize modern
27 implementation). So, clients should not attempt to call or utilize modern
28 wire protocol features until they have confirmation that the server
28 wire protocol features until they have confirmation that the server
29 supports them. The handshake implementation is designed to allow both
29 supports them. The handshake implementation is designed to allow both
30 ends to utilize the latest set of features and capabilities with as
30 ends to utilize the latest set of features and capabilities with as
31 few round trips as possible.
31 few round trips as possible.
32
32
33 The handshake mechanism varies by transport and protocol and is documented
33 The handshake mechanism varies by transport and protocol and is documented
34 in the sections below.
34 in the sections below.
35
35
36 HTTP Protocol
36 HTTP Protocol
37 =============
37 =============
38
38
39 Handshake
39 Handshake
40 ---------
40 ---------
41
41
42 The client sends a ``capabilities`` command request (``?cmd=capabilities``)
42 The client sends a ``capabilities`` command request (``?cmd=capabilities``)
43 as soon as HTTP requests may be issued.
43 as soon as HTTP requests may be issued.
44
44
45 The server responds with a capabilities string, which the client parses to
45 The server responds with a capabilities string, which the client parses to
46 learn about the server's abilities.
46 learn about the server's abilities.
47
47
48 HTTP Version 1 Transport
48 HTTP Version 1 Transport
49 ------------------------
49 ------------------------
50
50
51 Commands are issued as HTTP/1.0 or HTTP/1.1 requests. Commands are
51 Commands are issued as HTTP/1.0 or HTTP/1.1 requests. Commands are
52 sent to the base URL of the repository with the command name sent in
52 sent to the base URL of the repository with the command name sent in
53 the ``cmd`` query string parameter. e.g.
53 the ``cmd`` query string parameter. e.g.
54 ``https://example.com/repo?cmd=capabilities``. The HTTP method is ``GET``
54 ``https://example.com/repo?cmd=capabilities``. The HTTP method is ``GET``
55 or ``POST`` depending on the command and whether there is a request
55 or ``POST`` depending on the command and whether there is a request
56 body.
56 body.
57
57
58 Command arguments can be sent multiple ways.
58 Command arguments can be sent multiple ways.
59
59
60 The simplest is part of the URL query string using ``x-www-form-urlencoded``
60 The simplest is part of the URL query string using ``x-www-form-urlencoded``
61 encoding (see Python's ``urllib.urlencode()``. However, many servers impose
61 encoding (see Python's ``urllib.urlencode()``. However, many servers impose
62 length limitations on the URL. So this mechanism is typically only used if
62 length limitations on the URL. So this mechanism is typically only used if
63 the server doesn't support other mechanisms.
63 the server doesn't support other mechanisms.
64
64
65 If the server supports the ``httpheader`` capability, command arguments can
65 If the server supports the ``httpheader`` capability, command arguments can
66 be sent in HTTP request headers named ``X-HgArg-<N>`` where ``<N>`` is an
66 be sent in HTTP request headers named ``X-HgArg-<N>`` where ``<N>`` is an
67 integer starting at 1. A ``x-www-form-urlencoded`` representation of the
67 integer starting at 1. A ``x-www-form-urlencoded`` representation of the
68 arguments is obtained. This full string is then split into chunks and sent
68 arguments is obtained. This full string is then split into chunks and sent
69 in numbered ``X-HgArg-<N>`` headers. The maximum length of each HTTP header
69 in numbered ``X-HgArg-<N>`` headers. The maximum length of each HTTP header
70 is defined by the server in the ``httpheader`` capability value, which defaults
70 is defined by the server in the ``httpheader`` capability value, which defaults
71 to ``1024``. The server reassembles the encoded arguments string by
71 to ``1024``. The server reassembles the encoded arguments string by
72 concatenating the ``X-HgArg-<N>`` headers then URL decodes them into a
72 concatenating the ``X-HgArg-<N>`` headers then URL decodes them into a
73 dictionary.
73 dictionary.
74
74
75 The list of ``X-HgArg-<N>`` headers should be added to the ``Vary`` request
75 The list of ``X-HgArg-<N>`` headers should be added to the ``Vary`` request
76 header to instruct caches to take these headers into consideration when caching
76 header to instruct caches to take these headers into consideration when caching
77 requests.
77 requests.
78
78
79 If the server supports the ``httppostargs`` capability, the client
79 If the server supports the ``httppostargs`` capability, the client
80 may send command arguments in the HTTP request body as part of an
80 may send command arguments in the HTTP request body as part of an
81 HTTP POST request. The command arguments will be URL encoded just like
81 HTTP POST request. The command arguments will be URL encoded just like
82 they would for sending them via HTTP headers. However, no splitting is
82 they would for sending them via HTTP headers. However, no splitting is
83 performed: the raw arguments are included in the HTTP request body.
83 performed: the raw arguments are included in the HTTP request body.
84
84
85 The client sends a ``X-HgArgs-Post`` header with the string length of the
85 The client sends a ``X-HgArgs-Post`` header with the string length of the
86 encoded arguments data. Additional data may be included in the HTTP
86 encoded arguments data. Additional data may be included in the HTTP
87 request body immediately following the argument data. The offset of the
87 request body immediately following the argument data. The offset of the
88 non-argument data is defined by the ``X-HgArgs-Post`` header. The
88 non-argument data is defined by the ``X-HgArgs-Post`` header. The
89 ``X-HgArgs-Post`` header is not required if there is no argument data.
89 ``X-HgArgs-Post`` header is not required if there is no argument data.
90
90
91 Additional command data can be sent as part of the HTTP request body. The
91 Additional command data can be sent as part of the HTTP request body. The
92 default ``Content-Type`` when sending data is ``application/mercurial-0.1``.
92 default ``Content-Type`` when sending data is ``application/mercurial-0.1``.
93 A ``Content-Length`` header is currently always sent.
93 A ``Content-Length`` header is currently always sent.
94
94
95 Example HTTP requests::
95 Example HTTP requests::
96
96
97 GET /repo?cmd=capabilities
97 GET /repo?cmd=capabilities
98 X-HgArg-1: foo=bar&baz=hello%20world
98 X-HgArg-1: foo=bar&baz=hello%20world
99
99
100 The request media type should be chosen based on server support. If the
100 The request media type should be chosen based on server support. If the
101 ``httpmediatype`` server capability is present, the client should send
101 ``httpmediatype`` server capability is present, the client should send
102 the newest mutually supported media type. If this capability is absent,
102 the newest mutually supported media type. If this capability is absent,
103 the client must assume the server only supports the
103 the client must assume the server only supports the
104 ``application/mercurial-0.1`` media type.
104 ``application/mercurial-0.1`` media type.
105
105
106 The ``Content-Type`` HTTP response header identifies the response as coming
106 The ``Content-Type`` HTTP response header identifies the response as coming
107 from Mercurial and can also be used to signal an error has occurred.
107 from Mercurial and can also be used to signal an error has occurred.
108
108
109 The ``application/mercurial-*`` media types indicate a generic Mercurial
109 The ``application/mercurial-*`` media types indicate a generic Mercurial
110 data type.
110 data type.
111
111
112 The ``application/mercurial-0.1`` media type is raw Mercurial data. It is the
112 The ``application/mercurial-0.1`` media type is raw Mercurial data. It is the
113 predecessor of the format below.
113 predecessor of the format below.
114
114
115 The ``application/mercurial-0.2`` media type is compression framed Mercurial
115 The ``application/mercurial-0.2`` media type is compression framed Mercurial
116 data. The first byte of the payload indicates the length of the compression
116 data. The first byte of the payload indicates the length of the compression
117 format identifier that follows. Next are N bytes indicating the compression
117 format identifier that follows. Next are N bytes indicating the compression
118 format. e.g. ``zlib``. The remaining bytes are compressed according to that
118 format. e.g. ``zlib``. The remaining bytes are compressed according to that
119 compression format. The decompressed data behaves the same as with
119 compression format. The decompressed data behaves the same as with
120 ``application/mercurial-0.1``.
120 ``application/mercurial-0.1``.
121
121
122 The ``application/hg-error`` media type indicates a generic error occurred.
122 The ``application/hg-error`` media type indicates a generic error occurred.
123 The content of the HTTP response body typically holds text describing the
123 The content of the HTTP response body typically holds text describing the
124 error.
124 error.
125
125
126 The ``application/hg-changegroup`` media type indicates a changegroup response
126 The ``application/hg-changegroup`` media type indicates a changegroup response
127 type.
127 type.
128
128
129 Clients also accept the ``text/plain`` media type. All other media
129 Clients also accept the ``text/plain`` media type. All other media
130 types should cause the client to error.
130 types should cause the client to error.
131
131
132 Behavior of media types is further described in the ``Content Negotiation``
132 Behavior of media types is further described in the ``Content Negotiation``
133 section below.
133 section below.
134
134
135 Clients should issue a ``User-Agent`` request header that identifies the client.
135 Clients should issue a ``User-Agent`` request header that identifies the client.
136 The server should not use the ``User-Agent`` for feature detection.
136 The server should not use the ``User-Agent`` for feature detection.
137
137
138 A command returning a ``string`` response issues a
138 A command returning a ``string`` response issues a
139 ``application/mercurial-0.*`` media type and the HTTP response body contains
139 ``application/mercurial-0.*`` media type and the HTTP response body contains
140 the raw string value (after compression decoding, if used). A
140 the raw string value (after compression decoding, if used). A
141 ``Content-Length`` header is typically issued, but not required.
141 ``Content-Length`` header is typically issued, but not required.
142
142
143 A command returning a ``stream`` response issues a
143 A command returning a ``stream`` response issues a
144 ``application/mercurial-0.*`` media type and the HTTP response is typically
144 ``application/mercurial-0.*`` media type and the HTTP response is typically
145 using *chunked transfer* (``Transfer-Encoding: chunked``).
145 using *chunked transfer* (``Transfer-Encoding: chunked``).
146
146
147 HTTP Version 2 Transport
147 HTTP Version 2 Transport
148 ------------------------
148 ------------------------
149
149
150 **Experimental - feature under active development**
150 **Experimental - feature under active development**
151
151
152 Version 2 of the HTTP protocol is exposed under the ``/api/*`` URL space.
152 Version 2 of the HTTP protocol is exposed under the ``/api/*`` URL space.
153 It's final API name is not yet formalized.
153 It's final API name is not yet formalized.
154
154
155 Commands are triggered by sending HTTP POST requests against URLs of the
155 Commands are triggered by sending HTTP POST requests against URLs of the
156 form ``<permission>/<command>``, where ``<permission>`` is ``ro`` or
156 form ``<permission>/<command>``, where ``<permission>`` is ``ro`` or
157 ``rw``, meaning read-only and read-write, respectively and ``<command>``
157 ``rw``, meaning read-only and read-write, respectively and ``<command>``
158 is a named wire protocol command.
158 is a named wire protocol command.
159
159
160 Non-POST request methods MUST be rejected by the server with an HTTP
160 Non-POST request methods MUST be rejected by the server with an HTTP
161 405 response.
161 405 response.
162
162
163 Commands that modify repository state in meaningful ways MUST NOT be
163 Commands that modify repository state in meaningful ways MUST NOT be
164 exposed under the ``ro`` URL prefix. All available commands MUST be
164 exposed under the ``ro`` URL prefix. All available commands MUST be
165 available under the ``rw`` URL prefix.
165 available under the ``rw`` URL prefix.
166
166
167 Server adminstrators MAY implement blanket HTTP authentication keyed
167 Server adminstrators MAY implement blanket HTTP authentication keyed
168 off the URL prefix. For example, a server may require authentication
168 off the URL prefix. For example, a server may require authentication
169 for all ``rw/*`` URLs and let unauthenticated requests to ``ro/*``
169 for all ``rw/*`` URLs and let unauthenticated requests to ``ro/*``
170 URL proceed. A server MAY issue an HTTP 401, 403, or 407 response
170 URL proceed. A server MAY issue an HTTP 401, 403, or 407 response
171 in accordance with RFC 7235. Clients SHOULD recognize the HTTP Basic
171 in accordance with RFC 7235. Clients SHOULD recognize the HTTP Basic
172 (RFC 7617) and Digest (RFC 7616) authentication schemes. Clients SHOULD
172 (RFC 7617) and Digest (RFC 7616) authentication schemes. Clients SHOULD
173 make an attempt to recognize unknown schemes using the
173 make an attempt to recognize unknown schemes using the
174 ``WWW-Authenticate`` response header on a 401 response, as defined by
174 ``WWW-Authenticate`` response header on a 401 response, as defined by
175 RFC 7235.
175 RFC 7235.
176
176
177 Read-only commands are accessible under ``rw/*`` URLs so clients can
177 Read-only commands are accessible under ``rw/*`` URLs so clients can
178 signal the intent of the operation very early in the connection
178 signal the intent of the operation very early in the connection
179 lifecycle. For example, a ``push`` operation - which consists of
179 lifecycle. For example, a ``push`` operation - which consists of
180 various read-only commands mixed with at least one read-write command -
180 various read-only commands mixed with at least one read-write command -
181 can perform all commands against ``rw/*`` URLs so that any server-side
181 can perform all commands against ``rw/*`` URLs so that any server-side
182 authentication requirements are discovered upon attempting the first
182 authentication requirements are discovered upon attempting the first
183 command - not potentially several commands into the exchange. This
183 command - not potentially several commands into the exchange. This
184 allows clients to fail faster or prompt for credentials as soon as the
184 allows clients to fail faster or prompt for credentials as soon as the
185 exchange takes place. This provides a better end-user experience.
185 exchange takes place. This provides a better end-user experience.
186
186
187 Requests to unknown commands or URLS result in an HTTP 404.
187 Requests to unknown commands or URLS result in an HTTP 404.
188 TODO formally define response type, how error is communicated, etc.
188 TODO formally define response type, how error is communicated, etc.
189
189
190 HTTP request and response bodies use the *Unified Frame-Based Protocol*
190 HTTP request and response bodies use the *Unified Frame-Based Protocol*
191 (defined below) for media exchange. The entirety of the HTTP message
191 (defined below) for media exchange. The entirety of the HTTP message
192 body is 0 or more frames as defined by this protocol.
192 body is 0 or more frames as defined by this protocol.
193
193
194 Clients and servers MUST advertise the ``TBD`` media type via the
194 Clients and servers MUST advertise the ``TBD`` media type via the
195 ``Content-Type`` request and response headers. In addition, clients MUST
195 ``Content-Type`` request and response headers. In addition, clients MUST
196 advertise this media type value in their ``Accept`` request header in all
196 advertise this media type value in their ``Accept`` request header in all
197 requests.
197 requests.
198 TODO finalize the media type. For now, it is defined in wireprotoserver.py.
198 TODO finalize the media type. For now, it is defined in wireprotoserver.py.
199
199
200 Servers receiving requests without an ``Accept`` header SHOULD respond with
200 Servers receiving requests without an ``Accept`` header SHOULD respond with
201 an HTTP 406.
201 an HTTP 406.
202
202
203 Servers receiving requests with an invalid ``Content-Type`` header SHOULD
203 Servers receiving requests with an invalid ``Content-Type`` header SHOULD
204 respond with an HTTP 415.
204 respond with an HTTP 415.
205
205
206 The command to run is specified in the POST payload as defined by the
206 The command to run is specified in the POST payload as defined by the
207 *Unified Frame-Based Protocol*. This is redundant with data already
207 *Unified Frame-Based Protocol*. This is redundant with data already
208 encoded in the URL. This is by design, so server operators can have
208 encoded in the URL. This is by design, so server operators can have
209 better understanding about server activity from looking merely at
209 better understanding about server activity from looking merely at
210 HTTP access logs.
210 HTTP access logs.
211
211
212 In most circumstances, the command specified in the URL MUST match
212 In most circumstances, the command specified in the URL MUST match
213 the command specified in the frame-based payload or the server will
213 the command specified in the frame-based payload or the server will
214 respond with an error. The exception to this is the special
214 respond with an error. The exception to this is the special
215 ``multirequest`` URL. (See below.) In addition, HTTP requests
215 ``multirequest`` URL. (See below.) In addition, HTTP requests
216 are limited to one command invocation. The exception is the special
216 are limited to one command invocation. The exception is the special
217 ``multirequest`` URL.
217 ``multirequest`` URL.
218
218
219 The ``multirequest`` command endpoints (``ro/multirequest`` and
219 The ``multirequest`` command endpoints (``ro/multirequest`` and
220 ``rw/multirequest``) are special in that they allow the execution of
220 ``rw/multirequest``) are special in that they allow the execution of
221 *any* command and allow the execution of multiple commands. If the
221 *any* command and allow the execution of multiple commands. If the
222 HTTP request issues multiple commands across multiple frames, all
222 HTTP request issues multiple commands across multiple frames, all
223 issued commands will be processed by the server. Per the defined
223 issued commands will be processed by the server. Per the defined
224 behavior of the *Unified Frame-Based Protocol*, commands may be
224 behavior of the *Unified Frame-Based Protocol*, commands may be
225 issued interleaved and responses may come back in a different order
225 issued interleaved and responses may come back in a different order
226 than they were issued. Clients MUST be able to deal with this.
226 than they were issued. Clients MUST be able to deal with this.
227
227
228 SSH Protocol
228 SSH Protocol
229 ============
229 ============
230
230
231 Handshake
231 Handshake
232 ---------
232 ---------
233
233
234 For all clients, the handshake consists of the client sending 1 or more
234 For all clients, the handshake consists of the client sending 1 or more
235 commands to the server using version 1 of the transport. Servers respond
235 commands to the server using version 1 of the transport. Servers respond
236 to commands they know how to respond to and send an empty response (``0\n``)
236 to commands they know how to respond to and send an empty response (``0\n``)
237 for unknown commands (per standard behavior of version 1 of the transport).
237 for unknown commands (per standard behavior of version 1 of the transport).
238 Clients then typically look for a response to the newest sent command to
238 Clients then typically look for a response to the newest sent command to
239 determine which transport version to use and what the available features for
239 determine which transport version to use and what the available features for
240 the connection and server are.
240 the connection and server are.
241
241
242 Preceding any response from client-issued commands, the server may print
242 Preceding any response from client-issued commands, the server may print
243 non-protocol output. It is common for SSH servers to print banners, message
243 non-protocol output. It is common for SSH servers to print banners, message
244 of the day announcements, etc when clients connect. It is assumed that any
244 of the day announcements, etc when clients connect. It is assumed that any
245 such *banner* output will precede any Mercurial server output. So clients
245 such *banner* output will precede any Mercurial server output. So clients
246 must be prepared to handle server output on initial connect that isn't
246 must be prepared to handle server output on initial connect that isn't
247 in response to any client-issued command and doesn't conform to Mercurial's
247 in response to any client-issued command and doesn't conform to Mercurial's
248 wire protocol. This *banner* output should only be on stdout. However,
248 wire protocol. This *banner* output should only be on stdout. However,
249 some servers may send output on stderr.
249 some servers may send output on stderr.
250
250
251 Pre 0.9.1 clients issue a ``between`` command with the ``pairs`` argument
251 Pre 0.9.1 clients issue a ``between`` command with the ``pairs`` argument
252 having the value
252 having the value
253 ``0000000000000000000000000000000000000000-0000000000000000000000000000000000000000``.
253 ``0000000000000000000000000000000000000000-0000000000000000000000000000000000000000``.
254
254
255 The ``between`` command has been supported since the original Mercurial
255 The ``between`` command has been supported since the original Mercurial
256 SSH server. Requesting the empty range will return a ``\n`` string response,
256 SSH server. Requesting the empty range will return a ``\n`` string response,
257 which will be encoded as ``1\n\n`` (value length of ``1`` followed by a newline
257 which will be encoded as ``1\n\n`` (value length of ``1`` followed by a newline
258 followed by the value, which happens to be a newline).
258 followed by the value, which happens to be a newline).
259
259
260 For pre 0.9.1 clients and all servers, the exchange looks like::
260 For pre 0.9.1 clients and all servers, the exchange looks like::
261
261
262 c: between\n
262 c: between\n
263 c: pairs 81\n
263 c: pairs 81\n
264 c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000
264 c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000
265 s: 1\n
265 s: 1\n
266 s: \n
266 s: \n
267
267
268 0.9.1+ clients send a ``hello`` command (with no arguments) before the
268 0.9.1+ clients send a ``hello`` command (with no arguments) before the
269 ``between`` command. The response to this command allows clients to
269 ``between`` command. The response to this command allows clients to
270 discover server capabilities and settings.
270 discover server capabilities and settings.
271
271
272 An example exchange between 0.9.1+ clients and a ``hello`` aware server looks
272 An example exchange between 0.9.1+ clients and a ``hello`` aware server looks
273 like::
273 like::
274
274
275 c: hello\n
275 c: hello\n
276 c: between\n
276 c: between\n
277 c: pairs 81\n
277 c: pairs 81\n
278 c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000
278 c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000
279 s: 324\n
279 s: 324\n
280 s: capabilities: lookup changegroupsubset branchmap pushkey known getbundle ...\n
280 s: capabilities: lookup changegroupsubset branchmap pushkey known getbundle ...\n
281 s: 1\n
281 s: 1\n
282 s: \n
282 s: \n
283
283
284 And a similar scenario but with servers sending a banner on connect::
284 And a similar scenario but with servers sending a banner on connect::
285
285
286 c: hello\n
286 c: hello\n
287 c: between\n
287 c: between\n
288 c: pairs 81\n
288 c: pairs 81\n
289 c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000
289 c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000
290 s: welcome to the server\n
290 s: welcome to the server\n
291 s: if you find any issues, email someone@somewhere.com\n
291 s: if you find any issues, email someone@somewhere.com\n
292 s: 324\n
292 s: 324\n
293 s: capabilities: lookup changegroupsubset branchmap pushkey known getbundle ...\n
293 s: capabilities: lookup changegroupsubset branchmap pushkey known getbundle ...\n
294 s: 1\n
294 s: 1\n
295 s: \n
295 s: \n
296
296
297 Note that output from the ``hello`` command is terminated by a ``\n``. This is
297 Note that output from the ``hello`` command is terminated by a ``\n``. This is
298 part of the response payload and not part of the wire protocol adding a newline
298 part of the response payload and not part of the wire protocol adding a newline
299 after responses. In other words, the length of the response contains the
299 after responses. In other words, the length of the response contains the
300 trailing ``\n``.
300 trailing ``\n``.
301
301
302 Clients supporting version 2 of the SSH transport send a line beginning
302 Clients supporting version 2 of the SSH transport send a line beginning
303 with ``upgrade`` before the ``hello`` and ``between`` commands. The line
303 with ``upgrade`` before the ``hello`` and ``between`` commands. The line
304 (which isn't a well-formed command line because it doesn't consist of a
304 (which isn't a well-formed command line because it doesn't consist of a
305 single command name) serves to both communicate the client's intent to
305 single command name) serves to both communicate the client's intent to
306 switch to transport version 2 (transports are version 1 by default) as
306 switch to transport version 2 (transports are version 1 by default) as
307 well as to advertise the client's transport-level capabilities so the
307 well as to advertise the client's transport-level capabilities so the
308 server may satisfy that request immediately.
308 server may satisfy that request immediately.
309
309
310 The upgrade line has the form:
310 The upgrade line has the form:
311
311
312 upgrade <token> <transport capabilities>
312 upgrade <token> <transport capabilities>
313
313
314 That is the literal string ``upgrade`` followed by a space, followed by
314 That is the literal string ``upgrade`` followed by a space, followed by
315 a randomly generated string, followed by a space, followed by a string
315 a randomly generated string, followed by a space, followed by a string
316 denoting the client's transport capabilities.
316 denoting the client's transport capabilities.
317
317
318 The token can be anything. However, a random UUID is recommended. (Use
318 The token can be anything. However, a random UUID is recommended. (Use
319 of version 4 UUIDs is recommended because version 1 UUIDs can leak the
319 of version 4 UUIDs is recommended because version 1 UUIDs can leak the
320 client's MAC address.)
320 client's MAC address.)
321
321
322 The transport capabilities string is a URL/percent encoded string
322 The transport capabilities string is a URL/percent encoded string
323 containing key-value pairs defining the client's transport-level
323 containing key-value pairs defining the client's transport-level
324 capabilities. The following capabilities are defined:
324 capabilities. The following capabilities are defined:
325
325
326 proto
326 proto
327 A comma-delimited list of transport protocol versions the client
327 A comma-delimited list of transport protocol versions the client
328 supports. e.g. ``ssh-v2``.
328 supports. e.g. ``ssh-v2``.
329
329
330 If the server does not recognize the ``upgrade`` line, it should issue
330 If the server does not recognize the ``upgrade`` line, it should issue
331 an empty response and continue processing the ``hello`` and ``between``
331 an empty response and continue processing the ``hello`` and ``between``
332 commands. Here is an example handshake between a version 2 aware client
332 commands. Here is an example handshake between a version 2 aware client
333 and a non version 2 aware server:
333 and a non version 2 aware server:
334
334
335 c: upgrade 2e82ab3f-9ce3-4b4e-8f8c-6fd1c0e9e23a proto=ssh-v2
335 c: upgrade 2e82ab3f-9ce3-4b4e-8f8c-6fd1c0e9e23a proto=ssh-v2
336 c: hello\n
336 c: hello\n
337 c: between\n
337 c: between\n
338 c: pairs 81\n
338 c: pairs 81\n
339 c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000
339 c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000
340 s: 0\n
340 s: 0\n
341 s: 324\n
341 s: 324\n
342 s: capabilities: lookup changegroupsubset branchmap pushkey known getbundle ...\n
342 s: capabilities: lookup changegroupsubset branchmap pushkey known getbundle ...\n
343 s: 1\n
343 s: 1\n
344 s: \n
344 s: \n
345
345
346 (The initial ``0\n`` line from the server indicates an empty response to
346 (The initial ``0\n`` line from the server indicates an empty response to
347 the unknown ``upgrade ..`` command/line.)
347 the unknown ``upgrade ..`` command/line.)
348
348
349 If the server recognizes the ``upgrade`` line and is willing to satisfy that
349 If the server recognizes the ``upgrade`` line and is willing to satisfy that
350 upgrade request, it replies to with a payload of the following form:
350 upgrade request, it replies to with a payload of the following form:
351
351
352 upgraded <token> <transport name>\n
352 upgraded <token> <transport name>\n
353
353
354 This line is the literal string ``upgraded``, a space, the token that was
354 This line is the literal string ``upgraded``, a space, the token that was
355 specified by the client in its ``upgrade ...`` request line, a space, and the
355 specified by the client in its ``upgrade ...`` request line, a space, and the
356 name of the transport protocol that was chosen by the server. The transport
356 name of the transport protocol that was chosen by the server. The transport
357 name MUST match one of the names the client specified in the ``proto`` field
357 name MUST match one of the names the client specified in the ``proto`` field
358 of its ``upgrade ...`` request line.
358 of its ``upgrade ...`` request line.
359
359
360 If a server issues an ``upgraded`` response, it MUST also read and ignore
360 If a server issues an ``upgraded`` response, it MUST also read and ignore
361 the lines associated with the ``hello`` and ``between`` command requests
361 the lines associated with the ``hello`` and ``between`` command requests
362 that were issued by the server. It is assumed that the negotiated transport
362 that were issued by the server. It is assumed that the negotiated transport
363 will respond with equivalent requested information following the transport
363 will respond with equivalent requested information following the transport
364 handshake.
364 handshake.
365
365
366 All data following the ``\n`` terminating the ``upgraded`` line is the
366 All data following the ``\n`` terminating the ``upgraded`` line is the
367 domain of the negotiated transport. It is common for the data immediately
367 domain of the negotiated transport. It is common for the data immediately
368 following to contain additional metadata about the state of the transport and
368 following to contain additional metadata about the state of the transport and
369 the server. However, this isn't strictly speaking part of the transport
369 the server. However, this isn't strictly speaking part of the transport
370 handshake and isn't covered by this section.
370 handshake and isn't covered by this section.
371
371
372 Here is an example handshake between a version 2 aware client and a version
372 Here is an example handshake between a version 2 aware client and a version
373 2 aware server:
373 2 aware server:
374
374
375 c: upgrade 2e82ab3f-9ce3-4b4e-8f8c-6fd1c0e9e23a proto=ssh-v2
375 c: upgrade 2e82ab3f-9ce3-4b4e-8f8c-6fd1c0e9e23a proto=ssh-v2
376 c: hello\n
376 c: hello\n
377 c: between\n
377 c: between\n
378 c: pairs 81\n
378 c: pairs 81\n
379 c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000
379 c: 0000000000000000000000000000000000000000-0000000000000000000000000000000000000000
380 s: upgraded 2e82ab3f-9ce3-4b4e-8f8c-6fd1c0e9e23a ssh-v2\n
380 s: upgraded 2e82ab3f-9ce3-4b4e-8f8c-6fd1c0e9e23a ssh-v2\n
381 s: <additional transport specific data>
381 s: <additional transport specific data>
382
382
383 The client-issued token that is echoed in the response provides a more
383 The client-issued token that is echoed in the response provides a more
384 resilient mechanism for differentiating *banner* output from Mercurial
384 resilient mechanism for differentiating *banner* output from Mercurial
385 output. In version 1, properly formatted banner output could get confused
385 output. In version 1, properly formatted banner output could get confused
386 for Mercurial server output. By submitting a randomly generated token
386 for Mercurial server output. By submitting a randomly generated token
387 that is then present in the response, the client can look for that token
387 that is then present in the response, the client can look for that token
388 in response lines and have reasonable certainty that the line did not
388 in response lines and have reasonable certainty that the line did not
389 originate from a *banner* message.
389 originate from a *banner* message.
390
390
391 SSH Version 1 Transport
391 SSH Version 1 Transport
392 -----------------------
392 -----------------------
393
393
394 The SSH transport (version 1) is a custom text-based protocol suitable for
394 The SSH transport (version 1) is a custom text-based protocol suitable for
395 use over any bi-directional stream transport. It is most commonly used with
395 use over any bi-directional stream transport. It is most commonly used with
396 SSH.
396 SSH.
397
397
398 A SSH transport server can be started with ``hg serve --stdio``. The stdin,
398 A SSH transport server can be started with ``hg serve --stdio``. The stdin,
399 stderr, and stdout file descriptors of the started process are used to exchange
399 stderr, and stdout file descriptors of the started process are used to exchange
400 data. When Mercurial connects to a remote server over SSH, it actually starts
400 data. When Mercurial connects to a remote server over SSH, it actually starts
401 a ``hg serve --stdio`` process on the remote server.
401 a ``hg serve --stdio`` process on the remote server.
402
402
403 Commands are issued by sending the command name followed by a trailing newline
403 Commands are issued by sending the command name followed by a trailing newline
404 ``\n`` to the server. e.g. ``capabilities\n``.
404 ``\n`` to the server. e.g. ``capabilities\n``.
405
405
406 Command arguments are sent in the following format::
406 Command arguments are sent in the following format::
407
407
408 <argument> <length>\n<value>
408 <argument> <length>\n<value>
409
409
410 That is, the argument string name followed by a space followed by the
410 That is, the argument string name followed by a space followed by the
411 integer length of the value (expressed as a string) followed by a newline
411 integer length of the value (expressed as a string) followed by a newline
412 (``\n``) followed by the raw argument value.
412 (``\n``) followed by the raw argument value.
413
413
414 Dictionary arguments are encoded differently::
414 Dictionary arguments are encoded differently::
415
415
416 <argument> <# elements>\n
416 <argument> <# elements>\n
417 <key1> <length1>\n<value1>
417 <key1> <length1>\n<value1>
418 <key2> <length2>\n<value2>
418 <key2> <length2>\n<value2>
419 ...
419 ...
420
420
421 Non-argument data is sent immediately after the final argument value. It is
421 Non-argument data is sent immediately after the final argument value. It is
422 encoded in chunks::
422 encoded in chunks::
423
423
424 <length>\n<data>
424 <length>\n<data>
425
425
426 Each command declares a list of supported arguments and their types. If a
426 Each command declares a list of supported arguments and their types. If a
427 client sends an unknown argument to the server, the server should abort
427 client sends an unknown argument to the server, the server should abort
428 immediately. The special argument ``*`` in a command's definition indicates
428 immediately. The special argument ``*`` in a command's definition indicates
429 that all argument names are allowed.
429 that all argument names are allowed.
430
430
431 The definition of supported arguments and types is initially made when a
431 The definition of supported arguments and types is initially made when a
432 new command is implemented. The client and server must initially independently
432 new command is implemented. The client and server must initially independently
433 agree on the arguments and their types. This initial set of arguments can be
433 agree on the arguments and their types. This initial set of arguments can be
434 supplemented through the presence of *capabilities* advertised by the server.
434 supplemented through the presence of *capabilities* advertised by the server.
435
435
436 Each command has a defined expected response type.
436 Each command has a defined expected response type.
437
437
438 A ``string`` response type is a length framed value. The response consists of
438 A ``string`` response type is a length framed value. The response consists of
439 the string encoded integer length of a value followed by a newline (``\n``)
439 the string encoded integer length of a value followed by a newline (``\n``)
440 followed by the value. Empty values are allowed (and are represented as
440 followed by the value. Empty values are allowed (and are represented as
441 ``0\n``).
441 ``0\n``).
442
442
443 A ``stream`` response type consists of raw bytes of data. There is no framing.
443 A ``stream`` response type consists of raw bytes of data. There is no framing.
444
444
445 A generic error response type is also supported. It consists of a an error
445 A generic error response type is also supported. It consists of a an error
446 message written to ``stderr`` followed by ``\n-\n``. In addition, ``\n`` is
446 message written to ``stderr`` followed by ``\n-\n``. In addition, ``\n`` is
447 written to ``stdout``.
447 written to ``stdout``.
448
448
449 If the server receives an unknown command, it will send an empty ``string``
449 If the server receives an unknown command, it will send an empty ``string``
450 response.
450 response.
451
451
452 The server terminates if it receives an empty command (a ``\n`` character).
452 The server terminates if it receives an empty command (a ``\n`` character).
453
453
454 If the server announces support for the ``protocaps`` capability, the client
454 If the server announces support for the ``protocaps`` capability, the client
455 should issue a ``protocaps`` command after the initial handshake to annonunce
455 should issue a ``protocaps`` command after the initial handshake to annonunce
456 its own capabilities. The client capabilities are persistent.
456 its own capabilities. The client capabilities are persistent.
457
457
458 SSH Version 2 Transport
458 SSH Version 2 Transport
459 -----------------------
459 -----------------------
460
460
461 **Experimental and under development**
461 **Experimental and under development**
462
462
463 Version 2 of the SSH transport behaves identically to version 1 of the SSH
463 Version 2 of the SSH transport behaves identically to version 1 of the SSH
464 transport with the exception of handshake semantics. See above for how
464 transport with the exception of handshake semantics. See above for how
465 version 2 of the SSH transport is negotiated.
465 version 2 of the SSH transport is negotiated.
466
466
467 Immediately following the ``upgraded`` line signaling a switch to version
467 Immediately following the ``upgraded`` line signaling a switch to version
468 2 of the SSH protocol, the server automatically sends additional details
468 2 of the SSH protocol, the server automatically sends additional details
469 about the capabilities of the remote server. This has the form:
469 about the capabilities of the remote server. This has the form:
470
470
471 <integer length of value>\n
471 <integer length of value>\n
472 capabilities: ...\n
472 capabilities: ...\n
473
473
474 e.g.
474 e.g.
475
475
476 s: upgraded 2e82ab3f-9ce3-4b4e-8f8c-6fd1c0e9e23a ssh-v2\n
476 s: upgraded 2e82ab3f-9ce3-4b4e-8f8c-6fd1c0e9e23a ssh-v2\n
477 s: 240\n
477 s: 240\n
478 s: capabilities: known getbundle batch ...\n
478 s: capabilities: known getbundle batch ...\n
479
479
480 Following capabilities advertisement, the peers communicate using version
480 Following capabilities advertisement, the peers communicate using version
481 1 of the SSH transport.
481 1 of the SSH transport.
482
482
483 Unified Frame-Based Protocol
483 Unified Frame-Based Protocol
484 ============================
484 ============================
485
485
486 **Experimental and under development**
486 **Experimental and under development**
487
487
488 The *Unified Frame-Based Protocol* is a communications protocol between
488 The *Unified Frame-Based Protocol* is a communications protocol between
489 Mercurial peers. The protocol aims to be mostly transport agnostic
489 Mercurial peers. The protocol aims to be mostly transport agnostic
490 (works similarly on HTTP, SSH, etc).
490 (works similarly on HTTP, SSH, etc).
491
491
492 To operate the protocol, a bi-directional, half-duplex pipe supporting
492 To operate the protocol, a bi-directional, half-duplex pipe supporting
493 ordered sends and receives is required. That is, each peer has one pipe
493 ordered sends and receives is required. That is, each peer has one pipe
494 for sending data and another for receiving.
494 for sending data and another for receiving.
495
495
496 All data is read and written in atomic units called *frames*. These
496 All data is read and written in atomic units called *frames*. These
497 are conceptually similar to TCP packets. Higher-level functionality
497 are conceptually similar to TCP packets. Higher-level functionality
498 is built on the exchange and processing of frames.
498 is built on the exchange and processing of frames.
499
499
500 All frames are associated with a *stream*. A *stream* provides a
500 All frames are associated with a *stream*. A *stream* provides a
501 unidirectional grouping of frames. Streams facilitate two goals:
501 unidirectional grouping of frames. Streams facilitate two goals:
502 content encoding and parallelism. There is a dedicated section on
502 content encoding and parallelism. There is a dedicated section on
503 streams below.
503 streams below.
504
504
505 The protocol is request-response based: the client issues requests to
505 The protocol is request-response based: the client issues requests to
506 the server, which issues replies to those requests. Server-initiated
506 the server, which issues replies to those requests. Server-initiated
507 messaging is not currently supported, but this specification carves
507 messaging is not currently supported, but this specification carves
508 out room to implement it.
508 out room to implement it.
509
509
510 All frames are associated with a numbered request. Frames can thus
510 All frames are associated with a numbered request. Frames can thus
511 be logically grouped by their request ID.
511 be logically grouped by their request ID.
512
512
513 Frames begin with an 8 octet header followed by a variable length
513 Frames begin with an 8 octet header followed by a variable length
514 payload::
514 payload::
515
515
516 +------------------------------------------------+
516 +------------------------------------------------+
517 | Length (24) |
517 | Length (24) |
518 +--------------------------------+---------------+
518 +--------------------------------+---------------+
519 | Request ID (16) | Stream ID (8) |
519 | Request ID (16) | Stream ID (8) |
520 +------------------+-------------+---------------+
520 +------------------+-------------+---------------+
521 | Stream Flags (8) |
521 | Stream Flags (8) |
522 +-----------+------+
522 +-----------+------+
523 | Type (4) |
523 | Type (4) |
524 +-----------+
524 +-----------+
525 | Flags (4) |
525 | Flags (4) |
526 +===========+===================================================|
526 +===========+===================================================|
527 | Frame Payload (0...) ...
527 | Frame Payload (0...) ...
528 +---------------------------------------------------------------+
528 +---------------------------------------------------------------+
529
529
530 The length of the frame payload is expressed as an unsigned 24 bit
530 The length of the frame payload is expressed as an unsigned 24 bit
531 little endian integer. Values larger than 65535 MUST NOT be used unless
531 little endian integer. Values larger than 65535 MUST NOT be used unless
532 given permission by the server as part of the negotiated capabilities
532 given permission by the server as part of the negotiated capabilities
533 during the handshake. The frame header is not part of the advertised
533 during the handshake. The frame header is not part of the advertised
534 frame length. The payload length is the over-the-wire length. If there
534 frame length. The payload length is the over-the-wire length. If there
535 is content encoding applied to the payload as part of the frame's stream,
535 is content encoding applied to the payload as part of the frame's stream,
536 the length is the output of that content encoding, not the input.
536 the length is the output of that content encoding, not the input.
537
537
538 The 16-bit ``Request ID`` field denotes the integer request identifier,
538 The 16-bit ``Request ID`` field denotes the integer request identifier,
539 stored as an unsigned little endian integer. Odd numbered requests are
539 stored as an unsigned little endian integer. Odd numbered requests are
540 client-initiated. Even numbered requests are server-initiated. This
540 client-initiated. Even numbered requests are server-initiated. This
541 refers to where the *request* was initiated - not where the *frame* was
541 refers to where the *request* was initiated - not where the *frame* was
542 initiated, so servers will send frames with odd ``Request ID`` in
542 initiated, so servers will send frames with odd ``Request ID`` in
543 response to client-initiated requests. Implementations are advised to
543 response to client-initiated requests. Implementations are advised to
544 start ordering request identifiers at ``1`` and ``0``, increment by
544 start ordering request identifiers at ``1`` and ``0``, increment by
545 ``2``, and wrap around if all available numbers have been exhausted.
545 ``2``, and wrap around if all available numbers have been exhausted.
546
546
547 The 8-bit ``Stream ID`` field denotes the stream that the frame is
547 The 8-bit ``Stream ID`` field denotes the stream that the frame is
548 associated with. Frames belonging to a stream may have content
548 associated with. Frames belonging to a stream may have content
549 encoding applied and the receiver may need to decode the raw frame
549 encoding applied and the receiver may need to decode the raw frame
550 payload to obtain the original data. Odd numbered IDs are
550 payload to obtain the original data. Odd numbered IDs are
551 client-initiated. Even numbered IDs are server-initiated.
551 client-initiated. Even numbered IDs are server-initiated.
552
552
553 The 8-bit ``Stream Flags`` field defines stream processing semantics.
553 The 8-bit ``Stream Flags`` field defines stream processing semantics.
554 See the section on streams below.
554 See the section on streams below.
555
555
556 The 4-bit ``Type`` field denotes the type of frame being sent.
556 The 4-bit ``Type`` field denotes the type of frame being sent.
557
557
558 The 4-bit ``Flags`` field defines special, per-type attributes for
558 The 4-bit ``Flags`` field defines special, per-type attributes for
559 the frame.
559 the frame.
560
560
561 The sections below define the frame types and their behavior.
561 The sections below define the frame types and their behavior.
562
562
563 Command Request (``0x01``)
563 Command Request (``0x01``)
564 --------------------------
564 --------------------------
565
565
566 This frame contains a request to run a command.
566 This frame contains a request to run a command.
567
567
568 The payload consists of a CBOR map defining the command request. The
568 The payload consists of a CBOR map defining the command request. The
569 bytestring keys of that map are:
569 bytestring keys of that map are:
570
570
571 name
571 name
572 Name of the command that should be executed (bytestring).
572 Name of the command that should be executed (bytestring).
573 args
573 args
574 Map of bytestring keys to various value types containing the named
574 Map of bytestring keys to various value types containing the named
575 arguments to this command.
575 arguments to this command.
576
576
577 Each command defines its own set of argument names and their expected
577 Each command defines its own set of argument names and their expected
578 types.
578 types.
579
579
580 This frame type MUST ONLY be sent from clients to servers: it is illegal
580 This frame type MUST ONLY be sent from clients to servers: it is illegal
581 for a server to send this frame to a client.
581 for a server to send this frame to a client.
582
582
583 The following flag values are defined for this type:
583 The following flag values are defined for this type:
584
584
585 0x01
585 0x01
586 New command request. When set, this frame represents the beginning
586 New command request. When set, this frame represents the beginning
587 of a new request to run a command. The ``Request ID`` attached to this
587 of a new request to run a command. The ``Request ID`` attached to this
588 frame MUST NOT be active.
588 frame MUST NOT be active.
589 0x02
589 0x02
590 Command request continuation. When set, this frame is a continuation
590 Command request continuation. When set, this frame is a continuation
591 from a previous command request frame for its ``Request ID``. This
591 from a previous command request frame for its ``Request ID``. This
592 flag is set when the CBOR data for a command request does not fit
592 flag is set when the CBOR data for a command request does not fit
593 in a single frame.
593 in a single frame.
594 0x04
594 0x04
595 Additional frames expected. When set, the command request didn't fit
595 Additional frames expected. When set, the command request didn't fit
596 into a single frame and additional CBOR data follows in a subsequent
596 into a single frame and additional CBOR data follows in a subsequent
597 frame.
597 frame.
598 0x08
598 0x08
599 Command data frames expected. When set, command data frames are
599 Command data frames expected. When set, command data frames are
600 expected to follow the final command request frame for this request.
600 expected to follow the final command request frame for this request.
601
601
602 ``0x01`` MUST be set on the initial command request frame for a
602 ``0x01`` MUST be set on the initial command request frame for a
603 ``Request ID``.
603 ``Request ID``.
604
604
605 ``0x01`` or ``0x02`` MUST be set to indicate this frame's role in
605 ``0x01`` or ``0x02`` MUST be set to indicate this frame's role in
606 a series of command request frames.
606 a series of command request frames.
607
607
608 If command data frames are to be sent, ``0x10`` MUST be set on ALL
608 If command data frames are to be sent, ``0x10`` MUST be set on ALL
609 command request frames.
609 command request frames.
610
610
611 Command Data (``0x03``)
611 Command Data (``0x03``)
612 -----------------------
612 -----------------------
613
613
614 This frame contains raw data for a command.
614 This frame contains raw data for a command.
615
615
616 Most commands can be executed by specifying arguments. However,
616 Most commands can be executed by specifying arguments. However,
617 arguments have an upper bound to their length. For commands that
617 arguments have an upper bound to their length. For commands that
618 accept data that is beyond this length or whose length isn't known
618 accept data that is beyond this length or whose length isn't known
619 when the command is initially sent, they will need to stream
619 when the command is initially sent, they will need to stream
620 arbitrary data to the server. This frame type facilitates the sending
620 arbitrary data to the server. This frame type facilitates the sending
621 of this data.
621 of this data.
622
622
623 The payload of this frame type consists of a stream of raw data to be
623 The payload of this frame type consists of a stream of raw data to be
624 consumed by the command handler on the server. The format of the data
624 consumed by the command handler on the server. The format of the data
625 is command specific.
625 is command specific.
626
626
627 The following flag values are defined for this type:
627 The following flag values are defined for this type:
628
628
629 0x01
629 0x01
630 Command data continuation. When set, the data for this command
630 Command data continuation. When set, the data for this command
631 continues into a subsequent frame.
631 continues into a subsequent frame.
632
632
633 0x02
633 0x02
634 End of data. When set, command data has been fully sent to the
634 End of data. When set, command data has been fully sent to the
635 server. The command has been fully issued and no new data for this
635 server. The command has been fully issued and no new data for this
636 command will be sent. The next frame will belong to a new command.
636 command will be sent. The next frame will belong to a new command.
637
637
638 Response Data (``0x04``)
638 Response Data (``0x04``)
639 ------------------------
639 ------------------------
640
640
641 This frame contains raw response data to an issued command.
641 This frame contains raw response data to an issued command.
642
642
643 The following flag values are defined for this type:
643 The following flag values are defined for this type:
644
644
645 0x01
645 0x01
646 Data continuation. When set, an additional frame containing response data
646 Data continuation. When set, an additional frame containing response data
647 will follow.
647 will follow.
648 0x02
648 0x02
649 End of data. When set, the response data has been fully sent and
649 End of data. When set, the response data has been fully sent and
650 no additional frames for this response will be sent.
650 no additional frames for this response will be sent.
651 0x04
651 0x04
652 CBOR data. When set, the frame payload consists of CBOR data.
652 CBOR data. When set, the frame payload consists of CBOR data.
653
653
654 The ``0x01`` flag is mutually exclusive with the ``0x02`` flag.
654 The ``0x01`` flag is mutually exclusive with the ``0x02`` flag.
655
655
656 Error Response (``0x05``)
656 Error Response (``0x05``)
657 -------------------------
657 -------------------------
658
658
659 An error occurred when processing a request. This could indicate
659 An error occurred when processing a request. This could indicate
660 a protocol-level failure or an application level failure depending
660 a protocol-level failure or an application level failure depending
661 on the flags for this message type.
661 on the flags for this message type.
662
662
663 The payload for this type is an error message that should be
663 The payload for this type is an error message that should be
664 displayed to the user.
664 displayed to the user.
665
665
666 The following flag values are defined for this type:
666 The following flag values are defined for this type:
667
667
668 0x01
668 0x01
669 The error occurred at the transport/protocol level. If set, the
669 The error occurred at the transport/protocol level. If set, the
670 connection should be closed.
670 connection should be closed.
671 0x02
671 0x02
672 The error occurred at the application level. e.g. invalid command.
672 The error occurred at the application level. e.g. invalid command.
673
673
674 Human Output Side-Channel (``0x06``)
674 Human Output Side-Channel (``0x06``)
675 ------------------------------------
675 ------------------------------------
676
676
677 This frame contains a message that is intended to be displayed to
677 This frame contains a message that is intended to be displayed to
678 people. Whereas most frames communicate machine readable data, this
678 people. Whereas most frames communicate machine readable data, this
679 frame communicates textual data that is intended to be shown to
679 frame communicates textual data that is intended to be shown to
680 humans.
680 humans.
681
681
682 The frame consists of a series of *formatting requests*. Each formatting
682 The frame consists of a series of *formatting requests*. Each formatting
683 request consists of a formatting string, arguments for that formatting
683 request consists of a formatting string, arguments for that formatting
684 string, and labels to apply to that formatting string.
684 string, and labels to apply to that formatting string.
685
685
686 A formatting string is a printf()-like string that allows variable
686 A formatting string is a printf()-like string that allows variable
687 substitution within the string. Labels allow the rendered text to be
687 substitution within the string. Labels allow the rendered text to be
688 *decorated*. Assuming use of the canonical Mercurial code base, a
688 *decorated*. Assuming use of the canonical Mercurial code base, a
689 formatting string can be the input to the ``i18n._`` function. This
689 formatting string can be the input to the ``i18n._`` function. This
690 allows messages emitted from the server to be localized. So even if
690 allows messages emitted from the server to be localized. So even if
691 the server has different i18n settings, people could see messages in
691 the server has different i18n settings, people could see messages in
692 their *native* settings. Similarly, the use of labels allows
692 their *native* settings. Similarly, the use of labels allows
693 decorations like coloring and underlining to be applied using the
693 decorations like coloring and underlining to be applied using the
694 client's configured rendering settings.
694 client's configured rendering settings.
695
695
696 Formatting strings are similar to ``printf()`` strings or how
696 Formatting strings are similar to ``printf()`` strings or how
697 Python's ``%`` operator works. The only supported formatting sequences
697 Python's ``%`` operator works. The only supported formatting sequences
698 are ``%s`` and ``%%``. ``%s`` will be replaced by whatever the string
698 are ``%s`` and ``%%``. ``%s`` will be replaced by whatever the string
699 at that position resolves to. ``%%`` will be replaced by ``%``. All
699 at that position resolves to. ``%%`` will be replaced by ``%``. All
700 other 2-byte sequences beginning with ``%`` represent a literal
700 other 2-byte sequences beginning with ``%`` represent a literal
701 ``%`` followed by that character. However, future versions of the
701 ``%`` followed by that character. However, future versions of the
702 wire protocol reserve the right to allow clients to opt in to receiving
702 wire protocol reserve the right to allow clients to opt in to receiving
703 formatting strings with additional formatters, hence why ``%%`` is
703 formatting strings with additional formatters, hence why ``%%`` is
704 required to represent the literal ``%``.
704 required to represent the literal ``%``.
705
705
706 The frame payload consists of a CBOR array of CBOR maps. Each map
706 The frame payload consists of a CBOR array of CBOR maps. Each map
707 defines an *atom* of text data to print. Each *atom* has the following
707 defines an *atom* of text data to print. Each *atom* has the following
708 bytestring keys:
708 bytestring keys:
709
709
710 msg
710 msg
711 (bytestring) The formatting string. Content MUST be ASCII.
711 (bytestring) The formatting string. Content MUST be ASCII.
712 args (optional)
712 args (optional)
713 Array of bytestrings defining arguments to the formatting string.
713 Array of bytestrings defining arguments to the formatting string.
714 labels (optional)
714 labels (optional)
715 Array of bytestrings defining labels to apply to this atom.
715 Array of bytestrings defining labels to apply to this atom.
716
716
717 All data to be printed MUST be encoded into a single frame: this frame
717 All data to be printed MUST be encoded into a single frame: this frame
718 does not support spanning data across multiple frames.
718 does not support spanning data across multiple frames.
719
719
720 All textual data encoded in these frames is assumed to be line delimited.
720 All textual data encoded in these frames is assumed to be line delimited.
721 The last atom in the frame SHOULD end with a newline (``\n``). If it
721 The last atom in the frame SHOULD end with a newline (``\n``). If it
722 doesn't, clients MAY add a newline to facilitate immediate printing.
722 doesn't, clients MAY add a newline to facilitate immediate printing.
723
723
724 Progress Update (``0x07``)
724 Progress Update (``0x07``)
725 --------------------------
725 --------------------------
726
726
727 This frame holds the progress of an operation on the peer. Consumption
727 This frame holds the progress of an operation on the peer. Consumption
728 of these frames allows clients to display progress bars, estimated
728 of these frames allows clients to display progress bars, estimated
729 completion times, etc.
729 completion times, etc.
730
730
731 Each frame defines the progress of a single operation on the peer. The
731 Each frame defines the progress of a single operation on the peer. The
732 payload consists of a CBOR map with the following bytestring keys:
732 payload consists of a CBOR map with the following bytestring keys:
733
733
734 topic
734 topic
735 Topic name (string)
735 Topic name (string)
736 pos
736 pos
737 Current numeric position within the topic (integer)
737 Current numeric position within the topic (integer)
738 total
738 total
739 Total/end numeric position of this topic (unsigned integer)
739 Total/end numeric position of this topic (unsigned integer)
740 label (optional)
740 label (optional)
741 Unit label (string)
741 Unit label (string)
742 item (optional)
742 item (optional)
743 Item name (string)
743 Item name (string)
744
744
745 Progress state is created when a frame is received referencing a
745 Progress state is created when a frame is received referencing a
746 *topic* that isn't currently tracked. Progress tracking for that
746 *topic* that isn't currently tracked. Progress tracking for that
747 *topic* is finished when a frame is received reporting the current
747 *topic* is finished when a frame is received reporting the current
748 position of that topic as ``-1``.
748 position of that topic as ``-1``.
749
749
750 Multiple *topics* may be active at any given time.
750 Multiple *topics* may be active at any given time.
751
751
752 Rendering of progress information is not mandated or governed by this
752 Rendering of progress information is not mandated or governed by this
753 specification: implementations MAY render progress information however
753 specification: implementations MAY render progress information however
754 they see fit, including not at all.
754 they see fit, including not at all.
755
755
756 The string data describing the topic SHOULD be static strings to
756 The string data describing the topic SHOULD be static strings to
757 facilitate receivers localizing that string data. The emitter
757 facilitate receivers localizing that string data. The emitter
758 MUST normalize all string data to valid UTF-8 and receivers SHOULD
758 MUST normalize all string data to valid UTF-8 and receivers SHOULD
759 validate that received data conforms to UTF-8. The topic name
759 validate that received data conforms to UTF-8. The topic name
760 SHOULD be ASCII.
760 SHOULD be ASCII.
761
761
762 Stream Encoding Settings (``0x08``)
762 Stream Encoding Settings (``0x08``)
763 -----------------------------------
763 -----------------------------------
764
764
765 This frame type holds information defining the content encoding
765 This frame type holds information defining the content encoding
766 settings for a *stream*.
766 settings for a *stream*.
767
767
768 This frame type is likely consumed by the protocol layer and is not
768 This frame type is likely consumed by the protocol layer and is not
769 passed on to applications.
769 passed on to applications.
770
770
771 This frame type MUST ONLY occur on frames having the *Beginning of Stream*
771 This frame type MUST ONLY occur on frames having the *Beginning of Stream*
772 ``Stream Flag`` set.
772 ``Stream Flag`` set.
773
773
774 The payload of this frame defines what content encoding has (possibly)
774 The payload of this frame defines what content encoding has (possibly)
775 been applied to the payloads of subsequent frames in this stream.
775 been applied to the payloads of subsequent frames in this stream.
776
776
777 The payload begins with an 8-bit integer defining the length of the
777 The payload begins with an 8-bit integer defining the length of the
778 encoding *profile*, followed by the string name of that profile, which
778 encoding *profile*, followed by the string name of that profile, which
779 must be an ASCII string. All bytes that follow can be used by that
779 must be an ASCII string. All bytes that follow can be used by that
780 profile for supplemental settings definitions. See the section below
780 profile for supplemental settings definitions. See the section below
781 on defined encoding profiles.
781 on defined encoding profiles.
782
782
783 Stream States and Flags
783 Stream States and Flags
784 -----------------------
784 -----------------------
785
785
786 Streams can be in two states: *open* and *closed*. An *open* stream
786 Streams can be in two states: *open* and *closed*. An *open* stream
787 is active and frames attached to that stream could arrive at any time.
787 is active and frames attached to that stream could arrive at any time.
788 A *closed* stream is not active. If a frame attached to a *closed*
788 A *closed* stream is not active. If a frame attached to a *closed*
789 stream arrives, that frame MUST have an appropriate stream flag
789 stream arrives, that frame MUST have an appropriate stream flag
790 set indicating beginning of stream. All streams are in the *closed*
790 set indicating beginning of stream. All streams are in the *closed*
791 state by default.
791 state by default.
792
792
793 The ``Stream Flags`` field denotes a set of bit flags for defining
793 The ``Stream Flags`` field denotes a set of bit flags for defining
794 the relationship of this frame within a stream. The following flags
794 the relationship of this frame within a stream. The following flags
795 are defined:
795 are defined:
796
796
797 0x01
797 0x01
798 Beginning of stream. The first frame in the stream MUST set this
798 Beginning of stream. The first frame in the stream MUST set this
799 flag. When received, the ``Stream ID`` this frame is attached to
799 flag. When received, the ``Stream ID`` this frame is attached to
800 becomes ``open``.
800 becomes ``open``.
801
801
802 0x02
802 0x02
803 End of stream. The last frame in a stream MUST set this flag. When
803 End of stream. The last frame in a stream MUST set this flag. When
804 received, the ``Stream ID`` this frame is attached to becomes
804 received, the ``Stream ID`` this frame is attached to becomes
805 ``closed``. Any content encoding context associated with this stream
805 ``closed``. Any content encoding context associated with this stream
806 can be destroyed after processing the payload of this frame.
806 can be destroyed after processing the payload of this frame.
807
807
808 0x04
808 0x04
809 Apply content encoding. When set, any content encoding settings
809 Apply content encoding. When set, any content encoding settings
810 defined by the stream should be applied when attempting to read
810 defined by the stream should be applied when attempting to read
811 the frame. When not set, the frame payload isn't encoded.
811 the frame. When not set, the frame payload isn't encoded.
812
812
813 Streams
813 Streams
814 -------
814 -------
815
815
816 Streams - along with ``Request IDs`` - facilitate grouping of frames.
816 Streams - along with ``Request IDs`` - facilitate grouping of frames.
817 But the purpose of each is quite different and the groupings they
817 But the purpose of each is quite different and the groupings they
818 constitute are independent.
818 constitute are independent.
819
819
820 A ``Request ID`` is essentially a tag. It tells you which logical
820 A ``Request ID`` is essentially a tag. It tells you which logical
821 request a frame is associated with.
821 request a frame is associated with.
822
822
823 A *stream* is a sequence of frames grouped for the express purpose
823 A *stream* is a sequence of frames grouped for the express purpose
824 of applying a stateful encoding or for denoting sub-groups of frames.
824 of applying a stateful encoding or for denoting sub-groups of frames.
825
825
826 Unlike ``Request ID``s which span the request and response, a stream
826 Unlike ``Request ID``s which span the request and response, a stream
827 is unidirectional and stream IDs are independent from client to
827 is unidirectional and stream IDs are independent from client to
828 server.
828 server.
829
829
830 There is no strict hierarchical relationship between ``Request IDs``
830 There is no strict hierarchical relationship between ``Request IDs``
831 and *streams*. A stream can contain frames having multiple
831 and *streams*. A stream can contain frames having multiple
832 ``Request IDs``. Frames belonging to the same ``Request ID`` can
832 ``Request IDs``. Frames belonging to the same ``Request ID`` can
833 span multiple streams.
833 span multiple streams.
834
834
835 One goal of streams is to facilitate content encoding. A stream can
835 One goal of streams is to facilitate content encoding. A stream can
836 define an encoding to be applied to frame payloads. For example, the
836 define an encoding to be applied to frame payloads. For example, the
837 payload transmitted over the wire may contain output from a
837 payload transmitted over the wire may contain output from a
838 zstandard compression operation and the receiving end may decompress
838 zstandard compression operation and the receiving end may decompress
839 that payload to obtain the original data.
839 that payload to obtain the original data.
840
840
841 The other goal of streams is to facilitate concurrent execution. For
841 The other goal of streams is to facilitate concurrent execution. For
842 example, a server could spawn 4 threads to service a request that can
842 example, a server could spawn 4 threads to service a request that can
843 be easily parallelized. Each of those 4 threads could write into its
843 be easily parallelized. Each of those 4 threads could write into its
844 own stream. Those streams could then in turn be delivered to 4 threads
844 own stream. Those streams could then in turn be delivered to 4 threads
845 on the receiving end, with each thread consuming its stream in near
845 on the receiving end, with each thread consuming its stream in near
846 isolation. The *main* thread on both ends merely does I/O and
846 isolation. The *main* thread on both ends merely does I/O and
847 encodes/decodes frame headers: the bulk of the work is done by worker
847 encodes/decodes frame headers: the bulk of the work is done by worker
848 threads.
848 threads.
849
849
850 In addition, since content encoding is defined per stream, each
850 In addition, since content encoding is defined per stream, each
851 *worker thread* could perform potentially CPU bound work concurrently
851 *worker thread* could perform potentially CPU bound work concurrently
852 with other threads. This approach of applying encoding at the
852 with other threads. This approach of applying encoding at the
853 sub-protocol / stream level eliminates a potential resource constraint
853 sub-protocol / stream level eliminates a potential resource constraint
854 on the protocol stream as a whole (it is common for the throughput of
854 on the protocol stream as a whole (it is common for the throughput of
855 a compression engine to be smaller than the throughput of a network).
855 a compression engine to be smaller than the throughput of a network).
856
856
857 Having multiple streams - each with their own encoding settings - also
857 Having multiple streams - each with their own encoding settings - also
858 facilitates the use of advanced data compression techniques. For
858 facilitates the use of advanced data compression techniques. For
859 example, a transmitter could see that it is generating data faster
859 example, a transmitter could see that it is generating data faster
860 and slower than the receiving end is consuming it and adjust its
860 and slower than the receiving end is consuming it and adjust its
861 compression settings to trade CPU for compression ratio accordingly.
861 compression settings to trade CPU for compression ratio accordingly.
862
862
863 While streams can define a content encoding, not all frames within
863 While streams can define a content encoding, not all frames within
864 that stream must use that content encoding. This can be useful when
864 that stream must use that content encoding. This can be useful when
865 data is being served from caches and being derived dynamically. A
865 data is being served from caches and being derived dynamically. A
866 cache could pre-compressed data so the server doesn't have to
866 cache could pre-compressed data so the server doesn't have to
867 recompress it. The ability to pick and choose which frames are
867 recompress it. The ability to pick and choose which frames are
868 compressed allows servers to easily send data to the wire without
868 compressed allows servers to easily send data to the wire without
869 involving potentially expensive encoding overhead.
869 involving potentially expensive encoding overhead.
870
870
871 Content Encoding Profiles
871 Content Encoding Profiles
872 -------------------------
872 -------------------------
873
873
874 Streams can have named content encoding *profiles* associated with
874 Streams can have named content encoding *profiles* associated with
875 them. A profile defines a shared understanding of content encoding
875 them. A profile defines a shared understanding of content encoding
876 settings and behavior.
876 settings and behavior.
877
877
878 The following profiles are defined:
878 The following profiles are defined:
879
879
880 TBD
880 TBD
881
881
882 Issuing Commands
882 Issuing Commands
883 ----------------
883 ----------------
884
884
885 A client can request that a remote run a command by sending it
885 A client can request that a remote run a command by sending it
886 frames defining that command. This logical stream is composed of
886 frames defining that command. This logical stream is composed of
887 1 or more ``Command Request`` frames and and 0 or more ``Command Data``
887 1 or more ``Command Request`` frames and and 0 or more ``Command Data``
888 frames.
888 frames.
889
889
890 All frames composing a single command request MUST be associated with
890 All frames composing a single command request MUST be associated with
891 the same ``Request ID``.
891 the same ``Request ID``.
892
892
893 Clients MAY send additional command requests without waiting on the
893 Clients MAY send additional command requests without waiting on the
894 response to a previous command request. If they do so, they MUST ensure
894 response to a previous command request. If they do so, they MUST ensure
895 that the ``Request ID`` field of outbound frames does not conflict
895 that the ``Request ID`` field of outbound frames does not conflict
896 with that of an active ``Request ID`` whose response has not yet been
896 with that of an active ``Request ID`` whose response has not yet been
897 fully received.
897 fully received.
898
898
899 Servers MAY respond to commands in a different order than they were
899 Servers MAY respond to commands in a different order than they were
900 sent over the wire. Clients MUST be prepared to deal with this. Servers
900 sent over the wire. Clients MUST be prepared to deal with this. Servers
901 also MAY start executing commands in a different order than they were
901 also MAY start executing commands in a different order than they were
902 received, or MAY execute multiple commands concurrently.
902 received, or MAY execute multiple commands concurrently.
903
903
904 If there is a dependency between commands or a race condition between
904 If there is a dependency between commands or a race condition between
905 commands executing (e.g. a read-only command that depends on the results
905 commands executing (e.g. a read-only command that depends on the results
906 of a command that mutates the repository), then clients MUST NOT send
906 of a command that mutates the repository), then clients MUST NOT send
907 frames issuing a command until a response to all dependent commands has
907 frames issuing a command until a response to all dependent commands has
908 been received.
908 been received.
909 TODO think about whether we should express dependencies between commands
909 TODO think about whether we should express dependencies between commands
910 to avoid roundtrip latency.
910 to avoid roundtrip latency.
911
911
912 A command is defined by a command name, 0 or more command arguments,
912 A command is defined by a command name, 0 or more command arguments,
913 and optional command data.
913 and optional command data.
914
914
915 Arguments are the recommended mechanism for transferring fixed sets of
915 Arguments are the recommended mechanism for transferring fixed sets of
916 parameters to a command. Data is appropriate for transferring variable
916 parameters to a command. Data is appropriate for transferring variable
917 data. Thinking in terms of HTTP, arguments would be headers and data
917 data. Thinking in terms of HTTP, arguments would be headers and data
918 would be the message body.
918 would be the message body.
919
919
920 It is recommended for servers to delay the dispatch of a command
920 It is recommended for servers to delay the dispatch of a command
921 until all argument have been received. Servers MAY impose limits on the
921 until all argument have been received. Servers MAY impose limits on the
922 maximum argument size.
922 maximum argument size.
923 TODO define failure mechanism.
923 TODO define failure mechanism.
924
924
925 Servers MAY dispatch to commands immediately once argument data
925 Servers MAY dispatch to commands immediately once argument data
926 is available or delay until command data is received in full.
926 is available or delay until command data is received in full.
927
927
928 Capabilities
928 Capabilities
929 ============
929 ============
930
930
931 Servers advertise supported wire protocol features. This allows clients to
931 Servers advertise supported wire protocol features. This allows clients to
932 probe for server features before blindly calling a command or passing a
932 probe for server features before blindly calling a command or passing a
933 specific argument.
933 specific argument.
934
934
935 The server's features are exposed via a *capabilities* string. This is a
935 The server's features are exposed via a *capabilities* string. This is a
936 space-delimited string of tokens/features. Some features are single words
936 space-delimited string of tokens/features. Some features are single words
937 like ``lookup`` or ``batch``. Others are complicated key-value pairs
937 like ``lookup`` or ``batch``. Others are complicated key-value pairs
938 advertising sub-features. e.g. ``httpheader=2048``. When complex, non-word
938 advertising sub-features. e.g. ``httpheader=2048``. When complex, non-word
939 values are used, each feature name can define its own encoding of sub-values.
939 values are used, each feature name can define its own encoding of sub-values.
940 Comma-delimited and ``x-www-form-urlencoded`` values are common.
940 Comma-delimited and ``x-www-form-urlencoded`` values are common.
941
941
942 The following document capabilities defined by the canonical Mercurial server
942 The following document capabilities defined by the canonical Mercurial server
943 implementation.
943 implementation.
944
944
945 batch
945 batch
946 -----
946 -----
947
947
948 Whether the server supports the ``batch`` command.
948 Whether the server supports the ``batch`` command.
949
949
950 This capability/command was introduced in Mercurial 1.9 (released July 2011).
950 This capability/command was introduced in Mercurial 1.9 (released July 2011).
951
951
952 branchmap
952 branchmap
953 ---------
953 ---------
954
954
955 Whether the server supports the ``branchmap`` command.
955 Whether the server supports the ``branchmap`` command.
956
956
957 This capability/command was introduced in Mercurial 1.3 (released July 2009).
957 This capability/command was introduced in Mercurial 1.3 (released July 2009).
958
958
959 bundle2-exp
959 bundle2-exp
960 -----------
960 -----------
961
961
962 Precursor to ``bundle2`` capability that was used before bundle2 was a
962 Precursor to ``bundle2`` capability that was used before bundle2 was a
963 stable feature.
963 stable feature.
964
964
965 This capability was introduced in Mercurial 3.0 behind an experimental
965 This capability was introduced in Mercurial 3.0 behind an experimental
966 flag. This capability should not be observed in the wild.
966 flag. This capability should not be observed in the wild.
967
967
968 bundle2
968 bundle2
969 -------
969 -------
970
970
971 Indicates whether the server supports the ``bundle2`` data exchange format.
971 Indicates whether the server supports the ``bundle2`` data exchange format.
972
972
973 The value of the capability is a URL quoted, newline (``\n``) delimited
973 The value of the capability is a URL quoted, newline (``\n``) delimited
974 list of keys or key-value pairs.
974 list of keys or key-value pairs.
975
975
976 A key is simply a URL encoded string.
976 A key is simply a URL encoded string.
977
977
978 A key-value pair is a URL encoded key separated from a URL encoded value by
978 A key-value pair is a URL encoded key separated from a URL encoded value by
979 an ``=``. If the value is a list, elements are delimited by a ``,`` after
979 an ``=``. If the value is a list, elements are delimited by a ``,`` after
980 URL encoding.
980 URL encoding.
981
981
982 For example, say we have the values::
982 For example, say we have the values::
983
983
984 {'HG20': [], 'changegroup': ['01', '02'], 'digests': ['sha1', 'sha512']}
984 {'HG20': [], 'changegroup': ['01', '02'], 'digests': ['sha1', 'sha512']}
985
985
986 We would first construct a string::
986 We would first construct a string::
987
987
988 HG20\nchangegroup=01,02\ndigests=sha1,sha512
988 HG20\nchangegroup=01,02\ndigests=sha1,sha512
989
989
990 We would then URL quote this string::
990 We would then URL quote this string::
991
991
992 HG20%0Achangegroup%3D01%2C02%0Adigests%3Dsha1%2Csha512
992 HG20%0Achangegroup%3D01%2C02%0Adigests%3Dsha1%2Csha512
993
993
994 This capability was introduced in Mercurial 3.4 (released May 2015).
994 This capability was introduced in Mercurial 3.4 (released May 2015).
995
995
996 changegroupsubset
996 changegroupsubset
997 -----------------
997 -----------------
998
998
999 Whether the server supports the ``changegroupsubset`` command.
999 Whether the server supports the ``changegroupsubset`` command.
1000
1000
1001 This capability was introduced in Mercurial 0.9.2 (released December
1001 This capability was introduced in Mercurial 0.9.2 (released December
1002 2006).
1002 2006).
1003
1003
1004 This capability was introduced at the same time as the ``lookup``
1004 This capability was introduced at the same time as the ``lookup``
1005 capability/command.
1005 capability/command.
1006
1006
1007 compression
1007 compression
1008 -----------
1008 -----------
1009
1009
1010 Declares support for negotiating compression formats.
1010 Declares support for negotiating compression formats.
1011
1011
1012 Presence of this capability indicates the server supports dynamic selection
1012 Presence of this capability indicates the server supports dynamic selection
1013 of compression formats based on the client request.
1013 of compression formats based on the client request.
1014
1014
1015 Servers advertising this capability are required to support the
1015 Servers advertising this capability are required to support the
1016 ``application/mercurial-0.2`` media type in response to commands returning
1016 ``application/mercurial-0.2`` media type in response to commands returning
1017 streams. Servers may support this media type on any command.
1017 streams. Servers may support this media type on any command.
1018
1018
1019 The value of the capability is a comma-delimited list of strings declaring
1019 The value of the capability is a comma-delimited list of strings declaring
1020 supported compression formats. The order of the compression formats is in
1020 supported compression formats. The order of the compression formats is in
1021 server-preferred order, most preferred first.
1021 server-preferred order, most preferred first.
1022
1022
1023 The identifiers used by the official Mercurial distribution are:
1023 The identifiers used by the official Mercurial distribution are:
1024
1024
1025 bzip2
1025 bzip2
1026 bzip2
1026 bzip2
1027 none
1027 none
1028 uncompressed / raw data
1028 uncompressed / raw data
1029 zlib
1029 zlib
1030 zlib (no gzip header)
1030 zlib (no gzip header)
1031 zstd
1031 zstd
1032 zstd
1032 zstd
1033
1033
1034 This capability was introduced in Mercurial 4.1 (released February 2017).
1034 This capability was introduced in Mercurial 4.1 (released February 2017).
1035
1035
1036 getbundle
1036 getbundle
1037 ---------
1037 ---------
1038
1038
1039 Whether the server supports the ``getbundle`` command.
1039 Whether the server supports the ``getbundle`` command.
1040
1040
1041 This capability was introduced in Mercurial 1.9 (released July 2011).
1041 This capability was introduced in Mercurial 1.9 (released July 2011).
1042
1042
1043 httpheader
1043 httpheader
1044 ----------
1044 ----------
1045
1045
1046 Whether the server supports receiving command arguments via HTTP request
1046 Whether the server supports receiving command arguments via HTTP request
1047 headers.
1047 headers.
1048
1048
1049 The value of the capability is an integer describing the max header
1049 The value of the capability is an integer describing the max header
1050 length that clients should send. Clients should ignore any content after a
1050 length that clients should send. Clients should ignore any content after a
1051 comma in the value, as this is reserved for future use.
1051 comma in the value, as this is reserved for future use.
1052
1052
1053 This capability was introduced in Mercurial 1.9 (released July 2011).
1053 This capability was introduced in Mercurial 1.9 (released July 2011).
1054
1054
1055 httpmediatype
1055 httpmediatype
1056 -------------
1056 -------------
1057
1057
1058 Indicates which HTTP media types (``Content-Type`` header) the server is
1058 Indicates which HTTP media types (``Content-Type`` header) the server is
1059 capable of receiving and sending.
1059 capable of receiving and sending.
1060
1060
1061 The value of the capability is a comma-delimited list of strings identifying
1061 The value of the capability is a comma-delimited list of strings identifying
1062 support for media type and transmission direction. The following strings may
1062 support for media type and transmission direction. The following strings may
1063 be present:
1063 be present:
1064
1064
1065 0.1rx
1065 0.1rx
1066 Indicates server support for receiving ``application/mercurial-0.1`` media
1066 Indicates server support for receiving ``application/mercurial-0.1`` media
1067 types.
1067 types.
1068
1068
1069 0.1tx
1069 0.1tx
1070 Indicates server support for sending ``application/mercurial-0.1`` media
1070 Indicates server support for sending ``application/mercurial-0.1`` media
1071 types.
1071 types.
1072
1072
1073 0.2rx
1073 0.2rx
1074 Indicates server support for receiving ``application/mercurial-0.2`` media
1074 Indicates server support for receiving ``application/mercurial-0.2`` media
1075 types.
1075 types.
1076
1076
1077 0.2tx
1077 0.2tx
1078 Indicates server support for sending ``application/mercurial-0.2`` media
1078 Indicates server support for sending ``application/mercurial-0.2`` media
1079 types.
1079 types.
1080
1080
1081 minrx=X
1081 minrx=X
1082 Minimum media type version the server is capable of receiving. Value is a
1082 Minimum media type version the server is capable of receiving. Value is a
1083 string like ``0.2``.
1083 string like ``0.2``.
1084
1084
1085 This capability can be used by servers to limit connections from legacy
1085 This capability can be used by servers to limit connections from legacy
1086 clients not using the latest supported media type. However, only clients
1086 clients not using the latest supported media type. However, only clients
1087 with knowledge of this capability will know to consult this value. This
1087 with knowledge of this capability will know to consult this value. This
1088 capability is present so the client may issue a more user-friendly error
1088 capability is present so the client may issue a more user-friendly error
1089 when the server has locked out a legacy client.
1089 when the server has locked out a legacy client.
1090
1090
1091 mintx=X
1091 mintx=X
1092 Minimum media type version the server is capable of sending. Value is a
1092 Minimum media type version the server is capable of sending. Value is a
1093 string like ``0.1``.
1093 string like ``0.1``.
1094
1094
1095 Servers advertising support for the ``application/mercurial-0.2`` media type
1095 Servers advertising support for the ``application/mercurial-0.2`` media type
1096 should also advertise the ``compression`` capability.
1096 should also advertise the ``compression`` capability.
1097
1097
1098 This capability was introduced in Mercurial 4.1 (released February 2017).
1098 This capability was introduced in Mercurial 4.1 (released February 2017).
1099
1099
1100 httppostargs
1100 httppostargs
1101 ------------
1101 ------------
1102
1102
1103 **Experimental**
1103 **Experimental**
1104
1104
1105 Indicates that the server supports and prefers clients send command arguments
1105 Indicates that the server supports and prefers clients send command arguments
1106 via a HTTP POST request as part of the request body.
1106 via a HTTP POST request as part of the request body.
1107
1107
1108 This capability was introduced in Mercurial 3.8 (released May 2016).
1108 This capability was introduced in Mercurial 3.8 (released May 2016).
1109
1109
1110 known
1110 known
1111 -----
1111 -----
1112
1112
1113 Whether the server supports the ``known`` command.
1113 Whether the server supports the ``known`` command.
1114
1114
1115 This capability/command was introduced in Mercurial 1.9 (released July 2011).
1115 This capability/command was introduced in Mercurial 1.9 (released July 2011).
1116
1116
1117 lookup
1117 lookup
1118 ------
1118 ------
1119
1119
1120 Whether the server supports the ``lookup`` command.
1120 Whether the server supports the ``lookup`` command.
1121
1121
1122 This capability was introduced in Mercurial 0.9.2 (released December
1122 This capability was introduced in Mercurial 0.9.2 (released December
1123 2006).
1123 2006).
1124
1124
1125 This capability was introduced at the same time as the ``changegroupsubset``
1125 This capability was introduced at the same time as the ``changegroupsubset``
1126 capability/command.
1126 capability/command.
1127
1127
1128 protocaps
1128 protocaps
1129 ---------
1129 ---------
1130
1130
1131 Whether the server supports the ``protocaps`` command for SSH V1 transport.
1131 Whether the server supports the ``protocaps`` command for SSH V1 transport.
1132
1132
1133 This capability was introduced in Mercurial 4.6.
1133 This capability was introduced in Mercurial 4.6.
1134
1134
1135 pushkey
1135 pushkey
1136 -------
1136 -------
1137
1137
1138 Whether the server supports the ``pushkey`` and ``listkeys`` commands.
1138 Whether the server supports the ``pushkey`` and ``listkeys`` commands.
1139
1139
1140 This capability was introduced in Mercurial 1.6 (released July 2010).
1140 This capability was introduced in Mercurial 1.6 (released July 2010).
1141
1141
1142 standardbundle
1142 standardbundle
1143 --------------
1143 --------------
1144
1144
1145 **Unsupported**
1145 **Unsupported**
1146
1146
1147 This capability was introduced during the Mercurial 0.9.2 development cycle in
1147 This capability was introduced during the Mercurial 0.9.2 development cycle in
1148 2006. It was never present in a release, as it was replaced by the ``unbundle``
1148 2006. It was never present in a release, as it was replaced by the ``unbundle``
1149 capability. This capability should not be encountered in the wild.
1149 capability. This capability should not be encountered in the wild.
1150
1150
1151 stream-preferred
1151 stream-preferred
1152 ----------------
1152 ----------------
1153
1153
1154 If present the server prefers that clients clone using the streaming clone
1154 If present the server prefers that clients clone using the streaming clone
1155 protocol (``hg clone --stream``) rather than the standard
1155 protocol (``hg clone --stream``) rather than the standard
1156 changegroup/bundle based protocol.
1156 changegroup/bundle based protocol.
1157
1157
1158 This capability was introduced in Mercurial 2.2 (released May 2012).
1158 This capability was introduced in Mercurial 2.2 (released May 2012).
1159
1159
1160 streamreqs
1160 streamreqs
1161 ----------
1161 ----------
1162
1162
1163 Indicates whether the server supports *streaming clones* and the *requirements*
1163 Indicates whether the server supports *streaming clones* and the *requirements*
1164 that clients must support to receive it.
1164 that clients must support to receive it.
1165
1165
1166 If present, the server supports the ``stream_out`` command, which transmits
1166 If present, the server supports the ``stream_out`` command, which transmits
1167 raw revlogs from the repository instead of changegroups. This provides a faster
1167 raw revlogs from the repository instead of changegroups. This provides a faster
1168 cloning mechanism at the expense of more bandwidth used.
1168 cloning mechanism at the expense of more bandwidth used.
1169
1169
1170 The value of this capability is a comma-delimited list of repo format
1170 The value of this capability is a comma-delimited list of repo format
1171 *requirements*. These are requirements that impact the reading of data in
1171 *requirements*. These are requirements that impact the reading of data in
1172 the ``.hg/store`` directory. An example value is
1172 the ``.hg/store`` directory. An example value is
1173 ``streamreqs=generaldelta,revlogv1`` indicating the server repo requires
1173 ``streamreqs=generaldelta,revlogv1`` indicating the server repo requires
1174 the ``revlogv1`` and ``generaldelta`` requirements.
1174 the ``revlogv1`` and ``generaldelta`` requirements.
1175
1175
1176 If the only format requirement is ``revlogv1``, the server may expose the
1176 If the only format requirement is ``revlogv1``, the server may expose the
1177 ``stream`` capability instead of the ``streamreqs`` capability.
1177 ``stream`` capability instead of the ``streamreqs`` capability.
1178
1178
1179 This capability was introduced in Mercurial 1.7 (released November 2010).
1179 This capability was introduced in Mercurial 1.7 (released November 2010).
1180
1180
1181 stream
1181 stream
1182 ------
1182 ------
1183
1183
1184 Whether the server supports *streaming clones* from ``revlogv1`` repos.
1184 Whether the server supports *streaming clones* from ``revlogv1`` repos.
1185
1185
1186 If present, the server supports the ``stream_out`` command, which transmits
1186 If present, the server supports the ``stream_out`` command, which transmits
1187 raw revlogs from the repository instead of changegroups. This provides a faster
1187 raw revlogs from the repository instead of changegroups. This provides a faster
1188 cloning mechanism at the expense of more bandwidth used.
1188 cloning mechanism at the expense of more bandwidth used.
1189
1189
1190 This capability was introduced in Mercurial 0.9.1 (released July 2006).
1190 This capability was introduced in Mercurial 0.9.1 (released July 2006).
1191
1191
1192 When initially introduced, the value of the capability was the numeric
1192 When initially introduced, the value of the capability was the numeric
1193 revlog revision. e.g. ``stream=1``. This indicates the changegroup is using
1193 revlog revision. e.g. ``stream=1``. This indicates the changegroup is using
1194 ``revlogv1``. This simple integer value wasn't powerful enough, so the
1194 ``revlogv1``. This simple integer value wasn't powerful enough, so the
1195 ``streamreqs`` capability was invented to handle cases where the repo
1195 ``streamreqs`` capability was invented to handle cases where the repo
1196 requirements have more than just ``revlogv1``. Newer servers omit the
1196 requirements have more than just ``revlogv1``. Newer servers omit the
1197 ``=1`` since it was the only value supported and the value of ``1`` can
1197 ``=1`` since it was the only value supported and the value of ``1`` can
1198 be implied by clients.
1198 be implied by clients.
1199
1199
1200 unbundlehash
1200 unbundlehash
1201 ------------
1201 ------------
1202
1202
1203 Whether the ``unbundle`` commands supports receiving a hash of all the
1203 Whether the ``unbundle`` commands supports receiving a hash of all the
1204 heads instead of a list.
1204 heads instead of a list.
1205
1205
1206 For more, see the documentation for the ``unbundle`` command.
1206 For more, see the documentation for the ``unbundle`` command.
1207
1207
1208 This capability was introduced in Mercurial 1.9 (released July 2011).
1208 This capability was introduced in Mercurial 1.9 (released July 2011).
1209
1209
1210 unbundle
1210 unbundle
1211 --------
1211 --------
1212
1212
1213 Whether the server supports pushing via the ``unbundle`` command.
1213 Whether the server supports pushing via the ``unbundle`` command.
1214
1214
1215 This capability/command has been present since Mercurial 0.9.1 (released
1215 This capability/command has been present since Mercurial 0.9.1 (released
1216 July 2006).
1216 July 2006).
1217
1217
1218 Mercurial 0.9.2 (released December 2006) added values to the capability
1218 Mercurial 0.9.2 (released December 2006) added values to the capability
1219 indicating which bundle types the server supports receiving. This value is a
1219 indicating which bundle types the server supports receiving. This value is a
1220 comma-delimited list. e.g. ``HG10GZ,HG10BZ,HG10UN``. The order of values
1220 comma-delimited list. e.g. ``HG10GZ,HG10BZ,HG10UN``. The order of values
1221 reflects the priority/preference of that type, where the first value is the
1221 reflects the priority/preference of that type, where the first value is the
1222 most preferred type.
1222 most preferred type.
1223
1223
1224 Content Negotiation
1224 Content Negotiation
1225 ===================
1225 ===================
1226
1226
1227 The wire protocol has some mechanisms to help peers determine what content
1227 The wire protocol has some mechanisms to help peers determine what content
1228 types and encoding the other side will accept. Historically, these mechanisms
1228 types and encoding the other side will accept. Historically, these mechanisms
1229 have been built into commands themselves because most commands only send a
1229 have been built into commands themselves because most commands only send a
1230 well-defined response type and only certain commands needed to support
1230 well-defined response type and only certain commands needed to support
1231 functionality like compression.
1231 functionality like compression.
1232
1232
1233 Currently, only the HTTP version 1 transport supports content negotiation
1233 Currently, only the HTTP version 1 transport supports content negotiation
1234 at the protocol layer.
1234 at the protocol layer.
1235
1235
1236 HTTP requests advertise supported response formats via the ``X-HgProto-<N>``
1236 HTTP requests advertise supported response formats via the ``X-HgProto-<N>``
1237 request header, where ``<N>`` is an integer starting at 1 allowing the logical
1237 request header, where ``<N>`` is an integer starting at 1 allowing the logical
1238 value to span multiple headers. This value consists of a list of
1238 value to span multiple headers. This value consists of a list of
1239 space-delimited parameters. Each parameter denotes a feature or capability.
1239 space-delimited parameters. Each parameter denotes a feature or capability.
1240
1240
1241 The following parameters are defined:
1241 The following parameters are defined:
1242
1242
1243 0.1
1243 0.1
1244 Indicates the client supports receiving ``application/mercurial-0.1``
1244 Indicates the client supports receiving ``application/mercurial-0.1``
1245 responses.
1245 responses.
1246
1246
1247 0.2
1247 0.2
1248 Indicates the client supports receiving ``application/mercurial-0.2``
1248 Indicates the client supports receiving ``application/mercurial-0.2``
1249 responses.
1249 responses.
1250
1250
1251 comp
1251 comp
1252 Indicates compression formats the client can decode. Value is a list of
1252 Indicates compression formats the client can decode. Value is a list of
1253 comma delimited strings identifying compression formats ordered from
1253 comma delimited strings identifying compression formats ordered from
1254 most preferential to least preferential. e.g. ``comp=zstd,zlib,none``.
1254 most preferential to least preferential. e.g. ``comp=zstd,zlib,none``.
1255
1255
1256 This parameter does not have an effect if only the ``0.1`` parameter
1256 This parameter does not have an effect if only the ``0.1`` parameter
1257 is defined, as support for ``application/mercurial-0.2`` or greater is
1257 is defined, as support for ``application/mercurial-0.2`` or greater is
1258 required to use arbitrary compression formats.
1258 required to use arbitrary compression formats.
1259
1259
1260 If this parameter is not advertised, the server interprets this as
1260 If this parameter is not advertised, the server interprets this as
1261 equivalent to ``zlib,none``.
1261 equivalent to ``zlib,none``.
1262
1262
1263 Clients may choose to only send this header if the ``httpmediatype``
1263 Clients may choose to only send this header if the ``httpmediatype``
1264 server capability is present, as currently all server-side features
1264 server capability is present, as currently all server-side features
1265 consulting this header require the client to opt in to new protocol features
1265 consulting this header require the client to opt in to new protocol features
1266 advertised via the ``httpmediatype`` capability.
1266 advertised via the ``httpmediatype`` capability.
1267
1267
1268 A server that doesn't receive an ``X-HgProto-<N>`` header should infer a
1268 A server that doesn't receive an ``X-HgProto-<N>`` header should infer a
1269 value of ``0.1``. This is compatible with legacy clients.
1269 value of ``0.1``. This is compatible with legacy clients.
1270
1270
1271 A server receiving a request indicating support for multiple media type
1271 A server receiving a request indicating support for multiple media type
1272 versions may respond with any of the supported media types. Not all servers
1272 versions may respond with any of the supported media types. Not all servers
1273 may support all media types on all commands.
1273 may support all media types on all commands.
1274
1274
1275 Commands
1275 Commands
1276 ========
1276 ========
1277
1277
1278 This section contains a list of all wire protocol commands implemented by
1278 This section contains a list of all wire protocol commands implemented by
1279 the canonical Mercurial server.
1279 the canonical Mercurial server.
1280
1280
1281 batch
1281 batch
1282 -----
1282 -----
1283
1283
1284 Issue multiple commands while sending a single command request. The purpose
1284 Issue multiple commands while sending a single command request. The purpose
1285 of this command is to allow a client to issue multiple commands while avoiding
1285 of this command is to allow a client to issue multiple commands while avoiding
1286 multiple round trips to the server therefore enabling commands to complete
1286 multiple round trips to the server therefore enabling commands to complete
1287 quicker.
1287 quicker.
1288
1288
1289 The command accepts a ``cmds`` argument that contains a list of commands to
1289 The command accepts a ``cmds`` argument that contains a list of commands to
1290 execute.
1290 execute.
1291
1291
1292 The value of ``cmds`` is a ``;`` delimited list of strings. Each string has the
1292 The value of ``cmds`` is a ``;`` delimited list of strings. Each string has the
1293 form ``<command> <arguments>``. That is, the command name followed by a space
1293 form ``<command> <arguments>``. That is, the command name followed by a space
1294 followed by an argument string.
1294 followed by an argument string.
1295
1295
1296 The argument string is a ``,`` delimited list of ``<key>=<value>`` values
1296 The argument string is a ``,`` delimited list of ``<key>=<value>`` values
1297 corresponding to command arguments. Both the argument name and value are
1297 corresponding to command arguments. Both the argument name and value are
1298 escaped using a special substitution map::
1298 escaped using a special substitution map::
1299
1299
1300 : -> :c
1300 : -> :c
1301 , -> :o
1301 , -> :o
1302 ; -> :s
1302 ; -> :s
1303 = -> :e
1303 = -> :e
1304
1304
1305 The response type for this command is ``string``. The value contains a
1305 The response type for this command is ``string``. The value contains a
1306 ``;`` delimited list of responses for each requested command. Each value
1306 ``;`` delimited list of responses for each requested command. Each value
1307 in this list is escaped using the same substitution map used for arguments.
1307 in this list is escaped using the same substitution map used for arguments.
1308
1308
1309 If an error occurs, the generic error response may be sent.
1309 If an error occurs, the generic error response may be sent.
1310
1310
1311 between
1311 between
1312 -------
1312 -------
1313
1313
1314 (Legacy command used for discovery in old clients)
1314 (Legacy command used for discovery in old clients)
1315
1315
1316 Obtain nodes between pairs of nodes.
1316 Obtain nodes between pairs of nodes.
1317
1317
1318 The ``pairs`` arguments contains a space-delimited list of ``-`` delimited
1318 The ``pairs`` arguments contains a space-delimited list of ``-`` delimited
1319 hex node pairs. e.g.::
1319 hex node pairs. e.g.::
1320
1320
1321 a072279d3f7fd3a4aa7ffa1a5af8efc573e1c896-6dc58916e7c070f678682bfe404d2e2d68291a18
1321 a072279d3f7fd3a4aa7ffa1a5af8efc573e1c896-6dc58916e7c070f678682bfe404d2e2d68291a18
1322
1322
1323 Return type is a ``string``. Value consists of lines corresponding to each
1323 Return type is a ``string``. Value consists of lines corresponding to each
1324 requested range. Each line contains a space-delimited list of hex nodes.
1324 requested range. Each line contains a space-delimited list of hex nodes.
1325 A newline ``\n`` terminates each line, including the last one.
1325 A newline ``\n`` terminates each line, including the last one.
1326
1326
1327 branchmap
1327 branchmap
1328 ---------
1328 ---------
1329
1329
1330 Obtain heads in named branches.
1330 Obtain heads in named branches.
1331
1331
1332 Accepts no arguments. Return type is a ``string``.
1332 Accepts no arguments. Return type is a ``string``.
1333
1333
1334 Return value contains lines with URL encoded branch names followed by a space
1334 Return value contains lines with URL encoded branch names followed by a space
1335 followed by a space-delimited list of hex nodes of heads on that branch.
1335 followed by a space-delimited list of hex nodes of heads on that branch.
1336 e.g.::
1336 e.g.::
1337
1337
1338 default a072279d3f7fd3a4aa7ffa1a5af8efc573e1c896 6dc58916e7c070f678682bfe404d2e2d68291a18
1338 default a072279d3f7fd3a4aa7ffa1a5af8efc573e1c896 6dc58916e7c070f678682bfe404d2e2d68291a18
1339 stable baae3bf31522f41dd5e6d7377d0edd8d1cf3fccc
1339 stable baae3bf31522f41dd5e6d7377d0edd8d1cf3fccc
1340
1340
1341 There is no trailing newline.
1341 There is no trailing newline.
1342
1342
1343 branches
1343 branches
1344 --------
1344 --------
1345
1345
1346 (Legacy command used for discovery in old clients. Clients with ``getbundle``
1346 (Legacy command used for discovery in old clients. Clients with ``getbundle``
1347 use the ``known`` and ``heads`` commands instead.)
1347 use the ``known`` and ``heads`` commands instead.)
1348
1348
1349 Obtain ancestor changesets of specific nodes back to a branch point.
1349 Obtain ancestor changesets of specific nodes back to a branch point.
1350
1350
1351 Despite the name, this command has nothing to do with Mercurial named branches.
1351 Despite the name, this command has nothing to do with Mercurial named branches.
1352 Instead, it is related to DAG branches.
1352 Instead, it is related to DAG branches.
1353
1353
1354 The command accepts a ``nodes`` argument, which is a string of space-delimited
1354 The command accepts a ``nodes`` argument, which is a string of space-delimited
1355 hex nodes.
1355 hex nodes.
1356
1356
1357 For each node requested, the server will find the first ancestor node that is
1357 For each node requested, the server will find the first ancestor node that is
1358 a DAG root or is a merge.
1358 a DAG root or is a merge.
1359
1359
1360 Return type is a ``string``. Return value contains lines with result data for
1360 Return type is a ``string``. Return value contains lines with result data for
1361 each requested node. Each line contains space-delimited nodes followed by a
1361 each requested node. Each line contains space-delimited nodes followed by a
1362 newline (``\n``). The 4 nodes reported on each line correspond to the requested
1362 newline (``\n``). The 4 nodes reported on each line correspond to the requested
1363 node, the ancestor node found, and its 2 parent nodes (which may be the null
1363 node, the ancestor node found, and its 2 parent nodes (which may be the null
1364 node).
1364 node).
1365
1365
1366 capabilities
1366 capabilities
1367 ------------
1367 ------------
1368
1368
1369 Obtain the capabilities string for the repo.
1369 Obtain the capabilities string for the repo.
1370
1370
1371 Unlike the ``hello`` command, the capabilities string is not prefixed.
1371 Unlike the ``hello`` command, the capabilities string is not prefixed.
1372 There is no trailing newline.
1372 There is no trailing newline.
1373
1373
1374 This command does not accept any arguments. Return type is a ``string``.
1374 This command does not accept any arguments. Return type is a ``string``.
1375
1375
1376 This command was introduced in Mercurial 0.9.1 (released July 2006).
1376 This command was introduced in Mercurial 0.9.1 (released July 2006).
1377
1377
1378 changegroup
1378 changegroup
1379 -----------
1379 -----------
1380
1380
1381 (Legacy command: use ``getbundle`` instead)
1381 (Legacy command: use ``getbundle`` instead)
1382
1382
1383 Obtain a changegroup version 1 with data for changesets that are
1383 Obtain a changegroup version 1 with data for changesets that are
1384 descendants of client-specified changesets.
1384 descendants of client-specified changesets.
1385
1385
1386 The ``roots`` arguments contains a list of space-delimited hex nodes.
1386 The ``roots`` arguments contains a list of space-delimited hex nodes.
1387
1387
1388 The server responds with a changegroup version 1 containing all
1388 The server responds with a changegroup version 1 containing all
1389 changesets between the requested root/base nodes and the repo's head nodes
1389 changesets between the requested root/base nodes and the repo's head nodes
1390 at the time of the request.
1390 at the time of the request.
1391
1391
1392 The return type is a ``stream``.
1392 The return type is a ``stream``.
1393
1393
1394 changegroupsubset
1394 changegroupsubset
1395 -----------------
1395 -----------------
1396
1396
1397 (Legacy command: use ``getbundle`` instead)
1397 (Legacy command: use ``getbundle`` instead)
1398
1398
1399 Obtain a changegroup version 1 with data for changesetsets between
1399 Obtain a changegroup version 1 with data for changesetsets between
1400 client specified base and head nodes.
1400 client specified base and head nodes.
1401
1401
1402 The ``bases`` argument contains a list of space-delimited hex nodes.
1402 The ``bases`` argument contains a list of space-delimited hex nodes.
1403 The ``heads`` argument contains a list of space-delimited hex nodes.
1403 The ``heads`` argument contains a list of space-delimited hex nodes.
1404
1404
1405 The server responds with a changegroup version 1 containing all
1405 The server responds with a changegroup version 1 containing all
1406 changesets between the requested base and head nodes at the time of the
1406 changesets between the requested base and head nodes at the time of the
1407 request.
1407 request.
1408
1408
1409 The return type is a ``stream``.
1409 The return type is a ``stream``.
1410
1410
1411 clonebundles
1411 clonebundles
1412 ------------
1412 ------------
1413
1413
1414 Obtains a manifest of bundle URLs available to seed clones.
1414 Obtains a manifest of bundle URLs available to seed clones.
1415
1415
1416 Each returned line contains a URL followed by metadata. See the
1416 Each returned line contains a URL followed by metadata. See the
1417 documentation in the ``clonebundles`` extension for more.
1417 documentation in the ``clonebundles`` extension for more.
1418
1418
1419 The return type is a ``string``.
1419 The return type is a ``string``.
1420
1420
1421 getbundle
1421 getbundle
1422 ---------
1422 ---------
1423
1423
1424 Obtain a bundle containing repository data.
1424 Obtain a bundle containing repository data.
1425
1425
1426 This command accepts the following arguments:
1426 This command accepts the following arguments:
1427
1427
1428 heads
1428 heads
1429 List of space-delimited hex nodes of heads to retrieve.
1429 List of space-delimited hex nodes of heads to retrieve.
1430 common
1430 common
1431 List of space-delimited hex nodes that the client has in common with the
1431 List of space-delimited hex nodes that the client has in common with the
1432 server.
1432 server.
1433 obsmarkers
1433 obsmarkers
1434 Boolean indicating whether to include obsolescence markers as part
1434 Boolean indicating whether to include obsolescence markers as part
1435 of the response. Only works with bundle2.
1435 of the response. Only works with bundle2.
1436 bundlecaps
1436 bundlecaps
1437 Comma-delimited set of strings defining client bundle capabilities.
1437 Comma-delimited set of strings defining client bundle capabilities.
1438 listkeys
1438 listkeys
1439 Comma-delimited list of strings of ``pushkey`` namespaces. For each
1439 Comma-delimited list of strings of ``pushkey`` namespaces. For each
1440 namespace listed, a bundle2 part will be included with the content of
1440 namespace listed, a bundle2 part will be included with the content of
1441 that namespace.
1441 that namespace.
1442 cg
1442 cg
1443 Boolean indicating whether changegroup data is requested.
1443 Boolean indicating whether changegroup data is requested.
1444 cbattempted
1444 cbattempted
1445 Boolean indicating whether the client attempted to use the *clone bundles*
1445 Boolean indicating whether the client attempted to use the *clone bundles*
1446 feature before performing this request.
1446 feature before performing this request.
1447 bookmarks
1447 bookmarks
1448 Boolean indicating whether bookmark data is requested.
1448 Boolean indicating whether bookmark data is requested.
1449 phases
1449 phases
1450 Boolean indicating whether phases data is requested.
1450 Boolean indicating whether phases data is requested.
1451
1451
1452 The return type on success is a ``stream`` where the value is bundle.
1452 The return type on success is a ``stream`` where the value is bundle.
1453 On the HTTP version 1 transport, the response is zlib compressed.
1453 On the HTTP version 1 transport, the response is zlib compressed.
1454
1454
1455 If an error occurs, a generic error response can be sent.
1455 If an error occurs, a generic error response can be sent.
1456
1456
1457 Unless the client sends a false value for the ``cg`` argument, the returned
1457 Unless the client sends a false value for the ``cg`` argument, the returned
1458 bundle contains a changegroup with the nodes between the specified ``common``
1458 bundle contains a changegroup with the nodes between the specified ``common``
1459 and ``heads`` nodes. Depending on the command arguments, the type and content
1459 and ``heads`` nodes. Depending on the command arguments, the type and content
1460 of the returned bundle can vary significantly.
1460 of the returned bundle can vary significantly.
1461
1461
1462 The default behavior is for the server to send a raw changegroup version
1462 The default behavior is for the server to send a raw changegroup version
1463 ``01`` response.
1463 ``01`` response.
1464
1464
1465 If the ``bundlecaps`` provided by the client contain a value beginning
1465 If the ``bundlecaps`` provided by the client contain a value beginning
1466 with ``HG2``, a bundle2 will be returned. The bundle2 data may contain
1466 with ``HG2``, a bundle2 will be returned. The bundle2 data may contain
1467 additional repository data, such as ``pushkey`` namespace values.
1467 additional repository data, such as ``pushkey`` namespace values.
1468
1468
1469 heads
1469 heads
1470 -----
1470 -----
1471
1471
1472 Returns a list of space-delimited hex nodes of repository heads followed
1472 Returns a list of space-delimited hex nodes of repository heads followed
1473 by a newline. e.g.
1473 by a newline. e.g.
1474 ``a9eeb3adc7ddb5006c088e9eda61791c777cbf7c 31f91a3da534dc849f0d6bfc00a395a97cf218a1\n``
1474 ``a9eeb3adc7ddb5006c088e9eda61791c777cbf7c 31f91a3da534dc849f0d6bfc00a395a97cf218a1\n``
1475
1475
1476 This command does not accept any arguments. The return type is a ``string``.
1476 This command does not accept any arguments. The return type is a ``string``.
1477
1477
1478 hello
1478 hello
1479 -----
1479 -----
1480
1480
1481 Returns lines describing interesting things about the server in an RFC-822
1481 Returns lines describing interesting things about the server in an RFC-822
1482 like format.
1482 like format.
1483
1483
1484 Currently, the only line defines the server capabilities. It has the form::
1484 Currently, the only line defines the server capabilities. It has the form::
1485
1485
1486 capabilities: <value>
1486 capabilities: <value>
1487
1487
1488 See above for more about the capabilities string.
1488 See above for more about the capabilities string.
1489
1489
1490 SSH clients typically issue this command as soon as a connection is
1490 SSH clients typically issue this command as soon as a connection is
1491 established.
1491 established.
1492
1492
1493 This command does not accept any arguments. The return type is a ``string``.
1493 This command does not accept any arguments. The return type is a ``string``.
1494
1494
1495 This command was introduced in Mercurial 0.9.1 (released July 2006).
1495 This command was introduced in Mercurial 0.9.1 (released July 2006).
1496
1496
1497 listkeys
1497 listkeys
1498 --------
1498 --------
1499
1499
1500 List values in a specified ``pushkey`` namespace.
1500 List values in a specified ``pushkey`` namespace.
1501
1501
1502 The ``namespace`` argument defines the pushkey namespace to operate on.
1502 The ``namespace`` argument defines the pushkey namespace to operate on.
1503
1503
1504 The return type is a ``string``. The value is an encoded dictionary of keys.
1504 The return type is a ``string``. The value is an encoded dictionary of keys.
1505
1505
1506 Key-value pairs are delimited by newlines (``\n``). Within each line, keys and
1506 Key-value pairs are delimited by newlines (``\n``). Within each line, keys and
1507 values are separated by a tab (``\t``). Keys and values are both strings.
1507 values are separated by a tab (``\t``). Keys and values are both strings.
1508
1508
1509 lookup
1509 lookup
1510 ------
1510 ------
1511
1511
1512 Try to resolve a value to a known repository revision.
1512 Try to resolve a value to a known repository revision.
1513
1513
1514 The ``key`` argument is converted from bytes to an
1514 The ``key`` argument is converted from bytes to an
1515 ``encoding.localstr`` instance then passed into
1515 ``encoding.localstr`` instance then passed into
1516 ``localrepository.__getitem__`` in an attempt to resolve it.
1516 ``localrepository.__getitem__`` in an attempt to resolve it.
1517
1517
1518 The return type is a ``string``.
1518 The return type is a ``string``.
1519
1519
1520 Upon successful resolution, returns ``1 <hex node>\n``. On failure,
1520 Upon successful resolution, returns ``1 <hex node>\n``. On failure,
1521 returns ``0 <error string>\n``. e.g.::
1521 returns ``0 <error string>\n``. e.g.::
1522
1522
1523 1 273ce12ad8f155317b2c078ec75a4eba507f1fba\n
1523 1 273ce12ad8f155317b2c078ec75a4eba507f1fba\n
1524
1524
1525 0 unknown revision 'foo'\n
1525 0 unknown revision 'foo'\n
1526
1526
1527 known
1527 known
1528 -----
1528 -----
1529
1529
1530 Determine whether multiple nodes are known.
1530 Determine whether multiple nodes are known.
1531
1531
1532 The ``nodes`` argument is a list of space-delimited hex nodes to check
1532 The ``nodes`` argument is a list of space-delimited hex nodes to check
1533 for existence.
1533 for existence.
1534
1534
1535 The return type is ``string``.
1535 The return type is ``string``.
1536
1536
1537 Returns a string consisting of ``0``s and ``1``s indicating whether nodes
1537 Returns a string consisting of ``0``s and ``1``s indicating whether nodes
1538 are known. If the Nth node specified in the ``nodes`` argument is known,
1538 are known. If the Nth node specified in the ``nodes`` argument is known,
1539 a ``1`` will be returned at byte offset N. If the node isn't known, ``0``
1539 a ``1`` will be returned at byte offset N. If the node isn't known, ``0``
1540 will be present at byte offset N.
1540 will be present at byte offset N.
1541
1541
1542 There is no trailing newline.
1542 There is no trailing newline.
1543
1543
1544 protocaps
1544 protocaps
1545 ---------
1545 ---------
1546
1546
1547 Notify the server about the client capabilities in the SSH V1 transport
1547 Notify the server about the client capabilities in the SSH V1 transport
1548 protocol.
1548 protocol.
1549
1549
1550 The ``caps`` argument is a space-delimited list of capabilities.
1550 The ``caps`` argument is a space-delimited list of capabilities.
1551
1551
1552 The server will reply with the string ``OK``.
1552 The server will reply with the string ``OK``.
1553
1553
1554 pushkey
1554 pushkey
1555 -------
1555 -------
1556
1556
1557 Set a value using the ``pushkey`` protocol.
1557 Set a value using the ``pushkey`` protocol.
1558
1558
1559 Accepts arguments ``namespace``, ``key``, ``old``, and ``new``, which
1559 Accepts arguments ``namespace``, ``key``, ``old``, and ``new``, which
1560 correspond to the pushkey namespace to operate on, the key within that
1560 correspond to the pushkey namespace to operate on, the key within that
1561 namespace to change, the old value (which may be empty), and the new value.
1561 namespace to change, the old value (which may be empty), and the new value.
1562 All arguments are string types.
1562 All arguments are string types.
1563
1563
1564 The return type is a ``string``. The value depends on the transport protocol.
1564 The return type is a ``string``. The value depends on the transport protocol.
1565
1565
1566 The SSH version 1 transport sends a string encoded integer followed by a
1566 The SSH version 1 transport sends a string encoded integer followed by a
1567 newline (``\n``) which indicates operation result. The server may send
1567 newline (``\n``) which indicates operation result. The server may send
1568 additional output on the ``stderr`` stream that should be displayed to the
1568 additional output on the ``stderr`` stream that should be displayed to the
1569 user.
1569 user.
1570
1570
1571 The HTTP version 1 transport sends a string encoded integer followed by a
1571 The HTTP version 1 transport sends a string encoded integer followed by a
1572 newline followed by additional server output that should be displayed to
1572 newline followed by additional server output that should be displayed to
1573 the user. This may include output from hooks, etc.
1573 the user. This may include output from hooks, etc.
1574
1574
1575 The integer result varies by namespace. ``0`` means an error has occurred
1575 The integer result varies by namespace. ``0`` means an error has occurred
1576 and there should be additional output to display to the user.
1576 and there should be additional output to display to the user.
1577
1577
1578 stream_out
1578 stream_out
1579 ----------
1579 ----------
1580
1580
1581 Obtain *streaming clone* data.
1581 Obtain *streaming clone* data.
1582
1582
1583 The return type is either a ``string`` or a ``stream``, depending on
1583 The return type is either a ``string`` or a ``stream``, depending on
1584 whether the request was fulfilled properly.
1584 whether the request was fulfilled properly.
1585
1585
1586 A return value of ``1\n`` indicates the server is not configured to serve
1586 A return value of ``1\n`` indicates the server is not configured to serve
1587 this data. If this is seen by the client, they may not have verified the
1587 this data. If this is seen by the client, they may not have verified the
1588 ``stream`` capability is set before making the request.
1588 ``stream`` capability is set before making the request.
1589
1589
1590 A return value of ``2\n`` indicates the server was unable to lock the
1590 A return value of ``2\n`` indicates the server was unable to lock the
1591 repository to generate data.
1591 repository to generate data.
1592
1592
1593 All other responses are a ``stream`` of bytes. The first line of this data
1593 All other responses are a ``stream`` of bytes. The first line of this data
1594 contains 2 space-delimited integers corresponding to the path count and
1594 contains 2 space-delimited integers corresponding to the path count and
1595 payload size, respectively::
1595 payload size, respectively::
1596
1596
1597 <path count> <payload size>\n
1597 <path count> <payload size>\n
1598
1598
1599 The ``<payload size>`` is the total size of path data: it does not include
1599 The ``<payload size>`` is the total size of path data: it does not include
1600 the size of the per-path header lines.
1600 the size of the per-path header lines.
1601
1601
1602 Following that header are ``<path count>`` entries. Each entry consists of a
1602 Following that header are ``<path count>`` entries. Each entry consists of a
1603 line with metadata followed by raw revlog data. The line consists of::
1603 line with metadata followed by raw revlog data. The line consists of::
1604
1604
1605 <store path>\0<size>\n
1605 <store path>\0<size>\n
1606
1606
1607 The ``<store path>`` is the encoded store path of the data that follows.
1607 The ``<store path>`` is the encoded store path of the data that follows.
1608 ``<size>`` is the amount of data for this store path/revlog that follows the
1608 ``<size>`` is the amount of data for this store path/revlog that follows the
1609 newline.
1609 newline.
1610
1610
1611 There is no trailer to indicate end of data. Instead, the client should stop
1611 There is no trailer to indicate end of data. Instead, the client should stop
1612 reading after ``<path count>`` entries are consumed.
1612 reading after ``<path count>`` entries are consumed.
1613
1613
1614 unbundle
1614 unbundle
1615 --------
1615 --------
1616
1616
1617 Send a bundle containing data (usually changegroup data) to the server.
1617 Send a bundle containing data (usually changegroup data) to the server.
1618
1618
1619 Accepts the argument ``heads``, which is a space-delimited list of hex nodes
1619 Accepts the argument ``heads``, which is a space-delimited list of hex nodes
1620 corresponding to server repository heads observed by the client. This is used
1620 corresponding to server repository heads observed by the client. This is used
1621 to detect race conditions and abort push operations before a server performs
1621 to detect race conditions and abort push operations before a server performs
1622 too much work or a client transfers too much data.
1622 too much work or a client transfers too much data.
1623
1623
1624 The request payload consists of a bundle to be applied to the repository,
1624 The request payload consists of a bundle to be applied to the repository,
1625 similarly to as if :hg:`unbundle` were called.
1625 similarly to as if :hg:`unbundle` were called.
1626
1626
1627 In most scenarios, a special ``push response`` type is returned. This type
1627 In most scenarios, a special ``push response`` type is returned. This type
1628 contains an integer describing the change in heads as a result of the
1628 contains an integer describing the change in heads as a result of the
1629 operation. A value of ``0`` indicates nothing changed. ``1`` means the number
1629 operation. A value of ``0`` indicates nothing changed. ``1`` means the number
1630 of heads remained the same. Values ``2`` and larger indicate the number of
1630 of heads remained the same. Values ``2`` and larger indicate the number of
1631 added heads minus 1. e.g. ``3`` means 2 heads were added. Negative values
1631 added heads minus 1. e.g. ``3`` means 2 heads were added. Negative values
1632 indicate the number of fewer heads, also off by 1. e.g. ``-2`` means there
1632 indicate the number of fewer heads, also off by 1. e.g. ``-2`` means there
1633 is 1 fewer head.
1633 is 1 fewer head.
1634
1634
1635 The encoding of the ``push response`` type varies by transport.
1635 The encoding of the ``push response`` type varies by transport.
1636
1636
1637 For the SSH version 1 transport, this type is composed of 2 ``string``
1637 For the SSH version 1 transport, this type is composed of 2 ``string``
1638 responses: an empty response (``0\n``) followed by the integer result value.
1638 responses: an empty response (``0\n``) followed by the integer result value.
1639 e.g. ``1\n2``. So the full response might be ``0\n1\n2``.
1639 e.g. ``1\n2``. So the full response might be ``0\n1\n2``.
1640
1640
1641 For the HTTP version 1 transport, the response is a ``string`` type composed
1641 For the HTTP version 1 transport, the response is a ``string`` type composed
1642 of an integer result value followed by a newline (``\n``) followed by string
1642 of an integer result value followed by a newline (``\n``) followed by string
1643 content holding server output that should be displayed on the client (output
1643 content holding server output that should be displayed on the client (output
1644 hooks, etc).
1644 hooks, etc).
1645
1645
1646 In some cases, the server may respond with a ``bundle2`` bundle. In this
1646 In some cases, the server may respond with a ``bundle2`` bundle. In this
1647 case, the response type is ``stream``. For the HTTP version 1 transport, the
1647 case, the response type is ``stream``. For the HTTP version 1 transport, the
1648 response is zlib compressed.
1648 response is zlib compressed.
1649
1649
1650 The server may also respond with a generic error type, which contains a string
1650 The server may also respond with a generic error type, which contains a string
1651 indicating the failure.
1651 indicating the failure.
1652
1652
1653 Frame-Based Protocol Commands
1653 Frame-Based Protocol Commands
1654 =============================
1654 =============================
1655
1655
1656 **Experimental and under active development**
1656 **Experimental and under active development**
1657
1657
1658 This section documents the wire protocol commands exposed to transports
1658 This section documents the wire protocol commands exposed to transports
1659 using the frame-based protocol. The set of commands exposed through
1659 using the frame-based protocol. The set of commands exposed through
1660 these transports is distinct from the set of commands exposed to legacy
1660 these transports is distinct from the set of commands exposed to legacy
1661 transports.
1661 transports.
1662
1662
1663 The frame-based protocol uses CBOR to encode command execution requests.
1663 The frame-based protocol uses CBOR to encode command execution requests.
1664 All command arguments must be mapped to a specific or set of CBOR data
1664 All command arguments must be mapped to a specific or set of CBOR data
1665 types.
1665 types.
1666
1666
1667 The response to many commands is also CBOR. There is no common response
1667 The response to many commands is also CBOR. There is no common response
1668 format: each command defines its own response format.
1668 format: each command defines its own response format.
1669
1669
1670 TODO require node type be specified, as N bytes of binary node value
1670 TODO require node type be specified, as N bytes of binary node value
1671 could be ambiguous once SHA-1 is replaced.
1671 could be ambiguous once SHA-1 is replaced.
1672
1672
1673 heads
1673 heads
1674 -----
1674 -----
1675
1675
1676 Obtain DAG heads in the repository.
1676 Obtain DAG heads in the repository.
1677
1677
1678 The command accepts the following arguments:
1678 The command accepts the following arguments:
1679
1679
1680 publiconly (optional)
1680 publiconly (optional)
1681 (boolean) If set, operate on the DAG for public phase changesets only.
1681 (boolean) If set, operate on the DAG for public phase changesets only.
1682 Non-public (i.e. draft) phase DAG heads will not be returned.
1682 Non-public (i.e. draft) phase DAG heads will not be returned.
1683
1683
1684 The response is a CBOR array of bytestrings defining changeset nodes
1684 The response is a CBOR array of bytestrings defining changeset nodes
1685 of DAG heads. The array can be empty if the repository is empty or no
1685 of DAG heads. The array can be empty if the repository is empty or no
1686 changesets satisfied the request.
1686 changesets satisfied the request.
1687
1687
1688 TODO consider exposing phase of heads in response
1688 TODO consider exposing phase of heads in response
1689
1690 known
1691 -----
1692
1693 Determine whether a series of changeset nodes is known to the server.
1694
1695 The command accepts the following arguments:
1696
1697 nodes
1698 (array of bytestrings) List of changeset nodes whose presence to
1699 query.
1700
1701 The response is a bytestring where each byte contains a 0 or 1 for the
1702 corresponding requested node at the same index.
1703
1704 TODO use a bit array for even more compact response
@@ -1,1217 +1,1225 b''
1 # wireproto.py - generic wire protocol support functions
1 # wireproto.py - generic wire protocol support functions
2 #
2 #
3 # Copyright 2005-2010 Matt Mackall <mpm@selenic.com>
3 # Copyright 2005-2010 Matt Mackall <mpm@selenic.com>
4 #
4 #
5 # This software may be used and distributed according to the terms of the
5 # This software may be used and distributed according to the terms of the
6 # GNU General Public License version 2 or any later version.
6 # GNU General Public License version 2 or any later version.
7
7
8 from __future__ import absolute_import
8 from __future__ import absolute_import
9
9
10 import hashlib
10 import hashlib
11 import os
11 import os
12 import tempfile
12 import tempfile
13
13
14 from .i18n import _
14 from .i18n import _
15 from .node import (
15 from .node import (
16 bin,
16 bin,
17 hex,
17 hex,
18 nullid,
18 nullid,
19 )
19 )
20
20
21 from . import (
21 from . import (
22 bundle2,
22 bundle2,
23 changegroup as changegroupmod,
23 changegroup as changegroupmod,
24 discovery,
24 discovery,
25 encoding,
25 encoding,
26 error,
26 error,
27 exchange,
27 exchange,
28 peer,
28 peer,
29 pushkey as pushkeymod,
29 pushkey as pushkeymod,
30 pycompat,
30 pycompat,
31 repository,
31 repository,
32 streamclone,
32 streamclone,
33 util,
33 util,
34 wireprototypes,
34 wireprototypes,
35 )
35 )
36
36
37 from .utils import (
37 from .utils import (
38 procutil,
38 procutil,
39 stringutil,
39 stringutil,
40 )
40 )
41
41
42 urlerr = util.urlerr
42 urlerr = util.urlerr
43 urlreq = util.urlreq
43 urlreq = util.urlreq
44
44
45 bundle2requiredmain = _('incompatible Mercurial client; bundle2 required')
45 bundle2requiredmain = _('incompatible Mercurial client; bundle2 required')
46 bundle2requiredhint = _('see https://www.mercurial-scm.org/wiki/'
46 bundle2requiredhint = _('see https://www.mercurial-scm.org/wiki/'
47 'IncompatibleClient')
47 'IncompatibleClient')
48 bundle2required = '%s\n(%s)\n' % (bundle2requiredmain, bundle2requiredhint)
48 bundle2required = '%s\n(%s)\n' % (bundle2requiredmain, bundle2requiredhint)
49
49
50 class remoteiterbatcher(peer.iterbatcher):
50 class remoteiterbatcher(peer.iterbatcher):
51 def __init__(self, remote):
51 def __init__(self, remote):
52 super(remoteiterbatcher, self).__init__()
52 super(remoteiterbatcher, self).__init__()
53 self._remote = remote
53 self._remote = remote
54
54
55 def __getattr__(self, name):
55 def __getattr__(self, name):
56 # Validate this method is batchable, since submit() only supports
56 # Validate this method is batchable, since submit() only supports
57 # batchable methods.
57 # batchable methods.
58 fn = getattr(self._remote, name)
58 fn = getattr(self._remote, name)
59 if not getattr(fn, 'batchable', None):
59 if not getattr(fn, 'batchable', None):
60 raise error.ProgrammingError('Attempted to batch a non-batchable '
60 raise error.ProgrammingError('Attempted to batch a non-batchable '
61 'call to %r' % name)
61 'call to %r' % name)
62
62
63 return super(remoteiterbatcher, self).__getattr__(name)
63 return super(remoteiterbatcher, self).__getattr__(name)
64
64
65 def submit(self):
65 def submit(self):
66 """Break the batch request into many patch calls and pipeline them.
66 """Break the batch request into many patch calls and pipeline them.
67
67
68 This is mostly valuable over http where request sizes can be
68 This is mostly valuable over http where request sizes can be
69 limited, but can be used in other places as well.
69 limited, but can be used in other places as well.
70 """
70 """
71 # 2-tuple of (command, arguments) that represents what will be
71 # 2-tuple of (command, arguments) that represents what will be
72 # sent over the wire.
72 # sent over the wire.
73 requests = []
73 requests = []
74
74
75 # 4-tuple of (command, final future, @batchable generator, remote
75 # 4-tuple of (command, final future, @batchable generator, remote
76 # future).
76 # future).
77 results = []
77 results = []
78
78
79 for command, args, opts, finalfuture in self.calls:
79 for command, args, opts, finalfuture in self.calls:
80 mtd = getattr(self._remote, command)
80 mtd = getattr(self._remote, command)
81 batchable = mtd.batchable(mtd.__self__, *args, **opts)
81 batchable = mtd.batchable(mtd.__self__, *args, **opts)
82
82
83 commandargs, fremote = next(batchable)
83 commandargs, fremote = next(batchable)
84 assert fremote
84 assert fremote
85 requests.append((command, commandargs))
85 requests.append((command, commandargs))
86 results.append((command, finalfuture, batchable, fremote))
86 results.append((command, finalfuture, batchable, fremote))
87
87
88 if requests:
88 if requests:
89 self._resultiter = self._remote._submitbatch(requests)
89 self._resultiter = self._remote._submitbatch(requests)
90
90
91 self._results = results
91 self._results = results
92
92
93 def results(self):
93 def results(self):
94 for command, finalfuture, batchable, remotefuture in self._results:
94 for command, finalfuture, batchable, remotefuture in self._results:
95 # Get the raw result, set it in the remote future, feed it
95 # Get the raw result, set it in the remote future, feed it
96 # back into the @batchable generator so it can be decoded, and
96 # back into the @batchable generator so it can be decoded, and
97 # set the result on the final future to this value.
97 # set the result on the final future to this value.
98 remoteresult = next(self._resultiter)
98 remoteresult = next(self._resultiter)
99 remotefuture.set(remoteresult)
99 remotefuture.set(remoteresult)
100 finalfuture.set(next(batchable))
100 finalfuture.set(next(batchable))
101
101
102 # Verify our @batchable generators only emit 2 values.
102 # Verify our @batchable generators only emit 2 values.
103 try:
103 try:
104 next(batchable)
104 next(batchable)
105 except StopIteration:
105 except StopIteration:
106 pass
106 pass
107 else:
107 else:
108 raise error.ProgrammingError('%s @batchable generator emitted '
108 raise error.ProgrammingError('%s @batchable generator emitted '
109 'unexpected value count' % command)
109 'unexpected value count' % command)
110
110
111 yield finalfuture.value
111 yield finalfuture.value
112
112
113 # Forward a couple of names from peer to make wireproto interactions
113 # Forward a couple of names from peer to make wireproto interactions
114 # slightly more sensible.
114 # slightly more sensible.
115 batchable = peer.batchable
115 batchable = peer.batchable
116 future = peer.future
116 future = peer.future
117
117
118 # list of nodes encoding / decoding
118 # list of nodes encoding / decoding
119
119
120 def decodelist(l, sep=' '):
120 def decodelist(l, sep=' '):
121 if l:
121 if l:
122 return [bin(v) for v in l.split(sep)]
122 return [bin(v) for v in l.split(sep)]
123 return []
123 return []
124
124
125 def encodelist(l, sep=' '):
125 def encodelist(l, sep=' '):
126 try:
126 try:
127 return sep.join(map(hex, l))
127 return sep.join(map(hex, l))
128 except TypeError:
128 except TypeError:
129 raise
129 raise
130
130
131 # batched call argument encoding
131 # batched call argument encoding
132
132
133 def escapearg(plain):
133 def escapearg(plain):
134 return (plain
134 return (plain
135 .replace(':', ':c')
135 .replace(':', ':c')
136 .replace(',', ':o')
136 .replace(',', ':o')
137 .replace(';', ':s')
137 .replace(';', ':s')
138 .replace('=', ':e'))
138 .replace('=', ':e'))
139
139
140 def unescapearg(escaped):
140 def unescapearg(escaped):
141 return (escaped
141 return (escaped
142 .replace(':e', '=')
142 .replace(':e', '=')
143 .replace(':s', ';')
143 .replace(':s', ';')
144 .replace(':o', ',')
144 .replace(':o', ',')
145 .replace(':c', ':'))
145 .replace(':c', ':'))
146
146
147 def encodebatchcmds(req):
147 def encodebatchcmds(req):
148 """Return a ``cmds`` argument value for the ``batch`` command."""
148 """Return a ``cmds`` argument value for the ``batch`` command."""
149 cmds = []
149 cmds = []
150 for op, argsdict in req:
150 for op, argsdict in req:
151 # Old servers didn't properly unescape argument names. So prevent
151 # Old servers didn't properly unescape argument names. So prevent
152 # the sending of argument names that may not be decoded properly by
152 # the sending of argument names that may not be decoded properly by
153 # servers.
153 # servers.
154 assert all(escapearg(k) == k for k in argsdict)
154 assert all(escapearg(k) == k for k in argsdict)
155
155
156 args = ','.join('%s=%s' % (escapearg(k), escapearg(v))
156 args = ','.join('%s=%s' % (escapearg(k), escapearg(v))
157 for k, v in argsdict.iteritems())
157 for k, v in argsdict.iteritems())
158 cmds.append('%s %s' % (op, args))
158 cmds.append('%s %s' % (op, args))
159
159
160 return ';'.join(cmds)
160 return ';'.join(cmds)
161
161
162 def clientcompressionsupport(proto):
162 def clientcompressionsupport(proto):
163 """Returns a list of compression methods supported by the client.
163 """Returns a list of compression methods supported by the client.
164
164
165 Returns a list of the compression methods supported by the client
165 Returns a list of the compression methods supported by the client
166 according to the protocol capabilities. If no such capability has
166 according to the protocol capabilities. If no such capability has
167 been announced, fallback to the default of zlib and uncompressed.
167 been announced, fallback to the default of zlib and uncompressed.
168 """
168 """
169 for cap in proto.getprotocaps():
169 for cap in proto.getprotocaps():
170 if cap.startswith('comp='):
170 if cap.startswith('comp='):
171 return cap[5:].split(',')
171 return cap[5:].split(',')
172 return ['zlib', 'none']
172 return ['zlib', 'none']
173
173
174 # mapping of options accepted by getbundle and their types
174 # mapping of options accepted by getbundle and their types
175 #
175 #
176 # Meant to be extended by extensions. It is extensions responsibility to ensure
176 # Meant to be extended by extensions. It is extensions responsibility to ensure
177 # such options are properly processed in exchange.getbundle.
177 # such options are properly processed in exchange.getbundle.
178 #
178 #
179 # supported types are:
179 # supported types are:
180 #
180 #
181 # :nodes: list of binary nodes
181 # :nodes: list of binary nodes
182 # :csv: list of comma-separated values
182 # :csv: list of comma-separated values
183 # :scsv: list of comma-separated values return as set
183 # :scsv: list of comma-separated values return as set
184 # :plain: string with no transformation needed.
184 # :plain: string with no transformation needed.
185 gboptsmap = {'heads': 'nodes',
185 gboptsmap = {'heads': 'nodes',
186 'bookmarks': 'boolean',
186 'bookmarks': 'boolean',
187 'common': 'nodes',
187 'common': 'nodes',
188 'obsmarkers': 'boolean',
188 'obsmarkers': 'boolean',
189 'phases': 'boolean',
189 'phases': 'boolean',
190 'bundlecaps': 'scsv',
190 'bundlecaps': 'scsv',
191 'listkeys': 'csv',
191 'listkeys': 'csv',
192 'cg': 'boolean',
192 'cg': 'boolean',
193 'cbattempted': 'boolean',
193 'cbattempted': 'boolean',
194 'stream': 'boolean',
194 'stream': 'boolean',
195 }
195 }
196
196
197 # client side
197 # client side
198
198
199 class wirepeer(repository.legacypeer):
199 class wirepeer(repository.legacypeer):
200 """Client-side interface for communicating with a peer repository.
200 """Client-side interface for communicating with a peer repository.
201
201
202 Methods commonly call wire protocol commands of the same name.
202 Methods commonly call wire protocol commands of the same name.
203
203
204 See also httppeer.py and sshpeer.py for protocol-specific
204 See also httppeer.py and sshpeer.py for protocol-specific
205 implementations of this interface.
205 implementations of this interface.
206 """
206 """
207 # Begin of ipeercommands interface.
207 # Begin of ipeercommands interface.
208
208
209 def iterbatch(self):
209 def iterbatch(self):
210 return remoteiterbatcher(self)
210 return remoteiterbatcher(self)
211
211
212 @batchable
212 @batchable
213 def lookup(self, key):
213 def lookup(self, key):
214 self.requirecap('lookup', _('look up remote revision'))
214 self.requirecap('lookup', _('look up remote revision'))
215 f = future()
215 f = future()
216 yield {'key': encoding.fromlocal(key)}, f
216 yield {'key': encoding.fromlocal(key)}, f
217 d = f.value
217 d = f.value
218 success, data = d[:-1].split(" ", 1)
218 success, data = d[:-1].split(" ", 1)
219 if int(success):
219 if int(success):
220 yield bin(data)
220 yield bin(data)
221 else:
221 else:
222 self._abort(error.RepoError(data))
222 self._abort(error.RepoError(data))
223
223
224 @batchable
224 @batchable
225 def heads(self):
225 def heads(self):
226 f = future()
226 f = future()
227 yield {}, f
227 yield {}, f
228 d = f.value
228 d = f.value
229 try:
229 try:
230 yield decodelist(d[:-1])
230 yield decodelist(d[:-1])
231 except ValueError:
231 except ValueError:
232 self._abort(error.ResponseError(_("unexpected response:"), d))
232 self._abort(error.ResponseError(_("unexpected response:"), d))
233
233
234 @batchable
234 @batchable
235 def known(self, nodes):
235 def known(self, nodes):
236 f = future()
236 f = future()
237 yield {'nodes': encodelist(nodes)}, f
237 yield {'nodes': encodelist(nodes)}, f
238 d = f.value
238 d = f.value
239 try:
239 try:
240 yield [bool(int(b)) for b in d]
240 yield [bool(int(b)) for b in d]
241 except ValueError:
241 except ValueError:
242 self._abort(error.ResponseError(_("unexpected response:"), d))
242 self._abort(error.ResponseError(_("unexpected response:"), d))
243
243
244 @batchable
244 @batchable
245 def branchmap(self):
245 def branchmap(self):
246 f = future()
246 f = future()
247 yield {}, f
247 yield {}, f
248 d = f.value
248 d = f.value
249 try:
249 try:
250 branchmap = {}
250 branchmap = {}
251 for branchpart in d.splitlines():
251 for branchpart in d.splitlines():
252 branchname, branchheads = branchpart.split(' ', 1)
252 branchname, branchheads = branchpart.split(' ', 1)
253 branchname = encoding.tolocal(urlreq.unquote(branchname))
253 branchname = encoding.tolocal(urlreq.unquote(branchname))
254 branchheads = decodelist(branchheads)
254 branchheads = decodelist(branchheads)
255 branchmap[branchname] = branchheads
255 branchmap[branchname] = branchheads
256 yield branchmap
256 yield branchmap
257 except TypeError:
257 except TypeError:
258 self._abort(error.ResponseError(_("unexpected response:"), d))
258 self._abort(error.ResponseError(_("unexpected response:"), d))
259
259
260 @batchable
260 @batchable
261 def listkeys(self, namespace):
261 def listkeys(self, namespace):
262 if not self.capable('pushkey'):
262 if not self.capable('pushkey'):
263 yield {}, None
263 yield {}, None
264 f = future()
264 f = future()
265 self.ui.debug('preparing listkeys for "%s"\n' % namespace)
265 self.ui.debug('preparing listkeys for "%s"\n' % namespace)
266 yield {'namespace': encoding.fromlocal(namespace)}, f
266 yield {'namespace': encoding.fromlocal(namespace)}, f
267 d = f.value
267 d = f.value
268 self.ui.debug('received listkey for "%s": %i bytes\n'
268 self.ui.debug('received listkey for "%s": %i bytes\n'
269 % (namespace, len(d)))
269 % (namespace, len(d)))
270 yield pushkeymod.decodekeys(d)
270 yield pushkeymod.decodekeys(d)
271
271
272 @batchable
272 @batchable
273 def pushkey(self, namespace, key, old, new):
273 def pushkey(self, namespace, key, old, new):
274 if not self.capable('pushkey'):
274 if not self.capable('pushkey'):
275 yield False, None
275 yield False, None
276 f = future()
276 f = future()
277 self.ui.debug('preparing pushkey for "%s:%s"\n' % (namespace, key))
277 self.ui.debug('preparing pushkey for "%s:%s"\n' % (namespace, key))
278 yield {'namespace': encoding.fromlocal(namespace),
278 yield {'namespace': encoding.fromlocal(namespace),
279 'key': encoding.fromlocal(key),
279 'key': encoding.fromlocal(key),
280 'old': encoding.fromlocal(old),
280 'old': encoding.fromlocal(old),
281 'new': encoding.fromlocal(new)}, f
281 'new': encoding.fromlocal(new)}, f
282 d = f.value
282 d = f.value
283 d, output = d.split('\n', 1)
283 d, output = d.split('\n', 1)
284 try:
284 try:
285 d = bool(int(d))
285 d = bool(int(d))
286 except ValueError:
286 except ValueError:
287 raise error.ResponseError(
287 raise error.ResponseError(
288 _('push failed (unexpected response):'), d)
288 _('push failed (unexpected response):'), d)
289 for l in output.splitlines(True):
289 for l in output.splitlines(True):
290 self.ui.status(_('remote: '), l)
290 self.ui.status(_('remote: '), l)
291 yield d
291 yield d
292
292
293 def stream_out(self):
293 def stream_out(self):
294 return self._callstream('stream_out')
294 return self._callstream('stream_out')
295
295
296 def getbundle(self, source, **kwargs):
296 def getbundle(self, source, **kwargs):
297 kwargs = pycompat.byteskwargs(kwargs)
297 kwargs = pycompat.byteskwargs(kwargs)
298 self.requirecap('getbundle', _('look up remote changes'))
298 self.requirecap('getbundle', _('look up remote changes'))
299 opts = {}
299 opts = {}
300 bundlecaps = kwargs.get('bundlecaps') or set()
300 bundlecaps = kwargs.get('bundlecaps') or set()
301 for key, value in kwargs.iteritems():
301 for key, value in kwargs.iteritems():
302 if value is None:
302 if value is None:
303 continue
303 continue
304 keytype = gboptsmap.get(key)
304 keytype = gboptsmap.get(key)
305 if keytype is None:
305 if keytype is None:
306 raise error.ProgrammingError(
306 raise error.ProgrammingError(
307 'Unexpectedly None keytype for key %s' % key)
307 'Unexpectedly None keytype for key %s' % key)
308 elif keytype == 'nodes':
308 elif keytype == 'nodes':
309 value = encodelist(value)
309 value = encodelist(value)
310 elif keytype == 'csv':
310 elif keytype == 'csv':
311 value = ','.join(value)
311 value = ','.join(value)
312 elif keytype == 'scsv':
312 elif keytype == 'scsv':
313 value = ','.join(sorted(value))
313 value = ','.join(sorted(value))
314 elif keytype == 'boolean':
314 elif keytype == 'boolean':
315 value = '%i' % bool(value)
315 value = '%i' % bool(value)
316 elif keytype != 'plain':
316 elif keytype != 'plain':
317 raise KeyError('unknown getbundle option type %s'
317 raise KeyError('unknown getbundle option type %s'
318 % keytype)
318 % keytype)
319 opts[key] = value
319 opts[key] = value
320 f = self._callcompressable("getbundle", **pycompat.strkwargs(opts))
320 f = self._callcompressable("getbundle", **pycompat.strkwargs(opts))
321 if any((cap.startswith('HG2') for cap in bundlecaps)):
321 if any((cap.startswith('HG2') for cap in bundlecaps)):
322 return bundle2.getunbundler(self.ui, f)
322 return bundle2.getunbundler(self.ui, f)
323 else:
323 else:
324 return changegroupmod.cg1unpacker(f, 'UN')
324 return changegroupmod.cg1unpacker(f, 'UN')
325
325
326 def unbundle(self, cg, heads, url):
326 def unbundle(self, cg, heads, url):
327 '''Send cg (a readable file-like object representing the
327 '''Send cg (a readable file-like object representing the
328 changegroup to push, typically a chunkbuffer object) to the
328 changegroup to push, typically a chunkbuffer object) to the
329 remote server as a bundle.
329 remote server as a bundle.
330
330
331 When pushing a bundle10 stream, return an integer indicating the
331 When pushing a bundle10 stream, return an integer indicating the
332 result of the push (see changegroup.apply()).
332 result of the push (see changegroup.apply()).
333
333
334 When pushing a bundle20 stream, return a bundle20 stream.
334 When pushing a bundle20 stream, return a bundle20 stream.
335
335
336 `url` is the url the client thinks it's pushing to, which is
336 `url` is the url the client thinks it's pushing to, which is
337 visible to hooks.
337 visible to hooks.
338 '''
338 '''
339
339
340 if heads != ['force'] and self.capable('unbundlehash'):
340 if heads != ['force'] and self.capable('unbundlehash'):
341 heads = encodelist(['hashed',
341 heads = encodelist(['hashed',
342 hashlib.sha1(''.join(sorted(heads))).digest()])
342 hashlib.sha1(''.join(sorted(heads))).digest()])
343 else:
343 else:
344 heads = encodelist(heads)
344 heads = encodelist(heads)
345
345
346 if util.safehasattr(cg, 'deltaheader'):
346 if util.safehasattr(cg, 'deltaheader'):
347 # this a bundle10, do the old style call sequence
347 # this a bundle10, do the old style call sequence
348 ret, output = self._callpush("unbundle", cg, heads=heads)
348 ret, output = self._callpush("unbundle", cg, heads=heads)
349 if ret == "":
349 if ret == "":
350 raise error.ResponseError(
350 raise error.ResponseError(
351 _('push failed:'), output)
351 _('push failed:'), output)
352 try:
352 try:
353 ret = int(ret)
353 ret = int(ret)
354 except ValueError:
354 except ValueError:
355 raise error.ResponseError(
355 raise error.ResponseError(
356 _('push failed (unexpected response):'), ret)
356 _('push failed (unexpected response):'), ret)
357
357
358 for l in output.splitlines(True):
358 for l in output.splitlines(True):
359 self.ui.status(_('remote: '), l)
359 self.ui.status(_('remote: '), l)
360 else:
360 else:
361 # bundle2 push. Send a stream, fetch a stream.
361 # bundle2 push. Send a stream, fetch a stream.
362 stream = self._calltwowaystream('unbundle', cg, heads=heads)
362 stream = self._calltwowaystream('unbundle', cg, heads=heads)
363 ret = bundle2.getunbundler(self.ui, stream)
363 ret = bundle2.getunbundler(self.ui, stream)
364 return ret
364 return ret
365
365
366 # End of ipeercommands interface.
366 # End of ipeercommands interface.
367
367
368 # Begin of ipeerlegacycommands interface.
368 # Begin of ipeerlegacycommands interface.
369
369
370 def branches(self, nodes):
370 def branches(self, nodes):
371 n = encodelist(nodes)
371 n = encodelist(nodes)
372 d = self._call("branches", nodes=n)
372 d = self._call("branches", nodes=n)
373 try:
373 try:
374 br = [tuple(decodelist(b)) for b in d.splitlines()]
374 br = [tuple(decodelist(b)) for b in d.splitlines()]
375 return br
375 return br
376 except ValueError:
376 except ValueError:
377 self._abort(error.ResponseError(_("unexpected response:"), d))
377 self._abort(error.ResponseError(_("unexpected response:"), d))
378
378
379 def between(self, pairs):
379 def between(self, pairs):
380 batch = 8 # avoid giant requests
380 batch = 8 # avoid giant requests
381 r = []
381 r = []
382 for i in xrange(0, len(pairs), batch):
382 for i in xrange(0, len(pairs), batch):
383 n = " ".join([encodelist(p, '-') for p in pairs[i:i + batch]])
383 n = " ".join([encodelist(p, '-') for p in pairs[i:i + batch]])
384 d = self._call("between", pairs=n)
384 d = self._call("between", pairs=n)
385 try:
385 try:
386 r.extend(l and decodelist(l) or [] for l in d.splitlines())
386 r.extend(l and decodelist(l) or [] for l in d.splitlines())
387 except ValueError:
387 except ValueError:
388 self._abort(error.ResponseError(_("unexpected response:"), d))
388 self._abort(error.ResponseError(_("unexpected response:"), d))
389 return r
389 return r
390
390
391 def changegroup(self, nodes, kind):
391 def changegroup(self, nodes, kind):
392 n = encodelist(nodes)
392 n = encodelist(nodes)
393 f = self._callcompressable("changegroup", roots=n)
393 f = self._callcompressable("changegroup", roots=n)
394 return changegroupmod.cg1unpacker(f, 'UN')
394 return changegroupmod.cg1unpacker(f, 'UN')
395
395
396 def changegroupsubset(self, bases, heads, kind):
396 def changegroupsubset(self, bases, heads, kind):
397 self.requirecap('changegroupsubset', _('look up remote changes'))
397 self.requirecap('changegroupsubset', _('look up remote changes'))
398 bases = encodelist(bases)
398 bases = encodelist(bases)
399 heads = encodelist(heads)
399 heads = encodelist(heads)
400 f = self._callcompressable("changegroupsubset",
400 f = self._callcompressable("changegroupsubset",
401 bases=bases, heads=heads)
401 bases=bases, heads=heads)
402 return changegroupmod.cg1unpacker(f, 'UN')
402 return changegroupmod.cg1unpacker(f, 'UN')
403
403
404 # End of ipeerlegacycommands interface.
404 # End of ipeerlegacycommands interface.
405
405
406 def _submitbatch(self, req):
406 def _submitbatch(self, req):
407 """run batch request <req> on the server
407 """run batch request <req> on the server
408
408
409 Returns an iterator of the raw responses from the server.
409 Returns an iterator of the raw responses from the server.
410 """
410 """
411 ui = self.ui
411 ui = self.ui
412 if ui.debugflag and ui.configbool('devel', 'debug.peer-request'):
412 if ui.debugflag and ui.configbool('devel', 'debug.peer-request'):
413 ui.debug('devel-peer-request: batched-content\n')
413 ui.debug('devel-peer-request: batched-content\n')
414 for op, args in req:
414 for op, args in req:
415 msg = 'devel-peer-request: - %s (%d arguments)\n'
415 msg = 'devel-peer-request: - %s (%d arguments)\n'
416 ui.debug(msg % (op, len(args)))
416 ui.debug(msg % (op, len(args)))
417
417
418 rsp = self._callstream("batch", cmds=encodebatchcmds(req))
418 rsp = self._callstream("batch", cmds=encodebatchcmds(req))
419 chunk = rsp.read(1024)
419 chunk = rsp.read(1024)
420 work = [chunk]
420 work = [chunk]
421 while chunk:
421 while chunk:
422 while ';' not in chunk and chunk:
422 while ';' not in chunk and chunk:
423 chunk = rsp.read(1024)
423 chunk = rsp.read(1024)
424 work.append(chunk)
424 work.append(chunk)
425 merged = ''.join(work)
425 merged = ''.join(work)
426 while ';' in merged:
426 while ';' in merged:
427 one, merged = merged.split(';', 1)
427 one, merged = merged.split(';', 1)
428 yield unescapearg(one)
428 yield unescapearg(one)
429 chunk = rsp.read(1024)
429 chunk = rsp.read(1024)
430 work = [merged, chunk]
430 work = [merged, chunk]
431 yield unescapearg(''.join(work))
431 yield unescapearg(''.join(work))
432
432
433 def _submitone(self, op, args):
433 def _submitone(self, op, args):
434 return self._call(op, **pycompat.strkwargs(args))
434 return self._call(op, **pycompat.strkwargs(args))
435
435
436 def debugwireargs(self, one, two, three=None, four=None, five=None):
436 def debugwireargs(self, one, two, three=None, four=None, five=None):
437 # don't pass optional arguments left at their default value
437 # don't pass optional arguments left at their default value
438 opts = {}
438 opts = {}
439 if three is not None:
439 if three is not None:
440 opts[r'three'] = three
440 opts[r'three'] = three
441 if four is not None:
441 if four is not None:
442 opts[r'four'] = four
442 opts[r'four'] = four
443 return self._call('debugwireargs', one=one, two=two, **opts)
443 return self._call('debugwireargs', one=one, two=two, **opts)
444
444
445 def _call(self, cmd, **args):
445 def _call(self, cmd, **args):
446 """execute <cmd> on the server
446 """execute <cmd> on the server
447
447
448 The command is expected to return a simple string.
448 The command is expected to return a simple string.
449
449
450 returns the server reply as a string."""
450 returns the server reply as a string."""
451 raise NotImplementedError()
451 raise NotImplementedError()
452
452
453 def _callstream(self, cmd, **args):
453 def _callstream(self, cmd, **args):
454 """execute <cmd> on the server
454 """execute <cmd> on the server
455
455
456 The command is expected to return a stream. Note that if the
456 The command is expected to return a stream. Note that if the
457 command doesn't return a stream, _callstream behaves
457 command doesn't return a stream, _callstream behaves
458 differently for ssh and http peers.
458 differently for ssh and http peers.
459
459
460 returns the server reply as a file like object.
460 returns the server reply as a file like object.
461 """
461 """
462 raise NotImplementedError()
462 raise NotImplementedError()
463
463
464 def _callcompressable(self, cmd, **args):
464 def _callcompressable(self, cmd, **args):
465 """execute <cmd> on the server
465 """execute <cmd> on the server
466
466
467 The command is expected to return a stream.
467 The command is expected to return a stream.
468
468
469 The stream may have been compressed in some implementations. This
469 The stream may have been compressed in some implementations. This
470 function takes care of the decompression. This is the only difference
470 function takes care of the decompression. This is the only difference
471 with _callstream.
471 with _callstream.
472
472
473 returns the server reply as a file like object.
473 returns the server reply as a file like object.
474 """
474 """
475 raise NotImplementedError()
475 raise NotImplementedError()
476
476
477 def _callpush(self, cmd, fp, **args):
477 def _callpush(self, cmd, fp, **args):
478 """execute a <cmd> on server
478 """execute a <cmd> on server
479
479
480 The command is expected to be related to a push. Push has a special
480 The command is expected to be related to a push. Push has a special
481 return method.
481 return method.
482
482
483 returns the server reply as a (ret, output) tuple. ret is either
483 returns the server reply as a (ret, output) tuple. ret is either
484 empty (error) or a stringified int.
484 empty (error) or a stringified int.
485 """
485 """
486 raise NotImplementedError()
486 raise NotImplementedError()
487
487
488 def _calltwowaystream(self, cmd, fp, **args):
488 def _calltwowaystream(self, cmd, fp, **args):
489 """execute <cmd> on server
489 """execute <cmd> on server
490
490
491 The command will send a stream to the server and get a stream in reply.
491 The command will send a stream to the server and get a stream in reply.
492 """
492 """
493 raise NotImplementedError()
493 raise NotImplementedError()
494
494
495 def _abort(self, exception):
495 def _abort(self, exception):
496 """clearly abort the wire protocol connection and raise the exception
496 """clearly abort the wire protocol connection and raise the exception
497 """
497 """
498 raise NotImplementedError()
498 raise NotImplementedError()
499
499
500 # server side
500 # server side
501
501
502 # wire protocol command can either return a string or one of these classes.
502 # wire protocol command can either return a string or one of these classes.
503
503
504 def getdispatchrepo(repo, proto, command):
504 def getdispatchrepo(repo, proto, command):
505 """Obtain the repo used for processing wire protocol commands.
505 """Obtain the repo used for processing wire protocol commands.
506
506
507 The intent of this function is to serve as a monkeypatch point for
507 The intent of this function is to serve as a monkeypatch point for
508 extensions that need commands to operate on different repo views under
508 extensions that need commands to operate on different repo views under
509 specialized circumstances.
509 specialized circumstances.
510 """
510 """
511 return repo.filtered('served')
511 return repo.filtered('served')
512
512
513 def dispatch(repo, proto, command):
513 def dispatch(repo, proto, command):
514 repo = getdispatchrepo(repo, proto, command)
514 repo = getdispatchrepo(repo, proto, command)
515
515
516 transportversion = wireprototypes.TRANSPORTS[proto.name]['version']
516 transportversion = wireprototypes.TRANSPORTS[proto.name]['version']
517 commandtable = commandsv2 if transportversion == 2 else commands
517 commandtable = commandsv2 if transportversion == 2 else commands
518 func, spec = commandtable[command]
518 func, spec = commandtable[command]
519
519
520 args = proto.getargs(spec)
520 args = proto.getargs(spec)
521
521
522 # Version 1 protocols define arguments as a list. Version 2 uses a dict.
522 # Version 1 protocols define arguments as a list. Version 2 uses a dict.
523 if isinstance(args, list):
523 if isinstance(args, list):
524 return func(repo, proto, *args)
524 return func(repo, proto, *args)
525 elif isinstance(args, dict):
525 elif isinstance(args, dict):
526 return func(repo, proto, **args)
526 return func(repo, proto, **args)
527 else:
527 else:
528 raise error.ProgrammingError('unexpected type returned from '
528 raise error.ProgrammingError('unexpected type returned from '
529 'proto.getargs(): %s' % type(args))
529 'proto.getargs(): %s' % type(args))
530
530
531 def options(cmd, keys, others):
531 def options(cmd, keys, others):
532 opts = {}
532 opts = {}
533 for k in keys:
533 for k in keys:
534 if k in others:
534 if k in others:
535 opts[k] = others[k]
535 opts[k] = others[k]
536 del others[k]
536 del others[k]
537 if others:
537 if others:
538 procutil.stderr.write("warning: %s ignored unexpected arguments %s\n"
538 procutil.stderr.write("warning: %s ignored unexpected arguments %s\n"
539 % (cmd, ",".join(others)))
539 % (cmd, ",".join(others)))
540 return opts
540 return opts
541
541
542 def bundle1allowed(repo, action):
542 def bundle1allowed(repo, action):
543 """Whether a bundle1 operation is allowed from the server.
543 """Whether a bundle1 operation is allowed from the server.
544
544
545 Priority is:
545 Priority is:
546
546
547 1. server.bundle1gd.<action> (if generaldelta active)
547 1. server.bundle1gd.<action> (if generaldelta active)
548 2. server.bundle1.<action>
548 2. server.bundle1.<action>
549 3. server.bundle1gd (if generaldelta active)
549 3. server.bundle1gd (if generaldelta active)
550 4. server.bundle1
550 4. server.bundle1
551 """
551 """
552 ui = repo.ui
552 ui = repo.ui
553 gd = 'generaldelta' in repo.requirements
553 gd = 'generaldelta' in repo.requirements
554
554
555 if gd:
555 if gd:
556 v = ui.configbool('server', 'bundle1gd.%s' % action)
556 v = ui.configbool('server', 'bundle1gd.%s' % action)
557 if v is not None:
557 if v is not None:
558 return v
558 return v
559
559
560 v = ui.configbool('server', 'bundle1.%s' % action)
560 v = ui.configbool('server', 'bundle1.%s' % action)
561 if v is not None:
561 if v is not None:
562 return v
562 return v
563
563
564 if gd:
564 if gd:
565 v = ui.configbool('server', 'bundle1gd')
565 v = ui.configbool('server', 'bundle1gd')
566 if v is not None:
566 if v is not None:
567 return v
567 return v
568
568
569 return ui.configbool('server', 'bundle1')
569 return ui.configbool('server', 'bundle1')
570
570
571 def supportedcompengines(ui, role):
571 def supportedcompengines(ui, role):
572 """Obtain the list of supported compression engines for a request."""
572 """Obtain the list of supported compression engines for a request."""
573 assert role in (util.CLIENTROLE, util.SERVERROLE)
573 assert role in (util.CLIENTROLE, util.SERVERROLE)
574
574
575 compengines = util.compengines.supportedwireengines(role)
575 compengines = util.compengines.supportedwireengines(role)
576
576
577 # Allow config to override default list and ordering.
577 # Allow config to override default list and ordering.
578 if role == util.SERVERROLE:
578 if role == util.SERVERROLE:
579 configengines = ui.configlist('server', 'compressionengines')
579 configengines = ui.configlist('server', 'compressionengines')
580 config = 'server.compressionengines'
580 config = 'server.compressionengines'
581 else:
581 else:
582 # This is currently implemented mainly to facilitate testing. In most
582 # This is currently implemented mainly to facilitate testing. In most
583 # cases, the server should be in charge of choosing a compression engine
583 # cases, the server should be in charge of choosing a compression engine
584 # because a server has the most to lose from a sub-optimal choice. (e.g.
584 # because a server has the most to lose from a sub-optimal choice. (e.g.
585 # CPU DoS due to an expensive engine or a network DoS due to poor
585 # CPU DoS due to an expensive engine or a network DoS due to poor
586 # compression ratio).
586 # compression ratio).
587 configengines = ui.configlist('experimental',
587 configengines = ui.configlist('experimental',
588 'clientcompressionengines')
588 'clientcompressionengines')
589 config = 'experimental.clientcompressionengines'
589 config = 'experimental.clientcompressionengines'
590
590
591 # No explicit config. Filter out the ones that aren't supposed to be
591 # No explicit config. Filter out the ones that aren't supposed to be
592 # advertised and return default ordering.
592 # advertised and return default ordering.
593 if not configengines:
593 if not configengines:
594 attr = 'serverpriority' if role == util.SERVERROLE else 'clientpriority'
594 attr = 'serverpriority' if role == util.SERVERROLE else 'clientpriority'
595 return [e for e in compengines
595 return [e for e in compengines
596 if getattr(e.wireprotosupport(), attr) > 0]
596 if getattr(e.wireprotosupport(), attr) > 0]
597
597
598 # If compression engines are listed in the config, assume there is a good
598 # If compression engines are listed in the config, assume there is a good
599 # reason for it (like server operators wanting to achieve specific
599 # reason for it (like server operators wanting to achieve specific
600 # performance characteristics). So fail fast if the config references
600 # performance characteristics). So fail fast if the config references
601 # unusable compression engines.
601 # unusable compression engines.
602 validnames = set(e.name() for e in compengines)
602 validnames = set(e.name() for e in compengines)
603 invalidnames = set(e for e in configengines if e not in validnames)
603 invalidnames = set(e for e in configengines if e not in validnames)
604 if invalidnames:
604 if invalidnames:
605 raise error.Abort(_('invalid compression engine defined in %s: %s') %
605 raise error.Abort(_('invalid compression engine defined in %s: %s') %
606 (config, ', '.join(sorted(invalidnames))))
606 (config, ', '.join(sorted(invalidnames))))
607
607
608 compengines = [e for e in compengines if e.name() in configengines]
608 compengines = [e for e in compengines if e.name() in configengines]
609 compengines = sorted(compengines,
609 compengines = sorted(compengines,
610 key=lambda e: configengines.index(e.name()))
610 key=lambda e: configengines.index(e.name()))
611
611
612 if not compengines:
612 if not compengines:
613 raise error.Abort(_('%s config option does not specify any known '
613 raise error.Abort(_('%s config option does not specify any known '
614 'compression engines') % config,
614 'compression engines') % config,
615 hint=_('usable compression engines: %s') %
615 hint=_('usable compression engines: %s') %
616 ', '.sorted(validnames))
616 ', '.sorted(validnames))
617
617
618 return compengines
618 return compengines
619
619
620 class commandentry(object):
620 class commandentry(object):
621 """Represents a declared wire protocol command."""
621 """Represents a declared wire protocol command."""
622 def __init__(self, func, args='', transports=None,
622 def __init__(self, func, args='', transports=None,
623 permission='push'):
623 permission='push'):
624 self.func = func
624 self.func = func
625 self.args = args
625 self.args = args
626 self.transports = transports or set()
626 self.transports = transports or set()
627 self.permission = permission
627 self.permission = permission
628
628
629 def _merge(self, func, args):
629 def _merge(self, func, args):
630 """Merge this instance with an incoming 2-tuple.
630 """Merge this instance with an incoming 2-tuple.
631
631
632 This is called when a caller using the old 2-tuple API attempts
632 This is called when a caller using the old 2-tuple API attempts
633 to replace an instance. The incoming values are merged with
633 to replace an instance. The incoming values are merged with
634 data not captured by the 2-tuple and a new instance containing
634 data not captured by the 2-tuple and a new instance containing
635 the union of the two objects is returned.
635 the union of the two objects is returned.
636 """
636 """
637 return commandentry(func, args=args, transports=set(self.transports),
637 return commandentry(func, args=args, transports=set(self.transports),
638 permission=self.permission)
638 permission=self.permission)
639
639
640 # Old code treats instances as 2-tuples. So expose that interface.
640 # Old code treats instances as 2-tuples. So expose that interface.
641 def __iter__(self):
641 def __iter__(self):
642 yield self.func
642 yield self.func
643 yield self.args
643 yield self.args
644
644
645 def __getitem__(self, i):
645 def __getitem__(self, i):
646 if i == 0:
646 if i == 0:
647 return self.func
647 return self.func
648 elif i == 1:
648 elif i == 1:
649 return self.args
649 return self.args
650 else:
650 else:
651 raise IndexError('can only access elements 0 and 1')
651 raise IndexError('can only access elements 0 and 1')
652
652
653 class commanddict(dict):
653 class commanddict(dict):
654 """Container for registered wire protocol commands.
654 """Container for registered wire protocol commands.
655
655
656 It behaves like a dict. But __setitem__ is overwritten to allow silent
656 It behaves like a dict. But __setitem__ is overwritten to allow silent
657 coercion of values from 2-tuples for API compatibility.
657 coercion of values from 2-tuples for API compatibility.
658 """
658 """
659 def __setitem__(self, k, v):
659 def __setitem__(self, k, v):
660 if isinstance(v, commandentry):
660 if isinstance(v, commandentry):
661 pass
661 pass
662 # Cast 2-tuples to commandentry instances.
662 # Cast 2-tuples to commandentry instances.
663 elif isinstance(v, tuple):
663 elif isinstance(v, tuple):
664 if len(v) != 2:
664 if len(v) != 2:
665 raise ValueError('command tuples must have exactly 2 elements')
665 raise ValueError('command tuples must have exactly 2 elements')
666
666
667 # It is common for extensions to wrap wire protocol commands via
667 # It is common for extensions to wrap wire protocol commands via
668 # e.g. ``wireproto.commands[x] = (newfn, args)``. Because callers
668 # e.g. ``wireproto.commands[x] = (newfn, args)``. Because callers
669 # doing this aren't aware of the new API that uses objects to store
669 # doing this aren't aware of the new API that uses objects to store
670 # command entries, we automatically merge old state with new.
670 # command entries, we automatically merge old state with new.
671 if k in self:
671 if k in self:
672 v = self[k]._merge(v[0], v[1])
672 v = self[k]._merge(v[0], v[1])
673 else:
673 else:
674 # Use default values from @wireprotocommand.
674 # Use default values from @wireprotocommand.
675 v = commandentry(v[0], args=v[1],
675 v = commandentry(v[0], args=v[1],
676 transports=set(wireprototypes.TRANSPORTS),
676 transports=set(wireprototypes.TRANSPORTS),
677 permission='push')
677 permission='push')
678 else:
678 else:
679 raise ValueError('command entries must be commandentry instances '
679 raise ValueError('command entries must be commandentry instances '
680 'or 2-tuples')
680 'or 2-tuples')
681
681
682 return super(commanddict, self).__setitem__(k, v)
682 return super(commanddict, self).__setitem__(k, v)
683
683
684 def commandavailable(self, command, proto):
684 def commandavailable(self, command, proto):
685 """Determine if a command is available for the requested protocol."""
685 """Determine if a command is available for the requested protocol."""
686 assert proto.name in wireprototypes.TRANSPORTS
686 assert proto.name in wireprototypes.TRANSPORTS
687
687
688 entry = self.get(command)
688 entry = self.get(command)
689
689
690 if not entry:
690 if not entry:
691 return False
691 return False
692
692
693 if proto.name not in entry.transports:
693 if proto.name not in entry.transports:
694 return False
694 return False
695
695
696 return True
696 return True
697
697
698 # Constants specifying which transports a wire protocol command should be
698 # Constants specifying which transports a wire protocol command should be
699 # available on. For use with @wireprotocommand.
699 # available on. For use with @wireprotocommand.
700 POLICY_ALL = 'all'
700 POLICY_ALL = 'all'
701 POLICY_V1_ONLY = 'v1-only'
701 POLICY_V1_ONLY = 'v1-only'
702 POLICY_V2_ONLY = 'v2-only'
702 POLICY_V2_ONLY = 'v2-only'
703
703
704 # For version 1 transports.
704 # For version 1 transports.
705 commands = commanddict()
705 commands = commanddict()
706
706
707 # For version 2 transports.
707 # For version 2 transports.
708 commandsv2 = commanddict()
708 commandsv2 = commanddict()
709
709
710 def wireprotocommand(name, args='', transportpolicy=POLICY_ALL,
710 def wireprotocommand(name, args='', transportpolicy=POLICY_ALL,
711 permission='push'):
711 permission='push'):
712 """Decorator to declare a wire protocol command.
712 """Decorator to declare a wire protocol command.
713
713
714 ``name`` is the name of the wire protocol command being provided.
714 ``name`` is the name of the wire protocol command being provided.
715
715
716 ``args`` is a space-delimited list of named arguments that the command
716 ``args`` is a space-delimited list of named arguments that the command
717 accepts. ``*`` is a special value that says to accept all arguments.
717 accepts. ``*`` is a special value that says to accept all arguments.
718
718
719 ``transportpolicy`` is a POLICY_* constant denoting which transports
719 ``transportpolicy`` is a POLICY_* constant denoting which transports
720 this wire protocol command should be exposed to. By default, commands
720 this wire protocol command should be exposed to. By default, commands
721 are exposed to all wire protocol transports.
721 are exposed to all wire protocol transports.
722
722
723 ``permission`` defines the permission type needed to run this command.
723 ``permission`` defines the permission type needed to run this command.
724 Can be ``push`` or ``pull``. These roughly map to read-write and read-only,
724 Can be ``push`` or ``pull``. These roughly map to read-write and read-only,
725 respectively. Default is to assume command requires ``push`` permissions
725 respectively. Default is to assume command requires ``push`` permissions
726 because otherwise commands not declaring their permissions could modify
726 because otherwise commands not declaring their permissions could modify
727 a repository that is supposed to be read-only.
727 a repository that is supposed to be read-only.
728 """
728 """
729 if transportpolicy == POLICY_ALL:
729 if transportpolicy == POLICY_ALL:
730 transports = set(wireprototypes.TRANSPORTS)
730 transports = set(wireprototypes.TRANSPORTS)
731 transportversions = {1, 2}
731 transportversions = {1, 2}
732 elif transportpolicy == POLICY_V1_ONLY:
732 elif transportpolicy == POLICY_V1_ONLY:
733 transports = {k for k, v in wireprototypes.TRANSPORTS.items()
733 transports = {k for k, v in wireprototypes.TRANSPORTS.items()
734 if v['version'] == 1}
734 if v['version'] == 1}
735 transportversions = {1}
735 transportversions = {1}
736 elif transportpolicy == POLICY_V2_ONLY:
736 elif transportpolicy == POLICY_V2_ONLY:
737 transports = {k for k, v in wireprototypes.TRANSPORTS.items()
737 transports = {k for k, v in wireprototypes.TRANSPORTS.items()
738 if v['version'] == 2}
738 if v['version'] == 2}
739 transportversions = {2}
739 transportversions = {2}
740 else:
740 else:
741 raise error.ProgrammingError('invalid transport policy value: %s' %
741 raise error.ProgrammingError('invalid transport policy value: %s' %
742 transportpolicy)
742 transportpolicy)
743
743
744 # Because SSHv2 is a mirror of SSHv1, we allow "batch" commands through to
744 # Because SSHv2 is a mirror of SSHv1, we allow "batch" commands through to
745 # SSHv2.
745 # SSHv2.
746 # TODO undo this hack when SSH is using the unified frame protocol.
746 # TODO undo this hack when SSH is using the unified frame protocol.
747 if name == b'batch':
747 if name == b'batch':
748 transports.add(wireprototypes.SSHV2)
748 transports.add(wireprototypes.SSHV2)
749
749
750 if permission not in ('push', 'pull'):
750 if permission not in ('push', 'pull'):
751 raise error.ProgrammingError('invalid wire protocol permission; '
751 raise error.ProgrammingError('invalid wire protocol permission; '
752 'got %s; expected "push" or "pull"' %
752 'got %s; expected "push" or "pull"' %
753 permission)
753 permission)
754
754
755 def register(func):
755 def register(func):
756 if 1 in transportversions:
756 if 1 in transportversions:
757 if name in commands:
757 if name in commands:
758 raise error.ProgrammingError('%s command already registered '
758 raise error.ProgrammingError('%s command already registered '
759 'for version 1' % name)
759 'for version 1' % name)
760 commands[name] = commandentry(func, args=args,
760 commands[name] = commandentry(func, args=args,
761 transports=transports,
761 transports=transports,
762 permission=permission)
762 permission=permission)
763 if 2 in transportversions:
763 if 2 in transportversions:
764 if name in commandsv2:
764 if name in commandsv2:
765 raise error.ProgrammingError('%s command already registered '
765 raise error.ProgrammingError('%s command already registered '
766 'for version 2' % name)
766 'for version 2' % name)
767 commandsv2[name] = commandentry(func, args=args,
767 commandsv2[name] = commandentry(func, args=args,
768 transports=transports,
768 transports=transports,
769 permission=permission)
769 permission=permission)
770
770
771 return func
771 return func
772 return register
772 return register
773
773
774 # TODO define a more appropriate permissions type to use for this.
774 # TODO define a more appropriate permissions type to use for this.
775 @wireprotocommand('batch', 'cmds *', permission='pull',
775 @wireprotocommand('batch', 'cmds *', permission='pull',
776 transportpolicy=POLICY_V1_ONLY)
776 transportpolicy=POLICY_V1_ONLY)
777 def batch(repo, proto, cmds, others):
777 def batch(repo, proto, cmds, others):
778 repo = repo.filtered("served")
778 repo = repo.filtered("served")
779 res = []
779 res = []
780 for pair in cmds.split(';'):
780 for pair in cmds.split(';'):
781 op, args = pair.split(' ', 1)
781 op, args = pair.split(' ', 1)
782 vals = {}
782 vals = {}
783 for a in args.split(','):
783 for a in args.split(','):
784 if a:
784 if a:
785 n, v = a.split('=')
785 n, v = a.split('=')
786 vals[unescapearg(n)] = unescapearg(v)
786 vals[unescapearg(n)] = unescapearg(v)
787 func, spec = commands[op]
787 func, spec = commands[op]
788
788
789 # Validate that client has permissions to perform this command.
789 # Validate that client has permissions to perform this command.
790 perm = commands[op].permission
790 perm = commands[op].permission
791 assert perm in ('push', 'pull')
791 assert perm in ('push', 'pull')
792 proto.checkperm(perm)
792 proto.checkperm(perm)
793
793
794 if spec:
794 if spec:
795 keys = spec.split()
795 keys = spec.split()
796 data = {}
796 data = {}
797 for k in keys:
797 for k in keys:
798 if k == '*':
798 if k == '*':
799 star = {}
799 star = {}
800 for key in vals.keys():
800 for key in vals.keys():
801 if key not in keys:
801 if key not in keys:
802 star[key] = vals[key]
802 star[key] = vals[key]
803 data['*'] = star
803 data['*'] = star
804 else:
804 else:
805 data[k] = vals[k]
805 data[k] = vals[k]
806 result = func(repo, proto, *[data[k] for k in keys])
806 result = func(repo, proto, *[data[k] for k in keys])
807 else:
807 else:
808 result = func(repo, proto)
808 result = func(repo, proto)
809 if isinstance(result, wireprototypes.ooberror):
809 if isinstance(result, wireprototypes.ooberror):
810 return result
810 return result
811
811
812 # For now, all batchable commands must return bytesresponse or
812 # For now, all batchable commands must return bytesresponse or
813 # raw bytes (for backwards compatibility).
813 # raw bytes (for backwards compatibility).
814 assert isinstance(result, (wireprototypes.bytesresponse, bytes))
814 assert isinstance(result, (wireprototypes.bytesresponse, bytes))
815 if isinstance(result, wireprototypes.bytesresponse):
815 if isinstance(result, wireprototypes.bytesresponse):
816 result = result.data
816 result = result.data
817 res.append(escapearg(result))
817 res.append(escapearg(result))
818
818
819 return wireprototypes.bytesresponse(';'.join(res))
819 return wireprototypes.bytesresponse(';'.join(res))
820
820
821 @wireprotocommand('between', 'pairs', transportpolicy=POLICY_V1_ONLY,
821 @wireprotocommand('between', 'pairs', transportpolicy=POLICY_V1_ONLY,
822 permission='pull')
822 permission='pull')
823 def between(repo, proto, pairs):
823 def between(repo, proto, pairs):
824 pairs = [decodelist(p, '-') for p in pairs.split(" ")]
824 pairs = [decodelist(p, '-') for p in pairs.split(" ")]
825 r = []
825 r = []
826 for b in repo.between(pairs):
826 for b in repo.between(pairs):
827 r.append(encodelist(b) + "\n")
827 r.append(encodelist(b) + "\n")
828
828
829 return wireprototypes.bytesresponse(''.join(r))
829 return wireprototypes.bytesresponse(''.join(r))
830
830
831 @wireprotocommand('branchmap', permission='pull')
831 @wireprotocommand('branchmap', permission='pull')
832 def branchmap(repo, proto):
832 def branchmap(repo, proto):
833 branchmap = repo.branchmap()
833 branchmap = repo.branchmap()
834 heads = []
834 heads = []
835 for branch, nodes in branchmap.iteritems():
835 for branch, nodes in branchmap.iteritems():
836 branchname = urlreq.quote(encoding.fromlocal(branch))
836 branchname = urlreq.quote(encoding.fromlocal(branch))
837 branchnodes = encodelist(nodes)
837 branchnodes = encodelist(nodes)
838 heads.append('%s %s' % (branchname, branchnodes))
838 heads.append('%s %s' % (branchname, branchnodes))
839
839
840 return wireprototypes.bytesresponse('\n'.join(heads))
840 return wireprototypes.bytesresponse('\n'.join(heads))
841
841
842 @wireprotocommand('branches', 'nodes', transportpolicy=POLICY_V1_ONLY,
842 @wireprotocommand('branches', 'nodes', transportpolicy=POLICY_V1_ONLY,
843 permission='pull')
843 permission='pull')
844 def branches(repo, proto, nodes):
844 def branches(repo, proto, nodes):
845 nodes = decodelist(nodes)
845 nodes = decodelist(nodes)
846 r = []
846 r = []
847 for b in repo.branches(nodes):
847 for b in repo.branches(nodes):
848 r.append(encodelist(b) + "\n")
848 r.append(encodelist(b) + "\n")
849
849
850 return wireprototypes.bytesresponse(''.join(r))
850 return wireprototypes.bytesresponse(''.join(r))
851
851
852 @wireprotocommand('clonebundles', '', permission='pull')
852 @wireprotocommand('clonebundles', '', permission='pull')
853 def clonebundles(repo, proto):
853 def clonebundles(repo, proto):
854 """Server command for returning info for available bundles to seed clones.
854 """Server command for returning info for available bundles to seed clones.
855
855
856 Clients will parse this response and determine what bundle to fetch.
856 Clients will parse this response and determine what bundle to fetch.
857
857
858 Extensions may wrap this command to filter or dynamically emit data
858 Extensions may wrap this command to filter or dynamically emit data
859 depending on the request. e.g. you could advertise URLs for the closest
859 depending on the request. e.g. you could advertise URLs for the closest
860 data center given the client's IP address.
860 data center given the client's IP address.
861 """
861 """
862 return wireprototypes.bytesresponse(
862 return wireprototypes.bytesresponse(
863 repo.vfs.tryread('clonebundles.manifest'))
863 repo.vfs.tryread('clonebundles.manifest'))
864
864
865 wireprotocaps = ['lookup', 'branchmap', 'pushkey',
865 wireprotocaps = ['lookup', 'branchmap', 'pushkey',
866 'known', 'getbundle', 'unbundlehash']
866 'known', 'getbundle', 'unbundlehash']
867
867
868 def _capabilities(repo, proto):
868 def _capabilities(repo, proto):
869 """return a list of capabilities for a repo
869 """return a list of capabilities for a repo
870
870
871 This function exists to allow extensions to easily wrap capabilities
871 This function exists to allow extensions to easily wrap capabilities
872 computation
872 computation
873
873
874 - returns a lists: easy to alter
874 - returns a lists: easy to alter
875 - change done here will be propagated to both `capabilities` and `hello`
875 - change done here will be propagated to both `capabilities` and `hello`
876 command without any other action needed.
876 command without any other action needed.
877 """
877 """
878 # copy to prevent modification of the global list
878 # copy to prevent modification of the global list
879 caps = list(wireprotocaps)
879 caps = list(wireprotocaps)
880
880
881 # Command of same name as capability isn't exposed to version 1 of
881 # Command of same name as capability isn't exposed to version 1 of
882 # transports. So conditionally add it.
882 # transports. So conditionally add it.
883 if commands.commandavailable('changegroupsubset', proto):
883 if commands.commandavailable('changegroupsubset', proto):
884 caps.append('changegroupsubset')
884 caps.append('changegroupsubset')
885
885
886 if streamclone.allowservergeneration(repo):
886 if streamclone.allowservergeneration(repo):
887 if repo.ui.configbool('server', 'preferuncompressed'):
887 if repo.ui.configbool('server', 'preferuncompressed'):
888 caps.append('stream-preferred')
888 caps.append('stream-preferred')
889 requiredformats = repo.requirements & repo.supportedformats
889 requiredformats = repo.requirements & repo.supportedformats
890 # if our local revlogs are just revlogv1, add 'stream' cap
890 # if our local revlogs are just revlogv1, add 'stream' cap
891 if not requiredformats - {'revlogv1'}:
891 if not requiredformats - {'revlogv1'}:
892 caps.append('stream')
892 caps.append('stream')
893 # otherwise, add 'streamreqs' detailing our local revlog format
893 # otherwise, add 'streamreqs' detailing our local revlog format
894 else:
894 else:
895 caps.append('streamreqs=%s' % ','.join(sorted(requiredformats)))
895 caps.append('streamreqs=%s' % ','.join(sorted(requiredformats)))
896 if repo.ui.configbool('experimental', 'bundle2-advertise'):
896 if repo.ui.configbool('experimental', 'bundle2-advertise'):
897 capsblob = bundle2.encodecaps(bundle2.getrepocaps(repo, role='server'))
897 capsblob = bundle2.encodecaps(bundle2.getrepocaps(repo, role='server'))
898 caps.append('bundle2=' + urlreq.quote(capsblob))
898 caps.append('bundle2=' + urlreq.quote(capsblob))
899 caps.append('unbundle=%s' % ','.join(bundle2.bundlepriority))
899 caps.append('unbundle=%s' % ','.join(bundle2.bundlepriority))
900
900
901 return proto.addcapabilities(repo, caps)
901 return proto.addcapabilities(repo, caps)
902
902
903 # If you are writing an extension and consider wrapping this function. Wrap
903 # If you are writing an extension and consider wrapping this function. Wrap
904 # `_capabilities` instead.
904 # `_capabilities` instead.
905 @wireprotocommand('capabilities', permission='pull')
905 @wireprotocommand('capabilities', permission='pull')
906 def capabilities(repo, proto):
906 def capabilities(repo, proto):
907 caps = _capabilities(repo, proto)
907 caps = _capabilities(repo, proto)
908 return wireprototypes.bytesresponse(' '.join(sorted(caps)))
908 return wireprototypes.bytesresponse(' '.join(sorted(caps)))
909
909
910 @wireprotocommand('changegroup', 'roots', transportpolicy=POLICY_V1_ONLY,
910 @wireprotocommand('changegroup', 'roots', transportpolicy=POLICY_V1_ONLY,
911 permission='pull')
911 permission='pull')
912 def changegroup(repo, proto, roots):
912 def changegroup(repo, proto, roots):
913 nodes = decodelist(roots)
913 nodes = decodelist(roots)
914 outgoing = discovery.outgoing(repo, missingroots=nodes,
914 outgoing = discovery.outgoing(repo, missingroots=nodes,
915 missingheads=repo.heads())
915 missingheads=repo.heads())
916 cg = changegroupmod.makechangegroup(repo, outgoing, '01', 'serve')
916 cg = changegroupmod.makechangegroup(repo, outgoing, '01', 'serve')
917 gen = iter(lambda: cg.read(32768), '')
917 gen = iter(lambda: cg.read(32768), '')
918 return wireprototypes.streamres(gen=gen)
918 return wireprototypes.streamres(gen=gen)
919
919
920 @wireprotocommand('changegroupsubset', 'bases heads',
920 @wireprotocommand('changegroupsubset', 'bases heads',
921 transportpolicy=POLICY_V1_ONLY,
921 transportpolicy=POLICY_V1_ONLY,
922 permission='pull')
922 permission='pull')
923 def changegroupsubset(repo, proto, bases, heads):
923 def changegroupsubset(repo, proto, bases, heads):
924 bases = decodelist(bases)
924 bases = decodelist(bases)
925 heads = decodelist(heads)
925 heads = decodelist(heads)
926 outgoing = discovery.outgoing(repo, missingroots=bases,
926 outgoing = discovery.outgoing(repo, missingroots=bases,
927 missingheads=heads)
927 missingheads=heads)
928 cg = changegroupmod.makechangegroup(repo, outgoing, '01', 'serve')
928 cg = changegroupmod.makechangegroup(repo, outgoing, '01', 'serve')
929 gen = iter(lambda: cg.read(32768), '')
929 gen = iter(lambda: cg.read(32768), '')
930 return wireprototypes.streamres(gen=gen)
930 return wireprototypes.streamres(gen=gen)
931
931
932 @wireprotocommand('debugwireargs', 'one two *',
932 @wireprotocommand('debugwireargs', 'one two *',
933 permission='pull')
933 permission='pull')
934 def debugwireargs(repo, proto, one, two, others):
934 def debugwireargs(repo, proto, one, two, others):
935 # only accept optional args from the known set
935 # only accept optional args from the known set
936 opts = options('debugwireargs', ['three', 'four'], others)
936 opts = options('debugwireargs', ['three', 'four'], others)
937 return wireprototypes.bytesresponse(repo.debugwireargs(
937 return wireprototypes.bytesresponse(repo.debugwireargs(
938 one, two, **pycompat.strkwargs(opts)))
938 one, two, **pycompat.strkwargs(opts)))
939
939
940 @wireprotocommand('getbundle', '*', permission='pull')
940 @wireprotocommand('getbundle', '*', permission='pull')
941 def getbundle(repo, proto, others):
941 def getbundle(repo, proto, others):
942 opts = options('getbundle', gboptsmap.keys(), others)
942 opts = options('getbundle', gboptsmap.keys(), others)
943 for k, v in opts.iteritems():
943 for k, v in opts.iteritems():
944 keytype = gboptsmap[k]
944 keytype = gboptsmap[k]
945 if keytype == 'nodes':
945 if keytype == 'nodes':
946 opts[k] = decodelist(v)
946 opts[k] = decodelist(v)
947 elif keytype == 'csv':
947 elif keytype == 'csv':
948 opts[k] = list(v.split(','))
948 opts[k] = list(v.split(','))
949 elif keytype == 'scsv':
949 elif keytype == 'scsv':
950 opts[k] = set(v.split(','))
950 opts[k] = set(v.split(','))
951 elif keytype == 'boolean':
951 elif keytype == 'boolean':
952 # Client should serialize False as '0', which is a non-empty string
952 # Client should serialize False as '0', which is a non-empty string
953 # so it evaluates as a True bool.
953 # so it evaluates as a True bool.
954 if v == '0':
954 if v == '0':
955 opts[k] = False
955 opts[k] = False
956 else:
956 else:
957 opts[k] = bool(v)
957 opts[k] = bool(v)
958 elif keytype != 'plain':
958 elif keytype != 'plain':
959 raise KeyError('unknown getbundle option type %s'
959 raise KeyError('unknown getbundle option type %s'
960 % keytype)
960 % keytype)
961
961
962 if not bundle1allowed(repo, 'pull'):
962 if not bundle1allowed(repo, 'pull'):
963 if not exchange.bundle2requested(opts.get('bundlecaps')):
963 if not exchange.bundle2requested(opts.get('bundlecaps')):
964 if proto.name == 'http-v1':
964 if proto.name == 'http-v1':
965 return wireprototypes.ooberror(bundle2required)
965 return wireprototypes.ooberror(bundle2required)
966 raise error.Abort(bundle2requiredmain,
966 raise error.Abort(bundle2requiredmain,
967 hint=bundle2requiredhint)
967 hint=bundle2requiredhint)
968
968
969 prefercompressed = True
969 prefercompressed = True
970
970
971 try:
971 try:
972 if repo.ui.configbool('server', 'disablefullbundle'):
972 if repo.ui.configbool('server', 'disablefullbundle'):
973 # Check to see if this is a full clone.
973 # Check to see if this is a full clone.
974 clheads = set(repo.changelog.heads())
974 clheads = set(repo.changelog.heads())
975 changegroup = opts.get('cg', True)
975 changegroup = opts.get('cg', True)
976 heads = set(opts.get('heads', set()))
976 heads = set(opts.get('heads', set()))
977 common = set(opts.get('common', set()))
977 common = set(opts.get('common', set()))
978 common.discard(nullid)
978 common.discard(nullid)
979 if changegroup and not common and clheads == heads:
979 if changegroup and not common and clheads == heads:
980 raise error.Abort(
980 raise error.Abort(
981 _('server has pull-based clones disabled'),
981 _('server has pull-based clones disabled'),
982 hint=_('remove --pull if specified or upgrade Mercurial'))
982 hint=_('remove --pull if specified or upgrade Mercurial'))
983
983
984 info, chunks = exchange.getbundlechunks(repo, 'serve',
984 info, chunks = exchange.getbundlechunks(repo, 'serve',
985 **pycompat.strkwargs(opts))
985 **pycompat.strkwargs(opts))
986 prefercompressed = info.get('prefercompressed', True)
986 prefercompressed = info.get('prefercompressed', True)
987 except error.Abort as exc:
987 except error.Abort as exc:
988 # cleanly forward Abort error to the client
988 # cleanly forward Abort error to the client
989 if not exchange.bundle2requested(opts.get('bundlecaps')):
989 if not exchange.bundle2requested(opts.get('bundlecaps')):
990 if proto.name == 'http-v1':
990 if proto.name == 'http-v1':
991 return wireprototypes.ooberror(pycompat.bytestr(exc) + '\n')
991 return wireprototypes.ooberror(pycompat.bytestr(exc) + '\n')
992 raise # cannot do better for bundle1 + ssh
992 raise # cannot do better for bundle1 + ssh
993 # bundle2 request expect a bundle2 reply
993 # bundle2 request expect a bundle2 reply
994 bundler = bundle2.bundle20(repo.ui)
994 bundler = bundle2.bundle20(repo.ui)
995 manargs = [('message', pycompat.bytestr(exc))]
995 manargs = [('message', pycompat.bytestr(exc))]
996 advargs = []
996 advargs = []
997 if exc.hint is not None:
997 if exc.hint is not None:
998 advargs.append(('hint', exc.hint))
998 advargs.append(('hint', exc.hint))
999 bundler.addpart(bundle2.bundlepart('error:abort',
999 bundler.addpart(bundle2.bundlepart('error:abort',
1000 manargs, advargs))
1000 manargs, advargs))
1001 chunks = bundler.getchunks()
1001 chunks = bundler.getchunks()
1002 prefercompressed = False
1002 prefercompressed = False
1003
1003
1004 return wireprototypes.streamres(
1004 return wireprototypes.streamres(
1005 gen=chunks, prefer_uncompressed=not prefercompressed)
1005 gen=chunks, prefer_uncompressed=not prefercompressed)
1006
1006
1007 @wireprotocommand('heads', permission='pull', transportpolicy=POLICY_V1_ONLY)
1007 @wireprotocommand('heads', permission='pull', transportpolicy=POLICY_V1_ONLY)
1008 def heads(repo, proto):
1008 def heads(repo, proto):
1009 h = repo.heads()
1009 h = repo.heads()
1010 return wireprototypes.bytesresponse(encodelist(h) + '\n')
1010 return wireprototypes.bytesresponse(encodelist(h) + '\n')
1011
1011
1012 @wireprotocommand('hello', permission='pull')
1012 @wireprotocommand('hello', permission='pull')
1013 def hello(repo, proto):
1013 def hello(repo, proto):
1014 """Called as part of SSH handshake to obtain server info.
1014 """Called as part of SSH handshake to obtain server info.
1015
1015
1016 Returns a list of lines describing interesting things about the
1016 Returns a list of lines describing interesting things about the
1017 server, in an RFC822-like format.
1017 server, in an RFC822-like format.
1018
1018
1019 Currently, the only one defined is ``capabilities``, which consists of a
1019 Currently, the only one defined is ``capabilities``, which consists of a
1020 line of space separated tokens describing server abilities:
1020 line of space separated tokens describing server abilities:
1021
1021
1022 capabilities: <token0> <token1> <token2>
1022 capabilities: <token0> <token1> <token2>
1023 """
1023 """
1024 caps = capabilities(repo, proto).data
1024 caps = capabilities(repo, proto).data
1025 return wireprototypes.bytesresponse('capabilities: %s\n' % caps)
1025 return wireprototypes.bytesresponse('capabilities: %s\n' % caps)
1026
1026
1027 @wireprotocommand('listkeys', 'namespace', permission='pull')
1027 @wireprotocommand('listkeys', 'namespace', permission='pull')
1028 def listkeys(repo, proto, namespace):
1028 def listkeys(repo, proto, namespace):
1029 d = sorted(repo.listkeys(encoding.tolocal(namespace)).items())
1029 d = sorted(repo.listkeys(encoding.tolocal(namespace)).items())
1030 return wireprototypes.bytesresponse(pushkeymod.encodekeys(d))
1030 return wireprototypes.bytesresponse(pushkeymod.encodekeys(d))
1031
1031
1032 @wireprotocommand('lookup', 'key', permission='pull')
1032 @wireprotocommand('lookup', 'key', permission='pull')
1033 def lookup(repo, proto, key):
1033 def lookup(repo, proto, key):
1034 try:
1034 try:
1035 k = encoding.tolocal(key)
1035 k = encoding.tolocal(key)
1036 n = repo.lookup(k)
1036 n = repo.lookup(k)
1037 r = hex(n)
1037 r = hex(n)
1038 success = 1
1038 success = 1
1039 except Exception as inst:
1039 except Exception as inst:
1040 r = stringutil.forcebytestr(inst)
1040 r = stringutil.forcebytestr(inst)
1041 success = 0
1041 success = 0
1042 return wireprototypes.bytesresponse('%d %s\n' % (success, r))
1042 return wireprototypes.bytesresponse('%d %s\n' % (success, r))
1043
1043
1044 @wireprotocommand('known', 'nodes *', permission='pull')
1044 @wireprotocommand('known', 'nodes *', permission='pull',
1045 transportpolicy=POLICY_V1_ONLY)
1045 def known(repo, proto, nodes, others):
1046 def known(repo, proto, nodes, others):
1046 v = ''.join(b and '1' or '0' for b in repo.known(decodelist(nodes)))
1047 v = ''.join(b and '1' or '0' for b in repo.known(decodelist(nodes)))
1047 return wireprototypes.bytesresponse(v)
1048 return wireprototypes.bytesresponse(v)
1048
1049
1049 @wireprotocommand('protocaps', 'caps', permission='pull',
1050 @wireprotocommand('protocaps', 'caps', permission='pull',
1050 transportpolicy=POLICY_V1_ONLY)
1051 transportpolicy=POLICY_V1_ONLY)
1051 def protocaps(repo, proto, caps):
1052 def protocaps(repo, proto, caps):
1052 if proto.name == wireprototypes.SSHV1:
1053 if proto.name == wireprototypes.SSHV1:
1053 proto._protocaps = set(caps.split(' '))
1054 proto._protocaps = set(caps.split(' '))
1054 return wireprototypes.bytesresponse('OK')
1055 return wireprototypes.bytesresponse('OK')
1055
1056
1056 @wireprotocommand('pushkey', 'namespace key old new', permission='push')
1057 @wireprotocommand('pushkey', 'namespace key old new', permission='push')
1057 def pushkey(repo, proto, namespace, key, old, new):
1058 def pushkey(repo, proto, namespace, key, old, new):
1058 # compatibility with pre-1.8 clients which were accidentally
1059 # compatibility with pre-1.8 clients which were accidentally
1059 # sending raw binary nodes rather than utf-8-encoded hex
1060 # sending raw binary nodes rather than utf-8-encoded hex
1060 if len(new) == 20 and stringutil.escapestr(new) != new:
1061 if len(new) == 20 and stringutil.escapestr(new) != new:
1061 # looks like it could be a binary node
1062 # looks like it could be a binary node
1062 try:
1063 try:
1063 new.decode('utf-8')
1064 new.decode('utf-8')
1064 new = encoding.tolocal(new) # but cleanly decodes as UTF-8
1065 new = encoding.tolocal(new) # but cleanly decodes as UTF-8
1065 except UnicodeDecodeError:
1066 except UnicodeDecodeError:
1066 pass # binary, leave unmodified
1067 pass # binary, leave unmodified
1067 else:
1068 else:
1068 new = encoding.tolocal(new) # normal path
1069 new = encoding.tolocal(new) # normal path
1069
1070
1070 with proto.mayberedirectstdio() as output:
1071 with proto.mayberedirectstdio() as output:
1071 r = repo.pushkey(encoding.tolocal(namespace), encoding.tolocal(key),
1072 r = repo.pushkey(encoding.tolocal(namespace), encoding.tolocal(key),
1072 encoding.tolocal(old), new) or False
1073 encoding.tolocal(old), new) or False
1073
1074
1074 output = output.getvalue() if output else ''
1075 output = output.getvalue() if output else ''
1075 return wireprototypes.bytesresponse('%d\n%s' % (int(r), output))
1076 return wireprototypes.bytesresponse('%d\n%s' % (int(r), output))
1076
1077
1077 @wireprotocommand('stream_out', permission='pull')
1078 @wireprotocommand('stream_out', permission='pull')
1078 def stream(repo, proto):
1079 def stream(repo, proto):
1079 '''If the server supports streaming clone, it advertises the "stream"
1080 '''If the server supports streaming clone, it advertises the "stream"
1080 capability with a value representing the version and flags of the repo
1081 capability with a value representing the version and flags of the repo
1081 it is serving. Client checks to see if it understands the format.
1082 it is serving. Client checks to see if it understands the format.
1082 '''
1083 '''
1083 return wireprototypes.streamreslegacy(
1084 return wireprototypes.streamreslegacy(
1084 streamclone.generatev1wireproto(repo))
1085 streamclone.generatev1wireproto(repo))
1085
1086
1086 @wireprotocommand('unbundle', 'heads', permission='push')
1087 @wireprotocommand('unbundle', 'heads', permission='push')
1087 def unbundle(repo, proto, heads):
1088 def unbundle(repo, proto, heads):
1088 their_heads = decodelist(heads)
1089 their_heads = decodelist(heads)
1089
1090
1090 with proto.mayberedirectstdio() as output:
1091 with proto.mayberedirectstdio() as output:
1091 try:
1092 try:
1092 exchange.check_heads(repo, their_heads, 'preparing changes')
1093 exchange.check_heads(repo, their_heads, 'preparing changes')
1093 cleanup = lambda: None
1094 cleanup = lambda: None
1094 try:
1095 try:
1095 payload = proto.getpayload()
1096 payload = proto.getpayload()
1096 if repo.ui.configbool('server', 'streamunbundle'):
1097 if repo.ui.configbool('server', 'streamunbundle'):
1097 def cleanup():
1098 def cleanup():
1098 # Ensure that the full payload is consumed, so
1099 # Ensure that the full payload is consumed, so
1099 # that the connection doesn't contain trailing garbage.
1100 # that the connection doesn't contain trailing garbage.
1100 for p in payload:
1101 for p in payload:
1101 pass
1102 pass
1102 fp = util.chunkbuffer(payload)
1103 fp = util.chunkbuffer(payload)
1103 else:
1104 else:
1104 # write bundle data to temporary file as it can be big
1105 # write bundle data to temporary file as it can be big
1105 fp, tempname = None, None
1106 fp, tempname = None, None
1106 def cleanup():
1107 def cleanup():
1107 if fp:
1108 if fp:
1108 fp.close()
1109 fp.close()
1109 if tempname:
1110 if tempname:
1110 os.unlink(tempname)
1111 os.unlink(tempname)
1111 fd, tempname = tempfile.mkstemp(prefix='hg-unbundle-')
1112 fd, tempname = tempfile.mkstemp(prefix='hg-unbundle-')
1112 repo.ui.debug('redirecting incoming bundle to %s\n' %
1113 repo.ui.debug('redirecting incoming bundle to %s\n' %
1113 tempname)
1114 tempname)
1114 fp = os.fdopen(fd, pycompat.sysstr('wb+'))
1115 fp = os.fdopen(fd, pycompat.sysstr('wb+'))
1115 r = 0
1116 r = 0
1116 for p in payload:
1117 for p in payload:
1117 fp.write(p)
1118 fp.write(p)
1118 fp.seek(0)
1119 fp.seek(0)
1119
1120
1120 gen = exchange.readbundle(repo.ui, fp, None)
1121 gen = exchange.readbundle(repo.ui, fp, None)
1121 if (isinstance(gen, changegroupmod.cg1unpacker)
1122 if (isinstance(gen, changegroupmod.cg1unpacker)
1122 and not bundle1allowed(repo, 'push')):
1123 and not bundle1allowed(repo, 'push')):
1123 if proto.name == 'http-v1':
1124 if proto.name == 'http-v1':
1124 # need to special case http because stderr do not get to
1125 # need to special case http because stderr do not get to
1125 # the http client on failed push so we need to abuse
1126 # the http client on failed push so we need to abuse
1126 # some other error type to make sure the message get to
1127 # some other error type to make sure the message get to
1127 # the user.
1128 # the user.
1128 return wireprototypes.ooberror(bundle2required)
1129 return wireprototypes.ooberror(bundle2required)
1129 raise error.Abort(bundle2requiredmain,
1130 raise error.Abort(bundle2requiredmain,
1130 hint=bundle2requiredhint)
1131 hint=bundle2requiredhint)
1131
1132
1132 r = exchange.unbundle(repo, gen, their_heads, 'serve',
1133 r = exchange.unbundle(repo, gen, their_heads, 'serve',
1133 proto.client())
1134 proto.client())
1134 if util.safehasattr(r, 'addpart'):
1135 if util.safehasattr(r, 'addpart'):
1135 # The return looks streamable, we are in the bundle2 case
1136 # The return looks streamable, we are in the bundle2 case
1136 # and should return a stream.
1137 # and should return a stream.
1137 return wireprototypes.streamreslegacy(gen=r.getchunks())
1138 return wireprototypes.streamreslegacy(gen=r.getchunks())
1138 return wireprototypes.pushres(
1139 return wireprototypes.pushres(
1139 r, output.getvalue() if output else '')
1140 r, output.getvalue() if output else '')
1140
1141
1141 finally:
1142 finally:
1142 cleanup()
1143 cleanup()
1143
1144
1144 except (error.BundleValueError, error.Abort, error.PushRaced) as exc:
1145 except (error.BundleValueError, error.Abort, error.PushRaced) as exc:
1145 # handle non-bundle2 case first
1146 # handle non-bundle2 case first
1146 if not getattr(exc, 'duringunbundle2', False):
1147 if not getattr(exc, 'duringunbundle2', False):
1147 try:
1148 try:
1148 raise
1149 raise
1149 except error.Abort:
1150 except error.Abort:
1150 # The old code we moved used procutil.stderr directly.
1151 # The old code we moved used procutil.stderr directly.
1151 # We did not change it to minimise code change.
1152 # We did not change it to minimise code change.
1152 # This need to be moved to something proper.
1153 # This need to be moved to something proper.
1153 # Feel free to do it.
1154 # Feel free to do it.
1154 procutil.stderr.write("abort: %s\n" % exc)
1155 procutil.stderr.write("abort: %s\n" % exc)
1155 if exc.hint is not None:
1156 if exc.hint is not None:
1156 procutil.stderr.write("(%s)\n" % exc.hint)
1157 procutil.stderr.write("(%s)\n" % exc.hint)
1157 procutil.stderr.flush()
1158 procutil.stderr.flush()
1158 return wireprototypes.pushres(
1159 return wireprototypes.pushres(
1159 0, output.getvalue() if output else '')
1160 0, output.getvalue() if output else '')
1160 except error.PushRaced:
1161 except error.PushRaced:
1161 return wireprototypes.pusherr(
1162 return wireprototypes.pusherr(
1162 pycompat.bytestr(exc),
1163 pycompat.bytestr(exc),
1163 output.getvalue() if output else '')
1164 output.getvalue() if output else '')
1164
1165
1165 bundler = bundle2.bundle20(repo.ui)
1166 bundler = bundle2.bundle20(repo.ui)
1166 for out in getattr(exc, '_bundle2salvagedoutput', ()):
1167 for out in getattr(exc, '_bundle2salvagedoutput', ()):
1167 bundler.addpart(out)
1168 bundler.addpart(out)
1168 try:
1169 try:
1169 try:
1170 try:
1170 raise
1171 raise
1171 except error.PushkeyFailed as exc:
1172 except error.PushkeyFailed as exc:
1172 # check client caps
1173 # check client caps
1173 remotecaps = getattr(exc, '_replycaps', None)
1174 remotecaps = getattr(exc, '_replycaps', None)
1174 if (remotecaps is not None
1175 if (remotecaps is not None
1175 and 'pushkey' not in remotecaps.get('error', ())):
1176 and 'pushkey' not in remotecaps.get('error', ())):
1176 # no support remote side, fallback to Abort handler.
1177 # no support remote side, fallback to Abort handler.
1177 raise
1178 raise
1178 part = bundler.newpart('error:pushkey')
1179 part = bundler.newpart('error:pushkey')
1179 part.addparam('in-reply-to', exc.partid)
1180 part.addparam('in-reply-to', exc.partid)
1180 if exc.namespace is not None:
1181 if exc.namespace is not None:
1181 part.addparam('namespace', exc.namespace,
1182 part.addparam('namespace', exc.namespace,
1182 mandatory=False)
1183 mandatory=False)
1183 if exc.key is not None:
1184 if exc.key is not None:
1184 part.addparam('key', exc.key, mandatory=False)
1185 part.addparam('key', exc.key, mandatory=False)
1185 if exc.new is not None:
1186 if exc.new is not None:
1186 part.addparam('new', exc.new, mandatory=False)
1187 part.addparam('new', exc.new, mandatory=False)
1187 if exc.old is not None:
1188 if exc.old is not None:
1188 part.addparam('old', exc.old, mandatory=False)
1189 part.addparam('old', exc.old, mandatory=False)
1189 if exc.ret is not None:
1190 if exc.ret is not None:
1190 part.addparam('ret', exc.ret, mandatory=False)
1191 part.addparam('ret', exc.ret, mandatory=False)
1191 except error.BundleValueError as exc:
1192 except error.BundleValueError as exc:
1192 errpart = bundler.newpart('error:unsupportedcontent')
1193 errpart = bundler.newpart('error:unsupportedcontent')
1193 if exc.parttype is not None:
1194 if exc.parttype is not None:
1194 errpart.addparam('parttype', exc.parttype)
1195 errpart.addparam('parttype', exc.parttype)
1195 if exc.params:
1196 if exc.params:
1196 errpart.addparam('params', '\0'.join(exc.params))
1197 errpart.addparam('params', '\0'.join(exc.params))
1197 except error.Abort as exc:
1198 except error.Abort as exc:
1198 manargs = [('message', stringutil.forcebytestr(exc))]
1199 manargs = [('message', stringutil.forcebytestr(exc))]
1199 advargs = []
1200 advargs = []
1200 if exc.hint is not None:
1201 if exc.hint is not None:
1201 advargs.append(('hint', exc.hint))
1202 advargs.append(('hint', exc.hint))
1202 bundler.addpart(bundle2.bundlepart('error:abort',
1203 bundler.addpart(bundle2.bundlepart('error:abort',
1203 manargs, advargs))
1204 manargs, advargs))
1204 except error.PushRaced as exc:
1205 except error.PushRaced as exc:
1205 bundler.newpart('error:pushraced',
1206 bundler.newpart('error:pushraced',
1206 [('message', stringutil.forcebytestr(exc))])
1207 [('message', stringutil.forcebytestr(exc))])
1207 return wireprototypes.streamreslegacy(gen=bundler.getchunks())
1208 return wireprototypes.streamreslegacy(gen=bundler.getchunks())
1208
1209
1209 # Wire protocol version 2 commands only past this point.
1210 # Wire protocol version 2 commands only past this point.
1210
1211
1211 @wireprotocommand('heads', args='publiconly', permission='pull',
1212 @wireprotocommand('heads', args='publiconly', permission='pull',
1212 transportpolicy=POLICY_V2_ONLY)
1213 transportpolicy=POLICY_V2_ONLY)
1213 def headsv2(repo, proto, publiconly=False):
1214 def headsv2(repo, proto, publiconly=False):
1214 if publiconly:
1215 if publiconly:
1215 repo = repo.filtered('immutable')
1216 repo = repo.filtered('immutable')
1216
1217
1217 return wireprototypes.cborresponse(repo.heads())
1218 return wireprototypes.cborresponse(repo.heads())
1219
1220 @wireprotocommand('known', 'nodes', permission='pull',
1221 transportpolicy=POLICY_V2_ONLY)
1222 def knownv2(repo, proto, nodes=None):
1223 nodes = nodes or []
1224 result = b''.join(b'1' if n else b'0' for n in repo.known(nodes))
1225 return wireprototypes.cborresponse(result)
General Comments 0
You need to be logged in to leave comments. Login now