@tryterra/react-native 0.0.0-stage → 2.1.0

package/android/src/bridgeCore/kotlin/co/tryterra/sdk/bridge/StreamRegistry.kt

@@ -0,0 +1,77 @@
+package co.tryterra.sdk.bridge
+
+import java.util.concurrent.atomic.AtomicLong
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.CoroutineStart
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.launch
+
+/**
+ * One native stream per subscriber, started on subscribe and cancelled on unsubscribe.
+ *
+ * Sharing one collection would be cheaper and wrong: `changes()` polls while it is collected, so a
+ * shared stream keeps polling for a subscriber that has gone away, and that costs the user's
+ * battery. [invalidate] is the other half of the same rule, for a host runtime that reloads.
+ *
+ * Messages arrive fully framed by the generated `BridgeStreamDispatch`, endings included, so what
+ * this owns is only the lifetime of each collection.
+ */
+internal class StreamRegistry(private val scope: CoroutineScope) {
+
+    /**
+     * Guards [jobs], [closed] and every delivery, so subscribe, teardown and a message in flight
+     * are ordered by one lock: nothing is admitted or handed on once [invalidate] returns.
+     */
+    private val gate = Any()
+    private val jobs = HashMap<String, Job>()
+    private var closed: Boolean = false
+    private val nextId = AtomicLong(0)
+
+    /**
+     * Starts [messages] and sends each one to [sink].
+     *
+     * Returns the id the host cancels with. The id is minted here rather than supplied, so two
+     * subscriptions to the same stream cannot collide on a name the host chose.
+     */
+    fun subscribe(messages: Flow<String>, sink: (String, String) -> Unit): String {
+        val id = "sub-${nextId.incrementAndGet()}"
+        val job = scope.launch(start = CoroutineStart.LAZY) {
+            messages.collect { message -> deliver(id, message, sink) }
+        }
+        val admitted = synchronized(gate) {
+            if (!closed) jobs[id] = job
+            !closed
+        }
+        if (!admitted) {
+            job.cancel()
+            return id
+        }
+        job.invokeOnCompletion { synchronized(gate) { jobs.remove(id) } }
+        job.start()
+        return id
+    }
+
+    /** Cancels one subscription. An unknown id is ignored: a double unsubscribe is not an error. */
+    fun unsubscribe(id: String) {
+        synchronized(gate) { jobs.remove(id) }?.cancel()
+    }
+
+    /** Cancels every subscription, for a host runtime that is going away, and admits no later one. */
+    fun invalidate() {
+        val outstanding = synchronized(gate) {
+            closed = true
+            jobs.values.toList().also { jobs.clear() }
+        }
+        outstanding.forEach { it.cancel() }
+    }
+
+    /** Visible for tests: how many subscriptions are live. */
+    fun count(): Int = synchronized(gate) { jobs.size }
+
+    private fun deliver(id: String, message: String, sink: (String, String) -> Unit) {
+        synchronized(gate) {
+            if (!closed && id in jobs) sink(id, message)
+        }
+    }
+}

package/android/src/bridgeCore/kotlin/co/tryterra/sdk/bridge/TerraBridge.kt

