← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/smart/__init__.py

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2009-04-09 20:23:07 UTC
  • mfrom: (4265.1.4 bbc-merge)
  • Revision ID: pqm@pqm.ubuntu.com-20090409202307-n0depb16qepoe21o
(jam) Change _fetch_uses_deltas = False for CHK repos until we can
        write a better fix.

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/smart/__init__.py
12
12
#
13
13
# You should have received a copy of the GNU General Public License
14
14
# along with this program; if not, write to the Free Software
15
 
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
16
16
 
17
17
"""Smart-server protocol, client and server.
18
18
 
20
20
rather than being a single large module.  Refer to the individual module
21
21
docstrings for details.
22
22
 
23
 
Overview
24
 
========
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.
62
 
 
63
 
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,
65
 
sockets and pipes.
66
 
 
67
 
Server-side
68
 
-----------
69
 
 
70
 
 MEDIUM  (factory for protocol, reads bytes & pushes to protocol,
71
 
          uses protocol to detect end-of-request, sends written
72
 
          bytes to client) e.g. socket, pipe, HTTP request handler.
73
 
  ^
74
 
  | bytes.
75
 
  v
76
 
 
77
 
PROTOCOL  (serialization, deserialization)  accepts bytes for one
78
 
          request, decodes according to internal state, pushes
79
 
          structured data to handler.  accepts structured data from
80
 
          handler and encodes and writes to the medium.  factory for
81
 
          handler.
82
 
  ^
83
 
  | structured data
84
 
  v
85
 
 
86
 
HANDLER   (domain logic) accepts structured data, operates state
87
 
          machine until the request can be satisfied,
88
 
          sends structured data to the protocol.
89
 
 
90
 
 
91
 
Client-side
92
 
-----------
93
 
 
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
 
                    ...
103
 
  ^
104
 
  | structured data
105
 
  v
106
 
 
107
 
PROTOCOL  (serialization, deserialization)  accepts structured data for one
108
 
          request, encodes and writes to the medium.  Reads bytes from the
109
 
          medium, decodes and allows the client to read structured data.
110
 
  ^
111
 
  | bytes.
112
 
  v
113
 
 
114
 
 MEDIUM  (accepts bytes from the protocol & delivers to the remote server.
115
 
          Allows the potocol to read bytes e.g. socket, pipe, HTTP request.
 
23
Server-side request handlers are registered in the `bzrlib.smart.request`
 
24
module.
 
25
 
 
26
The domain logic is in `bzrlib.remote`: `RemoteBzrDir`, `RemoteBranch`,
 
27
and so on.
 
28
 
 
29
There is also an plain file-level transport that calls remote methods to
 
30
manipulate files on the server in `bzrlib.transport.remote`.
 
31
 
 
32
The protocol is described in doc/developers/network-protocol.txt.
 
33
 
116
34
"""
117
35
 
118
36
# TODO: _translate_error should be on the client, not the transport because
127
45
# consider how we'll handle error reporting, e.g. if we get halfway through a
128
46
# bulk transfer and then something goes wrong.
129
47
 
130
 
# TODO: Standard marker at start of request/response lines?
131
 
 
132
48
# TODO: Make each request and response self-validatable, e.g. with checksums.
133
49
#
134
50
# TODO: get/put objects could be changed to gradually read back the data as it
155
71
# connection?  Perhaps all Transports should factor out a common connection
156
72
# from the thing that has the directory context?
157
73
#
158
 
# TODO: Pull more things common to sftp and ssh to a higher level.
159
 
#
160
74
# TODO: The server that manages a connection should be quite small and retain
161
75
# minimum state because each of the requests are supposed to be stateless.
162
76
# Then we can write another implementation that maps to http.
168
82
# a particular root directory.  LocalTransport doesn't do anything to stop you
169
83
# ascending above the base directory, so we need to prevent paths
170
84
# containing '..' in either the server or transport layers.  (Also need to
171
 
# consider what happens if someone creates a symlink pointing outside the 
 
85
# consider what happens if someone creates a symlink pointing outside the
172
86
# directory tree...)
173
87
#
174
88
# TODO: Server should rebase absolute paths coming across the network to put
175
89
# them under the virtual root, if one is in use.  LocalTransport currently
176
90
# doesn't do that; if you give it an absolute path it just uses it.
177
 
# 
 
91
#
178
92
# XXX: Arguments can't contain newlines or ascii; possibly we should e.g.
179
93
# urlescape them instead.  Indeed possibly this should just literally be
180
94
# http-over-ssh.
181
95
#
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
96
# TODO: Probably want some way for server commands to gradually produce body
190
97
# data rather than passing it as a string; they could perhaps pass an
191
98
# iterator-like callback that will gradually yield data; it probably needs a
192
99
# 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
 
#
 
100
 
 
101
 
 
102
# Promote some attributes from submodules into this namespace
 
103
from bzrlib.smart.request import SmartServerRequestHandler
 
104
 
 
105