/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/request.py

  • Committer: mernst at mit
  • Date: 2008-10-16 10:57:16 UTC
  • mto: This revision was merged to the branch mainline in revision 3799.
  • Revision ID: mernst@csail.mit.edu-20081016105716-v8x8n5t2pf7f6uds
Improved documentation of stacked and lightweight branches

These patches improve the User Guide's documentation of stacked and
lightweight branches.

Section "1.2.6 Putting the concepts together" should mention stacked
branches and the difference between them and lightweight branches.  It
should also contain links to further details of the common scenarios.

Section "5.3.4 Getting a lightweight checkout" should mention stacked
branches as an option, and should link to all the options, not just some of
them.  It should also clarify that lightweight only applies to checkouts,
not to arbitrary branches.

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/smart/request.py
 
1
# Copyright (C) 2006, 2007 Canonical Ltd
 
2
#
 
3
# This program is free software; you can redistribute it and/or modify
 
4
# it under the terms of the GNU General Public License as published by
 
5
# the Free Software Foundation; either version 2 of the License, or
 
6
# (at your option) any later version.
 
7
#
 
8
# This program is distributed in the hope that it will be useful,
 
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
 
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
11
# GNU General Public License for more details.
 
12
#
 
13
# You should have received a copy of the GNU General Public License
 
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
 
16
 
 
17
"""Basic server-side logic for dealing with requests.
 
18
 
 
19
**XXX**:
 
20
 
 
21
The class names are a little confusing: the protocol will instantiate a
 
22
SmartServerRequestHandler, whose dispatch_command method creates an instance of
 
23
a SmartServerRequest subclass.
 
24
 
 
25
The request_handlers registry tracks SmartServerRequest classes (rather than
 
26
SmartServerRequestHandler).
 
27
"""
 
28
 
 
29
import tempfile
 
30
 
 
31
from bzrlib import (
 
32
    bzrdir,
 
33
    errors,
 
34
    registry,
 
35
    revision,
 
36
    urlutils,
 
37
    )
 
38
from bzrlib.lazy_import import lazy_import
 
39
lazy_import(globals(), """
 
40
from bzrlib.bundle import serializer
 
41
""")
 
42
 
 
43
 
 
44
class SmartServerRequest(object):
 
45
    """Base class for request handlers.
 
46
    
 
47
    To define a new request, subclass this class and override the `do` method
 
48
    (and if appropriate, `do_body` as well).  Request implementors should take
 
49
    care to call `translate_client_path` and `transport_from_client_path` as
 
50
    appropriate when dealing with paths received from the client.
 
51
    """
 
52
    # XXX: rename this class to BaseSmartServerRequestHandler ?  A request
 
53
    # *handler* is a different concept to the request.
 
54
 
 
55
    def __init__(self, backing_transport, root_client_path='/'):
 
56
        """Constructor.
 
57
 
 
58
        :param backing_transport: the base transport to be used when performing
 
59
            this request.
 
60
        :param root_client_path: the client path that maps to the root of
 
61
            backing_transport.  This is used to interpret relpaths received
 
62
            from the client.  Clients will not be able to refer to paths above
 
63
            this root.  If root_client_path is None, then no translation will
 
64
            be performed on client paths.  Default is '/'.
 
65
        """
 
66
        self._backing_transport = backing_transport
 
67
        if root_client_path is not None:
 
68
            if not root_client_path.startswith('/'):
 
69
                root_client_path = '/' + root_client_path
 
70
            if not root_client_path.endswith('/'):
 
71
                root_client_path += '/'
 
72
        self._root_client_path = root_client_path
 
73
 
 
74
    def _check_enabled(self):
 
75
        """Raises DisabledMethod if this method is disabled."""
 
76
        pass
 
77
 
 
78
    def do(self, *args):
 
79
        """Mandatory extension point for SmartServerRequest subclasses.
 
80
        
 
81
        Subclasses must implement this.
 
82
        
 
83
        This should return a SmartServerResponse if this command expects to
 
84
        receive no body.
 
85
        """
 
86
        raise NotImplementedError(self.do)
 
87
 
 
88
    def execute(self, *args):
 
89
        """Public entry point to execute this request.
 
90
 
 
91
        It will return a SmartServerResponse if the command does not expect a
 
92
        body.
 
93
 
 
94
        :param *args: the arguments of the request.
 
95
        """
 
96
        self._check_enabled()
 
97
        return self.do(*args)
 
98
 
 
99
    def do_body(self, body_bytes):
 
