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

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

@@ -0,0 +1,56 @@
+package dev.tileflow.reactnative
+
+import org.maplibre.android.ModuleProvider
+
+// Install/remove run on the module's serial scheduler. Network threads only
+// read owns(). Never restore a provider after another owner has replaced it.
+internal class AdmissionProviderLease(
+	private val read: () -> ModuleProvider,
+	private val write: (ModuleProvider) -> Unit,
+) {
+	val previous: ModuleProvider = read()
+	@Volatile private var candidate: ModuleProvider? = null
+	@Volatile private var removal: Map<String, Boolean>? = null
+	private var attempted = false
+
+	fun install(provider: ModuleProvider) {
+		if (attempted || removal != null || provider === previous) invalid()
+		attempted = true
+		try {
+			if (read() !== previous) invalid()
+			candidate = provider
+			write(provider)
+			if (read() !== provider) invalid()
+		} catch (_: Exception) {
+			// A setter may mutate successfully before throwing. Roll back only
+			// when identity still proves that the candidate is ours.
+			try { remove() } catch (_: Exception) { /* No acknowledgement on failed restoration. */ }
+			invalid()
+		}
+	}
+
+	fun owns(): Boolean = try {
+		val installed = candidate
+		installed != null && removal == null && read() === installed
+	} catch (_: Exception) { false }
+
+	fun remove(): Map<String, Boolean> {
+		removal?.let { return it }
+		val current = try { read() } catch (_: Exception) { invalid() }
+		val installed = candidate
+		if (current !== installed) {
+			val restored = current === previous
+			return mapOf("removed" to restored, "ownershipLost" to !restored).also { removal = it }
+		}
+		try { write(previous) } catch (_: Exception) {
+			// Verify the postcondition even when the setter throws afterwards.
+			if (try { read() !== previous } catch (_: Exception) { true }) invalid()
+		}
+		val after = try { read() } catch (_: Exception) { invalid() }
+		if (after === installed) invalid()
+		val restored = after === previous
+		return mapOf("removed" to restored, "ownershipLost" to !restored).also { removal = it }
+	}
+
+	private fun invalid(): Nothing = throw IllegalArgumentException("Native provider ownership is unavailable")
+}

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

@@ -0,0 +1,85 @@
+package dev.tileflow.reactnative
+
+internal fun interface AdmissionCancellation { fun cancel() }
+
+internal interface AdmissionScheduler {
+	fun nowMs(): Long
+	fun dispatch(action: () -> Unit)
+	fun after(delayMs: Long, action: () -> Unit): AdmissionCancellation
+}
+
+internal interface AdmissionNetwork {
+	fun start(request: AdmissionHttpRequest, callback: (AdmissionHttpResponse?) -> Unit): AdmissionCancellation
+}
+
+// Deliberately not data classes: generated string representations must not
+// expose headers, authority, response bodies or URLs to diagnostic tooling.
+internal class AdmissionHttpRequest(
+	val url: String,
+	val headers: Map<String, String>,
+	val maximumBytes: Int,
+	val mayStart: () -> Boolean,
+) {
+	constructor(url: String, headers: Map<String, String>, mayStart: () -> Boolean) :
+		this(url, headers, AdmissionLimits.RESPONSE_BYTES.toInt(), mayStart)
+	init { require(maximumBytes in 1..AdmissionLimits.RESPONSE_BYTES.toInt()) { "Invalid native resource bound" } }
+	override fun toString() = "AdmissionHttpRequest(redacted)"
+}
+
+internal class AdmissionHttpResponse(
+	val code: Int,
+	val headers: Map<String, String>,
+	val body: ByteArray,
+	val url: String? = null,
+) {
+	override fun toString() = "AdmissionHttpResponse(redacted)"
+}
+
+internal class AdmissionResource(
+	val url: String,
+	val scope: String,
+	val tilesetId: String?,
+	val template: String? = null,
+	fontStacks: List<String>? = null,
+) {
+	val fontStacks: List<String>? = fontStacks?.let { java.util.Collections.unmodifiableList(it.toList()) }
+	override fun toString() = "AdmissionResource(redacted)"
+}
+
+internal class AdmissionAuthority(
+	val grant: String,
+	val mapId: String,
+	val resourceOrigins: List<String>,
+	val resourceScopes: List<String>,
+	val tilesetIds: List<String>,
+) {
+	fun allows(resource: AdmissionResource, expectedMap: String): Boolean =
+		mapId == expectedMap && resourceOrigins.contains(AdmissionUrl.origin(resource.url)) &&
+		resourceScopes.contains(resource.scope) &&
+		(resource.scope != "style" || AdmissionUrl.styleMatchesMap(resource.url, expectedMap)) &&
+		(resource.tilesetId == null || tilesetIds.contains(resource.tilesetId))
+	override fun toString() = "AdmissionAuthority(redacted)"
+}
+
+internal sealed class AdmissionResult(val ticket: String) {
+	class Grant(ticket: String, val validForMs: Long, val authority: AdmissionAuthority) : AdmissionResult(ticket)
+	class Delegate(ticket: String) : AdmissionResult(ticket)
+	class Reject(ticket: String) : AdmissionResult(ticket)
+	override fun toString() = "AdmissionResult(redacted)"
+}
+
+internal object AdmissionLimits {
+	const val CONTEXTS = 16
+	const val RESOURCES = 128
+	const val QUEUE = 128
+	const val BATCH = 8
+	const val URL = 2048
+	const val BRIDGE_BYTES = 524288
+	const val GRANT = 24576
+	const val WAIT_MS = 30000L
+	const val SAFETY_MS = 1000L
+	const val MAX_VALID_MS = 900000L
+	const val REDIRECTS = 3
+	const val RESPONSE_BYTES = 8388608L
+	const val GRANT_HEADER = "X-Tileflow-Native-Grant"
+}

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

