[tor-bugs] #28503 [Core Tor/Stem]: Move annotation handling to the base Descriptor class

[Tor Bug Tracker & Wiki]

#28503: Move annotation handling to the base Descriptor class
---------------------------+------------------------
 Reporter:  irl            |          Owner:  atagar
     Type:  enhancement    |         Status:  new
 Priority:  Medium         |      Milestone:
Component:  Core Tor/Stem  |        Version:
 Severity:  Normal         |     Resolution:
 Keywords:                 |  Actual Points:
Parent ID:                 |         Points:
 Reviewer:                 |        Sponsor:
---------------------------+------------------------

Comment (by atagar):

 Hi Iain, I suspect there may be some confusion here due to overloaded
 terminology. There are two things that use the term of 'annotations'...

 * Server descriptor **files** (ie, '$TOR_DATA_DIR/cached-descriptors') are
 prefaced with data like the following. These were around before metric's
 @type was a twinkle in Karsten's eye, and what our ServerDescriptor class'
 [https://stem.torproject.org/api/descriptor/server_descriptor.html#stem.descriptor.server_descriptor.ServerDescriptor.get_annotations
 get_annotations method] is referencing.

 {{{
 @downloaded-at 2012-03-14 16:31:05
 @source "145.53.65.130"
 router caerSidi 71.35.143.157 9001 0 0
 platform Tor 0.2.1.30 on Linux x86_64
 ...
 }}}

 * The second are [https://metrics.torproject.org/collector.html#data-
 formats metrics annotations], but calling them general purpose annotations
 is a bit of a misnomer. When Karsten and I discussed them we **only**
 speced a single @type value. If metrics were to add a '@my_new_stuff'
 annotation it will break parsers until they're adjusted - stem included.

 Actually, the approach I'd like to take here is to...

 1. Deprecate ServerDescriptor's annotation methods. I included these for
 completeness, but they're not part of the dir-spec and nowadays stem users
 rarely read cached files.

 2. Does Karsten want to expand metrics annotations beyond @type? If so I'd
 be happy to work with you on the spec and expand stem to recognize them.
 But we should only invest this effort if there's something we plan to use
 them for.

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