recovery-probe 1.0.0 → 1.1.0-preview.2
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 +12 -0
- package/README.md +4 -2
- package/dist/cli/observe.mjs +1 -0
- package/dist/core/server.d.mts +3 -1
- package/dist/core/server.mjs +8 -0
- package/dist/targets/cdp-bridge/bridge.mjs +10 -1
- package/dist/targets/cdp-bridge/websocket.d.mts +6 -0
- package/dist/targets/cdp-bridge/websocket.mjs +29 -10
- package/dist/tools/mcp/server.mjs +12 -2
- 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/transports/net/control.mjs +7 -1
- package/dist/transports/net/rules.mjs +2 -1
- 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 +2 -0
- package/docs/ipc.md +1 -1
- package/docs/net.md +3 -2
- package/docs/observe.md +54 -1
- package/package.json +3 -3
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,18 @@ 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.2 (2026-10-28)
|
|
8
|
+
|
|
9
|
+
- Reject browser-origin WebSocket connections and untrusted Host headers on the Android CDP bridge before opening an upstream connection. Validate the network proxy control API's Host header to block DNS rebinding.
|
|
10
|
+
- Bound complete inbound CDP WebSocket messages, including continuation frames, and close oversized messages with code 1009.
|
|
11
|
+
- Suppress MCP tool responses after cancellation and emit `structuredContent` only for object results.
|
|
12
|
+
- Match network host names with or without a final DNS dot. Document wildcard apex behavior, unrestricted local CONNECT tunneling, and the `webContents.send` scope of IPC push counting.
|
|
13
|
+
|
|
14
|
+
## 1.1.0-preview.1 (2026-10-27)
|
|
15
|
+
|
|
16
|
+
- `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.
|
|
17
|
+
- 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.
|
|
18
|
+
|
|
7
19
|
## 1.0.0 (2026-10-27)
|
|
8
20
|
|
|
9
21
|
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/README.md
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
# Recovery Probe
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Stop assuming your code works. Test what actually happens.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Recovery Probe helps developers and AI coding agents discover bugs that ordinary tests can miss. It deliberately triggers failures in web and Electron applications, observes how the UI responds, and produces evidence you can use to reproduce, fix, and verify problems.
|
|
6
|
+
|
|
7
|
+
A failed request should not silently turn a populated screen into “No items found.” Recovery Probe helps you reproduce that failure and check whether the application recovers as expected.
|
|
6
8
|
|
|
7
9
|
[](https://github.com/BojanKovachki/recovery-probe/actions/workflows/validate.yml)
|
|
8
10
|
[](https://www.npmjs.com/package/recovery-probe)
|
package/dist/cli/observe.mjs
CHANGED
package/dist/core/server.d.mts
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
|
-
import type { Server } from 'node:http';
|
|
1
|
+
import type { IncomingMessage, Server } from 'node:http';
|
|
2
|
+
/** Reject DNS aliases and ambiguous authorities before exposing local controls. */
|
|
3
|
+
export declare function hasLoopbackHost(request: IncomingMessage): boolean;
|
|
2
4
|
/** Listens on 127.0.0.1 and returns the port; port 0 picks a free one. */
|
|
3
5
|
export declare function listenOnLoopback(server: Server, port: number): Promise<number>;
|
|
4
6
|
/** Closes the server and the connections it still holds. */
|
package/dist/core/server.mjs
CHANGED
|
@@ -1,3 +1,11 @@
|
|
|
1
|
+
/** Reject DNS aliases and ambiguous authorities before exposing local controls. */
|
|
2
|
+
export function hasLoopbackHost(request) {
|
|
3
|
+
const hosts = request.headersDistinct.host;
|
|
4
|
+
if (hosts?.length !== 1 || !request.socket.localPort)
|
|
5
|
+
return false;
|
|
6
|
+
const port = request.socket.localPort;
|
|
7
|
+
return hosts[0] === `127.0.0.1:${port}` || hosts[0] === `localhost:${port}`;
|
|
8
|
+
}
|
|
1
9
|
/** Listens on 127.0.0.1 and returns the port; port 0 picks a free one. */
|
|
2
10
|
export async function listenOnLoopback(server, port) {
|
|
3
11
|
await new Promise((resolve, reject) => {
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { createServer, } from 'node:http';
|
|
2
|
-
import { closeServer, listenOnLoopback } from '../../core/server.mjs';
|
|
2
|
+
import { closeServer, hasLoopbackHost, listenOnLoopback, } from '../../core/server.mjs';
|
|
3
3
|
import { BRIDGE_ID_BASE, TargetFilter } from './filter.mjs';
|
|
4
4
|
import { acceptWebSocket } from './websocket.mjs';
|
|
5
5
|
/** A page with nothing loaded, as Android keeps for a WebView that has no window yet. */
|
|
@@ -30,6 +30,10 @@ export async function startCdpBridge({ upstream, hide = isBlankPage, port = 0, }
|
|
|
30
30
|
};
|
|
31
31
|
}
|
|
32
32
|
async function answer(context, request, response) {
|
|
33
|
+
if (!hasLoopbackHost(request)) {
|
|
34
|
+
response.writeHead(403).end('Forbidden');
|
|
35
|
+
return;
|
|
36
|
+
}
|
|
33
37
|
try {
|
|
34
38
|
// Clients ask for both /json/version and /json/version/.
|
|
35
39
|
const path = new URL(request.url ?? '/', 'http://bridge').pathname.replace(/\/$/, '');
|
|
@@ -64,6 +68,11 @@ async function visibleTargets(context) {
|
|
|
64
68
|
}
|
|
65
69
|
/** Connects one client to the device's browser endpoint, through a target filter. */
|
|
66
70
|
function bridgeClient(context, peers, request, socket) {
|
|
71
|
+
// Native CDP clients send no Origin. Even an empty or null browser origin is denied.
|
|
72
|
+
if (!hasLoopbackHost(request) || request.headers.origin !== undefined) {
|
|
73
|
+
socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');
|
|
74
|
+
return;
|
|
75
|
+
}
|
|
67
76
|
if (new URL(request.url ?? '/', 'http://bridge').pathname !==
|
|
68
77
|
'/devtools/browser') {
|
|
69
78
|
socket.end('HTTP/1.1 404 Not Found\r\n\r\n');
|
|
@@ -6,3 +6,9 @@ export interface WebSocketPeer {
|
|
|
6
6
|
}
|
|
7
7
|
/** Accepts a WebSocket upgrade (RFC 6455) and delivers its text messages. */
|
|
8
8
|
export declare function acceptWebSocket(request: IncomingMessage, socket: Duplex, onMessage: (text: string) => void, onClose: () => void): WebSocketPeer;
|
|
9
|
+
export declare class ServerWebSocket implements WebSocketPeer {
|
|
10
|
+
#private;
|
|
11
|
+
constructor(socket: Duplex, onMessage: (text: string) => void, onClose: () => void, maxMessage?: number);
|
|
12
|
+
readonly send: (text: string) => void;
|
|
13
|
+
readonly close: (code?: number) => void;
|
|
14
|
+
}
|
|
@@ -27,13 +27,15 @@ function payloadLength(buffered) {
|
|
|
27
27
|
return { length, offset: 2 };
|
|
28
28
|
}
|
|
29
29
|
/** The first whole frame and its size in bytes, or undefined until it has all arrived. */
|
|
30
|
-
function readFrame(buffered) {
|
|
30
|
+
function readFrame(buffered, remaining) {
|
|
31
31
|
if (buffered.length < 2)
|
|
32
32
|
return undefined;
|
|
33
33
|
const header = payloadLength(buffered);
|
|
34
34
|
if (!header)
|
|
35
35
|
return undefined;
|
|
36
|
-
|
|
36
|
+
const opcode = buffered[0] & 0x0f;
|
|
37
|
+
const limit = opcode < 0x8 ? remaining : 125;
|
|
38
|
+
if (header.length > limit)
|
|
37
39
|
return 'too-large';
|
|
38
40
|
const masked = (buffered[1] & 0x80) !== 0;
|
|
39
41
|
const start = header.offset + (masked ? 4 : 0);
|
|
@@ -57,22 +59,26 @@ export function acceptWebSocket(request, socket, onMessage, onClose) {
|
|
|
57
59
|
`Sec-WebSocket-Accept: ${accept}\r\n\r\n`);
|
|
58
60
|
return new ServerWebSocket(socket, onMessage, onClose);
|
|
59
61
|
}
|
|
60
|
-
class ServerWebSocket {
|
|
62
|
+
export class ServerWebSocket {
|
|
61
63
|
#socket;
|
|
62
64
|
#onMessage;
|
|
63
65
|
#onClose;
|
|
66
|
+
#maxMessage;
|
|
64
67
|
#closed = false;
|
|
65
68
|
#buffered = Buffer.alloc(0);
|
|
66
69
|
#message = [];
|
|
67
|
-
|
|
70
|
+
#messageBytes = 0;
|
|
71
|
+
constructor(socket, onMessage, onClose, maxMessage = MAX_MESSAGE) {
|
|
68
72
|
this.#socket = socket;
|
|
69
73
|
this.#onMessage = onMessage;
|
|
70
74
|
this.#onClose = onClose;
|
|
75
|
+
this.#maxMessage = maxMessage;
|
|
71
76
|
socket.on('data', (chunk) => this.#receive(chunk));
|
|
72
77
|
socket.on('close', () => {
|
|
73
78
|
if (this.#closed)
|
|
74
79
|
return;
|
|
75
80
|
this.#closed = true;
|
|
81
|
+
this.#clear();
|
|
76
82
|
this.#onClose();
|
|
77
83
|
});
|
|
78
84
|
socket.on('error', () => socket.destroy());
|
|
@@ -81,11 +87,14 @@ class ServerWebSocket {
|
|
|
81
87
|
if (!this.#closed)
|
|
82
88
|
this.#frame(0x1, Buffer.from(text));
|
|
83
89
|
};
|
|
84
|
-
close = () => {
|
|
90
|
+
close = (code = 1000) => {
|
|
85
91
|
if (this.#closed)
|
|
86
92
|
return;
|
|
87
93
|
this.#closed = true;
|
|
88
|
-
|
|
94
|
+
const payload = Buffer.alloc(2);
|
|
95
|
+
payload.writeUInt16BE(code);
|
|
96
|
+
this.#frame(0x8, payload);
|
|
97
|
+
this.#clear();
|
|
89
98
|
this.#socket.end();
|
|
90
99
|
this.#onClose();
|
|
91
100
|
};
|
|
@@ -93,27 +102,37 @@ class ServerWebSocket {
|
|
|
93
102
|
this.#socket.write(Buffer.concat([frameHeader(opcode, payload.length), payload]));
|
|
94
103
|
}
|
|
95
104
|
#receive(chunk) {
|
|
105
|
+
if (this.#closed)
|
|
106
|
+
return;
|
|
96
107
|
this.#buffered = Buffer.concat([this.#buffered, chunk]);
|
|
97
|
-
|
|
98
|
-
const read = readFrame(this.#buffered);
|
|
108
|
+
while (!this.#closed) {
|
|
109
|
+
const read = readFrame(this.#buffered, this.#maxMessage - this.#messageBytes);
|
|
99
110
|
if (read === undefined)
|
|
100
111
|
return;
|
|
101
112
|
if (read === 'too-large')
|
|
102
|
-
return this.close();
|
|
113
|
+
return this.close(1009);
|
|
103
114
|
this.#buffered = this.#buffered.subarray(read.size);
|
|
104
115
|
if (read.frame.opcode === 0x8)
|
|
105
116
|
return this.close();
|
|
106
117
|
this.#handle(read.frame);
|
|
107
118
|
}
|
|
108
119
|
}
|
|
120
|
+
#clear() {
|
|
121
|
+
this.#buffered = Buffer.alloc(0);
|
|
122
|
+
this.#message = [];
|
|
123
|
+
this.#messageBytes = 0;
|
|
124
|
+
}
|
|
109
125
|
#handle({ fin, opcode, payload }) {
|
|
110
126
|
if (opcode === 0x9)
|
|
111
127
|
this.#frame(0xa, payload);
|
|
112
128
|
else if (opcode === 0x1 || opcode === 0x2 || opcode === 0x0) {
|
|
113
|
-
|
|
129
|
+
if (payload.length)
|
|
130
|
+
this.#message.push(payload);
|
|
131
|
+
this.#messageBytes += payload.length;
|
|
114
132
|
if (fin) {
|
|
115
133
|
const text = Buffer.concat(this.#message).toString('utf8');
|
|
116
134
|
this.#message = [];
|
|
135
|
+
this.#messageBytes = 0;
|
|
117
136
|
this.#onMessage(text);
|
|
118
137
|
}
|
|
119
138
|
}
|
|
@@ -121,13 +121,23 @@ class McpServer {
|
|
|
121
121
|
this.#running.set(id, controller);
|
|
122
122
|
try {
|
|
123
123
|
const result = await tool.run((params.arguments ?? {}), { signal: controller.signal });
|
|
124
|
+
if (controller.signal.aborted)
|
|
125
|
+
return undefined;
|
|
124
126
|
return reply(id, {
|
|
125
|
-
content: [
|
|
126
|
-
|
|
127
|
+
content: [
|
|
128
|
+
{ type: 'text', text: JSON.stringify(result, null, 2) ?? 'null' },
|
|
129
|
+
],
|
|
130
|
+
...(result !== null &&
|
|
131
|
+
typeof result === 'object' &&
|
|
132
|
+
!Array.isArray(result)
|
|
133
|
+
? { structuredContent: result }
|
|
134
|
+
: {}),
|
|
127
135
|
isError: false,
|
|
128
136
|
});
|
|
129
137
|
}
|
|
130
138
|
catch (error) {
|
|
139
|
+
if (controller.signal.aborted)
|
|
140
|
+
return undefined;
|
|
131
141
|
// A tool failure is a result the model can read and act on, not a protocol error.
|
|
132
142
|
return reply(id, {
|
|
133
143
|
content: [{ type: 'text', text: error.message }],
|
|
@@ -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
|
+
}
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { hasLoopbackHost } from '../../core/server.mjs';
|
|
1
2
|
import { CONTROL_HEADER, CONTROL_PATH } from './client.mjs';
|
|
2
3
|
const MAX_CONTROL_BODY = 64 * 1024;
|
|
3
4
|
const failure = (message, status) => Object.assign(new Error(message), { status });
|
|
@@ -23,7 +24,12 @@ export function controlListener(handle) {
|
|
|
23
24
|
response.writeHead(501).end('Recovery Probe tunnels HTTPS (CONNECT) only');
|
|
24
25
|
return;
|
|
25
26
|
}
|
|
26
|
-
// A
|
|
27
|
+
// A same-origin page after DNS rebinding can send the control header too.
|
|
28
|
+
if (!hasLoopbackHost(request)) {
|
|
29
|
+
reply(403, { error: 'Use the proxy loopback host and port' });
|
|
30
|
+
return;
|
|
31
|
+
}
|
|
32
|
+
// Other web pages cannot send this header without a preflight, never answered here.
|
|
27
33
|
if (request.headers[CONTROL_HEADER] !== 'network') {
|
|
28
34
|
reply(403, { error: `Send the ${CONTROL_HEADER}: network header` });
|
|
29
35
|
return;
|
|
@@ -3,7 +3,8 @@ import { ensure, isNonEmptyString } from '../../core/validate.mjs';
|
|
|
3
3
|
const FAULTS = new Set(['refuse', 'reset', 'stall', 'delay']);
|
|
4
4
|
const isWholeNumber = (value) => Number.isInteger(value) && value >= 0;
|
|
5
5
|
export function hostMatches(pattern, host) {
|
|
6
|
-
const name = host.toLowerCase();
|
|
6
|
+
const name = host.toLowerCase().replace(/\.$/, '');
|
|
7
|
+
pattern = pattern.toLowerCase().replace(/\.$/, '');
|
|
7
8
|
if (pattern === '*')
|
|
8
9
|
return true;
|
|
9
10
|
if (pattern.startsWith('*.'))
|
|
@@ -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';
|