100
        """Called if the client sends a body with the request.
 
101
 
 
102
        The do() method is still called, and must have returned None.
 
103
        
 
104
        Must return a SmartServerResponse.
 
105
        """
 
106
        raise NotImplementedError(self.do_body)
 
107
 
 
108
    def do_chunk(self, chunk_bytes):
 
109
        """Called with each body chunk if the request has a streamed body.
 
110
 
 
111
        The do() method is still called, and must have returned None.
 
112
        """
 
113
        raise NotImplementedError(self.do_chunk)
 
114
 
 
115
    def do_end(self):
 
116
        """Called when the end of the request has been received."""
 
117
        pass
 
118
    
 
119
    def translate_client_path(self, client_path):
 
120
        """Translate a path received from a network client into a local
 
121
        relpath.
 
122
 
 
123
        All paths received from the client *must* be translated.
 
124
 
 
125
        :param client_path: the path from the client.
 
126
        :returns: a relpath that may be used with self._backing_transport
 
127
            (unlike the untranslated client_path, which must not be used with
 
128
            the backing transport).
 
129
        """
 
130
        if self._root_client_path is None:
 
131
            # no translation necessary!
 
132
            return client_path
 
133
        if not client_path.startswith('/'):
 
134
            client_path = '/' + client_path
 
135
        if client_path.startswith(self._root_client_path):
 
136
            path = client_path[len(self._root_client_path):]
 
137
            relpath = urlutils.joinpath('/', path)
 
138
            if not relpath.startswith('/'):
 
139
                raise ValueError(relpath)
 
140
            return '.' + relpath
 
141
        else:
 
142
            raise errors.PathNotChild(client_path, self._root_client_path)
 
143
 
 
144
    def transport_from_client_path(self, client_path):
 
145
        """Get a backing transport corresponding to the location referred to by
 
146
        a network client.
 
147
 
 
148
        :seealso: translate_client_path
 
149
        :returns: a transport cloned from self._backing_transport
 
150
        """
 
151
        relpath = self.translate_client_path(client_path)
 
152
        return self._backing_transport.clone(relpath)
 
153
 
 
154
 
 
155
class SmartServerResponse(object):
 
156
    """A response to a client request.
 
157
    
 
158
    This base class should not be used. Instead use
 
159
    SuccessfulSmartServerResponse and FailedSmartServerResponse as appropriate.
 
160
    """
 
161
 
 
162
    def __init__(self, args, body=None, body_stream=None):
 
163
        """Constructor.
 
164
 
 
165
        :param args: tuple of response arguments.
 
166
        :param body: string of a response body.
 
167
        :param body_stream: iterable of bytestrings to be streamed to the
 
168
            client.
 
169
        """
 
170
        self.args = args
 
171
        if body is not None and body_stream is not None:
 
172
            raise errors.BzrError(
 
173
                "'body' and 'body_stream' are mutually exclusive.")
 
174
        self.body = body
 
175
        self.body_stream = body_stream
 
176
 
 
177
    def __eq__(self, other):
 
178
        if other is None:
 
179
            return False
 
180
        return (other.args == self.args and
 
181
                other.body == self.body and
 
182
                other.body_stream is self.body_stream)
 
183
 
 
184
    def __repr__(self):
 
185
        return "<%s args=%r body=%r>" % (self.__class__.__name__,
 
186
            self.args, self.body)
 
187
 
 
188
 
 
189
class FailedSmartServerResponse(SmartServerResponse):
 
190
    """A SmartServerResponse for a request which failed."""
 
191
 
 
192
    def is_successful(self):
 
193
        """FailedSmartServerResponse are not successful."""
 
194
        return False
 
195
 
 
196
 
 
197
class SuccessfulSmartServerResponse(SmartServerResponse):
 
198
    """A SmartServerResponse for a successfully completed request."""
 
199
 
 
200
    def is_successful(self):
 
201
        """SuccessfulSmartServerResponse are successful."""
 
202
        return True
 
203
 
 
204
 
 
205
class SmartServerRequestHandler(object):
 
206
    """Protocol logic for smart server.
 
207
    
 
208
    This doesn't handle serialization at all, it just processes requests and
 
209
    creates responses.
 
210
    """
 
211
 
 
212
    # IMPORTANT FOR IMPLEMENTORS: It is important that SmartServerRequestHandler
 
213
    # not contain encoding or decoding logic to allow the wire protocol to vary
 
214
    # from the object protocol: we will want to tweak the wire protocol separate
 
215
    # from the object model, and ideally we will be able to do that without
 
216
    # having a SmartServerRequestHandler subclass for each wire protocol, rather
 
