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

package/android/src/main/java/com/brickssoft/locationtracking/api/LocationTrackingNative.kt

@@ -0,0 +1,267 @@
+package com.brickssoft.locationtracking.api
+
+import android.content.Context
+import androidx.annotation.VisibleForTesting
+import com.brickssoft.locationtracking.bridge.BridgeServices
+import com.brickssoft.locationtracking.bridge.ComponentServices
+import com.brickssoft.locationtracking.bridge.PluginHandlers
+import com.brickssoft.locationtracking.bridge.Rejection
+import com.brickssoft.locationtracking.core.Components
+import com.brickssoft.locationtracking.core.ErrorCode
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.core.TrackingException
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.isActive
+import kotlinx.coroutines.launch
+import org.json.JSONArray
+import org.json.JSONObject
+import java.util.concurrent.atomic.AtomicBoolean
+import kotlin.coroutines.cancellation.CancellationException
+
+/**
+ * Public native API for companion plugins and native app code (round 2; guide: `docs/native-api.md`). Each method
+ * mirrors the JS method of the same name: it takes the same JSON shapes, runs the same code as the JS bridge
+ * (`PluginHandlers`, launched on `Components.scope`) and delivers the JS result shape to a [NativeCallback].
+ *
+ * - Every callback is invoked exactly once, on the `LT-native` thread ([THREAD_NAME]), when its call completes. Calls
+ *   run concurrently on the plugin's scope: a call that suspends (for example `start()`) can complete after a later
+ *   call, so callbacks arrive in completion order, not in call order.
+ * - A failure is a `Result.failure` holding a [TrackingException] whose `code` is the JS `ErrorCode` (for example
+ *   `PERMISSION_DENIED`, `INVALID_ARGUMENT`, `NO_URL`); any other exception is wrapped as `INTERNAL` with the original
+ *   exception as its cause.
+ * - Native calls are not subject to the JS bridge's NOT_READY rule and do not set the bridge's ready flag: JS must
+ *   still call `ready()` itself. A native caller that needs a configuration calls [ready] first.
+ * - JSON arguments are copied when the method is called, so the caller may change or reuse its JSONObject afterwards.
+ */
+object LocationTrackingNative {
+    /**
+     * Name (or name prefix, followed by `.`) of the `<meta-data>` that declares a [LocationTrackingListener] class:
+     * `<meta-data android:name="com.brickssoft.locationtracking.LISTENER" android:value="com.example.MyListener"/>`.
+     */
+    const val LISTENER_META_DATA = "com.brickssoft.locationtracking.LISTENER"
+
+    /** Name of the single background thread that runs listeners and callbacks. */
+    const val THREAD_NAME = "LT-native"
+
+    private const val TAG = "LT.Native"
+
+    /**
+     * Subscribes [listener] to every record and event emitted after this call (see [LocationTrackingListener]). The
+     * listener's methods receive the application context of [context]. The subscription is process-wide and does not
+     * create the plugin's components (nothing is emitted before they exist); [NativeSubscription.remove] ends it.
+     */
+    @JvmStatic
+    fun addListener(context: Context, listener: LocationTrackingListener): NativeSubscription =
+        NativeListeners.add(context, listener)
+
+    /** JS `ready({config, reset})`; result: `State` JSON (`ConfigJson.stateToJson`). */
+    @JvmStatic
+    fun ready(context: Context, config: JSONObject?, reset: Boolean, callback: NativeCallback<JSONObject>) {
+        val copy = if (config == null) null else copyOf(config, "ready", callback) ?: return
+        call(context, "ready", callback) {
+            val options = JSONObject().put("reset", reset)
+            if (copy != null) options.put("config", copy)
+            ready(options)
+        }
+    }
+
+    /** JS `setConfig({config})`; result: `State` JSON. */
+    @JvmStatic
+    fun setConfig(context: Context, config: JSONObject, callback: NativeCallback<JSONObject>) {
+        val copy = copyOf(config, "setConfig", callback) ?: return
+        call(context, "setConfig", callback) { setConfig(JSONObject().put("config", copy)) }
+    }
+
+    /** JS `start()`; result: `State` JSON. */
+    @JvmStatic
+    fun start(context: Context, callback: NativeCallback<JSONObject>) {
+        call(context, "start", callback) { start() }
+    }
+
+    /** JS `startGeofences()`; result: `State` JSON. */
+    @JvmStatic
+    fun startGeofences(context: Context, callback: NativeCallback<JSONObject>) {
+        call(context, "startGeofences", callback) { startGeofences() }
+    }
+
+    /** JS `stop()`; result: `State` JSON. */
+    @JvmStatic
+    fun stop(context: Context, callback: NativeCallback<JSONObject>) {
+        call(context, "stop", callback) { stop() }
+    }
+
+    /** JS `changePace({isMoving})`. */
+    @JvmStatic
+    fun changePace(context: Context, isMoving: Boolean, callback: NativeCallback<Unit>) {
+        call(context, "changePace", callback) {
+            changePace(JSONObject().put("isMoving", isMoving))
+            Unit
+        }
+    }
+
+    /** JS `getState()`; result: `State` JSON. */
+    @JvmStatic
+    fun getState(context: Context, callback: NativeCallback<JSONObject>) {
+        call(context, "getState", callback) { getState() }
+    }
+
+    /** JS `getHeartbeatStatus()`; result: `HeartbeatStatus` JSON. */
+    @JvmStatic
+    fun getHeartbeatStatus(context: Context, callback: NativeCallback<JSONObject>) {
+        call(context, "getHeartbeatStatus", callback) { getHeartbeatStatus() }
+    }
+
+    /** JS `sync()`; result: the uploaded records (wire JSON, the JS `locations` array). */
+    @JvmStatic
+    fun sync(context: Context, callback: NativeCallback<JSONArray>) {
+        call(context, "sync", callback) { sync().getJSONArray("locations") }
+    }
+
+    /**
+     * JS `insertLocation({location})` (`InsertLocationInput` JSON); result: the new record's uuid. The record is
+     * queued for upload and delivered to every [LocationTrackingListener.onRecord], like the JS method.
+     */
+    @JvmStatic
+    fun insertLocation(context: Context, location: JSONObject, callback: NativeCallback<String>) {
+        val copy = copyOf(location, "insertLocation", callback) ?: return
+        call(context, "insertLocation", callback) {
+            insertLocation(JSONObject().put("location", copy)).getString("uuid")
+        }
+    }
+
+    /** JS `addGeofence({geofence})` (JS `Geofence` JSON, parsed by `GeofenceJson`). */
+    @JvmStatic
+    fun addGeofence(context: Context, geofence: JSONObject, callback: NativeCallback<Unit>) {
+        val copy = copyOf(geofence, "addGeofence", callback) ?: return
+        call(context, "addGeofence", callback) {
+            addGeofence(JSONObject().put("geofence", copy))
+            Unit
+        }
+    }
+
+    /** JS `removeGeofence({identifier})`. */
+    @JvmStatic
+    fun removeGeofence(context: Context, identifier: String, callback: NativeCallback<Unit>) {
+        call(context, "removeGeofence", callback) {
+            removeGeofence(JSONObject().put("identifier", identifier))
+            Unit
+        }
+    }
+
+    /** JS `getGeofences()`; result: the JS `geofences` array. */
+    @JvmStatic
+    fun getGeofences(context: Context, callback: NativeCallback<JSONArray>) {
+        call(context, "getGeofences", callback) { getGeofences().getJSONArray("geofences") }
+    }
+
+    // ---- plumbing
+
+    /** Test seam: replaces the components the calls run on. */
+    @VisibleForTesting
+    @Volatile
+    internal var backendOverride: ((Context) -> NativeBackend)? = null
+
+    @Volatile
+    private var cached: NativeBackend? = null
+
+    private fun backend(context: Context): NativeBackend {
+        backendOverride?.let { return it(context) }
+        val components = Components.get(context)
+        // Components.get() publishes a new instance before its bootstrap() has run NativeListeners.install, and runs
+        // bootstrap() while it holds the lock of the Components companion object. If another thread is still inside
+        // that bootstrap, taking the same lock once waits until it has finished, so a native call can never emit a
+        // record before the manifest listeners are connected. (Uncontended, the lock costs nothing measurable.)
+        synchronized(Components) { }
+        cached?.takeIf { it.owner === components }?.let { return it }
+        return NativeBackend(ComponentServices(components), components.scope, owner = components).also { cached = it }
+    }
+
+    /**
+     * Runs [block] on the backend's scope and delivers its result, or its failure mapped by [failureOf], to
+     * [callback] on the `LT-native` thread. The callback is invoked exactly once: also when the scope is already
+     * cancelled or is cancelled while the call runs (then the failure is INTERNAL).
+     */
+    private fun <T> call(
+        context: Context,
+        method: String,
+        callback: NativeCallback<T>,
+        block: suspend PluginHandlers.() -> T,
+    ) {
+        val settled = AtomicBoolean(false)
+        val settle = { result: Result<T> -> if (settled.compareAndSet(false, true)) deliver(method, callback, result) }
+        try {
+            val backend = backend(context)
+            backend.scope.launch {
+                val result = try {
+                    Result.success(backend.handlers.block())
+                } catch (t: Throwable) { // also Errors and our own cancellation: the callback must always run
+                    Result.failure(failureOf(method, t, shutDown = t is CancellationException && !isActive))
+                }
+                settle(result)
+            }.invokeOnCompletion { cause ->
+                // Cancelled before the block ran (the scope was already cancelled): nothing settled the call yet.
+                if (cause != null && !settled.get()) settle(Result.failure(failureOf(method, cause, shutDown = true)))
+            }
+        } catch (t: Throwable) {
+            settle(Result.failure(failureOf(method, t, shutDown = false)))
+        }
+    }
+
+    /**
+     * Copies [json] now, so a caller that changes it afterwards does not affect the call. A JSONObject that cannot be
+     * serialized (for example one that contains itself) fails the call with INVALID_ARGUMENT.
+     */
+    private fun <T> copyOf(json: JSONObject, method: String, callback: NativeCallback<T>): JSONObject? = try {
+        JSONObject(json.toString())
+    } catch (t: Throwable) { // also StackOverflowError: never throw to the caller, always invoke the callback
+        Logger.d(TAG, "LocationTrackingNative.$method: the JSON argument cannot be serialized ($t)")
+        deliver(method, callback, Result.failure(TrackingException(ErrorCode.INVALID_ARGUMENT, "invalid JSON argument: $t", t)))
+        null
+    }
+
+    /**
+     * The failure delivered for [t], with the JS bridge's mapping ([Rejection.of]): a [TrackingException] keeps its
+     * code, anything else is INTERNAL. [shutDown] is true when the plugin's own scope was cancelled (the components
+     * were shut down), which gets its own message. Logged like the bridge logs a rejection.
+     */
+    private fun failureOf(method: String, t: Throwable, shutDown: Boolean): TrackingException {
+        val failure = when {
+            t is TrackingException -> t
+            shutDown -> TrackingException(
+                ErrorCode.INTERNAL,
+                "LocationTrackingNative.$method did not complete: the plugin's components were shut down",
+                t,
+            )
+            else -> Rejection.of(t).let { TrackingException(it.code, it.message, t) }
+        }
+        if (failure.code == ErrorCode.INTERNAL) {
+            Logger.e(TAG, "LocationTrackingNative.$method failed", t)
+        } else {
+            Logger.d(TAG, "LocationTrackingNative.$method failed: ${failure.code} ${failure.message}")
+        }
+        return failure
+    }
+
+    private fun <T> deliver(method: String, callback: NativeCallback<T>, result: Result<T>) {
+        NativeThread.post {
+            try {
+                callback.onResult(result)
+            } catch (t: Throwable) {
+                Logger.e(TAG, "the callback of LocationTrackingNative.$method threw", t)
+            }
+        }
+    }
+}
+
+/**
+ * What [LocationTrackingNative] calls run on: the bridge's handlers over [services] with their own ready flag (always
+ * true, so the NOT_READY rule does not apply and the JS bridge's flag is never set), launched on [scope]. [owner] is
+ * the [Components] instance the backend was built from (the facade builds a new backend after a reset).
+ */
+internal class NativeBackend(
+    services: BridgeServices,
+    val scope: CoroutineScope,
+    val owner: Any? = null,
+) {
+    val handlers = PluginHandlers(services, readyFlag = AtomicBoolean(true))
+}

