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

package/android/src/main/java/com/brickssoft/locationtracking/heartbeat/DefaultHeartbeatScheduler.kt

@@ -17,6 +17,7 @@ import com.brickssoft.locationtracking.core.LogLevel
 import com.brickssoft.locationtracking.core.Logger
 import com.brickssoft.locationtracking.data.LocationStore
 import com.brickssoft.locationtracking.device.DeviceMonitor
+import com.brickssoft.locationtracking.http.HttpSyncer
 import com.brickssoft.locationtracking.model.HeartbeatMeta
 import com.brickssoft.locationtracking.model.HeartbeatStatus
 import com.brickssoft.locationtracking.model.HeartbeatStrategy
@@ -70,8 +71,14 @@ import kotlin.coroutines.cancellation.CancellationException
  *   idle-paced backup. A record every 5 s therefore sets the alarms once per 30 s instead of once per record. An alarm
  *   left in place fires up to 30 s early; [onAlarm] then finds the window not due, creates no heartbeat and arms the
  *   real due time.
- * - One partial wake lock per alarm delivery. It is released when the heartbeat has been submitted (the upload that
- *   the submit starts holds no wake lock) and times out after [WAKE_LOCK_TIMEOUT_MS] if something hangs.
+ * - One partial wake lock per alarm delivery. It is released when the heartbeat has been submitted and times out after
+ *   [WAKE_LOCK_TIMEOUT_MS] if something hangs.
+ * - **Upload wake lock** (recommendation 11d, `heartbeat.uploadKeepAwake`, default 10 s). Right before the alarm's
+ *   wake lock ends, a second wake lock is taken for the heartbeat's upload: it is released when the first upload pass
+ *   that started after the heartbeat was queued has finished ([HttpSyncer.awaitUpload]: uploaded, failed or nothing to
+ *   send), or after `uploadKeepAwake` seconds. So the heartbeat reaches the server on time instead of when the phone
+ *   next wakes up. The wait runs outside the alarm broadcast, so a slow upload cannot hold the broadcast past its limit.
+ *   With 0 there is no second wake lock (the behavior before this setting).
  * - The backend's last known location is requested only when `runtime.lastLocation` is null, and not again within
  *   [LAST_LOCATION_RETRY_MS] after the backend answered that it has none (a timeout or an error is retried at the
  *   next heartbeat).
