[tor-commits] [torspec/master] Add control spec entry for HSPOST, and update HS_DESC events. (#3523)

[nickm at torproject.org]

commit ba30c1df4a11248c0a6c9b458530a7985ae41fac
Author: Donncha O'Cearbhaill <donncha at donncha.is>
Date:   Sun Mar 22 18:49:38 2015 +0000

    Add control spec entry for HSPOST, and update HS_DESC events. (#3523)
---
 control-spec.txt |   47 ++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 40 insertions(+), 7 deletions(-)

diff --git a/control-spec.txt b/control-spec.txt
index 276490a..8a55e94 100644
--- a/control-spec.txt
+++ b/control-spec.txt
@@ -1400,6 +1400,36 @@
 
   [DEL_ONION was added in Tor 0.2.7.1-alpha.]
 
+3.29. HSPOST
+
+  The syntax is:
+    "+HSPOST" *[SP "SERVER=" Server] CRLF Descriptor CRLF "." CRLF
+
+    Server = LongName
+    Descriptor =  The text of the descriptor formatted as specified
+    in rend-spec.txt section 1.3.
+
+  This command launches a hidden service descriptor upload to the specified
+  HSDirs. If one or more Server arguments are provided, an upload is triggered
+  on each of them in parallel. If no Server options are provided, it behaves
+  like a normal HS descriptor upload and will upload to the set of responsible
+  HS directories.
+
+  If any value is unrecognized, a 552 error is returned and the command is
+  stopped. If there is an error in parsing the descriptor, the server
+  must send a "554 Invalid descriptor" reply.
+
+  On success, Tor replies "250 OK" then Tor MUST eventually follow
+  this with a HS_DESC event with the result for each upload location.
+
+  Examples are:
+     C: +HSPOST SERVER=9695DFC35FFEB861329B9F1AB04C46397020CE31
+        [DESCRIPTOR]
+        .
+     S: 250 OK
+
+  [HSPOST was added in Tor 0.2.7.1-alpha]
+
 4. Replies
 
   Reply codes follow the same 3-character format as used by SMTP, with the
@@ -2690,18 +2720,20 @@
 
   The syntax is:
 
-    "650" SP "HS_DESC" SP Action SP HSAddress SP AuthType SP HsDir [SP DescriptorID]
-    [SP "REASON=" Reason]
+    "650" SP "HS_DESC" SP Action SP HSAddress SP AuthType SP HsDir
+             [SP DescriptorID] [SP "REASON=" Reason]
 
-    Action =  "REQUESTED" / "RECEIVED" / "IGNORE" / "FAILED"
-    HSAddress = 16*Base32Character / "UNKNOWN"
+    Action =  "REQUESTED" / "UPLOAD" / "RECEIVED" / "UPLOADED" / "IGNORE" /
+              "FAILED"
+    HSAddress = 16*Base32Character
     AuthType = "NO_AUTH" / "BASIC_AUTH" / "STEALTH_AUTH" / "UNKNOWN"
     HsDir = LongName / Fingerprint
     DescriptorID = 32*Base32Character
-    Reason = "BAD_DESC" / "QUERY_REJECTED" / "NOT_FOUND" / "UNEXPECTED"
+    Reason = "BAD_DESC" / "QUERY_REJECTED" / "UPLOAD_REJECTED" / "NOT_FOUND" /
+             "UNEXPECTED"
 
     These events will be triggerred when required HiddenService descriptor is
-    not found in the cache and a fetch from network is performed.
+    not found in the cache and a fetch or upload with the network is performed.
 
     If the fetch was triggered with only a DescriptorID (using the HSFETCH
     command for instance), the HSAddress only appears in the Action=RECEIVED
@@ -2714,10 +2746,11 @@
     For HsDir, LongName is always prefered. If HsDir cannot be found in node
     list at the time event is sent, Fingerprint will be used instead.
 
-    If Action is "FAILED", Tor SHOULD send Reason field as well. Possible 
+    If Action is "FAILED", Tor SHOULD send Reason field as well. Possible
     values of Reason are:
        - "BAD_DESC" - descriptor was retrieved, but found to be unparsable.
        - "QUERY_REJECTED" - query was rejected by HS directory.
+       - "UPLOAD_REJECTED" - descriptor was rejected by HS directory.
        - "NOT_FOUND" - HS descriptor with given identifier was not found.
        - "UNEXPECTED" - nature of failure is unknown.