ruby_everywhere 0.3.0 → 0.4.0

data/support/mobile/android/app/src/main/java/com/rubyeverywhere/shell/EverywhereConfig.kt

@@ -0,0 +1,409 @@
+package com.rubyeverywhere.shell
+
+import android.content.Context
+import android.content.SharedPreferences
+import android.content.res.Configuration
+import android.graphics.Color
+import androidx.annotation.ColorInt
+import androidx.core.content.edit
+import androidx.core.net.toUri
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.booleanOrNull
+import kotlinx.serialization.json.buildJsonObject
+import kotlinx.serialization.json.contentOrNull
+import kotlinx.serialization.json.doubleOrNull
+import kotlinx.serialization.json.jsonArray
+import kotlinx.serialization.json.jsonObject
+import kotlinx.serialization.json.jsonPrimitive
+import kotlinx.serialization.json.put
+
+/**
+ * A colour that adapts to light/dark mode. Decodes either a single hex string
+ * (used for both appearances) or a `{"light": "#RRGGBB", "dark": "#RRGGBB"}`
+ * object, matching iOS's ThemedColor exactly — the same everywhere.json is
+ * stamped for both shells.
+ *
+ * Note the shell rarely needs these: the theme reads the same two colours from
+ * res/values/colors.xml, which the builder stamps at the same time. They exist
+ * for the places a theme attribute can't reach, such as a Custom Tab's toolbar.
+ */
+class ThemedColor(private val light: String, private val dark: String?) {
+    @ColorInt
+    fun colorInt(context: Context): Int? {
+        val night = context.resources.configuration.uiMode and
+            Configuration.UI_MODE_NIGHT_MASK == Configuration.UI_MODE_NIGHT_YES
+        val hex = if (night) dark ?: light else light
+        return parseHex(hex)
+    }
+
+    companion object {
+        internal fun from(element: JsonElement?): ThemedColor? = when (element) {
+            null -> null
+            is JsonPrimitive -> element.contentOrNull?.let { ThemedColor(it, null) }
+            is JsonObject -> {
+                val light = element["light"]?.jsonPrimitive?.contentOrNull
+                val dark = element["dark"]?.jsonPrimitive?.contentOrNull
+                (light ?: dark)?.let { ThemedColor(it, dark ?: light) }
+            }
+            else -> null
+        }
+
+        /** Accepts `#RRGGBB` and `#RRGGBBAA` (leading `#` optional). */
+        @ColorInt
+        private fun parseHex(value: String): Int? {
+            val raw = value.trim().removePrefix("#")
+            if (raw.length != 6 && raw.length != 8) return null
+            val bits = raw.toLongOrNull(16) ?: return null
+            return if (raw.length == 8) {
+                // #RRGGBBAA on the wire, 0xAARRGGBB in Android.
+                val alpha = (bits and 0xFF).toInt()
+                Color.argb(alpha, ((bits shr 24) and 0xFF).toInt(), ((bits shr 16) and 0xFF).toInt(), ((bits shr 8) and 0xFF).toInt())
+            } else {
+                Color.rgb(((bits shr 16) and 0xFF).toInt(), ((bits shr 8) and 0xFF).toInt(), (bits and 0xFF).toInt())
+            }
+        }
+    }
+}
+
+/**
+ * Third-party sign-in (everywhere.yml `auth:`): which paths hand off to a
+ * Custom Tab instead of loading in the web view, and the custom scheme the
+ * callback comes back through. Absent when the app declares no `auth:` — a
+ * shell that diverts nothing.
+ */
+class AuthConfig(val oauthPaths: List<String>, val scheme: String) {
+    /**
+     * The patterns compiled once. They're regex sources, matched unanchored,
+     * exactly like the path-configuration `rules:` patterns they sit beside in
+     * everywhere.yml — and exactly like the gem matches them server-side, so
+     * both halves of the flow agree on what a provider path is.
+     */
+    private val expressions: List<Regex> = oauthPaths.mapNotNull {
+        runCatching { Regex(it) }.getOrNull()
+    }
+
+    /**
+     * Half a declaration is worse than none: without a scheme there's nothing
+     * for the callback to return through, and diverting a visit we can't
+     * finish would turn the sign-in button into a button that does nothing.
+     */
+    val isUsable: Boolean get() = scheme.isNotEmpty() && expressions.isNotEmpty()
+
+    fun matches(path: String): Boolean = expressions.any { it.containsMatchIn(path) }
+}
+
+/**
+ * The app's configuration, stamped into `assets/everywhere.json` by
+ * `every build`. The raw template ships a placeholder pointing at
+ * rubyeverywhere.com.
+ *
+ * Parsed from [JsonObject] rather than through `@Serializable` data classes on
+ * purpose: `tint_color` is either a string or an object, `permissions` may be
+ * absent entirely, and the gem adds keys (desktop `menu:`, `tray:`) that this
+ * shell has no business knowing about. Hand-reading tolerates all three
+ * without a custom serializer per field.
+ */
+class EverywhereConfig private constructor(
+    private val appContext: Context,
+    private val json: JsonObject
+) {
+    val name: String = json.string("name") ?: "RubyEverywhere"
+    val version: String? = json.string("version")
+    val entryPath: String? = json.string("entry_path")
+    val remoteInstances: Boolean = json["remote_instances"]?.jsonPrimitive?.booleanOrNull == true
+    val permissions: List<String> =
+        json["permissions"]?.jsonArray?.mapNotNull { it.jsonPrimitive.contentOrNull } ?: emptyList()
+    val universalLinkHosts: List<String> =
+        json["universal_link_hosts"]?.jsonArray?.mapNotNull { it.jsonPrimitive.contentOrNull } ?: emptyList()
+
+    val tintColor: ThemedColor? = ThemedColor.from(json["tint_color"])
+    val backgroundColor: ThemedColor? = ThemedColor.from(json["background_color"])
+
+    private val stampedRemoteUrl: String? = json.string("remote_url")
+
+    private val auth: AuthConfig? = json["auth"]?.jsonObject?.let { obj ->
+        AuthConfig(
+            oauthPaths = obj["oauth_paths"]?.jsonArray?.mapNotNull { it.jsonPrimitive.contentOrNull } ?: emptyList(),
+            scheme = obj.string("scheme") ?: ""
+        )
+    }
+
+    /**
+     * Whether each non-selected tab defers its initial visit until first
+     * selected (everywhere.yml `lazy_load_tabs`).
+     *
+     * Unlike iOS this defaults to `true` when absent, and the shell passes
+     * `true` to the controller regardless — see [MainActivity]. Five pooled
+     * NavigatorHosts loading eagerly means five cold-boot WebViews and five
+     * start-location fetches at launch, including the hidden auth-gated ones.
+     * The value is still read so `lazy_load_tabs: false` is at least visible
+     * in the config, but Android cannot honour it.
+     */
+    val lazyLoadTabs: Boolean = json["lazy_load_tabs"]?.jsonPrimitive?.booleanOrNull ?: true
+
+    /** Minimum on-screen time for an app-provided splash, in milliseconds. */
+    val splashMinimumDisplay: Long =
+        ((json["splash_min_seconds"]?.jsonPrimitive?.doubleOrNull ?: 1.0) * 1000).toLong()
+
+    val userAgentPrefix: String =
+        version?.let { "RubyEverywhere/$it (android)" } ?: "RubyEverywhere (android)"
+
+    /**
+     * User-Agent for native HTTP requests ([everywhereFetch]): the shell prefix
+     * plus the Hotwire Native marker, so the gem's native_app?/native_platform/
+     * native_version helpers see native-screen requests exactly like web-view
+     * requests. The framework appends the marker itself for the WebView; a
+     * hand-built request has to say it.
+     */
+    val nativeUserAgent: String
+        get() = "$userAgentPrefix Hotwire Native Android"
+
+    /**
+     * Whether everywhere.yml declares this permission. Undeclared permissions
+     * must never reach the system APIs: Android only merges a
+     * `<uses-permission>` for declared ones, and requesting a permission the
+     * manifest doesn't hold fails silently — a denial the user never saw and
+     * can never undo.
+     */
+    fun declaresPermission(name: String): Boolean = permissions.contains(name)
+
+    // MARK: Roots
+
+    /**
+     * The root URL of the deployed app. A picked instance outranks the dev
+     * override on purpose: it's the more recent, in-app expression of intent,
+     * and dev-testing the picker flow only works if picking takes effect.
+     * `Everywhere.instance.clear()` falls back to the dev/stamped root.
+     */
+    val rootUrl: String
+        get() = instanceUrl ?: devUrl ?: stampedRemoteUrl
+            ?: error("remote.url not set in everywhere.yml — the Android shell is remote-mode only")
+
+    /** The first location the navigator visits: rootUrl joined with entry_path. */
+    val startUrl: String
+        get() {
+            val path = entryPath
+            return if (path.isNullOrEmpty() || path == "/") rootUrl else url(forPath = path)
+        }
+
+    /**
+     * The server half of the path configuration (rules + settings.tabs),
+     * generated from everywhere.yml by the gem's MobileConfigEndpoint — so tab
+     * changes deploy with the web app, no Play Store release.
+     */
+    val pathConfigurationUrl: String
+        get() = url(forPath = "/everywhere/android_v1.json")
+
+    /** rootUrl joined with an absolute-style path (leading `/` optional). */
+    fun url(forPath: String): String {
+        val base = rootUrl.trimEnd('/')
+        val suffix = if (forPath.startsWith("/")) forPath else "/$forPath"
+        return base + suffix
+    }
+
+    /**
+     * The path (plus query) of an absolute URL, for re-routing a deep link
+     * through the app's own effective root (dev override / picked instance).
+     */
+    fun pathAndQuery(url: String): String {
+        val uri = url.toUri()
+        val path = uri.path?.takeIf { it.isNotEmpty() } ?: "/"
+        val query = uri.query
+        return if (query.isNullOrEmpty()) path else "$path?$query"
+    }
+
+    // MARK: Dev-server override
+
+    /**
+     * The dev-server URL, in debug builds only.
+     *
+     * Android has no `SIMCTL_CHILD_*`, so there is nothing to read from the
+     * launching environment: `every dev --android` stamps
+     * `src/debug/assets/dev-url.txt` and rebuilds, which it has to do anyway.
+     * Baked into the APK means it also survives a relaunch from the launcher,
+     * which is the case iOS needs UserDefaults to paper over. Release builds
+     * never look for the file, and the debug source set never ships in one.
+     */
+    private val devUrl: String? by lazy {
+        if (!BuildConfig.DEBUG) return@lazy null
+        runCatching {
+            appContext.assets.open(DEV_URL_ASSET).bufferedReader().use { it.readText() }.trim()
+        }.getOrNull()?.takeIf { it.isNotEmpty() }
+    }
+
+    // MARK: Instance override (multi-instance apps)
+
+    private val prefs: SharedPreferences
+        get() = appContext.getSharedPreferences(PREFS, Context.MODE_PRIVATE)
+
+    /**
+     * The persisted instance override. Read per-access, never cached:
+     * setInstance changes it mid-run and everything derived from rootUrl (start
+     * URL, path-configuration URL) must follow immediately.
+     */
+    val instanceUrl: String?
+        get() = if (!remoteInstances) null else prefs.getString(INSTANCE_KEY, null)
+
+    /**
+     * Persist (null clears) the instance override. Only absolute http(s) roots
+     * are accepted — the page posts arbitrary strings at the control channel,
+     * and re-rooting the whole app is the one place that must not take them on
+     * faith. (http stays allowed for LAN-hosted instances.)
+     */
+    fun setInstanceUrl(url: String?): Boolean {
+        if (url == null) {
+            prefs.edit { remove(INSTANCE_KEY) }
+            return true
+        }
+        val uri = url.toUri()
+        val scheme = uri.scheme?.lowercase()
+        if (scheme != "https" && scheme != "http") return false
+        if (uri.host.isNullOrEmpty()) return false
+
+        prefs.edit { putString(INSTANCE_KEY, url) }
+        return true
+    }
+
+    // MARK: Third-party sign-in
+
+    val authScheme: String? get() = auth?.takeIf { it.isUsable }?.scheme
+
+    /**
+     * The path a visit should hand to the auth flow, or null to let it load in
+     * the web view. Two shapes: a provider path the app linked to directly, and
+     * the gem's /everywhere/auth/native page, which is where the server sends
+     * visits the shell couldn't intercept (a `data-turbo="false"` link, or the
+     * POST OmniAuth 2 requires) — its `to` names the real provider path.
+     */
+    fun authTarget(url: String): String? {
+        val config = auth?.takeIf { it.isUsable } ?: return null
+        val uri = url.toUri()
+        val path = uri.path ?: return null
+
+        if (path == "/everywhere/auth/native") {
+            val to = uri.getQueryParameter("to")
+            return to?.takeIf { it.startsWith("/") && !it.startsWith("//") }
+        }
+        if (!config.matches(path)) return null
+
+        return pathAndQuery(url)
+    }
+
+    /**
+     * The first page of the auth flow: the gem's start endpoint, which marks
+     * the browser's cookie jar as ours and continues into `to`. `returnTo` is
+     * where the user was, used only if the app's own sign-in doesn't say where
+     * to land.
+     */
+    fun authStartUrl(to: String, returnTo: String?): String {
+        val builder = url(forPath = "/everywhere/auth/start").toUri().buildUpon()
+        builder.appendQueryParameter("to", to)
+        returnTo?.let { builder.appendQueryParameter("return_to", it) }
+        return builder.build().toString()
+    }
+
+    /**
+     * Where the token gets spent. Visited in the web view — that's the whole
+     * point, the response's cookies have to land in the web view's jar — and it
+     * redirects on to wherever the app's sign-in wanted the user.
+     */
+    fun authHandoffUrl(token: String): String =
+        url(forPath = "/everywhere/auth/handoff").toUri().buildUpon()
+            .appendQueryParameter("token", token)
+            .build()
+            .toString()
+
+    // MARK: Deep links
+
+    /**
+     * Whether an incoming link belongs to this app: https, and its host is the
+     * app's own root host or one of the verified domains (everywhere.yml
+     * `deep_linking`, injected as `universal_link_hosts`). A link to some other
+     * site is left to the browser.
+     *
+     * The manifest's `autoVerify` intent filter has already narrowed this on
+     * the way in, but the filter is stamped from the same list and an
+     * Intent can be sent by any app on the device, so the check is repeated
+     * here rather than trusted.
+     */
+    fun handlesUniversalLink(url: String): Boolean {
+        val uri = url.toUri()
+        if (uri.scheme?.lowercase() != "https") return false
+        val host = uri.host?.lowercase() ?: return false
+        if (rootUrl.toUri().host?.lowercase() == host) return true
+        return universalLinkHosts.any { it.lowercase() == host }
+    }
+
+    // MARK: Page-visible config
+
+    /**
+     * A compact JSON object injected into every page as
+     * `window.__EVERYWHERE_CONFIG__`. Built per web view (not once at launch):
+     * `instance` must reflect the override as it stands when the post-reset web
+     * views are created.
+     */
+    val webConfigJson: String
+        get() = buildJsonObject {
+            put("name", name)
+            put("os", "android")
+            version?.let { put("version", it) }
+            if (remoteInstances) {
+                put("instances", true)
+                instanceUrl?.let { put("instance", it) }
+            }
+        }.toString()
+
+    companion object {
+        private const val ASSET = "everywhere.json"
+        private const val DEV_URL_ASSET = "dev-url.txt"
+        private const val PREFS = "everywhere"
+        private const val INSTANCE_KEY = "instance_url"
+
+        private val parser = Json { ignoreUnknownKeys = true; isLenient = true }
+
+        @Volatile
+        private var instance: EverywhereConfig? = null
+
+        /**
+         * Parsed once, from [EverywhereApplication.onCreate], before anything
+         * can ask for [shared].
+         */
+        fun initialize(context: Context) {
+            instance = load(context.applicationContext)
+        }
+
+        val shared: EverywhereConfig
+            get() = instance ?: error(
+                "EverywhereConfig was read before EverywhereApplication.onCreate ran."
+            )
+
+        private fun load(appContext: Context): EverywhereConfig {
+            val text = try {
+                appContext.assets.open(ASSET).bufferedReader().use { it.readText() }
+            } catch (e: Exception) {
+                // Deliberately fatal, like iOS. A shell with no config has no
+                // URL to load; failing at launch with the reason beats a blank
+                // web view and a support ticket.
+                throw IllegalStateException(
+                    "$ASSET is missing from the app's assets — stamp this shell with `every build` before running it.",
+                    e
+                )
+            }
+            val json = try {
+                parser.parseToJsonElement(text).jsonObject
+            } catch (e: Exception) {
+                throw IllegalStateException(
+                    "$ASSET in the app's assets is invalid — re-stamp this shell with `every build`.",
+                    e
+                )
+            }
+            return EverywhereConfig(appContext, json)
+        }
+
+        private fun JsonObject.string(key: String): String? =
+            this[key]?.jsonPrimitive?.contentOrNull?.takeIf { it.isNotEmpty() }
+    }
+}

