[tor-bugs] #8036 [Stem]: Tweak Stem's documentation

[Tor Bug Tracker & Wiki]

#8036: Tweak Stem's documentation
--------------------+-------------------------------------------------------
 Reporter:  amj703  |          Owner:  atagar
     Type:  defect  |         Status:  new   
 Priority:  normal  |      Milestone:        
Component:  Stem    |        Version:        
 Keywords:          |         Parent:        
   Points:          |   Actualpoints:        
--------------------+-------------------------------------------------------

Comment(by karsten):

 Replying to [comment:2 atagar]:
 > > The Descriptor documentation should state that @type bridge-extra-info
 1.1 is supported, not just 1.0. There's a difference between supporting
 1.0 and ignoring the 1.1 parts and supporting 1.1.
 >
 > Please see the bit above:
 >
 > "Descriptor types include the following, including further minor
 versions (ie. if we support 1.0 then we also support 1.1 and above)..."
 >
 > Stem expects @type annotations to have a minor version, but ignores the
 value. I list minor versions in the table so users can copy and paste them
 for the 'descriptor_type' argument.

 I understand that stem ignores the minor version, but isn't this
 information valuable to users?  For example, if 1.1 adds a field that gets
 parsed by Stem, knowing whether that field will be in Stem's parsed object
 is useful to users.

 > > All fingerprints and digests, which are in most cases 160 bit value
 strings, should state exactly whether they're base64 or lower-case hex or
 upper-case hex encoded.
 >
 > Mind writing a patch for this? Personally I scratched my head for quite
 a while trying to figure out what format users would find the most
 convenient for these values.

 Personally, I find hex most useful, but anything works as long as it's
 clearly documented.  Yes, I can write a patch.  But before I do that: we
 discussed in private mail that it's still break-the-API time.  It would be
 convenient if those fields that are used as references between descriptors
 (e.g., from status entry to server descriptor) used the same encoding.  If
 you agree, I'd submit a patch that documents encodings more clearly and
 that converts fingerprint and server descriptor digest in status entries
 from base64 to upper-case hex.

 > > RouterStatusEntries should state exactly what fields the referenced
 "thin" document has and what fields it's missing.
 >
 > Hm? The thin document should *only* be missing the routers attribute (as
 documented). Footer attributes like bandwidth_weights should be present.

 Oh, okay.  Never mind then.

 > > The addresses_v6 field in RouterStatusEntryV3 doesn't support port
 ranges, but only port lists.
 >
 > Mind providing an example router status entry that's being misparsed?

 I don't know if something is misparsed, it's just that the documentation
 isn't correct.  RouterStatusEntryV3 says: "addresses_v6 (dict) – * relay’s
 IPv6 OR addresses, this is a mapping of IPv6 addresses to a listing of
 [(min port, max port)...] it accepts".  In theory, that field should be
 equivalent to "address_alt (list) – alternative for our address/or_port
 attributes, each entry is a tuple of the form (address (str), port (int),
 is_ipv6 (bool))" in ServerDescriptor.  Note that "addresses_v6" is also
 not correct, it should be "address_alt" or "addresses_alt".

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