From b6d3a7ea4e4cdbb674b8011ba1e56da0841aef45 Mon Sep 17 00:00:00 2001 From: Dwiki Riyadi Date: Sat, 7 Nov 2026 20:32:39 +0700 Subject: [PATCH] docs: sync the Guide with S6 Redaction and Network Monitor replay Adds the Redaction rules decided during the work (fragment parameters, unparseable JSON, short secrets) and the Network Monitor's Copy, Copy as cURL and Replay, which sends a request again through the app's own client. Co-Authored-By: Claude Opus 5.5 --- .../guide/02-packages/11-dev-tools.mdx | 51 ++++++++++++++++--- 1 file changed, 45 insertions(+), 6 deletions(-) diff --git a/docs/internal/development/guide/02-packages/11-dev-tools.mdx b/docs/internal/development/guide/02-packages/11-dev-tools.mdx index 49630a4..82281d3 100644 --- a/docs/internal/development/guide/02-packages/11-dev-tools.mdx +++ b/docs/internal/development/guide/02-packages/11-dev-tools.mdx @@ -84,7 +84,7 @@ SinewDevTools( | Inspector | Kind | Fed by | Safety rule | |---|---|---|---| -| **Network Monitor** | Page | the network recorder layer, plus cache serves the app reports | Redacted when recorded. Capped at 200 records. Cleared on sign-out. | +| **Network Monitor** | Page | the network recorder layer, plus cache serves the app reports | Redacted when recorded. Capped at 200 records. Cleared on sign-out. Copy and Copy as cURL give the redacted record; Replay sends it again through the app's client (see Copy and replay). | | **Exception Log** | Page | a `CrashReporter` decorator, plus the platform's uncaught-error hooks | Capped at 50, with repeats within 2 seconds merged into one row with a count. Copy gives the redacted text only. | | **Key-Value Store** | Page | `KeyValueStore` through `InspectableStore` | Values shown. Edit and delete ask for confirmation. | | **Secure Store** | Page | `SecureStore` through `InspectableStore` | Values **masked**: the last 4 characters and the length (`•••• 9f2c (412 chars)`). Never copyable. "Clear all" asks for confirmation. | @@ -113,23 +113,44 @@ Redaction( | A normalized name is redacted when it **contains** any of `fieldParts` (`refreshtoken`, `newpassword`, `idtoken`, `xapikey` all match), or equals one of `exactFields` | New fields that carry secrets are caught by their names, without updating a list | | Matching runs at **any depth** of a JSON body, including objects inside arrays | A password nested in `{ "user": { "credentials": [ { "password": … } ] } }` is still caught | | Every header the app sends through `defaultHeaders` is redacted automatically | Those are exactly the headers that carry API keys and device identifiers | -| Form bodies and query parameters are redacted by the same field list | Tokens also travel as `?token=…` and form fields | +| Form bodies, query parameters and fragment parameters are redacted by the same field list, with names percent-decoded first | Tokens also travel as `?token=…`, form fields, and an OAuth redirect's `#access_token=…` | | A body over `maxBodyBytes` is cut, with its real size shown | Large downloads don't fill memory | | Binary bodies (images, files) are stored as type and size only | Nothing useful to read, and they can contain personal data | | Cache records go through the same redaction | A cached response is still a response | | An app extends the defaults, never replaces them wholesale | A custom list can't accidentally drop `Authorization` | +| A redacted text body says whether anything in it was hidden | The recorder needs it to decide whether a request can be replayed | #### Recorders | Recorder | Keeps | Cleared | |---|---|---| -| `NetworkRecorder(capacity = 200)` | method, URL, status, duration, redacted headers and bodies, error type and code, a "served from cache" marker | on sign-out, on "Clear" in the page, on app restart | +| `NetworkRecorder(capacity = 200)` | method, URL, status, duration, redacted headers and bodies, error type and code, a "served from cache" marker, the client that sent it, whether it can be replayed, and whether it is a replay | on sign-out, on "Clear" in the page, on app restart | | `ExceptionRecorder(capacity = 50, dedupeWindow = 2 s)` | time, exception type, code, message key or server text, stack trace, repeat count | on "Clear", on app restart | The recorders keep data in memory only and never write it to disk. The app's sign-out use case calls `SinewDevTools.clearUserData()`. In a build without devtools, that call does nothing. `DevToolsCrashReporter` wraps the app's real reporter: `CrashReporter.install(DevToolsCrashReporter(wrapping = realReporter))`. Every report goes to the Exception Log and then on to the real reporter, unchanged. +#### Copy and replay + +A tester checking data after a backend fix shouldn't have to walk the app back to that screen. So a record in the Network Monitor offers three actions: + +| Action | What it gives | Rule | +|---|---|---| +| **Copy** | the record as text: method, URL, status, headers, bodies, timing | Exactly what was recorded, so every secret is still `•••` | +| **Copy as cURL** | a `curl` command for the request | The same redacted values. A request that needs a token won't run as copied: it's for a bug report, not for running. | +| **Replay** | the same request, sent again through **the app's own client** | The rules below | + +| Replay rule | Why | +|---|---| +| It goes through the client that sent the original, so the auth layer adds a **fresh** token and the client adds its `defaultHeaders` | The token is never in the record, and never needs to be. Fault rules and the host override apply too, as for any request. | +| Only a request where **nothing else was hidden** can be replayed: its URL, its own headers and its body kept everything. `Authorization` and the `defaultHeaders` don't count, since the client adds them again. | A login, an OTP check or a call with `?token=` lost the secret it needs. Replaying `•••` would send garbage. The page shows "Can't replay: a secret in it was hidden". | +| A cut body (over the cap) or a binary body can't be replayed | Only part of it, or only its type and size, was kept | +| `GET`, `HEAD` and `OPTIONS` replay on tap. Anything else asks first: "Send POST /orders again? It may repeat what it did." | Replaying a payment or an order does it twice | +| A replay is a **new** record, marked as a replay, at the top of the list | The original stays, so the two responses can be compared | +| No editing before sending (Later) | Editing turns devtools into an API client and widens what a tester can do on a shared device | +| Replay exists only where devtools does | It's part of `sinew_devtools`, so the no-op build has none | + #### Fault injection ``` @@ -207,6 +228,8 @@ Also Later: | `DevToolsGate` | `DevToolsGate.enabled: Boolean` (compile-time) | devtools | | `Redaction` | `Redaction(headers, fieldParts, exactFields, mask, maxBodyBytes)`, `Redaction.default`, `+ { … }` | devtools | | `NetworkRecorder` | `NetworkRecorder(capacity = 200, redaction)`, `.records`, `.clear()`, `.recordCacheServe(key, source, body)` | devtools | +| `NetworkRecord` | `.replayable`, `.isReplay`, `.asText()`, `.asCurl()` | devtools | +| `DevTools.replay` | `replay(record)`: sends the request again through the client that sent it, and records the result as a new record | devtools (no-op without devtools) | | `ExceptionRecorder` | `ExceptionRecorder(capacity = 50, dedupeWindow = 2 s)`, `.records`, `.clear()` | devtools | | `DevToolsCrashReporter` | `DevToolsCrashReporter(wrapping: CrashReporter)` | devtools | | `FaultRule`, `FaultRules` | `FaultRules.add(rule)`, `.remove(rule)`, `.clear()`, `.active` | devtools | @@ -230,15 +253,17 @@ Also Later: 2. `NetworkRecorder`, with tests: - the capacity drops the oldest record; - nothing unredacted is ever stored (assert on the stored record, not the screen); - - `clearUserData()` empties it. + - `clearUserData()` empties it; + - `replayable` is false when the URL, the request's own headers or its body lost a value, or the body was cut or binary, and true when only `Authorization` or `defaultHeaders` were masked; + - `asText()` and `asCurl()` contain only redacted values. 3. `ExceptionRecorder` and `DevToolsCrashReporter`. Tests: - de-duplication within the window; - capacity; - the wrapped reporter still receives every report; - the uncaught-error hooks chain to the previous handlers. 4. `FaultRules` in the network stack, tested: a forced 401 triggers exactly one refresh, a forced 503 on the refresh keeps the session, and a restart clears the rules. -5. `HostOverride` and `debugExpireToken`, tested against the mock HTTP setup. -6. `sinew_devtools_ui`, with the overlay and every built-in page, plus golden tests of the pages. +5. `HostOverride`, `debugExpireToken` and `DevTools.replay`, tested against the mock HTTP setup. Replay: the request goes out through the same client with a fresh token (never one from the record), fault rules and the host override apply, and the result is a new record marked as a replay. +6. `sinew_devtools_ui`, with the overlay and every built-in page, plus golden tests of the pages. The Network Monitor's Replay runs a `GET` on tap and asks first for any other method, and is disabled with its reason on a record that can't be replayed. 7. Gating. A CI job builds the production release (and, on Flutter, profile) variant and checks that no devtools class or symbol is in the output. On Kotlin, an ABI check confirms `sinew-devtools-noop` matches the real API. **Done when** @@ -260,6 +285,14 @@ Also Later: | The app has no router, or a custom one | The dashboard uses its own back stack, so it works the same. | | A production build by mistake depends on the real devtools | The CI gating job fails the build. | | The app's own uncaught-error handler is already set | Devtools chains to it. The app's handler still runs. | +| A tester replays a login, an OTP check or a `?token=` call | Not offered: a secret in it was hidden, so the page says why instead. | +| A tester replays `POST /orders` | Asked first, since it may place the order again. | +| A replay while the session has expired | It goes through the auth layer like any request, so the refresh runs and the replay is sent with the new token. | +| The record came from a client the app has since closed | Not replayable: the client that would add the token is gone. | +| A body says it's JSON, or starts with `{` or `[`, but doesn't parse | Masked whole: it can't be walked, so nothing in it can be kept. | +| A body without a content type | Kept as text only if it's valid UTF-8 without a NUL; otherwise type and size only. Multipart bodies are always type and size only, since they mix files and fields. | +| A secret shorter than 16 characters on the Secure Store page (a PIN, a one-time code) | Only its length shows (`•••• (6 chars)`): its last 4 characters would give most of it away. | +| A harmless name that contains a part (`shippingAddress` contains `pin`) | Masked. Matching by part errs toward hiding: a missed secret leaks, a hidden address only costs a tester a look elsewhere. An app can't narrow the parts, since the defaults are extend-only. | ## Implementation {#implementation} @@ -345,6 +378,9 @@ As the base note. Kotlin specifics: | `DevToolsMenuItem` | `@Composable public fun DevToolsMenuItem(modifier: Modifier = Modifier)`; the no-op artifact has an empty one | | `DevTools.open` / `DevTools.close` | `public fun open()`, `public fun close()`, `public val isOpen: StateFlow` | | `DevTools.clearUserData` | `public fun clearUserData()` | +| `Redaction` | `Redaction.Default + { headers += …; fieldParts += …; exactFields += …; maxBodyBytes = … }`, `withHeaders(names)`, `isSensitive(name)`, `isSensitiveHeader(name)`, `redactHeaders(Map>)`, `redactUrl(url)`, `redactBody(bytes, contentType): RecordedBody`, `Redaction.maskSecret(value)`. The constructor is private, so the only way to new rules is extending the defaults. | +| `RecordedBody` | `None`, `Text(text, size, truncated, masked)`, `Binary(contentType, size)`; `size` is the real body size in bytes, `masked` whether anything was hidden | +| `DevTools.replay` | `public suspend fun replay(record: NetworkRecord)`, through the `HttpClient` the hooks were installed in; the no-op returns at once | ### 4. Build steps {#kotlin-4-build-steps} @@ -450,6 +486,9 @@ EXIF, camera and map playgrounds are separate packages. Flutter links every plug | `DevToolsGate.assertMatchesFlavor` | `static void assertMatchesFlavor()`: compares the define with Flutter's `appFlavor` | | `SinewDevTools` | `SinewDevTools({required Widget child, List sections = const [], BuildRibbon? ribbon, DevToolsLauncher launcher = const FloatingLauncher(), Redaction redaction = Redaction.standard, List stores = const [], String? changelog, List hosts = const [], bool? showUncaughtErrors})` | | `DevTools.httpHooks`, `DevTools.clearUserData()` | as the base note | +| `Redaction` | `Redaction.standard.extend(headers: …, fieldParts: …, exactFields: …, maxBodyBytes: …)`, `withHeaders(names)`, `isSensitive(name)`, `isSensitiveHeader(name)`, `redactHeaders(Map>)`, `redactUrl(url)`, `redactBody(List? bytes, String? contentType)`, `Redaction.maskSecret(value)`. The constructor is private and the rule sets are unmodifiable, so the only way to new rules is extending the defaults. | +| `RecordedBody` | `sealed`: `NoBody`, `TextBody(text, size:, truncated:, masked:)`, `BinaryBody(contentType, size)` | +| `DevTools.replay` | `static Future replay(NetworkRecord record)`, through the `Dio` the hooks were installed in | ### 4. Build steps {#dart-4-build-steps}