/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 04:43:27 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-20070903044327-25pzbvri48bkg50j
Move HPSS protocol description from bzrlib.smart docstring into doc/developers.

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
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
Request/Response processing
 
82
---------------------------
 
83
 
 
84
On top of the protocol is the logic for processing requests (on the
 
85
server) or responses (on the client).
 
86
 
 
87
Server-side
 
88
-----------
 
89
 
 
90
Sketch::
 
91
 
 
92
 MEDIUM  (factory for protocol, reads bytes & pushes to protocol,
 
93
          uses protocol to detect end-of-request, sends written
 
94
          bytes to client) e.g. socket, pipe, HTTP request handler.
 
95
  ^
 
96
  | bytes.
 
97
  v
 
98
 
 
99
 PROTOCOL(serialization, deserialization)  accepts bytes for one
 
100
          request, decodes according to internal state, pushes
 
101
          structured data to handler.  accepts structured data from
 
102
          handler and encodes and writes to the medium.  factory for
 
103
          handler.
 
104
  ^
 
105
  | structured data
 
106
  v
 
107
 
 
108
 HANDLER  (domain logic) accepts structured data, operates state
 
109
          machine until the request can be satisfied,
 
110
          sends structured data to the protocol.
 
111
 
 
112
Request handlers are registered in the `bzrlib.smart.request` module.
 
113
 
 
114
 
 
115
Client-side
 
116
-----------
 
117
 
 
118
Sketch::
 
119
 
 
120
 CLIENT   domain logic, accepts domain requests, generated structured
 
121
          data, reads structured data from responses and turns into
 
122
          domain data.  Sends structured data to the protocol.
 
123
          Operates state machines until the request can be delivered
 
124
          (e.g. reading from a bundle generated in bzrlib to deliver a
 
125
          complete request).
 
126
 
 
127
          Possibly this should just be RemoteBzrDir, RemoteTransport,
 
128
          ...
 
129
  ^
 
130
  | structured data
 
131
  v
 
132
 
 
133
 PROTOCOL  (serialization, deserialization)  accepts structured data for one
 
134
          request, encodes and writes to the medium.  Reads bytes from the
 
135
          medium, decodes and allows the client to read structured data.
 
136
  ^
 
137
  | bytes.
 
138
  v
 
139
 
 
140
 MEDIUM  (accepts bytes from the protocol & delivers to the remote server.
 
141
          Allows the potocol to read bytes e.g. socket, pipe, HTTP request.
 
142
 
 
143
The domain logic is in `bzrlib.remote`: `RemoteBzrDir`, `RemoteBranch`,
 
144
and so on.
 
145
 
 
146
There is also an plain file-level transport that calls remote methods to
 
147
manipulate files on the server in `bzrlib.transport.remote`.
 
148
 
 
149
Paths
 
150
=====
 
151
 
 
152
Paths are passed across the network.  The client needs to see a namespace
 
153
that includes any repository that might need to be referenced, and the
 
154
client needs to know about a root directory beyond which it cannot ascend.
 
155
 
 
156
Servers run over ssh will typically want to be able to access any path the
 
157
user can access.  Public servers on the other hand (which might be over
 
158
http, ssh or tcp) will typically want to restrict access to only a
 
159
particular directory and its children, so will want to do a software
 
160
virtual root at that level.  In other words they'll want to rewrite
 
161
incoming paths to be under that level (and prevent escaping using ../
 
162
tricks.)
 
163
 
 
164
URLs that include ~ should probably be passed across to the server
 
165
verbatim and the server can expand them.  This will proably not be
 
166
meaningful when limited to a directory?
 
167
 
 
168
 
 
169
..
 
170
   vim: ft=rst tw=74 ai
 
171