← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/network-protocol.txt

  • Committer: Andrew Bennetts
  • Date: 2008-02-20 06:14:29 UTC
  • mto: This revision was merged to the branch mainline in revision 3398.
  • Revision ID: andrew.bennetts@canonical.com-20080220061429-sc6xla297wy2dnio
Update the protocol spec for Robert and Martin's latest comments.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/network-protocol.txt
213
213
 
214
214
  LENGTH_PREFIX := 32-bit unsigned integer in network byte order
215
215
 
216
 
The request and response protocol is::
217
 
 
218
 
  REQUEST_V3 := "bzr request 3" NEWLINE HEADERS ARGS_V3 BODY_V3
219
 
  RESPONSE_V3 := "bzr response 3" NEWLINE HEADERS RESPONSE_STATUS 
220
 
                 ARGS_V3 BODY_V3
221
 
  RESPONSE_STATUS_V3 := SUCCESS_STATUS | ERROR_STATUS
222
 
  SUCCESS_STATUS := "S"
223
 
  ERROR_STATUS := "E"
224
 
  HEADERS := LENGTH_PREFIX bencoded_dictionary
 
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
 
220
implements no verbs.
 
221
 
 
222
The underlying message format is::
 
223
 
 
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"
 
229
  MESSAGE_PART := ONE_BYTE | STRUCTURE | BYTES | CHUNKED_BYTES
 
230
  ONE_BYTE := "o" byte
 
231
  STRUCTURE := "s" LENGTH_PREFIX bencoded_structure
 
232
  BYTES := "b" LENGTH_PREFIX bytes
 
233
  CHUNKED_BYTES := "c" CHUNKS_V3
 
234
  CHUNKS_V3 := CHUNK_V3 | CHUNKS_TERMINATOR
 
235
  CHUNK_V3 := "c" LENGTH_PREFIX bytes CHUNK_V3
 
236
  CHUNKS_TERMINATOR := "t"
 
237
 
 
238
This format allows an arbitrary sequence of message parts to be encoded
 
239
in a single message.
 
240
 
 
241
Headers
 
242
~~~~~~~
225
243
 
226
244
Each request and response will have “headers”, a dictionary of key-value pairs.
227
245
The keys must be strings, not any other type of value.
231
249
free-form string such as “bzrlib 1.3”, to aid debugging and logging.  Clients
232
250
and servers **should not** vary behaviour based on this string.
233
251
 
234
 
The argument encoding is::
235
 
 
236
 
  ARGS_V3 := LENGTH_PREFIX bencoded_sequence
237
 
 
238
 
Arguments in this protocol version are bencoded, and the entire argument
239
 
structure is length-prefixed.  As a result, unlike previous protocol versions,
240
 
arguments in this version are 8-bit clean.
241
 
 
242
 
For requests, the first item in the encoded sequence must be a string of
243
 
the request's verb, e.g. ``Branch.last_revision_info``.  Thus requests must
244
 
always have at least one item in their ARGS_V3 sequence.
245
 
 
246
 
For error responses (where the RESPONSE_STATUS_V3 is ERROR_STATUS), the
247
 
situation is analagous to requests.  The first item in the encoded sequence must
248
 
be a string of the error name.  The other arguments supply details about the
 
252
Conventional requests/responses
 
253
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
254
 
 
255
Most requests will send a sequence of:
 
256
 
 
257
 * Arguments (a STRUCTURE of a tuple)
 
258
 * Optional body
 
259
   * a BYTES, or 
 
260
   * CHUNKED_BYTES followed by a ONE_BYTE status
 
261
 
 
262
Most responses will send a sequence of:
 
263
 
 
264
 * Status
 
265
 * Arguments (a STRUCTURE of a tuple)
 
266
 * Optional body
 
267
   * a BYTES, or 
 
268
   * CHUNKED_BYTES followed by a ONE_BYTE status
 
269
 
 
270
In all cases, the ONE_BYTE status is either "S" for Success or "E" for
 
271
Error.  These message part sequences reflect the message structures
 
272
allowed by earlier protocol versions, and this is how older smart methods
 
273
that pre-date this protocol version will be encoded in this version.
 
274
 
 
275
For new methods, these sequences are just a convention and may be varied
 
276
if appropriate for a particular request or response.  However, each
 
277
request should at least start with an STRUCTURE encoding the arguments
 
278
tuple.  The first element of that tuple must be a string that names the
 
279
request method.  (Note that arguments in this protocol version are
 
280
bencoded.  As a result, unlike previous protocol versions, arguments in
 
281
this version are 8-bit clean.)
 
282
 
 
283
For error responses (where the Status byte is "E"), the situation is
 
284
analagous to requests.  The first item in the encoded sequence must be a
 
285
string of the error name.  The other arguments supply details about the
249
286
error, and their number and types will depend on the type of error (as
250
287
identified by the error name).
251
288
 
252
 
For success responses, there are no restrictions on the sequence.  It may
253
 
be empty, and the first element does not have to be a string.  The
254
 
contents are entirely dependent on the verb.
255
 
 
256
289
One possible error name is ``UnknownRequestVerb``, which means the server does
257
290
not recognise the verb used by the client's request.
258
291
 
259
 
The body encoding is::
260
 
 
261
 
  BODY_V3 := NO_BODY | LENGTH_PREFIXED_BODY | STREAMED_BODY_V2
262
 
  NO_BODY := "n"
263
 
  LENGTH_PREFIXED_BODY := "p" LENGTH_PREFIX BODY_BYTES
264
 
  STREAMED_BODY_V2 := "s" CHUNKS_V2
265
 
 
266
 
  CHUNKS_V2 := CHUNK_V2 | CHUNKS_TERMINATOR
267
 
  CHUNK_V2 := "c" LENGTH_PREFIX CHUNK_CONTENT CHUNK_V2
268
 
  CHUNKS_TERMINATOR := "t" BODY_STATUS
269
 
  BODY_STATUS := SUCCESS_STATUS | BODY_ERROR
270
 
  BODY_ERROR := ERROR_STATUS ARGS_V3
271
 
 
272
 
Version 3 messages always explicitly declare if a body is included.  The
273
 
absence of a body is signalled by sending NO_BODY as the body type.  If
274
 
present, bodies may be a single length-prefixed string (similar to
275
 
protocol 1) or a stream of chunks (similar to the streamed bodies in
276
 
protocol 2).
277
 
 
278
 
Unlike earlier versions, clients and servers are no longer required to
279
 
know which request verbs and responses will have bodies attached.  It is
280
 
always possible to know when a complete request or response has been read,
281
 
even if the server implements no verbs.
 
292
Streamed bodies
 
293
~~~~~~~~~~~~~~~
282
294
 
283
295
If an error occurs while a client or a server is generating a streamed
284
296
body, the sender should finish the stream and use BODY_ERROR as the