recovery-probe 1.0.0 → 1.1.0-preview.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +5 -0
- package/dist/cli/observe.mjs +1 -0
- package/dist/transports/http/observer.d.mts +4 -1
- package/dist/transports/http/observer.mjs +12 -2
- package/dist/transports/http/read-log.d.mts +22 -0
- package/dist/transports/http/read-log.mjs +36 -0
- package/dist/workflows/observe/adapters.d.mts +3 -0
- package/dist/workflows/observe/adapters.mjs +7 -1
- package/dist/workflows/observe/capture.mjs +39 -52
- package/dist/workflows/observe/config.d.mts +2 -0
- package/dist/workflows/observe/config.mjs +6 -46
- package/dist/workflows/observe/operator.d.mts +13 -0
- package/dist/workflows/observe/operator.mjs +50 -0
- package/dist/workflows/observe/recorder.d.mts +11 -1
- package/dist/workflows/observe/recorder.mjs +39 -2
- package/dist/workflows/observe/report.d.mts +3 -0
- package/dist/workflows/observe/sample.d.mts +1 -0
- package/dist/workflows/observe/sample.mjs +1 -1
- package/dist/workflows/observe/slow-reads/bridge.d.mts +26 -0
- package/dist/workflows/observe/slow-reads/bridge.mjs +81 -0
- package/dist/workflows/observe/slow-reads/config.d.mts +13 -0
- package/dist/workflows/observe/slow-reads/config.mjs +26 -0
- package/dist/workflows/observe/slow-reads/evidence.d.mts +75 -0
- package/dist/workflows/observe/slow-reads/evidence.mjs +142 -0
- package/dist/workflows/observe/slow-reads/probe.d.mts +29 -0
- package/dist/workflows/observe/slow-reads/probe.mjs +54 -0
- package/dist/workflows/observe/slow-reads/renderer-load.d.mts +23 -0
- package/dist/workflows/observe/slow-reads/renderer-load.mjs +47 -0
- package/dist/workflows/observe/slow-reads/summary.d.mts +8 -0
- package/dist/workflows/observe/slow-reads/summary.mjs +61 -0
- package/dist/workflows/observe/summaries.mjs +1 -0
- package/dist/workflows/observe/target-config.d.mts +3 -0
- package/dist/workflows/observe/target-config.mjs +49 -0
- package/docs/android.md +1 -0
- package/docs/observe.md +52 -1
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,11 @@ All notable changes to Recovery Probe are documented here. The project follows [
|
|
|
4
4
|
|
|
5
5
|
Version 0.2.0 is the first npm release. Earlier 0.1.x revisions were repository-only prototypes.
|
|
6
6
|
|
|
7
|
+
## 1.1.0-preview.1 (2026-10-27)
|
|
8
|
+
|
|
9
|
+
- `observe` with `slowReads` explains slow screens over HTTP. For each read it records when it started and finished, how long the network took, when its content first showed, and how busy the page's main thread was in between. Optionally it also counts the requests waiting on a page bridge, such as an Android WebMessageListener object. A `SLOW_READ` lead says whether the time went to the network, to a busy main thread or to something else.
|
|
10
|
+
- With `slowReads`, a screen read that takes longer than 5 seconds no longer ends the capture, and HTTP captures can run for up to 10 minutes. IPC captures keep the 2-minute limit set by the development hook.
|
|
11
|
+
|
|
7
12
|
## 1.0.0 (2026-10-27)
|
|
8
13
|
|
|
9
14
|
The first release with an explicit 1.x compatibility commitment. It removes the old command spellings and brings in everything since 0.6.0: the 0.7.0 and 0.8.0 previews below. The README defines the supported interfaces and experimental exceptions, and explains that failed checks can save unredacted screen-text quotes of up to 200 characters.
|
package/dist/cli/observe.mjs
CHANGED
|
@@ -21,6 +21,8 @@ export interface HttpObserverOptions {
|
|
|
21
21
|
times?: number;
|
|
22
22
|
/** Matching reads that pass before the first fault: 1 fails the 2nd read. */
|
|
23
23
|
skip?: number;
|
|
24
|
+
/** Keep a record per read of `endpoint`. Only for runs without a fault. */
|
|
25
|
+
logReads?: boolean;
|
|
24
26
|
}
|
|
25
27
|
/** A request the page made, and whether it could be or was selected for a fault. */
|
|
26
28
|
export interface ReadCoverage {
|
|
@@ -34,7 +36,7 @@ export interface ReadCoverage {
|
|
|
34
36
|
export declare function observeHttp(page: Page, options: HttpObserverOptions): Promise<HttpObserver>;
|
|
35
37
|
declare class HttpObserver {
|
|
36
38
|
#private;
|
|
37
|
-
constructor(page: Page, { endpoint, requiredEndpoints, fault, times, skip, }: HttpObserverOptions);
|
|
39
|
+
constructor(page: Page, { endpoint, requiredEndpoints, fault, times, skip, logReads, }: HttpObserverOptions);
|
|
38
40
|
attach(): Promise<void>;
|
|
39
41
|
snapshot(): {
|
|
40
42
|
startedAt: number;
|
|
@@ -49,6 +51,7 @@ declare class HttpObserver {
|
|
|
49
51
|
channels: Record<string, ReadChannelStats>;
|
|
50
52
|
};
|
|
51
53
|
coverage(): ReadCoverage[];
|
|
54
|
+
readLog(): import("./read-log.mjs").ReadLogSnapshot | undefined;
|
|
52
55
|
/** Stops faulting and waits for the injected responses. */
|
|
53
56
|
disarm(): Promise<void>;
|
|
54
57
|
/** Disarms, then stops listening. */
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { performance } from 'node:perf_hooks';
|
|
2
2
|
import { pageIdentity } from '../../core/urls.mjs';
|
|
3
3
|
import { fulfillFault } from './route.mjs';
|
|
4
|
+
import { ReadLog } from './read-log.mjs';
|
|
4
5
|
const MAX_COVERAGE = 100;
|
|
5
6
|
const emptyRow = () => ({
|
|
6
7
|
calls: 0,
|
|
@@ -32,6 +33,7 @@ class HttpObserver {
|
|
|
32
33
|
#requests = new Map();
|
|
33
34
|
#coverage = new Map();
|
|
34
35
|
#operations = new Set();
|
|
36
|
+
#readLog;
|
|
35
37
|
#skipped = 0;
|
|
36
38
|
#reserved = 0;
|
|
37
39
|
#applied = 0;
|
|
@@ -40,7 +42,7 @@ class HttpObserver {
|
|
|
40
42
|
#active = true;
|
|
41
43
|
#injectionError = false;
|
|
42
44
|
#routed;
|
|
43
|
-
constructor(page, { endpoint, requiredEndpoints = [], fault, times = 1, skip = 0, }) {
|
|
45
|
+
constructor(page, { endpoint, requiredEndpoints = [], fault, times = 1, skip = 0, logReads = false, }) {
|
|
44
46
|
this.#page = page;
|
|
45
47
|
this.#endpoint = endpoint;
|
|
46
48
|
this.#fault = fault;
|
|
@@ -49,6 +51,7 @@ class HttpObserver {
|
|
|
49
51
|
this.#channels = Object.fromEntries([endpoint, ...requiredEndpoints].map((e) => [e, emptyRow()]));
|
|
50
52
|
this.#startedAt = Date.now();
|
|
51
53
|
this.#routed = Boolean(fault);
|
|
54
|
+
this.#readLog = logReads && !fault ? new ReadLog() : undefined;
|
|
52
55
|
}
|
|
53
56
|
async attach() {
|
|
54
57
|
const page = this.#page;
|
|
@@ -82,6 +85,9 @@ class HttpObserver {
|
|
|
82
85
|
coverage() {
|
|
83
86
|
return [...this.#coverage.values()];
|
|
84
87
|
}
|
|
88
|
+
readLog() {
|
|
89
|
+
return this.#readLog?.snapshot();
|
|
90
|
+
}
|
|
85
91
|
/** Stops faulting and waits for the injected responses. */
|
|
86
92
|
async disarm() {
|
|
87
93
|
this.#active = false;
|
|
@@ -132,12 +138,14 @@ class HttpObserver {
|
|
|
132
138
|
row.pending++;
|
|
133
139
|
row.firstReadAt ??= Date.now();
|
|
134
140
|
row.lastReadAt = Date.now();
|
|
141
|
+
const target = url === this.#endpoint;
|
|
135
142
|
this.#requests.set(r, {
|
|
136
143
|
row,
|
|
137
144
|
start: performance.now(),
|
|
138
145
|
injected: false,
|
|
139
146
|
afterFault: this.#reserved === this.#times && this.#injectedAt !== null,
|
|
140
|
-
target
|
|
147
|
+
target,
|
|
148
|
+
record: target ? this.#readLog?.start() : undefined,
|
|
141
149
|
});
|
|
142
150
|
}
|
|
143
151
|
#cover(method, url) {
|
|
@@ -171,6 +179,8 @@ class HttpObserver {
|
|
|
171
179
|
row.pending--;
|
|
172
180
|
if (meta.injected)
|
|
173
181
|
return;
|
|
182
|
+
if (meta.record)
|
|
183
|
+
this.#readLog.finish(meta.record, r, response);
|
|
174
184
|
const completed = Date.now();
|
|
175
185
|
row.firstCompletedAt ??= completed;
|
|
176
186
|
row.lastCompletedAt = completed;
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import type { Request, Response } from 'playwright';
|
|
2
|
+
/** One read of the selected endpoint: when it started and finished, and how. */
|
|
3
|
+
export interface ReadRecord {
|
|
4
|
+
startedAt: number;
|
|
5
|
+
completedAt: number | null;
|
|
6
|
+
status: number | null;
|
|
7
|
+
outcome: 'pending' | 'success' | 'error' | 'failed';
|
|
8
|
+
/** Request start to the last response byte, as the browser timed it. */
|
|
9
|
+
networkMs: number | null;
|
|
10
|
+
}
|
|
11
|
+
export interface ReadLogSnapshot {
|
|
12
|
+
reads: ReadRecord[];
|
|
13
|
+
truncated: boolean;
|
|
14
|
+
}
|
|
15
|
+
/** Keeps a record per read, so a slow read can be told apart from a slow screen. */
|
|
16
|
+
export declare class ReadLog {
|
|
17
|
+
#private;
|
|
18
|
+
/** Starts a record, or returns undefined once the log is full. */
|
|
19
|
+
start(): ReadRecord | undefined;
|
|
20
|
+
finish(record: ReadRecord, request: Request, response: Response | null): void;
|
|
21
|
+
snapshot(): ReadLogSnapshot;
|
|
22
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
const MAX_READS = 500;
|
|
2
|
+
/** Keeps a record per read, so a slow read can be told apart from a slow screen. */
|
|
3
|
+
export class ReadLog {
|
|
4
|
+
#reads = [];
|
|
5
|
+
#truncated = false;
|
|
6
|
+
/** Starts a record, or returns undefined once the log is full. */
|
|
7
|
+
start() {
|
|
8
|
+
if (this.#reads.length >= MAX_READS) {
|
|
9
|
+
this.#truncated = true;
|
|
10
|
+
return undefined;
|
|
11
|
+
}
|
|
12
|
+
const record = {
|
|
13
|
+
startedAt: Date.now(),
|
|
14
|
+
completedAt: null,
|
|
15
|
+
status: null,
|
|
16
|
+
outcome: 'pending',
|
|
17
|
+
networkMs: null,
|
|
18
|
+
};
|
|
19
|
+
this.#reads.push(record);
|
|
20
|
+
return record;
|
|
21
|
+
}
|
|
22
|
+
finish(record, request, response) {
|
|
23
|
+
record.completedAt = Date.now();
|
|
24
|
+
record.status = response?.status() ?? null;
|
|
25
|
+
record.outcome = !response ? 'failed' : response.ok() ? 'success' : 'error';
|
|
26
|
+
record.networkMs = networkMs(request);
|
|
27
|
+
}
|
|
28
|
+
snapshot() {
|
|
29
|
+
return { reads: structuredClone(this.#reads), truncated: this.#truncated };
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
// Timing fields are -1 when the browser did not measure them, for example a cache hit.
|
|
33
|
+
function networkMs(request) {
|
|
34
|
+
const { responseEnd } = request.timing();
|
|
35
|
+
return responseEnd >= 0 ? Math.round(responseEnd) : null;
|
|
36
|
+
}
|
|
@@ -3,11 +3,14 @@ import type { IpcInspector } from '../../transports/ipc/inspector.mjs';
|
|
|
3
3
|
import type { ObservationConfig } from './config.mjs';
|
|
4
4
|
import type { ReadSnapshot } from './reads.mjs';
|
|
5
5
|
import type { ObservationMetadata } from './report.mjs';
|
|
6
|
+
import type { ReadLogSnapshot } from '../../transports/http/read-log.mjs';
|
|
6
7
|
export interface ObservationAdapter {
|
|
7
8
|
start(): Promise<void>;
|
|
8
9
|
snapshot(): ReadSnapshot | Promise<ReadSnapshot>;
|
|
9
10
|
stop(): Promise<Record<string, unknown> | undefined>;
|
|
10
11
|
metadata?(): ObservationMetadata['ipcHook'];
|
|
12
|
+
/** A record per read, when the transport keeps one. */
|
|
13
|
+
readLog?(): ReadLogSnapshot | undefined;
|
|
11
14
|
}
|
|
12
15
|
export declare function ipcObservationAdapter(control: IpcInspector, config: ObservationConfig, senderId: number): ObservationAdapter;
|
|
13
16
|
export declare function httpObservationAdapter(page: Page, config: ObservationConfig): ObservationAdapter;
|
|
@@ -94,11 +94,17 @@ export function httpObservationAdapter(page, config) {
|
|
|
94
94
|
let observer;
|
|
95
95
|
return {
|
|
96
96
|
async start() {
|
|
97
|
-
observer = await observeHttp(page, {
|
|
97
|
+
observer = await observeHttp(page, {
|
|
98
|
+
endpoint: config.endpoint,
|
|
99
|
+
logReads: Boolean(config.slowReads),
|
|
100
|
+
});
|
|
98
101
|
},
|
|
99
102
|
snapshot() {
|
|
100
103
|
return observer.snapshot();
|
|
101
104
|
},
|
|
105
|
+
readLog() {
|
|
106
|
+
return observer?.readLog();
|
|
107
|
+
},
|
|
102
108
|
async stop() {
|
|
103
109
|
await observer?.stop();
|
|
104
110
|
return { transport: 'http', listenersDetached: true };
|
|
@@ -7,10 +7,11 @@ import { observationConfig } from './config.mjs';
|
|
|
7
7
|
import { installObserverKit, removeObserverKit } from './kit.mjs';
|
|
8
8
|
import { pageReadInput, pageSelectors } from './page-input.mjs';
|
|
9
9
|
import { ObservationRecorder } from './recorder.mjs';
|
|
10
|
+
import { OperatorRun } from './operator.mjs';
|
|
10
11
|
import { summarizeRows } from './rows.mjs';
|
|
12
|
+
import { SlowReadProbe } from './slow-reads/probe.mjs';
|
|
11
13
|
import { boundedUiRead } from './ui-read.mjs';
|
|
12
14
|
const MAX_INTERVALS = 50;
|
|
13
|
-
const OPERATOR_STOP_MS = 5000;
|
|
14
15
|
/**
|
|
15
16
|
* Observe only. No reload, navigation, routing, focus changes or final UI reset.
|
|
16
17
|
* An optional `operator` function may act on the app (for example explicit --steps); it
|
|
@@ -28,8 +29,8 @@ class Capture {
|
|
|
28
29
|
#recorder;
|
|
29
30
|
#kitToken = randomUUID();
|
|
30
31
|
#readInput;
|
|
31
|
-
#
|
|
32
|
-
#
|
|
32
|
+
#operator = new OperatorRun();
|
|
33
|
+
#slowProbe;
|
|
33
34
|
#started = 0;
|
|
34
35
|
/** Set once the adapter is reading; the capture has a clock from then on. */
|
|
35
36
|
#clock;
|
|
@@ -37,7 +38,6 @@ class Capture {
|
|
|
37
38
|
#pageErrors = 0;
|
|
38
39
|
#newDocument = false;
|
|
39
40
|
#adapterStarted = false;
|
|
40
|
-
#operatorRun;
|
|
41
41
|
#elapsed = () => Math.round(performance.now() - this.#started);
|
|
42
42
|
#countPageError = () => {
|
|
43
43
|
this.#pageErrors++;
|
|
@@ -53,6 +53,9 @@ class Capture {
|
|
|
53
53
|
this.#hooks = hooks;
|
|
54
54
|
this.#recorder = new ObservationRecorder(config);
|
|
55
55
|
this.#readInput = pageReadInput(config, this.#kitToken);
|
|
56
|
+
this.#slowProbe = config.slowReads
|
|
57
|
+
? new SlowReadProbe(page, config.slowReads, this.#kitToken)
|
|
58
|
+
: undefined;
|
|
56
59
|
}
|
|
57
60
|
async run() {
|
|
58
61
|
const report = this.#recorder.report;
|
|
@@ -78,6 +81,7 @@ class Capture {
|
|
|
78
81
|
async #start() {
|
|
79
82
|
const report = this.#recorder.report;
|
|
80
83
|
await this.#installKit();
|
|
84
|
+
await this.#slowProbe?.start();
|
|
81
85
|
this.#page.on('pageerror', this.#countPageError);
|
|
82
86
|
this.#page.on('domcontentloaded', this.#noteDocumentLoad);
|
|
83
87
|
this.#adapterStarted = true;
|
|
@@ -89,7 +93,7 @@ class Capture {
|
|
|
89
93
|
report.startedAt = this.#lastSnapshot.startedAt;
|
|
90
94
|
this.#recorder.openInterval(this.#lastSnapshot, this.#elapsed());
|
|
91
95
|
await this.#hooks.onReady?.();
|
|
92
|
-
this.#
|
|
96
|
+
this.#operator.start(this.#hooks.operator, this.#elapsed);
|
|
93
97
|
}
|
|
94
98
|
/** One renderer call installs the kit and validates every selector, mounted or not. */
|
|
95
99
|
async #installKit() {
|
|
@@ -98,23 +102,6 @@ class Capture {
|
|
|
98
102
|
const validate = pageSelectors(this.#config);
|
|
99
103
|
await boundedUiRead(() => this.#page.evaluate(installObserverKit, { token, actions, validate }), this.#hooks.signal);
|
|
100
104
|
}
|
|
101
|
-
#startOperator() {
|
|
102
|
-
const operator = this.#hooks.operator;
|
|
103
|
-
if (!operator)
|
|
104
|
-
return;
|
|
105
|
-
const abort = this.#operatorAbort;
|
|
106
|
-
const mark = () => new Promise((resolve) => this.#markerRequests.push({ resolve }));
|
|
107
|
-
this.#operatorRun = Promise.resolve()
|
|
108
|
-
.then(() => operator({ mark, signal: abort.signal, elapsed: this.#elapsed }))
|
|
109
|
-
.then((steps) => ({
|
|
110
|
-
status: 'complete',
|
|
111
|
-
...(Array.isArray(steps) ? { steps } : {}),
|
|
112
|
-
}), (error) => ({
|
|
113
|
-
status: abort.signal.aborted ? 'stopped' : 'failed',
|
|
114
|
-
error: error.message,
|
|
115
|
-
...(Array.isArray(error.results) ? { steps: error.results } : {}),
|
|
116
|
-
}));
|
|
117
|
-
}
|
|
118
105
|
async #sampleUntilDone() {
|
|
119
106
|
const report = this.#recorder.report;
|
|
120
107
|
const { observationMs, sampleMs } = this.#config;
|
|
@@ -135,13 +122,8 @@ class Capture {
|
|
|
135
122
|
await sleep(waitMs);
|
|
136
123
|
}
|
|
137
124
|
}
|
|
138
|
-
#nextMarker() {
|
|
139
|
-
if (this.#markerRequests.length)
|
|
140
|
-
return this.#markerRequests.shift();
|
|
141
|
-
return this.#hooks.takeMarker?.() ? {} : null;
|
|
142
|
-
}
|
|
143
125
|
async #openMarkedInterval() {
|
|
144
|
-
const marker = this.#nextMarker();
|
|
126
|
+
const marker = this.#operator.nextMarker(this.#hooks.takeMarker);
|
|
145
127
|
if (!marker)
|
|
146
128
|
return;
|
|
147
129
|
if (this.#recorder.report.intervals.length >= MAX_INTERVALS)
|
|
@@ -160,7 +142,16 @@ class Capture {
|
|
|
160
142
|
const before = await this.#adapter.snapshot();
|
|
161
143
|
const uiStart = performance.now();
|
|
162
144
|
const fromMs = this.#elapsed();
|
|
163
|
-
|
|
145
|
+
// Slow-read evidence waits out a busy renderer: that wait is what it measures.
|
|
146
|
+
const timeoutMs = c.slowReads ? c.observationMs : undefined;
|
|
147
|
+
const signal = this.#hooks.signal;
|
|
148
|
+
const slowProbe = this.#slowProbe;
|
|
149
|
+
const [{ rendererReadMs, rows, actions, ...raw }, load] = await Promise.all([
|
|
150
|
+
boundedUiRead(() => this.#page.evaluate(readRegion, this.#readInput), signal, timeoutMs),
|
|
151
|
+
slowProbe
|
|
152
|
+
? boundedUiRead(() => slowProbe.read(), signal, timeoutMs)
|
|
153
|
+
: null,
|
|
154
|
+
]);
|
|
164
155
|
const summarizeStart = performance.now();
|
|
165
156
|
// A read without text or content (an absent or hidden region) summarizes to itself.
|
|
166
157
|
const ui = summarizeRegion(raw);
|
|
@@ -175,6 +166,7 @@ class Capture {
|
|
|
175
166
|
ui,
|
|
176
167
|
rows: summarizedRows,
|
|
177
168
|
actions,
|
|
169
|
+
load,
|
|
178
170
|
phases: {
|
|
179
171
|
beforeSnapshotMs: uiStart - beforeStart,
|
|
180
172
|
uiRoundTripMs: summarizeStart - uiStart,
|
|
@@ -193,38 +185,33 @@ class Capture {
|
|
|
193
185
|
}
|
|
194
186
|
async #finish() {
|
|
195
187
|
const recorder = this.#recorder;
|
|
196
|
-
this.#
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
188
|
+
const operator = await this.#operator.finish();
|
|
189
|
+
if (operator) {
|
|
190
|
+
recorder.report.operator = operator;
|
|
191
|
+
if (operator.status !== 'complete')
|
|
192
|
+
recorder.gap('OPERATOR_STEPS_INCOMPLETE');
|
|
193
|
+
}
|
|
200
194
|
const elapsedMs = this.#clock ? this.#elapsed() : 0;
|
|
201
195
|
if (recorder.intervalOpen)
|
|
202
196
|
recorder.closeInterval(this.#lastSnapshot, elapsedMs);
|
|
203
197
|
recorder.endSampling(elapsedMs, this.#lastSnapshot);
|
|
204
198
|
this.#page.off('pageerror', this.#countPageError);
|
|
205
199
|
this.#page.off('domcontentloaded', this.#noteDocumentLoad);
|
|
200
|
+
const readLog = this.#adapter.readLog?.();
|
|
201
|
+
await this.#slowProbe?.stop();
|
|
206
202
|
await this.#removeKit();
|
|
207
203
|
await this.#stopAdapter();
|
|
208
|
-
recorder.conclude();
|
|
204
|
+
recorder.conclude(this.#slowReadsEnd(readLog));
|
|
209
205
|
}
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
status: 'stopped',
|
|
220
|
-
error: `Operator did not stop within ${OPERATOR_STOP_MS} ms`,
|
|
221
|
-
}), OPERATOR_STOP_MS);
|
|
222
|
-
}),
|
|
223
|
-
]);
|
|
224
|
-
this.#recorder.report.operator = outcome;
|
|
225
|
-
clearTimeout(timer);
|
|
226
|
-
if (outcome.status !== 'complete')
|
|
227
|
-
this.#recorder.gap('OPERATOR_STEPS_INCOMPLETE');
|
|
206
|
+
#slowReadsEnd(readLog) {
|
|
207
|
+
const probe = this.#slowProbe;
|
|
208
|
+
if (!probe || !this.#clock)
|
|
209
|
+
return undefined;
|
|
210
|
+
return {
|
|
211
|
+
readLog,
|
|
212
|
+
probe: probe.status,
|
|
213
|
+
startedEpoch: this.#clock.startedEpoch,
|
|
214
|
+
};
|
|
228
215
|
}
|
|
229
216
|
// Bounded: a replaced or unresponsive document must not delay owned IPC cleanup.
|
|
230
217
|
async #removeKit() {
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { type SelectorSpec } from '../../core/selector.mjs';
|
|
2
2
|
import type { ObservedActionConfig } from './kit.mjs';
|
|
3
|
+
import { type SlowReadsConfig } from './slow-reads/config.mjs';
|
|
3
4
|
export interface RowsConfig {
|
|
4
5
|
selector: SelectorSpec;
|
|
5
6
|
key?: SelectorSpec;
|
|
@@ -31,6 +32,7 @@ export interface ObservationConfig {
|
|
|
31
32
|
contentSelector: SelectorSpec;
|
|
32
33
|
rows?: RowsConfig;
|
|
33
34
|
actions?: ObservedActionConfig[];
|
|
35
|
+
slowReads?: SlowReadsConfig;
|
|
34
36
|
lagThresholdMs: number;
|
|
35
37
|
minUnchangedReads: number;
|
|
36
38
|
detail: 'content' | 'region';
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { ensure, ensureRanges, isIntegerIn, isNonEmptyString, isRecord, isUnique, withDefaults, } from '../../core/validate.mjs';
|
|
2
2
|
import { selectorSpec } from '../../core/selector.mjs';
|
|
3
|
-
|
|
3
|
+
import { slowReadsConfig } from './slow-reads/config.mjs';
|
|
4
|
+
import { hasOnlyKeys, validateHttpTarget, validateIpcTarget, } from './target-config.mjs';
|
|
4
5
|
const NAME = /^[\w.-]{1,40}$/;
|
|
5
6
|
/** Every state label a row can have besides 'none' and 'other'. */
|
|
6
7
|
export const stateLabels = (r) => [
|
|
@@ -21,6 +22,7 @@ const DEFAULTS = {
|
|
|
21
22
|
contentSelector: undefined,
|
|
22
23
|
rows: undefined,
|
|
23
24
|
actions: undefined,
|
|
25
|
+
slowReads: undefined,
|
|
24
26
|
lagThresholdMs: 2000,
|
|
25
27
|
minUnchangedReads: 2,
|
|
26
28
|
detail: 'content',
|
|
@@ -28,7 +30,7 @@ const DEFAULTS = {
|
|
|
28
30
|
sampleMs: 100,
|
|
29
31
|
};
|
|
30
32
|
const RANGES = [
|
|
31
|
-
['observationMs', 500,
|
|
33
|
+
['observationMs', 500, 600000],
|
|
32
34
|
['sampleMs', 50, 1000],
|
|
33
35
|
['lagThresholdMs', 500, 60000],
|
|
34
36
|
['minUnchangedReads', 1, 20],
|
|
@@ -47,6 +49,8 @@ export function observationConfig(input) {
|
|
|
47
49
|
c.rows = rowsConfig(c.rows);
|
|
48
50
|
if (c.actions !== undefined)
|
|
49
51
|
c.actions = actionsConfig(c.actions);
|
|
52
|
+
if (c.slowReads !== undefined)
|
|
53
|
+
c.slowReads = slowReadsConfig(c.slowReads);
|
|
50
54
|
if (c.transport === 'http')
|
|
51
55
|
validateHttpTarget(c);
|
|
52
56
|
else
|
|
@@ -57,10 +61,6 @@ const isLoopbackDevtools = (url) => ['http:', 'ws:'].includes(url.protocol) &&
|
|
|
57
61
|
['localhost', '127.0.0.1', '[::1]'].includes(url.hostname) &&
|
|
58
62
|
!url.username &&
|
|
59
63
|
!url.password;
|
|
60
|
-
// Arrays pass too; the checks that follow it reject them.
|
|
61
|
-
const hasOnlyKeys = (value, keys) => Boolean(value) &&
|
|
62
|
-
typeof value === 'object' &&
|
|
63
|
-
Object.keys(value).every((key) => keys.includes(key));
|
|
64
64
|
function actionsConfig(value) {
|
|
65
65
|
ensure(Array.isArray(value) && value.length > 0 && value.length <= 20, 'actions must list 1–20 { name, selector } entries');
|
|
66
66
|
const actions = value.map((action, i) => {
|
|
@@ -74,46 +74,6 @@ function actionsConfig(value) {
|
|
|
74
74
|
ensure(isUnique(actions.map((action) => action.name)), 'action names must be unique');
|
|
75
75
|
return actions;
|
|
76
76
|
}
|
|
77
|
-
function validateHttpTarget(c) {
|
|
78
|
-
const url = new URL(c.endpoint);
|
|
79
|
-
ensure(['http:', 'https:'].includes(url.protocol) &&
|
|
80
|
-
!url.username &&
|
|
81
|
-
!url.password &&
|
|
82
|
-
!url.search &&
|
|
83
|
-
!url.hash, 'endpoint must be HTTP(S) origin/path without credentials, query or fragment');
|
|
84
|
-
c.endpoint = url.href;
|
|
85
|
-
ensure(c.channel === undefined &&
|
|
86
|
-
c.methods === undefined &&
|
|
87
|
-
c.dataEvents === undefined, 'channel, methods and dataEvents are only supported with IPC');
|
|
88
|
-
}
|
|
89
|
-
function validateIpcTarget(c) {
|
|
90
|
-
ensure(isNonEmptyString(c.channel), 'channel is required');
|
|
91
|
-
ensure(c.endpoint === undefined && c.page === undefined && c.pageUrl === undefined, 'IPC selects the window owned by its development hook');
|
|
92
|
-
if (c.methods !== undefined)
|
|
93
|
-
c.methods = labels(c.methods, 'methods');
|
|
94
|
-
if (c.dataEvents !== undefined)
|
|
95
|
-
c.dataEvents = dataEventsConfig(c.dataEvents);
|
|
96
|
-
}
|
|
97
|
-
function dataEventsConfig(value) {
|
|
98
|
-
const message = 'dataEvents must be { channel, methods? }';
|
|
99
|
-
ensure(hasOnlyKeys(value, ['channel', 'methods']), message);
|
|
100
|
-
const events = value;
|
|
101
|
-
ensure(isNonEmptyString(events.channel), message);
|
|
102
|
-
return {
|
|
103
|
-
channel: events.channel,
|
|
104
|
-
...(events.methods === undefined
|
|
105
|
-
? {}
|
|
106
|
-
: { methods: labels(events.methods, 'dataEvents.methods') }),
|
|
107
|
-
};
|
|
108
|
-
}
|
|
109
|
-
function labels(value, key) {
|
|
110
|
-
ensure(Array.isArray(value) &&
|
|
111
|
-
value.length > 0 &&
|
|
112
|
-
value.length <= 50 &&
|
|
113
|
-
value.every((v) => typeof v === 'string' && LABEL.test(v)) &&
|
|
114
|
-
isUnique(value), `${key} must list 1–50 unique labels matching ${LABEL}`);
|
|
115
|
-
return [...value];
|
|
116
|
-
}
|
|
117
77
|
const ROW_KEYS = new Set([
|
|
118
78
|
'selector',
|
|
119
79
|
'key',
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import type { ObservationHooks } from './capture.mjs';
|
|
2
|
+
import type { ObservationOperator } from './report.mjs';
|
|
3
|
+
/** Runs the optional operator (for example --steps) beside the capture, with its interval markers. */
|
|
4
|
+
export declare class OperatorRun {
|
|
5
|
+
#private;
|
|
6
|
+
start(operator: ObservationHooks['operator'], elapsed: () => number): void;
|
|
7
|
+
/** The next interval to open: one the operator asked for, or one `takeMarker` reports. */
|
|
8
|
+
nextMarker(takeMarker: ObservationHooks['takeMarker']): {
|
|
9
|
+
resolve?: (index: number | null) => void;
|
|
10
|
+
} | null | undefined;
|
|
11
|
+
/** Stops the operator and returns its outcome, or undefined when there was none. */
|
|
12
|
+
finish(): Promise<ObservationOperator | undefined>;
|
|
13
|
+
}
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
const OPERATOR_STOP_MS = 5000;
|
|
2
|
+
/** Runs the optional operator (for example --steps) beside the capture, with its interval markers. */
|
|
3
|
+
export class OperatorRun {
|
|
4
|
+
#abort = new AbortController();
|
|
5
|
+
#markerRequests = [];
|
|
6
|
+
#run;
|
|
7
|
+
start(operator, elapsed) {
|
|
8
|
+
if (!operator)
|
|
9
|
+
return;
|
|
10
|
+
const abort = this.#abort;
|
|
11
|
+
const mark = () => new Promise((resolve) => this.#markerRequests.push({ resolve }));
|
|
12
|
+
this.#run = Promise.resolve()
|
|
13
|
+
.then(() => operator({ mark, signal: abort.signal, elapsed }))
|
|
14
|
+
.then((steps) => ({
|
|
15
|
+
status: 'complete',
|
|
16
|
+
...(Array.isArray(steps) ? { steps } : {}),
|
|
17
|
+
}), (error) => ({
|
|
18
|
+
status: abort.signal.aborted ? 'stopped' : 'failed',
|
|
19
|
+
error: error.message,
|
|
20
|
+
...(Array.isArray(error.results) ? { steps: error.results } : {}),
|
|
21
|
+
}));
|
|
22
|
+
}
|
|
23
|
+
/** The next interval to open: one the operator asked for, or one `takeMarker` reports. */
|
|
24
|
+
nextMarker(takeMarker) {
|
|
25
|
+
if (this.#markerRequests.length)
|
|
26
|
+
return this.#markerRequests.shift();
|
|
27
|
+
return takeMarker?.() ? {} : null;
|
|
28
|
+
}
|
|
29
|
+
/** Stops the operator and returns its outcome, or undefined when there was none. */
|
|
30
|
+
async finish() {
|
|
31
|
+
this.#abort.abort();
|
|
32
|
+
for (const pending of this.#markerRequests)
|
|
33
|
+
pending.resolve?.(null);
|
|
34
|
+
if (!this.#run)
|
|
35
|
+
return undefined;
|
|
36
|
+
let timer;
|
|
37
|
+
// An operator that ignores the stop signal must not hold cleanup hostage.
|
|
38
|
+
const outcome = await Promise.race([
|
|
39
|
+
this.#run,
|
|
40
|
+
new Promise((resolve) => {
|
|
41
|
+
timer = setTimeout(() => resolve({
|
|
42
|
+
status: 'stopped',
|
|
43
|
+
error: `Operator did not stop within ${OPERATOR_STOP_MS} ms`,
|
|
44
|
+
}), OPERATOR_STOP_MS);
|
|
45
|
+
}),
|
|
46
|
+
]);
|
|
47
|
+
clearTimeout(timer);
|
|
48
|
+
return outcome;
|
|
49
|
+
}
|
|
50
|
+
}
|
|
@@ -5,6 +5,8 @@ import { type CaptureReport } from './initial-report.mjs';
|
|
|
5
5
|
import { type ReadSnapshot } from './reads.mjs';
|
|
6
6
|
import { type SamplingTimings } from './sampling.mjs';
|
|
7
7
|
import { type ObservationInterval, type SummarizedRows, type TimelineEvent } from './report.mjs';
|
|
8
|
+
import type { ReadLogSnapshot } from '../../transports/http/read-log.mjs';
|
|
9
|
+
import type { LoadSample, ProbeStatus } from './slow-reads/probe.mjs';
|
|
8
10
|
/** A screen read between two read snapshots, so each read lands in one sample. */
|
|
9
11
|
export interface Sample {
|
|
10
12
|
before: ReadSnapshot;
|
|
@@ -14,6 +16,14 @@ export interface Sample {
|
|
|
14
16
|
rows: SummarizedRows | null;
|
|
15
17
|
actions: RegionRead['actions'];
|
|
16
18
|
phases: SamplingTimings;
|
|
19
|
+
/** Renderer and bridge load, when `slowReads` is configured. */
|
|
20
|
+
load?: LoadSample | null;
|
|
21
|
+
}
|
|
22
|
+
/** What slow-read evidence needs from the end of the capture. */
|
|
23
|
+
export interface SlowReadsEnd {
|
|
24
|
+
readLog: ReadLogSnapshot | undefined;
|
|
25
|
+
probe: ProbeStatus;
|
|
26
|
+
startedEpoch: number;
|
|
17
27
|
}
|
|
18
28
|
/** Capture time: milliseconds since the capture started, and when that was. */
|
|
19
29
|
export interface Clock {
|
|
@@ -35,5 +45,5 @@ export declare class ObservationRecorder {
|
|
|
35
45
|
/** Records how long sampling ran and the last read snapshot, before any cleanup. */
|
|
36
46
|
endSampling(elapsedMs: number, lastSnapshot: ReadSnapshot | undefined): void;
|
|
37
47
|
/** Adds what can only be judged over the whole capture, and whether it is complete. */
|
|
38
|
-
conclude(): void;
|
|
48
|
+
conclude(slowReads?: SlowReadsEnd): void;
|
|
39
49
|
}
|