@@ -0,0 +1,86 @@
+package co.tryterra.sdk.bridge
+
+import co.tryterra.sdk.Terra
+import co.tryterra.sdk.bridge.generated.BridgeDispatch
+import co.tryterra.sdk.bridge.generated.BridgeStreamDispatch
+import co.tryterra.sdk.bridge.generated.TerraErrorPayload
+import java.time.ZoneId
+import kotlinx.coroutines.CoroutineScope
+
+/**
+ * The whole public surface of this module: four calls, and none of them mentions a framework.
+ *
+ * A React Native TurboModule forwards `invoke` to [dispatch] and its event emitter to [subscribe].
+ * A Flutter `MethodChannel` handler is `dispatch(call.method, call.arguments)` and an `EventChannel`
+ * wraps [subscribe]. Nothing above this line may leak below it - no `ReadableMap`, no promise type,
+ * no `MethodCall` - because the second wrapper is supposed to be an emitter and a shell, not a
+ * second bridge.
+ *
+ * One per host runtime. The client and the [tokens] broker outlive a reload and are shared; this
+ * object is what a runtime attaches with, and [invalidate] tears down only what it started.
+ *
+ * @param tokens the broker whose `provide` the client was built with. A different one would be a
+ * broker nobody asks, and every `token.*` op would answer requests that never come.
+ */
+public class TerraBridge(
+    terra: Terra,
+    tokens: TokenBroker,
+    host: BridgeHost,
+    scope: CoroutineScope,
+    deviceZone: ZoneId = ZoneId.systemDefault(),
+    /** Receives `(subscriptionId, StreamMessage JSON)`. The framework layer forwards it to its own emitter. */
+    private val emit: (String, String) -> Unit,
+) {
+    private val session = tokens.session()
+    private val ops = BridgeDispatch(TerraBridgeOpsImpl(terra, host, session))
+    private val streams = BridgeStreamDispatch(TerraBridgeStreamsImpl(terra, session, deviceZone), Rejections::of)
+    private val registry = StreamRegistry(scope)
+
+    /**
+     * Runs one op and answers its response JSON.
+     *
+     * Throws [BridgeRejection], never a raw SDK error: the framework layer rejects a promise with a
+     * code and a detail bag, and asking it to translate a `TerraError` would put the error table in
+     * the RN module and again in the Flutter plugin.
+     */
+    public suspend fun dispatch(op: String, payload: String): String = try {
+        ops.dispatch(op, payload)
+    } catch (thrown: Throwable) {
+        if (thrown is kotlinx.coroutines.CancellationException) throw thrown
+        throw BridgeRejection(Rejections.of(thrown))
+    }
+
+    /**
+     * Starts one stream and answers the id that cancels it.
+     *
+     * Every subscription gets its own native stream. The SDK's `changes()` polls while it is
+     * collected, so a shared one would keep polling for a subscriber that had gone away.
+     */
+    public fun subscribe(stream: String, params: String): String {
+        val messages = try {
+            streams.open(stream, params)
+        } catch (thrown: Throwable) {
+            throw BridgeRejection(Rejections.of(thrown))
+        }
+        return registry.subscribe(messages, emit)
+    }
+
+    public fun unsubscribe(id: String) {
+        registry.unsubscribe(id)
+    }
+
+    /**
+     * For a host runtime that is going away: a JavaScript reload, or a Flutter engine detaching.
+     *
+     * The native client outlives it and must not be rebuilt, so what is torn down is everything
+     * this runtime started - its subscriptions and its pending token asks - and nothing a
+     * replacement runtime has started since.
+     */
+    public fun invalidate() {
+        registry.invalidate()
+        session.close()
+    }
+
+    /** What the framework layer turns into a rejected promise. */
+    public class BridgeRejection(public val payload: TerraErrorPayload) : Exception(payload.message)
+}

package/android/src/bridgeCore/kotlin/co/tryterra/sdk/bridge/TerraBridgeOpsImpl.kt

