@tileflow/react-native 0.0.0-bootstrap.0 → 0.1.0-alpha.1

package/android/src/main/java/dev/tileflow/reactnative/AdmissionCatalog.kt

@@ -0,0 +1,137 @@
+package dev.tileflow.reactnative
+
+import java.io.ByteArrayOutputStream
+import java.nio.ByteBuffer
+import java.nio.charset.CodingErrorAction
+
+/** A finite set of exact documents and narrowly typed URL expansions. */
+internal class AdmissionCatalog(resources: List<AdmissionResource>) {
+	private class Rule(val resource: AdmissionResource, val pattern: Regex?, val names: List<String>)
+	private val rules: List<Rule>
+
+	init {
+		if (resources.size > AdmissionLimits.RESOURCES) invalid()
+		val seen = mutableSetOf<String>()
+		rules = resources.map {
+			val resource = validate(it)
+			if (!seen.add(resource.url)) invalid()
+			if (resource.template == null) Rule(resource, null, emptyList())
+			else {
+				val names = mutableListOf<String>()
+				var cursor = 0
+				val expression = StringBuilder("^")
+				for (match in placeholder.findAll(resource.url)) {
+					val name = match.groupValues[1]
+					if (names.size >= 16 || (names.isNotEmpty() && match.range.first == cursor)) invalid()
+					expression.append(Regex.escape(resource.url.substring(cursor, match.range.first)))
+					expression.append('(').append(slots[name] ?: invalid()).append(')')
+					names.add(name)
+					cursor = match.range.last + 1
+				}
+				if (names.isEmpty()) invalid()
+				expression.append(Regex.escape(resource.url.substring(cursor))).append('$')
+				Rule(resource, Regex(expression.toString()), names.toList())
+			}
+		}
+	}
+
+	fun find(url: String): AdmissionResource? {
+		try { AdmissionUrl.clean(url) } catch (_: Exception) { return null }
+		var found: AdmissionResource? = null
+		for (rule in rules) {
+			if (!matches(rule, url)) continue
+			if (found != null) invalid()
+			found = AdmissionResource(url, rule.resource.scope, rule.resource.tilesetId)
+		}
+		return found
+	}
+
+	private fun matches(rule: Rule, url: String): Boolean {
+		val pattern = rule.pattern ?: return rule.resource.url == url
+		val match = pattern.matchEntire(url) ?: return false
+		val values = mutableMapOf<String, String>()
+		for ((index, name) in rule.names.withIndex()) {
+			val value = match.groupValues[index + 1]
+			if (values.containsKey(name) && values[name] != value) return false
+			values[name] = value
+		}
+		val zoom = values["z"]?.toIntOrNull()
+		if (zoom != null && zoom > 30) return false
+		for (name in listOf("x", "y")) {
+			val coordinate = values[name]?.toLongOrNull() ?: continue
+			if (coordinate >= (1L shl (zoom ?: 30))) return false
+		}
+		values["quadkey"]?.let { if (zoom != null && it.length != zoom) return false }
+		values["bbox-epsg-3857"]?.let { box ->
+			val numbers = box.split(',').map { it.toDoubleOrNull() ?: return false }
+			if (numbers.size != 4 || numbers.any { !it.isFinite() || kotlin.math.abs(it) > 20037508.343 } || numbers[0] >= numbers[2] || numbers[1] >= numbers[3]) return false
+		}
+		values["range"]?.let { range ->
+			val pair = range.split('-').map { it.toLongOrNull() ?: return false }
+			if (pair.size != 2 || pair[0] % 256 != 0L || pair[1] != pair[0] + 255 || pair[1] > 1114111) return false
+		}
+		values["fontstack"]?.let { stack ->
+			val decoded = try { decode(stack) } catch (_: Exception) { return false }
+			if (rule.resource.fontStacks?.contains(decoded) != true) return false
+		}
+		return true
+	}
+
+	companion object {
+		private val placeholder = Regex("\\{([a-z0-9-]+)\\}")
+		private val decimal = "(?:0|[1-9][0-9]{0,9})"
+		private val coordinate = "-?(?:0|[1-9][0-9]{0,7})(?:\\.[0-9]{1,16})?"
+		private val slots = mapOf(
+			"z" to "(?:0|[1-9][0-9]?)", "x" to decimal, "y" to decimal,
+			"ratio" to "(?:@2x|@3x)?", "quadkey" to "[0-3]{0,30}", "prefix" to "[0-9a-f]{2}",
+			"bbox-epsg-3857" to "$coordinate,$coordinate,$coordinate,$coordinate",
+			"fontstack" to "(?:[A-Za-z0-9_.~,+-]|%[0-9a-fA-F]{2}){1,768}", "range" to "$decimal-$decimal"
+		)
+		private val scopes = setOf("style", "tilejson", "tile", "sprite", "glyph", "font")
+		private val compact = Regex("[A-Za-z0-9._:-]{1,255}")
+
+		fun validate(value: AdmissionResource): AdmissionResource {
+			try {
+				if (value.url.length > AdmissionLimits.URL - 128 || !scopes.contains(value.scope)) invalid()
+				if ((value.scope == "tile" || value.scope == "tilejson") && value.tilesetId == null) invalid()
+				value.tilesetId?.let { if (!compact.matches(it) || it.contains("tf_native_", true) || it.contains("tf_public_", true)) invalid() }
+				if (value.template == null) {
+					if (value.fontStacks != null || value.url.contains('{') || value.url.contains('}')) invalid()
+					AdmissionUrl.clean(value.url)
+					return AdmissionResource(value.url, value.scope, value.tilesetId)
+				}
+				if (value.template !in setOf("tile", "glyphs")) invalid()
+				val authority = value.url.substringBefore('/', "").takeIf { it.isNotEmpty() }
+				if (authority == null || !value.url.startsWith("https://")) invalid()
+				val path = value.url.indexOf('/', 8)
+				if (path < 0 || value.url.substring(0, path).any { it == '{' || it == '}' }) invalid()
+				val names = placeholder.findAll(value.url).map { it.groupValues[1] }.toList()
+				if (names.isEmpty() || names.size > 16 || names.any { !slots.containsKey(it) }) invalid()
+				val masked = placeholder.replace(value.url, "native-template-slot")
+				if (masked.contains('{') || masked.contains('}')) invalid()
+				AdmissionUrl.clean(masked)
+				if (value.template == "tile") {
+					if (value.scope != "tile" || value.fontStacks != null || names.any { it == "fontstack" || it == "range" }) invalid()
+					return AdmissionResource(value.url, value.scope, value.tilesetId, "tile")
+				}
+				val stacks = value.fontStacks ?: invalid()
+				if (value.scope != "glyph" || !names.containsAll(listOf("fontstack", "range")) || names.any { it != "fontstack" && it != "range" } || stacks.isEmpty() || stacks.size > 16 || stacks.toSet().size != stacks.size) invalid()
+				for (stack in stacks) {
+					if (stack.isEmpty() || stack.length > 256 || stack != stack.trim() || stack.any { it.code < 32 || it.code in 127..159 || it in "\\/?#%&=" } || stack.contains("tf_native_", true) || stack.contains("tf_public_", true) || stack.split(',').any { it.isEmpty() || it != it.trim() }) invalid()
+				}
+				return AdmissionResource(value.url, value.scope, value.tilesetId, "glyphs", stacks.toList())
+			} catch (_: Exception) { invalid() }
+		}
+
+		private fun decode(value: String): String {
+			val bytes = ByteArrayOutputStream()
+			var index = 0
+			while (index < value.length) {
+				if (value[index] == '%') { bytes.write(value.substring(index + 1, index + 3).toInt(16)); index += 3 }
+				else { bytes.write(value[index].code); index++ }
+			}
+			return Charsets.UTF_8.newDecoder().onMalformedInput(CodingErrorAction.REPORT).onUnmappableCharacter(CodingErrorAction.REPORT).decode(ByteBuffer.wrap(bytes.toByteArray())).toString()
+		}
+		private fun invalid(): Nothing = throw IllegalArgumentException("Invalid native resource catalog")
+	}
+}

