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

package/android/src/main/java/com/brickssoft/locationtracking/provider/gms/GmsGeofenceBackend.kt

@@ -0,0 +1,152 @@
+package com.brickssoft.locationtracking.provider.gms
+
+import android.app.PendingIntent
+import android.content.Context
+import android.content.Intent
+import com.brickssoft.locationtracking.core.Constants
+import com.brickssoft.locationtracking.core.ErrorCode
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.core.TrackingException
+import com.brickssoft.locationtracking.model.ProviderKind
+import com.brickssoft.locationtracking.provider.GeofenceBackend
+import com.brickssoft.locationtracking.provider.OsGeofence
+import com.google.android.gms.location.Geofence
+import com.google.android.gms.location.GeofencingClient
+import com.google.android.gms.location.GeofencingRequest
+import kotlinx.coroutines.currentCoroutineContext
+import kotlinx.coroutines.ensureActive
+import kotlin.coroutines.cancellation.CancellationException
+
+/**
+ * OS geofencing through `GeofencingClient`. Transitions arrive at [GmsGeofenceReceiver] through a mutable,
+ * explicit broadcast PendingIntent. Adding a region with an existing id replaces it.
+ */
+internal class GmsGeofenceBackend(
+    private val context: Context,
+    private val client: GeofencingClient,
+) : GeofenceBackend {
+    override val kind: ProviderKind = ProviderKind.GMS
+    override val supportsDwell: Boolean = true
+
+    /**
+     * Registers [regions], one GMS request per distinct `initialTriggerEntry` value. Regions that watch no
+     * transition are skipped (GMS rejects them). If a later request fails, the regions registered by the earlier
+     * requests of this call are removed again (best effort) before the error is thrown.
+     *
+     * @throws TrackingException see [GmsErrors.map].
+     */
+    override suspend fun add(regions: List<OsGeofence>) = call("addGeofences") {
+        val requests = buildGeofencingRequests(regions)
+        val registered = mutableListOf<String>()
+        try {
+            for (request in requests) {
+                client.addGeofences(request, pendingIntent(context)).await()
+                registered += request.geofences.map { it.requestId }
+            }
+        } catch (e: Exception) {
+            if (registered.isNotEmpty()) rollBack(registered)
+            throw e
+        }
+        if (registered.isNotEmpty()) Logger.d(TAG, "registered ${registered.size} geofences")
+    }
+
+    /** @throws TrackingException see [GmsErrors.map]. */
+    override suspend fun remove(ids: List<String>) {
+        if (ids.isEmpty()) return
+        call("removeGeofences") { client.removeGeofences(ids).await() }
+    }
+
+    /** Removes every geofence registered with this backend's PendingIntent; a no-op if it does not exist. */
+    override suspend fun removeAll() = call("removeAllGeofences") {
+        val pending = existingPendingIntent(context) ?: return@call
+        client.removeGeofences(pending).await()
+    }
+
+    /** Best effort; never replaces the original error (unless the caller itself is cancelled). */
+    private suspend fun rollBack(ids: List<String>) {
+        try {
+            client.removeGeofences(ids).await()
+        } catch (e: Exception) {
+            currentCoroutineContext().ensureActive()
+            Logger.w(TAG, "rolling back geofences $ids failed", e)
+        }
+    }
+
+    private suspend fun call(operation: String, block: suspend () -> Unit) {
+        try {
+            block()
+        } catch (e: CancellationException) {
+            currentCoroutineContext().ensureActive()
+            // GMS cancelled the Task itself; the caller is still active and expects a TrackingException.
+            throw TrackingException(ErrorCode.UNAVAILABLE, "$operation was cancelled by Google Play services", e)
+        } catch (e: Exception) {
+            val mapped = GmsErrors.map(e, operation)
+            Logger.w(TAG, "${mapped.code}: ${mapped.message}", e)
+            throw mapped
+        }
+    }
+
+    companion object {
+        private const val TAG = "LT.GmsGeofence"
+
+        /** Initial trigger for `initialTriggerEntry`: report ENTER, and DWELL after the delay, if already inside. */
+        private const val INITIAL_TRIGGER_INSIDE =
+            GeofencingRequest.INITIAL_TRIGGER_ENTER or GeofencingRequest.INITIAL_TRIGGER_DWELL
+
+        /** Explicit broadcast to [GmsGeofenceReceiver]; mutable because GMS fills in the transition. */
+        fun pendingIntent(context: Context): PendingIntent =
+            PendingIntent.getBroadcast(context, Constants.RC_GMS_GEOFENCE, intent(context), Constants.piMutable())
+
+        /** The PendingIntent of [pendingIntent] if it exists, without creating it. */
+        fun existingPendingIntent(context: Context): PendingIntent? = PendingIntent.getBroadcast(
+            context,
+            Constants.RC_GMS_GEOFENCE,
+            intent(context),
+            Constants.piMutable() or PendingIntent.FLAG_NO_CREATE,
+        )
+
+        private fun intent(context: Context): Intent =
+            Intent(context, GmsGeofenceReceiver::class.java).setAction(Constants.ACTION_GEOFENCE)
+
+        /**
+         * Groups [regions] by `initialTriggerEntry`. `true` sets the initial trigger `ENTER | DWELL` (a device that is
+         * already inside reports ENTER, and DWELL after the loitering delay, for the transitions it watches); `false`
+         * sets no initial trigger.
+         *
+         * @throws IllegalArgumentException if GMS rejects a region (id longer than 100, bad coordinates or radius).
+         */
+        fun buildGeofencingRequests(regions: List<OsGeofence>): List<GeofencingRequest> = regions
+            .mapNotNull { region -> toGeofence(region)?.let { region.initialTriggerEntry to it } }
+            .groupBy({ it.first }, { it.second })
+            .map { (initialTriggerEntry, geofences) ->
+                GeofencingRequest.Builder()
+                    .setInitialTrigger(if (initialTriggerEntry) INITIAL_TRIGGER_INSIDE else 0)
+                    .addGeofences(geofences)
+                    .build()
+            }
+
+        /** The GMS geofence for [region], or null if it watches no transition. */
+        fun toGeofence(region: OsGeofence): Geofence? {
+            val transitions = transitionTypes(region)
+            if (transitions == 0) {
+                Logger.w(TAG, "geofence '${region.id}' watches no transition; not registered")
+                return null
+            }
+            return Geofence.Builder()
+                .setRequestId(region.id)
+                .setCircularRegion(region.latitude, region.longitude, region.radius)
+                .setTransitionTypes(transitions)
+                .setLoiteringDelay(region.loiteringDelayMs.coerceAtLeast(0))
+                .setExpirationDuration(Geofence.NEVER_EXPIRE)
+                .build()
+        }
+
+        fun transitionTypes(region: OsGeofence): Int {
+            var types = 0
+            if (region.onEntry) types = types or Geofence.GEOFENCE_TRANSITION_ENTER
+            if (region.onExit) types = types or Geofence.GEOFENCE_TRANSITION_EXIT
+            if (region.onDwell) types = types or Geofence.GEOFENCE_TRANSITION_DWELL
+            return types
+        }
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/provider/gms/GmsGeofenceReceiver.kt

@@ -0,0 +1,78 @@
+package com.brickssoft.locationtracking.provider.gms
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import com.brickssoft.locationtracking.core.Components
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.model.GeofenceAction
+import com.brickssoft.locationtracking.model.TrackedLocation
+import com.brickssoft.locationtracking.provider.GeofenceTransitionSink
+import com.brickssoft.locationtracking.provider.OsGeofenceTransition
+import com.google.android.gms.location.Geofence
+import com.google.android.gms.location.GeofenceStatusCodes
+import com.google.android.gms.location.GeofencingEvent
+
+/**
+ * Receives `GeofencingEvent`s from the PendingIntent of [GmsGeofenceBackend] and delivers one
+ * [OsGeofenceTransition] per triggering geofence to the GeofenceManager with `goAsync()` on `Components.scope`.
+ */
+class GmsGeofenceReceiver internal constructor(
+    private val target: (Context) -> ReceiverTarget<GeofenceTransitionSink>,
+) : BroadcastReceiver() {
+    constructor() : this({ ctx -> Components.get(ctx).let { ReceiverTarget(it.scope, it.geofences) } })
+
+    override fun onReceive(context: Context, intent: Intent) {
+        val transitions = parseGeofenceTransitions(intent)
+        if (transitions.isEmpty()) return
+        Logger.d(TAG, "geofence transitions: ${transitions.joinToString { "${it.id}:${it.action}" }}")
+        deliverAsync(context, target, TAG, "geofence delivery") { it.onGeofenceTransitions(transitions) }
+    }
+
+    internal companion object {
+        private const val TAG = "LT.GmsGeofence"
+
+        fun parseGeofenceTransitions(intent: Intent?): List<OsGeofenceTransition> {
+            val event = try {
+                intent?.let { GeofencingEvent.fromIntent(it) }
+            } catch (e: Exception) {
+                Logger.w(TAG, "unreadable geofencing event", e)
+                null
+            }
+            return parseGeofencingEvent(event)
+        }
+
+        /**
+         * One transition per triggering geofence, all with the event's action and triggering location.
+         * Empty (and logged) if [event] is null, carries an error or has an unknown transition.
+         */
+        fun parseGeofencingEvent(event: GeofencingEvent?): List<OsGeofenceTransition> {
+            if (event == null) {
+                Logger.w(TAG, "intent carries no geofencing event")
+                return emptyList()
+            }
+            if (event.hasError()) {
+                val code = event.errorCode
+                // GEOFENCE_NOT_AVAILABLE also means GMS removed every registered geofence; nothing re-adds them
+                // until tracking restarts (see the unit report's contract change request).
+                val notAvailable = code == GeofenceStatusCodes.GEOFENCE_NOT_AVAILABLE
+                val dropped = if (notAvailable) "; all geofences were removed" else ""
+                Logger.e(TAG, "geofencing error: ${GmsErrors.describe(code)}$dropped")
+                return emptyList()
+            }
+            val action = mapTransition(event.geofenceTransition) ?: run {
+                Logger.w(TAG, "unknown geofence transition ${event.geofenceTransition}")
+                return emptyList()
+            }
+            val location = event.triggeringLocation?.let(TrackedLocation::from)
+            return event.triggeringGeofences.orEmpty().map { OsGeofenceTransition(it.requestId, action, location) }
+        }
+
+        fun mapTransition(transition: Int): GeofenceAction? = when (transition) {
+            Geofence.GEOFENCE_TRANSITION_ENTER -> GeofenceAction.ENTER
+            Geofence.GEOFENCE_TRANSITION_EXIT -> GeofenceAction.EXIT
+            Geofence.GEOFENCE_TRANSITION_DWELL -> GeofenceAction.DWELL
+            else -> null
+        }
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/provider/gms/GmsLocationBackend.kt

@@ -0,0 +1,176 @@
+package com.brickssoft.locationtracking.provider.gms
+
+import android.os.Looper
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.core.TrackingException
+import com.brickssoft.locationtracking.model.DesiredAccuracy
+import com.brickssoft.locationtracking.model.ProviderKind
+import com.brickssoft.locationtracking.model.TrackedLocation
+import com.brickssoft.locationtracking.provider.LocationBackend
+import com.brickssoft.locationtracking.provider.LocationListener
+import com.brickssoft.locationtracking.provider.LocationRequestSpec
+import com.google.android.gms.location.CurrentLocationRequest
+import com.google.android.gms.location.FusedLocationProviderClient
+import com.google.android.gms.location.LocationAvailability
+import com.google.android.gms.location.LocationCallback
+import com.google.android.gms.location.LocationRequest
+import com.google.android.gms.location.LocationResult
+import com.google.android.gms.location.Priority
+import com.google.android.gms.tasks.CancellationTokenSource
+import kotlinx.coroutines.currentCoroutineContext
+import kotlinx.coroutines.ensureActive
+import kotlinx.coroutines.withTimeoutOrNull
+import kotlin.coroutines.cancellation.CancellationException
+
+/**
+ * Fused location provider backend.
+ *
+ * Every [LocationListener] gets its own [LocationCallback] on the main looper. Requesting again with the same
+ * listener reuses its callback, which GMS treats as a replacement of the previous request.
+ *
+ * Only [getCurrentLocation] throws: the [LocationBackend] contract declares no exception for the other methods, so
+ * their failures are logged (a missing permission also shows in the provider state).
+ */
+internal class GmsLocationBackend(
+    private val client: FusedLocationProviderClient,
+    private val looper: () -> Looper = Looper::getMainLooper,
+) : LocationBackend {
+    override val kind: ProviderKind = ProviderKind.GMS
+
+    /** Guarded by itself; GMS registration calls are made under the same lock so add/remove cannot interleave. */
+    private val callbacks = HashMap<LocationListener, ListenerCallback>()
+
+    /**
+     * Never throws. A synchronous rejection (e.g. `SecurityException` without location permission) is logged and
+     * leaves a new listener unregistered, or a replaced listener on its previous request. Asynchronous failures of
+     * the GMS Task are logged too.
+     */
+    override fun requestUpdates(spec: LocationRequestSpec, listener: LocationListener) {
+        val request = try {
+            buildLocationRequest(spec)
+        } catch (e: Exception) {
+            Logger.e(TAG, "invalid location request $spec", e)
+            return
+        }
+        synchronized(callbacks) {
+            val existing = callbacks[listener]
+            val callback = existing ?: ListenerCallback(listener)
+            try {
+                client.requestLocationUpdates(request, callback, looper()).logFailure(TAG, "requestLocationUpdates")
+            } catch (e: Exception) {
+                val mapped = GmsErrors.map(e, "requestLocationUpdates")
+                Logger.e(TAG, "${mapped.code}: ${mapped.message}", e)
+                return
+            }
+            if (existing == null) callbacks[listener] = callback
+            Logger.d(TAG, "location updates ${if (existing == null) "requested" else "replaced"}: $spec")
+        }
+    }
+
+    override fun removeUpdates(listener: LocationListener) {
+        synchronized(callbacks) {
+            val callback = callbacks.remove(listener) ?: return
+            callback.active = false
+            try {
+                client.removeLocationUpdates(callback).logFailure(TAG, "removeLocationUpdates")
+            } catch (e: Exception) {
+                Logger.w(TAG, "removeLocationUpdates failed", e)
+            }
+        }
+    }
+
+    /**
+     * The cached fused location, or null if there is none or GMS cannot provide it (including a missing permission;
+     * logged). Never throws, so callers such as the heartbeat can always fall back to a record without coords.
+     */
+    override suspend fun getLastLocation(): TrackedLocation? = try {
+        client.lastLocation.await()?.let(TrackedLocation::from)
+    } catch (e: CancellationException) {
+        currentCoroutineContext().ensureActive()
+        Logger.w(TAG, "getLastLocation cancelled by GMS")
+        null
+    } catch (e: Exception) {
+        val mapped = GmsErrors.map(e, "getLastLocation")
+        Logger.w(TAG, "${mapped.code}: ${mapped.message}", e)
+        null
+    }
+
+    /**
+     * Requests one fix computed now (a cached fix is accepted only for PASSIVE, which never computes one itself).
+     * Returns null if none arrives within [timeoutMs]: GMS gives up after the request duration, and the coroutine
+     * timeout is a safety net that also cancels the GMS request.
+     *
+     * @throws TrackingException PERMISSION_DENIED without location permission, otherwise see [GmsErrors.map]
+     *   (UNAVAILABLE for GMS API failures).
+     */
+    override suspend fun getCurrentLocation(accuracy: DesiredAccuracy, timeoutMs: Long): TrackedLocation? {
+        if (timeoutMs <= 0) return null
+        val cancellation = CancellationTokenSource()
+        return try {
+            val request = CurrentLocationRequest.Builder()
+                .setPriority(accuracy.toGmsPriority())
+                .setDurationMillis(timeoutMs)
+                .apply { if (accuracy != DesiredAccuracy.PASSIVE) setMaxUpdateAgeMillis(0) }
+                .build()
+            withTimeoutOrNull(timeoutMs) {
+                client.getCurrentLocation(request, cancellation.token).await(cancellation)
+            }?.let(TrackedLocation::from)
+        } catch (e: CancellationException) {
+            // Either the caller was cancelled (rethrown here) or GMS cancelled the task itself (no fix).
+            currentCoroutineContext().ensureActive()
+            null
+        } catch (e: Exception) {
+            throw GmsErrors.map(e, "getCurrentLocation")
+        } finally {
+            cancellation.cancel()
+        }
+    }
+
+    /**
+     * Forwards fixes to one listener until [removeUpdates] deactivates it. Best effort: a batch whose delivery already
+     * started on the looper thread may still reach the listener while [removeUpdates] runs on another thread.
+     */
+    private class ListenerCallback(private val listener: LocationListener) : LocationCallback() {
+        @Volatile
+        var active = true
+
+        override fun onLocationResult(result: LocationResult) {
+            if (!active) return
+            val locations = result.locations.map(TrackedLocation::from)
+            if (locations.isEmpty()) return
+            try {
+                listener.onLocations(locations)
+            } catch (e: Exception) {
+                Logger.e(TAG, "location listener failed", e)
+            }
+        }
+
+        override fun onLocationAvailability(availability: LocationAvailability) {
+            Logger.v(TAG, "location available: ${availability.isLocationAvailable}")
+        }
+    }
+
+    companion object {
+        private const val TAG = "LT.GmsLocation"
+
+        /**
+         * `LocationRequest.Builder(priority, interval)` with the fastest interval (clamped to [0, interval]) and the
+         * distance filter (at least 0).
+         */
+        fun buildLocationRequest(spec: LocationRequestSpec): LocationRequest {
+            val interval = spec.intervalMs.coerceAtLeast(0)
+            val distance = spec.distanceFilterM.takeIf { it.isFinite() }?.coerceAtLeast(0f) ?: 0f
+            return LocationRequest.Builder(spec.accuracy.toGmsPriority(), interval)
+                .setMinUpdateIntervalMillis(spec.fastestIntervalMs.coerceIn(0, interval))
+                .setMinUpdateDistanceMeters(distance)
+                .build()
+        }
+
+        fun DesiredAccuracy.toGmsPriority(): Int = when (this) {
+            DesiredAccuracy.HIGH -> Priority.PRIORITY_HIGH_ACCURACY
+            DesiredAccuracy.BALANCED -> Priority.PRIORITY_BALANCED_POWER_ACCURACY
+            DesiredAccuracy.LOW -> Priority.PRIORITY_LOW_POWER
+            DesiredAccuracy.PASSIVE -> Priority.PRIORITY_PASSIVE
+        }
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/provider/gms/GmsProviderBundle.kt

@@ -0,0 +1,62 @@
+package com.brickssoft.locationtracking.provider.gms
+
+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.google.android.gms.common.ConnectionResult
+import com.google.android.gms.common.GoogleApiAvailability
+import com.google.android.gms.location.ActivityRecognition
+import com.google.android.gms.location.ActivityRecognitionClient
+import com.google.android.gms.location.FusedLocationProviderClient
+import com.google.android.gms.location.GeofencingClient
+import com.google.android.gms.location.LocationServices
+
+/**
+ * Google Play services backends: fused location, activity recognition and geofencing.
+ *
+ * Created reflectively through the public `(Context)` constructor. The other parameters exist so tests can inject
+ * the availability check and the GMS clients. Each backend (and its client) is created on first use.
+ */
+class GmsProviderBundle @JvmOverloads constructor(
+    context: Context,
+    private val availabilityCheck: (Context) -> Int = {
+        GoogleApiAvailability.getInstance().isGooglePlayServicesAvailable(it)
+    },
+    private val fusedClient: (Context) -> FusedLocationProviderClient = {
+        LocationServices.getFusedLocationProviderClient(it)
+    },
+    private val activityClient: (Context) -> ActivityRecognitionClient = { ActivityRecognition.getClient(it) },
+    private val geofencingClient: (Context) -> GeofencingClient = { LocationServices.getGeofencingClient(it) },
+) : ProviderBundle {
+    private val appContext: Context = context.applicationContext ?: context
+
+    override val kind: ProviderKind = ProviderKind.GMS
+
+    private val locationBackend by lazy { GmsLocationBackend(fusedClient(appContext)) }
+    private val activityBackend by lazy { GmsActivityBackend(appContext, activityClient(appContext)) }
+    private val geofenceBackend by lazy { GmsGeofenceBackend(appContext, geofencingClient(appContext)) }
+
+    /** True if `GoogleApiAvailability` reports SUCCESS; false on any other result or failure. */
+    override fun isAvailable(): Boolean = try {
+        val status = availabilityCheck(appContext)
+        if (status != ConnectionResult.SUCCESS) Logger.d(TAG, "Google Play services unavailable: status $status")
+        status == ConnectionResult.SUCCESS
+    } catch (t: Throwable) {
+        Logger.w(TAG, "Google Play services 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.Gms"
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/provider/gms/GmsReceiverSupport.kt

@@ -0,0 +1,88 @@
+package com.brickssoft.locationtracking.provider.gms
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import com.brickssoft.locationtracking.core.Logger
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.launch
+import java.util.concurrent.atomic.AtomicBoolean
+import kotlin.coroutines.cancellation.CancellationException
+
+/** Where a PendingIntent receiver delivers its parsed payload: normally `Components.get(ctx).scope` and a sink. */
+internal class ReceiverTarget<T>(val scope: CoroutineScope, val sink: T)
+
+/**
+ * The system reports a broadcast ANR if `goAsync()` is not finished in time (10 s for foreground broadcasts), so
+ * the broadcast is finished after this deadline even if the delivery is still running.
+ */
+internal const val RECEIVER_FINISH_DEADLINE_MS = 9_000L
+
+/**
+ * Called from `onReceive`: calls `goAsync()`, resolves the target and runs [deliver] with its sink in its scope.
+ * The broadcast is always finished, also if the target cannot be resolved.
+ */
+internal fun <T> BroadcastReceiver.deliverAsync(
+    context: Context,
+    target: (Context) -> ReceiverTarget<T>,
+    tag: String,
+    what: String,
+    deliver: suspend (T) -> Unit,
+) {
+    val pending = goAsync()
+    try {
+        val resolved = target(context)
+        resolved.scope.launchReceiverWork(pending, tag, what) { deliver(resolved.sink) }
+    } catch (e: Exception) {
+        Logger.e(tag, "cannot start $what", e)
+        try {
+            pending?.finish()
+        } catch (finishError: Exception) {
+            Logger.w(tag, "$what: finishing the broadcast failed", finishError)
+        }
+    }
+}
+
+/**
+ * Runs [block] in this scope for a receiver that called `goAsync()`. [pending] is finished exactly once: when the
+ * work completes, fails or is cancelled (even if the scope was already cancelled), or after [deadlineMs] while the
+ * work keeps running. Failures are logged.
+ */
+internal fun CoroutineScope.launchReceiverWork(
+    pending: BroadcastReceiver.PendingResult?,
+    tag: String,
+    what: String,
+    deadlineMs: Long = RECEIVER_FINISH_DEADLINE_MS,
+    block: suspend () -> Unit,
+): Job {
+    val finished = AtomicBoolean(false)
+    val finish = {
+        if (finished.compareAndSet(false, true)) {
+            try {
+                pending?.finish()
+            } catch (e: Exception) {
+                Logger.w(tag, "$what: finishing the broadcast failed", e)
+            }
+        }
+    }
+    val job = launch {
+        try {
+            block()
+        } catch (e: CancellationException) {
+            throw e
+        } catch (e: Exception) {
+            Logger.e(tag, "$what failed", e)
+        }
+    }
+    val watchdog = launch {
+        delay(deadlineMs)
+        Logger.w(tag, "$what still running after $deadlineMs ms; finishing the broadcast early")
+        finish()
+    }
+    job.invokeOnCompletion {
+        watchdog.cancel()
+        finish()
+    }
+    return job
+}

package/android/src/main/java/com/brickssoft/locationtracking/provider/gms/GmsTasks.kt

@@ -0,0 +1,55 @@
+package com.brickssoft.locationtracking.provider.gms
+
+import com.brickssoft.locationtracking.core.Logger
+import com.google.android.gms.tasks.CancellationTokenSource
+import com.google.android.gms.tasks.Task
+import kotlinx.coroutines.suspendCancellableCoroutine
+import java.util.concurrent.Executor
+import kotlin.coroutines.cancellation.CancellationException
+import kotlin.coroutines.resume
+import kotlin.coroutines.resumeWithException
+
+/** Runs Task listeners on the thread that completes the task; the coroutine then resumes on its own dispatcher. */
+internal object DirectExecutor : Executor {
+    override fun execute(command: Runnable) = command.run()
+}
+
+/**
+ * Suspends until this Task completes, without the play-services coroutines dependency.
+ *
+ * - Success resumes with the result (which may be null, e.g. no last location or `Task<Void>`).
+ * - Failure rethrows the Task's exception unchanged.
+ * - A cancelled Task throws [CancellationException].
+ * - Cancelling the calling coroutine cancels [cancellationTokenSource], if given, so GMS stops the work.
+ */
+internal suspend fun <T> Task<T>.await(cancellationTokenSource: CancellationTokenSource? = null): T {
+    if (isComplete) return completedResult()
+    return suspendCancellableCoroutine { cont ->
+        addOnCompleteListener(DirectExecutor) { task ->
+            val error = task.exception
+            when {
+                error != null -> cont.resumeWithException(error)
+                task.isCanceled -> cont.cancel()
+                else -> cont.resume(task.result)
+            }
+        }
+        if (cancellationTokenSource != null) {
+            cont.invokeOnCancellation { cancellationTokenSource.cancel() }
+        }
+    }
+}
+
+private fun <T> Task<T>.completedResult(): T {
+    exception?.let { throw it }
+    if (isCanceled) throw CancellationException("Task ${this::class.java.name} was cancelled")
+    return result
+}
+
+/** Adds a listener that only logs a failure of a fire-and-forget Task. Never throws. */
+internal fun Task<*>?.logFailure(tag: String, what: String) {
+    try {
+        this?.addOnFailureListener(DirectExecutor) { e -> Logger.w(tag, "$what failed", e) }
+    } catch (e: Exception) {
+        Logger.w(tag, "$what: cannot observe result", e)
+    }
+}