/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 bzrlib/smart/__init__.py

  • Committer: Andrew Bennetts
  • Date: 2007-04-25 05:40:02 UTC
  • mto: This revision was merged to the branch mainline in revision 2459.
  • Revision ID: andrew.bennetts@canonical.com-20070425054002-08sj7lxphtpb6ewm
NEWS entry, greatly improved docstring in bzrlib.smart.

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/smart/__init__.py
23
23
Overview
24
24
========
25
25
 
26
 
Requests are sent as a command and list of arguments, followed by optional
27
 
bulk body data.  Responses are similarly a response and list of arguments,
28
 
followed by bulk body data. ::
29
 
 
30
 
  SEP := '\001'
31
 
    Fields are separated by Ctrl-A.
32
 
  BULK_DATA := CHUNK TRAILER
33
 
    Chunks can be repeated as many times as necessary.
34
 
  CHUNK := CHUNK_LEN CHUNK_BODY
35
 
  CHUNK_LEN := DIGIT+ NEWLINE
36
 
    Gives the number of bytes in the following chunk.
37
 
  CHUNK_BODY := BYTE[chunk_len]
38
 
  TRAILER := SUCCESS_TRAILER | ERROR_TRAILER
39
 
  SUCCESS_TRAILER := 'done' NEWLINE
40
 
  ERROR_TRAILER := 
41
 
 
42
 
Paths are passed across the network.  The client needs to see a namespace that
43
 
includes any repository that might need to be referenced, and the client needs
44
 
to know about a root directory beyond which it cannot ascend.
45
 
 
46
 
Servers run over ssh will typically want to be able to access any path the user 
47
 
can access.  Public servers on the other hand (which might be over http, ssh
48
 
or tcp) will typically want to restrict access to only a particular directory 
49
 
and its children, so will want to do a software virtual root at that level.
50
 
In other words they'll want to rewrite incoming paths to be under that level
51
 
(and prevent escaping using ../ tricks.)
52
 
 
53
 
URLs that include ~ should probably be passed across to the server verbatim
54
 
and the server can expand them.  This will proably not be meaningful when 
55
 
limited to a directory?
56
 
 
57
 
At the bottom level socket, pipes, HTTP server.  For sockets, we have the idea
58
 
that you have multiple requests and get a read error because the other side did
59
 
shutdown.  For pipes we have read pipe which will have a zero read which marks
60
 
end-of-file.  For HTTP server environment there is not end-of-stream because
61
 
each request coming into the server is independent.
 
26
The smart protocol provides a way to send a requests and corresponding
 
27
responses to communicate with a remote bzr process.
 
28
 
 
29
Layering
 
30
========
 
31
 
 
32
Medium
 
33
------
 
34
 
 
35
At the bottom level there is either a socket, pipes, or an HTTP
 
36
request/response.  We call this layer the *medium*.  It is responsible for
 
37
carrying bytes between a client and server.  For sockets, we have the
 
38
idea that you have multiple requests and get a read error because the other side
 
39
did shutdown.  For pipes we have read pipe which will have a zero read which
 
40
marks end-of-file.  For HTTP server environment there is no end-of-stream
 
41
because each request coming into the server is independent.
62
42
 
63
43
So we need a wrapper around pipes and sockets to seperate out requests from
64
 
substrate and this will give us a single model which is consist for HTTP,
 
44
substrate and this will give us a single model which is consistent for HTTP,
65
45
sockets and pipes.
66
46
 
 
47
Protocol
 
48
--------
 
49
 
 
50
On top of the medium is the *protocol*.  This is the layer that deserialises
 
51
bytes into the structured data that requests and responses consist of.
 
52
 
 
53
Version one of the protocol (for requests and responses) is described by::
 
54
 
 
55
  REQUEST := MESSAGE_V1
 
56
  RESPONSE := MESSAGE_V1
 
57
  MESSAGE_V1 := ARGS BODY
 
58
 
 
59
  ARGS := ARG [MORE_ARGS] NEWLINE
 
60
  MORE_ARGS := SEP ARG [MORE_ARGS]
 
61
  SEP := 0x01
 
62
 
 
63
  BODY := LENGTH NEWLINE BODY_BYTES TRAILER
 
64
  LENGTH := decimal integer
 
65
  TRAILER := "done" NEWLINE
 
66
 
 
67
That is, a tuple of arguments separated by Ctrl-A and terminated with a newline,
 
68
followed by length prefixed body with a constant trailer.  Note that although
 
69
arguments are not 8-bit safe (they cannot include 0x01 or 0x0a bytes without
 
70
breaking the protocol encoding), the body is.
 
71
 
 
72
Version two of the request protocol is::
 
73
 
 
74
  REQUEST_V2 := "bzr request 2" NEWLINE MESSAGE_V1
 
75
 
 
76
Version two of the response protocol is::
 
77
 
 
78
  RESPONSE_V2 := "bzr request 2" NEWLINE MESSAGE_V1
 
79
 
 
80
Future versions should follow this structure, like version two does::
 
81
 
 
82
  FUTURE_MESSAGE := VERSION_STRING NEWLINE REST_OF_MESSAGE
 
83
 
 
84
This is that clients and servers can read bytes up to the first newline byte to
 
85
determine what version a message is.
 
86
 
 
87
Request/Response processing
 
88
---------------------------
 
89
 
 
90
On top of the protocol is the logic for processing requests (on the server) or
 
91
responses (on the client).
 
92
 
67
93
Server-side
68
94
-----------
69
95
 
 
96
Sketch::
 
