196
197
same for a given request method. Only new request methods introduced in
197
198
Bazaar 0.91 and later use streamed bodies.
205
For some discussion of the requirements that led to this new protocol
206
version, see `bug #83935`_.
208
.. _bug #83935: https://bugs.launchpad.net/bzr/+bug/83935
210
Version three has bencoding of most protocol structures, to make parsing
211
simpler. For extra parsing convenience, these structures are length
214
LENGTH_PREFIX := 32-bit unsigned integer in network byte order
216
Unlike earlier versions, clients and servers are no longer required to
217
know which request verbs and responses will have bodies attached. Because
218
of length-prefixing and other changes, it is always possible to know when
219
a complete request or response has been read, even if the server
222
The underlying message format is::
224
MESSAGE := "bzr message 3" NEWLINE HEADERS MESSAGE_PARTS
225
HEADERS := LENGTH_PREFIX bencoded_dict
226
MESSAGE_PARTS := MESSAGE_PART [MORE_MESSAGE_PARTS]
227
MORE_MESSAGE_PARTS := END_MESSAGE_PARTS | MESSAGE_PARTS
228
END_MESSAGE_PARTS := "e"
230
MESSAGE_PART := ONE_BYTE | STRUCTURE | BYTES
232
STRUCTURE := "s" LENGTH_PREFIX bencoded_structure
233
BYTES := "b" LENGTH_PREFIX bytes
235
This format allows an arbitrary sequence of message parts to be encoded
241
Each request and response will have “headers”, a dictionary of key-value pairs.
242
The keys must be strings, not any other type of value.
244
Currently, the only defined header is “Software version”. Both the client and
245
the server should include a “Software version” header, with a value of a
246
free-form string such as “bzrlib 1.5”, to aid debugging and logging. Clients
247
and servers **should not** vary behaviour based on this string.
249
Conventional requests and responses
250
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
252
By convention, most requests and responses have a simple “arguments plus
253
optional body” structure, as in earlier protocol versions. This section
254
describes how such messages are encoded. All requests and responses
255
defined by earlier protocol versions must be encoded in this way.
257
Conventional requests will send a sequence of:
259
* Arguments (a STRUCTURE of a tuple)
263
* Single body (BYTES), or
265
* Streamed body (multiple BYTES parts), followed by a status (ONE_BYTE)
267
* if status is "E", followed by an Error (STRUCTURE)
269
Conventional responses will send a sequence of:
273
* Arguments (a STRUCTURE of a tuple)
277
* Single body (BYTES), or
279
* Streamed body (multiple BYTES parts), followed by a status (ONE_BYTE)
281
* if status is "E", followed by an Error (STRUCTURE)
283
In all cases, the ONE_BYTE status is either "S" for Success or "E" for
284
Error. Note that the streamed body from version two is now just multiple
287
For new methods, these sequences are just a convention and may be varied
288
if appropriate for a particular request or response. However, each
289
request should at least start with a STRUCTURE encoding the arguments
290
tuple. The first element of that tuple must be a string that names the
291
request method. (Note that arguments in this protocol version are
292
bencoded. As a result, unlike previous protocol versions, arguments in
293
this version are 8-bit clean.)
295
For errors (where the Status byte of a response or a streamed body is
296
"E"), the situation is analagous to requests. The first item in the
297
encoded sequence must be a string of the error name. The other arguments
298
supply details about the error, and their number and types will depend on
299
the type of error (as identified by the error name).
added
removed
doc/developers/network-protocol.txt
