1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
|
This is Info file cvsclient.info, produced by Makeinfo version 1.67
from the input file ./cvsclient.texi.
File: cvsclient.info, Node: Example, Next: Requirements, Prev: Text tags, Up: Protocol
Example
=======
Here is an example; lines are prefixed by `C: ' to indicate the
client sends them or `S: ' to indicate the server sends them.
The client starts by connecting, sending the root, and completing the
protocol negotiation. In actual practice the lists of valid responses
and requests would be longer.
C: Root /u/cvsroot
C: Valid-responses ok error Checked-in M E
C: valid-requests
S: Valid-requests Root Directory Entry Modified Argument Argumentx ci co
S: ok
C: UseUnchanged
The client wants to check out the `supermunger' module into a fresh
working directory. Therefore it first expands the `supermunger'
module; this step would be omitted if the client was operating on a
directory rather than a module.
C: Argument supermunger
C: Directory .
C: /u/cvsroot
C: expand-modules
The server replies that the `supermunger' module expands to the
directory `supermunger' (the simplest case):
S: Module-expansion supermunger
S: ok
The client then proceeds to check out the directory. The fact that
it sends only a single `Directory' request which specifies `.' for the
working directory means that there is not already a `supermunger'
directory on the client.
C: Argument -N
C: Argument supermunger
C: Directory .
C: /u/cvsroot
C: co
The server replies with the requested files. In this example, there
is only one file, `mungeall.c'. The `Clear-sticky' and
`Clear-static-directory' requests are sent by the current
implementation but they have no effect because the default is for those
settings to be clear when a directory is newly created.
S: Clear-sticky supermunger/
S: /u/cvsroot/supermunger/
S: Clear-static-directory supermunger/
S: /u/cvsroot/supermunger/
S: E cvs server: Updating supermunger
S: M U supermunger/mungeall.c
S: Created supermunger/
S: /u/cvsroot/supermunger/mungeall.c
S: /mungeall.c/1.1///
S: u=rw,g=r,o=r
S: 26
S: int mein () { abort (); }
S: ok
The current client implementation would break the connection here
and make a new connection for the next command. However, the protocol
allows it to keep the connection open and continue, which is what we
show here.
After the user modifies the file and instructs the client to check it
back in. The client sends arguments to specify the log message and file
to check in:
C: Argument -m
C: Argument Well, you see, it took me hours and hours to find
C: Argumentx this typo and I searched and searched and eventually
C: Argumentx had to ask John for help.
C: Argument mungeall.c
It also sends information about the contents of the working
directory, including the new contents of the modified file. Note that
the user has changed into the `supermunger' directory before executing
this command; the top level directory is a user-visible concept because
the server should print filenames in `M' and `E' responses relative to
that directory.
C: Directory .
C: /u/cvsroot/supermunger
C: Entry /mungeall.c/1.1///
C: Modified mungeall.c
C: u=rw,g=r,o=r
C: 26
C: int main () { abort (); }
And finally, the client issues the checkin command (which makes use
of the data just sent):
C: ci
And the server tells the client that the checkin succeeded:
S: M Checking in mungeall.c;
S: E /u/cvsroot/supermunger/mungeall.c,v <-- mungeall.c
S: E new revision: 1.2; previous revision: 1.1
S: E done
S: Mode u=rw,g=r,o=r
S: Checked-in ./
S: /u/cvsroot/supermunger/mungeall.c
S: /mungeall.c/1.2///
S: ok
File: cvsclient.info, Node: Requirements, Next: Obsolete, Prev: Example, Up: Protocol
Required versus optional parts of the protocol
==============================================
The following are part of every known implementation of the CVS
protocol (except obsolete, pre-1.5, versions of CVS) and it is
considered reasonable behavior to completely fail to work if you are
connected with an implementation which attempts to not support them.
Requests: `Root', `Valid-responses', `valid-requests', `Directory',
`Entry', `Modified', `Unchanged', `Argument', `Argumentx', `ci', `co',
`update'. Responses: `ok', `error', `Valid-requests', `Checked-in',
`Updated', `Merged', `Removed', `M', `E'.
A server need not implement `Repository', but in order to
interoperate with CVS 1.5 through 1.9 it must claim to implement it (in
`Valid-requests'). The client will not actually send the request.
File: cvsclient.info, Node: Obsolete, Prev: Requirements, Up: Protocol
Obsolete protocol elements
==========================
This section briefly describes protocol elements which are obsolete.
There is no attempt to document them in full detail.
There was a `Repository' request which was like `Directory' except
it only provided REPOSITORY, and the local directory was assumed to be
similarly named.
If the `UseUnchanged' request was not sent, there was a `Lost'
request which was sent to indicate that a file did not exist in the
working directory, and the meaning of sending `Entries' without `Lost'
or `Modified' was different. All current clients (CVS 1.5 and later)
will send `UseUnchanged' if it is supported.
File: cvsclient.info, Node: Protocol Notes, Prev: Protocol, Up: Top
Notes on the Protocol
*********************
A number of enhancements are possible. Also see the file TODO in
the CVS source distribution, which has further ideas concerning various
aspects of CVS, some of which impact the protocol.
* The `Modified' request could be speeded up by sending diffs rather
than entire files. The client would need some way to keep the
version of the file which was originally checked out; probably
requiring the use of "cvs edit" in this case is the most sensible
course (the "cvs edit" could be handled by a package like VC for
emacs). This would also allow local operation of `cvs diff'
without arguments.
* The current procedure for `cvs update' is highly sub-optimal if
there are many modified files. One possible alternative would be
to have the client send a first request without the contents of
every modified file, then have the server tell it what files it
needs. Note the server needs to do the what-needs-to-be-updated
check twice (or more, if changes in the repository mean it has to
ask the client for more files), because it can't keep locks open
while waiting for the network. Perhaps this whole thing is
irrelevant if there is a multisite capability (as noted in TODO),
and therefore the rcsmerge can be done with a repository which is
connected via a fast connection.
* The fact that `pserver' requires an extra network turnaround in
order to perform authentication would be nice to avoid. This
relates to the issue of reporting errors; probably the clean
solution is to defer the error until the client has issued a
request which expects a response. To some extent this might
relate to the next item (in terms of how easy it is to skip a
whole bunch of requests until we get to one that expects a
response). I know that the kerberos code doesn't wait in this
fashion, but that probably can cause network deadlocks and perhaps
future problems running over a transport which is more transaction
oriented than TCP. On the other hand I'm not sure it is wise to
make the client conduct a lengthy upload only to find there is an
authentication failure.
* The protocol uses an extra network turnaround for protocol
negotiation (`valid-requests'). It might be nice to avoid this by
having the client be able to send requests and tell the server to
ignore them if they are unrecognized (different requests could
produce a fatal error if unrecognized). To do this there should
be a standard syntax for requests. For example, perhaps all
future requests should be a single line, with mechanisms analogous
to `Argumentx', or several requests working together, to provide
greater amounts of information. Or there might be a standard
mechanism for counted data (analogous to that used by `Modified')
or continuation lines (like a generalized `Argumentx'). It would
be useful to compare what HTTP is planning in this area; last I
looked they were contemplating something called Protocol Extension
Protocol but I haven't looked at the relevant IETF documents in
any detail. Obviously, we want something as simple as possible
(but no simpler).
* The scrambling algorithm in the CVS client and server actually
support more characters than those documented in *Note Password
scrambling::. Someday we are going to either have to document
them all (but this is not as easy as it may look, see below), or
(gradually and with adequate process) phase out the support for
other characters in the CVS implementation. This business of
having the feature partly undocumented isn't a desirable state
long-term.
The problem with documenting other characters is that unless we
know what character set is in use, there is no way to make a
password portable from one system to another. For example, a with
a circle on top might have different encodings in different
character sets.
It *almost* works to say that the client picks an arbitrary,
unknown character set (indeed, having the CVS client know what
character set the user has in mind is a hard problem otherwise),
and scrambles according to a certain octet<->octet mapping. There
are two problems with this. One is that the protocol has no way
to transmit character 10 decimal (linefeed), and the current
server and clients have no way to handle 0 decimal (NUL). This
may cause problems with certain multibyte character sets, in which
octets 10 and 0 will appear in the middle of other characters.
The other problem, which is more minor and possibly not worth
worrying about, is that someone can type a password on one system
and then go to another system which uses a different encoding for
the same characters, and have their password not work.
The restriction to the ISO646 invariant subset is the best
approach for strings which are not particularly significant to
users. Passwords are visible enough that this is somewhat
doubtful as applied here. ISO646 does, however, have the virtue
(!?) of offending everyone. It is easy to say "But the $ is right
on people's keyboards! Surely we can't forbid that". From a
human factors point of view, that makes quite a bit of sense. The
contrary argument, of course, is that a with a circle on top, or
some of the characters poorly handled by Unicode, are on
*someone*'s keyboard.
|
