← 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: Canonical.com Patch Queue Manager
  • Date: 2008-04-07 07:52:50 UTC
  • mfrom: (3340.1.1 208418-1.4)
  • Revision ID: pqm@pqm.ubuntu.com-20080407075250-phs53xnslo8boaeo
Return the correct knit serialisation method in _StreamAccess.
        (Andrew Bennetts, Martin Pool, Robert Collins)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/network-protocol.txt
 
1
================
 
2
Network Protocol
 
3
================
 
4
 
 
5
:Date: 2007-09-03
 
6
 
 
7
 
 
8
.. contents::
 
9
 
 
10
 
 
11
Overview
 
12
========
 
13
 
 
14
The smart protocol provides a way to send a requests and corresponding
 
15
responses to communicate with a remote bzr process.
 
16
 
 
17
Layering
 
18
========
 
19
 
 
20
Medium
 
21
------
 
22
 
 
23
At the bottom level there is either a socket, pipes, or an HTTP
 
24
request/response.  We call this layer the *medium*.  It is responsible for
 
25
carrying bytes between a client and server.  For sockets, we have the idea
 
26
that you have multiple requests and get a read error because the other
 
27
side did shutdown.  For pipes we have read pipe which will have a zero
 
28
read which marks end-of-file.  For HTTP server environment there is no
 
29
end-of-stream because each request coming into the server is independent.
 
30
 
 
31
So we need a wrapper around pipes and sockets to seperate out requests
 
32
from substrate and this will give us a single model which is consistent
 
33
for HTTP, sockets and pipes.
 
34
 
 
35
Protocol
 
36
--------
 
37
 
 
38
On top of the medium is the *protocol*.  This is the layer that
 
39
deserialises bytes into the structured data that requests and responses
 
40
consist of.
 
41
 
 
42
Request/Response processing
 
43
---------------------------
 
44
 
 
45
On top of the protocol is the logic for processing requests (on the
 
46
server) or responses (on the client).
 
47
 
 
48
Server-side
 
49
-----------
 
50
 
 
51
Sketch::
 
52
 
 
53
 MEDIUM  (factory for protocol, reads bytes & pushes to protocol,
 
54
          uses protocol to detect end-of-request, sends written
 
55
          bytes to client) e.g. socket, pipe, HTTP request handler.
 
56
  ^
 
57
  | bytes.
 
58
  v
 
59
 
 
60
 PROTOCOL(serialization, deserialization)  accepts bytes for one
 
61
          request, decodes according to internal state, pushes
 
62
          structured data to handler.  accepts structured data from
 
63
          handler and encodes and writes to the medium.  factory for
 
64
          handler.
 
65
  ^
 
66
  | structured data
 
67
  v
 
68
 
 
69
 HANDLER  (domain logic) accepts structured data, operates state
 
70
          machine until the request can be satisfied,
 
71
          sends structured data to the protocol.
 
72
 
 
73
Request handlers are registered in the `bzrlib.smart.request` module.
 
74
 
 
75
 
 
76
Client-side
 
77
-----------
 
78
 
 
79
Sketch::
 
80
 
 
81
 CLIENT   domain logic, accepts domain requests, generated structured
 
82
          data, reads structured data from responses and turns into
 
83
          domain data.  Sends structured data to the protocol.
 
84
          Operates state machines until the request can be delivered
 
85
          (e.g. reading from a bundle generated in bzrlib to deliver a
 
86
          complete request).
 
87
 
 
88
          This is RemoteBzrDir, RemoteRepository, etc.
 
89
  ^
 
90
  | structured data
 
91
  v
 
92
 
 
93
 PROTOCOL  (serialization, deserialization)  accepts structured data for one
 
94
          request, encodes and writes to the medium.  Reads bytes from the
 
95
          medium, decodes and allows the client to read structured data.
 
96
  ^
 
97
  | bytes.
 
98
  v
 
99
 
 
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.
 
102
 
 
103
The domain logic is in `bzrlib.remote`: `RemoteBzrDir`, `RemoteBranch`,
 
104
and so on.
 
105
 
 
106
There is also an plain file-level transport that calls remote methods to
 
107
manipulate files on the server in `bzrlib.transport.remote`.
 
108
 
 
109
Protocol description
 
110
====================
 
111
 
 
112
Version one
 
113
-----------
 
114
 
 
115
Version one of the protocol was introduced in Bazaar 0.11.
 
116
 
 
117
The protocol (for both requests and responses) is described by::
 
118
 
 
119
  REQUEST := MESSAGE_V1
 
120
  RESPONSE := MESSAGE_V1
 
121
  MESSAGE_V1 := ARGS BODY
 
122
 
 
123
  ARGS := ARG [MORE_ARGS] NEWLINE
 
