Hi Ravi, Beck, and everyone else hacking on stem. I just finished and merged a rewrite of our documentation into reStructuredText. The results are... very pretty.
http://www.atagar.com/transfer/tmp/stem_html_12_06_05/
Next I plan to make a landing page for stem, and a cron process which will automatically keep a documentation page up to date with the current git master branch. Some pages that you might find especially relevant...
Ravi http://www.atagar.com/transfer/tmp/stem_html_12_06_05/stem.html#module-stem....
Beck http://www.atagar.com/transfer/tmp/stem_html_12_06_05/stem.html#stem.control...
Karsten http://www.atagar.com/transfer/tmp/stem_html_12_06_05/stem.descriptor.html#m...
Norman, Erik, and Megan http://www.atagar.com/transfer/tmp/stem_html_12_06_05/stem.util.html#module-...
Cheers! -Damian
On 6/6/12 6:48 AM, Damian Johnson wrote:
Hi Ravi, Beck, and everyone else hacking on stem. I just finished and merged a rewrite of our documentation into reStructuredText. The results are... very pretty.
Looks really cool!
Karsten http://www.atagar.com/transfer/tmp/stem_html_12_06_05/stem.descriptor.html#m...
I looked through the docs and found these minor issues:
- Does ExtraInfoDescriptor support bridge descriptors yet? Those don't contain a signature, which means that the signature variable shouldn't be marked as required. Also, there should be a digest() method for RelayExtraInfoDescriptor and a digest variable for BridgeExtraInfoDescriptor; the relay descriptor digest is calculated, whereas the bridge descriptor digest is parsed from the "router-digest" line.
- Should the conn_bi_direct_* variables be grouped under "Bi-directional connection usage:"?
- ServerDescriptor also has a digest() method for both relay and bridge descriptors. The same reasoning about a digest() method for relays and a digest variable for bridges applies here, too. In the documentation of digest(), better talk about "network status entry" instead of "server descriptor entry".
- Why does digest() return the base64-encoded digest, not the hex-formatted one? Network statuses are the only documents in Tor using base64 (or rather, a variant of it without trailing ='s), so it's easier to convert those to hex than to convert everything else to base64. Now, if you switch to hex, you'll only have to decide between lower-case and upper-case. I think Tor and metrics-lib use upper-case hex in most places.
- address_alt is not bridge-specific, but relays are going to list additional OR addresses in their descriptors in the near future.
And here are a few typos that I found while reading:
- "fastest querter" -> "fastest quarter"
- "circuits in a deciles" -> "circuits in a decile"
- "doens't conform" -> "doesn't conform"
- "averate rate" -> "average rate"
- "appeard" -> "appeared"
Best, Karsten
Thanks, Karsten.
- Does ExtraInfoDescriptor support bridge descriptors yet? Those don't
contain a signature, which means that the signature variable shouldn't be marked as required. Also, there should be a digest() method for RelayExtraInfoDescriptor and a digest variable for BridgeExtraInfoDescriptor; the relay descriptor digest is calculated, whereas the bridge descriptor digest is parsed from the "router-digest" line.
- ServerDescriptor also has a digest() method for both relay and bridge
descriptors. The same reasoning about a digest() method for relays and a digest variable for bridges applies here, too. In the documentation of digest(), better talk about "network status entry" instead of "server descriptor entry".
Ack! Good points. Time permitting I'll fix these over the weekend.
- Why does digest() return the base64-encoded digest, not the
hex-formatted one? Network statuses are the only documents in Tor using base64 (or rather, a variant of it without trailing ='s), so it's easier to convert those to hex than to convert everything else to base64. Now, if you switch to hex, you'll only have to decide between lower-case and upper-case. I think Tor and metrics-lib use upper-case hex in most places.
I went with base64 because I thought that this was only useful for comparing with the network status. What uses the hex encoded digest?
- Should the conn_bi_direct_* variables be grouped under "Bi-directional
connection usage:"?
And here are a few typos that I found while reading:
"fastest querter" -> "fastest quarter"
"circuits in a deciles" -> "circuits in a decile"
"doens't conform" -> "doesn't conform"
"averate rate" -> "average rate"
"appeard" -> "appeared"
great, changed
- address_alt is not bridge-specific, but relays are going to list
additional OR addresses in their descriptors in the near future.
Yup, but they don't yet nor is it in the tor spec (last that I checked). I was planning to move it up to the ServerDescriptor class when it is.
On 6/6/12 7:32 PM, Damian Johnson wrote:
- Why does digest() return the base64-encoded digest, not the
hex-formatted one? Network statuses are the only documents in Tor using base64 (or rather, a variant of it without trailing ='s), so it's easier to convert those to hex than to convert everything else to base64. Now, if you switch to hex, you'll only have to decide between lower-case and upper-case. I think Tor and metrics-lib use upper-case hex in most places.
I went with base64 because I thought that this was only useful for comparing with the network status. What uses the hex encoded digest?
The hex-encoded server descriptor digest is used as file name in metrics tarballs.
The (decoded) descriptor digest is used to verify the descriptor signature.
Other reasons for hex-encoding the digest() result is that the digest() in extra-info descriptors should return the hex-encoded digest, too, or you wouldn't be able to compare it to the extra-info-digest line in server descriptors. Having both methods return a different encoding would be confusing.
Oh, and router-digest lines in sanitized bridge descriptors also contain the hex-encoded digest. You wouldn't want to convert that to base64 before writing it to the digest variable, nor would you want digest() and digest to return differently encoded digests.
- address_alt is not bridge-specific, but relays are going to list
additional OR addresses in their descriptors in the near future.
Yup, but they don't yet nor is it in the tor spec (last that I checked). I was planning to move it up to the ServerDescriptor class when it is.
Makes sense.
Thanks, Karsten
-
Damian Johnson -
Karsten Loesing