#28067: Annotations should be documented in dir-spec.txt
--------------------------+----------------------------------
Reporter: rl1987 | Owner: (none)
Type: enhancement | Status: new
Priority: Medium | Milestone: Tor: unspecified
Component: Core Tor/Tor | Version:
Severity: Normal | Resolution:
Keywords: | Actual Points:
Parent ID: | Points:
Reviewer: | Sponsor:
--------------------------+----------------------------------
Comment (by irl):
For Metrics, the goal is:
* to have metadata about where descriptors came from (@source). This
could be:
* an IP address: we learned this from a directory cache/authority (tor
does this)
* a full URL: we learned this from a directory cache/authority or a
remote CollecTor instance (CollecTor would do this)
* "file": we learned this from files imported locally
* to have metadata about when we learned the descriptor (@downloaded-at):
* the timestamp format used by tor looks fine for this
* to know how to parse back a serialised descriptor (@type):
* these are defined by CollecTor, not implemented in tor
tor would not need to understand all of these annotations. The `cached-*`
files are written by tor and it's not expected that users would provide
other data there.
Other parsers would need to understand these annotations, but they are not
part of the descriptor unless the descriptor is on disk. They would never
appear on the wire as nickm commented above.
Unknown annotations should be ignored. It may be useful to warn if there
are unrecognised annotations, or provide some raw access to them, but it's
not required. We would want stem to provide access to them. If we have
metadata available we're going to want to store it, and everything should
not break when we do.
We can define annotations as (RFC5234):
{{{
AT = "@"
ANNOTATION-NAME = (ALPHA / DIGIT / "-") [ANNOTATION-NAME]
ANNOTATION-VALUE = VCHAR [ANNOTATION-VALUE]
ANNOTATION = AT ANNOTATION-NAME SP ANNOTATION-VALUE CRLF
}}}
We might want to use the definition of acceptable Unicode from
[[https://gitweb.torproject.org/torspec.git/tree/proposals/285-utf-8.txt#n70|ยง2.3
of proposal 285]] instead of VCHAR, but I don't see a need for doing this
for ANNOTATION-NAME.
I believe that the CollecTor protocol is the only place that we actually
talk about descriptors stored on disk, so perhaps it would be good to add
this in a section to the end of that.
https://spec.torproject.org/collector-protocol
--
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/28067#comment:6>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online