Merge pull request #12 from hotwired/router

Add the concept of a dedicated Router and custom Routes

core/build.gradle.kts

@@ -70,6 +70,9 @@ dependencies {
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")
 
+    // Browser
+    implementation("androidx.browser:browser:1.7.0")
+
     // Exported AndroidX dependencies
     api("androidx.appcompat:appcompat:1.6.1")
     api("androidx.core:core-ktx:1.12.0")

core/src/main/kotlin/dev/hotwire/core/config/Hotwire.kt

@@ -1,8 +1,13 @@
 package dev.hotwire.core.config
 
+import android.content.Context
 import androidx.fragment.app.Fragment
 import dev.hotwire.core.bridge.BridgeComponent
 import dev.hotwire.core.bridge.BridgeComponentFactory
+import dev.hotwire.core.navigation.routing.BrowserRoute
+import dev.hotwire.core.navigation.routing.AppNavigationRoute
+import dev.hotwire.core.navigation.routing.Router
+import dev.hotwire.core.turbo.config.TurboPathConfiguration
 import kotlin.reflect.KClass
 
 object Hotwire {
@@ -13,8 +18,39 @@ object Hotwire {
     internal var registeredFragmentDestinations: List<KClass<out Fragment>> = emptyList()
         private set
 
+    internal var router = Router(listOf(
+        AppNavigationRoute(),
+        BrowserRoute()
+    ))
+
     val config: HotwireConfig = HotwireConfig()
 
+    /**
+     * The base url of your web app.
+     */
+    var appUrl: String = ""
+
+    /**
+     * The path configuration that defines your navigation rules.
+     */
+    val pathConfiguration = TurboPathConfiguration()
+
+    /**
+     * Loads the [TurboPathConfiguration] JSON file(s) from the provided location to
+     * configure navigation rules.
+     */
+    fun loadPathConfiguration(context: Context, location: TurboPathConfiguration.Location) {
+        pathConfiguration.load(context, location)
+    }
+
+    /**
+     * Registers the [Router.Route] instances that determine whether to route location
+     * urls within in-app navigation or with alternative custom behaviors.
+     */
+    fun registerRoutes(routes: List<Router.Route>) {
+        router = Router(routes)
+    }
+
     /**
      * Register bridge components that the app supports. Every possible bridge
      * component, wrapped in a [BridgeComponentFactory], must be provided here.

core/src/main/kotlin/dev/hotwire/core/config/HotwireConfig.kt

@@ -37,12 +37,6 @@ class HotwireConfig internal constructor() {
             WebView.setWebContentsDebuggingEnabled(value)
         }
 
-    /**
-     * The location of your [TurboPathConfiguration] JSON file(s) to configure
-     * navigation rules.
-     */
-    var pathConfigurationLocation = TurboPathConfiguration.Location()
-
     /**
      * Provides a standard substring to be included in your WebView's user agent
      * to identify itself as a Hotwire Native app.

core/src/main/kotlin/dev/hotwire/core/navigation/routing/AppNavigationRoute.kt

@@ -0,0 +1,18 @@
+package dev.hotwire.core.navigation.routing
+
+import androidx.appcompat.app.AppCompatActivity
+import androidx.core.net.toUri
+
+class AppNavigationRoute : Router.Route {
+    override val name = "app-navigation"
+
+    override val result = Router.RouteResult.NAVIGATE
+
+    override fun matches(location: String): Boolean {
+        return appUrl.toUri().host == location.toUri().host
+    }
+
+    override fun perform(location: String, activity: AppCompatActivity) {
+        // No-op
+    }
+}

core/src/main/kotlin/dev/hotwire/core/navigation/routing/BrowserRoute.kt

@@ -0,0 +1,27 @@
+package dev.hotwire.core.navigation.routing
+
+import android.content.ActivityNotFoundException
+import android.content.Intent
+import androidx.appcompat.app.AppCompatActivity
+import androidx.core.net.toUri
+import dev.hotwire.core.logging.logError
+
+class BrowserRoute : Router.Route {
+    override val name = "browser"
+
+    override val result = Router.RouteResult.STOP
+
+    override fun matches(location: String): Boolean {
+        return appUrl.toUri().host != location.toUri().host
+    }
+
+    override fun perform(location: String, activity: AppCompatActivity) {
+        val intent = Intent(Intent.ACTION_VIEW, location.toUri())
+
+        try {
+            activity.startActivity(intent)
+        } catch (e: ActivityNotFoundException) {
+            logError("BrowserRoute", e)
+        }
+    }
+}

core/src/main/kotlin/dev/hotwire/core/navigation/routing/BrowserTabRoute.kt

@@ -0,0 +1,34 @@
+package dev.hotwire.core.navigation.routing
+
+import androidx.appcompat.app.AppCompatActivity
+import androidx.browser.customtabs.CustomTabColorSchemeParams
+import androidx.browser.customtabs.CustomTabsIntent
+import androidx.core.net.toUri
+import com.google.android.material.R
+import dev.hotwire.core.turbo.util.colorFromThemeAttr
+
+class BrowserTabRoute : Router.Route {
+    override val name = "browser-tab"
+
+    override val result = Router.RouteResult.STOP
+
+    override fun matches(location: String): Boolean {
+        return appUrl.toUri().host != location.toUri().host
+    }
+
+    override fun perform(location: String, activity: AppCompatActivity) {
+        val color = activity.colorFromThemeAttr(R.attr.colorSurface)
+        val colorParams = CustomTabColorSchemeParams.Builder()
+            .setToolbarColor(color)
+            .setNavigationBarColor(color)
+            .build()
+
+        CustomTabsIntent.Builder()
+            .setShowTitle(true)
+            .setShareState(CustomTabsIntent.SHARE_STATE_ON)
+            .setUrlBarHidingEnabled(false)
+            .setDefaultColorSchemeParams(colorParams)
+            .build()
+            .launchUrl(activity, location.toUri())
+    }
+}

core/src/main/kotlin/dev/hotwire/core/navigation/routing/Router.kt

@@ -0,0 +1,78 @@
+package dev.hotwire.core.navigation.routing
+
+import androidx.appcompat.app.AppCompatActivity
+import dev.hotwire.core.config.Hotwire
+import dev.hotwire.core.logging.logEvent
+import dev.hotwire.core.navigation.routing.Router.Route
+
+/**
+ * Routes location urls within in-app navigation or with custom behaviors
+ * provided in [Route] instances.
+ */
+class Router(private val routes: List<Route>) {
+
+    /**
+     * An interface to implement to provide custom route behaviors in your app.
+     */
+    interface Route {
+        /**
+         * The configured app url. You can use this to determine if a location
+         * exists on the same domain.
+         */
+        val appUrl get() = Hotwire.appUrl
+
+        /**
+         * The route name used in debug logging.
+         */
+        val name: String
+
+        /**
+         * To permit in-app navigation when the location matches this route,
+         * return [RouteResult.NAVIGATE]. To prevent in-app navigation return
+         * [RouteResult.STOP].
+         */
+        val result: RouteResult
+
+        /**
+         * Determines whether the location matches this route. Use your own custom
+         * rules based on the location's domain, protocol, path, or any other
+         * factors.
+         */
+        fun matches(location: String): Boolean
+
+        /**
+         * Perform custom routing behavior when a match is found. For example,
+         * open an external browser or app for external domain urls.
+         */
+        fun perform(location: String, activity: AppCompatActivity)
+    }
+
+    enum class RouteResult {
+        /**
+         * Permit in-app navigation with your app's domain urls.
+         */
+        NAVIGATE,
+
+        /**
+         * Prevent in-app navigation. Always use this for external domain urls.
+         */
+        STOP
+    }
+
+    internal fun route(location: String, activity: AppCompatActivity): RouteResult {
+        routes.forEach { route ->
+            if (route.matches(location)) {
+                logEvent("routeMatch", listOf(
+                    "route" to route.name,
+                    "location" to location
+                ))
+
+                route.perform(location, activity)
+                return route.result
+            }
+        }
+
+        logEvent("noRouteForLocation", location)
+        return RouteResult.STOP
+    }
+}

core/src/main/kotlin/dev/hotwire/core/turbo/config/TurboPathConfiguration.kt

@@ -13,10 +13,10 @@ import java.net.URL
  * Provides the ability to load, parse, and retrieve url path
  * properties from the app's JSON configuration file.
  */
-class TurboPathConfiguration(context: Context) {
+class TurboPathConfiguration {
     private val cachedProperties: HashMap<String, TurboPathConfigurationProperties> = hashMapOf()
 
-    internal val loader = TurboPathConfigurationLoader(context.applicationContext)
+    internal var loader: TurboPathConfigurationLoader? = null
 
     @SerializedName("rules")
     internal var rules: List<TurboPathConfigurationRule> = emptyList()
@@ -55,11 +55,14 @@ class TurboPathConfiguration(context: Context) {
 
     /**
      * Loads and parses the specified configuration file(s) from their local
-     * and/or remote locations. You should not need to call this directly
-     * outside of testing.
+     * and/or remote locations.
      */
-    fun load(location: Location) {
-        loader.load(location) {
+    internal fun load(context: Context, location: Location) {
+        if (loader == null) {
+            loader = TurboPathConfigurationLoader(context.applicationContext)
+        }
+
+        loader?.load(location) {
             cachedProperties.clear()
             rules = it.rules
             settings = it.settings

core/src/main/kotlin/dev/hotwire/core/turbo/config/TurboPathConfigurationLoader.kt

@@ -2,6 +2,8 @@ package dev.hotwire.core.turbo.config
 
 import android.content.Context
 import com.google.gson.reflect.TypeToken
+import dev.hotwire.core.logging.logError
+import dev.hotwire.core.logging.logEvent
 import dev.hotwire.core.turbo.util.dispatcherProvider
 import dev.hotwire.core.turbo.util.toObject
 import kotlinx.coroutines.CoroutineScope
@@ -30,29 +32,41 @@ internal class TurboPathConfigurationLoader(val context: Context) : CoroutineSco
         loadCachedConfigurationForUrl(url, onCompletion)
 
         launch {
-            repository.getRemoteConfiguration(url)?.let {
-                onCompletion(load(it))
-                cacheConfigurationForUrl(url, load(it))
+            repository.getRemoteConfiguration(url)?.let { json ->
+                load(json)?.let {
+                    logEvent("remotePathConfigurationLoaded", url)
+                    onCompletion(it)
+                    cacheConfigurationForUrl(url, it)
+                }
             }
         }
     }
 
     private fun loadBundledAssetConfiguration(filePath: String, onCompletion: (TurboPathConfiguration) -> Unit) {
-        val configuration = repository.getBundledConfiguration(context, filePath)
-        onCompletion(load(configuration))
+        val json = repository.getBundledConfiguration(context, filePath)
+        load(json)?.let {
+            logEvent("bundledPathConfigurationLoaded", filePath)
+            onCompletion(it)
+        }
     }
 
     private fun loadCachedConfigurationForUrl(url: String, onCompletion: (TurboPathConfiguration) -> Unit) {
-        repository.getCachedConfigurationForUrl(context, url)?.let {
-            onCompletion(load(it))
+        repository.getCachedConfigurationForUrl(context, url)?.let { json ->
+            load(json)?.let {
+                logEvent("cachedPathConfigurationLoaded", url)
+                onCompletion(it)
+            }
         }
     }
 
     private fun cacheConfigurationForUrl(url: String, pathConfiguration: TurboPathConfiguration) {
         repository.cacheConfigurationForUrl(context, url, pathConfiguration)
     }
 
-    private fun load(json: String): TurboPathConfiguration {
-        return json.toObject(object : TypeToken<TurboPathConfiguration>() {})
+    private fun load(json: String) = try {
+        json.toObject(object : TypeToken<TurboPathConfiguration>() {})
+    } catch(e: Exception) {
+        logError("pathConfiguredFailedToParse", e)
+        null
     }
 }

core/src/main/kotlin/dev/hotwire/core/turbo/nav/TurboNavDestination.kt

@@ -4,6 +4,7 @@ import android.content.Intent
 import android.os.Bundle
 import androidx.activity.result.ActivityResultLauncher
 import androidx.annotation.IdRes
+import androidx.appcompat.app.AppCompatActivity
 import androidx.appcompat.widget.Toolbar
 import androidx.fragment.app.Fragment
 import androidx.fragment.app.FragmentManager
@@ -13,7 +14,9 @@ import androidx.navigation.fragment.FragmentNavigator
 import androidx.navigation.fragment.findNavController
 import androidx.navigation.navOptions
 import androidx.navigation.ui.R
-import dev.hotwire.core.turbo.config.TurboPathConfiguration
+import dev.hotwire.core.config.Hotwire
+import dev.hotwire.core.config.Hotwire.pathConfiguration
+import dev.hotwire.core.navigation.routing.Router
 import dev.hotwire.core.turbo.config.TurboPathConfigurationProperties
 import dev.hotwire.core.turbo.config.context
 import dev.hotwire.core.turbo.delegates.TurboFragmentDelegate
@@ -24,8 +27,6 @@ import dev.hotwire.core.turbo.fragments.TurboWebFragment
 import dev.hotwire.core.turbo.session.TurboSession
 import dev.hotwire.core.turbo.session.TurboSessionNavHostFragment
 import dev.hotwire.core.turbo.visit.TurboVisitOptions
-import java.net.MalformedURLException
-import java.net.URL
 
 /**
  * The primary interface that a navigable Fragment implements to provide the library with
@@ -132,18 +133,16 @@ interface TurboNavDestination {
     }
 
     /**
-     * Gets whether the new location should be navigated to from the current destination. Override
-     * to provide your own custom rules based on the location's domain, protocol, path, or any other
-     * factors. (e.g. external domain urls or mailto: links should not be sent through the normal
-     * Turbo navigation flow).
+     * Determines whether the new location should be routed within in-app navigation from the
+     * current destination. By default, the registered [Router.Route] instances are used to
+     * determine routing logic. You can override the global behavior for a specific destination,
+     * but it's recommend to use dedicated [Router.Route] instances for routing logic.
      */
-    fun shouldNavigateTo(newLocation: String): Boolean {
-        return try {
-            URL(newLocation)
-            true
-        } catch (e: MalformedURLException) {
-            false
-        }
+    fun route(newLocation: String): Router.RouteResult {
+        return Hotwire.router.route(
+            location = newLocation,
+            activity = fragment.requireActivity() as AppCompatActivity
+        )
     }
 
     /**
@@ -236,9 +235,6 @@ interface TurboNavDestination {
     private val navigator: TurboNavigator
         get() = delegate().navigator
 
-    private val pathConfiguration: TurboPathConfiguration
-        get() = session.pathConfiguration
-
     /**
      * Retrieve the nav controller indirectly from the parent NavHostFragment,
      * since it's only available when the fragment is attached to its parent.