/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

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

  • Committer: Andrew Bennetts
  • Date: 2007-09-03 05:11:38 UTC
  • mto: (2748.4.9 hpss-streaming)
  • mto: This revision was merged to the branch mainline in revision 2985.
  • Revision ID: andrew.bennetts@canonical.com-20070903051138-ikak86wb238gk1da
Add description of proposed streamed body extension to network-protocol.txt.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/network-protocol.txt
39
39
deserialises bytes into the structured data that requests and responses
40
40
consist of.
41
41
 
42
 
Version one of the protocol (for requests and responses) is described by::
43
 
 
44
 
  REQUEST := MESSAGE_V1
45
 
  RESPONSE := MESSAGE_V1
46
 
  MESSAGE_V1 := ARGS BODY
47
 
 
48
 
  ARGS := ARG [MORE_ARGS] NEWLINE
49
 
  MORE_ARGS := SEP ARG [MORE_ARGS]
50
 
  SEP := 0x01
51
 
 
52
 
  BODY := LENGTH NEWLINE BODY_BYTES TRAILER
53
 
  LENGTH := decimal integer
54
 
  TRAILER := "done" NEWLINE
55
 
 
56
 
That is, a tuple of arguments separated by Ctrl-A and terminated with a
57
 
newline, followed by length prefixed body with a constant trailer.  Note
58
 
that although arguments are not 8-bit safe (they cannot include 0x01 or
59
 
0x0a bytes without breaking the protocol encoding), the body is.
60
 
 
61
 
Version two of the request protocol is::
62
 
 
63
 
  REQUEST_V2 := "bzr request 2" NEWLINE MESSAGE_V1
64
 
 
65
 
Version two of the response protocol is::
66
 
 
67
 
  RESPONSE_V2 := "bzr request 2" NEWLINE MESSAGE_V1
68
 
 
69
 
Future versions should follow this structure, like version two does::
70
 
 
71
 
  FUTURE_MESSAGE := VERSION_STRING NEWLINE REST_OF_MESSAGE
72
 
 
73
 
This is that clients and servers can read bytes up to the first newline
74
 
byte to determine what version a message is.
75
 
 
76
 
For compatibility will all versions (past and future) of bzr clients,
77
 
servers that receive a request in an unknown protocol version should
78
 
respond with a single-line error terminated with 0x0a (NEWLINE), rather
79
 
than structured response prefixed with a version string.
80
 
 
81
42
Request/Response processing
82
43
---------------------------
83
44
 
146
107
There is also an plain file-level transport that calls remote methods to
147
108
manipulate files on the server in `bzrlib.transport.remote`.
148
109
 
 
110
Protocol description
 
111
====================
 
112
 
 
113
Version one
 
114
-----------
 
115
 
 
116
Version one of the protocol (for requests and responses) is described by::
 
117
 
 
118
  REQUEST := MESSAGE_V1
 
119
  RESPONSE := MESSAGE_V1
 
120
  MESSAGE_V1 := ARGS BODY
 
121
 
 
122
  ARGS := ARG [MORE_ARGS] NEWLINE
 
123
  MORE_ARGS := SEP ARG [MORE_ARGS]
 
124
  SEP := 0x01
 
125
 
 
126
  BODY := LENGTH NEWLINE BODY_BYTES TRAILER
 
127
  LENGTH := decimal integer
 
128
  TRAILER := "done" NEWLINE
 
129
 
 
130
That is, a tuple of arguments separated by Ctrl-A and terminated with a
 
131
newline, followed by length prefixed body with a constant trailer.  Note
 
132
that although arguments are not 8-bit safe (they cannot include 0x01 or
 
133
0x0a bytes without breaking the protocol encoding), the body is.
 
134
 
 
135
Version two
 
136
-----------
 
137
 
 
138
Version two of the request protocol is::
 
139
 
 
140
  REQUEST_V2 := "bzr request 2" NEWLINE MESSAGE_V2
 
141
 
 
142
Version two of the response protocol is::
 
143
 
 
144
  RESPONSE_V2 := "bzr request 2" NEWLINE MESSAGE_V2
 
145
 
 
146
Future versions should follow this structure, like version two does::
 
147
 
 
148
  FUTURE_MESSAGE := VERSION_STRING NEWLINE REST_OF_MESSAGE
 
149
 
 
150
This is so that clients and servers can read bytes up to the first newline
 
151
byte to determine what version a message is.
 
152
 
 
153
For compatibility will all versions (past and future) of bzr clients,
 
154
servers that receive a request in an unknown protocol version should
 
155
respond with a single-line error terminated with 0x0a (NEWLINE), rather
 
156
than structured response prefixed with a version string.
 
157
 
 
158
Version two of the message protocol is::
 
159
 
 
160
  MESSAGE_V2 := ARGS BODY
 
161
  BODY_V2 := BODY | STREAMED_BODY
 
162
 
 
163
That is, a version one length-prefixed body, or a version two streamed
 
164
body.
 
165
 
 
166
A streamed body looks a lot like HTTP's chunked encoding::
 
167
 
 
168
  STREAMED_BODY := "chunked" NEWLINE CHUNKS TERMINATOR
 
169
  CHUNKS := CHUNK [CHUNKS]
 
170
  CHUNK := CHUNK_LENGTH CHUNK_CONTENT
 
171
  CHUNK_LENGTH := HEX_DIGITS NEWLINE
 
172
  CHUNK_CONTENT := bytes
 
173
  
 
174
  TERMINATOR := SUCCESS_TERMINATOR | ERROR_TERMINATOR
 
175
  SUCCESS_TERMINATOR := 'END' NEWLINE
 
176
  ERROR_TERMINATOR := 'ERR' NEWLINE CHUNKS SUCCESS_TERMINATOR
 
177
 
 
178
That is, the body consists of a series of chunks.  Each chunk starts with
 
179
a length prefix in hexadecimal digits, followed by an ASCII newline byte.
 
180
The end of the body is signaled by 'END\\n', or by 'ERR\\n' followed by
 
181
error args, one per chunk.  Note that this allows an 8-bit clean error
 
182
response.
 
183
 
 
184
A streamed body starts with the string "chunked" so that legacy clients
 
185
and servers will not mistake the first chunk as the start of a version one
 
186
body.
 
187
 
 
188
Software versions
 
189
-----------------
 
190
 
 
191
Version 1 of the protocol was introduced in Bazaar 0.11.
 
192
 
 
193
Version 2 was introduced in Bazaar 0.16.
 
194
 
 
195
 
149
196
Paths
150
197
=====
151
198
 
166
213
meaningful when limited to a directory?
167
214
 
168
215
 
 
216
Requests
 
217
========
 
218
 
 
219
The available request methods are registered in `bzrlib.smart.request`.
 
220
 
169
221
..
170
222
   vim: ft=rst tw=74 ai
171
223