Skip to content

Commit b91b558

Browse files
committed
feat(nav3): Add the SerialNameAndProperties mapper
1 parent 1a2ed62 commit b91b558

26 files changed

Lines changed: 2917 additions & 107 deletions

‎CHANGELOG.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,22 +10,22 @@
1010
### Features
1111

1212
- Nav3: Add `BackStackEntryMapper.SerialName`, a convenience mapper that names back stack entries after their kotlinx.serialization serial names ([#PR_NUMBER](https://github.com/getsentry/sentry-java/pull/PR_NUMBER))
13+
- Nav3: Add `BackStackEntryMapper.SerialNameAndProperties`, which is like `SerialName` except that it also records the properties of each back stack entry as arguments ([#PR_NUMBER](https://github.com/getsentry/sentry-java/pull/PR_NUMBER))
1314

1415
### Behavioral Changes
1516

1617
- Nav3: If a back stack entry's arguments contain a map with two keys that are recorded as the same string (e.g., `1` and `"1"`), Sentry now drops that entry's arguments and records `dropped_by_sentry: duplicate_key`, instead of keeping only one of the values ([#PR_NUMBER](https://github.com/getsentry/sentry-java/pull/PR_NUMBER))
1718

18-
### Dependencies
19-
20-
- Nav3: `sentry-android-navigation3` no longer declares a dependency on `androidx.lifecycle:lifecycle-runtime-compose`. Nav3 apps already depend on it via `navigation3-ui`, so no app changes are necessary ([#PR_NUMBER](https://github.com/getsentry/sentry-java/pull/PR_NUMBER))
21-
2219
### Fixes
2320

2421
- Nav3: `NaN` and infinite numbers in back stack entry arguments are now sent as the strings `"NaN"`, `"Infinity"`, and `"-Infinity"`, instead of causing the event they're attached to be dropped ([#PR_NUMBER](https://github.com/getsentry/sentry-java/pull/PR_NUMBER))
25-
2622
- Kotlin now sees `Attachment.getBytes()`, `Device.getArchs()`, `Spring.getActiveProfiles()` and `JsonSerializationUtils.bytesFrom(...)` as nullable, because `@Nullable` now annotates the returned array instead of its elements ([#6558](https://github.com/getsentry/sentry-java/pull/6558))
2723
- Shake-to-report no longer leaks the first Activity that resumes after `Sentry.init` ([#6686](https://github.com/getsentry/sentry-java/pull/6686))
2824

25+
### Dependencies
26+
27+
- Nav3: `sentry-android-navigation3` no longer declares a dependency on `androidx.lifecycle:lifecycle-runtime-compose`. Nav3 apps already depend on it via `navigation3-ui`, so no app changes are necessary ([#PR_NUMBER](https://github.com/getsentry/sentry-java/pull/PR_NUMBER))
28+
2929
## 8.65.0
3030

3131
### Features

‎sentry-android-navigation3/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,8 @@ Use `SentryNavEffect` alongside your `NavDisplay` to record navigation transacti
66
users move around your app. Configure the data you want captured via `SentryNavOptions`.
77

88
Because Nav3 back stacks can have arbitrary key types, host apps need to provide `SentryNavEffect` with a mapping between their back stack
9-
keys and the data Sentry should display for each (see `BackStackEntryMapper` and the built-in `SerialName` mapper).
9+
keys and the data Sentry should display for each (see `BackStackEntryMapper` and the built-in `SerialName` and
10+
`SerialNameAndProperties` mappers).
1011

1112
See the [Navigation for Android docs](https://docs.sentry.io/platforms/android/integrations/navigation/) for additional details, including
1213
configuration, supported setups, and limitations.

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ public abstract interface class io/sentry/compose/navigation3/BackStackEntryMapp
55

66
public final class io/sentry/compose/navigation3/BackStackEntryMapper$Companion {
77
public final fun getSerialName ()Lio/sentry/compose/navigation3/BackStackEntryMapper;
8+
public final fun getSerialNameAndProperties ()Lio/sentry/compose/navigation3/BackStackEntryMapper;
89
}
910

1011
public final class io/sentry/compose/navigation3/BuildConfig {

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

Lines changed: 79 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -54,13 +54,17 @@ public class SentryBackStackEntry(
5454
/**
5555
* Maps a back stack entry to a displayable name and optional diagnostic arguments.
5656
*
57-
* If you use kotlinx.serialization, see [SerialName] for convenient, out-of-the-box mappers.
58-
* Otherwise, provide your own implementation. (Note: Custom implementations can always fall back to
59-
* `SerialName` for any entries that don't have to be special-cased.)
57+
* If you use kotlinx.serialization, see [SerialName] and [SerialNameAndProperties] for convenient,
58+
* out-of-the-box mappers. Otherwise, provide your own implementation. (Note: Custom implementations
59+
* can always fall back to `SerialName` or `SerialNameAndProperties` for any entries that don't have
60+
* to be special-cased.)
6061
*
6162
* **Privacy / PII**
6263
*
63-
* Custom mappers are responsible for filtering their own arguments.
64+
* Built-in mappers that capture entry properties apply limited sensitive-data filtering before
65+
* recording arguments; see [SerialNameAndProperties] for the filtering rules. Custom mappers are
66+
* responsible for filtering their own arguments; Sentry does not apply its built-in sensitive-data
67+
* filtering to arguments they supply themselves.
6468
*
6569
* Only return names and arguments that are known to be safe or have been pre-scrubbed. All
6670
* arguments remain subject to size and structural limits.
@@ -144,6 +148,8 @@ public fun interface BackStackEntryMapper<in T : Any> {
144148
* would return `"ProductDetail"` as the destination's name, but would ***not*** return the
145149
* destination's properties (`userId` and `productId`).
146150
*
151+
* To return both entry names and properties, see [SerialNameAndProperties].
152+
*
147153
* **Name == SerialDescriptor.serialName**
148154
*
149155
* This mapper names each back stack entry after the entry's
@@ -177,8 +183,8 @@ public fun interface BackStackEntryMapper<in T : Any> {
177183
*
178184
* Entries share a Sentry name whenever their serializers share a serial name. In particular:
179185
*
180-
* - All constants of an enum are named after the enum. A `@SerialName` on a constant does not
181-
* change the destination name.
186+
* - All constants of an enum are named after the enum. A `@SerialName` on a constant only
187+
* changes how [SerialNameAndProperties] records the constant as an argument.
182188
*
183189
* - Classes that use the same custom serializer (`@Serializable(with = ...)`) are named after
184190
* that serializer's descriptor, which ignores a `@SerialName` on the class.
@@ -189,5 +195,72 @@ public fun interface BackStackEntryMapper<in T : Any> {
189195
@get:ApiStatus.Experimental
190196
public val SerialName: BackStackEntryMapper<Any>
191197
get() = BuiltInBackStackEntryMappers.serialName
198+
199+
/**
200+
* Like [SerialName], but also returns the properties of each back stack entry as Sentry
201+
* arguments.
202+
*
203+
* For instance, given:
204+
* ```
205+
* @Serializable
206+
* @SerialName("ProductDetail")
207+
* data class ProductDetail(
208+
* val userId: String,
209+
* val productId: String
210+
* ) : NavKey
211+
* ```
212+
*
213+
* when navigating to `ProductDetail(userId = "123abc", productId = "zyx987")`, this mapper
214+
* would return `"ProductDetail"` as the destination's name, along with the following arguments:
215+
* ```json
216+
* {
217+
* "userId": "123abc",
218+
* "productId": "zyx987"
219+
* }
220+
* ```
221+
*
222+
* Returns `null` for any entries that can't be named (see [SerialName]). Sentry displays these
223+
* entries as `"/unknown"` with no arguments.
224+
*
225+
* The argument limits described in [BackStackEntryMapper] apply.
226+
*
227+
* **Privacy / PII**
228+
*
229+
* This mapper returns arguments for every property of each back stack entry passed to it, which
230+
* may include private data or PII. Almost all properties are sent as-is (see below for limited
231+
* exceptions in the case of sensitive secrets). Neither `sendDefaultPii` nor the
232+
* `dataCollection` options change what this mapper returns.
233+
*
234+
* Modify your use of this mapper if any entry in your back stack contains info you don't want
235+
* sent to Sentry. For instance, i) use this mapper for all entries but filter out any
236+
* properties you want to omit, or ii) use a custom [BackStackEntryMapper] that special-cases
237+
* entries with sensitive info or PII and falls back to this mapper (or [SerialName]) for
238+
* entries without it. See
239+
* [Choosing Which Arguments to Send](https://docs.sentry.io/platforms/android/integrations/navigation/#choosing-which-arguments-to-send)
240+
* for examples.
241+
*
242+
* **Limited filtering for sensitive secrets**
243+
*
244+
* Values are replaced with `"[Filtered]"` when their property's targeted name (i.e., their
245+
* `@SerialName` if they have one, or else the property's name) contains a term from
246+
* [Sentry's sensitive denylist](https://develop.sentry.dev/sdk/foundations/client/data-collection/#sensitive-denylist)
247+
* (ignoring case). This filters secrets like `authToken`, but leaves PII like `userEmail`
248+
* unchanged.
249+
*
250+
* Matching follows the same rule Sentry SDKs use for HTTP headers, cookies, and query
251+
* parameters, meaning it may filter harmless properties like `insideCart` (`sid`) or `keyword`
252+
* (`key`).
253+
*
254+
* **Encoding and encoding failures**
255+
*
256+
* Properties are encoded on the first argument read, including by `equals` or `hashCode`.
257+
*
258+
* Failures preserve the entry's name and replace its arguments with a drop reason, e.g.,
259+
* `{"dropped_by_sentry": "encoding_failed"}`. Encoding errors are logged once per entry type
260+
* when `debug` is enabled.
261+
*/
262+
@get:ApiStatus.Experimental
263+
public val SerialNameAndProperties: BackStackEntryMapper<Any>
264+
get() = BuiltInBackStackEntryMappers.serialNameAndProperties
192265
}
193266
}

‎sentry-android-navigation3/src/main/kotlin/io/sentry/compose/navigation3/internal/backstack/ArgumentConversion.kt‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,52 @@ import java.util.IdentityHashMap
1414
* implementations are expected to materialize the provided info into a tree of Sentry arguments,
1515
* where the tree has a bounded size and height.
1616
*
17+
* **The argument conversion subsystem**
18+
*
19+
* With Nav3, host apps manage their own nav back stack, which they implement as a list of
20+
* arbitrarily typed entries. In order to be displayed in Sentry, each of those entries has to be
21+
* mapped to a Sentry name (e.g., ProductDetailScreen) and zero or more arguments (e.g., productId).
22+
* There are two ways for host apps to provide us with those mappings:
23+
*
24+
* 1. via a custom `BackStackEntryMapper`; or
25+
*
26+
* 2. via one of our own built-in mappers (viz., `BackStackEntryMapper.SerialName` or
27+
* `BackStackEntryMapper.SerialNameAndProperties`).
28+
*
29+
* `ArgumentSink` and `ArgumentSource` create the seam that lets us support variable processing on
30+
* the source side (the host app's logic vs built-in logic) but uniform processing on the sink side
31+
* (argument pruning, protecting against constraint violation, and tree materialization).
32+
*
33+
* Here are the moving parts:
34+
* ```text
35+
* ArgumentSource
36+
* Custom mapper Built-in mappers
37+
* ┌────────────────────┐ ┌──────────────────┐
38+
* │ HostArgumentSource │ │ KotlinxArguments │
39+
* │ (plain host map) │ │ (drives encoder) │
40+
* └────────┬───────────┘ └────────┬─────────┘
41+
* │ │ via
42+
* │ KotlinxPropertiesEncoder + SensitiveKeyFilter
43+
* │ │
44+
* └──────────────┬──────────────┘
45+
* ▼
46+
* ┌───────────────────────────────┐
47+
* │ ArgumentSink │
48+
* └───────────────────────────────┘
49+
* ▲ sole impl
50+
* ┌───────────────┴───────────────┐
51+
* │ TreeArgumentWriter │
52+
* │ │ ┌────────────────┐
53+
* │ Enforce + materialize: │ spends ──▶│ ArgumentBudget │
54+
* │ • builds the argument tree │ └────────────────┘
55+
* │ • prevents constraint │ ┌────────────────┐
56+
* │ violation (e.g., cycles) │ throws ──▶│ DropArguments │
57+
* └───────────────────────────────┘ └────────────────┘
58+
*
59+
* Note: BackStackConverter.ArgumentSanitizer owns the ArgumentBudget and
60+
* selects the ArgumentSource based on what the host app provides.
61+
* ```
62+
*
1763
* Receives one back stack entry's arguments as a [source][ArgumentSource] produces them, enforcing
1864
* the argument limits as it goes.
1965
*

‎sentry-android-navigation3/src/main/kotlin/io/sentry/compose/navigation3/internal/backstack/BuiltInBackStackEntryMappers.kt‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,23 @@ internal object BuiltInBackStackEntryMappers {
2929
// threads may each create and probe a mapper and log warnings, and all but the first
3030
// published instance would be discarded.
3131
create(logger) {
32-
KotlinxBackStackEntryMapper(logger = logger)
32+
KotlinxBackStackEntryMapper(includeProperties = false, logger = logger)
33+
}
34+
}
35+
36+
/**
37+
* Like [serialName], but also returns the properties of each back stack entry as Sentry
38+
* arguments.
39+
*
40+
* Falls back to [UnavailableBackStackEntryMapper] if a mapper can't be created.
41+
*
42+
* See [BackStackEntryMapper.SerialNameAndProperties] for more details.
43+
*/
44+
val serialNameAndProperties: BackStackEntryMapper<Any> by
45+
lazy(LazyThreadSafetyMode.PUBLICATION) {
46+
// PUBLICATION, as for serialName.
47+
create(logger) {
48+
KotlinxBackStackEntryMapper(includeProperties = true, logger = logger)
3349
}
3450
}
3551

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,15 @@
11
# `io.sentry.compose.navigation3.internal.backstack`
22

3-
Converts host back stacks into bounded Sentry names and arguments.
3+
Package contains code for generating Sentry data from a host app's back stack.
4+
5+
## Conventions
6+
7+
### Properties vs. arguments
8+
9+
Code in this package uses the term "properties" for the fields and values it reads from a back stack entry and "arguments" for the values
10+
a `BackStackEntryMapper` supplies for Sentry to record, i.e., `SentryBackStackEntry.arguments`. Arguments include the mapper's output before
11+
sanitization, which may modify or drop them before Sentry records them. Hence
12+
`SerialNameAndProperties` and `KotlinxPropertiesEncoder`, but `SentryBackStackEntry(arguments = ...)`.
13+
14+
When a host app uses a built-in `BackStackEntryMapper`, we're responsible for mapping entry properties to corresponding arguments. When the
15+
host app implements its own `BackStackEntryMapper`, it performs the mapping on its end and hands the resulting arguments to us.

0 commit comments

Comments
 (0)