@@ -0,0 +1,100 @@
+package dev.tileflow.reactnative
+
+import java.net.URI
+import java.util.Locale
+import okhttp3.HttpUrl.Companion.toHttpUrlOrNull
+
+internal object AdmissionUrl {
+	private const val PARAMETER = "__tf_native_context"
+	private val token = Regex("[A-Za-z0-9_.-]{1,96}")
+	private val compact = Regex("[A-Za-z0-9._:-]{1,255}")
+	private val scopes = setOf("style", "tilejson", "tile", "sprite", "glyph", "font")
+	private val percent = Regex("%([0-9a-fA-F]{2})")
+	private val nativeStyle = Regex("/maps/(map_[A-Za-z0-9_-]{16})/native/v([1-9][0-9]{0,15})/([A-Za-z][A-Za-z0-9_-]{0,63})\\.json")
+	private val reservedStyle = Regex("^/maps/[^/?#]+/native(?:[/?#]|$)")
+	private fun decoded(value: String) = percent.replace(value) { it.groupValues[1].toInt(16).toChar().toString() }
+	fun validToken(value: String) = token.matches(value) && !value.startsWith("tf_")
+	fun reserved(value: String): Boolean {
+		val query = value.indexOf('?')
+		if (query < 0) return false
+		return value.substring(query + 1).split('&').any {
+			decoded(it.substringBefore('=')).lowercase(Locale.ROOT).startsWith("__tf_native")
+		}
+	}
+	fun origin(value: String): String {
+		val parsed = value.toHttpUrlOrNull() ?: invalid()
+		val port = if (parsed.port == if (parsed.scheme == "https") 443 else 80) "" else ":${parsed.port}"
+		val host = if (parsed.host.contains(':')) "[${parsed.host}]" else parsed.host
+		return "${parsed.scheme}://$host$port"
+	}
+	fun styleMatchesMap(value: String, mapId: String): Boolean {
+		return try {
+			val path = value.substring(origin(value).length)
+			if (!reservedStyle.containsMatchIn(decoded(path))) true
+			else {
+				val match = nativeStyle.matchEntire(path)
+				val version = match?.groupValues?.get(2)?.toLongOrNull()
+				match != null && match.groupValues[1] == mapId && version != null && version in 1L..9007199254740991L
+			}
+		} catch (_: Exception) { false }
+	}
+	fun clean(value: String): String = clean(value, null)
+
+	/** Development HTTP is limited to credential-free document reads. */
+	fun document(value: String, developmentOrigin: String?): String {
+		if (developmentOrigin != null) {
+			if (!developmentOrigin.startsWith("http://") || origin("$developmentOrigin/") != developmentOrigin) invalid()
+			clean("$developmentOrigin/", developmentOrigin)
+		}
+		return clean(value, developmentOrigin)
+	}
+
+	private fun clean(value: String, developmentOrigin: String?): String {
+		if (value.length > AdmissionLimits.URL || value.any { it.code !in 33..126 || it == '\\' || it == '#' } || reserved(value)) invalid()
+		val parsed = value.toHttpUrlOrNull() ?: invalid()
+		if ((parsed.scheme != "https" && (parsed.scheme != "http" || origin(value) != developmentOrigin)) ||
+			parsed.username.isNotEmpty() || parsed.password.isNotEmpty() || parsed.toString() != value) invalid()
+		val text = decoded(value).lowercase(Locale.ROOT)
+		if (text.contains("tf_native_") || text.contains("tf_public_")) invalid()
+		return value
+	}
+	fun resource(value: AdmissionResource): AdmissionResource {
+		clean(value.url)
+		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()
+		}
+		return value
+	}
+	class Discriminated(val context: String, val url: String)
+	fun strip(value: String): Discriminated {
+		if (value.length > AdmissionLimits.URL || value.contains('#') || value.contains('\\')) invalid()
+		val queryAt = value.indexOf('?')
+		if (queryAt < 0) invalid()
+		val parts = value.substring(queryAt + 1).split('&')
+		val matches = parts.withIndex().filter {
+			decoded(it.value.substringBefore('=')).lowercase(Locale.ROOT).startsWith("__tf_native")
+		}
+		if (matches.size != 1) invalid()
+		val selected = matches.single()
+		if (!selected.value.startsWith("$PARAMETER=")) invalid()
+		val context = selected.value.substring(PARAMETER.length + 1)
+		if (!validToken(context)) invalid()
+		val remaining = parts.filterIndexed { index, _ -> index != selected.index }
+		val url = value.substring(0, queryAt) + if (remaining.isEmpty()) "" else "?" + remaining.joinToString("&")
+		return Discriminated(context, clean(url))
+	}
+	fun redirect(previous: String, location: String, context: String): String {
+		if (location.length > AdmissionLimits.URL || location.any { it.code !in 33..126 } || location.contains('\\')) invalid()
+		val resolved = try { URI(previous).resolve(location).toString() } catch (_: Exception) { invalid() }
+		val clean = if (reserved(resolved)) {
+			val tagged = strip(resolved)
+			if (tagged.context != context) invalid()
+			tagged.url
+		} else clean(resolved)
+		if (origin(clean) != origin(previous)) invalid()
+		return clean
+	}
+	private fun invalid(): Nothing = throw IllegalArgumentException("Invalid native resource")
+}

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