data/support/mobile/android/app/src/main/java/com/rubyeverywhere/shell/EverywhereEvents.kt

@@ -0,0 +1,68 @@
+package com.rubyeverywhere.shell
+
+import kotlinx.coroutines.flow.MutableSharedFlow
+
+/**
+ * Page → shell control messages, in one place. The Android answer to iOS's
+ * NotificationCenter names (`.everywhereReloadConfig` and friends).
+ *
+ * The producer is [com.rubyeverywhere.shell.bridge.WebControlChannel], which
+ * receives `window.everywhereControl.postMessage({action: …})` from the page;
+ * the consumer is [MainActivity], which collects on the main dispatcher and is
+ * the only thing allowed to act on these. Keeping the channel decoupled from
+ * the Activity matters for the same reason it does on iOS: the web view (and
+ * the channel bound to it) is created by the Application before any Activity
+ * exists, and survives the Activity being recreated for a tab-path change.
+ *
+ * Buffered and non-replaying, deliberately:
+ *   * `extraBufferCapacity` with DROP_OLDEST semantics via [tryEmit] means the
+ *     channel is never suspended by a slow collector — it is called from the
+ *     WebView's message thread, which must not block.
+ *   * `replay = 0` because every event is an imperative command. Replaying
+ *     "reset the app" to a collector that starts later would re-run it, and
+ *     MainActivity re-collects every time it is recreated.
+ */
+object EverywhereEvents {
+
+    sealed interface Event {
+        /** `{action: "reloadConfig"}` — refetch the auth-aware path configuration. */
+        data object ReloadConfig : Event
+
+        /** `{action: "reset", to: "/path"}` — full app reset, then land on `to`. */
+        data class ResetApp(val to: String?) : Event
+
+        /** `{action: "setTabBadge", path: "/x", count: 3}` — 0 clears. */
+        data class SetTabBadge(val path: String, val count: Int) : Event
+
+        /** `{action: "setBadge", count: 3}` — the launcher icon badge; 0 clears. */
+        data class SetBadge(val count: Int) : Event
+
+        /** `{action: "setInstance", url: "https://…", to: "/path"?}` */
+        data class SetInstance(val url: String, val to: String?) : Event
+
+        /** `{action: "clearInstance", to: "/path"?}` */
+        data class ClearInstance(val to: String?) : Event
+
+        /** `everywhereVisit(path)` from native extension code. */
+        data class NativeVisit(val path: String) : Event
+
+        /** `{action: "authFlow", to: "/auth/github"}` */
+        data class AuthFlow(val to: String) : Event
+    }
+
+    /**
+     * Mutable on purpose, and public. The control channel emits from a
+     * coroutine so it can await a slow collector rather than drop; the route
+     * decision handlers, which run on a framework callback that cannot suspend,
+     * use [emit] instead. Both need to write, so there is nothing to hide
+     * behind an `asSharedFlow()`.
+     */
+    val events = MutableSharedFlow<Event>(replay = 0, extraBufferCapacity = 32)
+
+    /**
+     * Non-suspending, callable from any thread. Returns false only if the
+     * buffer is full — 32 pending control messages means nothing is collecting,
+     * in which case dropping is the right answer, not blocking the caller.
+     */
+    fun emit(event: Event): Boolean = events.tryEmit(event)
+}

