← 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-04 04:34:08 UTC
  • mto: This revision was merged to the branch mainline in revision 3398.
  • Revision ID: andrew.bennetts@canonical.com-20080204043408-w1rlbu9s7mkcohdp
Add description of proposed new network protocol to developer docs (and fix some minor inaccuracies in previous versions' descriptions).

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/network-protocol.txt
118
118
 
119
119
  REQUEST := MESSAGE_V1
120
120
  RESPONSE := MESSAGE_V1
121
 
  MESSAGE_V1 := ARGS BODY
 
121
  MESSAGE_V1 := ARGS [BODY]
122
122
 
123
123
  ARGS := ARG [MORE_ARGS] NEWLINE
124
124
  MORE_ARGS := SEP ARG [MORE_ARGS]
144
144
 
145
145
The response protocol is::
146
146
 
147
 
  RESPONSE_V2 := "bzr response 2" NEWLINE MESSAGE_V2
 
147
  RESPONSE_V2 := "bzr response 2" NEWLINE RESPONSE_STATUS NEWLINE MESSAGE_V2
 
148
  RESPONSE_STATUS := "success" | "failed"
148
149
 
149
150
Future versions should follow this structure, like version two does::
150
151
 
160
161
 
161
162
Version two of the message protocol is::
162
163
 
163
 
  MESSAGE_V2 := ARGS BODY
 
164
  MESSAGE_V2 := ARGS [BODY_V2]
164
165
  BODY_V2 := BODY | STREAMED_BODY
165
166
 
166
167
That is, a version one length-prefixed body, or a version two streamed
174
175
 
175
176
  STREAMED_BODY := "chunked" NEWLINE CHUNKS TERMINATOR
176
177
  CHUNKS := CHUNK [CHUNKS]
177
 
  CHUNK := CHUNK_LENGTH CHUNK_CONTENT
178
 
  CHUNK_LENGTH := HEX_DIGITS NEWLINE
 
178
  CHUNK := HEX_LENGTH CHUNK_CONTENT
 
179
  HEX_LENGTH := HEX_DIGITS NEWLINE
179
180
  CHUNK_CONTENT := bytes
180
181
  
181
182
  TERMINATOR := SUCCESS_TERMINATOR | ERROR_TERMINATOR
196
197
same for a given request method.  Only new request methods introduced in
197
198
Bazaar 0.91 and later use streamed bodies.
198
199
 
 
200
Version three
 
201
-------------
 
202
 
 
203
.. note::
 
204
  
 
205
  For some discussion of the requirements that led to this new protocol
 
206
  version, see bug #\ 83935_.
 
207
 
 
208
.. _83935: https://bugs.launchpad.net/bzr/+bug/83935
 
209
 
 
210
Version three has bencoding of most protocol structures, to make parsing
 
211
simpler.
 
212
 
 
213
The request and response protocol is::
 
214
 
 
215
  REQUEST_V3 := "bzr request 3" NEWLINE HEADERS REQUEST_ARGS BODY_V3
 
216
  RESPONSE_V3 := "bzr response 3" NEWLINE RESPONSE_STATUS_V3 HEADERS
 
217
                 RESPONSE_ARGS BODY_V3
 
218
  RESPONSE_STATUS_V3 := SUCCESS_STATUS | ERROR_STATUS
 
219
  SUCCESS_STATUS := "S"
 
220
  ERROR_STATUS := "E"
 
221
  HEADERS := bencoded_dictionary
 
222
 
 
223
Each request and response will have “headers”, a dictionary of key-value pairs.
 
224
The keys must be strings, not any other type of value.
 
225
 
 
226
Currently, the only defined header is “Software version”.  Both the client and
 
227
the server should include a “Software version” header, with a value of a
 
228
free-form string such as “bzrlib 1.2”, to aid debugging and logging.  Clients
 
229
and servers **should not** vary behaviour based on this string.
 
230
 
 
231
The argument encoding is::
 
232
 
 
233
  REQUEST_ARGS := bencoded_sequence
 
234
  RESPONSE_ARGS := bencoded_sequence
 
235
 
 
236
Arguments in this protocol version are bencoded, and the entire argument
 
237
structure is length-prefixed.  As a result, unlike previous protocol versions,
 
238
arguments in this version are 8-bit clean.
 
239
 
 
240
For requests, the first item in the encoded sequence must be a string of
 
241
the request's verb, e.g. ``Branch.last_revision_info``.  (And so requests must
 
242
always have at least one item in their REQUEST_ARGS sequence.)
 
243
 
 
244
For error responses (where the RESPONSE_STATUS_V3 is ERROR_STATUS), the
 
245
situation is analagous to requests.  The first item in the encoded sequence must
 
246
be a string of the error name.  The other arguments supply details about the
 
247
error, and their number and types will depend on the type of error (as
 
248
identified by the error name).
 
249
 
 
250
One possible error name is ``UnknownRequestVerb``, which means the server does
 
251
not recognise the verb used by the client's request.
 
252
 
 
253
The body encoding is::
 
254
 
 
255
  BODY_V3 := NO_BODY | LENGTH_PREFIXED_BODY | STREAMED_BODY_V2
 
256
  NO_BODY := "n"
 
257
  LENGTH_PREFIXED_BODY := "p" LENGTH_PREFIX BODY_BYTES
 
258
  LENGTH_PREFIX := 32-bit unsigned integer in network byte order
 
259
  STREAMED_BODY_V2 := "s" CHUNKS_V2 TERMINATOR_V2
 
260
 
 
261
  CHUNKS_V2 := "c" CHUNK_V2 [CHUNKS_V2]
 
262
  CHUNK_V2 := LENGTH_PREFIX CHUNK_CONTENT
 
263
  
 
264
  TERMINATOR_V2 := SUCCESS_TERMINATOR_V2 | ERROR_TERMINATOR_V2
 
265
  SUCCESS_TERMINATOR_V2 := SUCCESS_STATUS
 
266
  ERROR_TERMINATOR_V2 := ERROR_STATUS bencoded_sequence
 
267
 
 
268
Version 3 messages always explicitly declare if a body is included.  Clients
 
269
and servers are no longer expected to know which request verbs and responses
 
270
will have bodies attached.  If present, bodies may be a single length-prefixed
 
271
string (like in protocol 1) or a stream of chunks (like in protocol 2).
 
272
 
 
273
If a streamed body is finished with an error, that error will be encoded
 
274
identically to RESPONSE_ARGS.
 
275
 
199
276
Paths
200
277
=====
201
278