package/android/src/main/java/com/brickssoft/locationtracking/api/NativeListeners.kt

@@ -0,0 +1,270 @@
+package com.brickssoft.locationtracking.api
+
+import android.content.Context
+import android.content.pm.ApplicationInfo
+import android.content.pm.PackageManager
+import android.os.Build
+import android.os.Bundle
+import androidx.annotation.VisibleForTesting
+import com.brickssoft.locationtracking.core.Components
+import com.brickssoft.locationtracking.core.EventBus
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.core.RecordHooks
+import com.brickssoft.locationtracking.core.Subscription
+import com.brickssoft.locationtracking.core.TrackingEvent
+import com.brickssoft.locationtracking.model.EventJson
+import com.brickssoft.locationtracking.model.Record
+import com.brickssoft.locationtracking.model.RecordJson
+import org.json.JSONObject
+import java.util.concurrent.CopyOnWriteArrayList
+
+/**
+ * Installs the manifest-declared [LocationTrackingListener]s and connects every listener (manifest and programmatic)
+ * to the plugin: `components.recordHooks` for records, `components.events` for events. Delivery runs on the
+ * `LT-native` thread ([NativeThread]).
+ *
+ * How a record or an event reaches a listener:
+ * 1. [RecordHooks.dispatch] or [EventBus.emit] calls this object synchronously on the emitting thread (the engine,
+ *    a receiver, an I/O coroutine).
+ * 2. This object takes a snapshot of the registered listeners (if there is any) and queues one task on the `LT-native`
+ *    thread. It does not build any JSON on the emitting thread, so the engine is never slowed down by a listener.
+ * 3. The task builds the JSON once (`RecordJson.toJson(record)` without `sent_at`, or `EventJson.name/payload`), gives
+ *    each listener its own JSONObject (a listener that changes its object does not change what the next listener
+ *    receives) and calls each listener that is still subscribed. A listener that throws is logged; the other
+ *    listeners still run.
+ *
+ * Programmatic listeners are process-wide: they stay registered when a new [Components] instance is installed (only
+ * tests create more than one). Manifest listeners are created again by every [install].
+ */
+internal object NativeListeners {
+    private const val TAG = "LT.Native"
+
+    /** One registered listener. [active] turns false when it is removed; queued deliveries then skip it. */
+    private class Entry(
+        val listener: LocationTrackingListener,
+        val context: Context,
+        val label: String,
+    ) {
+        @Volatile
+        var active = true
+    }
+
+    private val lock = Any()
+
+    /** Every listener, manifest listeners first (in manifest order), then programmatic ones in subscription order. */
+    private val entries = CopyOnWriteArrayList<Entry>()
+
+    /** The manifest listeners of the current installation. Guarded by [lock]. */
+    private var manifestEntries: List<Entry> = emptyList()
+
+    /** The record hook and event bus subscriptions of the current installation. Guarded by [lock]. */
+    private var connection: List<Subscription> = emptyList()
+
+    /**
+     * Called once per [Components] instance from `Components.bootstrap()`: reads the manifest meta-data, creates the
+     * listener classes and subscribes to the instance's record hooks and event bus, replacing the subscriptions and
+     * the manifest listeners of a previous instance. A failure while reading or creating manifest listeners is logged
+     * and never prevents the subscriptions.
+     */
+    fun install(context: Context, components: Components) {
+        val appContext = context.applicationContext ?: context
+        val manifest = try {
+            createManifestListeners(appContext)
+        } catch (e: Exception) {
+            Logger.e(TAG, "cannot read the listener meta-data; no manifest listener is installed", e)
+            emptyList()
+        }
+        connect(appContext, components.recordHooks, components.events, manifest)
+    }
+
+    /**
+     * Subscribes to [hooks] and [events] and makes [manifest] the manifest listeners (called with [context]).
+     * Cancels the subscriptions of the previous call and deactivates its manifest listeners.
+     * [install] uses it; tests call it directly with the full-stack harness or fakes.
+     */
+    fun connect(
+        context: Context,
+        hooks: RecordHooks,
+        events: EventBus,
+        manifest: List<Pair<String, LocationTrackingListener>>,
+    ) {
+        val appContext = context.applicationContext ?: context
+        synchronized(lock) {
+            connection.forEach { it.cancel() }
+            for (entry in manifestEntries) {
+                entry.active = false
+                entries.remove(entry)
+            }
+            val created = manifest.map { (key, listener) ->
+                Entry(listener, appContext, "manifest listener ${listener.javaClass.name} ($key)")
+            }
+            entries.addAll(0, created)
+            manifestEntries = created
+            connection = listOf(
+                hooks.add { record -> onRecordQueued(record) },
+                events.subscribe { event -> onEvent(event) },
+            )
+        }
+        if (manifest.isNotEmpty()) {
+            Logger.i(TAG, "installed ${manifest.size} manifest listener(s): ${manifest.joinToString { it.second.javaClass.name }}")
+        }
+    }
+
+    /** Programmatic subscription ([LocationTrackingNative.addListener]). */
+    fun add(context: Context, listener: LocationTrackingListener): NativeSubscription {
+        val entry = Entry(listener, context.applicationContext ?: context, "listener ${listener.javaClass.name}")
+        entries.add(entry)
+        return NativeSubscription {
+            entry.active = false
+            entries.remove(entry)
+        }
+    }
+
+    // ---- delivery
+
+    private fun onRecordQueued(record: Record) {
+        if (entries.isEmpty()) return
+        // The iterator of a CopyOnWriteArrayList is a snapshot of the listeners registered now; taking it copies nothing.
+        val targets = entries.iterator()
+        deliver({ "record ${record.event.wire} ${record.uuid}" }, targets, { RecordJson.toJson(record) }) { entry, json ->
+            entry.listener.onRecord(entry.context, json)
+        }
+    }
+
+    private fun onEvent(event: TrackingEvent) {
+        if (entries.isEmpty()) return
+        val targets = entries.iterator()
+        deliver({ "event ${event::class.simpleName}" }, targets, { EventJson.payload(event) }) { entry, json ->
+            entry.listener.onEvent(entry.context, EventJson.name(event), json)
+        }
+    }
+
+    /**
+     * Queues one task on the `LT-native` thread that builds the JSON once and calls [call] for every listener of
+     * [targets] that is still subscribed. Each listener gets its own JSONObject: the first one the built object, the
+     * others a copy parsed from its text (made before any listener runs).
+     *
+     * Every [Throwable] is caught, also an Error such as NoClassDefFoundError or StackOverflowError: an exception that
+     * escapes the `LT-native` thread would crash the process, and with it the tracking service.
+     */
+    private fun deliver(
+        what: () -> String,
+        targets: Iterator<Entry>,
+        build: () -> JSONObject,
+        call: (Entry, JSONObject) -> Unit,
+    ) {
+        NativeThread.post {
+            try {
+                val active = targets.asSequence().filter { it.active }.toList()
+                if (active.isEmpty()) return@post
+                val json = build()
+                val text = if (active.size > 1) json.toString() else null
+                for ((index, entry) in active.withIndex()) {
+                    if (!entry.active) continue // removed while an earlier listener ran
+                    try {
+                        call(entry, if (index == 0) json else JSONObject(text!!))
+                    } catch (t: Throwable) {
+                        Logger.e(TAG, "${entry.label} threw while receiving ${what()}", t)
+                    }
+                }
+            } catch (t: Throwable) {
+                Logger.e(TAG, "cannot deliver ${what()} to the native listeners", t)
+            }
+        }
+    }
+
+    // ---- manifest
+
+    /**
+     * The listener class names declared in the manifest, as (meta-data name, class name) pairs: the entry named
+     * [LocationTrackingNative.LISTENER_META_DATA] first, then the entries whose name starts with it followed by `.`,
+     * sorted by name. A class named twice is returned once (the first occurrence).
+     */
+    fun declaredListenerClasses(context: Context): List<Pair<String, String>> {
+        val metaData = applicationInfo(context).metaData ?: return emptyList()
+        val base = LocationTrackingNative.LISTENER_META_DATA
+        val keys = metaData.keySet()
+            .filter { it == base || it.startsWith("$base.") }
+            .sortedWith(compareBy<String>({ it != base }, { it }))
+        val seen = HashSet<String>()
+        val result = ArrayList<Pair<String, String>>()
+        for (key in keys) {
+            val className = classNameOf(metaData, key)
+            if (className == null) {
+                Logger.e(TAG, "meta-data $key must be a class name (android:value=\"com.example.MyListener\")")
+                continue
+            }
+            if (seen.add(className)) {
+                result += key to className
+            } else {
+                Logger.w(TAG, "meta-data $key names $className again; it is created once")
+            }
+        }
+        return result
+    }
+
+    /**
+     * Creates one instance of each declared listener class with its public no-arg constructor. A class that cannot
+     * be loaded or created, or that does not implement [LocationTrackingListener], is logged with its [Throwable]
+     * and skipped.
+     */
+    fun createManifestListeners(context: Context): List<Pair<String, LocationTrackingListener>> =
+        declaredListenerClasses(context).mapNotNull { (key, className) -> instantiate(context, key, className) }
+
+    private fun instantiate(context: Context, key: String, className: String): Pair<String, LocationTrackingListener>? =
+        try {
+            val type = Class.forName(className, true, context.classLoader)
+            if (!LocationTrackingListener::class.java.isAssignableFrom(type)) {
+                Logger.e(TAG, "$className ($key) does not implement ${LocationTrackingListener::class.java.name}; skipped")
+                null
+            } else {
+                key to (type.getConstructor().newInstance() as LocationTrackingListener)
+            }
+        } catch (e: Exception) {
+            // ClassNotFoundException, NoSuchMethodException (no public no-arg constructor), InstantiationException,
+            // IllegalAccessException, InvocationTargetException (the constructor threw).
+            Logger.e(TAG, "cannot create the listener $className ($key); skipped", e)
+            null
+        } catch (e: LinkageError) {
+            // NoClassDefFoundError (a missing dependency), ExceptionInInitializerError (a static initializer threw).
+            Logger.e(TAG, "cannot load the listener $className ($key); skipped", e)
+            null
+        }
+
+    private fun classNameOf(metaData: Bundle, key: String): String? {
+        @Suppress("DEPRECATION") // Bundle.get(String): the value type is not known in advance.
+        val value = metaData.get(key)
+        return (value as? String)?.trim()?.takeIf { it.isNotEmpty() }
+    }
+
+    private fun applicationInfo(context: Context): ApplicationInfo {
+        val pm = context.packageManager
+        return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            pm.getApplicationInfo(
+                context.packageName,
+                PackageManager.ApplicationInfoFlags.of(PackageManager.GET_META_DATA.toLong()),
+            )
+        } else {
+            @Suppress("DEPRECATION")
+            pm.getApplicationInfo(context.packageName, PackageManager.GET_META_DATA)
+        }
+    }
+
+    // ---- tests
+
+    /** Test hook: cancels the subscriptions and forgets every listener (manifest and programmatic). */
+    @VisibleForTesting
+    fun resetForTests() {
+        synchronized(lock) {
+            connection.forEach { it.cancel() }
+            connection = emptyList()
+            manifestEntries = emptyList()
+            entries.forEach { it.active = false }
+            entries.clear()
+        }
+    }
+
+    /** Test hook: the number of registered listeners (manifest and programmatic). */
+    @VisibleForTesting
+    val listenerCount: Int get() = entries.size
+}

