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

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

@@ -0,0 +1,109 @@
+package com.brickssoft.locationtracking.http
+
+import com.brickssoft.locationtracking.config.HttpConfig
+import com.brickssoft.locationtracking.model.Connectivity
+import com.brickssoft.locationtracking.model.ConnectivityType
+import com.brickssoft.locationtracking.model.RecordEvent
+
+/**
+ * Decides what an automatic upload pass sends (architecture §2, "Priority records"; round 2 §4, `http.syncInterval`).
+ * Manual `sync()` bypasses it.
+ *
+ * - No `http.url`, or no connectivity: nothing.
+ * - A queued priority record (heartbeat, tracking_start, tracking_stop, providerchange) forces an upload, ignoring
+ *   `autoSync`, `autoSyncThreshold` and `syncInterval`: only priority records on cellular with
+ *   `disableAutoSyncOnCellular`, otherwise the whole queue.
+ * - Otherwise nothing if `autoSync` is off or cellular is restricted. Then, by [IntervalCheck]:
+ *   - [IntervalCheck.OFF] (`syncInterval = 0`, or tracking off): the whole queue once it holds at least
+ *     `autoSyncThreshold` records (0 = every record).
+ *   - `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.
+ */
+internal object SyncPolicy {
+    /** The records an upload pass sends. */
+    enum class Scope {
+        NONE,
+        ALL,
+        PRIORITY_ONLY,
+    }
+
+    /** The state of the `syncInterval` rule for one pass (decided by the syncer). */
+    enum class IntervalCheck {
+        /** The rule does not apply (`syncInterval = 0`, `autoSync` off, or tracking off): threshold rule. */
+        OFF,
+
+        /** The oldest pending normal record is younger than `syncInterval`: only the size cap uploads. */
+        NOT_DUE,
+
+        /** 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()
+
+    /** The events that `autoSync`, `autoSyncThreshold` and `syncInterval` apply to. */
+    val NORMAL_EVENTS: Set<RecordEvent> = RecordEvent.entries.filterNot { it.isPriority }.toSet()
+
+    private const val MS_PER_SECOND = 1_000L
+
+    fun hasUrl(http: HttpConfig): Boolean = !http.url.isNullOrBlank()
+
+    /** True if [connectivity] is cellular and `disableAutoSyncOnCellular` is set. */
+    fun isCellularRestricted(http: HttpConfig, connectivity: Connectivity): Boolean =
+        http.disableAutoSyncOnCellular && connectivity.type == ConnectivityType.CELLULAR
+
+    /** True if normal records follow `syncInterval` (it is above 0 and `autoSync` is on). */
+    fun usesInterval(http: HttpConfig): Boolean = http.autoSync && http.syncInterval > 0
+
+    /** `syncInterval` in milliseconds (the validator keeps it at 0 or above). */
+    fun intervalMs(http: HttpConfig): Long = http.syncInterval * MS_PER_SECOND
+
+    /**
+     * True if the oldest pending normal record, created at [oldestRecordedAt], is due for upload at [now]: its age
+     * is at least `syncInterval`, or negative (the wall clock was set back after it was created).
+     */
+    fun isIntervalDue(http: HttpConfig, oldestRecordedAt: Long, now: Long): Boolean {
+        val age = now - oldestRecordedAt
+        return age < 0 || age >= intervalMs(http)
+    }
+
+    /**
+     * The wall time (epoch ms) at which the oldest pending normal record, created at [oldestRecordedAt], becomes due:
+     * `oldestRecordedAt + syncInterval`; null if it is already due at [now] (see [isIntervalDue]).
+     */
+    fun intervalDueAt(http: HttpConfig, oldestRecordedAt: Long, now: Long): Long? =
+        if (isIntervalDue(http, oldestRecordedAt, now)) null else oldestRecordedAt + intervalMs(http)
+
+    /**
+     * @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.
+     */
+    fun autoScope(
+        http: HttpConfig,
+        connectivity: Connectivity,
+        queued: Int,
+        priorityQueued: Int,
+        interval: IntervalCheck = IntervalCheck.OFF,
+    ): 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
+        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
+    }
+
+    /** Records per request: `maxBatchSize` (at least 1) when `batchSync`, else 1. */
+    fun chunkSize(http: HttpConfig): Int = if (http.batchSync) maxOf(1, http.maxBatchSize) else 1
+}

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

