@voltkit-rtc/react-native 0.0.0-stage → 0.1.1

package/android/src/main/java/com/voltkit/rtc/reactnative/NativeTimers.kt

@@ -0,0 +1,106 @@
+package com.voltkit.rtc.reactnative
+
+import android.os.Handler
+import android.os.HandlerThread
+
+/**
+ * Timers for the client's own work -- reconnect backoff, socket liveness, request deadlines, sampling -- that keep
+ * running in the background and with the screen off (plan §2, PLAN_UPDATES 3). React Native's JavaScript timers run
+ * on Choreographer frames, which stop at onHostPause and with the screen off even while the app is in front (Phase 0
+ * S5). These wait on their own thread and tell JavaScript through the module's onTimer event.
+ *
+ * A fire can be on its way when JavaScript stops a timer, so JavaScript ignores a fire for an id it no longer has, and
+ * never reuses an id. Here, a timer stopped or replaced before its fire ran never fires.
+ */
+internal class NativeTimers(
+    private val scheduler: Scheduler,
+    private val fire: (id: Double) -> Unit,
+) {
+    /** Where timers wait: a Handler thread in the app ([HandlerScheduler]), a virtual clock in tests. */
+    interface Scheduler {
+        /** Run [task] after [delayMillis]; returns how to cancel it. */
+        fun schedule(delayMillis: Long, task: Runnable): Cancel
+    }
+
+    fun interface Cancel {
+        fun cancel()
+    }
+
+    private class Entry(val id: Double, val delayMillis: Long, val repeat: Boolean) {
+        var cancel: Cancel? = null
+    }
+
+    private val lock = Any()
+    private val live = HashMap<Double, Entry>()
+
+    /** How many timers are live. */
+    val size: Int
+        get() = synchronized(lock) { live.size }
+
+    /** Fire [id] after [ms], and every [ms] after that when [repeat]. A live [id] is replaced. */
+    fun start(id: Double, ms: Double, repeat: Boolean) {
+        val entry = Entry(id, delayOf(ms, repeat), repeat)
+        synchronized(lock) {
+            live.remove(id)?.cancel?.cancel()
+            live[id] = entry
+            entry.cancel = scheduler.schedule(entry.delayMillis) { tick(entry) }
+        }
+    }
+
+    fun stop(id: Double) {
+        synchronized(lock) { live.remove(id) }?.cancel?.cancel()
+    }
+
+    /** Every timer ends (the React instance went away). */
+    fun stopAll() {
+        val all = synchronized(lock) { live.values.toList().also { live.clear() } }
+        all.forEach { it.cancel?.cancel() }
+    }
+
+    private fun tick(entry: Entry) {
+        synchronized(lock) {
+            // Stopped or replaced while this fire was on its way.
+            if (live[entry.id] !== entry) return
+            if (entry.repeat) {
+                entry.cancel = scheduler.schedule(entry.delayMillis) { tick(entry) }
+            } else {
+                live.remove(entry.id)
+            }
+        }
+        fire(entry.id)
+    }
+
+    companion object {
+        /** An interval of 0 would spin: held to the 4 ms browsers clamp nested timers to. */
+        const val MIN_INTERVAL_MILLIS = 4L
+
+        /** The longest wait: Handler adds the delay to the uptime clock, and a larger one would wrap around. */
+        const val MAX_DELAY_MILLIS = Int.MAX_VALUE.toLong()
+
+        /** Negative and NaN fire at once (as in browsers); infinite and huge wait the longest; fractions round down. */
+        fun delayOf(ms: Double, repeat: Boolean): Long {
+            val millis = when {
+                ms.isNaN() || ms <= 0.0 -> 0L
+                ms >= MAX_DELAY_MILLIS.toDouble() -> MAX_DELAY_MILLIS
+                else -> ms.toLong()
+            }
+            return if (repeat) maxOf(millis, MIN_INTERVAL_MILLIS) else millis
+        }
+    }
+}
+
+/** The app's [NativeTimers.Scheduler]: a thread of its own, so a busy main or JavaScript thread does not delay fires. */
+internal class HandlerScheduler(name: String) : NativeTimers.Scheduler {
+    private val thread = HandlerThread(name).apply { start() }
+    private val handler = Handler(thread.looper)
+
+    override fun schedule(delayMillis: Long, task: Runnable): NativeTimers.Cancel {
+        handler.postDelayed(task, delayMillis)
+        return NativeTimers.Cancel { handler.removeCallbacks(task) }
+    }
+
+    fun quit() {
+        handler.removeCallbacksAndMessages(null)
+        thread.quitSafely()
+    }
+}

package/android/src/main/java/com/voltkit/rtc/reactnative/NetworkWatch.kt

