Merge pull request #62 from 05nelsonm/mn/feature/background-manager-additional-options

Add option to BackgroundManager to run service in the Foreground

Author: 05nelsonm

sampleapp/src/main/java/io/matthewnelson/sampleapp/App.kt

@@ -121,8 +121,10 @@ class App: Application() {
     private fun generateBackgroundManagerPolicy(): BackgroundManager.Builder.Policy {
 //  private fun generateBackgroundManagerPolicy(): BackgroundManager.Builder.Policy {
         return BackgroundManager.Builder()
-            .respectResourcesWhileInBackground(secondsFrom5To45 = 20)
 
+            // All available options present. Only 1 is able to be chosen.
+            //.respectResourcesWhileInBackground(secondsFrom5To45 = 20)
+            .runServiceInForeground(killAppIfTaskIsRemoved = true)
 //  }
     }
 

topl-service/src/main/java/io/matthewnelson/topl_service/lifecycle/BackgroundManager.kt

@@ -67,6 +67,7 @@
 package io.matthewnelson.topl_service.lifecycle
 
 import android.content.Context
+import android.os.Process
 import androidx.lifecycle.Lifecycle
 import androidx.lifecycle.LifecycleObserver
 import androidx.lifecycle.OnLifecycleEvent
@@ -79,20 +80,22 @@ import io.matthewnelson.topl_service.util.ServiceConsts
 
 /**
  * When your application is sent to the background (the Recent App's tray or lock screen), the
- * chosen [BackgroundManager.Builder.Policy] will be executed after the number of seconds you've
- * declared.
+ * chosen [BackgroundManager.Builder.Policy] will be triggered.
+ *
+ * Additionally, there are 2 values for you to query if needed to give you context surrounding
+ * your application's background state; [taskIsInForeground] and [taskIsRemovedFromRecentApps].
  *
  * If brought back into the foreground by the user:
  *
  *   - **Before Policy execution**: Execution is canceled. If [BaseService.lastAcceptedServiceAction]
  *   was **not** [ServiceConsts.ServiceActionName.STOP], a startService call is made to ensure it's
  *   started.
  *
- *   - **After Policy execution**: If [BaseService.lastAcceptedServiceAction]
- *   was **not** [ServiceConsts.ServiceActionName.STOP], a startService call is made to ensure it's
- *   started.
+ *   - **After Policy execution**: If [BaseService.lastAcceptedServiceAction] was **not**
+ *   [ServiceConsts.ServiceActionName.STOP], a startService call is made to ensure it's started.
  *
- *   - See [BaseService.updateLastAcceptedServiceAction] and [TorService.onTaskRemoved] for
+ *   - See [io.matthewnelson.topl_service.service.components.binding.BaseServiceBinder],
+ *   [BaseService.updateLastAcceptedServiceAction], and [TorService.onTaskRemoved] for
  *   more information.
  *
  * While your application is in the foreground the only way to stop the service is by
@@ -103,14 +106,16 @@ import io.matthewnelson.topl_service.util.ServiceConsts
  *
  * When the user sends your application to the Recent App's tray though, to recoup resources
  * the OS will kill your app after being idle for a period of time (random AF... typically
- * 0.75m to 1.25m). This is not an issue if the user removes the task before the OS
- * kills the app, as Tor will be able to shutdown properly and the service will stop.
+ * 0.75m to 1.25m if the device's memory is being used heavily) if the service is not moved to
+ * the Foreground to inhibit this. This is not an issue if the user removes the task before the
+ * OS kills the app, as Tor will be able to shutdown properly and the service will stop.
  *
  * This is where Services get sketchy (especially when trying to implement an always
  * running service for networking), and is the purpose of the [BackgroundManager] class.
  *
  * This class starts your chosen [BackgroundManager.Builder.Policy] as soon as your
- * application is sent to the background, waits for the time you declared, and then executes.
+ * application is sent to the background. It facilitates a more declarative, flexible
+ * operation to fit Library users' needs.
  *
  * See the [BackgroundManager.Builder] for more detail.
  *
@@ -126,7 +131,8 @@ class BackgroundManager internal constructor(
     @BackgroundPolicy private val policy: String,
     private val executionDelay: Long,
     private val serviceClass: Class<*>,
-    private val bindServiceFlag: Int
+    private val bindServiceFlag: Int,
+    private val killAppIfTaskIsRemoved: Boolean
 ): ServiceConsts(), LifecycleObserver {
 
 
@@ -147,29 +153,7 @@ class BackgroundManager internal constructor(
         @BackgroundPolicy
         private lateinit var chosenPolicy: String
         private var executionDelay: Long = 30_000L
-
-        // TODO: Needs more work... running in the foreground is inhibiting the Application from
-        //  performing it's normal lifecycle after user swipes it away such that it's not going
-        //  through Application.onCreate, but is holding onto references. (same problem when
-        //  starting the service using Context.startForegroundService), which is bullshit.
-//        /**
-//         * While your application is in the background (the Recent App's tray or lock screen),
-//         * this [Policy] periodically switches [TorService] to the foreground then immediately
-//         * back the background. Doing do prevents your application from going idle and being
-//         * killed by the OS. It is much more resource intensive than choosing
-//         * [respectResourcesWhileInBackground].
-//         *
-//         * @param [secondsFrom20To40]? Seconds between the events of cycling from background to
-//         * foreground to background. Sending null will use the default (30s)
-//         * @return [BackgroundManager.Builder.Policy] To use when initializing
-//         *   [io.matthewnelson.topl_service.TorServiceController.Builder]
-//         * */
-//        fun keepAliveWhileInBackground(secondsFrom20To40: Int? = null): Policy {
-//            chosenPolicy = BackgroundPolicy.KEEP_ALIVE
-//            if (secondsFrom20To40 != null && secondsFrom20To40 in 20..40)
-//                executionDelay = (secondsFrom20To40 * 1000).toLong()
-//            return Policy(this)
-//        }
+        private var killAppIfTaskIsRemoved = false
 
         /**
          * Stops [TorService] after being in the background for the declared [secondsFrom5To45].
@@ -200,6 +184,37 @@ class BackgroundManager internal constructor(
             return Policy(this)
         }
 
+        /**
+         * Electing this option will, when your application is sent to the background, immediately
+         * move [TorService] to the Foreground. If the user returns to your application,
+         * [TorService] will then be backgrounded.
+         *
+         * Some things to note about your application's behaviour with this option:
+         *
+         *   - If the user sends your app to the recent App's tray and then swipes it away,
+         *   [TorService.onTaskRemoved] will stop Tor, and then [TorService].
+         *   - Because of how shitty the Service APIs are, your application will _not_ be
+         *   killed like one would expect, thus not going through `Application.onCreate` if the
+         *   user re-launches your application.
+         *   - In the event of being re-launched in the aforementioned state,
+         *   [applicationMovedToForeground] is called and Tor will be started again to match the
+         *   Service's State for which it was left, prior to "terminating" your application.
+         *   - Even while the Service has been properly stopped and everything cleaned up, your
+         *   application will continue running and not be killed (Again, Service APIs...).
+         *   - If [TorService] is stopped, and *then* your application is cleared from the
+         *   recent apps tray, your application will be killed.
+         *
+         * @param [killAppIfTaskIsRemoved] If set to `true`, your Application's Process will be
+         *   killed in [TorService.onDestroy] if the user removed the task from the recent app's
+         *   tray and has not returned to the application before [killAppProcess] is called.
+         * */
+        @JvmOverloads
+        fun runServiceInForeground(killAppIfTaskIsRemoved: Boolean = false): Policy {
+            chosenPolicy = BackgroundPolicy.RUN_IN_FOREGROUND
+            this.killAppIfTaskIsRemoved = killAppIfTaskIsRemoved
+            return Policy(this)
+        }
+
         /**
          * Holds the chosen policy to be built in
          * [io.matthewnelson.topl_service.TorServiceController.Builder.build].
@@ -229,25 +244,46 @@ class BackgroundManager internal constructor(
                             policyBuilder.chosenPolicy,
                             policyBuilder.executionDelay,
                             serviceClass,
-                            bindServiceFlag
+                            bindServiceFlag,
+                            policyBuilder.killAppIfTaskIsRemoved
                         )
                 }
             }
         }
     }
 
-    internal companion object {
+    companion object {
         private lateinit var backgroundManager: BackgroundManager
 
-        // TODO: re-implement in BaseService as a monitor for Tor's state so it can automatically
-        //  handle hiccups (such as network getting stuck b/c Android is sometimes unreliable,
-        //  or Bootstrapping stalling).
-//        var heartbeatTime = 30_000L
-//            private set
-//
-//        fun initialize(milliseconds: Long) {
-//            heartbeatTime = milliseconds
-//        }
+        @JvmStatic
+        @Volatile
+        var taskIsInForeground = true
+            private set
+
+        @JvmStatic
+        @Volatile
+        var taskIsRemovedFromRecentApps = false
+            private set
+
+        internal fun taskIsRemovedFromRecentApps(isRemoved: Boolean) {
+            taskIsRemovedFromRecentApps = isRemoved
+        }
+
+        /**
+         * Called from [TorService.onDestroy].
+         *
+         * Will only kill the application process if [taskIsRemovedFromRecentApps] is `true`.
+         * [taskIsRemovedFromRecentApps] will turn back to `false` when
+         * [applicationMovedToForeground] is fired off, as to not kill the application in the
+         * event the user quickly re-launches the application between the time
+         * [TorService.onTaskRemoved] gets a callback, and this method is called from
+         * [TorService.onDestroy].
+         * */
+        internal fun killAppProcess() {
+            if (backgroundManager.killAppIfTaskIsRemoved && taskIsRemovedFromRecentApps) {
+                Process.killProcess(Process.myPid())
+            }
+        }
     }
 
     init {
@@ -256,6 +292,8 @@ class BackgroundManager internal constructor(
 
     @OnLifecycleEvent(Lifecycle.Event.ON_START)
     private fun applicationMovedToForeground() {
+        taskIsRemovedFromRecentApps(false)
+        taskIsInForeground = true
         // if the last _accepted_ ServiceAction to be issued by the Application was not to STOP
         // the service, then we want to put it back in the state it was in
         if (!ServiceActionProcessor.wasLastAcceptedServiceActionStop()) {
@@ -271,7 +309,16 @@ class BackgroundManager internal constructor(
 
     @OnLifecycleEvent(Lifecycle.Event.ON_STOP)
     private fun applicationMovedToBackground() {
-        if (!ServiceActionProcessor.wasLastAcceptedServiceActionStop())
+        taskIsInForeground = false
+        if (!ServiceActionProcessor.wasLastAcceptedServiceActionStop()) {
+            // System automatically unbinds when app is sent to the background. This prevents
+            // it so that we maintain a started, bound service.
+            BaseService.bindService(
+                BaseService.getAppContext(),
+                serviceClass,
+                bindServiceFlag = bindServiceFlag
+            )
             TorServiceConnection.serviceBinder?.executeBackgroundPolicyJob(policy, executionDelay)
+        }
     }
 }

topl-service/src/main/java/io/matthewnelson/topl_service/notification/ServiceNotification.kt

@@ -432,11 +432,15 @@ class ServiceNotification internal constructor(
         if (notificationRefreshJob?.isActive == true)
             notificationRefreshJob?.cancel()
 
-        notificationRefreshJob = torService.getScopeMain().launch {
+        if (inForeground)
+            return
+
+        notificationRefreshJob = torService.getScopeIO().launch {
             delay(timeoutLength - 250L)
-            notificationBuilder?.let {
-                notify(torService, it)
-            }
+            if (!inForeground)
+                notificationBuilder?.let {
+                    notify(torService, it)
+                }
         }
     }
 
@@ -492,6 +496,7 @@ class ServiceNotification internal constructor(
         if (inForeground) {
             torService.stopForeground(!showNotification)
             inForeground = false
+            launchRefreshNotificationJob(torService)
         }
         return serviceNotification
     }

topl-service/src/main/java/io/matthewnelson/topl_service/service/BaseService.kt

@@ -76,6 +76,7 @@ import io.matthewnelson.topl_core.broadcaster.BroadcastLogger
 import io.matthewnelson.topl_core_base.TorConfigFiles
 import io.matthewnelson.topl_core_base.TorSettings
 import io.matthewnelson.topl_service.BuildConfig
+import io.matthewnelson.topl_service.lifecycle.BackgroundManager
 import io.matthewnelson.topl_service.notification.ServiceNotification
 import io.matthewnelson.topl_service.prefs.TorServicePrefsListener
 import io.matthewnelson.topl_service.service.components.actions.ServiceActionProcessor
@@ -194,17 +195,34 @@ internal abstract class BaseService: Service() {
             // the system via START_STICKY
             return try {
                 context.applicationContext.startService(intent)
-                context.applicationContext.bindService(
-                    intent,
-                    TorServiceConnection.torServiceConnection,
-                    bindServiceFlag
-                )
+                bindService(context, serviceClass, bindServiceFlag)
                 true
             } catch (e: RuntimeException) {
                 false
             }
         }
 
+        /**
+         * Binds the Service.
+         *
+         * @param [context]
+         * @param [serviceClass] The Service's class wanting to be started
+         * @param [bindServiceFlag] The flag to use when binding to [TorService]
+         * @return true if startService didn't throw an exception, false if it did.
+         * */
+        fun bindService(
+            context: Context,
+            serviceClass: Class<*>,
+            bindServiceFlag: Int = Context.BIND_AUTO_CREATE
+        ) {
+            context.applicationContext.bindService(
+                Intent(context.applicationContext, serviceClass),
+                TorServiceConnection.torServiceConnection,
+                bindServiceFlag
+            )
+        }
+
+
         /**
          * Unbinds [TorService] from the Application and clears the reference to
          * [TorServiceConnection.serviceBinder].
@@ -360,6 +378,7 @@ internal abstract class BaseService: Service() {
 
 
     override fun onTaskRemoved(rootIntent: Intent?) {
+        BackgroundManager.taskIsRemovedFromRecentApps(true)
         // Move to the foreground so we can properly shutdown w/o interrupting the
         // application's normal lifecycle (Context.startServiceForeground does... thus,
         // the complexity)

topl-service/src/main/java/io/matthewnelson/topl_service/service/TorService.kt

@@ -73,6 +73,7 @@ import io.matthewnelson.topl_core.OnionProxyManager
 import io.matthewnelson.topl_core.broadcaster.BroadcastLogger
 import io.matthewnelson.topl_core.util.FileUtilities
 import io.matthewnelson.topl_service.TorServiceController
+import io.matthewnelson.topl_service.lifecycle.BackgroundManager
 import io.matthewnelson.topl_service.service.components.binding.TorServiceBinder
 import io.matthewnelson.topl_service.service.components.binding.TorServiceConnection
 import io.matthewnelson.topl_service.service.components.onionproxy.ServiceEventBroadcaster
@@ -258,6 +259,7 @@ internal class TorService: BaseService() {
         super.onDestroy()
         supervisorJob.cancel()
         removeNotification()
+        BackgroundManager.killAppProcess()
     }
 
     override fun onTaskRemoved(rootIntent: Intent?) {

topl-service/src/main/java/io/matthewnelson/topl_service/service/components/binding/BaseServiceBinder.kt

@@ -66,7 +66,10 @@
 * */
 package io.matthewnelson.topl_service.service.components.binding
 
+import android.app.Activity
+import android.app.Application
 import android.os.Binder
+import android.os.Bundle
 import io.matthewnelson.topl_core.broadcaster.BroadcastLogger
 import io.matthewnelson.topl_service.service.BaseService
 import io.matthewnelson.topl_service.lifecycle.BackgroundManager
@@ -77,6 +80,7 @@ import kotlinx.coroutines.Job
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.isActive
 import kotlinx.coroutines.launch
+import net.freehaven.tor.control.TorControlCommands
 
 
 internal abstract class BaseServiceBinder(private val torService: BaseService): Binder() {
@@ -113,16 +117,9 @@ internal abstract class BaseServiceBinder(private val torService: BaseService):
         cancelExecuteBackgroundPolicyJob()
         backgroundPolicyExecutionJob = torService.getScopeMain().launch {
             when (policy) {
-                BackgroundPolicy.KEEP_ALIVE -> {
-                    while (isActive && TorServiceConnection.serviceBinder != null) {
-                        delay(executionDelay)
-                        if (isActive && TorServiceConnection.serviceBinder != null) {
-                            bgMgrBroadcastLogger.debug("Executing background management policy")
-                            torService.stopForegroundService()
-                            torService.startForegroundService()
-                            torService.stopForegroundService()
-                        }
-                    }
+                BackgroundPolicy.RUN_IN_FOREGROUND -> {
+                    bgMgrBroadcastLogger.debug("Executing background management policy")
+                    torService.startForegroundService()
                 }
                 BackgroundPolicy.RESPECT_RESOURCES -> {
                     delay(executionDelay)

topl-service/src/main/java/io/matthewnelson/topl_service/util/ServiceConsts.kt

@@ -83,15 +83,15 @@ abstract class ServiceConsts: BaseConsts() {
         AnnotationTarget.TYPE
     )
     @StringDef(
-        BackgroundPolicy.KEEP_ALIVE,
-        BackgroundPolicy.RESPECT_RESOURCES
+        BackgroundPolicy.RESPECT_RESOURCES,
+        BackgroundPolicy.RUN_IN_FOREGROUND
     )
     @Retention(AnnotationRetention.SOURCE)
     internal annotation class BackgroundPolicy {
         companion object {
             private const val BACKGROUND_POLICY = "BackgroundPolicy_"
-            const val KEEP_ALIVE = "${BACKGROUND_POLICY}KEEP_ALIVE"
             const val RESPECT_RESOURCES = "${BACKGROUND_POLICY}RESPECT_RESOURCES"
+            const val RUN_IN_FOREGROUND = "${BACKGROUND_POLICY}RUN_IN_FOREGROUND"
         }
     }