[tor-bugs] #28181 [Core Tor/Tor]: spec: Add to pt-spec.txt control messages going back to main process (tor)

[Tor Bug Tracker & Wiki]

#28181: spec: Add to pt-spec.txt control messages going back to main process (tor)
-------------------------------------------------+-------------------------
 Reporter:  dgoulet                              |          Owner:  dgoulet
     Type:  enhancement                          |         Status:
                                                 |  needs_review
 Priority:  Medium                               |      Milestone:  Tor:
                                                 |  0.4.0.x-final
Component:  Core Tor/Tor                         |        Version:
 Severity:  Normal                               |     Resolution:
 Keywords:  tor-spec, tor-pt, 040-roadmap-       |  Actual Points:
  subtask                                        |
Parent ID:  #28180                               |         Points:
 Reviewer:  ahf                                  |        Sponsor:
                                                 |  Sponsor8
-------------------------------------------------+-------------------------

Comment (by dcf):

 The quoting rules (String or QuotedString) are fine with me. That was my
 biggest question at comment:2:ticket:28940. I might even suggest that you
 make it easier on implementers by not allowing String, only QuotedString
 (reduces code complexity on the parsing side especially).

 The format example has a `,` but the syntax doesn't actually use `,`:
 {{{
 STATUS TYPE=Type <K_1>=<V_1> [<K_2>=<V_2>, ...]
 }}}

 I would like to better understand the reason for `STATUS`. What should a
 PT expect the managing process (tor) to do when it receives a `STATUS`
 message? What would motivate a PT to send such a message? Or is the
 feature unspecified deliberately, on the assumption that we will need it
 for something someday, or that a standard will emerge among developers?

 I suppose `STATUS` is meant to fill the desire for a more "machine-
 readable" type of message. If that's the case, then I would suggest some
 changes to the examples, which are currently:
 {{{
 STATUS TYPE=obfs4 CONNECT=Success
 STATUS TYPE=obfs4 CONNECT=Failed BRIDGE=<Fingerprint>
 STATUS TYPE="some name" PROGRESS="Getting to 42%"
 }}}

 My suggestions are:
 {{{
 STATUS TRANSPORT=obfs4 ADDRESS=198.51.100.123:1234 CONNECT=Success
 STATUS TRANSPORT=obfs4 ADDRESS=198.51.100.222:2222 CONNECT=Failed
 FINGERPRINT=<Fingerprint> ERRSTR="Connection refused"
 STATUS TRANSPORT=trebuchet ADDRESS=198.51.100.15:443 PERCENT=42
 }}}

 My reasoning:
  * Use `TRANSPORT` instead of `TYPE` to match the terminology in pt-
 spec.txt. `METHOD` would also work.
  * To specific a single bridge connection attempt (for success/failure
 reporting), you need to give both the `TRANSPORT` and the `ADDRESS`. If
 you give just the `TRANSPORT` there is ambiguity among the many bridges of
 that transport that may be configured. Just a fingerprint is no good,
 because a fingerprint is optional on a `Bridge` line, and if we failed to
 connect we may not know it.
  * Don't use `"some name"` as an example of a transport name, because that
 doesn't match "PT names MUST be valid C identifiers". I added `ERRSTR` for
 the sake of showing a quoted string.
  * If aiming for machine readability, prefer `42` to `"Getting to 42%"`.

--
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/28181#comment:20>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online