[or-cvs] r14803: Document our timelines for fetching consensuses. The languag (in tor/trunk/doc: . spec)

[nickm at seul.org]

Author: nickm
Date: 2008-05-28 22:51:47 -0400 (Wed, 28 May 2008)
New Revision: 14803

Modified:
   tor/trunk/doc/TODO
   tor/trunk/doc/spec/dir-spec.txt
Log:
Document our timelines for fetching consensuses.  The language is not as clear as it could be; can anybody make it better?

Modified: tor/trunk/doc/TODO
===================================================================
--- tor/trunk/doc/TODO	2008-05-29 02:29:35 UTC (rev 14802)
+++ tor/trunk/doc/TODO	2008-05-29 02:51:47 UTC (rev 14803)
@@ -306,7 +306,7 @@
     . 111: Prioritize local traffic over relayed.
 R     - Merge into tor-spec.txt.
     - 113: mark as closed close.
-N - document the "3/4 and 7/8" business in the clients fetching consensus
+  o document the "3/4 and 7/8" business in the clients fetching consensus
     documents timeline.
 R   - then document the bridge user download timeline.
   - HOWTO for DNSPort. See tup's wiki page.

Modified: tor/trunk/doc/spec/dir-spec.txt
===================================================================
--- tor/trunk/doc/spec/dir-spec.txt	2008-05-29 02:29:35 UTC (rev 14802)
+++ tor/trunk/doc/spec/dir-spec.txt	2008-05-29 02:51:47 UTC (rev 14803)
@@ -1336,10 +1336,16 @@
      - The cache has no consensus document.
      - The cache's consensus document is no longer valid.
    Otherwise, the cache downloads a new consensus document at a randomly
-   chosen time after its current consensus stops being fresh.  (This time is
-   chosen at random to avoid swarming the authorities at the start of each
-   period.)
+   chosen time in the first half-interval after its current consensus
+   stops being fresh.  (This time is chosen at random to avoid swarming
+   the authorities at the start of each period.  The interval size is
+   inferred from the difference between the valid-after time and the
+   fresh-until time on the consensus.)
 
+   [For example, if a cache has a consensus that became valid at 1:00,
+    and is fresh until 2:00, that cache will fetch a new consensus at
+    a random time between 2:00 and 2:30.]
+
 4.4. Downloading and storing router descriptors (authorities and caches)
 
    Periodically (currently, every 10 seconds), directory servers check
@@ -1515,7 +1521,20 @@
    from an authority, they should not need to go to the authority directly
    again.)
 
+   To avoid swarming the caches whenever a consensus expires, the
+   clients download new consensuses at a randomly chosen time after the
+   caches are expected to have a fresh consensus, but before their
+   consensus will expire.  (This time is chosen uniformly at random from
+   the interval between the time 3/4 into the first interval after the
+   consensus is no longer fresh, and 7/8 of the time remaining after
+   that before the consensus is invalid.)
 
+   [For example, if a cache has a consensus that became valid at 1:00,
+    and is fresh until 2:00, and expires at 4:00, that cache will fetch
+    a new consensus at a random time between 2:45 and 3:50, since 3/4
+    of the one-hour interval is 45 minutes, and 7/8 of the remaining 75
+    minutes is 65 minutes.]
+
 5.2. Downloading and storing router descriptors
 
    Clients try to have the best descriptor for each router.  A descriptor is