← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/smart/__init__.py

Merge latest chunking protocol, including support for errors, fixing a test failure.

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/smart/__init__.py
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
 
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.
42
 
 
43
 
So we need a wrapper around pipes and sockets to seperate out requests from
44
 
substrate and this will give us a single model which is consistent for HTTP,
45
 
sockets and pipes.
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
 
For compatibility will all versions (past and future) of bzr clients, servers
88
 
that receive a request in an unknown protocol version should respond with a
89
 
single-line error terminated with 0x0a (NEWLINE), rather than structured
90
 
response prefixed with a version string.
91
 
 
92
 
Request/Response processing
93
 
---------------------------
94
 
 
95
 
On top of the protocol is the logic for processing requests (on the server) or
96
 
responses (on the client).
97
 
 
98
 
Server-side
99
 
-----------
100
 
 
101
 
Sketch::
102
 
 
103
 
 MEDIUM  (factory for protocol, reads bytes & pushes to protocol,
104
 
          uses protocol to detect end-of-request, sends written
105
 
          bytes to client) e.g. socket, pipe, HTTP request handler.
106
 
  ^
107
 
  | bytes.
108
 
  v
109
 
 
110
 
 PROTOCOL(serialization, deserialization)  accepts bytes for one
111
 
          request, decodes according to internal state, pushes
112
 
          structured data to handler.  accepts structured data from
113
 
          handler and encodes and writes to the medium.  factory for
114
 
          handler.
115
 
  ^
116
 
  | structured data
117
 
  v
118
 
 
119
 
 HANDLER  (domain logic) accepts structured data, operates state
120
 
          machine until the request can be satisfied,
121
 
          sends structured data to the protocol.
122
 
 
123
 
Request handlers are registered in `bzrlib.smart.request`.
124
 
 
125
 
 
126
 
Client-side
127
 
-----------
128
 
 
129
 
Sketch::
130
 
 
131
 
 CLIENT   domain logic, accepts domain requests, generated structured
132
 
          data, reads structured data from responses and turns into
133
 
          domain data.  Sends structured data to the protocol.
134
 
          Operates state machines until the request can be delivered
135
 
          (e.g. reading from a bundle generated in bzrlib to deliver a
136
 
          complete request).
137
 
 
138
 
          Possibly this should just be RemoteBzrDir, RemoteTransport,
139
 
          ...
140
 
  ^
141
 
  | structured data
142
 
  v
143
 
 
144
 
PROTOCOL  (serialization, deserialization)  accepts structured data for one
145
 
          request, encodes and writes to the medium.  Reads bytes from the
146
 
          medium, decodes and allows the client to read structured data.
147
 
  ^
148
 
  | bytes.
149
 
  v
150
 
 
151
 
 MEDIUM  (accepts bytes from the protocol & delivers to the remote server.
152
 
          Allows the potocol to read bytes e.g. socket, pipe, HTTP request.
153
 
 
154
 
The domain logic is in `bzrlib.remote`: `RemoteBzrDir`, `RemoteBranch`, and so
155
 
on.
 
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.
156
28
 
157
29
There is also an plain file-level transport that calls remote methods to
158
30
manipulate files on the server in `bzrlib.transport.remote`.
159
31
 
160
 
Paths
161
 
=====
162
 
 
163
 
Paths are passed across the network.  The client needs to see a namespace that
164
 
includes any repository that might need to be referenced, and the client needs
165
 
to know about a root directory beyond which it cannot ascend.
166
 
 
167
 
Servers run over ssh will typically want to be able to access any path the user
168
 
can access.  Public servers on the other hand (which might be over http, ssh
169
 
or tcp) will typically want to restrict access to only a particular directory
170
 
and its children, so will want to do a software virtual root at that level.
171
 
In other words they'll want to rewrite incoming paths to be under that level
172
 
(and prevent escaping using ../ tricks.)
173
 
 
174
 
URLs that include ~ should probably be passed across to the server verbatim
175
 
and the server can expand them.  This will proably not be meaningful when
176
 
limited to a directory?
 
32
The protocol is described in doc/developers/network-protocol.txt.
 
33
 
177
34
"""
178
35
 
179
36
# TODO: _translate_error should be on the client, not the transport because