
                Adding an Interface for Tor Status Events


1. Introduction & Motivation

This document is intended to describe the addition of an interface to display
summaries of Tor status events in Vidalia. The status event interface is
intended to supplant the existing message log interface. The messages that
appear in the message log are often useful for developers helping users
determine why their Tor is not functioning as expected, but the messages
themselves are usually too confusing for average users.

The goal of the status event interface is to provide two functions. First, it
should promptly notify users when their Tor process is not working properly
(e.g., unable to fetch any directory information). Currently, relevant error
messages from Tor are simply appended to the message log without any
indication to the user that there is something in the log they should look at.
Second, in the case of a warning or error status event, the status event
interface should help the user understand what the problem is and make
specific suggestions for the user to correct the problem.


2. Overview

2.1. Main Interface

The main Vidalia UI will be a single window with multiple tabs or toolbar
buttons at the top. The first tab will always be a "Home" tab. The Home tab
displays general information on Tor, such as whether or not Tor is running,
Tor version information (if Tor is running), whether Vidalia is also running a
proxy application (e.g., Polipo), and information on whether the user is
currently running a Tor relay.

Below the general information is where the status event information will be
located. Status events will be added as a series of items to a QListBox. Each
item in the list box has a 48x48 icon indicating the type of status event.
Available types are STATUS_GENERAL, STATUS_CLIENT and STATUS_SERVER. If the
event has a WARN or ERR, a "badge" will be added to the lower-right corner of
the status event icon. WARN events will have a "yellow triangle with a black
exclamation point" badge. ERR events will have a "red circle with white X"
badge added to the status event icon.

To the right of the icon (or to the left, if the current translation is a RTL
language), will be two to three lines of text. The first line will be in a
bold typeface and will contain a short, one sentence summary of the event. For
example, "Your Tor server is inaccessible" could be the summary sentence for
REACHABILITY_FAILED events.

Below the summary line is up to two lines of descriptive text. In the event of
WARN or ERR status events, the descriptive text gives the user possible
suggestions as to what caused the status event and how they can fix it. If the
descriptive text does not fit in two lines, the part of the message that does
not fit will be replaced with an ellipses ("..."). Clicking on the status
event once will expand the QListBox item vertically allowing the item's full
descriptive text to be seen. Hovering over an item will also display the full
text in a tooltip.

On the far right (or, again, far left in the case of RTL languages), will be a
clickable gray "X". Users can click on the "X" to remove the associated event
from the QListBox. Some events may be removed from the list automatically,
since they can be superseded by another event. As an example, consider an item
representing a REACHABILITY_FAILED status event indicating to the user that
their Tor relay is not reachable from outside their network. If Tor
subsequently emits a REACHABILITY_SUCCEEDED status event, the
REACHABILITY_FAILED event is no longer relevant or accurate and may be removed
from the list. In any case, the list of status events will automatically be
cleared each time Tor is restarted.

The list of status events can also be filtered by the user in order to display
only WARN and/or ERR events. The filtering is accomplished via three clickable
QAction buttons near the status event list. Each button is labeled with the
same badge icon that is used to denote status event severity on the list
item's icon.


2.2. Tray Icon Notifications

As mentioned earlier, currently important warning or error messages are simply
appended to the user's message log without any indication to the user that
they should go look at the log. Consequently, we will use badges on the tray
or dock icon to indicate to the user that there are status event messages they
should look at more closely.

In the case of ERR or WARN status events, a message "balloon" or "bubble" may
also be displayed if the user's window manager permits it. While icon badges
are common on OS X dock icons, dock icons do not support message balloons.
Instead, we will make the dock icon bounce in order to get the user's
attention, which is a common notification mechanism on OS X.


3. Displayed Status Events

Tor currently exposes many status events via its control interface. Like log
messages, however, not all of them are of interest to the user. In this
section, we describe the particular set of status events that will be handled
and displayed to the user in the status event summary interface. Note that
some status events, such as BOOTSTRAP and DANGEROUS_VERSION events are already
handled by Vidalia and displayed to the user via other means, such as a
progress bar or a message boxes, respectively.


3.1. DIR_ALL_UNREACHABLE

