[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [torspec/master] 19537: Try to document and clarify GETINFO downloads/*



commit 675c470fe61d2368a5bd16ee297e02f0a94911a2
Author: Nick Mathewson <nickm@xxxxxxxxxxxxxx>
Date:   Wed Aug 23 10:10:15 2017 -0400

    19537: Try to document and clarify GETINFO downloads/*
---
 control-spec.txt | 72 ++++++++++++++++++++++++++++++++++----------------------
 1 file changed, 44 insertions(+), 28 deletions(-)

diff --git a/control-spec.txt b/control-spec.txt
index b31111c..69a77c1 100644
--- a/control-spec.txt
+++ b/control-spec.txt
@@ -920,17 +920,31 @@
     "downloads/"
       The keys under downloads/ are used to query download statuses; they all
       return either a sequence of newline-terminated hex encoded digests, or
-      a serialized download status as follows:
-
-      "next-attempt-at" SP ISOTime CRLF
-      "n-download-failures" SP UInt CRLF
-      "n-download-attempts" SP UInt CRLF
-      "schedule" SP DownloadSchedule CRLF
-      "want-authority" SP DownloadWantAuthority CRLF
-      "increment-on" SP DownloadIncrementOn CRLF
-      "backoff" SP DownloadBackoff CRLF
-      [ "last-backoff-position" Uint CRLF
-        "last-delay-used UInt CRLF ]
+      a "serialized download status" as follows:
+
+       SerializedDownloadSatus =
+         -- when do we plan to next attempt to download this object?
+         "next-attempt-at" SP ISOTime CRLF
+         -- how many times have we failed since the last success?
+         "n-download-failures" SP UInt CRLF
+         -- how many times have we tried to download this?
+         "n-download-attempts" SP UInt CRLF
+         -- according to which schedule rule will we download this?
+         "schedule" SP DownloadSchedule CRLF
+         -- do we want to fetch this from an authority, or will any cache do?
+         "want-authority" SP DownloadWantAuthority CRLF
+         -- do we increase our download delay whenever we fail to fetch this,
+         -- or whenever we attempt fetching this?
+         "increment-on" SP DownloadIncrementOn CRLF
+         -- do we increase the download schedule deterministically, or at
+         -- random?
+         "backoff" SP DownloadBackoff CRLF
+         [
+           -- with an exponential backoff, where are we in the schedule?
+           "last-backoff-position" Uint CRLF
+           -- with an exponential backoff, what was our last delay?
+           "last-delay-used UInt CRLF
+         ]
 
       where
 
@@ -950,35 +964,37 @@
       In detail, the keys supported are:
 
       "downloads/networkstatus/ns"
-        The serialized download status for the FLAV_NS consensus for whichever
-        bootstrap state Tor is currently in.
+        The SerializedDownloadStatus for the NS-flavored consensus for
+        whichever bootstrap state Tor is currently in.
 
       "downloads/networkstatus/ns/bootstrap"
-        The serialized download status for the FLAV_NS consensus at bootstrap
-        time, regardless of whether we are currently bootstrapping.
+        The SerializedDownloadStatus for the NS-flavored consensus at
+        bootstrap time, regardless of whether we are currently bootstrapping.
 
       "downloads/networkstatus/ns/running"
-        The serialized download status for the FLAV_NS consensus when running,
-        regardless of whether we are currently bootstrapping.
+
+        The SerializedDownloadStatus for the NS-flavored consensus when
+        running, regardless of whether we are currently bootstrapping.
 
       "downloads/networkstatus/microdesc"
-        The serialized download status for the FLAV_MICRODESC consensus for
+        The SerializedDownloadStatus for the microdesc-flavored consensus for
         whichever bootstrap state Tor is currently in.
 
       "downloads/networkstatus/microdesc/bootstrap"
-        The serialized download status for the FLAV_MICRODESC consensus at
+        The SerializedDownloadStatus for the microdesc-flavored consensus at
         bootstrap time, regardless of whether we are currently bootstrapping.
 
       "downloads/networkstatus/microdesc/running"
-        The serialized download status for the FLAV_MICRODESC consensus when
+        The SerializedDownloadStatus for the microdesc-flavored consensus when
         running, regardless of whether we are currently bootstrapping.
 
       "downloads/cert/fps"
-        A newline-separated list of hex-encoded digests for authority certificates
-        for which we have download status available.
+
+        A newline-separated list of hex-encoded digests for authority
+        certificates for which we have download status available.
 
       "downloads/cert/fp/<Fingerprint>"
-        A serialized download status for the default certificate for the
+        A SerializedDownloadStatus for the default certificate for the
         identity digest <Fingerprint> returned by the downloads/cert/fps key.
 
       "downloads/cert/fp/<Fingerprint>/sks"
@@ -987,7 +1003,7 @@
         downloads/cert/fps key.
 
       "downloads/cert/fp/<Fingerprint>/<SKDigest>"
-        A serialized download status for the certificate for the identity
+        A SerializedDownloadStatus for the certificate for the identity
         digest <Fingerprint> returned by the downloads/cert/fps key and signing
         key digest <SKDigest> returned by the downloads/cert/fp/<Fingerprint>/
         sks key.
@@ -996,19 +1012,19 @@
         A newline-separated list of hex-encoded router descriptor digests
         [note, not identity digests - the Tor process may not have seen them
         yet while downloading router descriptors].  If the Tor process is not
-        using a FLAV_NS consensus, a 551 error is returned.
+        using a NS-flavored consensus, a 551 error is returned.
 
       "downloads/desc/<Digest>"
-        A serialized download status for the router descriptor with digest
+        A SerializedDownloadStatus for the router descriptor with digest
         <Digest> as returned by the downloads/desc/descs key.  If the Tor
-        process is not using a FLAV_NS consensus, a 551 error is returned.
+        process is not using a NS-flavored consensus, a 551 error is returned.
 
       "downloads/bridge/bridges"
         A newline-separated list of hex-encoded bridge identity digests.  If
         the Tor process is not using bridges, a 551 error is returned.
 
       "downloads/bridge/<Digest>"
-        A serialized download status for the bridge descriptor with identity
+        A SerializedDownloadStatus for the bridge descriptor with identity
         digest <Digest> as returned by the downloads/bridge/bridges key.  If
         the Tor process is not using bridges, a 551 error is returned.
 

_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits