document how to use TorService with foreground priority via binding

[eighthave]

Android gives "foreground" priority to the activity that is currently visible. Things that are at the foreground priority are the last to be killed. With Service instances, it is possible to set the service to be permanently at the "foreground" priority as long as there is a permanent notification. It is also possible for a Service to get foreground priority if the currently active screen is bound to the Service using BIND_IMPORTANT.

[eighthave]

Android's Binder model means that all the things that need Tor bind to it with BIND_IMPORTANT. That tells Android to keep it alive. Then for letting TorService quit when idle, there is a built-in mechanism to shutdown a Service when nothing is bound to it. The Android docs explicitly recommend bindService for IPC: https://developer.android.com/guide/components/processes-and-threads

More on bound services: https://developer.android.com/guide/components/bound-services

[n8fr8]

Orbot does this today. OrbotService is the application specific foreground service that then binds to TorService:
https://github.com/guardianproject/orbot/blob/master/orbotservice/src/main/java/org/torproject/android/service/OrbotService.java#L759

[eighthave]

The Chromium docs outline some nice security properties of bound services:
https://chromium.googlesource.com/chromium/src.git/+/refs/heads/main/docs/security/android-ipc.md#binder

[eighthave]

It seems to me that we should be recommending WorkManager here also. Google is putting a lot of work into it to make it the complete background task runner. This is based on this discussion #61 (comment)

WorkManager started out for short lived background tasks, but has been extended to handle foreground and long-lived tasks:

• https://developer.android.com/topic/libraries/architecture/workmanager/advanced/long-running
• https://developer.android.com/topic/libraries/architecture/workmanager/how-to/define-work#quotas

[holywend]

heya I was wondering is there any documentation on implementing torservice on android? I tried the sampleapp, which doesn't work for me as well.

[eighthave]

There isn't really documentation outside of the example code and apps at this point. We welcome contributions. You can see it in production code in the TorServices app, OnionShare, Orbot, and some others.

[holywend]

@eighthave atm I couldn't even start the sampleapp. even tho I just clone it from the repo.