← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

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

Merge hpss-protocol-docs.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/network-protocol.txt
85
85
          (e.g. reading from a bundle generated in bzrlib to deliver a
86
86
          complete request).
87
87
 
88
 
          Possibly this should just be RemoteBzrDir, RemoteTransport,
89
 
          ...
 
88
          This is RemoteBzrDir, RemoteRepository, etc.
90
89
  ^
91
90
  | structured data
92
91
  v
98
97
  | bytes.
99
98
  v
100
99
 
101
 
 MEDIUM  (accepts bytes from the protocol & delivers to the remote server.
102
 
          Allows the potocol to read bytes e.g. socket, pipe, HTTP request.
 
100
 MEDIUM   accepts bytes from the protocol & delivers to the remote server.
 
101
          Allows the protocol to read bytes e.g. socket, pipe, HTTP request.
103
102
 
104
103
The domain logic is in `bzrlib.remote`: `RemoteBzrDir`, `RemoteBranch`,
105
104
and so on.
113
112
Version one
114
113
-----------
115
114
 
116
 
Version one of the protocol (for requests and responses) is described by::
 
115
Version one of the protocol was introduced in Bazaar 0.11.
 
116
 
 
117
The protocol (for both requests and responses) is described by::
117
118
 
118
119
  REQUEST := MESSAGE_V1
119
120
  RESPONSE := MESSAGE_V1
135
136
Version two
136
137
-----------
137
138
 
138
 
Version two of the request protocol is::
 
139
Version two was introduced in Bazaar 0.16.
 
140
 
 
141
The request protocol is::
139
142
 
140
143
  REQUEST_V2 := "bzr request 2" NEWLINE MESSAGE_V2
141
144
 
142
 
Version two of the response protocol is::
 
145
The response protocol is::
143
146
 
144
 
  RESPONSE_V2 := "bzr request 2" NEWLINE MESSAGE_V2
 
147
  RESPONSE_V2 := "bzr response 2" NEWLINE MESSAGE_V2
145
148
 
146
149
Future versions should follow this structure, like version two does::
147
150
 
163
166
That is, a version one length-prefixed body, or a version two streamed
164
167
body.
165
168
 
166
 
A streamed body looks a lot like HTTP's chunked encoding::
 
169
Version two with streamed bodies
 
170
--------------------------------
 
171
 
 
172
An extension to version two allows streamed bodies.  A streamed body looks
 
173
a lot like HTTP's chunked encoding::
167
174
 
168
175
  STREAMED_BODY := "chunked" NEWLINE CHUNKS TERMINATOR
169
176
  CHUNKS := CHUNK [CHUNKS]
185
192
and servers will not mistake the first chunk as the start of a version one
186
193
body.
187
194
 
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
The type of body (length-prefixed or chunked) in a response is always the
 
196
same for a given request method.  Only new request methods introduced in
 
197
Bazaar 0.91 and later use streamed bodies.
195
198
 
196
199
Paths
197
200
=====
206
209
particular directory and its children, so will want to do a software
207
210
virtual root at that level.  In other words they'll want to rewrite
208
211
incoming paths to be under that level (and prevent escaping using ../
209
 
tricks.)
 
212
tricks).  The default implementation in bzrlib does this using the
 
213
`bzrlib.transport.chroot` module.
210
214
 
211
215
URLs that include ~ should probably be passed across to the server
212
216
verbatim and the server can expand them.  This will proably not be
213
 
meaningful when limited to a directory?
 
217
meaningful when limited to a directory?  See `bug 109143`_.
 
218
 
 
219
.. _bug 109143: https://bugs.launchpad.net/bzr/+bug/109143
214
220
 
215
221
 
216
222
Requests
217
223
========
218
224
 
 
225
The first argument of a request specifies the request method.
 
226
 
219
227
The available request methods are registered in `bzrlib.smart.request`.
220
228
 
 
229
**XXX**: ideally the request methods should be documented here.
 
230
Contributions welcome!
 
231
 
 
232
 
221
233
..
222
234
   vim: ft=rst tw=74 ai
223
235