@tryterra/react-native 0.0.0-stage → 2.2.1

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

@@ -0,0 +1,300 @@
+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.DietaryQuantityList
+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.MenstruationFlowDayList
+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.AvailabilityResult
+import co.tryterra.sdk.bridge.generated.BodyEntryList
+import co.tryterra.sdk.bridge.generated.BodyReadingList
+import co.tryterra.sdk.bridge.generated.DayTotalList
+import co.tryterra.sdk.bridge.generated.HydrationList
+import co.tryterra.sdk.bridge.generated.IntradaySampleList
+import co.tryterra.sdk.bridge.generated.MenstrualEventList
+import co.tryterra.sdk.bridge.generated.RestingHeartRateList
+import co.tryterra.sdk.bridge.generated.WorkoutIntensityList
+import co.tryterra.sdk.bridge.generated.WorkoutRouteList
+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 clientAvailability(request: SourceRequest): AvailabilityResult =
+        AvailabilityResult(ReadConversions.availability(terra.availability(sourceOf(request.source))))
+
+    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()
+            .map { (category, status) -> Conversions.category(category) 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 bodyRestingHeartRate(request: RangeRequest): RestingHeartRateList =
+        RestingHeartRateList(terra.body.restingHeartRate(Conversions.timeRange(request.range)).map(ReadConversions::restingHeartRate))
+
+    override suspend fun bodyReadings(request: RangeRequest): BodyReadingList =
+        BodyReadingList(terra.body.readings(Conversions.timeRange(request.range)).mapNotNull(ReadConversions::bodyReading))
+
+    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 dailyTotals(request: RangeRequest): DayTotalList =
+        DayTotalList(terra.daily.totals(Conversions.timeRange(request.range)).mapNotNull(ReadConversions::dayTotal))
+
+    override suspend fun dailyIntraday(request: RangeRequest): IntradaySampleList =
+        IntradaySampleList(terra.daily.intraday(Conversions.timeRange(request.range)).map(ReadConversions::intraday))
+
+    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 activityRoutes(request: RangeRequest): WorkoutRouteList =
+        WorkoutRouteList(terra.activity.routes(Conversions.timeRange(request.range)).map(ReadConversions::route))
+
+    override suspend fun activityIntensity(request: RangeRequest): WorkoutIntensityList =
+        WorkoutIntensityList(terra.activity.intensity(Conversions.timeRange(request.range)).map(ReadConversions::intensity))
+
+    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 nutritionQuantities(request: RangeRequest): DietaryQuantityList =
+        DietaryQuantityList(terra.nutrition.quantities(Conversions.timeRange(request.range)).map(Conversions::quantity))
+
+    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()
+    }
+
+    override suspend fun nutritionHydration(request: RangeRequest): HydrationList =
+        HydrationList(terra.nutrition.hydration(Conversions.timeRange(request.range)).map(ReadConversions::hydration))
+
+    // ---- menstruation -----------------------------------------------------------------------
+
+    override suspend fun menstruationFlow(request: RangeRequest): MenstruationFlowDayList =
+        MenstruationFlowDayList(terra.menstruation.flow(Conversions.timeRange(request.range)).map(Conversions::flowDay))
+
+    override suspend fun menstruationEvents(request: RangeRequest): MenstrualEventList =
+        MenstrualEventList(terra.menstruation.events(Conversions.timeRange(request.range)).mapNotNull(ReadConversions::menstrualEvent))
+
+    /** 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,50 @@
+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
+
+/**
+ * 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()
+            DataCategory.NUTRITION, DataCategory.MENSTRUATION ->
+                error("no change stream for $category")
+        }
+        return source.map { 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
+    }
+}