diff --git a/docs/internal/development/guide/01-foundations/01-architecture.mdx b/docs/internal/development/guide/01-foundations/01-architecture.mdx index bd5324c..959cac0 100644 --- a/docs/internal/development/guide/01-foundations/01-architecture.mdx +++ b/docs/internal/development/guide/01-foundations/01-architecture.mdx @@ -82,6 +82,7 @@ flowchart BT RP --> ST DT[sinew_devtools] --> NW DT --> ST + DT --> EX DU[sinew_devtools_ui] --> DT DU --> L10 L10[sinew_l10n] --> EX @@ -95,7 +96,7 @@ flowchart BT | Only `sinew_camouflage` knows Camouflage, and Camouflage never knows Sinew | Either library can be used without the other | | `sinew_testing` is a test-only dependency | Fakes never reach production code | | Network and storage expose hook points (`SinewHttpHooks`, `InspectableStore`) that do nothing until devtools pass real hooks. `sinew_devtools` depends on network and storage to provide those hooks; network and storage never depend on devtools. | Production code paths don't change when devtools are absent, and devtools are an opt-in dependency | -| The adapters depend on exception (`toViewState` creates `UnexpectedException`); the glue depends on l10n (its convenience overload reads Sinew's localizer); `sinew_riverpod_providers` reaches security through storage | Every edge used in code is in this graph, so the CI graph check can enforce it | +| The adapters depend on exception (`toViewState` creates `UnexpectedException`); the glue depends on l10n (its convenience overload reads Sinew's localizer); devtools depends on exception (`DevToolsCrashReporter` wraps the app's `CrashReporter`, and the Exception Log reads `SinewException`); `sinew_riverpod_providers` reaches security through storage | Every edge used in code is in this graph, so the CI graph check can enforce it | #### Mechanism vs. configuration 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 82281d3..8fc79a9 100644 --- a/docs/internal/development/guide/02-packages/11-dev-tools.mdx +++ b/docs/internal/development/guide/02-packages/11-dev-tools.mdx @@ -127,6 +127,13 @@ Redaction( | `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 | +| Recording rule | Why | +|---|---| +| A repeat is merged when its type, code, message and source match a row last seen within the window, measured from that row's **last** occurrence, and the merged row moves to the top | A retry loop failing every second stays one row with a rising count, instead of filling the log | +| An exception's message and stack trace (with its cause) go through `Redaction.redactText`: `Bearer` and `Basic` credentials, and `name=value` and JSON `"name": value` pairs whose names are sensitive | A plain error's message often carries the URL it failed on, `?token=…` included | +| The network recorder takes the exchange **before** redaction and keeps only the redacted record | One place redacts, so no caller can store a raw value by mistake | +| A recording failure never stops the app's own handlers or the real crash reporter | Devtools must never change what the app does | + 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. @@ -380,6 +387,10 @@ As the base note. Kotlin specifics: | `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 | +| `NetworkRecorder` | `NetworkRecorder(capacity = 200, redaction = Redaction.Default)`, `records: StateFlow>` (newest first), `record(NetworkExchange): NetworkRecord`, `recordCacheServe(key, source, body, contentType, at)`, `clear()` | +| `NetworkExchange` | the raw exchange the hooks hand over: method, URL, headers and bodies before redaction, status, `startedAt`, `duration`, `error`, `clientHeaders` (the client's `defaultHeaders` names), `isReplay` | +| `ExceptionRecorder` | `ExceptionRecorder(capacity = 50, dedupeWindow = 2.seconds, redaction, clock: kotlin.time.Clock)`, `records: StateFlow>`, `record(error: Throwable, source = Reported)`, `clear()` | +| `DevTools` | `object DevTools { network; exceptions; coroutineHandler; captureUncaughtErrors(); clearUserData() }`; `open()`/`close()`/`replay` arrive with the UI and hooks | | `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} @@ -488,6 +499,10 @@ EXIF, camera and map playgrounds are separate packages. Flutter links every plug | `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)` | +| `NetworkRecorder` | `NetworkRecorder({int capacity = 200, Redaction? redaction})`, `ValueListenable> records` (newest first, unmodifiable), `record(NetworkExchange)`, `recordCacheServe(key, source, {body, contentType, at})`, `clear()` | +| `ExceptionRecorder` | `ExceptionRecorder({capacity = 50, dedupeWindow = Duration(seconds: 2), redaction, DateTime Function()? clock})`, `records`, `record(Object error, StackTrace? stack, {source})`, `clear()` | +| `DevTools` | `abstract final class` with `static network`, `exceptions`, `captureUncaughtErrors()`, `clearUserData()` | +| Dependencies | `sinew_devtools` imports `sinew_exception` (`CrashReporter`) and `sinew_models` (`SinewException`) directly, so both are declared and in the graph: Dart needs a direct dependency for every import, where Kotlin reaches them through `sinew-network`'s `api` | | `DevTools.replay` | `static Future replay(NetworkRecord record)`, through the `Dio` the hooks were installed in | ### 4. Build steps {#dart-4-build-steps}