@@ -0,0 +1,16 @@
+package dev.tileflow.reactnative
+
+import android.os.Handler
+import android.os.Looper
+import android.os.SystemClock
+
+internal class HandlerAdmissionScheduler : AdmissionScheduler {
+	private val handler = Handler(Looper.getMainLooper())
+	override fun nowMs(): Long = SystemClock.elapsedRealtime()
+	override fun dispatch(action: () -> Unit) { handler.post { action() } }
+	override fun after(delayMs: Long, action: () -> Unit): AdmissionCancellation {
+		val task = Runnable { action() }
+		handler.postDelayed(task, delayMs)
+		return AdmissionCancellation { handler.removeCallbacks(task) }
+	}
+}

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

@@ -0,0 +1,95 @@
+package dev.tileflow.reactnative
+
+import java.util.Locale
+
+internal class MobileConfigurationException : RuntimeException("Native application configuration is invalid.")
+
+/** The platform adapter must return only literal strings, never resolved resource aliases. */
+internal interface MobileConfigurationValues : AutoCloseable {
+	val size: Int
+	val applicationOwned: Boolean
+	fun literalString(index: Int): String?
+	override fun close()
+}
+
+/** Application data only. Never use this object as Map, session or transport identity. */
+internal class MobileConfiguration private constructor(val apiOrigin: String, val credential: String) {
+	override fun toString() = "MobileConfiguration"
+
+	companion object {
+		private val originPattern = Regex("[Hh][Tt][Tt][Pp][Ss]://([A-Za-z0-9.-]+)(?::([1-9][0-9]{0,4}))?/?")
+		private val labelPattern = Regex("[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?")
+		private val octetPattern = Regex("(?:0|[1-9][0-9]{0,2})")
+		private fun invalid(): Nothing = throw MobileConfigurationException()
+
+		private fun origin(input: String): String {
+			if (input.isEmpty() || input.length > 2048) invalid()
+			val match = originPattern.matchEntire(input) ?: invalid()
+			val host = match.groupValues[1].lowercase(Locale.ROOT)
+			val labels = host.split('.')
+			if (host.length > 253 || labels.any { !labelPattern.matches(it) }) invalid()
+			if (labels.last().first() !in 'a'..'z') {
+				if (labels.size != 4 || labels.any { !octetPattern.matches(it) || it.toInt() > 255 }) invalid()
+			}
+			val port = match.groupValues[2].let { if (it.isEmpty()) 443 else it.toInt() }
+			if (port > 65535) invalid()
+			return "https://$host" + if (port == 443) "" else ":$port"
+		}
+
+		fun parse(input: Any?): MobileConfiguration {
+			try {
+				if (input !is List<*> || input.size != 2) invalid()
+				var apiOrigin: String? = null
+				var credential: String? = null
+				for (item in input) {
+					if (item !is String || item.length > 2080) invalid()
+					val separator = item.indexOf('=')
+					if (separator <= 0) invalid()
+					val value = item.substring(separator + 1)
+					when (item.substring(0, separator)) {
+						"apiOrigin" -> { if (apiOrigin != null) invalid(); apiOrigin = origin(value) }
+						"credential" -> {
+							if (credential != null || value.length != 58 || !value.startsWith("tf_public_") ||
+								value.substring(10).any { it !in '0'..'9' && it !in 'a'..'f' }) invalid()
+							credential = value
+						}
+						else -> invalid()
+					}
+				}
+				return MobileConfiguration(apiOrigin ?: invalid(), credential ?: invalid())
+			} catch (_: Exception) { invalid() }
+		}
+
+		fun load(values: MobileConfigurationValues): MobileConfiguration {
+			try {
+				try {
+					if (!values.applicationOwned || values.size != 2) invalid()
+					return parse(listOf(values.literalString(0), values.literalString(1)))
+				} finally { values.close() }
+			} catch (_: Exception) { invalid() }
+		}
+	}
+}
+
+/** Process-scoped immutable configuration, including failed reads. Contains no React context. */
+internal class MobileConfigurationCache {
+	private var phase = 0
+	private var configuration: MobileConfiguration? = null
+
+	@Synchronized fun read(source: () -> MobileConfiguration): MobileConfiguration {
+		if (phase == 2) return configuration ?: throw MobileConfigurationException()
+		if (phase != 0) { phase = 3; throw MobileConfigurationException() }
+		phase = 1
+		try {
+			val result = source()
+			if (phase != 1) throw MobileConfigurationException()
+			configuration = result
+			phase = 2
+			return result
+		} catch (_: Exception) {
+			configuration = null
+			phase = 3
+			throw MobileConfigurationException()
+		}
+	}
+}

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

