[tor-commits] [torspec/master] 19537: Try to document and clarify GETINFO downloads/*
nickm at torproject.org
nickm at torproject.org
Wed Aug 23 14:10:30 UTC 2017
commit 675c470fe61d2368a5bd16ee297e02f0a94911a2
Author: Nick Mathewson <nickm at torproject.org>
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.
More information about the tor-commits
mailing list