← 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: 2009-12-03 05:57:41 UTC
  • mfrom: (4857 +trunk)
  • mto: This revision was merged to the branch mainline in revision 4869.
  • Revision ID: andrew.bennetts@canonical.com-20091203055741-vmmg0fmjgjw2pwvu
Merge lp:bzr.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/network-protocol.txt
172
172
 
173
173
An extension to version two allows streamed bodies.  A streamed body looks
174
174
a lot like HTTP's chunked encoding::
175
 
 
 
175
 
176
176
  STREAMED_BODY := "chunked" NEWLINE CHUNKS TERMINATOR
177
177
  CHUNKS := CHUNK [CHUNKS]
178
178
  CHUNK := HEX_LENGTH CHUNK_CONTENT
179
179
  HEX_LENGTH := HEX_DIGITS NEWLINE
180
180
  CHUNK_CONTENT := bytes
181
 
  
 
181
 
182
182
  TERMINATOR := SUCCESS_TERMINATOR | ERROR_TERMINATOR
183
183
  SUCCESS_TERMINATOR := 'END' NEWLINE
184
184
  ERROR_TERMINATOR := 'ERR' NEWLINE CHUNKS SUCCESS_TERMINATOR
201
201
-------------
202
202
 
203
203
.. note::
204
 
  
 
204
 
205
205
  For some discussion of the requirements that led to this new protocol
206
206
  version, see `bug #83935`_.
207
207
 
226
226
  HEADERS := LENGTH_PREFIX bencoded_dict
227
227
  END_MESSAGE := "e"
228
228
 
229
 
  BODY := MESSAGE_PART+ 
 
229
  BODY := MESSAGE_PART+
230
230
  MESSAGE_PART := ONE_BYTE | STRUCTURE | BYTES
231
231
  ONE_BYTE := "o" byte
232
232
  STRUCTURE := "s" LENGTH_PREFIX bencoded_structure
262
262
Conventional requests will send a CONTENTS of ::
263
263
 
264
264
  CONV_REQ := ARGS SINGLE_OR_STREAMED_BODY?
265
 
  SINGLE_OR_STREAMED_BODY := BYTES 
 
265
  SINGLE_OR_STREAMED_BODY := BYTES
266
266
        | BYTES+ TRAILER
267
 
         
268
 
  ARGS := STRUCTURE(argument_tuple) 
 
267
 
 
268
  ARGS := STRUCTURE(argument_tuple)
269
269
  TRAILER := SUCCESS_STATUS | ERROR
270
270
  SUCCESS_STATUS := ONE_BYTE("S")
271
271
  ERROR := ONE_BYTE("E") STRUCTURE(argument_tuple)
276
276
  RESP_STATUS := ONE_BYTE("S") | ONE_BYTE("E")
277
277
 
278
278
If the RESP_STATUS is success ("S"), the arguments are the
279
 
method-dependent result.  
 
279
method-dependent result.
280
280
 
281
281
For errors (where the Status byte of a response or a streamed body is
282
282
"E"), the situation is analagous to requests.  The first item in the
287
287
Note that the streamed body from version two is now just multiple
288
288
BYTES parts.
289
289
 
290
 
The end of the request or response is indicated by the lower-level 
 
290
The end of the request or response is indicated by the lower-level
291
291
END_MESSAGE.  If there's only one BYTES element in the body, the TRAILER
292
292
may or may not be present, depending on whether it was sent as a single
293
293
chunk or as a stream that happens to have one element.
304
304
  initial success and then another byte part with no intervening bytes.
305
305
  If we stop sending the final success message and only flag errors
306
306
  they'll only get one if the error is detected after streaming starts but
307
 
  before any bytes are actually sent.  Possibly we should wait until at 
 
307
  before any bytes are actually sent.  Possibly we should wait until at
308
308
  least the first chunk is ready before declaring success.
309
309
 
310
310
For new methods, these sequences are just a convention and may be varied
320
320
  be preserved in the rpc from end to end.  This may be useful when
321
321
  there's an iterator on one side feeding in to an iterator on the other,
322
322
  if it avoids doing chunking and byte-counting at two levels, and if
323
 
  those iterators are a natural place to get good granularity.  Also, for 
 
323
  those iterators are a natural place to get good granularity.  Also, for
324
324
  cases like ``insert_record_stream`` the server can't do much with the
325
325
  data until it gets a whole chunk, and so it'll be natural and efficient
326
326
  for it to be called with one chunk at a time.
327
327
 
328
 
  On the other hand, there may be times when we've got some bytes from the 
 
328
  On the other hand, there may be times when we've got some bytes from the
329
329
  network but not a full chunk, and it might be worthwhile to pass it up.
330
330
  If we promise to preserve chunks, then to do this we'd need two separate
331
331
  streaming interfaces: "we got a chunk" and "we got some bytes but not