@@ -0,0 +1,43 @@
+package dev.tileflow.reactnative
+
+import android.content.Context
+import android.content.res.Resources
+import android.util.TypedValue
+
+internal fun mobileConfigurationLiteral(value: TypedValue): String? {
+	if (value.type != TypedValue.TYPE_STRING || value.resourceId != 0) return null
+	val text = value.string as? String ?: return null
+	return if (text.length <= 2080) text else null
+}
+
+/** Only this named application array is accepted. There is no manifest or BuildConfig fallback. */
+internal fun readMobileConfigurationResources(context: Context): MobileConfiguration {
+	try {
+		val application = context.applicationContext
+		val resources = application.resources
+		val id = resources.getIdentifier("tileflow_mobile_configuration", "array", application.packageName)
+		if (id == 0 || resources.getResourcePackageName(id) != application.packageName ||
+			resources.getResourceTypeName(id) != "array") throw MobileConfigurationException()
+		// A complex array is a resource bag, not a scalar/reference. Reject a whole-array alias.
+		// Resources.getValue does not return complex bags; obtainTypedArray reads the bag below.
+		var scalar = false
+		try {
+			resources.getValue(id, TypedValue(), false)
+			scalar = true
+		} catch (_: Resources.NotFoundException) { /* Expected only for a complex bag. */ }
+		if (scalar) throw MobileConfigurationException()
+		val array = resources.obtainTypedArray(id)
+		return MobileConfiguration.load(object : MobileConfigurationValues {
+			override val size get() = array.length()
+			override val applicationOwned = true
+			override fun literalString(index: Int): String? {
+				val value = TypedValue()
+				return if (array.getValue(index, value)) mobileConfigurationLiteral(value) else null
+			}
+			override fun close() = array.recycle()
+		})
+	} catch (_: Exception) {
+		// Resource IDs, values, exception messages and configured origins are not diagnostics.
+		throw MobileConfigurationException()
+	}
+}

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

