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

package/android/src/main/java/com/brickssoft/locationtracking/http/SyncPolicy.kt

@@ -19,7 +19,9 @@ import com.brickssoft.locationtracking.model.RecordEvent
  *   - `syncInterval > 0` while tracking: the whole queue once the oldest pending normal record is at least
  *     `syncInterval` seconds old (age = now − `recorded_at`; a negative age, which a wall clock set back produces,
  *     counts as due), or once the queue holds `autoSyncThreshold` records when that is above 0 (a size cap that
- *     uploads earlier); nothing while a retry after a failed upload is pending.
+ *     uploads earlier).
+ * - While the stored wait after a failed automatic upload runs (`waiting`, see `NextTry`), normal records are not
+ *   sent; priority records still are, and take the whole queue with them.
  */
 internal object SyncPolicy {
     /** The records an upload pass sends. */
@@ -39,9 +41,6 @@ internal object SyncPolicy {
 
         /** The oldest pending normal record is due ([isIntervalDue]). */
         DUE,
-
-        /** An automatic upload failed less than `syncInterval` ago: normal records wait for the retry time. */
-        RETRY_PENDING,
     }
 
     val PRIORITY_EVENTS: Set<RecordEvent> = RecordEvent.entries.filter { it.isPriority }.toSet()
@@ -83,6 +82,7 @@ internal object SyncPolicy {
      * @param queued number of queued records.
      * @param priorityQueued number of queued priority records.
      * @param interval the state of the `syncInterval` rule; [IntervalCheck.OFF] applies the threshold rule.
+     * @param waiting true while the stored wait after a failed automatic upload runs: normal records are not sent.
      */
     fun autoScope(
         http: HttpConfig,
@@ -90,16 +90,16 @@ internal object SyncPolicy {
         queued: Int,
         priorityQueued: Int,
         interval: IntervalCheck = IntervalCheck.OFF,
+        waiting: Boolean = false,
     ): Scope {
         if (!hasUrl(http) || !connectivity.connected) return Scope.NONE
         val restricted = isCellularRestricted(http, connectivity)
         if (priorityQueued > 0) return if (restricted) Scope.PRIORITY_ONLY else Scope.ALL
-        if (restricted || !http.autoSync || queued <= 0) return Scope.NONE
+        if (restricted || !http.autoSync || queued <= 0 || waiting) return Scope.NONE
         val upload = when (interval) {
             IntervalCheck.OFF -> queued >= maxOf(1, http.autoSyncThreshold)
             IntervalCheck.NOT_DUE -> http.autoSyncThreshold > 0 && queued >= http.autoSyncThreshold
             IntervalCheck.DUE -> true
-            IntervalCheck.RETRY_PENDING -> false
         }
         return if (upload) Scope.ALL else Scope.NONE
     }

package/android/src/main/java/com/brickssoft/locationtracking/http/TemplateRenderer.kt

@@ -18,7 +18,8 @@ import org.json.JSONTokener
  * Each `<%= name %>` placeholder (surrounding whitespace allowed) is replaced by a raw JSON literal: numbers and
  * booleans bare, null as `null`, strings JSON-escaped but without quotes (templates write `"<%= uuid %>"`), and
  * `extras` as JSON object text (`{}` when the record has none), and `record` as the default record object (with
- * `sent_at`), so `"raw": <%= record %>` keeps every field, and `provider` as the record's provider object (or null).
+ * `sent_at`), so `"raw": <%= record %>` keeps every field, and `provider` and `device` as the record's provider and
+ * device objects (or null).
  * A null value in a placeholder that is exactly wrapped
  * in quotes (`"<%= timestamp %>"`) replaces the quotes too, so it becomes JSON `null` rather than the string "null".
  * An unknown placeholder becomes "" and logs a warning.
@@ -53,10 +54,26 @@ internal object TemplateRenderer {
         "activity.confidence" to { r, _ -> r.activity.confidence.toString() },
         "battery.level" to { r, _ -> number(r.battery.level) },
         "battery.is_charging" to { r, _ -> r.battery.isCharging.toString() },
+        "battery.temperature" to { r, _ -> number(r.batteryDetails?.temperature) },
+        "battery.health" to { r, _ -> r.batteryDetails?.health?.let { string(it) } },
+        "battery.plugged" to { r, _ -> r.batteryDetails?.plugged?.let { string(it) } },
+        "network" to { r, _ -> r.network?.let { string(it.wire) } },
+        "device.device_id" to { r, _ -> r.device?.deviceId?.let { string(it) } },
+        "device.background_restricted" to { r, _ -> r.device?.backgroundRestricted?.toString() },
+        "device.standby_bucket" to { r, _ -> r.device?.standbyBucket?.let { string(it) } },
+        "device.disk_free_bytes" to { r, _ -> r.device?.diskFreeBytes?.toString() },
+        "device.thermal_status" to { r, _ -> r.device?.thermalStatus?.let { string(it) } },
+        "device.manufacturer" to { r, _ -> r.device?.manufacturer?.let { string(it) } },
+        "device.model" to { r, _ -> r.device?.model?.let { string(it) } },
+        "device.os_version" to { r, _ -> r.device?.osVersion?.let { string(it) } },
+        "device.sdk_int" to { r, _ -> r.device?.sdkInt?.toString() },
+        "device.low_ram_device" to { r, _ -> r.device?.lowRamDevice?.toString() },
+        "device.ram_total_bytes" to { r, _ -> r.device?.ramTotalBytes?.toString() },
         "elapsed_realtime_ms" to { r, _ -> r.elapsedRealtimeMs.toString() },
         "boot_count" to { r, _ -> r.bootCount.toString() },
         "backend" to { r, _ -> r.backend?.let { string(it.wire) } },
         "reason" to { r, _ -> r.reason?.let { string(it) } },
+        "stopped_at" to { r, _ -> r.stoppedAt?.let { string(Iso8601.format(it)) } },
         "geofence.identifier" to { r, _ -> r.geofence?.let { string(it.identifier) } },
         "geofence.action" to { r, _ -> r.geofence?.let { string(it.action.name) } },
         "provider.enabled" to { r, _ -> r.provider?.enabled?.toString() },
@@ -66,11 +83,16 @@ internal object TemplateRenderer {
         "extras" to { r, _ -> JsonUtil.parseObject(r.extras)?.toString() ?: "{}" },
         "record" to { r, sentAt -> RecordJson.toJson(r, sentAt).toString() },
         "provider" to { r, _ -> r.provider?.let { ProviderStateJson.toJson(it).toString() } },
+        "device" to { r, _ -> r.device?.let { RecordJson.deviceToJson(it).toString() } },
     )
 
     /** Every supported placeholder name. */
     val PLACEHOLDERS: Set<String> get() = RESOLVERS.keys
 
+    /** The placeholder names used in [template]. */
+    fun placeholderNames(template: String): Set<String> =
+        PLACEHOLDER.findAll(template).map { it.groupValues[2] }.toSet()
+
     /**
      * The template for [record]: `geofenceTemplate` for geofence records (falling back to `locationTemplate`),
      * otherwise `locationTemplate`. Blank templates count as absent; null means the default shape.

package/android/src/main/java/com/brickssoft/locationtracking/http/UploadJobs.kt

@@ -0,0 +1,217 @@
+package com.brickssoft.locationtracking.http
+
+import android.app.job.JobInfo
+import android.app.job.JobParameters
+import android.app.job.JobScheduler
+import android.app.job.JobService
+import android.content.ComponentName
+import android.content.Context
+import android.os.Build
+import com.brickssoft.locationtracking.core.Components
+import com.brickssoft.locationtracking.core.Logger
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.launch
+import kotlin.coroutines.cancellation.CancellationException
+
+/**
+ * Schedules the upload job (recommendation 10): one upload pass in a process that may have no tracking session, so
+ * queued records reach the server whether tracking is on or off.
+ */
+interface UploadScheduler {
+    /**
+     * Replaces any waiting upload job with one that runs once a network is available and [delayMs] have passed.
+     * [unmetered]: only on an unmetered network (normal records with `disableAutoSyncOnCellular` on cellular).
+     */
+    fun schedule(delayMs: Long, unmetered: Boolean = false)
+
+    /** Cancels the waiting upload job (the queue is empty). */
+    fun cancel()
+
+    companion object {
+        /** Schedules nothing (tests, and callers without a Context). */
+        val NONE: UploadScheduler = object : UploadScheduler {
+            override fun schedule(delayMs: Long, unmetered: Boolean) = Unit
+
+            override fun cancel() = Unit
+        }
+    }
+}
+
+/**
+ * [UploadScheduler] over the platform `JobScheduler` (no WorkManager dependency). One job with the fixed id
+ * [UPLOAD_JOB_ID]; each [schedule] replaces the waiting one.
+ *
+ * - The job requires a network (any network, or an unmetered one), is persisted across reboots
+ *   (`RECEIVE_BOOT_COMPLETED` is declared by the plugin), and starts no earlier than the given delay.
+ * - Android 12+: a job without a delay is scheduled as expedited, so it runs as soon as possible even while the app is
+ *   in the background; when the expedited quota is used up (Android refuses it), it is scheduled as a regular job.
+ *   A job with a delay is always a regular job: Android does not allow a start delay on an expedited job.
+ * - A [schedule] or [cancel] made while the job runs (by the pass it runs) is applied when the job has finished:
+ *   scheduling the same id would stop the running job.
+ * - The same request as the last one is not sent again within this process (the pass runs on every new record).
+ */
+class JobUploadScheduler(context: Context, private val sdkInt: Int = Build.VERSION.SDK_INT) : UploadScheduler {
+    private val appContext: Context = context.applicationContext ?: context
+    private val jobScheduler: JobScheduler? by lazy { appContext.getSystemService(JobScheduler::class.java) }
+
+    override fun schedule(delayMs: Long, unmetered: Boolean) {
+        val request = Request.Schedule(delayMs.coerceAtLeast(0L), unmetered)
+        if (deferWhileRunning(request)) return
+        apply(request)
+    }
+
+    override fun cancel() {
+        if (deferWhileRunning(Request.Cancel)) return
+        apply(Request.Cancel)
+    }
+
+    /** Applies the request the job's own pass made, after the job finished. */
+    internal fun applyDeferred() {
+        val request = synchronized(lock) {
+            running = false
+            deferred.also { deferred = null }
+        } ?: return
+        apply(request)
+    }
+
+    private fun deferWhileRunning(request: Request): Boolean = synchronized(lock) {
+        if (!running) return false
+        deferred = request
+        true
+    }
+
+    private fun apply(request: Request) {
+        synchronized(lock) {
+            if (request == lastApplied) return
+            lastApplied = request
+        }
+        val scheduler = jobScheduler ?: return Logger.w(TAG, "JobScheduler is unavailable; no upload job")
+        try {
+            when (request) {
+                Request.Cancel -> {
+                    scheduler.cancel(UPLOAD_JOB_ID)
+                    Logger.d(TAG, "upload job cancelled: the queue is empty")
+                }
+                is Request.Schedule -> scheduleJob(scheduler, request)
+            }
+        } catch (e: Exception) {
+            synchronized(lock) { lastApplied = null }
+            Logger.w(TAG, "could not update the upload job", e)
+        }
+    }
+
+    private fun scheduleJob(scheduler: JobScheduler, request: Request.Schedule) {
+        val network = if (request.unmetered) JobInfo.NETWORK_TYPE_UNMETERED else JobInfo.NETWORK_TYPE_ANY
+        if (request.delayMs == 0L && sdkInt >= Build.VERSION_CODES.S) {
+            val expedited = try {
+                scheduler.schedule(builder(network).setExpedited(true).build()) == JobScheduler.RESULT_SUCCESS
+            } catch (e: Exception) {
+                Logger.d(TAG, "expedited upload job refused (${e.javaClass.simpleName}: ${e.message})")
+                false
+            }
+            if (expedited) {
+                Logger.d(TAG, "upload job scheduled (expedited, network ${networkName(network)})")
+                return
+            }
+            Logger.d(TAG, "expedited upload job refused (quota used up?); scheduling a regular job")
+        }
+        val builder = builder(network)
+        if (request.delayMs > 0) builder.setMinimumLatency(request.delayMs)
+        val result = scheduler.schedule(builder.build())
+        if (result == JobScheduler.RESULT_SUCCESS) {
+            Logger.d(TAG, "upload job scheduled in ${request.delayMs / 1_000} s (network ${networkName(network)})")
+        } else {
+            synchronized(lock) { lastApplied = null }
+            Logger.w(TAG, "JobScheduler refused the upload job")
+        }
+    }
+
+    private fun builder(network: Int): JobInfo.Builder =
+        JobInfo.Builder(UPLOAD_JOB_ID, ComponentName(appContext, UploadJobService::class.java))
+            .setRequiredNetworkType(network)
+            .setPersisted(true)
+
+    private fun networkName(network: Int): String = if (network == JobInfo.NETWORK_TYPE_UNMETERED) "unmetered" else "any"
+
+    private sealed interface Request {
+        data class Schedule(val delayMs: Long, val unmetered: Boolean) : Request
+
+        data object Cancel : Request
+    }
+
+    internal companion object {
+        private const val TAG = "LT.UploadJob"
+
+        /**
+         * JobScheduler ids are shared with the host app's own jobs (and WorkManager's, which counts up from 0), so the
+         * plugin uses one large fixed id ("LT" in its high bytes).
+         */
+        const val UPLOAD_JOB_ID = 0x4C54_0001
+
+        private val lock = Any()
+
+        /** True while [UploadJobService] runs a pass; guarded by [lock]. */
+        private var running = false
+        private var deferred: Request? = null
+        private var lastApplied: Request? = null
+
+        /** Marks the job as running, so the scheduling its pass does waits for [applyDeferred]. */
+        internal fun markRunning() = synchronized(lock) {
+            running = true
+            // The system dropped the job it runs now: the next request must be sent even if it equals the last one.
+            lastApplied = null
+        }
+
+        /** Test hook: forgets the in-process state. */
+        internal fun resetForTest() = synchronized(lock) {
+            running = false
+            deferred = null
+            lastApplied = null
+        }
+    }
+}
+
+/**
+ * Runs one upload job: builds `Components` (the process may have been started for this job) and lets the uploader run
+ * its scheduled passes ([HttpSyncer.runScheduledPass]). What the passes want next (another job, or none) is applied
+ * after the job has finished.
+ */
+class UploadJobService : JobService() {
+    @Volatile
+    private var work: Job? = null
+
+    override fun onStartJob(params: JobParameters): Boolean {
+        val components = try {
+            Components.get(applicationContext)
+        } catch (e: Exception) {
+            Logger.e(TAG, "components unavailable; upload job not run", e)
+            return false
+        }
+        JobUploadScheduler.markRunning()
+        Logger.i(TAG, "upload job started")
+        work = components.scope.launch {
+            try {
+                components.syncer.runScheduledPass()
+            } catch (e: CancellationException) {
+                throw e
+            } catch (e: Exception) {
+                Logger.e(TAG, "upload job failed", e)
+            } finally {
+                jobFinished(params, false)
+                (components.uploadScheduler as? JobUploadScheduler)?.applyDeferred()
+                Logger.d(TAG, "upload job finished")
+            }
+        }
+        return true
+    }
+
+    override fun onStopJob(params: JobParameters): Boolean {
+        Logger.i(TAG, "upload job stopped by the system; it will run again")
+        work?.cancel()
+        return true
+    }
+
+    private companion object {
+        const val TAG = "LT.UploadJob"
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/http/UploadWait.kt

@@ -0,0 +1,184 @@
+package com.brickssoft.locationtracking.http
+
+import android.content.Context
+import android.content.SharedPreferences
+import com.brickssoft.locationtracking.core.Clock
+import com.brickssoft.locationtracking.core.Constants
+import com.brickssoft.locationtracking.core.Logger
+import okhttp3.Headers.Companion.headersOf
+import org.json.JSONObject
+import java.security.MessageDigest
+
+/**
+ * The stored "next try" time of automatic uploads (recommendations 4 and 11): after a failed automatic upload, normal
+ * records are not sent again before [atWall] / [atElapsed]. Priority records (heartbeat and audit records) and
+ * `sync()` do not wait.
+ *
+ * @property reason why uploads wait.
+ * @property failures consecutive failed automatic uploads with reason [Reason.SERVER]; the wait doubles with each.
+ * @property atElapsed elapsed-realtime ms of the next try, valid while the boot count is [bootCount].
+ * @property atWall epoch ms of the next try, used after a reboot (elapsed realtime restarts at 0).
+ * @property authKey for [Reason.AUTHORIZATION]: a hash of the access and refresh tokens that were rejected. The wait
+ *   ends as soon as the configured tokens differ (the app set new ones).
+ */
+data class NextTry(
+    val reason: Reason,
+    val failures: Int,
+    val atElapsed: Long,
+    val bootCount: Int,
+    val atWall: Long,
+    val authKey: String? = null,
+) {
+    enum class Reason(val wire: String) {
+        /** The server failed or rejected the upload, or did not answer. */
+        SERVER("server"),
+
+        /** HTTP 401 and the token could not be refreshed, or the stored tokens cannot be read. */
+        AUTHORIZATION("authorization"),
+        ;
+
+        companion object {
+            fun fromWire(value: String?): Reason? = entries.firstOrNull { it.wire == value }
+        }
+    }
+
+    /** Milliseconds until the next try at the times of [clock]; 0 or less when it is due. */
+    fun remainingMs(clock: Clock): Long {
+        val boot = clock.bootCount()
+        return if (bootCount >= 0 && boot == bootCount) atElapsed - clock.elapsedRealtime() else atWall - clock.now()
+    }
+
+    fun toJson(): JSONObject = JSONObject()
+        .put("reason", reason.wire)
+        .put("failures", failures)
+        .put("atElapsed", atElapsed)
+        .put("bootCount", bootCount)
+        .put("atWall", atWall)
+        .put("authKey", authKey ?: JSONObject.NULL)
+
+    companion object {
+        /** Null if [json] is not a stored [NextTry]. */
+        fun fromJson(json: JSONObject): NextTry? {
+            val reason = Reason.fromWire(json.optString("reason")) ?: return null
+            return NextTry(
+                reason = reason,
+                failures = json.optInt("failures", 1),
+                atElapsed = json.optLong("atElapsed"),
+                bootCount = json.optInt("bootCount", -1),
+                atWall = json.optLong("atWall"),
+                authKey = if (json.isNull("authKey")) null else json.optString("authKey"),
+            )
+        }
+    }
+}
+
+/** Persists the [NextTry] across process restarts. */
+interface NextTryStore {
+    fun load(): NextTry?
+
+    fun save(value: NextTry?)
+
+    companion object {
+        /** Keeps the value in memory only (tests, and callers without a Context). */
+        fun inMemory(): NextTryStore = object : NextTryStore {
+            @Volatile
+            private var value: NextTry? = null
+
+            override fun load(): NextTry? = value
+
+            override fun save(value: NextTry?) {
+                this.value = value
+            }
+        }
+    }
+}
+
+/** [NextTryStore] in the plugin's SharedPreferences file, key [KEY]. */
+class PrefsNextTryStore(context: Context) : NextTryStore {
+    private val prefs: SharedPreferences by lazy {
+        (context.applicationContext ?: context).getSharedPreferences(Constants.PREFS_NAME, Context.MODE_PRIVATE)
+    }
+
+    override fun load(): NextTry? = try {
+        prefs.getString(KEY, null)?.let { NextTry.fromJson(JSONObject(it)) }
+    } catch (e: Exception) {
+        Logger.w(TAG, "stored upload wait is unreadable; ignoring it", e)
+        null
+    }
+
+    override fun save(value: NextTry?) {
+        try {
+            val editor = prefs.edit()
+            if (value == null) editor.remove(KEY) else editor.putString(KEY, value.toJson().toString())
+            editor.apply()
+        } catch (e: Exception) {
+            Logger.w(TAG, "cannot store the upload wait", e)
+        }
+    }
+
+    private companion object {
+        const val TAG = "LT.Http"
+        const val KEY = "http_next_try"
+    }
+}
+
+/**
+ * Wait rules for failed uploads.
+ *
+ * - Inside one upload (owner decision R2-Q18): the retries after 2, 4 and 8 s, each moved by a random amount of up to
+ *   20 % up or down ([retryDelayMs]), so many phones that failed at the same moment do not retry at the same moment.
+ * - Between automatic uploads ([serverWaitMs]): 30 s after the first failure, doubling with each further failure up to
+ *   15 minutes, each moved by up to 20 % up or down; never shorter than a `Retry-After` of a 429 or 503 answer (limited
+ *   to `http.maxRetryAfter`) and, while `http.syncInterval` applies, never shorter than `syncInterval`.
+ * - After an authorization failure: [AUTH_WAIT_MS] (15 minutes), or until the app sets new tokens.
+ */
+object UploadBackoff {
+    /** Waits before the retries of one upload, before jitter. */
+    val RETRY_DELAYS_MS = longArrayOf(2_000L, 4_000L, 8_000L)
+
+    const val FIRST_WAIT_MS = 30_000L
+    const val MAX_WAIT_MS = 15 * 60_000L
+    const val AUTH_WAIT_MS = 15 * 60_000L
+
+    /** Largest relative change of a wait by jitter (20 %). */
+    const val JITTER = 0.2
+
+    /** [base] moved by up to [JITTER] up or down; [random] is in [0, 1). */
+    fun jittered(base: Long, random: Double): Long = (base * (1.0 - JITTER + 2 * JITTER * random)).toLong()
+
+    /** The wait before retry number [index] (0-based) of one upload. */
+    fun retryDelayMs(index: Int, random: Double): Long = jittered(RETRY_DELAYS_MS[index], random)
+
+    /**
+     * The wait after the [failures]-th consecutive failed automatic upload (1 = first failure), at least
+     * [retryAfterMs] (already limited to `http.maxRetryAfter`) and [minimumMs].
+     */
+    fun serverWaitMs(failures: Int, random: Double, retryAfterMs: Long?, minimumMs: Long): Long {
+        val doublings = (failures - 1).coerceIn(0, 30)
+        val base = minOf(FIRST_WAIT_MS shl minOf(doublings, 20), MAX_WAIT_MS)
+        return maxOf(jittered(base, random), retryAfterMs ?: 0L, minimumMs)
+    }
+
+    /**
+     * The `Retry-After` value in ms (delta-seconds or an HTTP date relative to [now]), at most [maxSeconds] seconds;
+     * null if absent or unreadable. A date in the past gives 0.
+     */
+    fun retryAfterMs(value: String?, now: Long, maxSeconds: Int): Long? {
+        val text = value?.trim()?.takeIf { it.isNotEmpty() } ?: return null
+        val ms = text.toLongOrNull()?.let { if (it < 0) null else it * 1_000L }
+            ?: try {
+                headersOf(HttpSupport.RETRY_AFTER, text).getDate(HttpSupport.RETRY_AFTER)?.time?.let { maxOf(0L, it - now) }
+            } catch (e: IllegalArgumentException) {
+                null
+            }
+            ?: return null
+        return minOf(ms, maxSeconds.coerceAtLeast(0) * 1_000L)
+    }
+
+    /** A short, non-reversible key of a token pair, so the stored wait never holds a token. */
+    fun authKey(accessToken: String?, refreshToken: String?): String {
+        val digest = MessageDigest.getInstance("SHA-256")
+            .digest("${accessToken.orEmpty()}\u0000${refreshToken.orEmpty()}".toByteArray(Charsets.UTF_8))
+        return digest.take(12).joinToString("") { "%02x".format(it) }
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/logging/FileLogger.kt

@@ -43,8 +43,9 @@ import java.util.concurrent.atomic.AtomicBoolean
 import java.util.zip.GZIPOutputStream
 
 /**
- * [LogStore] that keeps the log in daily UTC files `filesDir/location-tracking-logs/lt-YYYY-MM-DD.log`, in the format
- * of [LogFormatter].
+ * [LogStore] that keeps the log in daily UTC files `noBackupFilesDir/location-tracking-logs/lt-YYYY-MM-DD.log`, in the
+ * format of [LogFormatter]. `noBackupFilesDir` keeps the logs out of Android Auto Backup and device-to-device transfer
+ * (recommendation 7); files written by an older version under `filesDir` are moved there on first use.
  *
  * [write] never blocks and never throws: it stamps the entry with [Clock.now] and appends it to an in-memory queue
  * (beyond [maxPending] pending entries the oldest are dropped, and a warning records how many). One writer at a time
@@ -52,7 +53,10 @@ import java.util.zip.GZIPOutputStream
  * they see every entry written before they were called.
  *
  * Files are purged by [configure] and on each UTC day rollover: a file is deleted when its whole day lies more than
- * `maxDays` days back, i.e. the files of today and of the previous `maxDays` days are kept.
+ * `maxDays` days back, i.e. the files of today and of the previous `maxDays` days are kept. On top of that, the files
+ * together are kept under `maxTotalBytes` (10 MB; recommendation 16): after every [SIZE_CHECK_BYTES] written, and when
+ * purging, the oldest daily files are deleted until they fit. The file of the current day is never deleted, so a single
+ * day of verbose logging can still exceed the limit.
  *
  * [read] returns whole entries (a header line plus its indented continuation lines). `start`/`end` are inclusive
  * bounds on the entry time; `level` keeps entries at that severity or above, as [LogLevel.allows] (so `OFF` matches
@@ -69,6 +73,7 @@ class FileLogger(
     private val dispatchers: AppDispatchers,
     private val http: Lazy<OkHttpClient>,
     maxPending: Int = DEFAULT_MAX_PENDING,
+    private val maxTotalBytes: Long = DEFAULT_MAX_TOTAL_BYTES,
 ) : LogStore {
     /** A queued entry; the stack trace is rendered at write time so the throwable is not retained. */
     private class Entry(
@@ -82,8 +87,8 @@ class FileLogger(
     private val appContext: Context = context.applicationContext ?: context
     private val maxPending = maxPending.coerceAtLeast(1)
 
-    // Resolved on first use, on the writer's thread: Context.getFilesDir() may touch the disk.
-    private val logDir: File by lazy { File(appContext.filesDir, Constants.LOG_DIR) }
+    // Resolved on first use, on the writer's thread: Context.getNoBackupFilesDir() may touch the disk.
+    private val logDir: File by lazy { noBackupLogDir() }
     private val cacheLogDir: File by lazy { File(appContext.cacheDir, Constants.LOG_DIR) }
 
     private val queueLock = Any()
@@ -95,6 +100,7 @@ class FileLogger(
     private val fileLock = Mutex()
     private var lastWrittenDay = Long.MIN_VALUE // guarded by fileLock
     private var newlineCheckedFile: String? = null // guarded by fileLock
+    private var bytesSinceSizeCheck = 0L // guarded by fileLock
 
     @Volatile
     private var level: LogLevel = LogLevel.INFO
@@ -318,8 +324,11 @@ class FileLogger(
                 val e = batch[i]
                 text.append(LogFormatter.formatEntry(e.timeMs, e.level, e.tag, e.message, e.stackTrace))
             }
-            FileOutputStream(file, true).use { it.write(text.toString().toByteArray(Charsets.UTF_8)) }
+            val bytes = text.toString().toByteArray(Charsets.UTF_8)
+            FileOutputStream(file, true).use { it.write(bytes) }
             newlineCheckedFile = file.name
+            bytesSinceSizeCheck += bytes.size
+            if (bytesSinceSizeCheck >= SIZE_CHECK_BYTES) limitTotalSizeLocked(file)
         } catch (e: IOException) {
             newlineCheckedFile = null
             fallbackLog("could not write $file", e)
@@ -334,7 +343,10 @@ class FileLogger(
         }
     }
 
-    /** Deletes daily files whose day is more than [maxDays] days before [today]. Caller holds [fileLock]. */
+    /**
+     * Deletes daily files whose day is more than [maxDays] days before [today], then the oldest ones beyond
+     * `maxTotalBytes`. Caller holds [fileLock].
+     */
     private fun purgeLocked(today: Long) {
         val keepFrom = today - maxDays.coerceAtLeast(0)
         try {
@@ -342,6 +354,47 @@ class FileLogger(
         } catch (e: RuntimeException) {
             fallbackLog("could not purge old log files", e)
         }
+        limitTotalSizeLocked(File(logDir, LogFormatter.fileName(clock.now())))
+    }
+
+    /** Deletes the oldest daily files, never [current], until all of them fit in `maxTotalBytes`. Caller holds [fileLock]. */
+    private fun limitTotalSizeLocked(current: File) {
+        bytesSinceSizeCheck = 0
+        try {
+            val files = logFiles().map { it.second }
+            var total = files.sumOf { it.length() }
+            for (file in files) {
+                if (total <= maxTotalBytes) break
+                if (file.name == current.name) continue
+                val size = file.length()
+                if (file.delete()) total -= size
+            }
+        } catch (e: RuntimeException) {
+            fallbackLog("could not limit the log size", e)
+        }
+    }
+
+    /**
+     * `noBackupFilesDir/location-tracking-logs`, after moving the daily files an older version wrote to
+     * `filesDir/location-tracking-logs` there (a file that already exists in the new folder is left in the old one).
+     */
+    private fun noBackupLogDir(): File {
+        val target = File(appContext.noBackupFilesDir, Constants.LOG_DIR)
+        try {
+            val legacy = File(appContext.filesDir, Constants.LOG_DIR)
+            if (legacy.isDirectory) {
+                if (!target.exists() && legacy.renameTo(target)) return target
+                target.mkdirs()
+                legacy.listFiles()?.forEach { file ->
+                    val moved = File(target, file.name)
+                    if (!moved.exists()) file.renameTo(moved)
+                }
+                legacy.delete() // only if empty
+            }
+        } catch (e: RuntimeException) {
+            fallbackLog("could not move the old log files", e)
+        }
+        return target
     }
 
     /** Daily log files with their day numbers, oldest first. */
@@ -447,6 +500,12 @@ class FileLogger(
         const val DEFAULT_MAX_PENDING = 5_000
         const val DEFAULT_MAX_DAYS = 3
 
+        /** All daily log files together are kept under this size (recommendation 16). */
+        const val DEFAULT_MAX_TOTAL_BYTES = 10L * 1024 * 1024
+
+        /** The size limit is checked after this many bytes were written. */
+        const val SIZE_CHECK_BYTES = 256L * 1024
+
         /** Name of the gzipped log attached by [upload] and [prepareEmail]. */
         const val UPLOAD_FILE_NAME = "location-tracking-log.txt.gz"
         const val EMAIL_FILE_NAME = UPLOAD_FILE_NAME

package/android/src/main/java/com/brickssoft/locationtracking/logging/LogRedaction.kt

@@ -0,0 +1,31 @@
+package com.brickssoft.locationtracking.logging
+
+/**
+ * Removes credentials and addresses from text the app passes to the JS `log()` method (recommendation 16), before it
+ * reaches logcat and the log files, which can be emailed or uploaded:
+ * - values of credential fields (`accessToken`, `refresh_token`, `password`, `secret`, `apiKey`, `authorization`, …)
+ *   written as `key: value`, `key=value` or JSON `"key": "value"`, in any letter case;
+ * - `Bearer <token>`;
+ * - JSON Web Tokens (`eyJ….….…`);
+ * - URLs (`http(s)://…`, `ws(s)://…`), which can carry tokens in their query or user info.
+ */
+internal object LogRedaction {
+    const val REDACTED = "[redacted]"
+
+    private val SECRET_FIELD = Regex(
+        "(?i)(\"?\\b(?:access[_-]?token|refresh[_-]?token|id[_-]?token|token|password|passwd|secret|client[_-]?secret|" +
+            "api[_-]?key|authorization)\\b\"?\\s*[:=]\\s*)(\"(?:[^\"\\\\]|\\\\.)*\"|[^\\s,;&}]+)",
+    )
+    private val BEARER = Regex("(?i)\\bBearer\\s+[A-Za-z0-9._~+/=-]+")
+    private val JWT = Regex("\\beyJ[A-Za-z0-9_-]*\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]*")
+    private val URL = Regex("(?i)\\b(?:https?|wss?)://[^\\s\"'<>]+")
+
+    fun redact(text: String): String = text
+        .replace(SECRET_FIELD) { match ->
+            val value = match.groupValues[2]
+            match.groupValues[1] + if (value.startsWith("\"")) "\"$REDACTED\"" else REDACTED
+        }
+        .replace(BEARER, "Bearer $REDACTED")
+        .replace(JWT, "[jwt]")
+        .replace(URL, "[url]")
+}