@@ -91,6 +98,8 @@ class DefaultHeartbeatScheduler(
     private val clock: Clock,
     private val scope: CoroutineScope,
     private val alarms: HeartbeatAlarms = SystemHeartbeatAlarms(context),
+    /** The uploader whose pass the upload wake lock waits for; null = no upload wake lock. */
+    private val uploads: Lazy<HttpSyncer>? = null,
 ) : HeartbeatScheduler {
     private enum class Lifecycle {
         /** Fresh process: never started. An alarm may still arrive from a previous process. */
@@ -323,7 +332,9 @@ class DefaultHeartbeatScheduler(
                 Logger.d(TAG, "$trigger: superseded by a newer record or stop() while the heartbeat was built")
                 return
             }
+            val ticket = uploads?.let { tryOrNull("upload ticket") { it.value.uploadTicket() } }
             recordSink.value.submit(record)
+            keepAwakeForUpload(ticket)
             val meta = record.heartbeat
             Logger.i(
                 TAG,
@@ -625,13 +636,45 @@ class DefaultHeartbeatScheduler(
 
     // ---- wake lock
 
-    private fun acquireWakeLock(): PowerManager.WakeLock? = try {
-        powerManager?.newWakeLock(PowerManager.PARTIAL_WAKE_LOCK, WAKE_LOCK_TAG)?.apply {
-            setReferenceCounted(false)
-            acquire(WAKE_LOCK_TIMEOUT_MS)
+    private fun acquireWakeLock(timeoutMs: Long = WAKE_LOCK_TIMEOUT_MS, tag: String = WAKE_LOCK_TAG): PowerManager.WakeLock? =
+        try {
+            powerManager?.newWakeLock(PowerManager.PARTIAL_WAKE_LOCK, tag)?.apply {
+                setReferenceCounted(false)
+                acquire(timeoutMs)
+            }
+        } catch (e: RuntimeException) {
+            Logger.w(TAG, "cannot acquire the wake lock", e)
+            null
+        }
+
+    /**
+     * Keeps the phone awake until the first upload pass started after [ticket] has finished, at most
+     * `heartbeat.uploadKeepAwake` seconds (see the class docs). Taken before the caller's wake lock ends.
+     */
+    private fun keepAwakeForUpload(ticket: Long?) {
+        val syncer = uploads ?: return
+        val seconds = configStore.config.value.heartbeat.uploadKeepAwake
+        if (ticket == null || seconds <= 0) return
+        val limitMs = seconds * 1_000L
+        val wakeLock = acquireWakeLock(limitMs, UPLOAD_WAKE_LOCK_TAG)
+        scope.launch {
+            try {
+                val done = withTimeoutOrNull(limitMs) { syncer.value.awaitUpload(ticket) }
+                if (done == null) Logger.d(TAG, "heartbeat upload not finished within $seconds s; the phone may sleep")
+            } catch (e: CancellationException) {
+                throw e
+            } catch (e: Exception) {
+                Logger.w(TAG, "waiting for the heartbeat upload failed", e)
+            } finally {
+                release(wakeLock)
+            }
         }
-    } catch (e: RuntimeException) {
-        Logger.w(TAG, "cannot acquire the wake lock", e)
+    }
+
+    private inline fun <T> tryOrNull(what: String, block: () -> T): T? = try {
+        block()
+    } catch (e: Exception) {
+        Logger.w(TAG, "$what failed", e)
         null
     }
 
@@ -689,6 +732,7 @@ class DefaultHeartbeatScheduler(
         const val TAG = "LT.Heartbeat"
         const val LISTENER_TAG = "lt-heartbeat"
         const val WAKE_LOCK_TAG = "LocationTracking:heartbeat"
+        const val UPLOAD_WAKE_LOCK_TAG = "LocationTracking:heartbeat-upload"
 
         /**
          * Upper bound of the heartbeat wake lock. The lock is released as soon as the heartbeat is submitted

package/android/src/main/java/com/brickssoft/locationtracking/heartbeat/HeartbeatAlarmReceiver.kt

@@ -40,6 +40,10 @@ class HeartbeatAlarmReceiver : BroadcastReceiver() {
         /**
          * The post-alarm decision: run the heartbeat, then restore tracking if it is enabled while the foreground
          * service is not running. Failures are logged; the restore check runs even if the heartbeat failed.
+         *
+         * In a process that started after the user stopped the app (the Android 13+ Task Manager's Stop leaves the
+         * alarms in place), no heartbeat is created: the engine's restore releases the alarms and records the user stop
+         * instead (recommendation 6).
          */
         suspend fun deliver(
             trigger: HeartbeatTrigger,
@@ -48,6 +52,24 @@ class HeartbeatAlarmReceiver : BroadcastReceiver() {
             serviceController: Lazy<ServiceController>,
             engine: Lazy<TrackingEngine>,
         ) {
+            val userStopped = try {
+                configStore.runtime.value.enabled && !serviceController.value.isRunning &&
+                    engine.value.startedAfterUserStop()
+            } catch (e: Exception) {
+                Logger.w(TAG, "cannot tell whether the user stopped the app", e)
+                false
+            }
+            if (userStopped) {
+                Logger.i(TAG, "heartbeat alarm ($trigger) after a user stop: no heartbeat")
+                try {
+                    engine.value.restore("restore")
+                } catch (e: CancellationException) {
+                    throw e
+                } catch (e: Exception) {
+                    Logger.e(TAG, "handling the user stop failed", e)
+                }
+                return
+            }
             try {
                 heartbeat.onAlarm(trigger)
             } catch (e: CancellationException) {

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

@@ -27,9 +27,16 @@ import java.io.IOException
  *   a 401 (at most once per upload; the caller enforces that).
  * - A refresh POSTs `refreshPayload` (string values with `{refreshToken}` substituted, JSON or form encoded) with
  *   `refreshHeaders` to `refreshUrl`, reads `accessToken|access_token`, `refreshToken|refresh_token` and
- *   `expires|expires_at` (epoch; seconds if < 1e12) or `expires_in` (relative seconds), persists the new tokens with
- *   `configStore.update` and emits an `Authorization` event (also on failure).
- * - Refreshes are single-flight: callers that waited while another caller replaced their stale token reuse it.
+ *   `expires|expires_at` (epoch; seconds if < 1e12) or `expires_in` (relative seconds), and emits an `Authorization`
+ *   event (also on failure). The refresh answer is read in full: the new tokens are parsed from it.
+ * - **One identity per upload** (recommendation 2). An upload reads the [Credentials] once, at its start, and every
+ *   try of that upload uses only them or credentials refreshed from them. When the configured tokens differ from them
+ *   (the app called `setConfig` with another user's token, or removed the authorization), [renew] and [prepare]
+ *   answer [Outcome.CHANGED] and the upload stops, keeping its records.
+ * - **Compare-and-set save.** A refresh saves its new tokens only if the configured access and refresh tokens are still
+ *   the ones it started from; otherwise the new tokens are dropped and the answer is [Outcome.CHANGED]. A refresh that
+ *   finishes after the app configured another user can therefore never overwrite that user's tokens.
+ * - Refreshes are single-flight (one at a time).
  *
  * Token values are never logged.
  */
@@ -48,8 +55,28 @@ internal class AuthorizationManager(
     @Volatile
     private var shortLivedToken: String? = null
 
-    /** The access token to send ([value] null = no Authorization header) and whether a refresh was attempted. */
-    data class Token(val value: String?, val refreshAttempted: Boolean)
+    /** The access and refresh tokens one upload is sent with (blank values are null). */
+    data class Credentials(val accessToken: String?, val refreshToken: String?) {
+        override fun toString(): String = "Credentials(redacted)"
+    }
+
+    /** What [prepare] or [renew] found. */
+    enum class Outcome {
+        /** The credentials are usable as they are (no refresh was needed, or [prepare] may not refresh). */
+        UNCHANGED,
+
+        /** The token was refreshed; use the returned credentials. */
+        RENEWED,
+
+        /** A refresh was needed but failed or is not possible (no `refreshUrl`). */
+        FAILED,
+
+        /** The configured tokens are no longer the upload's: stop the upload and keep its records. */
+        CHANGED,
+    }
+
+    /** [credentials] to send with and what happened; [refreshAttempted] is true if a refresh request was made. */
+    data class Result(val outcome: Outcome, val credentials: Credentials, val refreshAttempted: Boolean)
 
     /** Tokens read from a refresh response; [expires] is epoch ms or -1 if unknown. */
     data class Tokens(val accessToken: String, val refreshToken: String?, val expires: Long)
@@ -58,29 +85,38 @@ internal class AuthorizationManager(
     fun appliesTo(http: HttpConfig): Boolean =
         http.authorization != null && !HttpSupport.hasHeader(http.headers, HttpSupport.AUTHORIZATION)
 
+    /** The configured credentials, or null without `http.authorization`. */
+    fun current(): Credentials? = configStore.config.value.http.authorization?.let(::credentialsOf)
+
+    /** True while the configured credentials are still [credentials]. */
+    fun isCurrent(credentials: Credentials): Boolean = current() == credentials
+
     /**
-     * The token for the next request, refreshing first if it is missing or about to expire (and refreshable), unless
-     * [mayRefresh] is false.
+     * Before a request with [credentials]: refreshes first if the token is missing or about to expire and a refresh is
+     * possible, unless [mayRefresh] is false. Never answers [Outcome.FAILED] for a token that is still usable; a failed
+     * refresh of an expiring token keeps sending the old one ([Outcome.FAILED] with the old credentials).
      */
-    suspend fun tokenForRequest(client: OkHttpClient, mayRefresh: Boolean = true): Token {
-        val auth = configStore.config.value.http.authorization ?: return Token(null, false)
-        val current = auth.accessToken.nonBlank()
-        if (!mayRefresh || !needsRefresh(auth) || !canRefresh(auth)) return Token(current, false)
-        return Token(refresh(client, current) ?: current, true)
+    suspend fun prepare(client: OkHttpClient, credentials: Credentials, mayRefresh: Boolean): Result {
+        val auth = configStore.config.value.http.authorization
+        if (auth == null || credentialsOf(auth) != credentials) return Result(Outcome.CHANGED, credentials, false)
+        if (!mayRefresh || !needsRefresh(auth) || !canRefresh(auth)) return Result(Outcome.UNCHANGED, credentials, false)
+        return renew(client, credentials)
     }
 
     /**
-     * Refreshes the token (single-flight) unless another caller already replaced [staleToken] with a token that
-     * does not need a refresh. Returns the token to use, or null if there is none (refresh failed or impossible).
+     * Refreshes [from] (single-flight). [Outcome.CHANGED] if the configured tokens are no longer [from] (before or after
+     * the refresh request); [Outcome.FAILED] if the refresh failed or is not possible.
      */
-    suspend fun refresh(client: OkHttpClient, staleToken: String?): String? = mutex.withLock {
-        val auth = configStore.config.value.http.authorization ?: return@withLock null
-        val current = auth.accessToken.nonBlank()
-        if (current != null && current != staleToken && !needsRefresh(auth)) return@withLock current
-        if (!canRefresh(auth)) return@withLock null
-        performRefresh(client, auth)
+    suspend fun renew(client: OkHttpClient, from: Credentials): Result = mutex.withLock {
+        val auth = configStore.config.value.http.authorization
+        if (auth == null || credentialsOf(auth) != from) return@withLock Result(Outcome.CHANGED, from, false)
+        if (!canRefresh(auth)) return@withLock Result(Outcome.FAILED, from, false)
+        performRefresh(client, auth, from)
     }
 
+    private fun credentialsOf(auth: AuthorizationConfig) =
+        Credentials(auth.accessToken.nonBlank(), auth.refreshToken.nonBlank())
+
     private fun canRefresh(auth: AuthorizationConfig): Boolean = !auth.refreshUrl.isNullOrBlank()
 
     private fun needsRefresh(auth: AuthorizationConfig): Boolean {
@@ -91,12 +127,13 @@ internal class AuthorizationManager(
         return now >= auth.expires || (now >= auth.expires - EXPIRY_MARGIN_MS && token != shortLivedToken)
     }
 
-    private suspend fun performRefresh(client: OkHttpClient, auth: AuthorizationConfig): String? {
+    private suspend fun performRefresh(client: OkHttpClient, auth: AuthorizationConfig, from: Credentials): Result {
+        val failed = Result(Outcome.FAILED, from, refreshAttempted = true)
         val url = HttpSupport.parseUrl(auth.refreshUrl)
         if (url == null) {
             Logger.e(TAG, "authorization.refreshUrl is not a valid http(s) URL")
             emit(false, 0, "authorization.refreshUrl is not a valid http(s) URL", null)
-            return null
+            return failed.copy(refreshAttempted = false)
         }
         val (contentType, body) = refreshBody(auth)
         val headers = HttpSupport.headers(contentType, auth.refreshHeaders, bearerToken = null)
@@ -107,36 +144,50 @@ internal class AuthorizationManager(
             currentCoroutineContext().ensureActive()
             Logger.w(TAG, "token refresh failed: ${e.message}")
             emit(false, 0, e.message ?: e.javaClass.simpleName, null)
-            return null
+            return failed
         }
         val json = JsonUtil.parseObject(response.body)
         if (!response.isSuccessful) {
             Logger.w(TAG, "token refresh failed: HTTP ${response.status}")
             emit(false, response.status, "HTTP ${response.status}", json?.toString())
-            return null
+            return failed
         }
         val tokens = parseTokens(json, clock.now())
         if (tokens == null) {
             Logger.w(TAG, "token refresh response (HTTP ${response.status}) has no accessToken")
             emit(false, response.status, "refresh response has no accessToken", json?.toString())
-            return null
+            return failed
         }
+        var saved: Credentials? = null
         configStore.update { config ->
-            // Do not resurrect an authorization config removed while the refresh was in flight.
+            // Only onto the tokens the refresh started from: the app may have removed the authorization or configured
+            // another user while the refresh was in flight.
             val current = config.http.authorization ?: return@update config
+            if (credentialsOf(current) != from) return@update config
             val updated = current.copy(
                 accessToken = tokens.accessToken,
                 refreshToken = tokens.refreshToken ?: current.refreshToken,
                 expires = tokens.expires,
             )
+            saved = credentialsOf(updated)
             config.copy(http = config.http.copy(authorization = updated))
         }
+        val renewed = saved
+        if (renewed == null) {
+            Logger.w(TAG, "the authorization changed while its token was refreshed; the new tokens are not saved")
+            return Result(Outcome.CHANGED, from, refreshAttempted = true)
+        }
         val shortLived = tokens.expires > 0 && tokens.expires - clock.now() <= EXPIRY_MARGIN_MS
         shortLivedToken = if (shortLived) tokens.accessToken else null
         if (shortLived) Logger.w(TAG, "refreshed access token expires within ${EXPIRY_MARGIN_MS / 1000} s")
         Logger.i(TAG, "access token refreshed (HTTP ${response.status})")
         emit(true, response.status, null, json?.toString())
-        return tokens.accessToken
+        return Result(Outcome.RENEWED, renewed, refreshAttempted = true)
+    }
+
+    /** Emits an `Authorization` event with [error] and no request (for example the stored tokens cannot be read). */
+    fun reportUnusable(error: String) {
+        emit(false, 0, error, null)
     }
 
     private fun emit(success: Boolean, status: Int, error: String?, responseJson: String?) {

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

@@ -0,0 +1,140 @@
+package com.brickssoft.locationtracking.http
+
+import com.brickssoft.locationtracking.config.Config
+import com.brickssoft.locationtracking.config.HttpConfig
+import com.brickssoft.locationtracking.core.ErrorCode
+import com.brickssoft.locationtracking.core.TrackingException
+import com.brickssoft.locationtracking.model.AccuracyLevel
+import com.brickssoft.locationtracking.model.ActivitySample
+import com.brickssoft.locationtracking.model.ActivityType
+import com.brickssoft.locationtracking.model.BatteryDetails
+import com.brickssoft.locationtracking.model.BatterySnapshot
+import com.brickssoft.locationtracking.model.ConnectivityType
+import com.brickssoft.locationtracking.model.DeviceSnapshot
+import com.brickssoft.locationtracking.model.GeofenceAction
+import com.brickssoft.locationtracking.model.GeofenceHit
+import com.brickssoft.locationtracking.model.HeartbeatMeta
+import com.brickssoft.locationtracking.model.HeartbeatStrategy
+import com.brickssoft.locationtracking.model.PermissionLevel
+import com.brickssoft.locationtracking.model.ProviderKind
+import com.brickssoft.locationtracking.model.ProviderState
+import com.brickssoft.locationtracking.model.Record
+import com.brickssoft.locationtracking.model.RecordEvent
+import com.brickssoft.locationtracking.model.TrackedLocation
+import okhttp3.Headers
+
+/**
+ * Checks of a config the app gives (`ready()`, `setConfig()`, `reset()`) that [com.brickssoft.locationtracking.config.
+ * ConfigValidator] cannot fix by clamping (recommendation 14). Mistakes that would otherwise show only at upload time
+ * reject the call with `INVALID_ARGUMENT`, and nothing is applied:
+ * - `http.url` (unless unset or blank): an http or https URL with a host, without user info (`user:password@`) and
+ *   without a fragment (`#…`);
+ * - `http.headers` and `http.authorization.refreshHeaders`: names and values that OkHttp accepts (ASCII, no line
+ *   breaks). A rejected header is named; its value is never repeated;
+ * - `http.locationTemplate` and `http.geofenceTemplate`: every `<%= name %>` placeholder is known, and the template
+ *   renders to a valid JSON object or array ([StrictJson]) for a sample record with every field set and for one with
+ *   none set.
+ *
+ * [warnings] lists what is accepted but probably wrong: an `http://` upload URL (Android 9+ blocks cleartext traffic
+ * unless the app's network security config allows that host).
+ */
+internal object ConfigChecks {
+    /** Throws `INVALID_ARGUMENT` for the first mistake found; returns [warnings] otherwise. */
+    fun check(config: Config): List<String> {
+        val http = config.http
+        checkUrl(http)
+        checkHeaders("http.headers", http.headers)
+        http.authorization?.let { checkHeaders("http.authorization.refreshHeaders", it.refreshHeaders) }
+        checkTemplate("http.locationTemplate", http.locationTemplate)
+        checkTemplate("http.geofenceTemplate", http.geofenceTemplate)
+        return warnings(config)
+    }
+
+    fun warnings(config: Config): List<String> {
+        val url = HttpSupport.parseUrl(config.http.url) ?: return emptyList()
+        if (url.scheme != "http") return emptyList()
+        return listOf(
+            "http.url uses http://: Android 9+ blocks cleartext traffic unless the app's network security config " +
+                "allows ${url.host}; uploads would fail until then",
+        )
+    }
+
+    private fun checkUrl(http: HttpConfig) {
+        val text = http.url?.takeIf { it.isNotBlank() } ?: return
+        val url = HttpSupport.parseUrl(text) ?: invalid("http.url must be an http(s) URL with a host")
+        if (url.host.isEmpty()) invalid("http.url must have a host")
+        if (url.username.isNotEmpty() || url.password.isNotEmpty()) {
+            invalid("http.url must not contain user info (user:password@); use http.headers")
+        }
+        if (url.fragment != null) invalid("http.url must not contain a fragment (#...)")
+    }
+
+    private fun checkHeaders(path: String, headers: Map<String, String>) {
+        for ((name, value) in headers) {
+            try {
+                Headers.Builder().add(name, value)
+            } catch (e: IllegalArgumentException) {
+                // Never repeat the value: it may be a credential.
+                invalid("$path: header '${name.take(MAX_ECHO)}' has an invalid name or value (ASCII only, no line breaks)")
+            }
+        }
+    }
+
+    private fun checkTemplate(path: String, template: String?) {
+        if (template.isNullOrBlank()) return
+        val unknown = TemplateRenderer.placeholderNames(template) - TemplateRenderer.PLACEHOLDERS
+        if (unknown.isNotEmpty()) {
+            invalid("$path has unknown placeholder(s) ${unknown.joinToString { "'${it.take(MAX_ECHO)}'" }}")
+        }
+        for (sample in SAMPLES) {
+            val text = TemplateRenderer.renderText(template, sample, sample.recordedAt)
+            if (!StrictJson.isValid(text) || !(text.trimStart().startsWith("{") || text.trimStart().startsWith("["))) {
+                invalid("$path does not render to a JSON object or array (check the quotes around string placeholders)")
+            }
+        }
+    }
+
+    private fun invalid(message: String): Nothing = throw TrackingException(ErrorCode.INVALID_ARGUMENT, "config.$message")
+
+    private const val MAX_ECHO = 40
+    private const val SAMPLE_TIME = 1_790_000_000_000L
+
+    /** A record with every field set, and one with none (no location, no geofence, no provider). */
+    private val SAMPLES: List<Record> by lazy {
+        val full = Record(
+            uuid = "00000000-0000-4000-8000-000000000000",
+            event = RecordEvent.GEOFENCE,
+            location = TrackedLocation(
+                latitude = 52.5, longitude = 13.4, accuracy = 5f, altitude = 34.0, altitudeAccuracy = 3f, speed = 1.5f,
+                speedAccuracy = 0.5f, heading = 90f, headingAccuracy = 10f, time = SAMPLE_TIME, isMock = false,
+            ),
+            recordedAt = SAMPLE_TIME,
+            elapsedRealtimeMs = 1_000L,
+            bootCount = 1,
+            isMoving = true,
+            odometer = 10.0,
+            activity = ActivitySample(ActivityType.WALKING, 80),
+            battery = BatterySnapshot(0.5f, false),
+            backend = ProviderKind.GMS,
+            extras = """{"k":"v"}""",
+            geofence = GeofenceHit("id", GeofenceAction.ENTER, """{"k":"v"}"""),
+            provider = ProviderState(true, true, true, PermissionLevel.ALWAYS, AccuracyLevel.PRECISE, ProviderKind.GMS),
+            reason = "start",
+            heartbeat = HeartbeatMeta(HeartbeatStrategy.EXACT, 180, 300, SAMPLE_TIME, true, false),
+            stoppedAt = SAMPLE_TIME,
+            network = ConnectivityType.WIFI,
+            device = DeviceSnapshot(
+                backgroundRestricted = false, standbyBucket = "active", diskFreeBytes = 1L, thermalStatus = "none",
+                manufacturer = "m", model = "m", osVersion = "14", sdkInt = 34, deviceId = "a", lowRamDevice = false,
+                ramTotalBytes = 1L,
+            ),
+            batteryDetails = BatteryDetails(30f, "good", "ac"),
+        )
+        val empty = Record(
+            uuid = full.uuid, event = RecordEvent.HEARTBEAT, location = null, recordedAt = SAMPLE_TIME,
+            elapsedRealtimeMs = 1_000L, bootCount = -1, isMoving = false, odometer = 0.0,
+            activity = ActivitySample.UNKNOWN, battery = BatterySnapshot.UNKNOWN, backend = null,
+        )
+        listOf(full, empty)
+    }
+}

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

@@ -17,8 +17,11 @@ import java.util.Locale
 import java.util.concurrent.TimeUnit
 import java.util.concurrent.atomic.AtomicBoolean
 
-/** Status and body text of a completed HTTP exchange. */
-internal data class HttpResponse(val status: Int, val body: String) {
+/**
+ * Status and body text of a completed HTTP exchange. [retryAfter] is the raw `Retry-After` header value, if the server
+ * sent one.
+ */
+internal data class HttpResponse(val status: Int, val body: String, val retryAfter: String? = null) {
     val isSuccessful: Boolean get() = status in 200..299
 }
 
@@ -28,20 +31,45 @@ internal object HttpSupport {
 
     const val CONTENT_TYPE = "Content-Type"
     const val AUTHORIZATION = "Authorization"
+    const val RETRY_AFTER = "Retry-After"
     const val JSON_CONTENT_TYPE = "application/json; charset=utf-8"
     const val FORM_CONTENT_TYPE = "application/x-www-form-urlencoded"
 
+    /** Most bytes of an upload answer that are read and passed on in the `http` event (16 KB). */
+    const val MAX_UPLOAD_RESPONSE_BYTES = 16_384L
+
+    /**
+     * The plugin's shared client (uploads, token refresh, `uploadLog`). It follows no redirects: OkHttp would send a
+     * redirected POST again as a GET without a body, and a 2xx answer to that GET would delete records the server never
+     * received. A 3xx is therefore an answer like any other non-2xx one. It also does not repeat a request on its own
+     * after a connection failure; the uploader decides about retries.
+     */
+    fun sharedClient(): OkHttpClient = OkHttpClient.Builder()
+        .followRedirects(false)
+        .followSslRedirects(false)
+        .retryOnConnectionFailure(false)
+        .build()
+
     /** Parses an http(s) URL (surrounding whitespace ignored); null if blank or invalid. */
     fun parseUrl(url: String?): HttpUrl? = url?.trim()?.takeIf { it.isNotEmpty() }?.toHttpUrlOrNull()
 
-    /** A client derived from [base] (sharing its pool) whose call, read and write timeouts are [timeoutMs]. */
+    /**
+     * A client derived from [base] (sharing its pool) whose call, read and write timeouts are [timeoutMs] (unless
+     * [timeoutMs] <= 0). Whatever [base] is configured with, the derived client follows no redirects and does not
+     * repeat a request after a connection failure (see [sharedClient]).
+     */
     fun client(base: OkHttpClient, timeoutMs: Long): OkHttpClient {
-        if (timeoutMs <= 0) return base
-        return base.newBuilder()
-            .callTimeout(timeoutMs, TimeUnit.MILLISECONDS)
-            .readTimeout(timeoutMs, TimeUnit.MILLISECONDS)
-            .writeTimeout(timeoutMs, TimeUnit.MILLISECONDS)
-            .build()
+        val builder = base.newBuilder()
+            .followRedirects(false)
+            .followSslRedirects(false)
+            .retryOnConnectionFailure(false)
+        if (timeoutMs > 0) {
+            builder
+                .callTimeout(timeoutMs, TimeUnit.MILLISECONDS)
+                .readTimeout(timeoutMs, TimeUnit.MILLISECONDS)
+                .writeTimeout(timeoutMs, TimeUnit.MILLISECONDS)
+        }
+        return builder.build()
     }
 
     /** True if [headers] contains [name], ignoring case. */
@@ -86,10 +114,16 @@ internal object HttpSupport {
     /**
      * Executes [request] on [io]. Cancelling the coroutine cancels the call (OkHttp does not support thread
      * interrupts). A body that fails to read after the status arrived yields "", because the server already answered.
+     * With [maxBodyBytes], at most that many bytes of the body are read (`peekBody`); the rest is discarded.
      *
      * @throws IOException if the exchange fails before a status is received.
      */
-    suspend fun execute(client: OkHttpClient, request: Request, io: CoroutineDispatcher): HttpResponse =
+    suspend fun execute(
+        client: OkHttpClient,
+        request: Request,
+        io: CoroutineDispatcher,
+        maxBodyBytes: Long? = null,
+    ): HttpResponse =
         withContext(io) {
             val call = client.newCall(request)
             val finished = AtomicBoolean(false)
@@ -103,12 +137,16 @@ internal object HttpSupport {
             try {
                 call.execute().use { response ->
                     val text = try {
-                        response.body?.string().orEmpty()
+                        if (maxBodyBytes != null) {
+                            response.peekBody(maxBodyBytes).string()
+                        } else {
+                            response.body?.string().orEmpty()
+                        }
                     } catch (e: IOException) {
                         Logger.w(TAG, "could not read the response body of HTTP ${response.code}: ${e.message}")
                         ""
                     }
-                    HttpResponse(response.code, text)
+                    HttpResponse(response.code, text, response.header(RETRY_AFTER))
                 }
             } finally {
                 finished.set(true)

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

@@ -15,4 +15,21 @@ interface HttpSyncer {
      * @throws com.brickssoft.locationtracking.core.TrackingException NO_URL, HTTP_ERROR or NETWORK_ERROR.
      */
     suspend fun sync(): List<Record>
+
+    /** Tracking stopped: make sure what is still queued is uploaded later, also if this process dies (upload job). */
+    fun onTrackingStopped() = Unit
+
+    /**
+     * The upload job runs: one automatic pass, and more while they succeed and leave records due. Returns when done.
+     */
+    suspend fun runScheduledPass() = Unit
+
+    /** A ticket for [awaitUpload]; take it before the record whose upload is awaited is queued. */
+    fun uploadTicket(): Long = 0L
+
+    /**
+     * Suspends until the first automatic pass started after [ticket] was taken has finished (uploaded, failed, or
+     * found nothing to send). Returns at once if no `http.url` is set. Callers bound the wait with a timeout.
+     */
+    suspend fun awaitUpload(ticket: Long) = Unit
 }