@@ -0,0 +1,101 @@
+package dev.tileflow.reactnative
+
+import java.io.ByteArrayOutputStream
+import java.io.IOException
+import java.io.InputStream
+import java.net.URI
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicBoolean
+import okhttp3.Authenticator
+import okhttp3.Call
+import okhttp3.Callback
+import okhttp3.CookieJar
+import okhttp3.Dispatcher
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.Response
+
+internal fun readNativeDocumentBody(source: InputStream, maximumBytes: Int, declared: Long, active: () -> Boolean): ByteArray {
+	if (maximumBytes !in 1..8388608 || declared > maximumBytes) throw IOException("Native document acquisition failed.")
+	val output = ByteArrayOutputStream(minOf(maximumBytes, 8192))
+	val buffer = ByteArray(8192)
+	while (true) {
+		if (!active()) throw IOException("Native document acquisition failed.")
+		val count = source.read(buffer, 0, minOf(buffer.size, maximumBytes - output.size() + 1))
+		if (count < 0) return output.toByteArray()
+		if (count == 0 || output.size() + count > maximumBytes) throw IOException("Native document acquisition failed.")
+		output.write(buffer, 0, count)
+	}
+}
+
+/** Initial manifests and unprotected preparation never use the MapLibre session or application credential. */
+internal class NativeDocumentOkHttpNetwork {
+	private class Guard(val active: () -> Boolean)
+	private val dispatcher = Dispatcher().apply { maxRequests = 4; maxRequestsPerHost = 4 }
+	private val client = OkHttpClient.Builder()
+		.dispatcher(dispatcher)
+		.cookieJar(CookieJar.NO_COOKIES)
+		.authenticator(Authenticator.NONE)
+		.proxyAuthenticator(Authenticator.NONE)
+		.cache(null)
+		.followRedirects(false)
+		.followSslRedirects(false)
+		.callTimeout(30, TimeUnit.SECONDS)
+		.addInterceptor { chain ->
+			if (chain.request().tag(Guard::class.java)?.active?.invoke() != true) throw IOException("Native document acquisition failed.")
+			chain.proceed(chain.request())
+		}
+		.build()
+
+	fun start(url: String, maximumBytes: Int, active: () -> Boolean, completion: (AdmissionHttpResponse?) -> Unit, developmentOrigin: String? = null): AdmissionCancellation {
+		val live = AtomicBoolean(true)
+		val completed = AtomicBoolean(false)
+		var redirects = 0
+		var call: Call? = null
+		val guard = { live.get() && active() }
+		fun finish(response: AdmissionHttpResponse?) {
+			if (completed.compareAndSet(false, true)) completion(response)
+		}
+		fun issue(target: String) {
+			if (!guard()) { finish(null); return }
+			try {
+				AdmissionUrl.document(target, developmentOrigin)
+				val next = client.newCall(Request.Builder().url(target).get().tag(Guard::class.java, Guard(guard)).build())
+				call = next
+				next.enqueue(object : Callback {
+					override fun onFailure(call: Call, error: IOException) { finish(null) }
+					override fun onResponse(call: Call, response: Response) {
+						try {
+							var redirect: String? = null
+							val received = response.use { reply ->
+								if (!guard()) throw IOException("Native document acquisition failed.")
+								if (reply.code in listOf(301, 302, 303, 307, 308)) {
+									if (++redirects > 3) throw IOException("Native document acquisition failed.")
+									val location = reply.header("Location") ?: throw IOException("Native document acquisition failed.")
+									if (location.length > 2048 || location.any { it.code !in 33..126 || it == '\\' }) throw IOException("Native document acquisition failed.")
+									redirect = AdmissionUrl.document(URI(target).resolve(location).toString(), developmentOrigin)
+									if (AdmissionUrl.origin(redirect!!) != AdmissionUrl.origin(target)) throw IOException("Native document acquisition failed.")
+									null
+								} else {
+									val body = reply.body ?: throw IOException("Native document acquisition failed.")
+									val bytes = readNativeDocumentBody(body.byteStream(), maximumBytes, body.contentLength(), guard)
+									AdmissionHttpResponse(reply.code, emptyMap(), bytes, target)
+								}
+							}
+							if (redirect != null) issue(redirect!!) else finish(received)
+						} catch (_: Exception) { finish(null) }
+					}
+				})
+				if (!guard()) next.cancel()
+			} catch (_: Exception) { finish(null) }
+		}
+		issue(url)
+		return AdmissionCancellation {
+			live.set(false)
+			call?.cancel()
+			// OkHttp's callback is the physical terminal acknowledgement.
+		}
+	}
+
+	fun close() { dispatcher.cancelAll() }
+}

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

