[tor-bugs] #25510 [Core Tor/Tor]: Collect feedback on mobile embedding API; resolve issues.

[Tor Bug Tracker & Wiki]

#25510: Collect feedback on mobile embedding API; resolve issues.
-------------------------------------------------+-------------------------
 Reporter:  nickm                                |          Owner:  nickm
     Type:  project                              |         Status:
                                                 |  assigned
 Priority:  Medium                               |      Milestone:  Tor:
                                                 |  0.3.5.x-final
Component:  Core Tor/Tor                         |        Version:
 Severity:  Normal                               |     Resolution:
 Keywords:  roadmap, 035-roadmap-master,         |  Actual Points:
  034-triage-20180328, 034-included-20180328,    |
  035-triaged-in-20180711                        |
Parent ID:                                       |         Points:
 Reviewer:                                       |        Sponsor:
                                                 |  Sponsor8-must
-------------------------------------------------+-------------------------

Comment (by hellais):

 I started the new tor_api.h and have been chatting with ahf on IRC about
 this.

 Here is how far I got with testing it.

 == Setup

 First, to setup an environment for testing I needed to build it as a
 shared library.

 This was done by building tor with `make V=1 CFLAGS=-fPIC`.

 I then deleted `src/app/tor`, re-ran `make V=1 CFLAGS=-fPIC` and reran
 that line adding `-shared` to it. That lead me to having a `dylib` (or
 `.so` on linux) in `src/app/tor`.

 This artifact can now be used for testing libtor.

 == Testing

 I wrote a testing harness that uses python and `cffi`, to implement some
 basic smoke tests for libtor. This can be found here:
 https://gist.github.com/hellais/b56043d57eb5be885958e80b3665bfe2 (to run
 it do `pip install cffi` and change the `LIB_PATH` to the correct path).

 In particular by adding the command line flag `--version` and starting
 tor, I am unable to re-start it due to the exception listed in the above
 gist.

 == Feedback

 WRT API design I have the following thoughts on possible areas for
 improvement. I have for the time being only created tickets for the things
 I think should be part of an MVP, while the others can possibly be
 deferred to a future version and if you think they are good ideas I will
 proceed with creating tickets for them.
 I may also be missing some best practice here.

 * Add function for reporting the tor version -
 https://trac.torproject.org/projects/tor/ticket/26947

 * Ability to know when the control port is ready

 Currently it's not possible for a user of the API to know when the control
 port is ready if not by looking at the standard output and/or polling the
 port/socket where the control port is supposed to be at. It would be great
 if there were some function (or some documented approach) to doing this.

 * Ability to get the output of tor_run_main() without having to mock
 standard out

 There is a wealth of information inside of the log output of tor, which
 would be nice if it were exposed in a more API friendly way (maybe some
 sort of callback function?) so that a user of the library doesn't have to
 mock stdout/stderr.

 * Ability to terminate tor cleanly without using the control port

 I am aware of the fact that there is a control port command to stop tor,
 but it would be great if there were also an API call to be used to tell
 tor to shutdown cleanly (similarly to calling kill -SIGTERM tor).

 * Add API calls for making it easier to setup the configuration for tor

 This is more of usability issue, but it would be great if the tor_api.h
 has some function for setting configuration options for Tor, without
 having to rely on passing them as command line arguments.

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