217
    # just a Protocol subclass.
 
218
 
 
219
    # TODO: Better way of representing the body for commands that take it,
 
220
    # and allow it to be streamed into the server.
 
221
 
 
222
    def __init__(self, backing_transport, commands, root_client_path):
 
223
        """Constructor.
 
224
 
 
225
        :param backing_transport: a Transport to handle requests for.
 
226
        :param commands: a registry mapping command names to SmartServerRequest
 
227
            subclasses. e.g. bzrlib.transport.smart.vfs.vfs_commands.
 
228
        """
 
229
        self._backing_transport = backing_transport
 
230
        self._root_client_path = root_client_path
 
231
        self._commands = commands
 
232
        self._body_bytes = ''
 
233
        self.response = None
 
234
        self.finished_reading = False
 
235
        self._command = None
 
236
 
 
237
    def accept_body(self, bytes):
 
238
        """Accept body data."""
 
239
 
 
240
        # TODO: This should be overriden for each command that desired body data
 
241
        # to handle the right format of that data, i.e. plain bytes, a bundle,
 
242
        # etc.  The deserialisation into that format should be done in the
 
243
        # Protocol object.
 
244
 
 
245
        # default fallback is to accumulate bytes.
 
246
        self._body_bytes += bytes
 
247
        
 
248
    def end_of_body(self):
 
249
        """No more body data will be received."""
 
250
        self._run_handler_code(self._command.do_body, (self._body_bytes,), {})
 
251
        # cannot read after this.
 
252
        self.finished_reading = True
 
253
 
 
254
    def dispatch_command(self, cmd, args):
 
255
        """Deprecated compatibility method.""" # XXX XXX
 
256
        try:
 
257
            command = self._commands.get(cmd)
 
258
        except LookupError:
 
259
            raise errors.UnknownSmartMethod(cmd)
 
260
        self._command = command(self._backing_transport, self._root_client_path)
 
261
        self._run_handler_code(self._command.execute, args, {})
 
262
 
 
263
    def _run_handler_code(self, callable, args, kwargs):
 
264
        """Run some handler specific code 'callable'.
 
265
 
 
266
        If a result is returned, it is considered to be the commands response,
 
267
        and finished_reading is set true, and its assigned to self.response.
 
268
 
 
269
        Any exceptions caught are translated and a response object created
 
270
        from them.
 
271
        """
 
272
        result = self._call_converting_errors(callable, args, kwargs)
 
273
 
 
274
        if result is not None:
 
275
            self.response = result
 
276
            self.finished_reading = True
 
277
 
 
278
    def _call_converting_errors(self, callable, args, kwargs):
 
279
        """Call callable converting errors to Response objects."""
 
280
        # XXX: most of this error conversion is VFS-related, and thus ought to
 
281
        # be in SmartServerVFSRequestHandler somewhere.
 
282
        try:
 
283
            return callable(*args, **kwargs)
 
284
        except errors.NoSuchFile, e:
 
285
            return FailedSmartServerResponse(('NoSuchFile', e.path))
 
286
        except errors.FileExists, e:
 
287
            return FailedSmartServerResponse(('FileExists', e.path))
 
288
        except errors.DirectoryNotEmpty, e:
 
289
            return FailedSmartServerResponse(('DirectoryNotEmpty', e.path))
 
290
        except errors.ShortReadvError, e:
 
291
            return FailedSmartServerResponse(('ShortReadvError',
 
292
                e.path, str(e.offset), str(e.length), str(e.actual)))
 
293
        except errors.UnstackableRepositoryFormat, e:
 
294
            return FailedSmartServerResponse(('UnstackableRepositoryFormat',
 
295
                str(e.format), e.url))
 
296
        except errors.UnstackableBranchFormat, e:
 
297
            return FailedSmartServerResponse(('UnstackableBranchFormat',
 
298
                str(e.format), e.url))
 
299
        except errors.NotStacked, e:
 
300
            return FailedSmartServerResponse(('NotStacked',))
 
301
        except UnicodeError, e:
 
302
            # If it is a DecodeError, than most likely we are starting
 
303
            # with a plain string
 
304
            str_or_unicode = e.object
 
305
            if isinstance(str_or_unicode, unicode):
 
306
                # XXX: UTF-8 might have \x01 (our seperator byte) in it.  We
 
307
                # should escape it somehow.
 
308
                val = 'u:' + str_or_unicode.encode('utf-8')
 
309
            else:
 
310
                val = 's:' + str_or_unicode.encode('base64')
 
311
            # This handles UnicodeEncodeError or UnicodeDecodeError
 