@@ -0,0 +1,136 @@
+package dev.tileflow.reactnative
+
+import java.util.UUID
+import java.util.concurrent.atomic.AtomicBoolean
+
+internal class NativeDocumentScope(
+	val isActive: () -> Boolean,
+	val load: (String, (AdmissionHttpResponse?) -> Unit) -> AdmissionCancellation,
+	val context: String? = null,
+) {
+	override fun toString() = "NativeDocumentScope(redacted)"
+}
+internal class NativeDocumentHeader(val url: String, val status: Int) {
+	override fun toString() = "NativeDocumentHeader(redacted)"
+}
+internal class NativeDocumentChunk(val bytes: ByteArray, val last: Boolean) {
+	override fun toString() = "NativeDocumentChunk(redacted)"
+}
+
+/** All registry mutations run on the native serial scheduler, independently of JavaScript. */
+internal class NativeDocumentRegistry(
+	private val scheduler: AdmissionScheduler,
+	private val load: (String, Int, NativeDocumentScope?, String?, () -> Boolean, (AdmissionHttpResponse?) -> Unit) -> AdmissionCancellation,
+	private val identifier: () -> String = { UUID.randomUUID().toString() },
+) {
+	private class Work(val id: String, val url: String, val maximumBytes: Int, val scope: NativeDocumentScope?, val developmentOrigin: String?, val deadline: Long) {
+		val live = AtomicBoolean(true)
+		var nativeFinished = false
+		var cancellation: AdmissionCancellation? = null
+		var timer: AdmissionCancellation? = null
+		var body: ByteArray? = null
+		var offset = 0
+		var header: NativeDocumentHeader? = null
+		var requested = false
+		var waiter: ((NativeDocumentHeader?) -> Unit)? = null
+	}
+	private val work = linkedMapOf<String, Work>()
+	@Volatile private var foreground = true
+	@Volatile private var closed = false
+
+	fun open(url: String, maximumBytes: Int, scope: NativeDocumentScope?, developmentOrigin: String? = null): String {
+		if (scope != null && developmentOrigin != null) invalid()
+		AdmissionUrl.document(url, developmentOrigin)
+		if (closed || !foreground || work.size >= 16 || maximumBytes !in 1..8388608 || (scope != null && !scope.isActive())) invalid()
+		val id = identifier()
+		if (!AdmissionUrl.validToken(id) || work.containsKey(id)) invalid()
+		val item = Work(id, url, maximumBytes, scope, developmentOrigin, scheduler.nowMs() + 30000)
+		work[id] = item
+		item.timer = scheduler.after(30000) { retireQuietly(id) }
+		try {
+			val cancellation = load(url, maximumBytes, scope, developmentOrigin, { active(item) }) { response ->
+				scheduler.dispatch { received(item, response) }
+			}
+			item.cancellation = cancellation
+			if (!item.live.get()) cancellation.cancel()
+		} catch (_: Exception) {
+			item.nativeFinished = true
+			retireQuietly(id)
+			invalid()
+		}
+		return id
+	}
+
+	fun response(id: String, callback: (NativeDocumentHeader?) -> Unit) {
+		val item = work[id]
+		if (item == null || !active(item) || item.requested) { callback(null); return }
+		item.requested = true
+		if (item.header != null) callback(item.header)
+		else item.waiter = callback
+	}
+
+	fun chunk(id: String, maximumBytes: Int): NativeDocumentChunk {
+		val item = work[id] ?: invalid()
+		if (!active(item) || !item.requested || maximumBytes !in 1..65536) { retireQuietly(id); invalid() }
+		val bytes = item.body ?: invalid()
+		val end = minOf(bytes.size, item.offset + maximumBytes)
+		val value = bytes.copyOfRange(item.offset, end)
+		item.offset = end
+		val last = end == bytes.size
+		if (last) cancel(id)
+		return NativeDocumentChunk(value, last)
+	}
+
+	fun cancel(id: String) {
+		if (!AdmissionUrl.validToken(id)) invalid()
+		val item = work[id] ?: return
+		item.live.set(false)
+		item.timer?.cancel(); item.timer = null
+		val waiter = item.waiter; item.waiter = null
+		item.body?.fill(0); item.body = null; item.header = null
+		try {
+			if (!item.nativeFinished) item.cancellation?.cancel()
+			item.cancellation = null
+		} finally {
+			if (item.nativeFinished) work.remove(id)
+			waiter?.invoke(null)
+		}
+	}
+
+	fun retireContext(context: String) {
+		for (item in work.values.toList()) if (item.scope?.context == context) retireQuietly(item.id)
+	}
+	fun lifecycle(active: Boolean) {
+		foreground = active
+		if (!active) for (id in work.keys.toList()) retireQuietly(id)
+	}
+	fun close() {
+		closed = true
+		for (id in work.keys.toList()) retireQuietly(id)
+	}
+	private fun retireQuietly(id: String) {
+		try { cancel(id) } catch (_: Exception) { /* Logical retirement precedes retryable native cleanup. */ }
+	}
+
+	private fun active(item: Work): Boolean = try {
+		item.live.get() && !closed && foreground && scheduler.nowMs() < item.deadline && (item.scope?.isActive() != false)
+	} catch (_: Exception) { false }
+
+	private fun received(item: Work, response: AdmissionHttpResponse?) {
+		if (item.nativeFinished) return
+		item.nativeFinished = true
+		if (!active(item) || response == null || response.code !in 100..599 || response.body.size > item.maximumBytes) {
+			response?.body?.fill(0); retireQuietly(item.id); return
+		}
+		val finalUrl = response.url ?: item.url
+		try {
+			AdmissionUrl.document(finalUrl, item.developmentOrigin)
+			if (AdmissionUrl.origin(finalUrl) != AdmissionUrl.origin(item.url)) invalid()
+		} catch (_: Exception) { response.body.fill(0); retireQuietly(item.id); return }
+		item.body = response.body
+		item.header = NativeDocumentHeader(finalUrl, response.code)
+		val waiter = item.waiter; item.waiter = null
+		waiter?.invoke(item.header)
+	}
+	private fun invalid(): Nothing = throw IllegalArgumentException("Native document acquisition failed.")
+}