[MERGE][RFC] Proposed version 3 of smart server protocol
Andrew Bennetts
andrew at canonical.com
Mon Feb 4 04:41:52 GMT 2008
Hi all,
This bundle adds a section to network-protocol.txt describing new version of the
smart protocol. If you think there's some other change to the protocol that
should be taken into account, now would be a good time to mention it ;)
The text should be pretty self-explanatory. Let me know if it isn't.
-Andrew.
-------------- next part --------------
# Bazaar merge directive format 2 (Bazaar 0.90)
# revision_id: andrew.bennetts at canonical.com-20080204043408-\
# w1rlbu9s7mkcohdp
# target_branch: http://bazaar-vcs.org/bzr/bzr.dev
# testament_sha1: 12ef30c50452ced8d457d8cc214bcd8a5a53dfc5
# timestamp: 2008-02-04 15:36:29 +1100
# source_branch: http://people.ubuntu.com/~andrew/bzr/protocol-v3-doc
# base_revision_id: pqm at pqm.ubuntu.com-20080201053934-q32y2nk5vvo13c6v
#
# Begin patch
=== modified file 'doc/default.css'
--- doc/default.css 2007-08-07 14:56:50 +0000
+++ doc/default.css 2008-02-04 04:34:08 +0000
@@ -35,6 +35,20 @@
color: inherit;
}
+div.note {
+ margin-left: 5em;
+ margin-right: 5em;
+ color: #000000;
+ background-color: #c1d1ff;
+ border: 1px solid #888888;
+ padding-left: 1em;
+ padding-right: 1em;
+ }
+
+div.note .first {
+ font-weight: bold;
+ }
+
h1 {
color: #b52b2b;
/* DKREDcolor: #966b72; */
@@ -124,7 +138,6 @@
margin-right: 5em;
color: #000000;
font-weight: normal;
- background-color: #c1d1ff;
background-color: #e5ecf9;
border: 1px solid #888888;
padding: 1em;
=== modified file 'doc/developers/network-protocol.txt'
--- doc/developers/network-protocol.txt 2007-11-09 20:49:54 +0000
+++ doc/developers/network-protocol.txt 2008-02-04 04:34:08 +0000
@@ -118,7 +118,7 @@
REQUEST := MESSAGE_V1
RESPONSE := MESSAGE_V1
- MESSAGE_V1 := ARGS BODY
+ MESSAGE_V1 := ARGS [BODY]
ARGS := ARG [MORE_ARGS] NEWLINE
MORE_ARGS := SEP ARG [MORE_ARGS]
@@ -144,7 +144,8 @@
The response protocol is::
- RESPONSE_V2 := "bzr response 2" NEWLINE MESSAGE_V2
+ RESPONSE_V2 := "bzr response 2" NEWLINE RESPONSE_STATUS NEWLINE MESSAGE_V2
+ RESPONSE_STATUS := "success" | "failed"
Future versions should follow this structure, like version two does::
@@ -160,7 +161,7 @@
Version two of the message protocol is::
- MESSAGE_V2 := ARGS BODY
+ MESSAGE_V2 := ARGS [BODY_V2]
BODY_V2 := BODY | STREAMED_BODY
That is, a version one length-prefixed body, or a version two streamed
@@ -174,8 +175,8 @@
STREAMED_BODY := "chunked" NEWLINE CHUNKS TERMINATOR
CHUNKS := CHUNK [CHUNKS]
- CHUNK := CHUNK_LENGTH CHUNK_CONTENT
- CHUNK_LENGTH := HEX_DIGITS NEWLINE
+ CHUNK := HEX_LENGTH CHUNK_CONTENT
+ HEX_LENGTH := HEX_DIGITS NEWLINE
CHUNK_CONTENT := bytes
TERMINATOR := SUCCESS_TERMINATOR | ERROR_TERMINATOR
@@ -196,6 +197,82 @@
same for a given request method. Only new request methods introduced in
Bazaar 0.91 and later use streamed bodies.
+Version three
+-------------
+
+.. note::
+
+ For some discussion of the requirements that led to this new protocol
+ version, see bug #\ 83935_.
+
+.. _83935: https://bugs.launchpad.net/bzr/+bug/83935
+
+Version three has bencoding of most protocol structures, to make parsing
+simpler.
+
+The request and response protocol is::
+
+ REQUEST_V3 := "bzr request 3" NEWLINE HEADERS REQUEST_ARGS BODY_V3
+ RESPONSE_V3 := "bzr response 3" NEWLINE RESPONSE_STATUS_V3 HEADERS
+ RESPONSE_ARGS BODY_V3
+ RESPONSE_STATUS_V3 := SUCCESS_STATUS | ERROR_STATUS
+ SUCCESS_STATUS := "S"
+ ERROR_STATUS := "E"
+ HEADERS := bencoded_dictionary
+
+Each request and response will have ?headers?, a dictionary of key-value pairs.
+The keys must be strings, not any other type of value.
+
+Currently, the only defined header is ?Software version?. Both the client and
+the server should include a ?Software version? header, with a value of a
+free-form string such as ?bzrlib 1.2?, to aid debugging and logging. Clients
+and servers **should not** vary behaviour based on this string.
+
+The argument encoding is::
+
+ REQUEST_ARGS := bencoded_sequence
+ RESPONSE_ARGS := bencoded_sequence
+
+Arguments in this protocol version are bencoded, and the entire argument
+structure is length-prefixed. As a result, unlike previous protocol versions,
+arguments in this version are 8-bit clean.
+
+For requests, the first item in the encoded sequence must be a string of
+the request's verb, e.g. ``Branch.last_revision_info``. (And so requests must
+always have at least one item in their REQUEST_ARGS sequence.)
+
+For error responses (where the RESPONSE_STATUS_V3 is ERROR_STATUS), the
+situation is analagous to requests. The first item in the encoded sequence must
+be a string of the error name. The other arguments supply details about the
+error, and their number and types will depend on the type of error (as
+identified by the error name).
+
+One possible error name is ``UnknownRequestVerb``, which means the server does
+not recognise the verb used by the client's request.
+
+The body encoding is::
+
+ BODY_V3 := NO_BODY | LENGTH_PREFIXED_BODY | STREAMED_BODY_V2
+ NO_BODY := "n"
+ LENGTH_PREFIXED_BODY := "p" LENGTH_PREFIX BODY_BYTES
+ LENGTH_PREFIX := 32-bit unsigned integer in network byte order
+ STREAMED_BODY_V2 := "s" CHUNKS_V2 TERMINATOR_V2
+
+ CHUNKS_V2 := "c" CHUNK_V2 [CHUNKS_V2]
+ CHUNK_V2 := LENGTH_PREFIX CHUNK_CONTENT
+
+ TERMINATOR_V2 := SUCCESS_TERMINATOR_V2 | ERROR_TERMINATOR_V2
+ SUCCESS_TERMINATOR_V2 := SUCCESS_STATUS
+ ERROR_TERMINATOR_V2 := ERROR_STATUS bencoded_sequence
+
+Version 3 messages always explicitly declare if a body is included. Clients
+and servers are no longer expected to know which request verbs and responses
+will have bodies attached. If present, bodies may be a single length-prefixed
+string (like in protocol 1) or a stream of chunks (like in protocol 2).
+
+If a streamed body is finished with an error, that error will be encoded
+identically to RESPONSE_ARGS.
+
Paths
=====
# Begin bundle
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
f/F3JFOFCQS1UEew
More information about the bazaar
mailing list