312
            return FailedSmartServerResponse((e.__class__.__name__,
 
313
                    e.encoding, val, str(e.start), str(e.end), e.reason))
 
314
        except errors.TransportNotPossible, e:
 
315
            if e.msg == "readonly transport":
 
316
                return FailedSmartServerResponse(('ReadOnlyError', ))
 
317
            else:
 
318
                raise
 
319
 
 
320
    def headers_received(self, headers):
 
321
        # Just a no-op at the moment.
 
322
        pass
 
323
 
 
324
    def args_received(self, args):
 
325
        cmd = args[0]
 
326
        args = args[1:]
 
327
        try:
 
328
            command = self._commands.get(cmd)
 
329
        except LookupError:
 
330
            raise errors.UnknownSmartMethod(cmd)
 
331
        self._command = command(self._backing_transport)
 
332
        self._run_handler_code(self._command.execute, args, {})
 
333
 
 
334
    def prefixed_body_received(self, body_bytes):
 
335
        """No more body data will be received."""
 
336
        self._run_handler_code(self._command.do_body, (body_bytes,), {})
 
337
        # cannot read after this.
 
338
        self.finished_reading = True
 
339
 
 
340
    def body_chunk_received(self, chunk_bytes):
 
341
        self._run_handler_code(self._command.do_chunk, (chunk_bytes,), {})
 
342
 
 
343
    def end_received(self):
 
344
        self._run_handler_code(self._command.do_end, (), {})
 
345
 
 
346
 
 
347
class HelloRequest(SmartServerRequest):
 
348
    """Answer a version request with the highest protocol version this server
 
349
    supports.
 
350
    """
 
351
 
 
352
    def do(self):
 
353
        return SuccessfulSmartServerResponse(('ok', '2'))
 
354
 
 
355
 
 
356
class GetBundleRequest(SmartServerRequest):
 
357
    """Get a bundle of from the null revision to the specified revision."""
 
358
 
 
359
    def do(self, path, revision_id):
 
360
        # open transport relative to our base
 
361
        t = self.transport_from_client_path(path)
 
362
        control, extra_path = bzrdir.BzrDir.open_containing_from_transport(t)
 
363
        repo = control.open_repository()
 
364
        tmpf = tempfile.TemporaryFile()
 
365
        base_revision = revision.NULL_REVISION
 
366
        serializer.write_bundle(repo, revision_id, base_revision, tmpf)
 
367
        tmpf.seek(0)
 
368
        return SuccessfulSmartServerResponse((), tmpf.read())
 
369
 
 
370
 
 
371
class SmartServerIsReadonly(SmartServerRequest):
 
372
    # XXX: this request method belongs somewhere else.
 
373
 
 
374
    def do(self):
 
375
        if self._backing_transport.is_readonly():
 
376
            answer = 'yes'
 
377
        else:
 
378
            answer = 'no'
 
379
        return SuccessfulSmartServerResponse((answer,))
 
380
 
 
381
 
 
382
request_handlers = registry.Registry()
 
383
request_handlers.register_lazy(
 
384
    'append', 'bzrlib.smart.vfs', 'AppendRequest')
 
385
request_handlers.register_lazy(
 
386
    'Branch.get_config_file', 'bzrlib.smart.branch', 'SmartServerBranchGetConfigFile')
 
387
request_handlers.register_lazy(
 
388
    'Branch.get_stacked_on_url', 'bzrlib.smart.branch', 'SmartServerBranchRequestGetStackedOnURL')
 
389
request_handlers.register_lazy(
 
390
    'Branch.last_revision_info', 'bzrlib.smart.branch', 'SmartServerBranchRequestLastRevisionInfo')
 
391
request_handlers.register_lazy(
 
392
    'Branch.lock_write', 'bzrlib.smart.branch', 'SmartServerBranchRequestLockWrite')
 
393
request_handlers.register_lazy(
 
394
    'Branch.revision_history', 'bzrlib.smart.branch', 'SmartServerRequestRevisionHistory')
 
395
request_handlers.register_lazy(
 
396
    'Branch.set_last_revision', 'bzrlib.smart.branch', 'SmartServerBranchRequestSetLastRevision')
 
397
request_handlers.register_lazy(
 
398
    'Branch.set_last_revision_info', 'bzrlib.smart.branch',
 
399
    'SmartServerBranchRequestSetLastRevisionInfo')
 
400
request_handlers.register_lazy(
 
401
    'Branch.set_last_revision_ex', 'bzrlib.smart.branch',
 
402
    'SmartServerBranchRequestSetLastRevisionEx')
 