package/android/src/main/java/com/brickssoft/locationtracking/api/NativeThread.kt

@@ -0,0 +1,57 @@
+package com.brickssoft.locationtracking.api
+
+import androidx.annotation.VisibleForTesting
+import com.brickssoft.locationtracking.core.Logger
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.LinkedBlockingQueue
+import java.util.concurrent.RejectedExecutionException
+import java.util.concurrent.ThreadPoolExecutor
+import java.util.concurrent.TimeUnit
+
+/**
+ * The one background thread of the companion native API, named [LocationTrackingNative.THREAD_NAME] (`LT-native`).
+ *
+ * Every [LocationTrackingListener] call and every [NativeCallback] runs here, one task at a time, in the order the
+ * tasks were posted. Because there is only one thread for all listeners and all callbacks, the order is global: a
+ * record posted before an event is delivered before that event, to every listener.
+ *
+ * The thread is a daemon thread (it never keeps the JVM alive) and exists for the whole process once created. The
+ * queue has no size limit, so nothing is dropped; a listener that blocks this thread delays every later delivery.
+ */
+internal object NativeThread {
+    private const val TAG = "LT.Native"
+
+    private val executor = ThreadPoolExecutor(1, 1, 0L, TimeUnit.MILLISECONDS, LinkedBlockingQueue()) { runnable ->
+        Thread(runnable, LocationTrackingNative.THREAD_NAME).apply { isDaemon = true }
+    }
+
+    /** Queue length at which (and at every further multiple of which) a backlog warning is logged. */
+    const val BACKLOG_WARNING = 1_000
+
+    /** Queues [task] for the `LT-native` thread. [task] must catch its own exceptions. */
+    fun post(task: Runnable) {
+        try {
+            executor.execute(task)
+        } catch (e: RejectedExecutionException) {
+            // Only possible if the executor was shut down, which this object never does.
+            Logger.e(TAG, "the ${LocationTrackingNative.THREAD_NAME} executor rejected a task", e)
+            return
+        }
+        val queued = executor.queue.size
+        if (queued >= BACKLOG_WARNING && queued % BACKLOG_WARNING == 0) {
+            // Nothing is dropped; this only makes a blocked listener or callback visible in the log.
+            Logger.w(TAG, "$queued tasks wait for the ${LocationTrackingNative.THREAD_NAME} thread: a native listener or callback is blocking it")
+        }
+    }
+
+    /**
+     * Test hook: waits until every task queued before this call has run. Returns false on timeout. Must not be
+     * called from the `LT-native` thread itself (it would wait for itself).
+     */
+    @VisibleForTesting
+    fun awaitIdle(timeoutMs: Long = 15_000L): Boolean {
+        val done = CountDownLatch(1)
+        post { done.countDown() }
+        return done.await(timeoutMs, TimeUnit.MILLISECONDS)
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/bridge/BridgeServices.kt

@@ -0,0 +1,64 @@
+package com.brickssoft.locationtracking.bridge
+
+import com.brickssoft.locationtracking.config.ConfigStore
+import com.brickssoft.locationtracking.core.AppDispatchers
+import com.brickssoft.locationtracking.core.Components
+import com.brickssoft.locationtracking.core.EventBus
+import com.brickssoft.locationtracking.core.RecordHooks
+import com.brickssoft.locationtracking.data.LocationStore
+import com.brickssoft.locationtracking.device.DeviceInfoProvider
+import com.brickssoft.locationtracking.device.DeviceMonitor
+import com.brickssoft.locationtracking.engine.TrackingEngine
+import com.brickssoft.locationtracking.geofence.GeofenceManager
+import com.brickssoft.locationtracking.heartbeat.HeartbeatScheduler
+import com.brickssoft.locationtracking.http.HttpSyncer
+import com.brickssoft.locationtracking.logging.LogStore
+import com.brickssoft.locationtracking.permission.PermissionManager
+import com.brickssoft.locationtracking.position.PositionService
+import com.brickssoft.locationtracking.processing.Odometer
+import com.brickssoft.locationtracking.processing.RecordFactory
+import com.brickssoft.locationtracking.settings.DeviceSettings
+
+/** The components [PluginHandlers] delegates to. Tests implement it with the scaffold fakes. */
+internal interface BridgeServices {
+    val engine: TrackingEngine
+    val positions: PositionService
+    val locationStore: LocationStore
+    val recordFactory: RecordFactory
+    val syncer: HttpSyncer
+    val geofences: GeofenceManager
+    val heartbeat: HeartbeatScheduler
+    val device: DeviceMonitor
+    val deviceInfo: DeviceInfoProvider
+    val deviceSettings: DeviceSettings
+    val permissions: PermissionManager
+    val logStore: LogStore
+    val odometer: Odometer
+    val configStore: ConfigStore
+    val events: EventBus
+    val dispatchers: AppDispatchers
+
+    /** Round 2: `insertLocation` dispatches its record here (unit 5). */
+    val recordHooks: RecordHooks
+}
+
+/** [BridgeServices] backed by [Components]; each component is resolved (and created) on first use only. */
+internal class ComponentServices(private val components: Components) : BridgeServices {
+    override val engine: TrackingEngine get() = components.engine
+    override val positions: PositionService get() = components.positions
+    override val locationStore: LocationStore get() = components.locationStore
+    override val recordFactory: RecordFactory get() = components.recordFactory
+    override val syncer: HttpSyncer get() = components.syncer
+    override val geofences: GeofenceManager get() = components.geofences
+    override val heartbeat: HeartbeatScheduler get() = components.heartbeat
+    override val device: DeviceMonitor get() = components.device
+    override val deviceInfo: DeviceInfoProvider get() = components.deviceInfo
+    override val deviceSettings: DeviceSettings get() = components.deviceSettings
+    override val permissions: PermissionManager get() = components.permissions
+    override val logStore: LogStore get() = components.logStore
+    override val odometer: Odometer get() = components.odometer
+    override val configStore: ConfigStore get() = components.configStore
+    override val events: EventBus get() = components.events
+    override val dispatchers: AppDispatchers get() = components.dispatchers
+    override val recordHooks: RecordHooks get() = components.recordHooks
+}