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

package/android/src/main/java/com/brickssoft/locationtracking/config/ConfigValidator.kt

@@ -0,0 +1,170 @@
+package com.brickssoft.locationtracking.config
+
+import com.brickssoft.locationtracking.core.Constants
+import com.brickssoft.locationtracking.core.Logger
+
+/**
+ * Clamps config values to their allowed ranges and logs a warning for each value it changes. Never throws.
+ *
+ * - `heartbeat.minInterval` >= 60 s and `heartbeat.maxInterval` >= `minInterval`;
+ * - `activity.minimumActivityRecognitionConfidence` in 0..100;
+ * - `geolocation.stationaryRadius` >= 1; distances, intervals, delays and filter thresholds >= 0;
+ * - `geolocation.locationTimeout` and `http.timeout` > 0 (otherwise their defaults);
+ * - `http.maxBatchSize` >= 1, `http.autoSyncThreshold` >= 0, `http.syncInterval` >= 0;
+ * - `persistence.maxDaysToPersist` >= 1, `persistence.maxRecordsToPersist` >= -1 (-1 = unlimited);
+ * - `logger.logMaxDays` >= 1;
+ * - at most [Constants.MAX_NOTIFICATION_ACTIONS] notification actions (the first ones are kept);
+ * - non-finite numbers become their defaults.
+ */
+object ConfigValidator {
+    private const val TAG = "LT.ConfigValidator"
+
+    /** Smallest allowed `heartbeat.minInterval`, seconds. */
+    const val MIN_HEARTBEAT_INTERVAL_S = 60
+
+    const val MIN_STATIONARY_RADIUS_M = 1.0
+
+    /** Returns [config] with every out-of-range value clamped (equal to [config] when all values are valid). */
+    fun validate(config: Config): Config {
+        val validated = config.copy(
+            geolocation = geolocation(config.geolocation),
+            activity = activity(config.activity),
+            heartbeat = heartbeat(config.heartbeat),
+            http = http(config.http),
+            persistence = persistence(config.persistence),
+            notification = notification(config.notification),
+            logger = config.logger.copy(logMaxDays = atLeast("logger.logMaxDays", config.logger.logMaxDays, 1)),
+        )
+        return if (validated == config) config else validated
+    }
+
+    private fun geolocation(g: GeolocationConfig): GeolocationConfig {
+        val d = GeolocationConfig()
+        return g.copy(
+            distanceFilter = atLeast("geolocation.distanceFilter", g.distanceFilter, 0.0, d.distanceFilter),
+            locationUpdateInterval = atLeast("geolocation.locationUpdateInterval", g.locationUpdateInterval, 0L),
+            fastestLocationUpdateInterval = atLeast(
+                "geolocation.fastestLocationUpdateInterval",
+                g.fastestLocationUpdateInterval,
+                0L,
+            ),
+            elasticityMultiplier = atLeast(
+                "geolocation.elasticityMultiplier",
+                g.elasticityMultiplier,
+                0.0,
+                d.elasticityMultiplier,
+            ),
+            stationaryRadius = atLeast(
+                "geolocation.stationaryRadius",
+                g.stationaryRadius,
+                MIN_STATIONARY_RADIUS_M,
+                d.stationaryRadius,
+            ),
+            stopTimeout = atLeast("geolocation.stopTimeout", g.stopTimeout, 0),
+            stopAfterElapsedMinutes = atLeast("geolocation.stopAfterElapsedMinutes", g.stopAfterElapsedMinutes, 0),
+            locationTimeout = positive("geolocation.locationTimeout", g.locationTimeout, d.locationTimeout),
+            filter = filter(g.filter),
+        )
+    }
+
+    private fun filter(f: LocationFilterConfig): LocationFilterConfig {
+        val d = LocationFilterConfig()
+        return f.copy(
+            trackingAccuracyThreshold = atLeast(
+                "geolocation.filter.trackingAccuracyThreshold",
+                f.trackingAccuracyThreshold,
+                0.0,
+                d.trackingAccuracyThreshold,
+            ),
+            maxImpliedSpeed = atLeast("geolocation.filter.maxImpliedSpeed", f.maxImpliedSpeed, 0.0, d.maxImpliedSpeed),
+            odometerAccuracyThreshold = atLeast(
+                "geolocation.filter.odometerAccuracyThreshold",
+                f.odometerAccuracyThreshold,
+                0.0,
+                d.odometerAccuracyThreshold,
+            ),
+        )
+    }
+
+    private fun activity(a: ActivityConfig): ActivityConfig = a.copy(
+        activityRecognitionInterval = atLeast(
+            "activity.activityRecognitionInterval",
+            a.activityRecognitionInterval,
+            0L,
+        ),
+        minimumActivityRecognitionConfidence = inRange(
+            "activity.minimumActivityRecognitionConfidence",
+            a.minimumActivityRecognitionConfidence,
+            0,
+            100,
+        ),
+        motionTriggerDelay = atLeast("activity.motionTriggerDelay", a.motionTriggerDelay, 0L),
+    )
+
+    private fun heartbeat(h: HeartbeatConfig): HeartbeatConfig {
+        val min = atLeast("heartbeat.minInterval", h.minInterval, MIN_HEARTBEAT_INTERVAL_S)
+        val max = atLeast("heartbeat.maxInterval", h.maxInterval, min)
+        return h.copy(minInterval = min, maxInterval = max)
+    }
+
+    private fun http(h: HttpConfig): HttpConfig = h.copy(
+        autoSyncThreshold = atLeast("http.autoSyncThreshold", h.autoSyncThreshold, 0),
+        syncInterval = atLeast("http.syncInterval", h.syncInterval, 0),
+        maxBatchSize = atLeast("http.maxBatchSize", h.maxBatchSize, 1),
+        timeout = positive("http.timeout", h.timeout, HttpConfig().timeout),
+    )
+
+    private fun persistence(p: PersistenceConfig): PersistenceConfig = p.copy(
+        maxDaysToPersist = atLeast("persistence.maxDaysToPersist", p.maxDaysToPersist, 1),
+        maxRecordsToPersist = atLeast("persistence.maxRecordsToPersist", p.maxRecordsToPersist, -1),
+    )
+
+    private fun notification(n: NotificationConfig): NotificationConfig {
+        val max = Constants.MAX_NOTIFICATION_ACTIONS
+        if (n.actions.size <= max) return n
+        Logger.w(TAG, "notification.actions has ${n.actions.size} entries; keeping the first $max")
+        return n.copy(actions = n.actions.take(max))
+    }
+
+    // ---- clamps (each logs when it changes a value)
+
+    private fun atLeast(path: String, value: Int, min: Int): Int {
+        if (value >= min) return value
+        clamped(path, value, min)
+        return min
+    }
+
+    private fun atLeast(path: String, value: Long, min: Long): Long {
+        if (value >= min) return value
+        clamped(path, value, min)
+        return min
+    }
+
+    /** Non-finite [value]s become [fallback]. */
+    private fun atLeast(path: String, value: Double, min: Double, fallback: Double): Double {
+        if (!value.isFinite()) {
+            clamped(path, value, fallback)
+            return fallback
+        }
+        if (value >= min) return value
+        clamped(path, value, min)
+        return min
+    }
+
+    private fun inRange(path: String, value: Int, min: Int, max: Int): Int {
+        val result = value.coerceIn(min, max)
+        if (result != value) clamped(path, value, result)
+        return result
+    }
+
+    /** Values <= 0 become [fallback]. */
+    private fun positive(path: String, value: Long, fallback: Long): Long {
+        if (value > 0) return value
+        clamped(path, value, fallback)
+        return fallback
+    }
+
+    private fun clamped(path: String, from: Any, to: Any) {
+        Logger.w(TAG, "config $path=$from is out of range; using $to")
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/config/RuntimeStateJson.kt

@@ -0,0 +1,73 @@
+package com.brickssoft.locationtracking.config
+
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.model.ActivitySample
+import com.brickssoft.locationtracking.model.ActivityType
+import com.brickssoft.locationtracking.model.JsonUtil
+import com.brickssoft.locationtracking.model.ProviderStateJson
+import com.brickssoft.locationtracking.model.TrackedLocation
+import com.brickssoft.locationtracking.model.TrackedLocationJson
+import org.json.JSONObject
+
+/**
+ * Lossless persistence JSON for [RuntimeState] (not a JS shape). Keys use the Kotlin property names; times are
+ * epoch ms. [fromJson] is lenient: a missing or invalid field falls back to its default.
+ */
+internal object RuntimeStateJson {
+    private const val TAG = "LT.RuntimeStateJson"
+
+    fun toJson(r: RuntimeState): JSONObject = JSONObject()
+        .put("enabled", r.enabled)
+        .put("trackingMode", r.trackingMode.wire)
+        .put("isMoving", r.isMoving)
+        .put("odometer", if (r.odometer.isFinite()) r.odometer else 0.0)
+        .put("activity", JSONObject().put("type", r.activity.type.wire).put("confidence", r.activity.confidence))
+        .put("lastLocation", r.lastLocation?.let { lastLocationToJson(it) } ?: JSONObject.NULL)
+        .put("lastRecordAt", JsonUtil.orNull(r.lastRecordAt))
+        .put("lastRecordElapsed", JsonUtil.orNull(r.lastRecordElapsed))
+        .put("lastRecordBootCount", JsonUtil.orNull(r.lastRecordBootCount))
+        .put("lastHeartbeatAt", JsonUtil.orNull(r.lastHeartbeatAt))
+        .put("trackingStartedAt", JsonUtil.orNull(r.trackingStartedAt))
+        .put("providerState", r.providerState?.let { ProviderStateJson.toJson(it) } ?: JSONObject.NULL)
+        .put("didReady", r.didReady)
+
+    fun fromJson(json: JSONObject): RuntimeState {
+        val d = RuntimeState()
+        return RuntimeState(
+            enabled = JsonUtil.optBoolean(json, "enabled") ?: d.enabled,
+            trackingMode = TrackingMode.fromWire(JsonUtil.optString(json, "trackingMode")) ?: d.trackingMode,
+            isMoving = JsonUtil.optBoolean(json, "isMoving") ?: d.isMoving,
+            odometer = JsonUtil.optDouble(json, "odometer") ?: d.odometer,
+            activity = json.optJSONObject("activity")?.let { a ->
+                ActivitySample(
+                    type = ActivityType.fromWire(JsonUtil.optString(a, "type")) ?: ActivityType.UNKNOWN,
+                    confidence = JsonUtil.optInt(a, "confidence") ?: 0,
+                )
+            } ?: d.activity,
+            lastLocation = json.optJSONObject("lastLocation")?.let { l ->
+                try {
+                    TrackedLocationJson.fromJson(l)
+                } catch (e: Exception) {
+                    Logger.w(TAG, "dropping invalid persisted lastLocation", e)
+                    null
+                }
+            },
+            lastRecordAt = JsonUtil.optLong(json, "lastRecordAt"),
+            lastRecordElapsed = JsonUtil.optLong(json, "lastRecordElapsed"),
+            lastRecordBootCount = JsonUtil.optInt(json, "lastRecordBootCount"),
+            lastHeartbeatAt = JsonUtil.optLong(json, "lastHeartbeatAt"),
+            trackingStartedAt = JsonUtil.optLong(json, "trackingStartedAt"),
+            providerState = json.optJSONObject("providerState")?.let { ProviderStateJson.fromJson(it) },
+            didReady = JsonUtil.optBoolean(json, "didReady") ?: d.didReady,
+        )
+    }
+
+    /** org.json rejects NaN/Infinity, so a location with non-finite coordinates is not persisted. */
+    private fun lastLocationToJson(l: TrackedLocation): Any =
+        if (l.latitude.isFinite() && l.longitude.isFinite() && (l.altitude?.isFinite() != false)) {
+            TrackedLocationJson.toJson(l)
+        } else {
+            Logger.w(TAG, "not persisting lastLocation with non-finite coordinates")
+            JSONObject.NULL
+        }
+}

package/android/src/main/java/com/brickssoft/locationtracking/config/SharedPrefsConfigStore.kt

@@ -0,0 +1,135 @@
+package com.brickssoft.locationtracking.config
+
+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 kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import org.json.JSONObject
+
+/**
+ * [ConfigStore] backed by the SharedPreferences file [Constants.PREFS_NAME].
+ *
+ * Config and runtime state are loaded synchronously in the constructor. An unreadable stored value falls back to
+ * its default; unreadable JSON text falls back to all defaults.
+ *
+ * Every write runs under one lock: it computes the new value, persists it with `apply()` and publishes it on the
+ * matching [StateFlow] before returning. Config writes go through [ConfigJson.parse] and [ConfigValidator].
+ * Only the `cfg_` keys of the shared prefs file are touched.
+ */
+class SharedPrefsConfigStore(
+    context: Context,
+    @Suppress("unused") private val clock: Clock,
+) : ConfigStore {
+    private val prefs: SharedPreferences =
+        (context.applicationContext ?: context).getSharedPreferences(Constants.PREFS_NAME, Context.MODE_PRIVATE)
+    private val lock = Any()
+
+    private val configFlow = MutableStateFlow(loadConfig())
+    private val runtimeFlow = MutableStateFlow(loadRuntime())
+
+    override val config: StateFlow<Config> = configFlow.asStateFlow()
+    override val runtime: StateFlow<RuntimeState> = runtimeFlow.asStateFlow()
+
+    override fun ready(json: JSONObject?, reset: Boolean): Config = synchronized(lock) {
+        val current = configFlow.value
+        val next = when {
+            reset -> build(json, Config())
+            !runtimeFlow.value.didReady -> build(json, current)
+            else -> {
+                if (json != null && json.length() > 0) {
+                    Logger.i(TAG, "ready(reset=false): keeping the persisted config; the given config is ignored")
+                }
+                current
+            }
+        }
+        val runtime = runtimeFlow.value.copy(didReady = true)
+        persist(next.takeIf { it != current }, runtime.takeIf { it != runtimeFlow.value })
+        configFlow.value = next
+        runtimeFlow.value = runtime
+        next
+    }
+
+    override fun merge(json: JSONObject): Config = setConfig { build(json, it) }
+
+    override fun reset(json: JSONObject?): Config = setConfig { build(json, Config()) }
+
+    override fun update(transform: (Config) -> Config): Config = setConfig { ConfigValidator.validate(transform(it)) }
+
+    override fun updateRuntime(transform: (RuntimeState) -> RuntimeState): RuntimeState = synchronized(lock) {
+        val current = runtimeFlow.value
+        val next = transform(current)
+        if (next != current) {
+            persist(null, next)
+            runtimeFlow.value = next
+        }
+        next
+    }
+
+    private inline fun setConfig(compute: (Config) -> Config): Config = synchronized(lock) {
+        val current = configFlow.value
+        val next = compute(current)
+        if (next != current) {
+            persist(next, null)
+            configFlow.value = next
+        }
+        next
+    }
+
+    /** Defaults-or-[base] plus [json], clamped. Throws INVALID_ARGUMENT (before anything changes) on bad input. */
+    private fun build(json: JSONObject?, base: Config): Config =
+        ConfigValidator.validate(if (json == null) base else ConfigJson.parse(json, base))
+
+    /** Writes the non-null values in one `apply()`. A value that cannot be serialized is logged and skipped. */
+    private fun persist(config: Config?, runtime: RuntimeState?) {
+        if (config == null && runtime == null) return
+        val editor = prefs.edit()
+        if (config != null) {
+            serialize("config") { ConfigJson.toJson(config) }?.let { editor.putString(KEY_CONFIG, it) }
+        }
+        if (runtime != null) {
+            serialize("runtime state") { RuntimeStateJson.toJson(runtime) }?.let { editor.putString(KEY_RUNTIME, it) }
+        }
+        editor.apply()
+    }
+
+    private inline fun serialize(what: String, toJson: () -> JSONObject): String? = try {
+        toJson().toString()
+    } catch (e: Exception) {
+        Logger.e(TAG, "cannot persist $what", e)
+        null
+    }
+
+    private fun loadConfig(): Config {
+        val text = prefs.getString(KEY_CONFIG, null) ?: return Config()
+        return try {
+            ConfigValidator.validate(ConfigJson.parseStored(JSONObject(text)))
+        } catch (e: Exception) {
+            Logger.e(TAG, "persisted config is unreadable; using defaults", e)
+            Config()
+        }
+    }
+
+    private fun loadRuntime(): RuntimeState {
+        val text = prefs.getString(KEY_RUNTIME, null) ?: return RuntimeState()
+        return try {
+            RuntimeStateJson.fromJson(JSONObject(text))
+        } catch (e: Exception) {
+            Logger.e(TAG, "persisted runtime state is unreadable; using defaults", e)
+            RuntimeState()
+        }
+    }
+
+    internal companion object {
+        private const val TAG = "LT.ConfigStore"
+
+        /** Full TS-shaped config JSON (`ConfigJson.toJson`). */
+        const val KEY_CONFIG = "cfg_config"
+
+        /** Runtime state JSON (`RuntimeStateJson`). */
+        const val KEY_RUNTIME = "cfg_runtime"
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/config/State.kt

@@ -0,0 +1,45 @@
+package com.brickssoft.locationtracking.config
+
+import com.brickssoft.locationtracking.model.ActivitySample
+import com.brickssoft.locationtracking.model.ProviderKind
+import com.brickssoft.locationtracking.model.ProviderState
+import com.brickssoft.locationtracking.model.TrackedLocation
+
+/** JS `TrackingMode`. */
+enum class TrackingMode(val wire: String) {
+    LOCATION("location"),
+    GEOFENCES("geofences"),
+    ;
+
+    companion object {
+        fun fromWire(value: String?): TrackingMode? = entries.firstOrNull { it.wire == value }
+    }
+}
+
+/**
+ * Persisted runtime state (survives process death).
+ *
+ * @property lastRecordAt wall time of the last persisted record, epoch ms.
+ * @property lastRecordElapsed elapsed-realtime ms of the last persisted record.
+ * @property lastRecordBootCount boot count when the last record was persisted.
+ * @property providerState last provider state seen, used to detect `providerchange` across process restarts.
+ * @property didReady true once `ready()` has ever completed (drives `ReadyOptions.reset=false`).
+ */
+data class RuntimeState(
+    val enabled: Boolean = false,
+    val trackingMode: TrackingMode = TrackingMode.LOCATION,
+    val isMoving: Boolean = false,
+    val odometer: Double = 0.0,
+    val activity: ActivitySample = ActivitySample.UNKNOWN,
+    val lastLocation: TrackedLocation? = null,
+    val lastRecordAt: Long? = null,
+    val lastRecordElapsed: Long? = null,
+    val lastRecordBootCount: Int? = null,
+    val lastHeartbeatAt: Long? = null,
+    val trackingStartedAt: Long? = null,
+    val providerState: ProviderState? = null,
+    val didReady: Boolean = false,
+)
+
+/** Snapshot returned to JS as `State` (see `ConfigJson.stateToJson`). */
+data class State(val config: Config, val runtime: RuntimeState, val backend: ProviderKind)

package/android/src/main/java/com/brickssoft/locationtracking/core/AppDispatchers.kt

@@ -0,0 +1,21 @@
+package com.brickssoft.locationtracking.core
+
+import kotlinx.coroutines.CoroutineDispatcher
+import kotlinx.coroutines.Dispatchers
+
+/**
+ * Dispatchers used by all components. Never hard-code `Dispatchers.IO`; inject this instead.
+ *
+ * @property main Android main thread.
+ * @property io SQLite, files and HTTP.
+ * @property engine single-threaded dispatcher on which all engine state changes happen.
+ */
+class AppDispatchers(
+    val main: CoroutineDispatcher,
+    val io: CoroutineDispatcher,
+    val engine: CoroutineDispatcher,
+) {
+    companion object {
+        val DEFAULT = AppDispatchers(Dispatchers.Main, Dispatchers.IO, Dispatchers.Default.limitedParallelism(1))
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/core/Clock.kt

@@ -0,0 +1,41 @@
+package com.brickssoft.locationtracking.core
+
+import android.content.Context
+import android.os.SystemClock
+import android.provider.Settings
+
+/** Time source. Units must use this instead of `System.currentTimeMillis()` so tests can control time. */
+interface Clock {
+    /** Wall-clock time, epoch ms. */
+    fun now(): Long
+
+    /** Milliseconds since boot, including deep sleep ([SystemClock.elapsedRealtime]). */
+    fun elapsedRealtime(): Long
+
+    /** `Settings.Global.BOOT_COUNT`, or -1 if unavailable. */
+    fun bootCount(): Int
+}
+
+/** Production [Clock]. */
+class SystemClockImpl(context: Context) : Clock {
+    private val appContext = context.applicationContext ?: context
+
+    @Volatile
+    private var cachedBootCount: Int? = null
+
+    override fun now(): Long = System.currentTimeMillis()
+
+    override fun elapsedRealtime(): Long = SystemClock.elapsedRealtime()
+
+    override fun bootCount(): Int {
+        cachedBootCount?.let { return it }
+        val value = try {
+            Settings.Global.getInt(appContext.contentResolver, Settings.Global.BOOT_COUNT, -1)
+        } catch (e: Exception) {
+            -1
+        }
+        // The boot count cannot change while this process is alive.
+        if (value >= 0) cachedBootCount = value
+        return value
+    }
+}