@@ -0,0 +1,143 @@
+package com.brickssoft.locationtracking.http
+
+import com.brickssoft.locationtracking.config.HttpConfig
+import com.brickssoft.locationtracking.core.Iso8601
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.model.JsonUtil
+import com.brickssoft.locationtracking.model.ProviderStateJson
+import com.brickssoft.locationtracking.model.Record
+import com.brickssoft.locationtracking.model.RecordEvent
+import com.brickssoft.locationtracking.model.RecordJson
+import org.json.JSONArray
+import org.json.JSONObject
+import org.json.JSONTokener
+
+/**
+ * Renders `http.locationTemplate` / `http.geofenceTemplate` (architecture §2).
+ *
+ * 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).
+ * 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.
+ */
+internal object TemplateRenderer {
+    private const val TAG = "LT.Template"
+    private const val NULL = "null"
+
+    /** A placeholder, with the quote directly before and after it when present. */
+    private val PLACEHOLDER = Regex("""("?)<%=\s*(.*?)\s*%>("?)""", RegexOption.DOT_MATCHES_ALL)
+
+    /** JSON literal text per placeholder; a resolver returns null for a null value. */
+    private val RESOLVERS: Map<String, (Record, Long) -> String?> = linkedMapOf(
+        "uuid" to { r, _ -> string(r.uuid) },
+        "event" to { r, _ -> string(r.event.wire) },
+        "timestamp" to { r, _ -> r.location?.let { string(Iso8601.format(it.time)) } },
+        "recorded_at" to { r, _ -> string(Iso8601.format(r.recordedAt)) },
+        "sent_at" to { _, sentAt -> string(Iso8601.format(sentAt)) },
+        "latitude" to { r, _ -> number(r.location?.latitude) },
+        "longitude" to { r, _ -> number(r.location?.longitude) },
+        "accuracy" to { r, _ -> number(r.location?.accuracy) },
+        "altitude" to { r, _ -> number(r.location?.altitude) },
+        "altitude_accuracy" to { r, _ -> number(r.location?.altitudeAccuracy) },
+        "speed" to { r, _ -> number(r.location?.speed) },
+        "speed_accuracy" to { r, _ -> number(r.location?.speedAccuracy) },
+        "heading" to { r, _ -> number(r.location?.heading) },
+        "heading_accuracy" to { r, _ -> number(r.location?.headingAccuracy) },
+        "is_moving" to { r, _ -> r.isMoving.toString() },
+        "odometer" to { r, _ -> number(r.odometer) },
+        "mock" to { r, _ -> (r.location?.isMock ?: false).toString() },
+        "activity.type" to { r, _ -> string(r.activity.type.wire) },
+        "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() },
+        "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) } },
+        "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() },
+        "provider.gps" to { r, _ -> r.provider?.gps?.toString() },
+        "provider.network" to { r, _ -> r.provider?.network?.toString() },
+        "provider.permission" to { r, _ -> r.provider?.let { string(it.permission.wire) } },
+        "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() } },
+    )
+
+    /** Every supported placeholder name. */
+    val PLACEHOLDERS: Set<String> get() = RESOLVERS.keys
+
+    /**
+     * The template for [record]: `geofenceTemplate` for geofence records (falling back to `locationTemplate`),
+     * otherwise `locationTemplate`. Blank templates count as absent; null means the default shape.
+     */
+    fun templateFor(record: Record, http: HttpConfig): String? {
+        val location = http.locationTemplate?.takeIf { it.isNotBlank() }
+        if (record.event == RecordEvent.GEOFENCE) return http.geofenceTemplate?.takeIf { it.isNotBlank() } ?: location
+        return location
+    }
+
+    /**
+     * Renders [template] for [record] and parses the result. Returns a [JSONObject] or [JSONArray], or null (and
+     * logs an error) if the rendered text is not a valid JSON object or array; callers then use the default shape.
+     */
+    fun render(template: String, record: Record, sentAt: Long): Any? {
+        val text = renderText(template, record, sentAt)
+        val value = if (StrictJson.isValid(text)) parse(text) else null
+        if (value == null) {
+            Logger.e(
+                TAG,
+                "template for ${record.event.wire} record ${record.uuid} did not render to a JSON object or array; " +
+                    "using the default shape. Template: ${template.take(200)}",
+            )
+        }
+        return value
+    }
+
+    /** Substitutes every placeholder of [template] (no JSON validation). */
+    fun renderText(template: String, record: Record, sentAt: Long): String {
+        val unknown = LinkedHashSet<String>()
+        val text = PLACEHOLDER.replace(template) { match ->
+            val (open, name, close) = match.destructured
+            val resolver = RESOLVERS[name]
+            if (resolver == null) {
+                unknown += name
+                return@replace open + close
+            }
+            val literal = resolver(record, sentAt)
+            when {
+                literal != null -> open + literal + close
+                open.isNotEmpty() && close.isNotEmpty() -> NULL
+                else -> open + NULL + close
+            }
+        }
+        if (unknown.isNotEmpty()) {
+            Logger.w(TAG, "unknown template placeholder(s) ${unknown.joinToString { "'$it'" }} replaced by \"\"")
+        }
+        return text
+    }
+
+    /** The JSON literal for placeholder [name] (`null` for a null value), or null if the name is unknown. */
+    fun literal(name: String, record: Record, sentAt: Long): String? {
+        val resolver = RESOLVERS[name] ?: return null
+        return resolver(record, sentAt) ?: NULL
+    }
+
+    private fun parse(text: String): Any? = try {
+        JSONTokener(text).nextValue().takeIf { it is JSONObject || it is JSONArray }
+    } catch (e: Exception) {
+        // e.g. a number out of range (org.json rejects infinities)
+        null
+    }
+
+    /** JSON string-content escaping, without the surrounding quotes. */
+    private fun string(value: String): String = JSONObject.quote(value).let { it.substring(1, it.length - 1) }
+
+    private fun number(value: Double?): String? = value?.takeIf { !it.isNaN() && !it.isInfinite() }?.toString()
+
+    private fun number(value: Float?): String? = number(value?.let { JsonUtil.floatToJson(it) })
+}