feat(android-nav3): Android Nav3 integration (JAVA-274) (#6128)

Initial Nav3 support (internal and experimental)

Commit introduces a new sentry-android-navigation3 module and SentryNavEffect, our primary abstraction for phase 1 Nav3 support.

Phase 1 aims at achieving parity with our existing Nav2 integration. That means generating nav transactions, breadcrumbs, and screen names for each destination as the user navigates through the app. 

In line with Nav2, SentryNavEffect assumes the top of the nav back stack represents the current screen and the entirety of its contents. Phase 2 will introduce support for [Scenes](https://developer.android.com/guide/navigation/navigation-3/scenes) and multipane layouts; phase 3 will support multiple back stacks (See [#5649](#5649) and [#5650](#5650), respectively.)

In addition to what Nav2 offers, SentryNavEffect also records up to N frames of the host app's back stack in current scope context. (N is 10 by default; it can be adjusted via SentryNavOptions, along with other nav3 configs.) 

For more details, see the KDocs to SentryNavEffect, SentryNavOptions, RouteNameExtractor, and RouteArgumentsExtractor.

SentryNavEffect is experimental and (for now) internal. It will be made it public in a later release commit.

Author: 0xadam-brown

.github/ISSUE_TEMPLATE/bug_report_android.yml

@@ -12,6 +12,7 @@ body:
         - sentry-android-ndk
         - sentry-android-timber
         - sentry-android-fragment
+        - sentry-android-navigation3
         - sentry-android-sqlite
         - sentry-apollo
         - sentry-apollo-3

AGENTS.md

@@ -98,7 +98,7 @@ The repository is organized into multiple modules:
 - **Logging**: `sentry-logback`, `sentry-log4j2`, `sentry-jul`, `sentry-android-timber`
 - **Web**: `sentry-servlet*`, `sentry-okhttp`, `sentry-openfeign`, `sentry-apache-http-client-5`
 - **GraphQL**: `sentry-graphql*`, `sentry-apollo*`
-- **Android UI**: `sentry-android-fragment`, `sentry-android-navigation`, `sentry-compose`
+- **Android UI**: `sentry-android-fragment`, `sentry-android-navigation`, `sentry-android-navigation3`, `sentry-compose`
 - **Session Replay**: `sentry-android-replay`
 - **Database**: `sentry-jdbc`, `sentry-android-sqlite`, `sentry-jcache`
 - **Reactive**: `sentry-reactor`, `sentry-ktor-client`

buildSrc/src/main/java/Config.kt

@@ -98,6 +98,7 @@ object Config {
             "sentry-android-ndk",
             "sentry-android-fragment",
             "sentry-android-navigation",
+            "sentry-android-navigation3",
             "sentry-android-timber",
             "sentry-compose-android",
             "sentry-android-sqlite",

gradle/libs.versions.toml

@@ -91,6 +91,7 @@ androidx-activity-compose = { module = "androidx.activity:activity-compose", ver
 androidx-compose-foundation = { module = "androidx.compose.foundation:foundation", version.ref = "androidxCompose" }
 androidx-compose-foundation-layout = { module = "androidx.compose.foundation:foundation-layout", version.ref = "androidxCompose" }
 androidx-compose-material3 = { module = "androidx.compose.material3:material3", version = "1.4.0" }
+androidx-compose-runtime = { module = "androidx.compose.runtime:runtime", version.ref = "androidxCompose" }
 androidx-compose-material-icons-core = { module = "androidx.compose.material:material-icons-core", version="1.7.8" }
 androidx-compose-material-icons-extended = { module = "androidx.compose.material:material-icons-extended", version="1.7.8" }
 androidx-compose-ui = { module = "androidx.compose.ui:ui", version.ref = "androidxCompose" }

sentry-android-navigation3/api/sentry-android-navigation3.api

@@ -0,0 +1,51 @@
+public final class io/sentry/compose/navigation3/BuildConfig {
+	public static final field BUILD_TYPE Ljava/lang/String;
+	public static final field DEBUG Z
+	public static final field LIBRARY_PACKAGE_NAME Ljava/lang/String;
+	public static final field VERSION_NAME Ljava/lang/String;
+	public fun <init> ()V
+}
+
+public abstract interface class io/sentry/compose/navigation3/RouteArgumentsExtractor {
+	public abstract fun extract (Ljava/lang/Object;)Ljava/util/Map;
+}
+
+public abstract interface class io/sentry/compose/navigation3/RouteNameExtractor {
+	public abstract fun extract (Ljava/lang/Object;)Ljava/lang/String;
+}
+
+public final class io/sentry/compose/navigation3/SentryNavEffectKt {
+	public static final fun SentryNavEffect (Ljava/util/List;Lio/sentry/compose/navigation3/RouteNameExtractor;Lio/sentry/compose/navigation3/RouteArgumentsExtractor;Lio/sentry/compose/navigation3/SentryNavOptions;Landroidx/compose/runtime/Composer;II)V
+}
+
+public final class io/sentry/compose/navigation3/SentryNavOptions {
+	public static final field $stable I
+	public synthetic fun <init> (ZZZILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun equals (Ljava/lang/Object;)Z
+	public final fun getCaptureBackStack ()Z
+	public final fun getEnableNavigationBreadcrumbs ()Z
+	public final fun getEnableNavigationTransactions ()Z
+	public final fun getMaxCapturedBackStackEntries ()I
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+}
+
+public final class io/sentry/compose/navigation3/SentryNavOptions$Builder {
+	public static final field $stable I
+	public fun <init> ()V
+	public final fun build ()Lio/sentry/compose/navigation3/SentryNavOptions;
+	public final fun getCaptureBackStack ()Z
+	public final fun getEnableNavigationBreadcrumbs ()Z
+	public final fun getEnableNavigationTransactions ()Z
+	public final fun getMaxCapturedBackStackEntries ()I
+	public final fun setCaptureBackStack (Z)V
+	public final fun setEnableNavigationBreadcrumbs (Z)V
+	public final fun setEnableNavigationTransactions (Z)V
+	public final fun setMaxCapturedBackStackEntries (I)V
+}
+
+public final class io/sentry/compose/navigation3/SentryNavOptionsKt {
+	public static final fun SentryNavOptions (Lkotlin/jvm/functions/Function1;)Lio/sentry/compose/navigation3/SentryNavOptions;
+	public static synthetic fun SentryNavOptions$default (Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lio/sentry/compose/navigation3/SentryNavOptions;
+}
+

sentry-android-navigation3/build.gradle.kts

@@ -0,0 +1,78 @@
+import io.gitlab.arturbosch.detekt.Detekt
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_1_8
+import org.jetbrains.kotlin.gradle.dsl.KotlinVersion
+
+plugins {
+  id("com.android.library")
+  alias(libs.plugins.kotlin.android)
+  alias(libs.plugins.kotlin.compose)
+  alias(libs.plugins.gradle.versions)
+  alias(libs.plugins.detekt)
+}
+
+android {
+  compileSdk = libs.versions.compileSdk.get().toInt()
+  namespace = "io.sentry.compose.navigation3"
+
+  defaultConfig {
+    minSdk = libs.versions.minSdk.get().toInt()
+
+    buildConfigField("String", "VERSION_NAME", "\"${project.version}\"")
+  }
+
+  buildTypes {
+    getByName("release") { consumerProguardFiles("proguard-rules.pro") }
+  }
+
+  // AGP 9 only generates unit tests for the testBuildType. The debug variant is
+  // disabled, so unit tests must target release to run at all.
+  testBuildType = "release"
+
+  kotlin {
+    compilerOptions.jvmTarget = JVM_1_8
+    compilerOptions.languageVersion = KotlinVersion.KOTLIN_1_9
+    compilerOptions.apiVersion = KotlinVersion.KOTLIN_1_9
+  }
+
+  testOptions {
+    unitTests.isReturnDefaultValues = true
+  }
+
+  lint {
+    warningsAsErrors = true
+    checkDependencies = true
+
+    // We run a full lint analysis as build part in CI, so skip vital checks for assemble tasks.
+    checkReleaseBuilds = false
+  }
+
+  buildFeatures {
+    buildConfig = true
+    compose = true
+  }
+
+  androidComponents.beforeVariants {
+    it.enable = !Config.Android.shouldSkipDebugVariant(it.buildType)
+  }
+}
+
+kotlin { explicitApi() }
+
+dependencies {
+  implementation(projects.sentry)
+
+  compileOnly(libs.androidx.compose.runtime)
+
+  testImplementation(libs.androidx.compose.ui.test.junit4)
+  testImplementation(libs.androidx.test.core)
+  testImplementation(libs.androidx.test.ext.junit)
+  testImplementation(libs.google.truth)
+  testImplementation(libs.mockito.inline)
+  testImplementation(libs.mockito.kotlin)
+  testImplementation(libs.roboelectric)
+}
+
+tasks.withType<Detekt>().configureEach {
+  // Target version of the generated JVM bytecode. It is used for type resolution.
+  jvmTarget = JavaVersion.VERSION_1_8.toString()
+}

sentry-android-navigation3/proguard-rules.pro

@@ -0,0 +1,7 @@
+##---------------Begin: proguard configuration for Compose  ----------
+
+# To ensure that stack traces is unambiguous
+# https://developer.android.com/studio/build/shrink-code#decode-stack-trace
+-keepattributes LineNumberTable,SourceFile
+
+##---------------End: proguard configuration for Compose  ----------

sentry-android-navigation3/src/main/kotlin/io/sentry/compose/navigation3/BackStackKey.kt

@@ -0,0 +1,35 @@
+package io.sentry.compose.navigation3
+
+/**
+ * A key for distinguishing back stacks over time.
+ *
+ * Lets `*Effect`s restart when either the identity of a stack entry changes or the stack's entries
+ * are reordered.
+ */
+internal class BackStackKey<T : Any>(private val backStack: List<T>) {
+
+  override fun equals(other: Any?): Boolean {
+    // Use of identity rather than structural equality frees us from entries' equals() and
+    // hashCode() implementations, which are provided by the host app and may be incomplete,
+    // expensive, or incorrect for our purposes.
+    if (this === other) {
+      return true
+    }
+    if (other !is BackStackKey<*>) {
+      return false
+    }
+    if (backStack.size != other.backStack.size) {
+      return false
+    }
+
+    return backStack.indices.all { index -> backStack[index] === other.backStack[index] }
+  }
+
+  override fun hashCode(): Int {
+    var result = backStack.size
+    for (entry in backStack) {
+      result = 31 * result + System.identityHashCode(entry)
+    }
+    return result
+  }
+}