package/android/src/main/java/dev/tileflow/reactnative/AdmissionDocumentScope.kt

@@ -0,0 +1,22 @@
+package dev.tileflow.reactnative
+
+import java.util.concurrent.atomic.AtomicBoolean
+
+internal fun createAdmissionDocumentScope(admission: AdmissionEngine, context: String, maximumBytes: Int): NativeDocumentScope {
+	if (maximumBytes !in 1..8388608) throw IllegalArgumentException("Native document acquisition failed.")
+	val active = admission.contextGuard(context)
+	return NativeDocumentScope(active, { url, completion ->
+		AdmissionUrl.clean(url)
+		val completed = AtomicBoolean(false)
+		val finish: (AdmissionHttpResponse?) -> Unit = { response ->
+			if (completed.compareAndSet(false, true)) completion(response)
+		}
+		val tagged = "$url${if (url.contains('?')) '&' else '?'}__tf_native_context=$context"
+		val request = admission.requestDocument(tagged, maximumBytes, { finish(it) }, { finish(null) })
+		AdmissionCancellation {
+			request.cancel()
+			// The admission transport independently retains its physical network slot.
+			finish(null)
+		}
+	}, context)
+}

package/android/src/main/java/dev/tileflow/reactnative/AdmissionEngine.kt

@@ -0,0 +1,335 @@
+package dev.tileflow.reactnative
+
+import java.util.concurrent.atomic.AtomicBoolean
+import java.util.concurrent.atomic.AtomicInteger
+
+// All mutable collections are confined to the injected serial scheduler.
+// Atomic liveness and volatile deadlines are also read at OkHttp network start.
+internal class AdmissionEngine(
+	private val installation: String,
+	private val scheduler: AdmissionScheduler,
+	private val network: AdmissionNetwork,
+	private val owns: () -> Boolean,
+	private val emit: (Map<String, Any>) -> Unit,
+) {
+	private class Context(val id: String, val mapId: String?, var resources: Map<String, AdmissionResource>) {
+		var catalog = AdmissionCatalog(resources.values.toList())
+		val live = AtomicBoolean(true)
+		val work = linkedMapOf<String, Work>()
+		var batch: Batch? = null
+		var sequence = 0L
+	}
+	private class Batch(val id: String, val tickets: List<String>) {
+		var timer: AdmissionCancellation? = null
+	}
+	private class Work(
+		val id: String,
+		val context: Context,
+		val url: String,
+		val headers: Map<String, String>,
+		val maximumBytes: Int,
+		val entered: Long,
+		val live: AtomicBoolean,
+		val response: (AdmissionHttpResponse) -> Unit,
+		val failure: () -> Unit,
+		val delegate: (String, (AdmissionHttpResponse?) -> Unit) -> AdmissionCancellation,
+		val release: () -> Unit,
+	) {
+		var phase = "queue"
+		var cancellation: AdmissionCancellation? = null
+		var timer: AdmissionCancellation? = null
+		var authority: AdmissionAuthority? = null
+		@Volatile var deadline = 0L
+		var redirects = 0
+	}
+	private val contexts = linkedMapOf<String, Context>()
+	private val live = AtomicBoolean(true)
+	private val lossQueued = AtomicBoolean(false)
+	private val reservations = AtomicInteger(0)
+	@Volatile private var foreground = true
+	private var contextSequence = 0L
+	private var ticketSequence = 0L
+
+	fun register(mapId: String?, resources: List<AdmissionResource>): String {
+		if (!checkOwnership() || contexts.size >= AdmissionLimits.CONTEXTS || resources.size > AdmissionLimits.RESOURCES ||
+			(mapId != null && !Regex("map_[A-Za-z0-9_-]{16}").matches(mapId))) invalid()
+		val catalog = linkedMapOf<String, AdmissionResource>()
+		for (resource in resources) {
+			val snapshot = AdmissionCatalog.validate(resource)
+			if (catalog.put(snapshot.url, snapshot) != null) invalid()
+		}
+		if (contextSequence >= 9007199254740991L) invalid()
+		val id = "$installation.${++contextSequence}"
+		contexts[id] = Context(id, mapId, catalog)
+		return id
+	}
+
+	// Capture the original atomic context lifetime rather than consulting a mutable registry off-thread.
+	fun contextGuard(contextId: String): () -> Boolean {
+		val context = contexts[contextId] ?: invalid()
+		if (!context.live.get() || !checkOwnership()) invalid()
+		return { context.live.get() && foreground && checkOwnership() }
+	}
+
+	private fun extension(previous: AdmissionResource, next: AdmissionResource): AdmissionResource {
+		if (previous.scope != next.scope || previous.tilesetId != next.tilesetId || previous.template != next.template) invalid()
+		if (previous.fontStacks == next.fontStacks) return previous
+		if (previous.scope != "glyph" || previous.template != "glyphs") invalid()
+		val before = previous.fontStacks ?: invalid()
+		val after = next.fontStacks ?: invalid()
+		if (!after.containsAll(before) || after.size > 16) invalid()
+		return AdmissionCatalog.validate(
+			AdmissionResource(previous.url, previous.scope, previous.tilesetId, previous.template, after)
+		)
+	}
+
+	// Append-only within a context: rollback can still use its last accepted style.
+	// Identical retries are acknowledged; only a glyph template may widen its finite stack set.
+	fun extend(contextId: String, resources: List<AdmissionResource>): Int {
+		val context = contexts[contextId] ?: invalid()
+		if (!checkOwnership() || !context.live.get() || resources.size > AdmissionLimits.RESOURCES) invalid()
+		val next = LinkedHashMap(context.resources)
+		for (resource in resources) {
+			val snapshot = AdmissionCatalog.validate(resource)
+			val previous = next[snapshot.url]
+			next[snapshot.url] = if (previous == null) snapshot else extension(previous, snapshot)
+		}
+		val catalog = AdmissionCatalog(next.values.toList())
+		context.resources = next
+		context.catalog = catalog
+		return next.size
+	}
+
+	private fun resource(context: Context, url: String): AdmissionResource? =
+		try { context.catalog.find(url) } catch (_: Exception) { null }
+
+	fun request(
+		url: String,
+		headers: Map<String, String>,
+		onResponse: (AdmissionHttpResponse) -> Unit,
+		onFailure: () -> Unit,
+		onDelegate: (String, (AdmissionHttpResponse?) -> Unit) -> AdmissionCancellation,
+	): AdmissionCancellation = requestBounded(url, headers, AdmissionLimits.RESPONSE_BYTES.toInt(), onResponse, onFailure, onDelegate)
+
+	fun requestDocument(
+		url: String,
+		maximumBytes: Int,
+		onResponse: (AdmissionHttpResponse) -> Unit,
+		onFailure: () -> Unit,
+	): AdmissionCancellation = requestBounded(url, emptyMap(), maximumBytes, onResponse, onFailure, { _, completion ->
+		// Unprotected preparation uses the separate credential-free document channel.
+		completion(null); AdmissionCancellation {}
+	})
+
+	private fun requestBounded(
+		url: String,
+		headers: Map<String, String>,
+		maximumBytes: Int,
+		onResponse: (AdmissionHttpResponse) -> Unit,
+		onFailure: () -> Unit,
+		onDelegate: (String, (AdmissionHttpResponse?) -> Unit) -> AdmissionCancellation,
+	): AdmissionCancellation {
+		if (maximumBytes !in 1..AdmissionLimits.RESPONSE_BYTES.toInt()) invalid()
+		// Bound ingress before posting to the main scheduler. Cancellation
+		// retains this transport slot until serialized cleanup has run.
+		if (reservations.incrementAndGet() > AdmissionLimits.CONTEXTS * AdmissionLimits.QUEUE) {
+			reservations.decrementAndGet(); onFailure(); return AdmissionCancellation {}
+		}
+		val reserved = AtomicBoolean(true)
+		val release: () -> Unit = { if (reserved.getAndSet(false)) reservations.decrementAndGet() }
+		val active = AtomicBoolean(true)
+		var work: Work? = null
+		scheduler.dispatch {
+			if (!active.get()) { release(); return@dispatch }
+			val tagged = try { AdmissionUrl.strip(url) } catch (_: Exception) {
+				active.set(false); release(); onFailure(); return@dispatch
+			}
+			val context = contexts[tagged.context]
+			if (!foreground || !checkOwnership() || context == null || !context.live.get() ||
+				resource(context, tagged.url) == null || context.work.size >= AdmissionLimits.QUEUE ||
+				headers.keys.any { it.equals(AdmissionLimits.GRANT_HEADER, true) } ||
+				ticketSequence >= 9007199254740991L) {
+				active.set(false); release(); onFailure(); return@dispatch
+			}
+			val item = Work((++ticketSequence).toString(), context, tagged.url, headers.toMap(), maximumBytes, scheduler.nowMs(), active, onResponse, onFailure, onDelegate, release)
+			work = item
+			context.work[item.id] = item
+			item.timer = scheduler.after(AdmissionLimits.WAIT_MS) {
+				if (context.batch?.tickets?.contains(item.id) == true) retire(context.id)
+				else fail(item)
+			}
+			scheduler.dispatch { drain(context) }
+		}
+		return AdmissionCancellation {
+			if (active.compareAndSet(true, false)) scheduler.dispatch {
+				work?.let { item ->
+					if (item.context.batch?.tickets?.contains(item.id) == true) {
+						event(item.context, "cancel", mapOf("tickets" to listOf(item.id)))
+					}
+					finish(item)
+				}
+			}
+		}
+	}
+
+	private fun drain(context: Context) {
+		if (!context.live.get() || !foreground || !checkOwnership() || context.batch != null) return
+		val selected = context.work.values.filter { it.live.get() && it.phase == "queue" }.take(AdmissionLimits.BATCH)
+		if (selected.isEmpty()) return
+		if (context.sequence >= 9007199254740991L) { retire(context.id); return }
+		val batch = Batch((++context.sequence).toString(), selected.map { it.id })
+		context.batch = batch
+		for (item in selected) item.phase = "javascript"
+		batch.timer = scheduler.after(AdmissionLimits.WAIT_MS) {
+			if (context.batch === batch) retire(context.id)
+		}
+		event(context, "batch", mapOf("batch" to batch.id, "tickets" to selected.map { mapOf("ticket" to it.id, "url" to it.url) }))
+	}
+
+	fun complete(contextId: String, generation: Long, batchId: String, results: List<AdmissionResult>): Int {
+		val context = contexts[contextId] ?: return 0
+		val batch = context.batch ?: return 0
+		if (!context.live.get() || generation != 1L || batch.id != batchId || !checkOwnership()) return 0
+		if (results.size > AdmissionLimits.BATCH || results.map { it.ticket } != batch.tickets) { retire(contextId); return 0 }
+		batch.timer?.cancel()
+		context.batch = null
+		var accepted = 0
+		for (result in results) {
+			val item = context.work[result.ticket] ?: continue
+			if (!item.live.get()) { finish(item); continue }
+			if (!foreground || scheduler.nowMs() - item.entered >= AdmissionLimits.WAIT_MS) { fail(item); continue }
+			when (result) {
+				is AdmissionResult.Reject -> fail(item)
+				is AdmissionResult.Delegate -> {
+					if (context.mapId != null) { fail(item); continue }
+					item.phase = "network"
+					item.deadline = item.entered + AdmissionLimits.WAIT_MS
+					if (!canStart(item)) { fail(item); continue }
+					try {
+						item.cancellation = item.delegate(item.url) { response -> scheduler.dispatch { received(item, item.url, response) } }
+						if (!item.live.get()) item.cancellation?.cancel()
+						accepted++
+					} catch (_: Exception) { fail(item) }
+				}
+				is AdmissionResult.Grant -> {
+					val selected = resource(context, item.url)
+					val authority = result.authority
+					if (context.mapId == null || selected == null || result.validForMs !in 1..AdmissionLimits.MAX_VALID_MS ||
+						authority.grant.length > AdmissionLimits.GRANT || !Regex("tf_native_v1\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+").matches(authority.grant) ||
+						!authority.allows(selected, context.mapId)) { fail(item); continue }
+					item.authority = authority
+					// Anchor at the earlier enqueue time, never at bridge receipt.
+					item.deadline = minOf(item.entered + AdmissionLimits.WAIT_MS, item.entered + result.validForMs - AdmissionLimits.SAFETY_MS)
+					if (start(item, item.url)) accepted++
+				}
+			}
+		}
+		scheduler.dispatch { drain(context) }
+		return accepted
+	}
+
+	private fun canStart(item: Work): Boolean {
+		if (!item.live.get() || !item.context.live.get() || !foreground || !live.get() || scheduler.nowMs() >= item.deadline) return false
+		if (!ownsSafely()) { loseOwnership(); return false }
+		return true
+	}
+
+	private fun start(item: Work, url: String): Boolean {
+		val authority = item.authority ?: return false
+		val selected = resource(item.context, url)
+		val mapId = item.context.mapId
+		if (selected == null || mapId == null || !authority.allows(selected, mapId) || !canStart(item)) { fail(item); return false }
+		item.phase = "network"
+		val headers = item.headers + (AdmissionLimits.GRANT_HEADER to authority.grant)
+		return try {
+			item.cancellation = network.start(AdmissionHttpRequest(url, headers, item.maximumBytes) { canStart(item) }) { response ->
+				scheduler.dispatch { received(item, url, response) }
+			}
+			if (!item.live.get()) item.cancellation?.cancel()
+			true
+		} catch (_: Exception) { fail(item); false }
+	}
+
+	private fun received(item: Work, url: String, response: AdmissionHttpResponse?) {
+		if (!item.live.get() || !item.context.live.get()) return
+		if (!checkOwnership()) return
+		if (response == null || response.body.size > item.maximumBytes || !foreground || scheduler.nowMs() >= item.deadline) { fail(item); return }
+		event(item.context, "response", mapOf("status" to response.code))
+		if (item.authority != null && response.code in listOf(301, 302, 303, 307, 308)) {
+			if (++item.redirects > AdmissionLimits.REDIRECTS) { fail(item); return }
+			val location = response.headers.entries.firstOrNull { it.key.equals("location", true) }?.value
+			val target = try { AdmissionUrl.redirect(url, location ?: "", item.context.id) } catch (_: Exception) { fail(item); return }
+			if (location.isNullOrEmpty()) { fail(item); return }
+			start(item, target)
+			return
+		}
+		if (!item.live.compareAndSet(true, false)) return
+		finish(item)
+		item.response(AdmissionHttpResponse(response.code, response.headers, response.body, url))
+	}
+
+	private fun finish(item: Work) {
+		item.live.set(false)
+		item.cancellation?.cancel()
+		item.cancellation = null
+		item.timer?.cancel()
+		item.timer = null
+		item.authority = null
+		item.context.work.remove(item.id)
+		item.release()
+		scheduler.dispatch { drain(item.context) }
+	}
+	private fun fail(item: Work) {
+		val notify = item.live.getAndSet(false)
+		finish(item)
+		if (notify) item.failure()
+	}
+
+	fun retire(contextId: String) {
+		val context = contexts.remove(contextId) ?: return
+		context.live.set(false)
+		context.batch?.timer?.cancel()
+		context.batch = null
+		for (item in context.work.values.toList()) fail(item)
+		event(context, "retired", mapOf("code" to "NATIVE_ADMISSION_CANCELLED"))
+	}
+
+	fun lifecycle(active: Boolean) {
+		foreground = active
+		if (!active) {
+			for (context in contexts.values.toList()) {
+				val tickets = context.batch?.tickets
+				if (!tickets.isNullOrEmpty()) event(context, "cancel", mapOf("tickets" to tickets))
+				for (item in context.work.values.toList()) fail(item)
+			}
+		}
+		safeEmit(mapOf("kind" to "lifecycle", "installation" to installation, "foreground" to active))
+		if (active) for (context in contexts.values) scheduler.dispatch { drain(context) }
+	}
+
+	fun close() {
+		live.set(false)
+		for (context in contexts.keys.toList()) retire(context)
+	}
+	fun checkOwnership(): Boolean {
+		if (!live.get()) return false
+		if (!ownsSafely()) { loseOwnership(); return false }
+		return true
+	}
+	private fun ownsSafely() = try { owns() } catch (_: Exception) { false }
+	private fun loseOwnership() {
+		live.set(false)
+		if (!lossQueued.compareAndSet(false, true)) return
+		scheduler.dispatch {
+			close()
+			safeEmit(mapOf("kind" to "ownershipLost", "installation" to installation))
+		}
+	}
+	private fun event(context: Context, kind: String, fields: Map<String, Any>) {
+		safeEmit(mapOf("kind" to kind, "installation" to installation, "context" to context.id, "generation" to 1) + fields)
+	}
+	private fun safeEmit(event: Map<String, Any>) {
+		try { emit(event) } catch (_: Exception) { close() }
+	}
+	private fun invalid(): Nothing = throw IllegalArgumentException("Invalid native admission")
+}

