[tor-commits] [torspec/master] Specify download/ GETINFO queries for controller

[nickm at torproject.org]

commit 12d462f192209ec99221795193322b4d95ccfff3
Author: Andrea Shepard <andrea at persephoneslair.org>
Date:   Wed Jun 29 21:31:28 2016 +0000

    Specify download/ GETINFO queries for controller
---
 control-spec.txt | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)

diff --git a/control-spec.txt b/control-spec.txt
index 5c9d3ab..9529d35 100644
--- a/control-spec.txt
+++ b/control-spec.txt
@@ -245,6 +245,10 @@
   ISOTime2 = IsoDatePart "T" IsoTimePart
   ISOTime2Frac = IsoTime2 [ "." 1*DIGIT ]
 
+  ; Numbers
+  LeadingDigit = "1" - "9"
+  UInt = LeadingDigit *Digit
+
 3. Commands
 
   All commands are case-insensitive, but most keywords are case-sensitive.
@@ -892,6 +896,101 @@
       The string "up" or "down", indicating whether we currently believe the
       network is reachable.
 
+      "download/"
+      The keys under download/ 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 ]
+
+      where
+
+      DownloadSchedule =
+        "DL_SCHED_GENERIC" / "DL_SCHED_CONSENSUS" / "DL_SCHED_BRIDGE"
+      DownloadWantAuthority =
+        "DL_WANT_ANY_DIRSERVER" / "DL_WANT_AUTHORITY"
+      DownloadIncrementOn =
+        "DL_SCHED_INCREMENT_FAILURE" / "DL_SCHED_INCREMENT_ATTEMPT"
+      DownloadBackoff =
+        "DL_SCHED_DETERMINISTIC" / "DL_SCHED_RANDOM_EXPONENTIAL"
+
+      The optional last two lines must be present if DownloadBackoff is
+      "DL_SCHED_RANDOM_EXPONENTIAL" and must be absent if DownloadBackoff
+      is "DL_SCHED_DETERMINISTIC".
+
+      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.
+
+      "downloads/networkstatus/ns/bootstrap"
+      The serialized download status for the FLAV_NS 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.
+
+      "downloads/networkstatus/microdesc"
+      The serialized download status for the FLAV_MICRODESC consensus for
+      whichever bootstrap state Tor is currently in.
+
+      "downloads/networkstatus/microdesc/bootstrap"
+      The serialized download status for the FLAV_MICRODESC 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
+      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.
+
+      "downloads/cert/fp/<Fingerprint>"
+      A serialized download status for the default certificate for the
+      identity digest <Fingerprint> returned by the downloads/cert/fps key.
+
+      "downloads/cert/fp/<Fingerprint>/sks"
+      A newline-separated list of hex-encoded signing key digests for the
+      authority identity digest <Fingerprint> returned by the
+      downloads/cert/fps key.
+
+      "downloads/cert/fp/<Fingerprint>/<SKDigest>"
+      A serialized download status 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.
+
+      "downloads/desc/descs"
+      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.
+
+      "downloads/desc/<Digest>"
+      A serialized download status 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.
+
+      "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
+      digest <Digest> as returned by the downloads/bridge/bridges key.  If
+      the Tor process is not using bridges, a 551 error is returned.
+
   Examples:
      C: GETINFO version desc/name/moria1
      S: 250+desc/name/moria=