403
request_handlers.register_lazy(
 
404
    'Branch.unlock', 'bzrlib.smart.branch', 'SmartServerBranchRequestUnlock')
 
405
request_handlers.register_lazy(
 
406
    'BzrDir.find_repository', 'bzrlib.smart.bzrdir', 'SmartServerRequestFindRepositoryV1')
 
407
request_handlers.register_lazy(
 
408
    'BzrDir.find_repositoryV2', 'bzrlib.smart.bzrdir', 'SmartServerRequestFindRepositoryV2')
 
409
request_handlers.register_lazy(
 
410
    'BzrDirFormat.initialize', 'bzrlib.smart.bzrdir', 'SmartServerRequestInitializeBzrDir')
 
411
request_handlers.register_lazy(
 
412
    'BzrDir.open_branch', 'bzrlib.smart.bzrdir', 'SmartServerRequestOpenBranch')
 
413
request_handlers.register_lazy(
 
414
    'delete', 'bzrlib.smart.vfs', 'DeleteRequest')
 
415
request_handlers.register_lazy(
 
416
    'get', 'bzrlib.smart.vfs', 'GetRequest')
 
417
request_handlers.register_lazy(
 
418
    'get_bundle', 'bzrlib.smart.request', 'GetBundleRequest')
 
419
request_handlers.register_lazy(
 
420
    'has', 'bzrlib.smart.vfs', 'HasRequest')
 
421
request_handlers.register_lazy(
 
422
    'hello', 'bzrlib.smart.request', 'HelloRequest')
 
423
request_handlers.register_lazy(
 
424
    'iter_files_recursive', 'bzrlib.smart.vfs', 'IterFilesRecursiveRequest')
 
425
request_handlers.register_lazy(
 
426
    'list_dir', 'bzrlib.smart.vfs', 'ListDirRequest')
 
427
request_handlers.register_lazy(
 
428
    'mkdir', 'bzrlib.smart.vfs', 'MkdirRequest')
 
429
request_handlers.register_lazy(
 
430
    'move', 'bzrlib.smart.vfs', 'MoveRequest')
 
431
request_handlers.register_lazy(
 
432
    'put', 'bzrlib.smart.vfs', 'PutRequest')
 
433
request_handlers.register_lazy(
 
434
    'put_non_atomic', 'bzrlib.smart.vfs', 'PutNonAtomicRequest')
 
435
request_handlers.register_lazy(
 
436
    'readv', 'bzrlib.smart.vfs', 'ReadvRequest')
 
437
request_handlers.register_lazy(
 
438
    'rename', 'bzrlib.smart.vfs', 'RenameRequest')
 
439
request_handlers.register_lazy('Repository.gather_stats',
 
440
                               'bzrlib.smart.repository',
 
441
                               'SmartServerRepositoryGatherStats')
 
442
request_handlers.register_lazy('Repository.get_parent_map',
 
443
                               'bzrlib.smart.repository',
 
444
                               'SmartServerRepositoryGetParentMap')
 
445
request_handlers.register_lazy(
 
446
    'Repository.get_revision_graph', 'bzrlib.smart.repository', 'SmartServerRepositoryGetRevisionGraph')
 
447
request_handlers.register_lazy(
 
448
    'Repository.has_revision', 'bzrlib.smart.repository', 'SmartServerRequestHasRevision')
 
449
request_handlers.register_lazy(
 
450
    'Repository.is_shared', 'bzrlib.smart.repository', 'SmartServerRepositoryIsShared')
 
451
request_handlers.register_lazy(
 
452
    'Repository.lock_write', 'bzrlib.smart.repository', 'SmartServerRepositoryLockWrite')
 
453
request_handlers.register_lazy(
 
454
    'Repository.unlock', 'bzrlib.smart.repository', 'SmartServerRepositoryUnlock')
 
455
request_handlers.register_lazy(
 
456
    'Repository.tarball', 'bzrlib.smart.repository',
 
457
    'SmartServerRepositoryTarball')
 
458
request_handlers.register_lazy(
 
459
    'rmdir', 'bzrlib.smart.vfs', 'RmdirRequest')
 
460
request_handlers.register_lazy(
 
461
    'stat', 'bzrlib.smart.vfs', 'StatRequest')
 
462
request_handlers.register_lazy(
 
463
    'Transport.is_readonly', 'bzrlib.smart.request', 'SmartServerIsReadonly')
 
464
request_handlers.register_lazy(
 
465
    'BzrDir.open', 'bzrlib.smart.bzrdir', 'SmartServerRequestOpenBzrDir')