@@ -0,0 +1,258 @@
+package co.tryterra.sdk.bridge
+
+import co.tryterra.sdk.RecordId
+import co.tryterra.sdk.Source
+import co.tryterra.sdk.Terra
+import co.tryterra.sdk.bridge.generated.BoolResult
+import co.tryterra.sdk.bridge.generated.BootstrapState
+import co.tryterra.sdk.bridge.generated.BridgeError
+import co.tryterra.sdk.bridge.generated.BridgeInstant
+import co.tryterra.sdk.bridge.generated.CategoryRequest
+import co.tryterra.sdk.bridge.generated.Connection
+import co.tryterra.sdk.bridge.generated.ConnectRequest
+import co.tryterra.sdk.bridge.generated.ConnectionList
+import co.tryterra.sdk.bridge.generated.DiagnosticsState
+import co.tryterra.sdk.bridge.generated.Empty
+import co.tryterra.sdk.bridge.generated.HealthAccess
+import co.tryterra.sdk.bridge.generated.HeartRateEntryList
+import co.tryterra.sdk.bridge.generated.HeartRateList
+import co.tryterra.sdk.bridge.generated.LastDeliveryResult
+import co.tryterra.sdk.bridge.generated.NutritionEntryList
+import co.tryterra.sdk.bridge.generated.PermissionGrant
+import co.tryterra.sdk.bridge.generated.PermissionRequest
+import co.tryterra.sdk.bridge.generated.RangeRequest
+import co.tryterra.sdk.bridge.generated.RecordIdList
+import co.tryterra.sdk.bridge.generated.RecordIdRequest
+import co.tryterra.sdk.bridge.generated.SleepEntryList
+import co.tryterra.sdk.bridge.generated.SleepSegmentList
+import co.tryterra.sdk.bridge.generated.SourceRequest
+import co.tryterra.sdk.bridge.generated.StatusResult
+import co.tryterra.sdk.bridge.generated.StatusesResult
+import co.tryterra.sdk.bridge.generated.StepCountList
+import co.tryterra.sdk.bridge.generated.StepEntryList
+import co.tryterra.sdk.bridge.generated.SupportReport
+import co.tryterra.sdk.bridge.generated.TerraBridgeOps
+import co.tryterra.sdk.bridge.generated.TokenProviderRequest
+import co.tryterra.sdk.bridge.generated.TokenRejectRequest
+import co.tryterra.sdk.bridge.generated.TokenResolveRequest
+import co.tryterra.sdk.bridge.generated.WorkoutEntryList
+import co.tryterra.sdk.bridge.generated.WorkoutList
+import co.tryterra.sdk.bridge.generated.BodyEntryList
+import co.tryterra.sdk.bridge.generated.Source as WireSource
+import kotlinx.coroutines.CancellationException
+
+/**
+ * The hand-written half: about forty short functions that call the SDK.
+ *
+ * It cannot be incomplete. `TerraBridgeOps` is generated from the schema, so an op added there stops
+ * this file compiling until someone implements it - which is the property the old wrapper's
+ * hand-written string switch could not have, because nothing forced the switch to be exhaustive.
+ *
+ * Everything that is not a direct call lives in `Conversions`. What is left here is the shape of
+ * each call and the one place the SDK's Android surface differs from the wrapper's: the activity a
+ * sheet needs.
+ */
+internal class TerraBridgeOpsImpl(
+    private val terra: Terra,
+    private val host: BridgeHost,
+    private val tokens: TokenBroker.Session,
+) : TerraBridgeOps {
+
+    // ---- client -----------------------------------------------------------------------------
+
+    override suspend fun clientAttach(request: Empty): BootstrapState = BootstrapState(
+        bootstrapped = true,
+        devId = host.devId,
+        platform = host.platform,
+        sdkVersion = host.sdkVersion,
+        backgroundRegistered = host.backgroundRegistered(),
+    )
+
+    override suspend fun clientConnect(request: ConnectRequest): Connection {
+        val source = sourceOf(request.source)
+        val endUser = Conversions.endUser(request.endUser)
+        val stored = request.token?.let { terra.connect(source, endUser, it) } ?: terra.connect(source, endUser)
+        return Conversions.connection(stored)
+    }
+
+    override suspend fun clientConnections(request: Empty): ConnectionList =
+        ConnectionList(terra.connections().map(Conversions::connection))
+
+    override suspend fun clientDisconnect(request: SourceRequest): Empty {
+        terra.disconnect(sourceOf(request.source))
+        return Empty()
+    }
+
+    // ---- token ------------------------------------------------------------------------------
+
+    override suspend fun tokenSetProviderPresent(request: TokenProviderRequest): Empty {
+        tokens.setProviderPresent(request.present, request.timeoutMs)
+        return Empty()
+    }
+
+    override suspend fun tokenResolve(request: TokenResolveRequest): Empty {
+        tokens.resolve(request.requestId, request.token)
+        return Empty()
+    }
+
+    override suspend fun tokenReject(request: TokenRejectRequest): Empty {
+        tokens.reject(request.requestId, request.message)
+        return Empty()
+    }
+
+    // ---- permissions ------------------------------------------------------------------------
+
+    /**
+     * The one op that needs an activity, presented through the launcher that activity registered.
+     *
+     * A host with no registered launcher gets `bridge.no_activity`, and one whose launcher cannot
+     * present right now gets `bridge.permission_sheet_unavailable`, rather than a crash in the contract.
+     */
+    override suspend fun permissionsRequest(request: PermissionRequest): PermissionGrant {
+        val source = sourceOf(request.source)
+        val permissions = terra.on(source).permissions
+        val launcher = host.permissionLauncher(source) ?: throw BridgeError.NoActivity
+        val granted = try {
+            permissions.request(
+                read = request.read.map(Conversions::category).toSet(),
+                write = request.write.map(Conversions::category).toSet(),
+                workouts = request.workouts.map(Conversions::scope).toSet(),
+                launcher = launcher,
+            )
+        } catch (cancelled: CancellationException) {
+            // CancellationException is an IllegalStateException.
+            throw cancelled
+        } catch (refused: IllegalStateException) {
+            // The SDK's refusal of a launcher whose sheet is still up or that was unregistered,
+            // raised before anything is recorded.
+            throw BridgeError.PermissionSheetUnavailable
+        }
+        return PermissionGrant(granted = Conversions.access(granted))
+    }
+
+    override suspend fun permissionsStatus(request: CategoryRequest): StatusResult =
+        StatusResult(Conversions.permissionStatus(permissionsOf(request.source).status(Conversions.category(request.category))))
+
+    override suspend fun permissionsWriteStatus(request: CategoryRequest): StatusResult =
+        StatusResult(
+            Conversions.permissionStatus(permissionsOf(request.source).writeStatus(Conversions.category(request.category))),
+        )
+
+    override suspend fun permissionsRequested(request: SourceRequest): HealthAccess =
+        Conversions.access(permissionsOf(request.source).requested())
+
+    override suspend fun permissionsStatuses(request: SourceRequest): StatusesResult {
+        val statuses = permissionsOf(request.source).statuses()
+            .mapNotNull { (category, status) ->
+                // A category the wrapper does not project has no key to report it under. Dropping
+                // it is right: inventing one would put a name in the map that no type admits.
+                Conversions.category(category)?.let { it to Conversions.permissionStatus(status) }
+            }
+            .toMap()
+        return StatusesResult(statuses)
+    }
+
+    override suspend fun permissionsBackgroundReadStatus(request: SourceRequest): StatusResult =
+        StatusResult(Conversions.permissionStatus(permissionsOf(request.source).backgroundReadStatus()))
+
+    override suspend fun permissionsHistoryReadStatus(request: SourceRequest): StatusResult =
+        StatusResult(Conversions.permissionStatus(permissionsOf(request.source).historyReadStatus()))
+
+    // ---- diagnostics ------------------------------------------------------------------------
+
+    override suspend fun diagnosticsState(request: SourceRequest): DiagnosticsState =
+        Conversions.diagnosticsState(diagnosticsOf(request.source).state())
+
+    override suspend fun diagnosticsLastDelivery(request: SourceRequest): LastDeliveryResult =
+        LastDeliveryResult(diagnosticsOf(request.source).lastDelivery()?.let(BridgeInstant::format))
+
+    override suspend fun diagnosticsReport(request: SourceRequest): SupportReport =
+        Conversions.report(diagnosticsOf(request.source).report())
+
+    override suspend fun diagnosticsSend(request: SourceRequest): Empty {
+        diagnosticsOf(request.source).send()
+        return Empty()
+    }
+
+    // ---- background -------------------------------------------------------------------------
+
+    override suspend fun backgroundIsRegistered(request: Empty): BoolResult =
+        BoolResult(host.backgroundRegistered())
+
+    override suspend fun backgroundCancel(request: Empty): BoolResult =
+        BoolResult(host.cancelBackgroundSync())
+
+    // ---- body -------------------------------------------------------------------------------
+
+    override suspend fun bodyHeartRate(request: RangeRequest): HeartRateList =
+        HeartRateList(terra.body.heartRate(Conversions.timeRange(request.range)).map(Conversions::heartRate))
+
+    override suspend fun bodyLogHeartRate(request: HeartRateEntryList): RecordIdList =
+        RecordIdList(terra.body.log(request.entries.map(Conversions::entry)).map { it.value })
+
+    override suspend fun bodyLog(request: BodyEntryList): RecordIdList =
+        RecordIdList(terra.body.log(request.entries.map(Conversions::entry)).map { it.value })
+
+    override suspend fun bodyDelete(request: RecordIdRequest): Empty {
+        terra.body.delete(RecordId(request.id))
+        return Empty()
+    }
+
+    // ---- daily ------------------------------------------------------------------------------
+
+    override suspend fun dailySteps(request: RangeRequest): StepCountList =
+        StepCountList(terra.daily.steps(Conversions.timeRange(request.range)).map(Conversions::steps))
+
+    override suspend fun dailyLog(request: StepEntryList): RecordIdList =
+        RecordIdList(terra.daily.log(request.entries.map(Conversions::entry)).map { it.value })
+
+    override suspend fun dailyDelete(request: RecordIdRequest): Empty {
+        terra.daily.delete(RecordId(request.id))
+        return Empty()
+    }
+
+    // ---- sleep ------------------------------------------------------------------------------
+
+    override suspend fun sleepSegments(request: RangeRequest): SleepSegmentList =
+        SleepSegmentList(terra.sleep.segments(Conversions.timeRange(request.range)).map(Conversions::segment))
+
+    override suspend fun sleepLog(request: SleepEntryList): RecordIdList =
+        RecordIdList(terra.sleep.log(request.entries.map(Conversions::entry)).map { it.value })
+
+    override suspend fun sleepDelete(request: RecordIdRequest): Empty {
+        terra.sleep.delete(RecordId(request.id))
+        return Empty()
+    }
+
+    // ---- activity ---------------------------------------------------------------------------
+
+    override suspend fun activityWorkouts(request: RangeRequest): WorkoutList =
+        WorkoutList(terra.activity.workouts(Conversions.timeRange(request.range)).map(Conversions::workout))
+
+    override suspend fun activityLog(request: WorkoutEntryList): RecordIdList =
+        RecordIdList(terra.activity.log(request.entries.map(Conversions::entry)).map { it.value })
+
+    override suspend fun activityDelete(request: RecordIdRequest): Empty {
+        terra.activity.delete(RecordId(request.id))
+        return Empty()
+    }
+
+    // ---- nutrition --------------------------------------------------------------------------
+
+    override suspend fun nutritionLog(request: NutritionEntryList): RecordIdList =
+        RecordIdList(terra.nutrition.log(request.entries.map(Conversions::entry)).map { it.value })
+
+    override suspend fun nutritionDelete(request: RecordIdRequest): Empty {
+        terra.nutrition.delete(RecordId(request.id))
+        return Empty()
+    }
+
+    /** Absent means the default source, which is what every other entry point on the SDK assumes. */
+    private fun sourceOf(wire: WireSource?): Source = wire?.let(Conversions::source) ?: Source.HEALTH
+
+    private fun permissionsOf(wire: WireSource?) = terra.on(sourceOf(wire)).permissions
+
+    /** [wire]'s own diagnostics, which read that store's permission record rather than Health Connect's. */
+    private fun diagnosticsOf(wire: WireSource?) = terra.on(sourceOf(wire)).diagnostics
+
+}