97
 
70
98
 MEDIUM  (factory for protocol, reads bytes & pushes to protocol,
71
99
          uses protocol to detect end-of-request, sends written
72
100
          bytes to client) e.g. socket, pipe, HTTP request handler.
74
102
  | bytes.
75
103
  v
76
104
 
77
 
PROTOCOL  (serialization, deserialization)  accepts bytes for one
 
105
 PROTOCOL(serialization, deserialization)  accepts bytes for one
78
106
          request, decodes according to internal state, pushes
79
107
          structured data to handler.  accepts structured data from
80
108
          handler and encodes and writes to the medium.  factory for
83
111
  | structured data
84
112
  v
85
113
 
86
 
HANDLER   (domain logic) accepts structured data, operates state
 
114
 HANDLER  (domain logic) accepts structured data, operates state
87
115
          machine until the request can be satisfied,
88
116
          sends structured data to the protocol.
89
117
 
 
118
Request handlers are registered in `bzrlib.smart.request`.
 
119
 
90
120
 
91
121
Client-side
92
122
-----------
93
123
 
94
 
 CLIENT             domain logic, accepts domain requests, generated structured
95
 
                    data, reads structured data from responses and turns into
96
 
                    domain data.  Sends structured data to the protocol.
97
 
                    Operates state machines until the request can be delivered
98
 
                    (e.g. reading from a bundle generated in bzrlib to deliver a
99
 
                    complete request).
100
 
 
101
 
                    Possibly this should just be RemoteBzrDir, RemoteTransport,
102
 
                    ...
 
124
Sketch::
 
125
 
 
126
 CLIENT   domain logic, accepts domain requests, generated structured
 
127
          data, reads structured data from responses and turns into
 
128
          domain data.  Sends structured data to the protocol.
 
129
          Operates state machines until the request can be delivered
 
130
          (e.g. reading from a bundle generated in bzrlib to deliver a
 
131
          complete request).
 
132
 
 
133
          Possibly this should just be RemoteBzrDir, RemoteTransport,
 
134
          ...
103
135
  ^
104
136
  | structured data
105
137
  v
113
145
 
114
146
 MEDIUM  (accepts bytes from the protocol & delivers to the remote server.
115
147
          Allows the potocol to read bytes e.g. socket, pipe, HTTP request.
 
148
 
 
149
The domain logic is in `bzrlib.remote`: `RemoteBzrDir`, `RemoteBranch`, and so
 
150
on.
 
151
 
 
152
There is also an plain file-level transport that calls remote methods to
 
153
manipulate files on the server in `bzrlib.transport.remote`.
 
154
 
 
155
Paths
 
156
=====
 
157
 
 
158
Paths are passed across the network.  The client needs to see a namespace that
 
159
includes any repository that might need to be referenced, and the client needs
 
160
to know about a root directory beyond which it cannot ascend.
 
161
 
 
162
Servers run over ssh will typically want to be able to access any path the user
 
163
can access.  Public servers on the other hand (which might be over http, ssh
 
164
or tcp) will typically want to restrict access to only a particular directory
 
165
and its children, so will want to do a software virtual root at that level.
 
166
In other words they'll want to rewrite incoming paths to be under that level
 
167
(and prevent escaping using ../ tricks.)
 
168
 
 
169
URLs that include ~ should probably be passed across to the server verbatim
 
170
and the server can expand them.  This will proably not be meaningful when
 
171
limited to a directory?
116
172
"""
117
173
 
118
174
# TODO: _translate_error should be on the client, not the transport because
127
183
# consider how we'll handle error reporting, e.g. if we get halfway through a
128
184
# bulk transfer and then something goes wrong.
129
185
 
130
 
# TODO: Standard marker at start of request/response lines?
131
 
 
132
186
# TODO: Make each request and response self-validatable, e.g. with checksums.
133
187
#
134
188
# TODO: get/put objects could be changed to gradually read back the data as it
155
209
# connection?  Perhaps all Transports should factor out a common connection
156
210
# from the thing that has the directory context?
157
211
#
158
 
# TODO: Pull more things common to sftp and ssh to a higher level.
159
 
#
160
212
# TODO: The server that manages a connection should be quite small and retain
161
213
# minimum state because each of the requests are supposed to be stateless.
162
214
# Then we can write another implementation that maps to http.
179
231
# urlescape them instead.  Indeed possibly this should just literally be
180
232
# http-over-ssh.
181
233
#
182
 
# FIXME: This transport, with several others, has imperfect handling of paths
183
 
# within urls.  It'd probably be better for ".." from a root to raise an error
184
 
# rather than return the same directory as we do at present.
185
 
#
186
 
# TODO: Rather than working at the Transport layer we want a Branch,
187
 
# Repository or BzrDir objects that talk to a server.
188
 
#
189
234
# TODO: Probably want some way for server commands to gradually produce body
190
235
# data rather than passing it as a string; they could perhaps pass an
191
236
# iterator-like callback that will gradually yield data; it probably needs a
192
237
# close() method that will always be closed to do any necessary cleanup.
193
 
#
194
 
# TODO: Split the actual smart server from the ssh encoding of it.
195
 
#
196
 
# TODO: Perhaps support file-level readwrite operations over the transport
197
 
# too.
198
 
#
199
 
# TODO: SmartBzrDir class, proxying all Branch etc methods across to another
200
 
# branch doing file-level operations.
201
 
#
202
238
 
203
239
 
204
240
# Promote some attributes from submodules into this namespace