124
  MORE_ARGS := SEP ARG [MORE_ARGS]
 
125
  SEP := 0x01
 
126
 
 
127
  BODY := LENGTH NEWLINE BODY_BYTES TRAILER
 
128
  LENGTH := decimal integer
 
129
  TRAILER := "done" NEWLINE
 
130
 
 
131
That is, a tuple of arguments separated by Ctrl-A and terminated with a
 
132
newline, followed by length prefixed body with a constant trailer.  Note
 
133
that although arguments are not 8-bit safe (they cannot include 0x01 or
 
134
0x0a bytes without breaking the protocol encoding), the body is.
 
135
 
 
136
Version two
 
137
-----------
 
138
 
 
139
Version two was introduced in Bazaar 0.16.
 
140
 
 
141
The request protocol is::
 
142
 
 
143
  REQUEST_V2 := "bzr request 2" NEWLINE MESSAGE_V2
 
144
 
 
145
The response protocol is::
 
146
 
 
147
  RESPONSE_V2 := "bzr response 2" NEWLINE MESSAGE_V2
 
148
 
 
149
Future versions should follow this structure, like version two does::
 
150
 
 
151
  FUTURE_MESSAGE := VERSION_STRING NEWLINE REST_OF_MESSAGE
 
152
 
 
153
This is so that clients and servers can read bytes up to the first newline
 
154
byte to determine what version a message is.
 
155
 
 
156
For compatibility will all versions (past and future) of bzr clients,
 
157
servers that receive a request in an unknown protocol version should
 
158
respond with a single-line error terminated with 0x0a (NEWLINE), rather
 
159
than structured response prefixed with a version string.
 
160
 
 
161
Version two of the message protocol is::
 
162
 
 
163
  MESSAGE_V2 := ARGS BODY
 
164
  BODY_V2 := BODY | STREAMED_BODY
 
165
 
 
166
That is, a version one length-prefixed body, or a version two streamed
 
167
body.
 
168
 
 
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::
 
174
 
 
175
  STREAMED_BODY := "chunked" NEWLINE CHUNKS TERMINATOR
 
176
  CHUNKS := CHUNK [CHUNKS]
 
177
  CHUNK := CHUNK_LENGTH CHUNK_CONTENT
 
178
  CHUNK_LENGTH := HEX_DIGITS NEWLINE
 
179
  CHUNK_CONTENT := bytes
 
180
  
 
181
  TERMINATOR := SUCCESS_TERMINATOR | ERROR_TERMINATOR
 
182
  SUCCESS_TERMINATOR := 'END' NEWLINE
 
183
  ERROR_TERMINATOR := 'ERR' NEWLINE CHUNKS SUCCESS_TERMINATOR
 
184
 
 
185
That is, the body consists of a series of chunks.  Each chunk starts with
 
186
a length prefix in hexadecimal digits, followed by an ASCII newline byte.
 
187
The end of the body is signaled by '``END\\n``', or by '``ERR\\n``'
 
188
followed by error args, one per chunk.  Note that these args are 8-bit
 
189
safe, unlike request args.
 
190
 
 
191
A streamed body starts with the string "chunked" so that legacy clients
 
192
and servers will not mistake the first chunk as the start of a version one
 
193
body.
 
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.
 
198
 
 
199
Paths
 
200
=====
 
201
 
 
202
Paths are passed across the network.  The client needs to see a namespace
 
203
that includes any repository that might need to be referenced, and the
 
204
client needs to know about a root directory beyond which it cannot ascend.
 
205
 
 
206
Servers run over ssh will typically want to be able to access any path the
 
207
user can access.  Public servers on the other hand (which might be over
 
208
http, ssh or tcp) will typically want to restrict access to only a
 
209
particular directory and its children, so will want to do a software
 
210
virtual root at that level.  In other words they'll want to rewrite
 
211
incoming paths to be under that level (and prevent escaping using ../
 
212
tricks).  The default implementation in bzrlib does this using the
 
213
`bzrlib.transport.chroot` module.
 
214
 
 
215
URLs that include ~ should probably be passed across to the server
 
216
verbatim and the server can expand them.  This will proably not be
 
217
meaningful when limited to a directory?  See `bug 109143`_.
 
218
 
 
219
.. _bug 109143: https://bugs.launchpad.net/bzr/+bug/109143
 
220
 
 
221
 
 
222
Requests
 
223
========
 
224
 
 
225
The first argument of a request specifies the request method.
 
226
 
 
227
The available request methods are registered in `bzrlib.smart.request`.
 
228
 
 
229
**XXX**: ideally the request methods should be documented here.
 
230
Contributions welcome!
 
231
 
 
232
 
 
233
..
 
234
   vim: ft=rst tw=74 ai
 
235