package/android/src/bridgeCore/kotlin/co/tryterra/sdk/bridge/TerraBridgeStreamsImpl.kt

@@ -0,0 +1,52 @@
+package co.tryterra.sdk.bridge
+
+import co.tryterra.sdk.DataCategory
+import co.tryterra.sdk.Terra
+import co.tryterra.sdk.bridge.generated.Empty
+import co.tryterra.sdk.bridge.generated.HealthChange
+import co.tryterra.sdk.bridge.generated.TerraBridgeStreams
+import co.tryterra.sdk.bridge.generated.TerraEvent
+import co.tryterra.sdk.bridge.generated.TokenRequest
+import java.time.ZoneId
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.flow.mapNotNull
+
+/**
+ * The hand-written half of the streams: which SDK flow answers each stream, as typed values.
+ *
+ * Routing, validation and the `StreamMessage` framing are generated in `BridgeStreamDispatch`, so a
+ * stream added to the schema stops this file compiling until it is published here.
+ */
+internal class TerraBridgeStreamsImpl(
+    private val terra: Terra,
+    private val tokens: TokenBroker.Session,
+    private val deviceZone: ZoneId,
+) : TerraBridgeStreams {
+
+    override fun diagnosticsEvents(params: Empty): Flow<TerraEvent> =
+        terra.diagnostics.events().map(Conversions::event)
+
+    override fun bodyChanges(params: Empty): Flow<HealthChange> = changes(DataCategory.BODY)
+
+    override fun dailyChanges(params: Empty): Flow<HealthChange> = changes(DataCategory.DAILY)
+
+    override fun sleepChanges(params: Empty): Flow<HealthChange> = changes(DataCategory.SLEEP)
+
+    override fun activityChanges(params: Empty): Flow<HealthChange> = changes(DataCategory.ACTIVITY)
+
+    override fun bridgeTokenRequest(params: Empty): Flow<TokenRequest> = tokens.requests
+
+    private fun changes(category: DataCategory): Flow<HealthChange> {
+        val source = when (category) {
+            DataCategory.BODY -> terra.body.changes()
+            DataCategory.DAILY -> terra.daily.changes()
+            DataCategory.SLEEP -> terra.sleep.changes()
+            DataCategory.ACTIVITY -> terra.activity.changes()
+            // Nutrition is write-only on both platforms and has no `changes()`.
+            DataCategory.NUTRITION, DataCategory.MENSTRUATION ->
+                error("no change stream for $category")
+        }
+        return source.mapNotNull { change -> Conversions.change(change, deviceZone) }
+    }
+}

