[tor-dev] Dusting off dir-spec.txt

[Karsten Loesing]

[Re-sending, because my first attempt apparently got lost somewhere.
Apologies if gets found and this is now a duplicate.]


Hi devs, hi dir-spec.txt authors,

when I reviewed the open proposals related to the directory protocol, I
wondered how to integrate the proposed changes into dir-spec.txt.  For
example, status opinions (proposal 147) are going to add a new variant
of the status data format and a new operation that makes authorities
produce and exchange opinions at some point in the voting process.

I also thought back when I wrote the patch to add microdescriptors to
the spec and remembered that I had a hard time finding the right places
to add things.

So, here's my question: can we reorder a few things in dir-spec.txt to
make it easier to read and easier to extend?  (To be clear, I'm happy to
submit patches for this, I'm just asking if patches are welcome.)

In particular, I'd want to start by making the following changes (if you
need a table of contents, here's how I generated mine: `grep -Ev "^
|^$|XXXX" dir-spec.txt | less`):

Sections 3 ("Formats produced by directory authorities") and 4
("Directory server operation") apparently started out by separating
passive parts (data formats) from active parts (operations).  But then
3.4 ("Assigning flags in a vote") and 3.5 ("Computing a consensus from a
set of votes") broke this abstraction.

One way to fix this would be to move the two mentioned subsections 3.4
and 3.5 to Section 4.  Though, personally I'm not a big fan of the
passive-active separation, because the description of passive parts
implies a lot about how they're going to be used.  And then we end up
describing things twice, once implicitly and once explicitly.

The better fix, IMHO, would be to turn Section 3 into "Directory
authority operation and formats" and Section 4 into "Directory cache
operation".  Section 3 would specify operations in causal order (not
sure if this the right term) and specify data formats together with the
operation that generates them:
  - "creating key certificates",
  - "accepting router descriptors and extra-info documents",
  - "computing microdescriptors",
  - "exchanging votes",
  - "downloading missing certificates",
  - "downloading router descriptors and extra-info documents",
  - "computing the consensus",
  - "computing consensus flavors",
  - "exchanging detached signatures", and
  - "publishing the signed consensus".

Section 4 would then only contain the subsections from the current
Section 4 that are relevant for caches.  In cases where cache operations
are equivalent or similar to authority operations, there would be a
simple reference to the earlier section.

Also on the top-level of sections, I'd want to merge Sections 5 ("Client
operation: downloading information") and 6 ("Using directory
information") into a single section "Client operation".

Would you accept patches making these changes?

All the best,
Karsten