Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 70 additions & 4 deletions docs/DESIGN_SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -232,6 +232,63 @@ must recompute mid-scroll rather than assume) — see §9.
- **Toolbar** (`.toolbar`): flex row, wraps, `align-items: flex-end` so label-stacked fields
(uppercase label over input) share a bottom baseline with bare buttons. (This was a bug — see §9.)

## 4a. Detail pane anatomy (split views)

Four of the five split views build their right-hand pane from one shared helper (`detailHeadHtml`) —
Network, WebSockets, Push and Crashes. Timeline hand-rolls its own head from the same classes and
is the odd one out; folding it into the helper is an open item (§9).

```
┌ .detail-head ────────────────────────────────────────────────┐
│ [BADGE] [MOCK] title (mono, ellipsis) STATUS [⤢] [⋮] │ head row
│ ‹facts strip — see table below› │ .detail-facts
│ ‹actions row — see table below› │ .detail-actions-row
│ Summary │ Request & response │ Headers │ … [Stacked] │ .detail-tabs
├ .detail-find (compare/diff tabs only) ───────────────────────┤
│ Find in headers, payload and response… N matches │
├ .detail-body (scrolls) ──────────────────────────────────────┤
│ ┌ .sbs-pane ────────┐ ┌ .sbs-pane ────────┐ │ .sbs-grid
│ │ ● Request [Copy] │ │ ● Response [Copy] │ │
│ │ › Request headers │ │ › Response headers│ │ collapsed
│ │ ⌄ Payload │ │ ⌄ Body │ │ expanded
│ └───────────────────┘ └───────────────────┘ │
│ redaction footnote │
└──────────────────────────────────────────────────────────────┘
```

**Two variants of the head's middle band.** The facts strip and the actions row are per-pane
choices, not fixed furniture:

| Pane | Facts strip | Actions |
|---|---|---|
| **Network** | none — folded into the Summary tab | kebab **⋮** menu, right of the expand button |
| WebSockets, Push, Crashes | `.detail-facts` row under the title | flat `.detail-actions-row` |

The kebab is opt-in via `detailHeadHtml`'s `actionsMenu` flag. Network carries up to seven actions
(flag, pin, resend, clone, mock *or* unmock, cURL, fetch) — a full row of buttons for controls
used occasionally, not per-capture. The other panes carry two or three, where a row costs nothing
and a menu would only add a click. Menu items keep the same `data-detail-action` ids as row
buttons, so a pane's delegated click handler is identical either way. The panel is
`position: fixed` (placed by `positionDetailMenuPanel()`) because `.detail-pane-v2` is
`overflow: hidden` and an absolutely positioned popup clips at the pane edge — the same trade
`.drop-panel` makes. It closes on pick, outside click, and Escape (returning focus to its button).

