[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

Re: Please review new control-spec.txt

On Tue, Jun 28, 2005 at 12:11:03AM +0200, Robert Mischke wrote:
> (I finally got round to write this down...)

Thanks, Robert!  I know you're busy, so I really appreciate your
having taken a look at this.

> Sorry to cut in here already, but after taking a look
> at the new protocol, I'm left wondering: In which way
> is it really simpler than the old one?

Hm.  I think I might be wandering into religious territory here.

I am pretty convinced that it's simpler to use.  As a completely
unscientific study, the interface code to deal with the new protocol
is about 30% shorter than the code to deal with the old protocol,
excluding comments and whitespace.  I'm seeing this trend across the
Java and Python interface libraries, so I'm pretty confident of it.

Also, the new protocol is far, far simpler to test and debug.  When I
wrote implemented the old one, I needed a pretty complicated test
harness to test each new feature.  I also needed to answer tons of
email and IRC questions from people who had misunderstood how to
connect to the system, how to parse its responses, and so on.  Most
people who approached me with difficulties were stuck at the earliest
message formatting stages: they were sending something slightly
misformatted and baffling themselves completely.

Being able to telnet to the control port makes stuff far, far easier.
Now writing tests is as easy as telnet, scripting tests is as easy as
netcat, and telling people how to use the controller interface is as
easy as typing human-readable strings.

I agree that there are too many different ways to escape things.

"We encode short one-ling strings like this, with \" double quotes"

We encode multiline text like  RFC822,
..where lines beginning with a dot get an extra dot prepended
and after the last line, we have a line containing only a dot

- We've encode binary stuff in hex.

None of these is hard to processor generate, but choosing a single
consistent format would probably help a lot.  The problem is that the
needs are kinda different: in the first case, we have arguments with
optional spaces; in the second, we have multiline arguments; in the
third, we have non-printable arguments.

> ---SPEC---
> ...
>   If all of the listed keywords exist in the Tor
> configuration, Tor replies
>   with a series of reply lines of the form:
>       250 keyword=value
> ---END---
> I don't think it's a good idea to use the general 250
> code for this, because this means that the message
> receiver must be context-aware of the command that was
> sent before. Better to define a response code that
> *always* means "this is the current state of this CONF
> value" (e.g. "259 key=value"). The 250 text should
> always be optional to parse, IMO.

Hm.  I took a lead from SMTP here, which uses 250 to give values and
OK responses.  A 259 response type would probably be better.

> (Note: All of this applies to GETINFO as well; it
> should, of course, get a different response code than

I'm not sure I believe this part.

> ---SPEC---
> ...
>   If any option is set to a 'default' value
> semantically different from an
>   empty string, Tor may reply with a reply line of the
> form:
>       250 keyword
> ---END---
> I'm not sure I understand this?

Tor's configuration system assumes that there is a "null" or "default"
value for every option that is distinct from setting the option to a
particular value.

> The above example, rewritten (with extra data lines):
>      C: router foobar 9001 0 9030 \
>      C: more desciptor data \
>      C: even more desciptor data \
>      C: last line of descriptor
>      S: 250 OK

Sadly, this wouldn't work.  This is signed data; you can't add
whitespace willy-nilly. You would have to say:

     C: router foobar 9001 0 9030\
     C: more desciptor data\
     C: even more desciptor data\
     C: last line of descriptor
     S: 250 OK

Hm.  I wish I had a better idea of what I wanted to do here.  My
current inclination is to stay with the current system as "simple
enough", but I wouldn't mind sanding out some of the corner cases.

Nick Mathewson

Attachment: pgpZaXDkpGW8O.pgp
Description: PGP signature