Collect feedback on mobile embedding API; resolve issues.

This is a master ticket for improving the design and reliability of the embedding API in tor_api.h. We already have a few projects starting to try this code, but we need more feedback about it in order to know where the developer-facing issues are. As we learn more about such issues, we should fix them.

changed milestone to %Tor: unspecified

added 034-included-20180328 034-triage-20180328 035-roadmap-master 035-triaged-in-20180711 component::core tor/tor milestone::Tor: unspecified priority::medium roadmap severity::normal status::new type::project labels

Trac:
Keywords: roadmap deleted, roadmap 034-roadmap-master added

Trac:
Keywords: roadmap 034-roadmap-master deleted, 034-roadmap-master, roadmap, 034-triage-20180328 added

Trac:
Keywords: N/A deleted, 034-included-20180328 added

Trac:
Milestone: Tor: 0.3.4.x-final to Tor: 0.3.5.x-final

Trac:
Keywords: 034-roadmap-master deleted, 035-roadmap-master added
Sponsor: N/A to Sponsor8-must

Trac:
Keywords: N/A deleted, 035-triaged-in-20180711 added

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.

Trac:
Cc: N/A to dmr

Replying to hellais:

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.

Making this easier is now the focus of #23846 (moved).

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.

Hellais opened #26948 (moved) for this.

== Feedback

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

Now in needs_review.

• Ability to know when the control port is ready
• Ability to terminate tor cleanly without using the control port

These two are covered by #24204 (moved).

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

Opened #26999 (moved) for this.

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

Opened #26997 (moved) for this.

These are not on track for 0.3.5, given the amount of time remaining before freeze.

Trac:
Milestone: Tor: 0.3.5.x-final to Tor: 0.3.6.x-final

I finally took a look at the API. I really like it. I created some example programs while I was looking at it and thinking about whether anything was missing. I documented some of that on #26653 (moved). They're in my public tor repo on branch testing_26653.

#24204 (moved) was a big win.

I think the API can use a little more documentation, and I created #27801 (moved) as a maybe-this-will-be-useful-for-someone.

Overall, I don't think we need anything else for TBA. Thanks!

Tor 0.3.6.x has been renamed to 0.4.0.x.

Trac:
Milestone: Tor: 0.3.6.x-final to Tor: 0.4.0.x-final

Trac:
Sponsor: Sponsor8-must to N/A

Trac:
Milestone: Tor: 0.4.0.x-final to Tor: unspecified

These tickets are not things I'm currently working on. They may be important, but they don't need to be done by me specifically. Un-assigning.

Trac:
Owner: nickm to N/A

Change tickets that are assigned to nobody to "new".

Trac:
Status: assigned to new

mentioned in issue #25512 (moved)

mentioned in issue #25607 (moved)

mentioned in issue #26997 (moved)

mentioned in issue #26999 (moved)

mentioned in issue #28019 (moved)

moved to tpo/core/tor#25510 (closed)

mentioned in issue tpo/core/tor#26997 (closed)

mentioned in issue tpo/core/tor#26999 (closed)

mentioned in issue tpo/core/tor#28019 (closed)