/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

Merge from hpss-protocol-docs.

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
          Possibly this should just be RemoteBzrDir, RemoteTransport,
 
89
          ...
 
90
  ^
 
91
  | structured data
 
92
  v
 
93
 
 
94
 PROTOCOL  (serialization, deserialization)  accepts structured data for one
 
95
          request, encodes and writes to the medium.  Reads bytes from the
 
96
          medium, decodes and allows the client to read structured data.
 
97
  ^
 
98
  | bytes.
 
99
  v
 
100
 
 
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.
 
103
 
 
104
The domain logic is in `bzrlib.remote`: `RemoteBzrDir`, `RemoteBranch`,
 
105
and so on.
 
106
 
 
107
There is also an plain file-level transport that calls remote methods to
 
108
manipulate files on the server in `bzrlib.transport.remote`.
 
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
 
 
196
Paths
 
197
=====
 
198
 
 
199
Paths are passed across the network.  The client needs to see a namespace
 
200
that includes any repository that might need to be referenced, and the
 
201
client needs to know about a root directory beyond which it cannot ascend.
 
202
 
 
203
Servers run over ssh will typically want to be able to access any path the
 
204
user can access.  Public servers on the other hand (which might be over
 
205
http, ssh or tcp) will typically want to restrict access to only a
 
206
particular directory and its children, so will want to do a software
 
207
virtual root at that level.  In other words they'll want to rewrite
 
208
incoming paths to be under that level (and prevent escaping using ../
 
209
tricks.)
 
210
 
 
211
URLs that include ~ should probably be passed across to the server
 
212
verbatim and the server can expand them.  This will proably not be
 
213
meaningful when limited to a directory?
 
214
 
 
215
 
 
216
Requests
 
217
========
 
218
 
 
219
The available request methods are registered in `bzrlib.smart.request`.
 
220
 
 
221
..
 
222
   vim: ft=rst tw=74 ai
 
223