Opened 18 months ago

Closed 14 months ago

Last modified 14 months ago

#22232 closed task (fixed)

gather info on how Tor Launcher uses bootstrap status messages

Reported by: catalyst Owned by: brade
Priority: Medium Milestone:
Component: Applications/Tor Launcher Version:
Severity: Normal Keywords: usability, ux
Cc: mcs, isabela Actual Points:
Parent ID: #21951 Points:
Reviewer: Sponsor: Sponsor4

Description

As part of the effort to improve the user experience during Tor Launcher bootstrap (#21951), it would be helpful to know some details of how Tor Launcher currently uses bootstrap status messages (STATUS_CLIENT BOOTSTRAP asynchronous messages from the control protocol). Among other things, it could help Core Tor make short-term incremental changes to vastly improve the user experience.

  • Does the progress bar currently map phase numbers directly into percent-done on the bar?
  • Does it do anything with TAG= keywords in the BOOTSTRAP messages?
  • Does it do anything with SUMMARY= strings other than displaying them in the dialog box?
  • How does it know when to display the "copy logs" button with the warning icon?
  • Which other of the BOOTSTRAP keywords does it use and how?
  • Does it use any other asynchronous control protocol messages?

Child Tickets

Change History (11)

comment:1 Changed 18 months ago by mcs

Cc: mcs added

comment:2 in reply to:  description Changed 17 months ago by brade

To start monitoring events, Tor Launcher issues the following control port command: SETEVENTS STATUS_CLIENT NOTICE WARN ERR
Tor Launcher then looks for 650 responses.

When one of the following responses is received, it is logged to the browser console and added to an in-memory log buffer (which is used to implement "copy log"):
WARN, ERR, DEBUG, INFO, NOTICE

Tor Launcher also issues a GETINFO status/bootstrap-phase command soon after the control port connection has been established.

When a STATUS_CLIENT message is received, Tor Launcher uses the info contained within the message to detect bootstrap errors and to show progress. The GETINFO status/bootstrap-phase response is used for this same purpose (both kinds of response messages are parsed and processeed by the same code).

Tor Launcher maintains two important pieces of state information about the bootstrap process:

  • mIsBootstrapDone (Boolean) This is set to true when a STATUS_CLIENT BOOTSTRAP event with PROGRESS=100 is received. It is set to false when any other STATUS_CLIENT BOOTSTRAP event is received.
  • mBootstrapErrorOccurred (Boolean) This is set to true when a STATUS_CLIENT BOOTSTRAP event with a severity of WARN or ERR, and RECOMMENDATION of warn is received. It is set to false when mIsBootstrapDone is set to true as well as after the user makes changes to their settings (after a SAVECONF is done).

Replying to catalyst:

Does the progress bar currently map phase numbers directly into percent-done on the bar?

Tor Launcher uses the PROGRESS field of the STATUS_CLIENT event for displaying the percent-done on the bar. Do those numbers directly correspond to phases?

Does it do anything with TAG= keywords in the BOOTSTRAP messages?

The TAG= keywords are used for two purposes:

  1. The values are mapped to localized strings and displayed in the progress window.
  2. The TAG value along with REASON is used to suppress repeated errors. When Tor Launcher sets mBootstrapErrorOccurred to true (see above), an error is shown to the user unless the previous error displayed had the same TAG and REASON values.

Does it do anything with SUMMARY= strings other than displaying them in the dialog box?

No. If Tor Launcher can't map the TAG to a localized string, it will display the SUMMARY text instead; otherwise, it is not used at all.

How does it know when to display the "copy logs" button with the warning icon?

The "copy log" button is displayed with the warning icon when Tor Launcher detects a bootstrap error (see mBootstrapErrorOccurred above) or when it receives a log message event with severity of WARN or ERR.

Which other of the BOOTSTRAP keywords does it use and how?

The severity value within a STATUS_CLIENT BOOTSTRAP event is used to detect bootstrap errors (as described above) and also to determine the level for local logging.

When displaying errors, Tor Launcher tries to map the REASON values to localized strings. If this fails, the WARNING text is displayed instead. HOSTADDR is appended to the error text when it is present.

RECOMMENDATION is part of the information that is used to determine if a bootstrap error has occurred (as described above).

Does it use any other asynchronous control protocol messages?

Only the log events that were mentioned above.

Mark and I know this is somewhat complicated, so we expect some follow up questions.

comment:3 Changed 17 months ago by catalyst

Cc: isabela added

comment:4 Changed 15 months ago by mcs

Status: newneeds_information

catalyst: Is it okay to close this ticket or is more information needed about how Tor Launcher currently uses bootstrap status messages?

comment:5 Changed 15 months ago by gk

Sponsor: Sponsor4

comment:6 in reply to:  4 ; Changed 15 months ago by catalyst

Replying to mcs:

catalyst: Is it okay to close this ticket or is more information needed about how Tor Launcher currently uses bootstrap status messages?

I think I would rather someone copy the information into a wiki page before closing this ticket. I can do that if you prefer. (though I'm not sure where best to put it)

comment:7 in reply to:  6 ; Changed 14 months ago by mcs

Replying to catalyst:

I think I would rather someone copy the information into a wiki page before closing this ticket. I can do that if you prefer. (though I'm not sure where best to put it)

I am worried that a wiki page will be difficult to find and that it will quickly become outdated. Instead, Kathy and I would prefer to add a README-BOOTSTRAP file at the top of the Tor Launcher source tree. catalyst, would that meet your needs?

comment:8 in reply to:  7 Changed 14 months ago by catalyst

Status: needs_informationnew

Replying to mcs:

I am worried that a wiki page will be difficult to find and that it will quickly become outdated. Instead, Kathy and I would prefer to add a README-BOOTSTRAP file at the top of the Tor Launcher source tree. catalyst, would that meet your needs?

I think that would be fine. Thanks!

comment:9 Changed 14 months ago by mcs

Resolution: fixed
Status: newclosed

Kathy and I added README-BOOTSTRAP via commit ab8e081f3007f45e98171e163f080fea8caad964 on Tor Launcher master. You can view the file here:
https://gitweb.torproject.org/tor-launcher.git/plain/README-BOOTSTRAP

comment:10 Changed 14 months ago by cypherpunks

The PROGRESS field of the STATUS_CLIENT messages are used directly

*is used

comment:11 in reply to:  10 Changed 14 months ago by mcs

Replying to cypherpunks:

The PROGRESS field of the STATUS_CLIENT messages are used directly

*is used

Thanks! Fixed via commit a120bb02f4dbcb3e26fe0c031d383a9a8681678a on Tor Launcher master (we also changed the wording of that sentence slightly to avoid confusion).

Note: See TracTickets for help on using tickets.