Describe approach to downloading status documents; update TODO a bit

svn:r4899

2 files changed, 24 insertions, 2 deletions

diff --git a/doc/TODO b/doc/TODO
index a9c701106a..c739ed7760 100644
--- a/doc/TODO
+++ b/doc/TODO
@@ -115,9 +115,10 @@ R     - check reachability as soon as you hear about a new server
       - find 10 dirservers.
         - (what are criteria to be a dirserver?)
 N     . Dirservers publish compressed network-status objects.
-        - Support several-at-once
+        - Support retrieving several-at-once
 N     . Everyone downloads network-status objects
         - From all directories, round-robin
+        . Parse them
         - Cache them, reload on restart
         o Serve cached directories
 N     . Directories expose individual descriptors
@@ -152,6 +153,8 @@ Reach (deferrable) items for 0.1.1.x:
   - Start using create-fast cells as clients
   o Let more config options (e.g. ORPort) change dynamically.
   - start handling server descriptors without a socksport?
+  o Add TTLs to DNS-related replies, and use them (where present) to adjust
+    addressmap values.
 
   . Research memory use on Linux: what's happening?
     - Is it threading?  (Maybe, maybe not)
diff --git a/doc/dir-spec.txt b/doc/dir-spec.txt
index b01d0b3478..2693352dee 100644
--- a/doc/dir-spec.txt
+++ b/doc/dir-spec.txt
@@ -228,7 +228,26 @@ $Id$
 
    Clients store network status documents so long as they are live.
 
-5.1. Managing naming
+5.1. Scheduling network status downloads
+
+   This download scheduling algorithm implements the approach described above
+   in a relatively low-state fashion.  It reflects the current Tor
+   implementation.
+
+   Clients maintain a list of authorities; each client tries to keep the same
+   list, in the same order.
+
+   Periodically, on startup, and on HUP, clients check whether they need to
+   download fresh network status documents.  The approach is as follows:
+     - If we have under X network status documents newer than OLD, we choose a
+       member of the list at random and try download XX documents starting
+       with that member's.
+     - Otherwise, if we have no network status documents newer than NEW, we
+       check to see which authority's document we retrieved most recently,
+       and try to retrieve the next authority's document.  If we can't, we
+       try the next authority in sequence, and so on.
+
+5.2. Managing naming
 
    In order to provide human-memorable names for individual server
    identities, some directory servers bind names to IDs.  Clients handle