@@ -0,0 +1,120 @@
+package com.voltkit.rtc.reactnative
+
+import android.content.Context
+import android.net.ConnectivityManager
+import android.net.Network
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+
+/**
+ * The network coming back, for the client's `onOnline` hook (a browser's `online` event): a reconnect waiting out its
+ * backoff tries at once, and the socket is checked. Told when the default network returns after there was none
+ * (`handover` false), and when it changes to another one, say Wi-Fi to mobile data (`handover` true), since the old
+ * network's sockets are then on their way out. Needs ACCESS_NETWORK_STATE, which the library's manifest declares.
+ *
+ * Not told at once: Android hands the default callback's onAvailable out before it has switched the app's routes to
+ * that network (on the API 37 emulator "Switching to new default network" followed it by 40 to 80 ms, and a connect
+ * made at once failed in 7 ms: Phase 3, C11). The news waits [NetworkWatchLogic.GRACE_MILLIS] and goes out only if the
+ * network is still the default then; a newer network's own onAvailable covers the case where it is not.
+ */
+internal class NetworkWatch(context: Context, onAvailable: (handover: Boolean) -> Unit) {
+    private val cm = context.applicationContext.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager?
+    private val main = Handler(Looper.getMainLooper())
+    private val lock = Any()
+    private var registered = false
+    private val logic = NetworkWatchLogic<Network>(
+        schedule = { delayMillis, task -> main.postDelayed(task, delayMillis) },
+        // Still the app's default network when the grace ends; when that cannot be read, taken as yes.
+        isDefault = { network -> runCatching { cm?.activeNetwork == network }.getOrDefault(true) },
+        tell = onAvailable,
+    )
+
+    private val callback = object : ConnectivityManager.NetworkCallback() {
+        override fun onAvailable(network: Network) = logic.available(network)
+
+        override fun onLost(network: Network) = logic.lost(network)
+    }
+
+    fun start() {
+        val manager = cm ?: return
+        synchronized(lock) {
+            if (registered) return
+            registered = true
+        }
+        logic.reset(runCatching { manager.activeNetwork }.getOrNull())
+        try {
+            manager.registerDefaultNetworkCallback(callback)
+        } catch (t: Throwable) {
+            Log.w(TAG, "could not watch the network: ${t.message}")
+            synchronized(lock) { registered = false }
+        }
+    }
+
+    fun stop() {
+        val manager = cm ?: return
+        synchronized(lock) {
+            if (!registered) return
+            registered = false
+        }
+        runCatching { manager.unregisterNetworkCallback(callback) }
+    }
+
+    private companion object {
+        const val TAG = "VoltKitRtc"
+    }
+}
+
+/**
+ * The decision behind [NetworkWatch], without Android: which onAvailable is news (the first network after none, or a
+ * handover), and when it may be told (after [GRACE_MILLIS], if the network is still the default and nothing newer
+ * came). [N] is the network's type: android.net.Network in the app, anything in a test.
+ */
+internal class NetworkWatchLogic<N : Any>(
+    private val schedule: (delayMillis: Long, task: () -> Unit) -> Unit,
+    private val isDefault: (N) -> Boolean,
+    private val tell: (handover: Boolean) -> Unit,
+) {
+    private val lock = Any()
+    private var current: N? = null
+    /** Bumped by every change: a grace that ends after a later change says nothing. */
+    private var generation = 0L
+
+    /** The default network at the start (registration replays it, which is not news). */
+    fun reset(active: N?) {
+        synchronized(lock) {
+            current = active
+            generation += 1
+        }
+    }
+
+    fun available(network: N) {
+        val handover: Boolean
+        val gen: Long
+        synchronized(lock) {
+            val was = current
+            if (was == network) return
+            current = network
+            handover = was != null
+            generation += 1
+            gen = generation
+        }
+        schedule(GRACE_MILLIS) {
+            val still = synchronized(lock) { generation == gen && current == network }
+            if (still && isDefault(network)) runCatching { tell(handover) }
+        }
+    }
+
+    fun lost(network: N) {
+        synchronized(lock) {
+            if (current != network) return
+            current = null
+            generation += 1
+        }
+    }
+
+    companion object {
+        /** How long after onAvailable the routes are trusted to have followed (observed 40 to 80 ms; a wide margin). */
+        const val GRACE_MILLIS = 500L
+    }
+}

package/android/src/main/java/com/voltkit/rtc/reactnative/OutputChoice.kt