data/support/mobile/android/app/src/main/java/com/rubyeverywhere/shell/EverywhereHost.kt

@@ -0,0 +1,101 @@
+package com.rubyeverywhere.shell
+
+import android.webkit.CookieManager
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import java.net.HttpURLConnection
+import java.net.URL
+
+// Note for whoever edits the comments in this file: Kotlin block comments NEST,
+// unlike Java's, so a "slash star" sequence inside a KDoc block — which is what
+// a glob like the one naming this app's Kotlin sources would be — opens a nested
+// comment and swallows the rest of the file. It fails as "Unclosed comment" at
+// the last line, naming nothing. Globs belong in line comments only.
+
+/**
+ * The two things app-authored native code in the app repo's native/android
+ * directory needs from the shell, and the Android half of iOS's
+ * EverywhereHost.swift. Deliberately top-level functions with the same names as
+ * the Swift ones, so the two platforms' extension code reads the same.
+ *
+ * There is no `everywhereHost` counterpart: iOS needs one to lift a SwiftUI
+ * view into a UIViewController, while a Hotwire Android destination is already
+ * a Fragment.
+ */
+
+/**
+ * Route the app to a path (or absolute URL) from native extension code — the
+ * native counterpart of `Everywhere.visit()`. Relative paths resolve against
+ * the effective root (dev override / picked instance included); web routes load
+ * in the web view, native-screen routes push their screen.
+ *
+ * Non-suspending and safe from any thread: it hands the path to
+ * [EverywhereEvents], which [MainActivity] collects on the main dispatcher.
+ */
+fun everywhereVisit(path: String) {
+    EverywhereEvents.emit(EverywhereEvents.Event.NativeVisit(path))
+}
+
+/**
+ * GET a path (or absolute URL) from the app's own server and return the body —
+ * for native screens that render the app's data instead of its HTML. The
+ * counterpart of iOS's `everywhereURLSession`, narrowed to the one call that
+ * needs shell knowledge to get right:
+ *
+ *   * Relative paths resolve against the effective root, so a native screen
+ *     follows a dev override or a picked instance like every web visit does.
+ *   * The session cookie is copied from the WebView's store, so the request
+ *     rides the signed-in session. Android's CookieManager is one process-wide
+ *     store, so this is a synchronous read (on iOS it is a whole round trip).
+ *   * The User-Agent carries the Hotwire Native marker, so the gem's
+ *     `native_app?` / `native_platform` / `native_version` helpers answer for
+ *     native-screen requests exactly as they do for web-view requests.
+ *
+ * Suspending, and switched to Dispatchers.IO: a blocking call on the main
+ * thread would raise NetworkOnMainThreadException. Throws on a transport
+ * failure or a non-2xx status — a native screen has to render *something* for a
+ * signed-out or erroring server, and swallowing that here would leave it
+ * rendering an empty list with no way to tell why.
+ */
+suspend fun everywhereFetch(path: String, accept: String = "application/json"): String =
+    withContext(Dispatchers.IO) {
+        val config = EverywhereConfig.shared
+        val location = if (path.startsWith("http://") || path.startsWith("https://")) {
+            path
+        } else {
+            config.url(forPath = path)
+        }
+
+        val connection = (URL(location).openConnection() as HttpURLConnection).apply {
+            requestMethod = "GET"
+            setRequestProperty("Accept", accept)
+            setRequestProperty("User-Agent", config.nativeUserAgent)
+            runCatching { CookieManager.getInstance().getCookie(location) }.getOrNull()
+                ?.takeIf { it.isNotEmpty() }
+                ?.let { setRequestProperty("Cookie", it) }
+            connectTimeout = TIMEOUT_MS
+            readTimeout = TIMEOUT_MS
+        }
+
+        try {
+            val status = connection.responseCode
+            if (status !in 200..299) {
+                // errorStream, not inputStream: reading the latter on a 4xx/5xx
+                // throws, which would hide the status the caller needs to report.
+                val detail = connection.errorStream?.bufferedReader()?.use { it.readText() }.orEmpty()
+                throw EverywhereFetchError(status, location, detail)
+            }
+            connection.inputStream.bufferedReader().use { it.readText() }
+        } finally {
+            connection.disconnect()
+        }
+    }
+
+/** A non-2xx response from [everywhereFetch]. */
+class EverywhereFetchError(
+    val status: Int,
+    val location: String,
+    val body: String
+) : Exception("HTTP $status for $location")
+
+private const val TIMEOUT_MS = 15_000