@bricks-soft/capacitor-location-tracking 0.0.0-stage → 8.0.0

package/android/src/main/java/com/brickssoft/locationtracking/provider/hms/HmsProviderBundle.kt

@@ -0,0 +1,55 @@
+package com.brickssoft.locationtracking.provider.hms
+
+import android.content.Context
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.model.ProviderKind
+import com.brickssoft.locationtracking.provider.ActivityBackend
+import com.brickssoft.locationtracking.provider.GeofenceBackend
+import com.brickssoft.locationtracking.provider.LocationBackend
+import com.brickssoft.locationtracking.provider.ProviderBundle
+import com.huawei.hms.api.ConnectionResult
+import com.huawei.hms.api.HuaweiApiAvailability
+
+/**
+ * HMS (Huawei Location Kit) backends. Created reflectively through the public `(Context)` constructor, only after
+ * the HMS SDK class was found on the classpath. Construction touches no HMS API; each backend is created on first
+ * use and then reused, so listener and registration state survives repeated `location()`/`activity()`/`geofence()`
+ * calls.
+ *
+ * @param availabilityCheck returns an HMS `ConnectionResult` code for the device; injectable for tests.
+ */
+class HmsProviderBundle @JvmOverloads constructor(
+    context: Context,
+    private val availabilityCheck: (Context) -> Int = { ctx ->
+        HuaweiApiAvailability.getInstance().isHuaweiMobileServicesAvailable(ctx)
+    },
+) : ProviderBundle {
+    private val appContext: Context = context.applicationContext ?: context
+
+    override val kind: ProviderKind = ProviderKind.HMS
+
+    private val locationBackend by lazy { HmsLocationBackend(appContext) }
+    private val activityBackend by lazy { HmsActivityBackend(appContext) }
+    private val geofenceBackend by lazy { HmsGeofenceBackend(appContext) }
+
+    /** True if HMS Core reports SUCCESS; any failure (including a missing SDK class) counts as unavailable. */
+    override fun isAvailable(): Boolean =
+        try {
+            val result = availabilityCheck(appContext)
+            if (result != ConnectionResult.SUCCESS) Logger.d(TAG, "HMS Core unavailable: result $result")
+            result == ConnectionResult.SUCCESS
+        } catch (t: Throwable) {
+            Logger.w(TAG, "HMS availability check failed", t)
+            false
+        }
+
+    override fun location(): LocationBackend = locationBackend
+
+    override fun activity(): ActivityBackend = activityBackend
+
+    override fun geofence(): GeofenceBackend = geofenceBackend
+
+    private companion object {
+        const val TAG = "LT.HmsBundle"
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/provider/hms/HmsTasks.kt

@@ -0,0 +1,44 @@
+package com.brickssoft.locationtracking.provider.hms
+
+import com.brickssoft.locationtracking.core.TrackingException
+import com.huawei.hmf.tasks.Task
+import com.huawei.hmf.tasks.TaskExecutors
+import kotlinx.coroutines.suspendCancellableCoroutine
+import kotlin.coroutines.cancellation.CancellationException
+import kotlin.coroutines.resume
+import kotlin.coroutines.resumeWithException
+
+/**
+ * Suspends until this HMS task completes and returns its result (which may be null for `Task<Void>` or an absent
+ * last location).
+ *
+ * - A failed task rethrows its exception unchanged (usually `com.huawei.hms.common.ApiException`).
+ * - A task canceled by HMS throws [HmsTaskCanceledException], deliberately not a [CancellationException]: the
+ *   caller's coroutine was not cancelled, so the failure must not be mistaken for cancellation.
+ * - Cancelling the coroutine stops waiting; HMS tasks cannot be cancelled, so a late result is ignored.
+ *
+ * Listeners run on the completing thread ([TaskExecutors.immediate]); the continuation then resumes on the
+ * caller's dispatcher.
+ */
+internal suspend fun <T> Task<T>.await(): T = suspendCancellableCoroutine { cont ->
+    val executor = TaskExecutors.immediate()
+    addOnSuccessListener(executor) { result -> cont.resume(result) }
+    addOnFailureListener(executor) { e -> cont.resumeWithException(e) }
+    addOnCanceledListener(executor) { cont.resumeWithException(HmsTaskCanceledException()) }
+}
+
+/** An HMS task was canceled by the SDK; [hmsCall] maps it to `UNAVAILABLE`. */
+internal class HmsTaskCanceledException : Exception("HMS task was canceled")
+
+/**
+ * Runs [block] and converts every failure except coroutine cancellation into a [TrackingException]
+ * (see [toTrackingException]). [operation] names the HMS call in the message.
+ */
+internal inline fun <T> hmsCall(operation: String, block: () -> T): T =
+    try {
+        block()
+    } catch (e: CancellationException) {
+        throw e
+    } catch (e: Exception) {
+        throw e.toTrackingException(operation)
+    }

package/android/src/main/java/com/brickssoft/locationtracking/record/RecordSink.kt

@@ -0,0 +1,95 @@
+package com.brickssoft.locationtracking.record
+
+import com.brickssoft.locationtracking.config.ConfigStore
+import com.brickssoft.locationtracking.core.EventBus
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.core.RecordHooks
+import com.brickssoft.locationtracking.core.TrackingEvent
+import com.brickssoft.locationtracking.data.LocationStore
+import com.brickssoft.locationtracking.heartbeat.HeartbeatScheduler
+import com.brickssoft.locationtracking.http.HttpSyncer
+import com.brickssoft.locationtracking.model.Record
+import com.brickssoft.locationtracking.model.RecordEvent
+import kotlin.coroutines.cancellation.CancellationException
+
+/** Single entry point for persisting a record. */
+interface RecordSink {
+    /** Persists [record], updates runtime state, restarts the heartbeat window, emits events and triggers sync. */
+    suspend fun submit(record: Record): Record
+}
+
+/**
+ * Default [RecordSink]. Order of operations:
+ * 1. `store.insert(record)`, then `hooks.dispatch(record)` (round 2, see below);
+ * 2. `updateRuntime { lastRecordAt/Elapsed/BootCount, lastLocation = record.location ?: it.lastLocation,
+ *    lastHeartbeatAt if HEARTBEAT }`;
+ * 3. `heartbeat.onRecordRecorded(record)`;
+ * 4. emit: LOCATION / CURRENT_POSITION / WATCH_POSITION -> Location; MOTIONCHANGE -> Location + MotionChange;
+ *    HEARTBEAT -> Heartbeat; every other event is emitted by its producer;
+ * 5. `syncer.onRecordInserted(record)`.
+ *
+ * If the insert fails, the failure is logged, steps 2-4 still run (live listeners still get the record) and
+ * step 5 is skipped because the record is not queued.
+ *
+ * Round 2: [hooks] receives every record right after step 1, also when the insert failed or the caller was cancelled
+ * during the insert (a companion listener keeps its own audit trail, so a local database failure must not hide the
+ * record from it). Because this happens before step 4, a native listener receives a record before the events that
+ * carry it (see `api/NativeListeners`).
+ */
+class DefaultRecordSink(
+    private val store: LocationStore,
+    private val configStore: ConfigStore,
+    private val heartbeat: HeartbeatScheduler,
+    private val syncer: HttpSyncer,
+    private val events: EventBus,
+    private val hooks: RecordHooks = RecordHooks(),
+) : RecordSink {
+    override suspend fun submit(record: Record): Record {
+        val stored = try {
+            store.insert(record)
+            true
+        } catch (e: CancellationException) {
+            // The caller was cancelled during the insert; the row may be committed already (a blocking SQLite write
+            // finishes before the coroutine sees the cancellation). The companion keeps its own audit, so it gets the
+            // record in either case, like after a failed insert.
+            hooks.dispatch(record)
+            throw e
+        } catch (e: Exception) {
+            Logger.e(TAG, "failed to persist ${record.event.wire} record ${record.uuid}", e)
+            false
+        }
+
+        hooks.dispatch(record)
+
+        configStore.updateRuntime { runtime ->
+            runtime.copy(
+                lastRecordAt = record.recordedAt,
+                lastRecordElapsed = record.elapsedRealtimeMs,
+                lastRecordBootCount = record.bootCount,
+                lastLocation = record.location ?: runtime.lastLocation,
+                lastHeartbeatAt = if (record.event == RecordEvent.HEARTBEAT) record.recordedAt else runtime.lastHeartbeatAt,
+            )
+        }
+
+        heartbeat.onRecordRecorded(record)
+
+        when (record.event) {
+            RecordEvent.LOCATION, RecordEvent.CURRENT_POSITION, RecordEvent.WATCH_POSITION ->
+                events.emit(TrackingEvent.Location(record))
+            RecordEvent.MOTIONCHANGE -> {
+                events.emit(TrackingEvent.Location(record))
+                events.emit(TrackingEvent.MotionChange(record.isMoving, record))
+            }
+            RecordEvent.HEARTBEAT -> events.emit(TrackingEvent.Heartbeat(record))
+            RecordEvent.GEOFENCE, RecordEvent.TRACKING_START, RecordEvent.TRACKING_STOP, RecordEvent.PROVIDERCHANGE ->
+                Unit // emitted by the producer
+        }
+
+        if (stored) syncer.onRecordInserted(record)
+        return record
+    }
+
+    private companion object {
+        const val TAG = "LT.RecordSink"
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/service/BootCountStore.kt

@@ -0,0 +1,44 @@
+package com.brickssoft.locationtracking.service
+
+import android.annotation.SuppressLint
+import android.content.Context
+
+/**
+ * Boot counts (`Settings.Global.BOOT_COUNT`) that [BootReceiver] uses to tell a real boot from a repeated or fake boot
+ * broadcast, in the SharedPreferences file [PREFS_NAME] (owned by the service package):
+ * - [lastHandled]: the boot count of the last boot broadcast [BootReceiver] handled;
+ * - [lastServiceStart]: the boot count during which [DefaultServiceController] last had a start of the location service
+ *   accepted by Android (a tracking session was started or restored during that boot).
+ *
+ * The file is loaded on first use (disk I/O); call these methods off the main thread.
+ */
+internal class BootCountStore(context: Context) {
+    private val context: Context = context.applicationContext ?: context
+
+    private val prefs by lazy { this.context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE) }
+
+    /** The boot count of the last handled boot broadcast, or null if none was stored. */
+    fun lastHandled(): Int? = read(KEY_LAST_HANDLED)
+
+    /** Stores [bootCount] as handled; written synchronously (`commit`), so it survives a process death right after. */
+    @SuppressLint("ApplySharedPref") // deliberate: called off the main thread, and the value must be on disk
+    fun setLastHandled(bootCount: Int) {
+        prefs.edit().putInt(KEY_LAST_HANDLED, bootCount).commit()
+    }
+
+    /** The boot count during which the location service was last started, or null if none was stored. */
+    fun lastServiceStart(): Int? = read(KEY_LAST_SERVICE_START)
+
+    /** Records that the location service was started during boot [bootCount]; writes only when the value changes. */
+    fun setServiceStarted(bootCount: Int) {
+        if (read(KEY_LAST_SERVICE_START) != bootCount) prefs.edit().putInt(KEY_LAST_SERVICE_START, bootCount).apply()
+    }
+
+    private fun read(key: String): Int? = if (prefs.contains(key)) prefs.getInt(key, -1) else null
+
+    companion object {
+        const val PREFS_NAME = "location_tracking_boot"
+        private const val KEY_LAST_HANDLED = "last_handled_boot_count"
+        private const val KEY_LAST_SERVICE_START = "last_service_start_boot_count"
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/service/BootReceiver.kt

@@ -0,0 +1,175 @@
+package com.brickssoft.locationtracking.service
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import androidx.annotation.VisibleForTesting
+import com.brickssoft.locationtracking.config.ConfigStore
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.engine.TrackingEngine
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.launch
+import java.util.concurrent.atomic.AtomicBoolean
+import kotlin.coroutines.cancellation.CancellationException
+
+/**
+ * Resumes tracking after a reboot (`BOOT_COMPLETED`, both `QUICKBOOT_POWERON` variants) or an app update
+ * (`MY_PACKAGE_REPLACED`).
+ *
+ * - Tracking enabled and `app.startOnBoot` → `engine.restore("boot" | "package_replaced")`.
+ * - Tracking enabled but not `startOnBoot` → `engine.endWithoutRestore("reboot" | "package_replaced")` records
+ *   `tracking_stop` with that reason (so the server learns why heartbeats stopped) and clears `enabled`.
+ * - Tracking not enabled → nothing.
+ *
+ * Devices that send several boot broadcasts are handled once per process.
+ *
+ * **Boot count gate.** The receiver is exported (plugin manifest) and `QUICKBOOT_POWERON` is not a protected
+ * broadcast, so any app, or `adb shell am broadcast`, can send it without a reboot. A boot action is therefore
+ * handled only when `Settings.Global.BOOT_COUNT` (via `Clock.bootCount()`) shows a boot that has not been seen yet;
+ * it is ignored when the current boot count
+ * - equals the boot count of the last boot broadcast this receiver handled (stored in [BootCountStore] after handling,
+ *   also when tracking was not enabled or the restore failed), or
+ * - equals the boot count during which [DefaultServiceController] last started the location service
+ *   ([BootCountStore.lastServiceStart]): a tracking session was already started or restored during this boot, so a
+ *   boot restore would duplicate `tracking_start` (or end a running audit trail with `tracking_stop: reboot`). This
+ *   also covers an app that was installed and started without a reboot since.
+ *
+ * If the boot count cannot be read (-1), every boot action is handled as before. `MY_PACKAGE_REPLACED` is not gated.
+ */
+class BootReceiver : BroadcastReceiver() {
+    override fun onReceive(context: Context, intent: Intent) {
+        val reason = reasonFor(intent.action) ?: return
+        val deps = try {
+            ServiceDeps.from(context)
+        } catch (e: Exception) {
+            Logger.e(TAG, "components unavailable", e)
+            return
+        }
+        if (reason == REASON_BOOT && !bootHandled.compareAndSet(false, true)) {
+            Logger.d(TAG, "${intent.action}: boot already handled")
+            return
+        }
+        // Null when onReceive is called directly instead of by the system.
+        val pending: PendingResult? = goAsync()
+        val finished = AtomicBoolean(false)
+        val finish = { if (finished.compareAndSet(false, true)) pending?.finish() }
+        val bootCounts = BootCountStore(context)
+        val work = deps.scope.launch {
+            try {
+                if (reason == REASON_BOOT) {
+                    handleBoot(intent.action, deps, bootCounts)
+                } else {
+                    handle(reason, deps.configStore) { deps.engine.value }
+                }
+            } catch (e: CancellationException) {
+                throw e
+            } catch (e: Exception) {
+                Logger.e(TAG, "$reason: restoring tracking failed", e)
+            }
+        }
+        // Release the broadcast before its ~10 s limit even if the restore takes longer; the restore keeps
+        // running (by then its foreground service keeps the process alive).
+        val watchdog = deps.scope.launch {
+            delay(FINISH_BUDGET_MS)
+            Logger.w(TAG, "$reason: restore still running; releasing the broadcast")
+            finish()
+        }
+        // Also runs if the work is cancelled before it starts, unlike a finally block inside it.
+        work.invokeOnCompletion {
+            watchdog.cancel()
+            finish()
+        }
+    }
+
+    /** Applies the boot count gate, then [handle]; stores the boot count once it was handled (also on failure). */
+    private suspend fun handleBoot(action: String?, deps: ServiceDeps, bootCounts: BootCountStore) {
+        val bootCount = deps.clock.bootCount()
+        ignoredBootReason(bootCount, bootCounts.lastHandled(), bootCounts.lastServiceStart())?.let {
+            Logger.i(TAG, "$action ignored: $it")
+            return
+        }
+        var failure: Exception? = null
+        try {
+            handle(REASON_BOOT, deps.configStore) { deps.engine.value }
+        } catch (e: CancellationException) {
+            throw e
+        } catch (e: Exception) {
+            failure = e
+        }
+        if (bootCount >= 0) bootCounts.setLastHandled(bootCount)
+        failure?.let { throw it }
+    }
+
+    /** What [handle] did. */
+    internal enum class Outcome { RESTORED, DISABLED, IGNORED }
+
+    internal companion object {
+        private const val TAG = "LT.Boot"
+        const val REASON_BOOT = "boot"
+        const val STOP_REASON_REBOOT = "reboot"
+        const val REASON_PACKAGE_REPLACED = "package_replaced"
+
+        /** How long the broadcast is held for the restore (receivers must finish within about 10 s). */
+        const val FINISH_BUDGET_MS = 8_000L
+
+        private val BOOT_ACTIONS = setOf(
+            Intent.ACTION_BOOT_COMPLETED,
+            "android.intent.action.QUICKBOOT_POWERON",
+            "com.htc.intent.action.QUICKBOOT_POWERON",
+        )
+
+        private val bootHandled = AtomicBoolean(false)
+
+        /** `"boot"`, `"package_replaced"`, or null for any other action. */
+        fun reasonFor(action: String?): String? = when (action) {
+            in BOOT_ACTIONS -> REASON_BOOT
+            Intent.ACTION_MY_PACKAGE_REPLACED -> REASON_PACKAGE_REPLACED
+            else -> null
+        }
+
+        /**
+         * Why a boot action must be ignored, or null to handle it. [bootCount] is the current `BOOT_COUNT` (-1 if it
+         * cannot be read: always handled), [lastHandled] the boot count of the last handled boot broadcast (null if
+         * none), [lastServiceStart] the boot count during which the location service was last started (null if none).
+         */
+        fun ignoredBootReason(bootCount: Int, lastHandled: Int?, lastServiceStart: Int?): String? = when {
+            bootCount < 0 -> null
+            bootCount == lastHandled -> "boot $bootCount was already handled (no reboot since)"
+            bootCount == lastServiceStart -> "tracking was already started during boot $bootCount (no reboot since)"
+            else -> null
+        }
+
+        /** `tracking_stop` reason when tracking is not resumed: `"reboot"` or `"package_replaced"`. */
+        fun stopReasonFor(reason: String): String = if (reason == REASON_BOOT) STOP_REASON_REBOOT else reason
+
+        /** The boot decision; [engine] is only resolved when tracking was enabled. */
+        suspend fun handle(reason: String, configStore: ConfigStore, engine: () -> TrackingEngine): Outcome {
+            if (!configStore.runtime.value.enabled) {
+                Logger.d(TAG, "$reason: tracking is not enabled")
+                return Outcome.IGNORED
+            }
+            if (!configStore.config.value.app.startOnBoot) {
+                Logger.i(TAG, "$reason: tracking was enabled but app.startOnBoot is false; tracking does not resume")
+                try {
+                    // Clears `enabled` together with the tracking_stop record. It deliberately does nothing when a
+                    // session is already running in this process (e.g. START_STICKY or start() before this broadcast).
+                    engine().endWithoutRestore(stopReasonFor(reason))
+                } catch (e: CancellationException) {
+                    throw e
+                } catch (e: Exception) {
+                    // Recording failed: tracking does not resume, so the persisted state must still say so.
+                    configStore.updateRuntime { it.copy(enabled = false) }
+                    throw e
+                }
+                return Outcome.DISABLED
+            }
+            Logger.i(TAG, "$reason: restoring tracking")
+            engine().restore(reason)
+            return Outcome.RESTORED
+        }
+
+        /** Test hook: forgets that a boot broadcast was handled in this process. */
+        @VisibleForTesting
+        fun resetBootHandled() = bootHandled.set(false)
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/service/DefaultServiceController.kt

@@ -0,0 +1,196 @@
+package com.brickssoft.locationtracking.service
+
+import android.Manifest
+import android.annotation.SuppressLint
+import android.content.Context
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.os.Build
+import androidx.core.app.NotificationManagerCompat
+import androidx.core.content.ContextCompat
+import com.brickssoft.locationtracking.config.ConfigStore
+import com.brickssoft.locationtracking.core.Constants
+import com.brickssoft.locationtracking.core.Clock
+import com.brickssoft.locationtracking.core.EventBus
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.core.SystemClockImpl
+
+/**
+ * Starts and stops [LocationTrackingService]. The start/stop state machine is described in [ServiceCommands].
+ *
+ * - [start] sends a start command with `startForegroundService` (`startService` below API 26). It returns false
+ *   (and logs), without sending anything, when:
+ *   - Android 14+ and no location permission is granted (the service could not enter the foreground);
+ *   - Android 14+, the service is not in the foreground, no background location permission and no visible activity
+ *     ([WhileInUseStartCheck]): Android would throw `SecurityException` from `startForeground`, because while-in-use
+ *     location access does not apply in the background. (A start while the service is already in the foreground
+ *     keeps the service's while-in-use access, so it is not checked.)
+ *
+ *   It also returns false when Android refuses the start, for example `ForegroundServiceStartNotAllowedException` for a
+ *   background start on Android 12+, or when the service is not found. When a start is already pending (sent, not yet
+ *   in the foreground) and no stop was requested after it, it returns true without sending a second start.
+ *
+ *   On false the engine records `tracking_stop` with reason `service_start_failed`: `start()` then rejects with
+ *   `PERMISSION_DENIED`, and `restore()` ends the session.
+ * - [stop] sends a stop command with `startService`, so the stop is handled after every start sent before it (each of
+ *   which enters the foreground first). If Android refuses the stop command, `stopService` is used only when no start
+ *   is pending; while a start is pending, the service stops itself right after it has entered the foreground. So
+ *   `stopService` never races a pending start (that race makes the system crash the app with
+ *   `ForegroundServiceDidNotStartInTimeException`).
+ * - Each accepted start records the current boot count in [BootCountStore] (read by [BootReceiver]'s boot count gate).
+ * - [isRunning] is true while the service is in the foreground: from a successful `startForeground` until the
+ *   service is destroyed or `startForeground` fails.
+ * - [refreshNotification] re-posts the notification from the current config while the service runs.
+ * - [showResumeNotification] / [cancelResumeNotification] post and remove the resume notification
+ *   (`notification.resume`), whose tap starts the service with [LocationTrackingService.ACTION_RESUME].
+ */
+class DefaultServiceController(
+    context: Context,
+    private val configStore: ConfigStore,
+    @Suppress("unused") private val events: EventBus,
+    private val clock: Clock = SystemClockImpl(context),
+) : ServiceController {
+    private val context: Context = context.applicationContext ?: context
+    private val whileInUse = WhileInUseStartCheck(this.context, clock)
+    private val bootCounts = BootCountStore(this.context)
+
+    /** Serializes [start] and [stop], so the sequence numbers reach Android in order. */
+    private val sendLock = Any()
+
+    override val isRunning: Boolean get() = LocationTrackingService.isRunning
+
+    override fun start(): Boolean = synchronized(sendLock) { startLocked() }
+
+    private fun startLocked(): Boolean {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE && !hasLocationPermission()) {
+            Logger.w(TAG, "no location permission: Android 14+ does not allow a location foreground service")
+            return false
+        }
+        if (ServiceCommands.isStartPendingAndLatest) {
+            Logger.d(TAG, "a start is already pending; not sending another")
+            return true
+        }
+        if (!isRunning) {
+            whileInUse.refusalReason()?.let { reason ->
+                Logger.w(TAG, "$reason: the location foreground service would be refused; not starting it")
+                return false
+            }
+        }
+        val seq = ServiceCommands.nextSeq()
+        val command = ServiceCommands.stamp(serviceIntent(), seq, foregroundRequired = true)
+        ServiceCommands.putNotification(command, configStore.config.value.notification)
+        return try {
+            val component = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+                context.startForegroundService(command)
+            } else {
+                context.startService(command)
+            }
+            if (component == null) {
+                // Never delivered, so it must not count as pending.
+                Logger.e(TAG, "the foreground service was not found (is it declared in the manifest?)")
+                return false
+            }
+            ServiceCommands.startSent(seq)
+            // Android's deadline for startForeground() runs from here (the e2e scenario P-L13 reads this line).
+            Logger.d(TAG, "foreground service start sent (seq $seq)")
+            markServiceStarted()
+            true
+        } catch (e: Exception) {
+            if (isForegroundStartNotAllowed(e)) {
+                Logger.w(TAG, "the OS refused to start the foreground service from the background", e)
+            } else {
+                Logger.e(TAG, "could not start the foreground service", e)
+            }
+            false
+        }
+    }
+
+    override fun stop() {
+        synchronized(sendLock) { stopLocked() }
+    }
+
+    private fun stopLocked() {
+        val seq = ServiceCommands.nextSeq()
+        ServiceCommands.stopRequested(seq)
+        val stopCommand =
+            ServiceCommands.stamp(serviceIntent().setAction(LocationTrackingService.ACTION_STOP), seq, foregroundRequired = false)
+        try {
+            context.startService(stopCommand)
+            return
+        } catch (e: Exception) {
+            // IllegalStateException: an app in the background may not start a service that is not running.
+            Logger.d(TAG, "stop command refused (${e.javaClass.simpleName})")
+        }
+        if (ServiceCommands.isStartPending) {
+            Logger.i(TAG, "a start is pending: the service stops itself after it has entered the foreground")
+            return
+        }
+        try {
+            context.stopService(serviceIntent())
+        } catch (e: Exception) {
+            Logger.w(TAG, "could not stop the foreground service", e)
+        }
+    }
+
+    override fun refreshNotification() {
+        try {
+            LocationTrackingService.refresh(context, configStore)
+        } catch (e: Exception) {
+            Logger.w(TAG, "could not refresh the notification", e)
+        }
+    }
+
+    @SuppressLint("MissingPermission") // areNotificationsEnabled() is false without POST_NOTIFICATIONS
+    override fun showResumeNotification(deadline: Long?) {
+        try {
+            val manager = NotificationManagerCompat.from(context)
+            if (!manager.areNotificationsEnabled()) {
+                Logger.w(TAG, "notifications are not allowed (POST_NOTIFICATIONS); no resume notification")
+                return
+            }
+            val timeout = deadline?.let { (it - clock.now()).coerceAtLeast(1L) }
+            val notification = NotificationFactory(context).buildResume(configStore.config.value.notification, timeout)
+            manager.notify(Constants.RESUME_NOTIFICATION_ID, notification)
+            Logger.i(TAG, "resume notification posted")
+        } catch (e: Exception) {
+            Logger.w(TAG, "could not post the resume notification", e)
+        }
+    }
+
+    override fun cancelResumeNotification() {
+        try {
+            NotificationManagerCompat.from(context).cancel(Constants.RESUME_NOTIFICATION_ID)
+        } catch (e: Exception) {
+            Logger.w(TAG, "could not cancel the resume notification", e)
+        }
+    }
+
+    /** Lets [BootReceiver] ignore a later boot broadcast of this boot (a session already ran in this boot). */
+    private fun markServiceStarted() {
+        try {
+            val bootCount = clock.bootCount()
+            if (bootCount >= 0) bootCounts.setServiceStarted(bootCount)
+        } catch (e: Exception) {
+            Logger.w(TAG, "could not record the boot count of this start", e)
+        }
+    }
+
+    private fun serviceIntent(): Intent = Intent(context, LocationTrackingService::class.java)
+
+    private fun hasLocationPermission(): Boolean =
+        listOf(Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_COARSE_LOCATION).any {
+            ContextCompat.checkSelfPermission(context, it) == PackageManager.PERMISSION_GRANTED
+        }
+
+    internal companion object {
+        private const val TAG = "LT.ServiceController"
+        private const val FGS_NOT_ALLOWED = "android.app.ForegroundServiceStartNotAllowedException"
+
+        /**
+         * True for `ForegroundServiceStartNotAllowedException` (API 31+). Compared by name: the class does not
+         * exist below API 31, so it must not appear in a catch clause or type check.
+         */
+        fun isForegroundStartNotAllowed(e: Throwable): Boolean =
+            Build.VERSION.SDK_INT >= Build.VERSION_CODES.S && e.javaClass.name == FGS_NOT_ALLOWED
+    }
+}