@bricks-soft/capacitor-location-tracking 8.0.1 → 8.2.0

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

@@ -9,6 +9,9 @@ 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.brickssoft.locationtracking.provider.LocationSubscriptions
+import com.brickssoft.locationtracking.provider.OsRegistration
+import com.brickssoft.locationtracking.provider.RegistrationEvents
 import com.google.android.gms.location.CurrentLocationRequest
 import com.google.android.gms.location.FusedLocationProviderClient
 import com.google.android.gms.location.LocationAvailability
@@ -25,11 +28,12 @@ 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.
+ * Listener bookkeeping is [LocationSubscriptions]: every request gets its own [LocationCallback] on the main looper,
+ * a request for the same listener removes the previous callback first, and a failure of `requestLocationUpdates`
+ * (thrown, or reported later by its Task) reaches the listener's `onError` (recommendation 3).
+ * `onLocationAvailability` is kept as [availabilityHint].
  *
- * 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).
+ * Only [getCurrentLocation] throws: the [LocationBackend] contract declares no exception for the other methods.
  */
 internal class GmsLocationBackend(
     private val client: FusedLocationProviderClient,
@@ -37,40 +41,48 @@ internal class GmsLocationBackend(
 ) : 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>()
+    private val subscriptions = LocationSubscriptions(TAG) { GmsErrors.map(it, "requestLocationUpdates") }
+
+    override val availabilityHint: Boolean? get() = subscriptions.availabilityHint
 
-    /**
-     * 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)
+            listener.onError(GmsErrors.map(e, "requestLocationUpdates"))
             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")
-        }
+        subscriptions.request(listener, spec) { events -> Registration(request, events) }
+        Logger.d(TAG, "location updates requested: $spec")
     }
 
     override fun removeUpdates(listener: LocationListener) {
-        synchronized(callbacks) {
-            val callback = callbacks.remove(listener) ?: return
-            callback.active = false
+        subscriptions.remove(listener)
+    }
+
+    /** One `requestLocationUpdates` with its own callback. */
+    private inner class Registration(
+        private val request: LocationRequest,
+        private val events: RegistrationEvents,
+    ) : OsRegistration {
+        private val callback = object : LocationCallback() {
+            override fun onLocationResult(result: LocationResult) {
+                events.locations(result.locations.map(TrackedLocation::from))
+            }
+
+            override fun onLocationAvailability(availability: LocationAvailability) {
+                events.availability(availability.isLocationAvailable)
+            }
+        }
+
+        override fun start(done: (Exception?) -> Unit) {
+            client.requestLocationUpdates(request, callback, looper()).addOnCompleteListener(DirectExecutor) { task ->
+                done(task.exception ?: if (task.isCanceled) IllegalStateException("request cancelled by GMS") else null)
+            }
+        }
+
+        override fun remove() {
             try {
                 client.removeLocationUpdates(callback).logFailure(TAG, "removeLocationUpdates")
             } catch (e: Exception) {
@@ -126,30 +138,6 @@ internal class GmsLocationBackend(
         }
     }
 
-    /**
-     * 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"
 

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

@@ -40,16 +40,24 @@ class GmsProviderBundle @JvmOverloads constructor(
     private val activityBackend by lazy { GmsActivityBackend(appContext, activityClient(appContext)) }
     private val geofenceBackend by lazy { GmsGeofenceBackend(appContext, geofencingClient(appContext)) }
 
+    @Volatile
+    private var lastStatus: Int? = null
+
     /** True if `GoogleApiAvailability` reports SUCCESS; false on any other result or failure. */
     override fun isAvailable(): Boolean = try {
         val status = availabilityCheck(appContext)
+        lastStatus = status
         if (status != ConnectionResult.SUCCESS) Logger.d(TAG, "Google Play services unavailable: status $status")
         status == ConnectionResult.SUCCESS
     } catch (t: Throwable) {
+        lastStatus = null
         Logger.w(TAG, "Google Play services availability check failed", t)
         false
     }
 
+    /** The `GoogleApiAvailability` result of the last [isAvailable] (`ConnectionResult` code), or null. */
+    override fun availabilityStatus(): Int? = lastStatus
+
     override fun location(): LocationBackend = locationBackend
 
     override fun activity(): ActivityBackend = activityBackend

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

@@ -10,8 +10,12 @@ 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.brickssoft.locationtracking.provider.LocationSubscriptions
+import com.brickssoft.locationtracking.provider.OsRegistration
+import com.brickssoft.locationtracking.provider.RegistrationEvents
 import com.huawei.hmf.tasks.TaskExecutors
 import com.huawei.hms.location.FusedLocationProviderClient
+import com.huawei.hms.location.LocationAvailability
 import com.huawei.hms.location.LocationCallback
 import com.huawei.hms.location.LocationRequest
 import com.huawei.hms.location.LocationResult
@@ -22,9 +26,14 @@ import kotlinx.coroutines.withTimeoutOrNull
 /**
  * [LocationBackend] over the HMS fused location client.
  *
- * - Each listener gets its own [LocationCallback] on the main looper; requesting again with the same listener
- *   replaces its request, and late fixes from a replaced callback are dropped.
- * - `getCurrentLocation` is a one-shot request (`numUpdates = 1`) whose callback is always removed.
+ * - Listener bookkeeping is [LocationSubscriptions]: each request gets its own [LocationCallback] on the main looper; a
+ *   request for the same listener removes the previous callback first, and late fixes of a replaced callback are
+ *   dropped. A failure of `requestLocationUpdates` (thrown, or reported later by its task) reaches the listener's
+ *   `onError` (recommendation 3). The first delivered fix counts as a successful registration: Huawei does not
+ *   guarantee that the task succeeds before the first result.
+ * - `getCurrentLocation` is a one-shot request (`numUpdates = 1`) whose callback is always removed. It returns the
+ *   first fix even while the request task has not completed, and a failed request ends it at once with the error
+ *   instead of waiting for the timeout.
  * - Permission failures surface as `TrackingException(PERMISSION_DENIED)`; other HMS failures are mapped by
  *   [toTrackingException].
  *
@@ -40,35 +49,17 @@ internal class HmsLocationBackend(
 
     private val client: FusedLocationProviderClient by lazy(clientProvider)
 
-    /**
-     * Active callback per listener. Guarded by [lock], which is also held across the HMS request/remove calls so a
-     * concurrent request/remove for the same listener cannot leave an orphaned HMS registration. Those calls only
-     * submit work and return a task; callbacks never take the lock (they check [ListenerCallback.active]).
-     */
-    private val callbacks = HashMap<LocationListener, ListenerCallback>()
-    private val lock = Any()
+    private val subscriptions = LocationSubscriptions(TAG) { it.toTrackingException("requestLocationUpdates") }
+
+    override val availabilityHint: Boolean? get() = subscriptions.availabilityHint
 
     override fun requestUpdates(spec: LocationRequestSpec, listener: LocationListener) {
         val request = buildLocationRequest(spec)
-        synchronized(lock) {
-            callbacks.remove(listener)?.let(::deactivateAndRemove)
-            val callback = ListenerCallback(listener)
-            callbacks[listener] = callback
-            try {
-                client.requestLocationUpdates(request, callback, looperProvider())
-                    .addOnFailureListener(TaskExecutors.immediate()) { e ->
-                        Logger.e(TAG, "requestLocationUpdates failed: ${describeHmsError(e)}", e)
-                        forget(callback)
-                    }
-            } catch (e: Exception) {
-                Logger.e(TAG, "requestLocationUpdates failed: ${describeHmsError(e)}", e)
-                forget(callback)
-            }
-        }
+        subscriptions.request(listener, spec) { events -> Registration(request, events) }
     }
 
     override fun removeUpdates(listener: LocationListener) {
-        synchronized(lock) { callbacks.remove(listener)?.let(::deactivateAndRemove) }
+        subscriptions.remove(listener)
     }
 
     override suspend fun getLastLocation(): TrackedLocation? = hmsCall("getLastLocation") {
@@ -87,9 +78,15 @@ internal class HmsLocationBackend(
         var requested = false
         try {
             return withTimeoutOrNull(timeoutMs.coerceAtLeast(0)) {
-                hmsCall("getCurrentLocation") {
+                val task = hmsCall("getCurrentLocation") {
                     requested = true
-                    client.requestLocationUpdates(buildOneShotRequest(accuracy), callback, looperProvider()).await()
+                    client.requestLocationUpdates(buildOneShotRequest(accuracy), callback, looperProvider())
+                }
+                task.addOnFailureListener(TaskExecutors.immediate()) { e ->
+                    fix.completeExceptionally(e.toTrackingException("getCurrentLocation"))
+                }
+                task.addOnCanceledListener(TaskExecutors.immediate()) {
+                    fix.completeExceptionally(HmsTaskCanceledException().toTrackingException("getCurrentLocation"))
                 }
                 fix.await()
             }
@@ -99,18 +96,7 @@ internal class HmsLocationBackend(
     }
 
     /** Number of listeners with an active request (for tests and diagnostics). */
-    internal val activeListenerCount: Int get() = synchronized(lock) { callbacks.size }
-
-    /** Drops [callback] after its request failed, unless it was already replaced or removed. */
-    private fun forget(callback: ListenerCallback) {
-        callback.active = false
-        synchronized(lock) { if (callbacks[callback.listener] === callback) callbacks.remove(callback.listener) }
-    }
-
-    private fun deactivateAndRemove(callback: ListenerCallback) {
-        callback.active = false
-        removeQuietly(callback)
-    }
+    internal val activeListenerCount: Int get() = subscriptions.count
 
     private fun removeQuietly(callback: LocationCallback) {
         try {
@@ -123,21 +109,29 @@ internal class HmsLocationBackend(
         }
     }
 
-    /** Delivers to [listener] until replaced or removed; late fixes after that are dropped. */
-    private class ListenerCallback(val listener: LocationListener) : LocationCallback() {
-        @Volatile
-        var active = true
-
-        override fun onLocationResult(result: LocationResult?) {
-            if (!active) return
-            val fixes = result?.locations.orEmpty().mapNotNull { location -> location?.let(::toTrackedLocation) }
-            if (fixes.isEmpty()) return
-            try {
-                listener.onLocations(fixes)
-            } catch (e: Exception) {
-                Logger.e(TAG, "location listener failed", e)
+    /** One `requestLocationUpdates` with its own callback. */
+    private inner class Registration(
+        private val request: LocationRequest,
+        private val events: RegistrationEvents,
+    ) : OsRegistration {
+        private val callback = object : LocationCallback() {
+            override fun onLocationResult(result: LocationResult?) {
+                events.locations(result?.locations.orEmpty().mapNotNull { location -> location?.let(::toTrackedLocation) })
+            }
+
+            override fun onLocationAvailability(availability: LocationAvailability?) {
+                availability?.let { events.availability(it.isLocationAvailable) }
             }
         }
+
+        override fun start(done: (Exception?) -> Unit) {
+            client.requestLocationUpdates(request, callback, looperProvider())
+                .addOnSuccessListener(TaskExecutors.immediate()) { done(null) }
+                .addOnFailureListener(TaskExecutors.immediate()) { e -> done(e) }
+                .addOnCanceledListener(TaskExecutors.immediate()) { done(HmsTaskCanceledException()) }
+        }
+
+        override fun remove() = removeQuietly(callback)
     }
 
     companion object {

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

@@ -23,6 +23,10 @@ class HmsProviderBundle @JvmOverloads constructor(
     private val availabilityCheck: (Context) -> Int = { ctx ->
         HuaweiApiAvailability.getInstance().isHuaweiMobileServicesAvailable(ctx)
     },
+    /** `isHuaweiMobileServicesAvailable(context, minimumVersion)`; injectable for tests. */
+    private val versionCheck: (Context, Int) -> Int = { ctx, minimum ->
+        HuaweiApiAvailability.getInstance().isHuaweiMobileServicesAvailable(ctx, minimum)
+    },
 ) : ProviderBundle {
     private val appContext: Context = context.applicationContext ?: context
 
@@ -32,24 +36,52 @@ class HmsProviderBundle @JvmOverloads constructor(
     private val activityBackend by lazy { HmsActivityBackend(appContext) }
     private val geofenceBackend by lazy { HmsGeofenceBackend(appContext) }
 
+    @Volatile
+    private var lastStatus: Int? = null
+
     /** 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)
+            lastStatus = result
             if (result != ConnectionResult.SUCCESS) Logger.d(TAG, "HMS Core unavailable: result $result")
             result == ConnectionResult.SUCCESS
         } catch (t: Throwable) {
+            lastStatus = null
             Logger.w(TAG, "HMS availability check failed", t)
             false
         }
 
+    /** The `HuaweiApiAvailability` result of the last [isAvailable], or null. */
+    override fun availabilityStatus(): Int? = lastStatus
+
+    /**
+     * A diagnostic when HMS Core is older than 6.3.0.301 ([MIN_RECOMMENDED_HMS_CORE]), the version Huawei's Location
+     * Kit documentation asks for (recommendation 15). It does not change the provider choice. Null when HMS Core is
+     * that version or newer, or the check fails.
+     */
+    override fun versionDiagnostic(): String? = try {
+        val result = versionCheck(appContext, MIN_RECOMMENDED_HMS_CORE)
+        if (result == ConnectionResult.SUCCESS) {
+            null
+        } else {
+            "HMS Core is older than 6.3.0.301 or needs an update (isHuaweiMobileServicesAvailable result $result)"
+        }
+    } catch (t: Throwable) {
+        Logger.w(TAG, "HMS Core version check failed", t)
+        null
+    }
+
     override fun location(): LocationBackend = locationBackend
 
     override fun activity(): ActivityBackend = activityBackend
 
     override fun geofence(): GeofenceBackend = geofenceBackend
 
-    private companion object {
-        const val TAG = "LT.HmsBundle"
+    internal companion object {
+        private const val TAG = "LT.HmsBundle"
+
+        /** HMS Core 6.3.0.301, as `isHuaweiMobileServicesAvailable` expects a version (60300301). */
+        const val MIN_RECOMMENDED_HMS_CORE = 60300301
     }
 }

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

@@ -1,5 +1,6 @@
 package com.brickssoft.locationtracking.record
 
+import android.database.sqlite.SQLiteFullException
 import com.brickssoft.locationtracking.config.ConfigStore
 import com.brickssoft.locationtracking.core.EventBus
 import com.brickssoft.locationtracking.core.Logger
@@ -29,7 +30,8 @@ interface RecordSink {
  * 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.
+ * step 5 is skipped because the record is not queued. A failure because the storage is full (`SQLiteFullException`)
+ * also emits a `StorageFull` event (recommendation 16), so the app can tell the user.
  *
  * 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
@@ -43,6 +45,8 @@ class DefaultRecordSink(
     private val syncer: HttpSyncer,
     private val events: EventBus,
     private val hooks: RecordHooks = RecordHooks(),
+    /** Free bytes of the app's storage, for the `StorageFull` event; null if unknown. */
+    private val diskFreeBytes: () -> Long? = { null },
 ) : RecordSink {
     override suspend fun submit(record: Record): Record {
         val stored = try {
@@ -56,6 +60,14 @@ class DefaultRecordSink(
             throw e
         } catch (e: Exception) {
             Logger.e(TAG, "failed to persist ${record.event.wire} record ${record.uuid}", e)
+            if (isStorageFull(e)) {
+                val free = try {
+                    diskFreeBytes()
+                } catch (x: Exception) {
+                    null
+                }
+                events.emit(TrackingEvent.StorageFull(record.uuid, record.event, free))
+            }
             false
         }
 
@@ -91,5 +103,11 @@ class DefaultRecordSink(
 
     private companion object {
         const val TAG = "LT.RecordSink"
+
+        /** True if [e] or one of its causes is `SQLiteFullException` (or an "out of disk space" I/O error). */
+        fun isStorageFull(e: Throwable): Boolean = generateSequence(e) { it.cause }.take(8).any {
+            it is SQLiteFullException || it.message?.contains("SQLITE_FULL") == true ||
+                it.message?.contains("ENOSPC") == true
+        }
     }
 }

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

@@ -37,6 +37,13 @@ internal class BootCountStore(context: Context) {
     private fun read(key: String): Int? = if (prefs.contains(key)) prefs.getInt(key, -1) else null
 
     companion object {
+        /** Forgets every stored boot count (the state was restored onto another installation). */
+        @SuppressLint("ApplySharedPref")
+        fun clear(context: Context) {
+            (context.applicationContext ?: context).getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+                .edit().clear().commit()
+        }
+
         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/res/xml/lt_file_paths.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
 <paths>
-    <files-path name="lt_logs" path="location-tracking-logs/" />
+    <!-- Only the gzipped copy in the cache is shared (emailLog); the daily files are under noBackupFilesDir. -->
     <cache-path name="lt_logs_cache" path="location-tracking-logs/" />
 </paths>