react-native-nitro-geolocation 1.3.2 → 1.3.3

package/android/src/main/java/com/margelo/nitro/nitrogeolocation/background/AndroidBackgroundHttpSync.kt

@@ -6,6 +6,7 @@ import com.margelo.nitro.nitrogeolocation.StoredBackgroundLocation
 import java.io.OutputStreamWriter
 import java.net.HttpURLConnection
 import java.net.URL
+import kotlin.random.Random
 
 internal class AndroidBackgroundHttpSync {
     fun uploadLocationsWithRetry(
@@ -43,7 +44,7 @@ internal class AndroidBackgroundHttpSync {
                 lastError = error.message ?: "HTTP sync failed"
             }
             if (attempt < maxAttempts - 1) {
-                Thread.sleep(1_000L)
+                Thread.sleep(backoffDelayMs(attempt))
             }
         }
 
@@ -61,10 +62,16 @@ internal class AndroidBackgroundHttpSync {
         locations: Array<StoredBackgroundLocation>
     ): Int {
         val connection = createConnection(sync)
-        OutputStreamWriter(connection.outputStream).use { writer ->
-            writer.write(sync.batchBody(locations).toString())
+        return try {
+            OutputStreamWriter(connection.outputStream).use { writer ->
+                writer.write(sync.batchBody(locations).toString())
+            }
+            val code = connection.responseCode
+            drainResponse(connection, code)
+            code
+        } finally {
+            connection.disconnect()
         }
-        return connection.responseCode
     }
 
     private fun uploadSingleLocationsWithRetry(
@@ -93,7 +100,7 @@ internal class AndroidBackgroundHttpSync {
                     lastError = error.message ?: "HTTP sync failed"
                 }
                 if (!didSync && attempt < maxAttempts - 1) {
-                    Thread.sleep(1_000L)
+                    Thread.sleep(backoffDelayMs(attempt))
                 }
             }
             if (!didSync) {
@@ -115,10 +122,16 @@ internal class AndroidBackgroundHttpSync {
         location: StoredBackgroundLocation
     ): Int {
         val connection = createConnection(sync)
-        OutputStreamWriter(connection.outputStream).use { writer ->
-            writer.write(sync.singleBody(location).toString())
+        return try {
+            OutputStreamWriter(connection.outputStream).use { writer ->
+                writer.write(sync.singleBody(location).toString())
+            }
+            val code = connection.responseCode
+            drainResponse(connection, code)
+            code
+        } finally {
+            connection.disconnect()
         }
-        return connection.responseCode
     }
 
     private fun createConnection(sync: BackgroundHttpSyncOptions): HttpURLConnection {
@@ -131,4 +144,34 @@ internal class AndroidBackgroundHttpSync {
             sync.headers?.forEach { (key, value) -> setRequestProperty(key, value) }
         }
     }
+
+    // Drain (up to a cap) then disconnect so the socket is returned to the pool; an undrained
+    // HttpURLConnection blocks connection reuse and leaks sockets over a long trip.
+    private fun drainResponse(connection: HttpURLConnection, code: Int) {
+        runCatching {
+            val stream = if (code in 200..299) connection.inputStream else connection.errorStream
+            stream?.use { input ->
+                val buffer = ByteArray(4_096)
+                var total = 0
+                while (total < MAX_DRAIN_BYTES) {
+                    val read = input.read(buffer)
+                    if (read < 0) break
+                    total += read
+                }
+            }
+        }
+    }
+
+    // Exponential backoff with full jitter so many devices retrying a failed sync don't hammer the
+    // server in lockstep (thundering herd).
+    private fun backoffDelayMs(attempt: Int): Long {
+        return backoffBaseDelayMs(attempt, BASE_BACKOFF_MS, MAX_BACKOFF_MS) +
+            Random.nextLong(BASE_BACKOFF_MS)
+    }
+
+    private companion object {
+        const val BASE_BACKOFF_MS = 1_000L
+        const val MAX_BACKOFF_MS = 30_000L
+        const val MAX_DRAIN_BYTES = 64 * 1024
+    }
 }

package/android/src/main/java/com/margelo/nitro/nitrogeolocation/background/BackgroundDecisions.kt

@@ -0,0 +1,52 @@
+package com.margelo.nitro.nitrogeolocation.background
+
+import android.app.PendingIntent
+import android.os.Build
+
+/**
+ * Pure decision helpers for the background pipeline, extracted so they can be unit-tested with
+ * plain JUnit (no Android framework instances) — see BackgroundDecisionsTest. They take their
+ * inputs explicitly instead of reading global state. The Android constants used here
+ * (PendingIntent.FLAG_*, Build.VERSION_CODES.*) are compile-time `static final int` values, so the
+ * logic is fully evaluable on a plain JVM.
+ */
+
+/**
+ * Flags for the broadcast PendingIntents the OS fills in at delivery time (location / geofence /
+ * activity). The result MUST be mutable on API 31+ (S), otherwise FusedLocationProviderClient
+ * rejects registration with "PendingIntent must be mutable" and zero updates are ever delivered.
+ * Pre-S PendingIntents are mutable by default, so no immutability flag is set there.
+ */
+internal fun mutablePendingIntentFlags(sdkInt: Int): Int {
+    return if (sdkInt >= Build.VERSION_CODES.S) {
+        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_MUTABLE
+    } else {
+        PendingIntent.FLAG_UPDATE_CURRENT
+    }
+}
+
+/**
+ * Capped exponential backoff base (without jitter): baseMs * 2^attempt, clamped to [baseMs, maxMs].
+ * Callers add jitter on top to avoid synchronized retries across devices.
+ */
+internal fun backoffBaseDelayMs(attempt: Int, baseMs: Long, maxMs: Long): Long {
+    if (attempt <= 0) return baseMs
+    val grown = if (attempt >= 31) maxMs else baseMs shl attempt
+    return grown.coerceIn(baseMs, maxMs)
+}
+
+/**
+ * Resolves the effective store cap (rows), preserving the library's original opt-out for unbounded
+ * storage while adding a safe default when the option is unset:
+ *  - unset (null) → [default] (a safety cap so the store can't grow without bound by accident)
+ *  - explicit <= 0 → 0, meaning UNBOUNDED — pruneRows treats <= 0 as no-prune, the same opt-out the
+ *    original code gave for any non-positive value
+ *  - explicit > 0 → that cap
+ */
+internal fun resolveMaxStored(configured: Int?, default: Int): Int {
+    return when {
+        configured == null -> default
+        configured <= 0 -> 0
+        else -> configured
+    }
+}

package/android/src/main/java/com/margelo/nitro/nitrogeolocation/background/NitroBackgroundEventHub.kt

@@ -46,20 +46,26 @@ class NitroBackgroundEventHub {
     }
 
     fun emit(event: BackgroundEventEnvelope) {
-        eventListeners.values.forEach { listener -> listener(event) }
+        eventListeners.values.forEach { listener -> dispatch { listener(event) } }
 
         when (event.type) {
             BackgroundEventType.LOCATION -> {
                 event.location?.let { location ->
-                    locationListeners.values.forEach { listener -> listener(location) }
+                    locationListeners.values.forEach { listener -> dispatch { listener(location) } }
                 }
             }
             BackgroundEventType.ERROR -> {
                 event.error?.let { error ->
-                    errorListeners.values.forEach { listener -> listener(error) }
+                    errorListeners.values.forEach { listener -> dispatch { listener(error) } }
                 }
             }
             else -> Unit
         }
     }
+
+    // Listeners run inline on the caller's thread (often the broadcast receiver thread). Isolate
+    // each one so a single throwing listener cannot abort delivery to the remaining listeners.
+    private inline fun dispatch(block: () -> Unit) {
+        runCatching(block).onFailure { NitroGeoLog.w("background event listener threw", it) }
+    }
 }

package/android/src/main/java/com/margelo/nitro/nitrogeolocation/background/NitroBackgroundLocationController.kt

@@ -34,6 +34,14 @@ private const val ACTION_GEOFENCE_UPDATE =
 private const val ACTION_ACTIVITY_UPDATE =
     "com.margelo.nitro.nitrogeolocation.background.ACTIVITY_UPDATE"
 
+// LocationError codes mirror the W3C GeolocationPositionError contract.
+private const val ERROR_CODE_PERMISSION_DENIED = 1
+private const val ERROR_CODE_POSITION_UNAVAILABLE = 2
+
+// Default store caps so an unconfigured store cannot grow without bound over a long trip.
+private const val DEFAULT_MAX_STORED_LOCATIONS = 10_000
+private const val DEFAULT_MAX_STORED_EVENTS = 10_000
+
 class NitroBackgroundLocationController private constructor(
     private val context: Context
 ) {
@@ -59,12 +67,23 @@ class NitroBackgroundLocationController private constructor(
     private val httpSync = AndroidBackgroundHttpSync()
     private val taskExecutor = Executors.newSingleThreadExecutor()
 
+    // Serializes HTTP-sync uploads: a burst of locations queues onto one worker instead of
+    // spawning an unbounded number of raw threads.
+    private val syncExecutor = Executors.newSingleThreadExecutor()
+
     @Volatile
     private var config: BackgroundLocationOptions? = null
 
     @Volatile
     private var state = BackgroundLocationState.IDLE
 
+    @Volatile
+    private var lastError: LocationError? = null
+
+    // Serializes lifecycle transitions (configure/start/stop/reset), which are invoked from
+    // Nitro Promise.async worker threads and must not interleave on the shared singleton.
+    private val lifecycleLock = Any()
+
     fun checkBackgroundPermission(): BackgroundPermissionResult {
         return permissions.checkBackgroundPermission()
     }
@@ -78,9 +97,11 @@ class NitroBackgroundLocationController private constructor(
     }
 
     fun configure(options: BackgroundLocationOptions) {
-        validate(options)
-        config = options
-        persistConfig(options)
+        synchronized(lifecycleLock) {
+            validate(options)
+            config = options
+            persistConfig(options)
+        }
     }
 
     fun getConfigOrNull(): BackgroundLocationOptions? {
@@ -94,41 +115,53 @@ class NitroBackgroundLocationController private constructor(
     }
 
     fun start(options: BackgroundLocationOptions?) {
-        options?.let(::configure)
-        val current = requireConfig()
-        validate(current)
-        if (permissions.foregroundPermission() != PermissionStatus.GRANTED) {
-            throw SecurityException("Foreground location permission is required")
-        }
-        if (current.android?.foregroundService == null &&
-            permissions.backgroundPermission() != BackgroundPermissionStatus.GRANTED) {
-            throw SecurityException("Background location permission is required")
+        synchronized(lifecycleLock) {
+            options?.let(::configure)
+            val current = requireConfig()
+            validate(current)
+            NitroGeoLog.d(
+                "start(): provider=${current.android?.locationProvider} interval=${current.interval} state=$state"
+            )
+            if (permissions.foregroundPermission() != PermissionStatus.GRANTED) {
+                throw SecurityException("Foreground location permission is required")
+            }
+            if (current.android?.foregroundService == null &&
+                permissions.backgroundPermission() != BackgroundPermissionStatus.GRANTED) {
+                throw SecurityException("Background location permission is required")
+            }
+            state = BackgroundLocationState.STARTING
+            prefs.edit().putBoolean("running", true).apply()
+            ContextCompat.startForegroundService(
+                appContext,
+                Intent(appContext, NitroBackgroundLocationService::class.java)
+            )
+            // State stays STARTING until the service actually registers updates and the provider
+            // confirms (see startNativeLocationUpdates) — only then do we report RUNNING.
+            NitroGeoLog.d("start(): foreground service requested, state=STARTING")
         }
-        state = BackgroundLocationState.STARTING
-        prefs.edit().putBoolean("running", true).apply()
-        ContextCompat.startForegroundService(
-            appContext,
-            Intent(appContext, NitroBackgroundLocationService::class.java)
-        )
-        state = BackgroundLocationState.RUNNING
     }
 
     fun stop() {
-        state = BackgroundLocationState.STOPPING
-        stopNativeLocationUpdates()
-        stopActivityRecognition()
-        appContext.stopService(Intent(appContext, NitroBackgroundLocationService::class.java))
-        prefs.edit().putBoolean("running", false).apply()
-        state = BackgroundLocationState.STOPPED
+        synchronized(lifecycleLock) {
+            NitroGeoLog.d("stop(): tearing down location updates")
+            state = BackgroundLocationState.STOPPING
+            stopNativeLocationUpdates()
+            stopActivityRecognition()
+            appContext.stopService(Intent(appContext, NitroBackgroundLocationService::class.java))
+            prefs.edit().putBoolean("running", false).apply()
+            state = BackgroundLocationState.STOPPED
+        }
     }
 
     fun reset() {
-        stop()
-        removeGeofences(null)
-        config = null
-        prefs.edit().clear().apply()
-        store.clearEvents(null)
-        store.clearLocations(null)
+        synchronized(lifecycleLock) {
+            stop()
+            removeGeofences(null)
+            config = null
+            prefs.edit().clear().apply()
+            store.clearEvents(null)
+            store.clearLocations(null)
+        }
     }
 
     fun getStatus(): BackgroundLocationStatus {
@@ -156,17 +189,65 @@ class NitroBackgroundLocationController private constructor(
                 permissions.notificationPermission()
             ),
             null,
-            null
+            currentLastError()
         )
     }
 
+    internal fun recordError(code: Int, message: String, throwable: Throwable? = null) {
+        val error = LocationError(code.toDouble(), message)
+        lastError = error
+        prefs.edit()
+            .putInt("lastErrorCode", code)
+            .putString("lastErrorMessage", message)
+            .putLong("lastErrorAt", System.currentTimeMillis())
+            .apply()
+        NitroGeoLog.e("background location error [$code]: $message", throwable)
+        runCatching {
+            dispatchEvent(
+                BackgroundEventEnvelope(
+                    null,
+                    null,
+                    null,
+                    null,
+                    null,
+                    error,
+                    UUID.randomUUID().toString(),
+                    BackgroundEventType.ERROR,
+                    System.currentTimeMillis().toDouble(),
+                    false
+                )
+            )
+        }
+    }
+
+    internal fun recordError(message: String, throwable: Throwable) =
+        recordError(ERROR_CODE_POSITION_UNAVAILABLE, message, throwable)
+
+    private fun clearError() {
+        lastError = null
+        prefs.edit()
+            .remove("lastErrorCode")
+            .remove("lastErrorMessage")
+            .remove("lastErrorAt")
+            .apply()
+    }
+
+    private fun currentLastError(): LocationError? {
+        lastError?.let { return it }
+        val message = prefs.getString("lastErrorMessage", null) ?: return null
+        return LocationError(prefs.getInt("lastErrorCode", 0).toDouble(), message)
+            .also { lastError = it }
+    }
+
     @SuppressLint("MissingPermission")
     fun startNativeLocationUpdates() {
         val current = requireConfig()
         if (current.android?.locationProvider == AndroidBackgroundProvider.ANDROID_PLATFORM) {
+            NitroGeoLog.d("startNativeLocationUpdates(): ANDROID_PLATFORM LocationManager path")
             startPlatformLocationUpdates(current)
             return
         }
+        NitroGeoLog.d("startNativeLocationUpdates(): FUSED provider, registering broadcast PendingIntent")
         val request = LocationRequest.Builder(
             resolvePriority(current),
             current.interval?.toLong() ?: 10_000L
@@ -177,7 +258,27 @@ class NitroBackgroundLocationController private constructor(
             .setMaxUpdateDelayMillis(current.maxUpdateDelay?.toLong() ?: 0L)
             .build()
 
-        fusedLocationClient.requestLocationUpdates(request, locationPendingIntent())
+        try {
+            fusedLocationClient.requestLocationUpdates(request, locationPendingIntent())
+                .addOnSuccessListener {
+                    NitroGeoLog.d("startNativeLocationUpdates(): fused registration accepted")
+                    state = BackgroundLocationState.RUNNING
+                    clearError()
+                }
+                .addOnFailureListener { error ->
+                    recordError(
+                        ERROR_CODE_POSITION_UNAVAILABLE,
+                        "Failed to register fused location updates: ${error.message}",
+                        error
+                    )
+                }
+        } catch (error: SecurityException) {
+            recordError(
+                ERROR_CODE_PERMISSION_DENIED,
+                "Missing location permission for fused updates: ${error.message}",
+                error
+            )
+        }
     }
 
     fun stopNativeLocationUpdates() {
@@ -186,6 +287,7 @@ class NitroBackgroundLocationController private constructor(
     }
 
     fun handleNativeLocation(location: Location, source: BackgroundLocationSource) {
+        NitroGeoLog.d("handleNativeLocation(): src=$source lat=${location.latitude} lng=${location.longitude}")
         val id = UUID.randomUUID().toString()
         val backgroundLocation = BackgroundLocation(
             id,
@@ -391,7 +493,7 @@ class NitroBackgroundLocationController private constructor(
         if (interval > 0 && now - lastSyncAt < interval) return
         prefs.edit().putLong("lastSyncAt", now).apply()
 
-        Thread {
+        syncExecutor.execute {
             val result = runCatching { syncStoredLocations() }.getOrElse { error ->
                 BackgroundHttpSyncResult(
                     false,
@@ -415,7 +517,7 @@ class NitroBackgroundLocationController private constructor(
             )
             persistEventIfNeeded(event)
             dispatchEvent(event)
-        }.start()
+        }
     }
 
     private fun shouldPersist(): Boolean {
@@ -428,12 +530,18 @@ class NitroBackgroundLocationController private constructor(
         store.pruneEvents(currentMaxStoredEvents())
     }
 
-    private fun currentMaxStoredLocations(): Int? {
-        return getConfigOrNull()?.maxStoredLocations?.toInt()?.takeIf { it > 0 }
+    private fun currentMaxStoredLocations(): Int {
+        return resolveMaxStored(
+            getConfigOrNull()?.maxStoredLocations?.toInt(),
+            DEFAULT_MAX_STORED_LOCATIONS
+        )
     }
 
-    private fun currentMaxStoredEvents(): Int? {
-        return getConfigOrNull()?.maxStoredEvents?.toInt()?.takeIf { it > 0 }
+    private fun currentMaxStoredEvents(): Int {
+        return resolveMaxStored(
+            getConfigOrNull()?.maxStoredEvents?.toInt(),
+            DEFAULT_MAX_STORED_EVENTS
+        )
     }
 
     @SuppressLint("MissingPermission")
@@ -443,13 +551,26 @@ class NitroBackgroundLocationController private constructor(
         val providers = listOf(LocationManager.GPS_PROVIDER, LocationManager.NETWORK_PROVIDER)
             .filter { provider -> runCatching { platformLocationManager.isProviderEnabled(provider) }.getOrDefault(false) }
             .ifEmpty { listOf(LocationManager.GPS_PROVIDER) }
+        var registered = false
         providers.forEach { provider ->
-            platformLocationManager.requestLocationUpdates(
-                provider,
-                interval,
-                distance,
-                locationPendingIntent()
-            )
+            try {
+                platformLocationManager.requestLocationUpdates(
+                    provider,
+                    interval,
+                    distance,
+                    locationPendingIntent()
+                )
+                registered = true
+            } catch (error: SecurityException) {
+                recordError(
+                    ERROR_CODE_PERMISSION_DENIED,
+                    "Missing location permission for $provider updates: ${error.message}",
+                    error
+                )
+            }
+        }
+        if (registered) {
+            state = BackgroundLocationState.RUNNING
         }
     }
 
@@ -484,10 +605,16 @@ class NitroBackgroundLocationController private constructor(
 
     private fun dispatchEvent(event: BackgroundEventEnvelope) {
         eventHub.emit(event)
-        val intent = Intent(appContext, NitroBackgroundHeadlessTaskService::class.java)
-            .putExtra("event", event.toJson().toString())
-        appContext.startService(intent)
-        HeadlessJsTaskService.acquireWakeLockNow(appContext)
+        // The in-process eventHub already delivered to any live JS listeners; the headless task is
+        // the fallback for when JS is dead. Guard its start: startService from the background can be
+        // rejected (ForegroundServiceStartNotAllowed / IllegalState), which must not crash the
+        // broadcast receiver thread that drives delivery.
+        runCatching {
+            val intent = Intent(appContext, NitroBackgroundHeadlessTaskService::class.java)
+                .putExtra("event", event.toJson().toString())
+            appContext.startService(intent)
+            HeadlessJsTaskService.acquireWakeLockNow(appContext)
+        }.onFailure { NitroGeoLog.w("dispatchEvent: headless task dispatch failed", it) }
     }
 
     private fun waitForTask(task: Task<Void>) {
@@ -661,7 +788,7 @@ class NitroBackgroundLocationController private constructor(
             appContext,
             1001,
             intent,
-            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+            mutablePendingIntentFlags(Build.VERSION.SDK_INT)
         )
     }
 
@@ -672,7 +799,7 @@ class NitroBackgroundLocationController private constructor(
             appContext,
             1002,
             intent,
-            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+            mutablePendingIntentFlags(Build.VERSION.SDK_INT)
         )
     }
 
@@ -683,7 +810,7 @@ class NitroBackgroundLocationController private constructor(
             appContext,
             1003,
             intent,
-            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+            mutablePendingIntentFlags(Build.VERSION.SDK_INT)
         )
     }
 

package/android/src/main/java/com/margelo/nitro/nitrogeolocation/background/NitroBackgroundLocationService.kt

@@ -2,7 +2,9 @@ package com.margelo.nitro.nitrogeolocation.background
 
 import android.app.Service
 import android.content.Intent
+import android.content.pm.ServiceInfo
 import android.os.IBinder
+import androidx.core.app.ServiceCompat
 
 class NitroBackgroundLocationService : Service() {
     private val controller by lazy {
@@ -14,18 +16,38 @@ class NitroBackgroundLocationService : Service() {
         val foregroundService = config.android?.foregroundService
             ?: throw IllegalStateException("Android foreground service options are required")
         val notification = NitroBackgroundNotificationFactory.create(this, foregroundService)
-        startForeground(
-            foregroundService.notificationId?.toInt() ?: 9471,
-            notification
-        )
+        val notificationId = foregroundService.notificationId?.toInt() ?: 9471
+        NitroGeoLog.d("Service.onStartCommand(): startForeground id=$notificationId type=location")
+        try {
+            ServiceCompat.startForeground(
+                this,
+                notificationId,
+                notification,
+                ServiceInfo.FOREGROUND_SERVICE_TYPE_LOCATION
+            )
+        } catch (error: Exception) {
+            // Android 14+ rejects a "location" foreground service if location permission is not
+            // held at start time (SecurityException), and Android 12+ rejects background starts
+            // (ForegroundServiceStartNotAllowedException, an IllegalStateException). Record and stop
+            // cleanly instead of letting the service crash.
+            controller.recordError("Failed to start foreground location service: ${error.message}", error)
+            stopSelf()
+            return START_NOT_STICKY
+        }
+        NitroGeoLog.d("Service.onStartCommand(): starting native location updates")
         controller.startNativeLocationUpdates()
         if (config.trackingMode == com.margelo.nitro.nitrogeolocation.BackgroundTrackingMode.ACTIVITYAWARE ||
             config.activityRecognition?.enabled == true) {
             runCatching {
                 controller.startActivityRecognition(config.activityRecognition)
+            }.onFailure {
+                controller.recordError("Failed to start activity recognition: ${it.message}", it)
             }
         }
         runCatching { controller.registerPersistedGeofencesIfNeeded() }
+            .onFailure {
+                controller.recordError("Failed to register persisted geofences: ${it.message}", it)
+            }
         return if (config.stopOnTerminate == false) START_STICKY else START_NOT_STICKY
     }
 

package/android/src/main/java/com/margelo/nitro/nitrogeolocation/background/NitroBackgroundStore.kt

@@ -29,6 +29,12 @@ import org.json.JSONObject
 class NitroBackgroundStore(context: Context) :
     SQLiteOpenHelper(context, "nitro_background_location.db", null, 3) {
 
+    init {
+        // WAL lets the broadcast-receiver writer and concurrent readers (JS Promise threads and the
+        // sync worker) proceed without blocking each other under a steady stream of location inserts.
+        setWriteAheadLoggingEnabled(true)
+    }
+
     override fun onCreate(db: SQLiteDatabase) {
         db.execSQL(
             """

package/android/src/main/java/com/margelo/nitro/nitrogeolocation/background/NitroBootReceiver.kt

@@ -13,14 +13,25 @@ class NitroBootReceiver : BroadcastReceiver() {
             return
         }
 
-        val prefs = context.applicationContext.getSharedPreferences(
-            "nitro_background_location",
-            Context.MODE_PRIVATE
-        )
-        val controller = NitroBackgroundLocationController.getInstance(context)
-        runCatching { controller.registerPersistedGeofencesIfNeeded() }
-        if (prefs.getBoolean("startOnBoot", false)) {
-            runCatching { controller.start(null) }
-        }
+        // registerPersistedGeofencesIfNeeded() blocks (waitForTask, up to 30s) and start() does
+        // disk I/O; running them inline would block the broadcast's main thread and risk an ANR.
+        // Hand off to a worker thread and keep the broadcast alive with goAsync() until it finishes.
+        val appContext = context.applicationContext
+        val pendingResult = goAsync()
+        Thread {
+            try {
+                val prefs = appContext.getSharedPreferences(
+                    "nitro_background_location",
+                    Context.MODE_PRIVATE
+                )
+                val controller = NitroBackgroundLocationController.getInstance(appContext)
+                runCatching { controller.registerPersistedGeofencesIfNeeded() }
+                if (prefs.getBoolean("startOnBoot", false)) {
+                    runCatching { controller.start(null) }
+                }
+            } finally {
+                pendingResult.finish()
+            }
+        }.start()
     }
 }

package/android/src/main/java/com/margelo/nitro/nitrogeolocation/background/NitroGeoLog.kt

@@ -0,0 +1,33 @@
+package com.margelo.nitro.nitrogeolocation.background
+
+import android.util.Log
+import com.margelo.nitro.nitrogeolocation.BuildConfig
+
+/**
+ * Lightweight tagged logger for the background location pipeline.
+ *
+ * The background delivery path runs across a foreground service, a broadcast receiver and a
+ * headless task, where a misconfiguration can silently stop location delivery with no error.
+ * This logger makes that path observable from logcat.
+ *
+ * Verbose [d] logs are gated behind [verbose] (defaults to debug builds) so release builds stay
+ * quiet, while [w] and [e] always emit because they mark real delivery or registration failures.
+ */
+internal object NitroGeoLog {
+    private const val TAG = "NitroGeolocation"
+
+    @Volatile
+    var verbose: Boolean = BuildConfig.DEBUG
+
+    fun d(message: String) {
+        if (verbose) Log.d(TAG, message)
+    }
+
+    fun w(message: String, error: Throwable? = null) {
+        Log.w(TAG, message, error)
+    }
+
+    fun e(message: String, error: Throwable? = null) {
+        Log.e(TAG, message, error)
+    }
+}

package/android/src/main/java/com/margelo/nitro/nitrogeolocation/background/NitroLocationUpdateReceiver.kt

@@ -11,6 +11,7 @@ import com.margelo.nitro.nitrogeolocation.BackgroundLocationSource
 
 class NitroLocationUpdateReceiver : BroadcastReceiver() {
     override fun onReceive(context: Context, intent: Intent) {
+        NitroGeoLog.d("LocationUpdateReceiver.onReceive(): action=${intent.action}")
         val controller = NitroBackgroundLocationController.getInstance(context)
         val platformLocation = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
             intent.getParcelableExtra(LocationManager.KEY_LOCATION_CHANGED, Location::class.java)
@@ -26,7 +27,16 @@ class NitroLocationUpdateReceiver : BroadcastReceiver() {
             return
         }
 
-        val result = LocationResult.extractResult(intent) ?: return
+        val result = LocationResult.extractResult(intent)
+        if (result == null) {
+            NitroGeoLog.w(
+                "LocationUpdateReceiver.onReceive(): broadcast carried no location " +
+                    "(KEY_LOCATION_CHANGED and LocationResult both null) — dropping. " +
+                    "On Android 12+ this usually means the broadcast PendingIntent was built " +
+                    "with FLAG_IMMUTABLE, so the OS could not inject the LocationResult extras."
+            )
+            return
+        }
         for (location in result.locations) {
             controller.handleNativeLocation(
                 location,

package/android/src/test/java/com/margelo/nitro/nitrogeolocation/background/BackgroundDecisionsTest.kt

@@ -0,0 +1,67 @@
+package com.margelo.nitro.nitrogeolocation.background
+
+import android.app.PendingIntent
+import android.os.Build
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class BackgroundDecisionsTest {
+    @Test
+    fun pendingIntentFlagsAreMutableOnApiSAndAbove() {
+        val flags = mutablePendingIntentFlags(Build.VERSION_CODES.S)
+        assertTrue(
+            "FLAG_MUTABLE must be set on API >= S, or the OS rejects the registration",
+            (flags and PendingIntent.FLAG_MUTABLE) != 0
+        )
+        assertTrue(
+            "FLAG_UPDATE_CURRENT must be set",
+            (flags and PendingIntent.FLAG_UPDATE_CURRENT) != 0
+        )
+    }
+
+    @Test
+    fun pendingIntentFlagsAreNotImmutableBelowApiS() {
+        val flags = mutablePendingIntentFlags(Build.VERSION_CODES.R)
+        assertFalse(
+            "FLAG_IMMUTABLE must not be set below S (PendingIntents are mutable by default there)",
+            (flags and PendingIntent.FLAG_IMMUTABLE) != 0
+        )
+        assertTrue(
+            "FLAG_UPDATE_CURRENT must be set",
+            (flags and PendingIntent.FLAG_UPDATE_CURRENT) != 0
+        )
+    }
+
+    @Test
+    fun backoffGrowsExponentiallyThenCaps() {
+        assertEquals(1_000L, backoffBaseDelayMs(0, 1_000L, 30_000L))
+        assertEquals(2_000L, backoffBaseDelayMs(1, 1_000L, 30_000L))
+        assertEquals(4_000L, backoffBaseDelayMs(2, 1_000L, 30_000L))
+        assertEquals(8_000L, backoffBaseDelayMs(3, 1_000L, 30_000L))
+        assertEquals(30_000L, backoffBaseDelayMs(10, 1_000L, 30_000L))
+    }
+
+    @Test
+    fun backoffClampsNegativeAttemptToBase() {
+        assertEquals(1_000L, backoffBaseDelayMs(-1, 1_000L, 30_000L))
+    }
+
+    @Test
+    fun resolveMaxStoredUsesConfiguredPositiveValue() {
+        assertEquals(500, resolveMaxStored(500, 10_000))
+    }
+
+    @Test
+    fun resolveMaxStoredFallsBackToDefaultWhenUnset() {
+        assertEquals(10_000, resolveMaxStored(null, 10_000))
+    }
+
+    @Test
+    fun resolveMaxStoredTreatsNonPositiveAsUnbounded() {
+        // 0 is the library's explicit unbounded opt-out (pruneRows treats <= 0 as no-prune).
+        assertEquals(0, resolveMaxStored(0, 10_000))
+        assertEquals(0, resolveMaxStored(-5, 10_000))
+    }
+}

package/ios/NitroBackgroundLocation.swift

@@ -544,6 +544,12 @@ class NitroBackgroundLocation: HybridNitroBackgroundLocationSpec {
     }
 
     func handleError(_ error: Error) {
+        // kCLErrorLocationUnknown is transient — CoreLocation couldn't get a fix right now but keeps
+        // trying (very common on the Simulator and during brief GPS gaps). Apple's guidance is to
+        // ignore it; forwarding it would pollute the consumer's error stream with benign noise.
+        if let clError = error as? CLError, clError.code == .locationUnknown {
+            return
+        }
         let locationError = LocationError(code: -1, message: error.localizedDescription)
         errorListeners.values.forEach { $0(locationError) }
     }
@@ -690,25 +696,31 @@ class NitroBackgroundLocation: HybridNitroBackgroundLocationSpec {
         return max(Int(value.rounded(.down)), 1)
     }
 
+    // Default store cap (rows) applied when maxStored* is unset, matching the Android side. An
+    // explicit value <= 0 means UNBOUNDED (no cap), preserving the library's original opt-out.
+    private static let defaultMaxStoredRows = 10_000
+
+    private func resolveMaxStored(_ configured: Double?, default def: Int) -> Int? {
+        guard let configured = configured else { return def }
+        if configured <= 0 { return nil }
+        return Int(configured)
+    }
+
     private func appendStoredLocation(_ location: StoredBackgroundLocation) {
         guard shouldPersist() else { return }
         storedLocations.append(location)
-        if let maxValue = options?.maxStoredLocations, maxValue > 0 {
-            let max = Int(maxValue)
-            if storedLocations.count > max {
-                storedLocations = Array(storedLocations.suffix(max))
-            }
+        if let max = resolveMaxStored(options?.maxStoredLocations, default: Self.defaultMaxStoredRows),
+           storedLocations.count > max {
+            storedLocations = Array(storedLocations.suffix(max))
         }
     }
 
     private func appendStoredEvent(_ event: StoredBackgroundEventEnvelope) {
         guard shouldPersist() else { return }
         storedEvents.append(event)
-        if let maxValue = options?.maxStoredEvents, maxValue > 0 {
-            let max = Int(maxValue)
-            if storedEvents.count > max {
-                storedEvents = Array(storedEvents.suffix(max))
-            }
+        if let max = resolveMaxStored(options?.maxStoredEvents, default: Self.defaultMaxStoredRows),
+           storedEvents.count > max {
+            storedEvents = Array(storedEvents.suffix(max))
         }
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-geolocation",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "description": "Nitro-powered native geolocation for modern React Native apps",
   "main": "src/index",
   "source": "src/index",

package/src/background/types.ts

@@ -76,7 +76,15 @@ export interface BackgroundLocationOptions {
   maxUpdateDelay?: number;
   waitForAccurateLocation?: boolean;
   persist?: boolean;
+  /**
+   * Max number of locations retained in the on-device store before older rows are pruned.
+   * Unset → a built-in safety cap (the native default). Set to `0` for UNBOUNDED storage.
+   */
   maxStoredLocations?: number;
+  /**
+   * Max number of events retained in the on-device store before older rows are pruned.
+   * Unset → a built-in safety cap (the native default). Set to `0` for UNBOUNDED storage.
+   */
   maxStoredEvents?: number;
   stopOnTerminate?: boolean;
   startOnBoot?: boolean;