**Network's tab order** is `Summary · Request & response · [Diff vs baseline] · Headers · Timing ·
Related events`. Summary leads because it absorbed the head's old facts strip and is the "what is
this capture" view: time, duration, request url/method, response status, `response.error` on a
failure, content type, correlation id, mock rule (a link into Mocks), vs-original field count, and
tags. Diff only appears once a baseline is pinned. **Default selection is Request & response**, not
the first tab — the body is what an engineer opens a capture to read.

Consequently Network's two compare panes hold only headers and body; they have no "General" group,
because everything it used to duplicate now lives one tab left. Group collapse defaults come from
`detailGroupHtml`: `Payload`/`Body` open, everything else collapsed, an explicit user toggle always
winning over the default.

**Simple mode** hides the Headers/Timing/Related tabs outright, and hides individual actions that
carry `hideInSimple` (`fetch` always; `pin` only while no baseline is pinned, so a pinned baseline
can never be stranded behind a mode switch).

## 4b. Layout (Android in-app inspector)

- **Bottom nav, 4 destinations:** `01 Observe · 02 Control · 03 Data · 04 More` (numbered + label,
Expand Down Expand Up @@ -300,7 +357,9 @@ tray screen becomes a natural addition, just not one this pass builds.
- **Segmented control** (`.seg`): joined buttons, one active (signal).
- **Chips / chip-row** (`.chip-row`): wrapping pill filters.
- **Cards** (`.card`): panel surface, 1px `--line`, 16px pad, `h2` with small leading icon.
- **Split panes:** `.list` (rows) + `.splitter` + `.detail-pane` (min-width 300px).
- **Split panes:** `.list-pane` (rows) + `.splitter` (5px) + `.detail-pane-v2`, inside `.split-shell`
(min 360px per column). Detail-pane anatomy — head, facts/actions variants, tabs, find bar,
side-by-side groups — is specified in §4a.
- **Data table** (`.db-table`): real `<table>`, `<th scope=col>`, truncation via `.db-truncated`,
horizontal scroll in `.db-table-wrap`.
- **Empty states** (`.empty-state`): centered icon + title + sub. Used widely — design these well;
Expand All @@ -317,9 +376,10 @@ tray screen becomes a natural addition, just not one this pass builds.

1. **Overview** — landing / status summary, connect prompt when unauthenticated, and the
previous-run-crashed banner (see [CRASH_AND_ANR.md](CRASH_AND_ANR.md#the-previous-run-crashed-banner)).
2. **Network** — captured HTTP list + detail; toolbar (search, status seg, method seg, Apply, Clear,
HAR, Postman); detail action row (Clone to composer, cURL, fetch, JSON, Related events); redacted
metadata pane.
2. **Network** — captured HTTP list + detail; toolbar (search, status seg, method seg, service drop,
HAR, Postman, Clear) over a "More filters" disclosure; redacted metadata pane whose actions
(flag, pin, resend, clone, mock/unmock, cURL, fetch) live in the head's **⋮ menu** and whose tabs
lead with Summary — see §4a.
3. **WebSockets** — socket sessions (URL, STATE/SENT/RECV), frame list per socket.
4. **Timeline** — unified event timeline (search).
5. **Crashes** — crash/ANR list + detail: kind/thread badges, breadcrumb strip, the all-thread dump
Expand Down Expand Up @@ -427,6 +487,10 @@ The final web visual contract relies on a rigid separation of concerns. `dashboa
next step: the device's More screen, the `adb forward tcp:8080 tcp:8080` command (with its caveat
that 8080 is only the first port tried), and the two browser access modes: a bare URL by default or
the `#code=` credential when SESSION_CODE is selected.
- **Network's detail head carried three stacked strips** (facts, actions, tabs) before the panes
even started, each duplicating something already on screen — the facts repeated the compare
panes' "General" groups. Facts moved into the Summary tab, the General groups went away, the
actions row became a ⋮ menu, and Summary was ordered first. See §4a.
- **Cross-surface parity was undecided** — resolved and documented in §4c, with a full 16-row table
of which web views the Android inspector mirrors, which it deliberately doesn't (Composer, capture
rules, Overview), and one open naming mismatch (Timeline / Logs) left as a documented gap rather
Expand All @@ -435,6 +499,8 @@ The final web visual contract relies on a rigid separation of concerns. `dashboa
**Open / worth a design eye:**
- **Table/detail density** on Network/Database detail panes — readability at scale — is still
unaddressed by this pass.
- **Timeline's detail head is hand-rolled** rather than built from `detailHeadHtml` like the other
three split views (§4a), so it drifts from them silently whenever the shared helper changes.
- **The Timeline / Logs naming mismatch** (§4c) — same underlying event stream, different name on
each surface. Documented, not fixed; fixing it is a code change (renaming `ObserveTab.LOGS` or the
web view, or both to a shared name), out of scope for a documentation-only pass.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -112,14 +112,33 @@ import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import kotlinx.coroutines.withContext
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody
import org.eclipse.paho.client.mqttv3.MqttAsyncClient
import org.eclipse.paho.client.mqttv3.MqttConnectOptions
import org.eclipse.paho.client.mqttv3.persist.MemoryPersistence
import java.io.File
import java.util.concurrent.atomic.AtomicInteger

/** Public read endpoint: answers gzipped and chunked, which is what the capture tee is built for. */
private const val SAMPLE_GET_URL = "https://jsonplaceholder.typicode.com/todos/1"

/**
* Public write endpoint. It echoes the posted object back with an `id`, so one tap produces a
* capture carrying a real request body *and* a real response body -- the pair every other sample
* action leaves half empty, and the only way to exercise the request side of the inspector
* (payload viewer, cURL/fetch reproduction, mock-from-request) against live traffic.
*
* Nothing is persisted: jsonplaceholder fakes the write and always answers 201 with id 101.
*/
private const val SAMPLE_POST_URL = "https://jsonplaceholder.typicode.com/posts"

/** Sent by [SampleActivity.sendJsonPost]; small enough to read whole in either inspector. */
private const val SAMPLE_POST_BODY =
"""{"title":"DevConsole sample","body":"Posted from the compose sample app","userId":9912837}"""

private const val SHOW_ORDER_HISTORY_FLAG = "compose_sample.show_order_history"
private const val MOCK_RULE_ID = "compose-sample-orders"

Expand Down Expand Up @@ -251,7 +270,12 @@ private fun devConsoleStatusText(
* owns the server lifecycle and builds its own launch surface on top of [DevConsole.state], but can
* also drop into the SDK's own in-app inspector (More screen QR, Data rail, exports) via
* [DevConsole.open].
*
* Carries one private method per capability it demonstrates (GET, POST, Ktor, MQTT, screenshot,
* push, ...), which is what the `TooManyFunctions` suppression below covers: splitting them across
* helper classes would put each demonstration somewhere other than the screen that offers it.
*/
@Suppress("TooManyFunctions") // One private method per capability demonstrated; see the class doc.
class MainActivity : ComponentActivity() {
private val socketClient = OkHttpClient()

Expand All @@ -274,9 +298,14 @@ class MainActivity : ComponentActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
DevConsole.initialize(application, buildConfig())
// Mock rules are SESSION-scoped and dropped whenever the embedded server restarts (fresh
// session), so the rule is (re)installed from the Running-state observer below rather than
// once here -- a one-shot install here would silently stop mocking after any restart.
// Installed here AND re-installed from the Running-state observer below. Both are needed:
// mock rules are SESSION-scoped and DevConsole's stop sequence calls clearSessionRules(),
// so a one-shot install would silently stop mocking after any restart -- but installing
// *only* on Running left the rule missing until the embedded server was first started,
// which made a fresh launch show an empty Mocks list and send "Send mocked request"
// to the real network. Mocking is in-process and needs no server, so it should not wait
// for one.
installMockRule()
seedSampleData(applicationContext)

setContent {
Expand Down Expand Up @@ -399,7 +428,7 @@ class MainActivity : ComponentActivity() {
if (state is DevConsoleState.Running) {
endpoint = DevConsole.endpoint()
// Re-seed on every Running transition (first start AND every restart) -- see the
// comment in onCreate for why a one-shot install at init isn't enough.
// comment in onCreate for why the install there isn't enough on its own.
installMockRule()
// Poll while running so either access mode updates the displayed URL after a restart;
// SESSION_CODE also re-issues the code after a browser consumes it.
Expand Down Expand Up @@ -505,16 +534,20 @@ class MainActivity : ComponentActivity() {

SectionLabel("Exercise the SDK")
CapabilityCard(
title = "Send network request",
title = "Send GET request",
subtitle = "OkHttp interceptor -- chunked response, body captured via the tee",
onClick = {
scope.launch {
lastResponse =
sendRequest("https://jsonplaceholder.typicode.com/todos/1", "Network response")
lastResponse = sendRequest(SAMPLE_GET_URL, "GET response")
showOrderHistory = DevConsole.featureFlagValue(SHOW_ORDER_HISTORY_FLAG)
}
},
)
CapabilityCard(
title = "Send POST request",
subtitle = "JSON request body and JSON response body -- both captured on the same transaction",
onClick = { scope.launch { lastResponse = sendJsonPost() } },
)
CapabilityCard(
title = "Send Ktor request",
subtitle = "Ktor plugin on the CIO engine -- request and response bodies, no OkHttp involved",
Expand Down Expand Up @@ -630,6 +663,37 @@ class MainActivity : ComponentActivity() {
}
}

/**
* Posts [SAMPLE_POST_BODY] to [SAMPLE_POST_URL] through the same instrumented client the GET
* card uses, so the capture carries both bodies.
*
* The request body goes through OkHttp's own `RequestBody`, not a pre-serialized string handed
* to the recorder: the capture interceptor reads what OkHttp actually writes to the wire, so
* what the inspector shows is the request as sent rather than as intended. `Content-Type` comes
* from the media type here (not a manual header) for the same reason -- it is the one the call
* really carries.
*/
private suspend fun sendJsonPost(): String =
withContext(Dispatchers.IO) {
requestCount.incrementAndGet()
try {
val request =
Request
.Builder()
.url(SAMPLE_POST_URL)
.post(SAMPLE_POST_BODY.toRequestBody("application/json; charset=utf-8".toMediaType()))
.build()
instrumentedClient.newCall(request).execute().use { response ->
val body = response.body?.string().orEmpty()
"POST response: ${response.code} (${body.length} chars)"
}
} catch (cancellation: kotlinx.coroutines.CancellationException) {
throw cancellation
} catch (error: Exception) {
"POST failed: ${error.message ?: error.javaClass.simpleName}"
}
}

/**
* Issues one request through the sample's Ktor client, whose debug build installs
* `DevConsoleKtorClientPlugin` (see `SampleKtorClient` in `src/debug`).
Expand Down
Loading
Loading