Tor sends this events when it is unable to connect to any of the known
directory servers, likely because the user's local network is down. Vidalia
should suggest to the user that they verify their computer is connected to the
Internet.


3.3. ENOUGH_DIR_INFO

This event indicates that Tor has enough directory information to begin
building circuits, but hasn't built one yet. This event can be superseded by a
subsequent CIRCUIT_ESTABLISHED event.


3.4. NOT_ENOUGH_DIR_INFO

Tor sends this event when it believes it does not have sufficient directory
information to build circuits.


3.5. CIRCUIT_ESTABLISHED

This event indicates that Tor has successfully retrieved enough directory
information and has constructed a circuit. No further user action needs to be
taken, but a status event message should still be added indicating to the user
that their Tor client is functioning properly. Additionally, Vidalia currently
changes its tray or dock to green when this event is received.


3.6. CHECKING_REACHABILITY
      "ORADDRESS=IP:port"
      "DIRADDRESS=IP:port"

This status event will indicate to the user that Tor is checking to see if
their Tor relay is accessible from outside their network. No further action
needs to be taken unless a REACHABILITY_FAILED status event is subsequently
received.


3.7. REACHABILITY_FAILED
      "ORADDRESS=IP:port"
      "DIRADDRESS=IP:port"

When Vidalia receives a REACHABILITY_FAILED status event, it will notify the
user and suggest ways to make their relay reachable by Tor clients. Most often
this means they have a NAT or firewall that needs the user's ORPort and
possibly DirPort opened. Vidalia could offer to use its UPnP functionality to
attempt to configure the user's network for them.


3.8. REACHABILITY_SUCCEEDED
      "ORADDRESS=IP:port"
      "DIRADDRESS=IP:port

This event should indicate to the user that their relay was found to be
reachable. No further user action needs to be taken.


3.9. GOOD_SERVER_DESCRIPTOR and ACCEPTED_SERVER_DESCRIPTOR
                                "DIRAUTH=addr:port"
Tor will send these event after the user's Tor relay has successfully uploaded
its server descriptor to at least one of the directory authorities. This
typically means that the user's relay is functioning properly. No further user
action needs to be taken.


3.10. BAD_SERVER_DESCRIPTOR
      "DIRAUTH=addr:port"
      "REASON=string"

When Vidalia receives this event, it should notify the user. The most likely
reason for this problem is the user's clock is not set correctly. The status
event text should suggest to the user that they should verify their system's
clock is accurate.


3.11. BUG
      "REASON=STRING"

Tor sends this status event when an internal check has indicated that there is
likely a Tor software bug. The descriptive text will suggest to the user how
and where to report the bug, as well as what information to include in the bug
report. It may also be useful to generate additional information
automatically, such as the user's operating system version, Tor software
version, etc. The user can then just copy-paste that information into the bug
report.

It is possible that a bug can be triggered repeatedly, so Vidalia will make
sure that only one status event for a particular bug will be displayed. Bug
status events will be compared based on the string provided in the event's
REASON field.


3.12. CLOCK_SKEW
      SKEW="+" / "-" SECONDS
      MIN_SKEW="+" / "-" SECONDS.
      SOURCE="DIRSERV:IP:Port" / "NETWORKSTATUS:IP:PORT" / "CONSENSUS"

If the user's clock skew is high relative to the directory authorities,
Vidalia should notify the user and suggest that they check the accuracy of
their system clock. If the skew is low, then this event should be ignored and
no further action needs to be taken.


4. Unhandled Status Events

The status events described in the previous section are a subset of the status
events Tor currently is capable of reporting. Further, it is quite likely that
Tor will add status events after a particular Vidalia version is released.
Since all status events follow a similar, well-defined interface, it is
possible for Vidalia to still parse these and display them to the user in some
generic format; however, this is not likely to be useful to the user. Recall
that the purpose of adding the status event interface is to be able to provide
specific and directed suggestions to users about how to fix a particular
problem that occurs with their Tor process. If Vidalia just blindly displays
some status events without adding any details on the problem or how to fix it,
the interface is not likely to be any more useful than the existing message
log interface.

As a result, the default behavior should be for Vidalia to simply discard
status events that it does not recognize. We may want to consider adding a
"verbose" option that does display all status events for the user. It's not
clear that this would be benefical to the user, though.

