[tor-bugs] #24742 [Core Tor/Fallback Scripts]: Add fallback list spec to torspec

[Tor Bug Tracker & Wiki]

#24742: Add fallback list spec to torspec
---------------------------------------+-----------------------------------
 Reporter:  teor                       |          Owner:  teor
     Type:  enhancement                |         Status:  needs_review
 Priority:  Medium                     |      Milestone:  Tor:
                                       |  0.3.3.x-final
Component:  Core Tor/Fallback Scripts  |        Version:
 Severity:  Normal                     |     Resolution:
 Keywords:  fallback, torspec          |  Actual Points:
Parent ID:  #24725                     |         Points:  0.5
 Reviewer:                             |        Sponsor:
---------------------------------------+-----------------------------------

Comment (by atagar):

 Thanks Tim. For other's reference
 [https://github.com/teor2345/torspec/blob/fallback-format-2/fallback-
 spec.txt here's the link].

 Very well written, nice work! Only a few minor thoughts...

 * In the 'Fallback Summary' lets explicitly say 'The separator MUST not
 appear within the user readable comments.' Since parsers will be using it
 to determine where it ends that would of course be a bad thing. :)

 * Concerning the headers I just had an idea: how about a revision number?
 Stem uses tor's git commit to determine "Have I already read this copy of
 the fallbacks file?". If the file instead had an incrementing number I
 could use that instead ("Oh hey, I've already parsed revision 64. Nothing
 to do.").

   Not necessary in the least. Just an idea.

 * Not certain I know what all "A fallback entry consists of a C string
 constant" entails. If you simply mean that the fields are quoted then lets
 say that instead.

 * For the ipv6_address lets specify that the address is fully expanded
 (ie, nothing like '::').

 * Concerning nickname and extrainfo it's not jumping out to me to expect
 those to be C-style comments rather than quoted.

 * Total aesthetic thing but I'd include more equal signs in the divider,
 but do whatever you think makes the file the nicest to read. :)

 * On my first read I missed that you were listing fields rather than
 lines. Every other spec we have this would mean to expect the orport line
 to be separate from id line, etc.

   Mind if we instead do a per-line spec instead? That is to say tell users
 they can expect...

     DQUOTE AddressIPv4 ":" DirPort SP "orport=" OrPort SP "id="
 Fingerprint DQUOTE NL [[BR]]
     [ Exactly once ] [[BR]][[BR]]
     DQUOTE SP "ipv6=^^[^^" AddressIPv6 "]:" Port DQUOTE NL [[BR]]
     [ Any number of times ][[BR]][[BR]]
     ... etc...

--
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/24742#comment:5>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online