package/android/src/main/java/dev/tileflow/reactnative/AdmissionModuleProvider.kt

@@ -0,0 +1,68 @@
+package dev.tileflow.reactnative
+
+import java.util.concurrent.atomic.AtomicBoolean
+import org.maplibre.android.LibraryLoaderProvider
+import org.maplibre.android.ModuleProvider
+import org.maplibre.android.http.HttpRequest
+import org.maplibre.android.http.HttpResponder
+
+internal class AdmissionModuleProvider(
+	private val previous: ModuleProvider,
+	private val engine: AdmissionEngine,
+) : ModuleProvider {
+	override fun createLibraryLoaderProvider(): LibraryLoaderProvider = previous.createLibraryLoaderProvider()
+	override fun createHttpRequest(): HttpRequest = Request(previous.createHttpRequest(), engine)
+
+	private class Request(private val previous: HttpRequest, private val engine: AdmissionEngine) : HttpRequest {
+		private val cancelled = AtomicBoolean(false)
+		private val used = AtomicBoolean(false)
+		@Volatile private var delegated = false
+		@Volatile private var cancellation: AdmissionCancellation? = null
+
+		override fun executeRequest(responder: HttpResponder, nativePtr: Long, resourceUrl: String, dataRange: String, etag: String, modified: String, offlineUsage: Boolean) {
+			if (cancelled.get()) return
+			if (!used.compareAndSet(false, true)) {
+				responder.handleFailure(HttpRequest.PERMANENT_ERROR, "Native request was already started")
+				return
+			}
+			if (!AdmissionUrl.reserved(resourceUrl)) {
+				// Unowned traffic does not pass through our queue or header code.
+				delegated = true
+				previous.executeRequest(responder, nativePtr, resourceUrl, dataRange, etag, modified, offlineUsage)
+				if (cancelled.get()) previous.cancelRequest()
+				return
+			}
+			val headers = linkedMapOf<String, String>()
+			if (dataRange.isNotEmpty()) headers["Range"] = dataRange
+			if (etag.isNotEmpty()) headers["If-None-Match"] = etag
+			else if (modified.isNotEmpty()) headers["If-Modified-Since"] = modified
+			cancellation = engine.request(resourceUrl, headers,
+				{ response ->
+					if (!cancelled.get()) responder.onResponse(response.code,
+						response.headers["etag"], response.headers["last-modified"], response.headers["cache-control"],
+						response.headers["expires"], response.headers["retry-after"], response.headers["x-rate-limit-reset"], response.body)
+				},
+				{ if (!cancelled.get()) responder.handleFailure(HttpRequest.TEMPORARY_ERROR, "Native resource admission failed") },
+				{ clean, done ->
+					previous.executeRequest(object : HttpResponder {
+						override fun onResponse(responseCode: Int, eTag: String?, lastModified: String?, cacheControl: String?, expires: String?, retryAfter: String?, xRateLimitReset: String?, body: ByteArray?) {
+							val metadata = linkedMapOf<String, String>()
+							for ((name, value) in listOf("etag" to eTag, "last-modified" to lastModified, "cache-control" to cacheControl, "expires" to expires, "retry-after" to retryAfter, "x-rate-limit-reset" to xRateLimitReset)) {
+								if (value != null) metadata[name] = value
+							}
+							done(AdmissionHttpResponse(responseCode, metadata, body ?: byteArrayOf()))
+						}
+						override fun handleFailure(type: Int, errorMessage: String?) { done(null) }
+					}, nativePtr, clean, dataRange, etag, modified, offlineUsage)
+					AdmissionCancellation { previous.cancelRequest() }
+				})
+			if (cancelled.get()) cancellation?.cancel()
+		}
+
+		override fun cancelRequest() {
+			cancelled.set(true)
+			cancellation?.cancel()
+			if (delegated) previous.cancelRequest()
+		}
+	}
+}

