Formally define PT_LOG and PT_STATUS eventsbug29136

Attempting a formal definition of these events for...

  https://trac.torproject.org/projects/tor/ticket/29136

To be clear I do *not* know of this specification is accurate. My goal here is
to exemplify a specificaiton patch that defines these events using the grammar
used throughout this specification.

Our pluggable transport folks will need to review this. In particular a few
questions that came to mind while writing this are...

  * Do PT_STATUS events exist or not? The prior spec confusingly said they're
    both a thing and unimplemented. We should either implement PT_STATUS or
    remove it from this specification (and tor's codebase, if present).

  * Are other severities permissible? And are we sure we want the 'severity'
    to be lowercase? Other events use upercase enumerations. Changing this
    would probably require a change in tor.

  * I've defined all PT_LOG and PT_STATUS attributes to be optional. Should
    any of them be mandatory? If so then please drop their square brackets.

1 files changed, 23 insertions, 36 deletions

diff --git a/control-spec.txt b/control-spec.txt
index f01bec7..f4f81c3 100644
--- a/control-spec.txt
+++ b/control-spec.txt
@@ -3285,36 +3285,26 @@
 
 4.1.28. Pluggable Transport Logs
 
-   Syntax:
-      "650" SP "PT_LOG" SP Message
-
-      Message = The log message that the PT sends back to the Tor parent
-                process minus the "LOG" string prefix. Formatted as
-                specified in pt-spec.txt section 3.3.4 using the key/value
-                encoding specified in pt-spec.txt section 3.3.5.
-
-                The following keys are defined for the LOG message:
-
-                  PT (string)      = A string containing the path to the
-                                     executable that is emitting the current
-                                     log message.
+  The syntax is:
 
-                  MESSAGE (string) = A string containing the log message in
-                                     a human readable format.
+    "650" SP "PT_LOG" [SP "PT=" PluggableTransport] [SP "MESSAGE=" Message]
+             [SP "SEVERITY=" Severity]
 
-                  SEVERITY (enum)  = Can be one of the following strings:
-                                     error, warning, notice, info, debug.
+    PluggableTransport = QuotedString
+    Message = QuotedString
+    Severity = "error" / "warning" / "notice" / "info" / "debug"
 
-                Please note that the order of the key/value pairs is an
-                implementation detail.
+   This event is triggered when tor receives a log message from the PT. Clients
+   MUST allow the key/value pairs to appear in any order.
 
-   This event is triggered when tor receives a log message from the PT.
+   "PluggableTransport" is an absolute path to the executable emitting this log
+   message.
 
-   Example:
+   For example...
 
       PT (obfs4): LOG SEVERITY=debug MESSAGE="Connected to bridge A"
 
-    the resulting control port event would be:
+   ... would result in a control port event of...
 
       Tor: 650 PT_LOG PT=/usr/bin/obs4proxy SEVERITY=debug MESSAGE="Connected to bridge A"
 
@@ -3322,28 +3312,25 @@
 
 4.1.29. Pluggable Transport Status
 
-   Syntax:
-      "650" SP "PT_STATUS" SP PT=Program SP TRANSPORT=Transport SP Message
+  The syntax is:
+
+    "650" SP "PT_STATUS" [SP "PT=" PluggableTransport] [SP "TRANSPORT=" Transport]
+             [SP "MESSAGE=" Message]
 
-      Program = The program path as defined in the *TransportPlugin
-                configuration option. Tor accepts relative and full path.
-      Transport = This value indicate a hint on what the PT is such has the
-                  name or the protocol used for instance.
-      Message = The status message that the PT sends back to the tor parent
-                process minus the "STATUS" string prefix. Formatted as
-                specified in pt-spec.txt section 3.3.5.
+    PluggableTransport = QuotedString
+    Transport = QuotedString
+    Message = QuotedString
 
    This event is triggered when Tor receives a STATUS message from the PT.
 
-   Currently no PT specific STATUS messages are defined and this message can
-   thus safely be ignored. In the future we will specify concrete message
-   structures for the different PT implementations that are available.
+   "PluggableTransport" is an absolute path to the executable emitting this log
+   message. "Transport" is the name of the protocol being used.
 
-   Example:
+   For example...
 
       PT (obfs4): STATUS TRANSPORT=obfs4 CONNECT=Success
 
-   the resulting control port event would be:
+   ... would result in a control port event of...
 
       Tor: 650 PT_STATUS PT=/usr/bin/obs4proxy TRANSPORT=obfs4 CONNECT=Success