Opened 2 weeks ago

Last modified 2 weeks ago

#28615 new enhancement

Additional @type annotation

Reported by: atagar Owned by: metrics-team
Priority: Medium Milestone:
Component: Metrics/Library Version:
Severity: Normal Keywords:
Cc: Actual Points:
Parent ID: Points:
Reviewer: Sponsor:

Description

Hi Karsten, would you mind if we add a few new @type annotations? Stem is getting the ability to parse detached signatures (#28495), and sometimes is called to parse individual router status entries.

The way I've designed Stem expects that all descriptor types have a type annotation that users can provide to say 'please parse this as X'. As such I need to either make up my own annotations or (better!) ask for us to expand our official set.

In particular I'm hoping for...

@type detached-signature 1.0

  Detached signature as per section 3.10 of the dir-spec,
  and downloadable for five minutes each hour via the
  '/tor/status-vote/next/consensus-signatures' resource.

@type router-status-entry-2 1.0


  Individual router status entry from a v2 network status
  document.

@type router-status-entry-3 1.0


  Individual router status entry from a v3 network status
  document.

@type router-status-entry-micro-3 1.0


  Individual router status entry from a v3 microdescriptor
  network status document.

Thanks!

Child Tickets

Change History (3)

comment:1 Changed 2 weeks ago by irl

downloadable for five minutes each hour

It is actually for DistSeconds every freshness period. This just happens to be 5 minutes at the moment but could change.

Other than that I think these are all important and we should add them.

comment:2 Changed 2 weeks ago by karsten

Adding a @type annotation for detached signatures sounds reasonable.

But I'm less clear about the other three. A status entry is not a descriptor. It is part of another descriptor. In Metrics Library we have NetworkStatusEntry for status entry, but it's explicitly marked as not being a descriptor type of its own.

Wouldn't it be sufficient to pass the @type annotation of the network status containing the status entry to Stem?

Asked differently, if we make the status entry a descriptor type of its own, why would we not do the same with dir-source entries (DirSourceEntry in Metrics Library), directory-signature entries (DirectorySignature in Metrics Library)? (I'm not suggesting we do this, but what would we tell somebody suggesting this after defining descriptor types for the various status entries?)

comment:3 Changed 2 weeks ago by atagar

Adding a @type annotation for detached signatures sounds reasonable.

Great! Thanks Karsten. Once the @type docs are updated please let me know and I'll make the related tweaks on stem's end.

But I'm less clear about the other three

You're completely right that router status entries are simply entities in a network status document (@type network-status-*). The trouble is that unlike other descriptor types router status entries are often provided on their own. For example, via the control port...

>>> GETINFO ns/name/caersidi
250+ns/name/caersidi=
r caersidi O7NMYwctnRDoNu5ClocT97kyX2Y 1cL1nVzDsMuGliTcNUnjIc6MAEE 2018-11-26 17:23:54 208.113.135.162 1443 1444
s Fast Guard HSDir Running Stable V2Dir Valid
w Bandwidth=4820
.
250 OK

As such stem users sometimes have a desire to parse individual router status entries despite the fact that they're not technically valid descriptors on their own.

why would we not do the same with dir-source entries

That's an interesting point. Is there anything that vends dir-source entries on their own?

Note: See TracTickets for help on using tickets.