Rev 3398: Add the smart protocol v3 specification to network-protocol.txt in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Thu May 1 12:25:22 BST 2008
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 3398
revision-id:pqm at pqm.ubuntu.com-20080501112512-b9lgs4w8r43evtn1
parent: pqm at pqm.ubuntu.com-20080501091514-61b80pvo69wnhf2t
parent: andrew.bennetts at canonical.com-20080501004334-2m1vke5vkohpq172
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Thu 2008-05-01 12:25:12 +0100
message:
Add the smart protocol v3 specification to network-protocol.txt
modified:
doc/default.css default.css-20060622101119-tgwtdci8z769bjb9-1
doc/developers/network-protocol.txt networkprotocol.txt-20070903044232-woustorrjbmg5zol-1
------------------------------------------------------------
revno: 3211.7.10
revision-id:andrew.bennetts at canonical.com-20080501004334-2m1vke5vkohpq172
parent: andrew.bennetts at canonical.com-20080220121704-h65l9ol4g1d4dk0v
committer: Andrew Bennetts <andrew.bennetts at canonical.com>
branch nick: protocol-v3-doc
timestamp: Thu 2008-05-01 10:43:34 +1000
message:
Trivial tweaks to keep network-protocol.txt current with implementation.
modified:
doc/developers/network-protocol.txt networkprotocol.txt-20070903044232-woustorrjbmg5zol-1
------------------------------------------------------------
revno: 3211.7.9
revision-id:andrew.bennetts at canonical.com-20080220121704-h65l9ol4g1d4dk0v
parent: andrew.bennetts at canonical.com-20080220092550-ig314l6l188b0vmc
committer: Andrew Bennetts <andrew.bennetts at canonical.com>
branch nick: protocol-v3-doc
timestamp: Wed 2008-02-20 23:17:04 +1100
message:
Remove CHUNKED_BYTES message part; it's unnecessary. Also polished the text a little.
modified:
doc/developers/network-protocol.txt networkprotocol.txt-20070903044232-woustorrjbmg5zol-1
------------------------------------------------------------
revno: 3211.7.8
revision-id:andrew.bennetts at canonical.com-20080220092550-ig314l6l188b0vmc
parent: andrew.bennetts at canonical.com-20080220061429-sc6xla297wy2dnio
committer: Andrew Bennetts <andrew.bennetts at canonical.com>
branch nick: protocol-v3-doc
timestamp: Wed 2008-02-20 20:25:50 +1100
message:
Cosmetic tweaks.
modified:
doc/developers/network-protocol.txt networkprotocol.txt-20070903044232-woustorrjbmg5zol-1
------------------------------------------------------------
revno: 3211.7.7
revision-id:andrew.bennetts at canonical.com-20080220061429-sc6xla297wy2dnio
parent: andrew.bennetts at canonical.com-20080214225755-fzmw8cgiw3thn9uk
committer: Andrew Bennetts <andrew.bennetts at canonical.com>
branch nick: protocol-v3-doc
timestamp: Wed 2008-02-20 17:14:29 +1100
message:
Update the protocol spec for Robert and Martin's latest comments.
modified:
doc/developers/network-protocol.txt networkprotocol.txt-20070903044232-woustorrjbmg5zol-1
------------------------------------------------------------
revno: 3211.7.6
revision-id:andrew.bennetts at canonical.com-20080214225755-fzmw8cgiw3thn9uk
parent: andrew.bennetts at canonical.com-20080211093814-rxkawg4lbjteeb8x
committer: Andrew Bennetts <andrew.bennetts at canonical.com>
branch nick: protocol-v3-doc
timestamp: Fri 2008-02-15 09:57:55 +1100
message:
Take Martin's latest comments into account: Keep symmetry of requests and responses, allow streamed bodies to be explicitly interrupted with an error.
modified:
doc/developers/network-protocol.txt networkprotocol.txt-20070903044232-woustorrjbmg5zol-1
------------------------------------------------------------
revno: 3211.7.5
revision-id:andrew.bennetts at canonical.com-20080211093814-rxkawg4lbjteeb8x
parent: andrew.bennetts at canonical.com-20080211064548-ezbwec9slxsmz7k3
committer: Andrew Bennetts <andrew.bennetts at canonical.com>
branch nick: protocol-v3-doc
timestamp: Mon 2008-02-11 20:38:14 +1100
message:
Describe how error during streamed request bodies ought to be handled.
modified:
doc/developers/network-protocol.txt networkprotocol.txt-20070903044232-woustorrjbmg5zol-1
------------------------------------------------------------
revno: 3211.7.4
revision-id:andrew.bennetts at canonical.com-20080211064548-ezbwec9slxsmz7k3
parent: andrew.bennetts at canonical.com-20080207070513-u7tvul100g1yn6n7
committer: Andrew Bennetts <andrew.bennetts at canonical.com>
branch nick: protocol-v3-doc
timestamp: Mon 2008-02-11 17:45:48 +1100
message:
Add another XXX, tweak grammar to allow a streamed body with zero chunks.
modified:
doc/developers/network-protocol.txt networkprotocol.txt-20070903044232-woustorrjbmg5zol-1
------------------------------------------------------------
revno: 3211.7.3
revision-id:andrew.bennetts at canonical.com-20080207070513-u7tvul100g1yn6n7
parent: andrew.bennetts at canonical.com-20080207065757-cyw15130ejca3db3
committer: Andrew Bennetts <andrew.bennetts at canonical.com>
branch nick: protocol-v3-doc
timestamp: Thu 2008-02-07 18:05:13 +1100
message:
Add a comment to the new CSS.
modified:
doc/default.css default.css-20060622101119-tgwtdci8z769bjb9-1
------------------------------------------------------------
revno: 3211.7.2
revision-id:andrew.bennetts at canonical.com-20080207065757-cyw15130ejca3db3
parent: andrew.bennetts at canonical.com-20080204043408-w1rlbu9s7mkcohdp
committer: Andrew Bennetts <andrew.bennetts at canonical.com>
branch nick: protocol-v3-doc
timestamp: Thu 2008-02-07 17:57:57 +1100
message:
Tweak the proposed protocol according to review comments.
modified:
doc/developers/network-protocol.txt networkprotocol.txt-20070903044232-woustorrjbmg5zol-1
------------------------------------------------------------
revno: 3211.7.1
revision-id:andrew.bennetts at canonical.com-20080204043408-w1rlbu9s7mkcohdp
parent: pqm at pqm.ubuntu.com-20080201053934-q32y2nk5vvo13c6v
committer: Andrew Bennetts <andrew.bennetts at canonical.com>
branch nick: protocol-v3-doc
timestamp: Mon 2008-02-04 15:34:08 +1100
message:
Add description of proposed new network protocol to developer docs (and fix some minor inaccuracies in previous versions' descriptions).
modified:
doc/default.css default.css-20060622101119-tgwtdci8z769bjb9-1
doc/developers/network-protocol.txt networkprotocol.txt-20070903044232-woustorrjbmg5zol-1
=== modified file 'doc/default.css'
--- a/doc/default.css 2007-08-07 14:56:50 +0000
+++ b/doc/default.css 2008-02-07 07:05:13 +0000
@@ -35,6 +35,21 @@
color: inherit;
}
+/* Format ".. note:" sections nicely */
+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 +139,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'
--- a/doc/developers/network-protocol.txt 2007-11-09 20:49:54 +0000
+++ b/doc/developers/network-protocol.txt 2008-05-01 00:43:34 +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,107 @@
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`_.
+
+.. _bug #83935: https://bugs.launchpad.net/bzr/+bug/83935
+
+Version three has bencoding of most protocol structures, to make parsing
+simpler. For extra parsing convenience, these structures are length
+prefixed::
+
+ LENGTH_PREFIX := 32-bit unsigned integer in network byte order
+
+Unlike earlier versions, clients and servers are no longer required to
+know which request verbs and responses will have bodies attached. Because
+of length-prefixing and other changes, it is always possible to know when
+a complete request or response has been read, even if the server
+implements no verbs.
+
+The underlying message format is::
+
+ MESSAGE := "bzr message 3" NEWLINE HEADERS MESSAGE_PARTS
+ HEADERS := LENGTH_PREFIX bencoded_dict
+ MESSAGE_PARTS := MESSAGE_PART [MORE_MESSAGE_PARTS]
+ MORE_MESSAGE_PARTS := END_MESSAGE_PARTS | MESSAGE_PARTS
+ END_MESSAGE_PARTS := "e"
+
+ MESSAGE_PART := ONE_BYTE | STRUCTURE | BYTES
+ ONE_BYTE := "o" byte
+ STRUCTURE := "s" LENGTH_PREFIX bencoded_structure
+ BYTES := "b" LENGTH_PREFIX bytes
+
+This format allows an arbitrary sequence of message parts to be encoded
+in a single message.
+
+Headers
+~~~~~~~
+
+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.5â€, to aid debugging and logging. Clients
+and servers **should not** vary behaviour based on this string.
+
+Conventional requests and responses
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By convention, most requests and responses have a simple “arguments plus
+optional body†structure, as in earlier protocol versions. This section
+describes how such messages are encoded. All requests and responses
+defined by earlier protocol versions must be encoded in this way.
+
+Conventional requests will send a sequence of:
+
+* Arguments (a STRUCTURE of a tuple)
+
+* (Optional) body
+
+ * Single body (BYTES), or
+
+ * Streamed body (multiple BYTES parts), followed by a status (ONE_BYTE)
+
+ * if status is "E", followed by an Error (STRUCTURE)
+
+Conventional responses will send a sequence of:
+
+* Status (ONE_BYTE)
+
+* Arguments (a STRUCTURE of a tuple)
+
+* (Optional) body
+
+ * Single body (BYTES), or
+
+ * Streamed body (multiple BYTES parts), followed by a status (ONE_BYTE)
+
+ * if status is "E", followed by an Error (STRUCTURE)
+
+In all cases, the ONE_BYTE status is either "S" for Success or "E" for
+Error. Note that the streamed body from version two is now just multiple
+BYTES parts.
+
+For new methods, these sequences are just a convention and may be varied
+if appropriate for a particular request or response. However, each
+request should at least start with a STRUCTURE encoding the arguments
+tuple. The first element of that tuple must be a string that names the
+request method. (Note that arguments in this protocol version are
+bencoded. As a result, unlike previous protocol versions, arguments in
+this version are 8-bit clean.)
+
+For errors (where the Status byte of a response or a streamed body is
+"E"), 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).
+
Paths
=====
@@ -230,6 +332,18 @@
Contributions welcome!
+Recognised errors
+=================
+
+The first argument of an error response specifies the error type.
+
+One possible error name is ``UnknownMethod``, which means the server does
+not recognise the verb used by the client's request. This error was
+introduced in version three.
+
+**XXX**: ideally the error types should be documented here. Contributions
+welcome!
+
..
vim: ft=rst tw=74 ai
More information about the bazaar-commits
mailing list