package/android/src/main/java/dev/tileflow/reactnative/AdmissionOkHttpNetwork.kt

@@ -0,0 +1,86 @@
+package dev.tileflow.reactnative
+
+import java.io.IOException
+import java.util.concurrent.TimeUnit
+import okhttp3.Call
+import okhttp3.Callback
+import okhttp3.Dispatcher
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.Response
+
+internal class AdmissionOkHttpNetwork(private val dispatcher: Dispatcher = Dispatcher()) : AdmissionNetwork {
+	private class StartGuard(val allowed: () -> Boolean) {
+		override fun toString() = "NativeAdmissionStartGuard"
+	}
+	private val lock = Any()
+	private val calls = mutableSetOf<Call>()
+	private var closed = false
+	init { dispatcher.maxRequests = 16; dispatcher.maxRequestsPerHost = 8 }
+	// This client is independent of MapLibre's global HTTP client and of the
+	// bootstrap channel. Never add a logging interceptor or shared cookie jar.
+	private val client = OkHttpClient.Builder()
+		.dispatcher(dispatcher)
+		.followRedirects(false)
+		.followSslRedirects(false)
+		.retryOnConnectionFailure(false)
+		.cache(null)
+		.connectTimeout(10, TimeUnit.SECONDS)
+		.callTimeout(30, TimeUnit.SECONDS)
+		.addNetworkInterceptor { chain ->
+			val guard = chain.request().tag(StartGuard::class.java)
+			if (guard == null || !guard.allowed()) throw IOException("Native admission is no longer valid")
+			// This is a nonblocking liveness/expiry check, never a JavaScript wait.
+			chain.proceed(chain.request())
+		}
+		.build()
+
+	override fun start(request: AdmissionHttpRequest, callback: (AdmissionHttpResponse?) -> Unit): AdmissionCancellation {
+		if (!request.mayStart()) { callback(null); return AdmissionCancellation {} }
+		val builder = Request.Builder().url(request.url).get().tag(StartGuard::class.java, StartGuard(request.mayStart))
+		for ((name, value) in request.headers) builder.header(name, value)
+		val call = client.newCall(builder.build())
+		val accepted = synchronized(lock) {
+			if (closed || calls.size >= AdmissionLimits.CONTEXTS * AdmissionLimits.QUEUE) false
+			else { calls.add(call); true }
+		}
+		if (!accepted) { callback(null); return AdmissionCancellation {} }
+		fun complete(response: AdmissionHttpResponse?) {
+			synchronized(lock) { calls.remove(call) }
+			callback(response)
+		}
+		try {
+			call.enqueue(object : Callback {
+				override fun onFailure(call: Call, e: IOException) { complete(null) }
+				override fun onResponse(call: Call, response: Response) {
+					val result = try {
+						response.use {
+							val body = it.body
+							val bytes = body?.byteStream()?.use { stream ->
+								readNativeDocumentBody(stream, request.maximumBytes, body.contentLength(), request.mayStart)
+							} ?: byteArrayOf()
+							// Forward only metadata consumed by MapLibre and Location
+							// for our own redirect validation, never raw headers.
+							val headers = linkedMapOf<String, String>()
+							for (name in listOf("etag", "last-modified", "cache-control", "expires", "retry-after", "x-rate-limit-reset", "location")) {
+								it.header(name)?.let { value -> headers[name] = value }
+							}
+							AdmissionHttpResponse(it.code, headers, bytes)
+						}
+					} catch (_: Exception) { null }
+					complete(result)
+				}
+			})
+		} catch (_: Exception) { call.cancel(); complete(null) }
+		// Logical cancellation does not release the physical dispatcher slot.
+		// Its terminal callback does, so rapid retire/register cannot grow it.
+		return AdmissionCancellation { call.cancel() }
+	}
+
+	fun close() {
+		val pending = synchronized(lock) { closed = true; calls.toList() }
+		for (call in pending) call.cancel()
+		client.connectionPool.evictAll()
+		dispatcher.executorService.shutdown()
+	}
+}