package/android/src/bridgeCore/kotlin/co/tryterra/sdk/bridge/TokenBroker.kt

@@ -0,0 +1,198 @@
+package co.tryterra.sdk.bridge
+
+import co.tryterra.sdk.TerraError
+import co.tryterra.sdk.bridge.generated.BridgeError
+import co.tryterra.sdk.bridge.generated.TokenRequest
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.atomic.AtomicLong
+import java.util.concurrent.atomic.AtomicReference
+import kotlinx.coroutines.CompletableDeferred
+import kotlinx.coroutines.TimeoutCancellationException
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.MutableSharedFlow
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.merge
+import kotlinx.coroutines.flow.emitAll
+import kotlinx.coroutines.flow.filter
+import kotlinx.coroutines.flow.filterNotNull
+import kotlinx.coroutines.flow.flow
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.flow.onSubscription
+import kotlinx.coroutines.flow.takeWhile
+import kotlinx.coroutines.withTimeout
+
+/**
+ * The SDK's token provider, answered by a runtime that is not in the same process boundary.
+ *
+ * The native client is built before any JavaScript exists, because `BackgroundSync.register` needs
+ * a live `Terra` at process start. So the closure the SDK holds cannot be the host's - it is this
+ * broker's [provide], which asks whichever runtime is listening and waits. Bootstrap creates the
+ * broker first, builds the client with `tokenProvider = broker::provide`, and hands the same broker
+ * to every [TerraBridge] it attaches; a broker the client was not built with is one nobody asks.
+ *
+ * The whole reason this is safe is in the SDK: the provider is referenced on exactly one path,
+ * `Linker.connect`, and `connect` can only be reached from the host's own code. A background wake
+ * never calls it - uploads are signed by the device key, not by a token - so the broker is never
+ * asked a question while nobody is there to answer it.
+ */
+public class TokenBroker {
+
+    private val current = AtomicReference<Session?>(null)
+    private val nextId = AtomicLong(0)
+
+    /**
+     * The closure handed to `Terra`.
+     *
+     * Throws [TerraError.TokenUnavailable] rather than a bridge code when nothing is listening: a
+     * host should not be able to tell itself apart from a native app built without a provider.
+     */
+    public suspend fun provide(): String {
+        val session = current.get() ?: throw TerraError.TokenUnavailable
+        return session.ask("tok-${nextId.incrementAndGet()}")
+    }
+
+    /** A runtime's own view of the broker. One per [TerraBridge], so one per runtime. */
+    internal fun session(): Session = Session()
+
+    /**
+     * Everything one runtime asked, answers and tears down.
+     *
+     * Per runtime rather than per broker, because a reload is a new runtime answering through the
+     * same broker: the old one's teardown has to fail its own asks and leave the new one's alone, and
+     * without an owner on each ask a teardown racing a replacement rejects a link the new runtime
+     * could have answered.
+     */
+    internal inner class Session {
+        private val pending = ConcurrentHashMap<String, CompletableDeferred<String>>()
+
+        /** Each new ask's id. */
+        private val announced = MutableSharedFlow<String>(extraBufferCapacity = ANNOUNCE_BUFFER)
+
+        /** A state rather than a message on [announced], so a full buffer cannot drop the ending. */
+        private val closing = MutableStateFlow(false)
+
+        @Volatile
+        private var open: Boolean = true
+
+        @Volatile
+        private var timeoutMs: Int = DEFAULT_TIMEOUT_MS
+
+        /**
+         * What the `bridge.tokenRequest` stream publishes for this runtime: every subscription sees
+         * every ask, and the first answer settles it.
+         *
+         * Broadcast rather than handed to one collector, because a runtime can hold two
+         * subscriptions - a reload of the screen that made the first, a second `createTerra` - and
+         * an ask taken by one that never answers would time the link out while the other could
+         * have answered. A subscription starting late is first handed the asks still waiting, so
+         * an ask made between setting the provider and subscribing is not lost; the replay and the
+         * live feed can overlap, so each subscription skips an id it has already seen. Another
+         * runtime's asks never reach it: they live in that runtime's own session.
+         */
+        val requests: Flow<TokenRequest> = flow {
+            val seen = HashSet<String>()
+            val asks = announced.onSubscription { for (id in pending.keys.sorted()) emit(id) }
+            emitAll(
+                merge(asks, closing.filter { it }.map { null })
+                    .takeWhile { it != null }
+                    .filterNotNull()
+                    .filter { id -> seen.add(id) && pending.containsKey(id) }
+                    .map { id -> TokenRequest(requestId = id) },
+            )
+        }
+
+        /**
+         * Whether this runtime answers, and how long it may take.
+         *
+         * Without this the broker cannot tell "no host is listening" from "the host is slow", and
+         * would spend the whole timeout on a link that could have failed immediately with the same
+         * code a native app with no provider gets.
+         */
+        fun setProviderPresent(present: Boolean, timeoutMs: Int) {
+            this.timeoutMs = timeoutMs
+            if (present) {
+                if (open) current.set(this)
+            } else {
+                current.compareAndSet(this, null)
+            }
+        }
+
+        suspend fun ask(id: String): String {
+            val answer = CompletableDeferred<String>()
+            pending[id] = answer
+            // Re-read after the insert. `close` between the caller's check and the insert would
+            // otherwise leave this ask in the map with nobody left to answer it, and the link would
+            // wait out its whole timeout instead of failing at once.
+            if (!open) {
+                pending.remove(id)
+                throw TerraError.TokenUnavailable
+            }
+            val limit = timeoutMs
+            return try {
+                // Inside the timeout: a subscription that stopped collecting can fill the feed, and
+                // an ask waiting for room is still an ask the host has not answered.
+                withTimeout(limit.toLong()) {
+                    announced.emit(id)
+                    answer.await()
+                }
+            } catch (timedOut: TimeoutCancellationException) {
+                throw TerraError.TokenProviderFailed(BridgeError.TokenTimeout(limit))
+            } finally {
+                pending.remove(id)
+            }
+        }
+
+        /**
+         * An unknown or already-settled id is ignored rather than refused.
+         *
+         * A host that reloads answers a request the previous runtime made, and failing that answer
+         * would turn a harmless race into a failed link.
+         */
+        fun resolve(requestId: String, token: String) {
+            pending[requestId]?.complete(token)
+        }
+
+        fun reject(requestId: String, message: String) {
+            pending[requestId]?.completeExceptionally(TerraError.TokenProviderFailed(ProviderRefused(message)))
+        }
+
+        /**
+         * Fails this runtime's outstanding asks, for a runtime that is going away.
+         *
+         * Otherwise a pending ask holds the link open for its whole timeout and the host sees a
+         * connect that hangs rather than one that failed. Marked closed before draining, so an ask
+         * inserted after the drain finds `open` false on its re-read and removes itself.
+         */
+        fun close() {
+            open = false
+            current.compareAndSet(this, null)
+            closing.value = true
+            while (pending.isNotEmpty()) {
+                for (id in pending.keys.toList()) {
+                    pending.remove(id)?.completeExceptionally(
+                        TerraError.TokenProviderFailed(ProviderRefused("the host runtime went away")),
+                    )
+                }
+            }
+        }
+
+        /** Visible for tests: how many asks are waiting for an answer. */
+        fun pendingCount(): Int = pending.size
+    }
+
+    /** The provider's own failure, carried so that its message reaches `details.message`. */
+    public class ProviderRefused(message: String) : Exception(message)
+
+    public companion object {
+        /**
+         * Thirty seconds, matching the documented default.
+         *
+         * Long enough for a host to call its own backend on a poor connection, short enough that a
+         * host which never answers fails the link rather than appearing to hang.
+         */
+        public const val DEFAULT_TIMEOUT_MS: Int = 30_000
+
+        /** Asks a slow subscription can fall behind by; a link makes at most two. */
+        private const val ANNOUNCE_BUFFER = 64
+    }
+}