@@ -0,0 +1,65 @@
+package com.voltkit.rtc.reactnative
+
+/**
+ * Where call audio should play: the output picked by hand, the loudspeaker or earpiece preference, and the Bluetooth
+ * headsets that refused call audio. Decisions only, so they can be tested off a device; [AudioRouter] keeps one and
+ * touches it on its own thread. Ported unchanged from the Android SDK (android-sdk/.../OutputChoice.kt).
+ */
+internal class OutputChoice {
+    /** Loudspeaker (true) or earpiece (false) when no headset is connected. */
+    var speakerPreferred: Boolean = true
+
+    /** The output picked by hand ([AudioRouter.selectOutput]), while it stays connected. */
+    var picked: String? = null
+        private set
+
+    /**
+     * Every headset that refused call audio, skipped until it is picked again, a device is added, or the call ends.
+     * Every one, not the last: with one remembered, two refusing headsets were switched between forever (K096-1).
+     */
+    private val refused = HashSet<String>()
+
+    /** Picked by hand: it wins while it stays connected, and a headset that refused is tried again. */
+    fun pick(deviceId: String) {
+        picked = deviceId
+        refused.remove(deviceId)
+    }
+
+    /** The preference changed: a built-in output picked by hand gives way to it; a headset picked by hand stays. */
+    fun preferSpeaker(on: Boolean) {
+        speakerPreferred = on
+        if (picked == AudioRouter.SPEAKER || picked == AudioRouter.EARPIECE) picked = null
+    }
+
+    /** The headset [deviceId] refused call audio: route elsewhere. */
+    fun refusedBy(deviceId: String?) {
+        deviceId?.let { refused.add(it) }
+    }
+
+    /** A device was added: every headset gets another try. */
+    fun devicesAdded() {
+        refused.clear()
+    }
+
+    /** The call audio was let go: nothing picked, nothing refused. */
+    fun reset() {
+        picked = null
+        refused.clear()
+    }
+
+    /** The outputs now: a pick no longer among them is forgotten. */
+    fun outputsNow(outputs: List<MediaDevice>) {
+        if (picked != null && outputs.none { it.deviceId == picked }) picked = null
+    }
+
+    fun choose(outputs: List<MediaDevice>): MediaDevice? {
+        // A pick that refused is passed over: picked first regardless, it was started again every 3 seconds, and call
+        // audio had no working output (K096-1).
+        picked?.takeIf { it !in refused }?.let { id -> outputs.firstOrNull { it.deviceId == id }?.let { return it } }
+        outputs.firstOrNull { it.type == AudioDeviceType.bluetooth && it.deviceId !in refused }?.let { return it }
+        outputs.firstOrNull { it.type == AudioDeviceType.wiredHeadset || it.type == AudioDeviceType.usb }?.let { return it }
+        val speaker = outputs.firstOrNull { it.type == AudioDeviceType.speaker }
+        val earpiece = outputs.firstOrNull { it.type == AudioDeviceType.earpiece }
+        return if (speakerPreferred) speaker ?: earpiece else earpiece ?: speaker
+    }
+}

package/android/src/main/java/com/voltkit/rtc/reactnative/RtcConfig.kt

