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. ::
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
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.
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.)
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?
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.
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.
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,
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.
53
Version one of the protocol (for requests and responses) is described by::
56
RESPONSE := MESSAGE_V1
57
MESSAGE_V1 := ARGS BODY
59
ARGS := ARG [MORE_ARGS] NEWLINE
60
MORE_ARGS := SEP ARG [MORE_ARGS]
63
BODY := LENGTH NEWLINE BODY_BYTES TRAILER
64
LENGTH := decimal integer
65
TRAILER := "done" NEWLINE
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.
72
Version two of the request protocol is::
74
REQUEST_V2 := "bzr request 2" NEWLINE MESSAGE_V1
76
Version two of the response protocol is::
78
RESPONSE_V2 := "bzr request 2" NEWLINE MESSAGE_V1
80
Future versions should follow this structure, like version two does::
82
FUTURE_MESSAGE := VERSION_STRING NEWLINE REST_OF_MESSAGE
84
This is that clients and servers can read bytes up to the first newline byte to
85
determine what version a message is.
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.
92
Request/Response processing
93
---------------------------
95
On top of the protocol is the logic for processing requests (on the server) or
96
responses (on the client).
70
103
MEDIUM (factory for protocol, reads bytes & pushes to protocol,
71
104
uses protocol to detect end-of-request, sends written
72
105
bytes to client) e.g. socket, pipe, HTTP request handler.
86
HANDLER (domain logic) accepts structured data, operates state
119
HANDLER (domain logic) accepts structured data, operates state
87
120
machine until the request can be satisfied,
88
121
sends structured data to the protocol.
123
Request handlers are registered in `bzrlib.smart.request`.
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
101
Possibly this should just be RemoteBzrDir, RemoteTransport,
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
138
Possibly this should just be RemoteBzrDir, RemoteTransport,
104
141
| structured data
114
151
MEDIUM (accepts bytes from the protocol & delivers to the remote server.
115
152
Allows the potocol to read bytes e.g. socket, pipe, HTTP request.
154
The domain logic is in `bzrlib.remote`: `RemoteBzrDir`, `RemoteBranch`, and so
157
There is also an plain file-level transport that calls remote methods to
158
manipulate files on the server in `bzrlib.transport.remote`.
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.
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.)
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?
118
179
# TODO: _translate_error should be on the client, not the transport because
179
236
# urlescape them instead. Indeed possibly this should just literally be
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.
186
# TODO: Rather than working at the Transport layer we want a Branch,
187
# Repository or BzrDir objects that talk to a server.
189
239
# TODO: Probably want some way for server commands to gradually produce body
190
240
# data rather than passing it as a string; they could perhaps pass an
191
241
# iterator-like callback that will gradually yield data; it probably needs a
192
242
# close() method that will always be closed to do any necessary cleanup.
194
# TODO: Split the actual smart server from the ssh encoding of it.
196
# TODO: Perhaps support file-level readwrite operations over the transport
199
# TODO: SmartBzrDir class, proxying all Branch etc methods across to another
200
# branch doing file-level operations.
245
# Promote some attributes from submodules into this namespace
246
from bzrlib.smart.request import SmartServerRequestHandler
added
removed
bzrlib/smart/__init__.py