@@ -0,0 +1,83 @@
+package com.voltkit.rtc.reactnative
+
+/**
+ * How this process plays call audio, chosen once in the app's manifest (meta-data in.voltkit.rtc.AUDIO_MODE) and
+ * fixed for the life of the audio engine, as the Android SDK's `RtcOptions.audioMode`.
+ */
+@Suppress("EnumEntryName")
+internal enum class AudioMode {
+    /**
+     * A call: echo cancellation, the call volume, Bluetooth headsets as two-way headsets, and the earpiece or
+     * loudspeaker by choice. For anyone who speaks -- calls and audio rooms, listeners included, since a listener
+     * brought on stage must not echo.
+     */
+    communication,
+
+    /**
+     * Media playback, for an app whose users only ever listen: the media volume, Bluetooth headphones in their
+     * high-quality mode, no earpiece. Not for anyone who may speak.
+     */
+    media,
+}
+
+/**
+ * The process-wide settings the init provider reads from the app's manifest before react-native-webrtc starts
+ * (plan §5.3), as the Expo config plugin writes them or a hand-written manifest gives them:
+ *
+ *     <meta-data android:name="in.voltkit.rtc.AUDIO_MODE" android:value="communication" />  communication | media
+ *     <meta-data android:name="in.voltkit.rtc.HW_AEC" android:value="true" />               the handset's own echo
+ *                                                                                            canceller and noise suppressor
+ *     <meta-data android:name="in.voltkit.rtc.SCREEN_SHARE" android:value="false" />        react-native-webrtc's
+ *                                                                                            screen-share service
+ *
+ * Parsing only, so it can be tested off a device. A value that cannot be read keeps its default and is reported.
+ */
+internal data class RtcConfig(
+    val audioMode: AudioMode = AudioMode.communication,
+    val hardwareEchoCancellation: Boolean = true,
+    val screenShare: Boolean = false,
+    /** What could not be read, with the default used instead; the init provider logs it. */
+    val problems: List<String> = emptyList(),
+) {
+    companion object {
+        const val AUDIO_MODE = "in.voltkit.rtc.AUDIO_MODE"
+        const val HW_AEC = "in.voltkit.rtc.HW_AEC"
+        const val SCREEN_SHARE = "in.voltkit.rtc.SCREEN_SHARE"
+
+        /** From the application's meta-data: [meta] gives one key's value (a Bundle's `get`), or null. */
+        fun from(meta: (String) -> Any?): RtcConfig {
+            val problems = ArrayList<String>()
+            val mode = when (val raw = meta(AUDIO_MODE)) {
+                null -> AudioMode.communication
+                is String -> AudioMode.values().firstOrNull { it.name == raw.trim().lowercase() }
+                    ?: AudioMode.communication.also { problems += "$AUDIO_MODE: '$raw' is not communication or media; using communication" }
+                else -> AudioMode.communication.also { problems += "$AUDIO_MODE: '$raw' is not communication or media; using communication" }
+            }
+            return RtcConfig(
+                audioMode = mode,
+                hardwareEchoCancellation = flag(meta(HW_AEC), HW_AEC, default = true, problems),
+                screenShare = flag(meta(SCREEN_SHARE), SCREEN_SHARE, default = false, problems),
+                problems = problems,
+            )
+        }
+
+        private fun flag(raw: Any?, key: String, default: Boolean, problems: MutableList<String>): Boolean {
+            val value = when (raw) {
+                null -> return default
+                is Boolean -> raw
+                is String -> when (raw.trim().lowercase()) {
+                    "true" -> true
+                    "false" -> false
+                    else -> null
+                }
+                is Number -> when (raw.toInt()) {
+                    1 -> true
+                    0 -> false
+                    else -> null
+                }
+                else -> null
+            }
+            return value ?: default.also { problems += "$key: '$raw' is not true or false; using $default" }
+        }
+    }
+}

package/android/src/main/java/com/voltkit/rtc/reactnative/ScoLink.kt

@@ -0,0 +1,61 @@
+package com.voltkit.rtc.reactnative
+
+/**
+ * What the Bluetooth call link's state broadcasts mean (API 23 to 30, where call audio reaches a headset through
+ * `startBluetoothSco`). Decisions only, so they can be tested off a device; [AudioRouter] acts on them. Ported
+ * unchanged from the Android SDK (android-sdk/.../ScoLink.kt).
+ *
+ * The broadcast also reports the link stopped before: switching from Bluetooth to the speaker and back quickly, that
+ * link's DISCONNECTED arrived after the new start and was taken for the new link's refusal, and the headset was routed
+ * away until devices changed (SR-1). So after a start, DISCONNECTED says nothing until the link has said CONNECTING or
+ * CONNECTED. A refusal can say DISCONNECTED and nothing else: a start that hears nothing of its link within
+ * [START_TIMEOUT_MILLIS] failed too ([silent]). ERROR is always a failure.
+ */
+internal class ScoLink {
+    /** The call link is asked for: started and not stopped since. */
+    var wanted: Boolean = false
+        private set
+
+    /** Starts so far; [silent] checks the one it was given. */
+    private var starts = 0
+
+    /** Since the last start, the link said CONNECTING or CONNECTED: a DISCONNECTED is about this link. */
+    private var heard = false
+
+    /** Asked for; returns this start's number, for [silent]. */
+    fun start(): Int {
+        wanted = true
+        heard = false
+        return ++starts
+    }
+
+    fun stop() {
+        wanted = false
+        heard = false
+    }
+
+    /** One state broadcast: true when the link asked for failed. */
+    fun failed(state: Int): Boolean {
+        if (!wanted) return false
+        return when (state) {
+            CONNECTING, CONNECTED -> {
+                heard = true
+                false
+            }
+            DISCONNECTED -> heard
+            else -> true
+        }
+    }
+
+    /** [START_TIMEOUT_MILLIS] after start [start]: still asked for, and nothing heard of the link. */
+    fun silent(start: Int): Boolean = wanted && start == starts && !heard
+
+    companion object {
+        // AudioManager.SCO_AUDIO_STATE_*, as the broadcast carries them.
+        const val ERROR = -1
+        const val DISCONNECTED = 0
+        const val CONNECTED = 1
+        const val CONNECTING = 2
+        const val START_TIMEOUT_MILLIS = 3_000L
+    }
+}