@parcha/pi-browser 0.1.0-beta.30 → 0.1.0-beta.32

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.
Files changed (48) hide show
  1. package/CHANGELOG.md +52 -0
  2. package/NOTICE +4 -4
  3. package/README.md +41 -12
  4. package/dist/coding-agent.d.ts +1 -0
  5. package/dist/coding-agent.js +5 -4
  6. package/dist/core/contract.d.ts +9 -0
  7. package/dist/core/contract.js +15 -3
  8. package/dist/core/custody.d.ts +7 -2
  9. package/dist/core/custody.js +7 -3
  10. package/dist/core/downloads.d.ts +7 -0
  11. package/dist/core/downloads.js +13 -1
  12. package/dist/core/driving-guard.d.ts +20 -0
  13. package/dist/core/driving-guard.js +175 -23
  14. package/dist/core/driving.d.ts +56 -2
  15. package/dist/core/driving.js +189 -10
  16. package/dist/core/effects.d.ts +80 -6
  17. package/dist/core/effects.js +374 -41
  18. package/dist/core/failures.d.ts +15 -1
  19. package/dist/core/failures.js +7 -0
  20. package/dist/core/host.d.ts +11 -2
  21. package/dist/core/tools.d.ts +14 -0
  22. package/dist/core/tools.js +42 -8
  23. package/dist/driver/page-driver.js +77 -4
  24. package/dist/driver/sealed.d.ts +4 -12
  25. package/dist/driver/sealed.js +23 -37
  26. package/dist/driver/stagehand.d.ts +10 -15
  27. package/dist/driver/stagehand.js +19 -17
  28. package/dist/durable/result.d.ts +1 -2
  29. package/dist/durable/result.js +2 -2
  30. package/dist/durable/store.d.ts +4 -1
  31. package/dist/durable/store.js +16 -11
  32. package/dist/durable.d.ts +17 -1
  33. package/dist/durable.js +41 -14
  34. package/dist/live-view/index.d.ts +2 -1
  35. package/dist/live-view/index.js +1 -0
  36. package/dist/live-view/protocol.d.ts +38 -6
  37. package/dist/live-view/protocol.js +2 -0
  38. package/dist/live-view/server.d.ts +24 -1
  39. package/dist/live-view/server.js +131 -11
  40. package/dist/live-view/stream.js +16 -3
  41. package/dist/live-view/viewer.js +106 -13
  42. package/dist/providers/cdp.d.ts +0 -1
  43. package/dist/providers/cdp.js +33 -11
  44. package/dist/providers/worker-extension.d.ts +6 -0
  45. package/dist/providers/worker-extension.js +17 -4
  46. package/package.json +10 -10
  47. package/dist/driver/extension-worker.d.ts +0 -9
  48. package/dist/driver/extension-worker.js +0 -185
@@ -9,9 +9,13 @@ export type EffectDecision = {
9
9
  verdict: EffectVerdict | null;
10
10
  };
11
11
  export type EffectDecider = (request: EffectRequest) => Promise<EffectDecision>;
12
- /** Where Stagehand's trace exporter, which cannot be turned off, is pointed: a closed loopback port, so a request to it
13
- * arrives nowhere and is neither held nor journaled. */
14
- export declare const INERT_TRACE_ENDPOINT = "http://127.0.0.1:9/v1/traces";
12
+ /** A request the browser lost before it was sent: the same fields a journal row holds, never a body, header or query. */
13
+ export type LostEffect = {
14
+ requestId: string;
15
+ method: string;
16
+ origin: string;
17
+ path: string;
18
+ };
15
19
  /** Judgments are memoized per request shape, so a page that beacons every second costs one question; `ask` approvals
16
20
  * are not. No judge, a null answer or a failure leaves the request judged irreversible. */
17
21
  export declare function effectDecider(policy: ActionPolicy, decisions?: Pick<Decisions, "judgeEffect" | "approveEffect">): EffectDecider;
@@ -32,6 +36,48 @@ export declare class EffectObserver {
32
36
  /** Announced by `Network.requestWillBeSent` (in order with page commands) but not yet paused by `Fetch.requestPaused`
33
37
  * (which can lag). A holding session journals only at the pause, so `flush` waits for these. */
34
38
  private readonly announced;
39
+ /** By network id, how many times a holding session paused a non-GET request (once per redirect hop), so a late
40
+ * announcement of a hop already paused is never taken for a request still on its way. */
41
+ private readonly pauses;
42
+ /** By network id, how many hops of a non-GET request were announced: a redirect announces the same id again. */
43
+ private readonly hops;
44
+ /** Allowed requests, continued and not yet answered: until the response's head says whether the request redirects (its
45
+ * next hop is then announced) or ends, a flush waits for them, so a redirect's next hop is decided under the same call. */
46
+ private readonly responding;
47
+ private respondSeq;
48
+ private lastAskAt;
49
+ /** Chrome's network service runs in a process of its own. When it dies, Chrome starts another, and a request the dead one
50
+ * carried before its pause is gone: it was never sent (a holding session sends nothing it has not paused), and the page
51
+ * may never hear of it. While an announced request waits for its pause, the service's pid is asked for (never when
52
+ * nothing waits); a new pid means the requests announced before the old one was last seen, and still unpaused, were lost
53
+ * with it. `confirmedSeq`: how far `announceSeq` had got when the old pid was last asked for. */
54
+ private servicePid;
55
+ private confirmedSeq;
56
+ /** How far `announceSeq` had got when the service was last asked, whatever it answered. */
57
+ private askedSeq;
58
+ private watching;
59
+ /** Questions in a row left unanswered; `UNANSWERED_STALL` of them stall the watch until a new held request. */
60
+ private unanswered;
61
+ private stalled;
62
+ /** The browser refused `SystemInfo.getProcessInfo` (a provider's endpoint may), or kept answering without a network
63
+ * service of its own (one in-process) for `NO_SERVICE_MS`: it is not asked again. */
64
+ private noService;
65
+ /** Since when the answers have named no network service. In a browser that never named one, `NO_SERVICE_MS` of that
66
+ * means it has none of its own (in-process). After a known one, it is a restart whose new service is slow to show:
67
+ * `SERVICE_GONE_MS` of that and the old one's waiting requests are told lost. */
68
+ private missingSince;
69
+ /** A network service was named at least once in this observer's life. */
70
+ private seenService;
71
+ /** Ends the watch's wait between questions early: a request just announced is asked about at once, so a service that dies
72
+ * a moment after it is found to have died with it. */
73
+ private nudge;
74
+ private checking;
75
+ /** Requests that ended unpaused (`loadingFailed`) since the service was last asked for: one that failed because the
76
+ * service died is lost too. */
77
+ private readonly endedUnpaused;
78
+ /** Lost requests the call was told were not sent: a pause of one that comes after all is refused, never sent. */
79
+ private readonly lost;
80
+ private lostListener;
35
81
  private announceSeq;
36
82
  private announcedWaiters;
37
83
  closed: boolean;
@@ -45,17 +91,41 @@ export declare class EffectObserver {
45
91
  get holding(): boolean;
46
92
  /** `decide` null observes without holding; a decision not made within `decideMs` is a refusal. */
47
93
  static open(target: AttachTarget, decide: EffectDecider | null, decideMs?: number): Promise<EffectObserver>;
48
- /** Journal every effect from now on (a held one before it is sent); returns the stop. Lifts the previous call's cut. */
49
- record(listener: (row: EffectRow) => unknown): () => void;
94
+ /** Journal every effect from now on (a held one before it is sent); returns the stop. Lifts the previous call's cut.
95
+ * `lost` hears of each request the browser lost before it was sent (see `servicePid`), while this call records. */
96
+ record(listener: (row: EffectRow) => unknown, lost?: (request: LostEffect) => unknown): () => void;
50
97
  /** Resolves once everything the page started before this call is journaled. */
51
98
  flush(signal?: AbortSignal, timeoutMs?: number): Promise<void>;
52
99
  close(): void;
53
100
  private arm;
101
+ /** `send`, whose question is forgotten when it goes unanswered for `ms`: "late", and nothing kept pending for it. */
102
+ private sendWithin;
54
103
  private send;
55
104
  private receive;
105
+ /** Which hop of its request a non-GET announcement is: 1, then one more for each redirect; 0 for a GET. */
106
+ private hopOf;
107
+ /** A redirect announces its next hop under the same id; it is waited for as the first was, unless already paused. */
56
108
  private announce;
109
+ /** Asks for the network service's pid while a request waits for its pause or one ended unpaused, and never otherwise:
110
+ * at once for a request just announced, then every `SERVICE_POLL_MS` while it waits. */
111
+ private watch;
112
+ /** One question about the network service at a time, so one restart is found once. */
113
+ private checkService;
114
+ /** Asks until the answer says whether the service restarted, within `ms`, or the call's `signal` ends. A browser that
115
+ * never named a network service (one in-process, or a refused question) is asked once. While a known service is missing
116
+ * the wait runs to the end of its window (`SERVICE_GONE_MS`), so a successor slow to show still has the call told what
117
+ * the old one took; the call's own end ends it sooner. */
118
+ private conclusiveCheck;
119
+ private askService;
120
+ /** The service last seen died: the requests seen waiting while it was alive, and still unpaused, are lost and told; one
121
+ * announced since may be the new service's, on its way. Not paused means never sent, and a later pause of one is refused. */
122
+ private lose;
57
123
  private unannounce;
58
- /** Bounded: a request the browser never pauses (it ended some other way) must not hold a flush forever. */
124
+ private answered;
125
+ private wakeIfSettled;
126
+ /** Bounded: a request the browser never pauses (it ended some other way) must not hold a flush forever. One still waiting
127
+ * when the wait ends may be one a dead network service took: the service is asked about it, while the call can be told,
128
+ * before it is given up. */
59
129
  private announcedSettled;
60
130
  /** Every command is sent before any answer is awaited, and the resume goes last: a paused target answers
61
131
  * renderer-side commands only after it resumes. */
@@ -67,5 +137,9 @@ export declare class EffectObserver {
67
137
  * it. The browser's own DevTools endpoint is the extension's connection to its host, not a request out. */
68
138
  private socket;
69
139
  private isOwnEndpoint;
140
+ /** A held request stays in `responding` (set at its pause) only once it is let go: refused, or not decided at all, it
141
+ * is not waited for. */
70
142
  private paused;
143
+ /** True when the held request was continued (allowed and recorded). */
144
+ private decidePaused;
71
145
  }
@@ -8,14 +8,25 @@ const REFUSED = { allow: false, verdict: null };
8
8
  const EXTENSION = "chrome-extension://";
9
9
  /** The run code's own words in `trigger`, so a host asked about the request knows where it came from. */
10
10
  const RUN_CODE = "run code";
11
+ /** How often the network service's pid is asked for while a request waits for its pause. */
12
+ const SERVICE_POLL_MS = 250;
13
+ /** How long a browser that never named a network service may go on naming none before it is taken to have none of its own. */
14
+ const NO_SERVICE_MS = 2_000;
15
+ /** How long a known network service may be missing, its successor not yet shown, before what it carried is told lost. */
16
+ const SERVICE_GONE_MS = 10_000;
17
+ /** How long one question about the network service may go unanswered: a timeout is no answer, never a restart. */
18
+ const ASK_MS = 1_000;
19
+ /** Unanswered questions in a row after which the watch waits for a new held request before it asks again. */
20
+ const UNANSWERED_STALL = 3;
21
+ /** The least time between two questions: requests announced meanwhile share the next one. */
22
+ const ASK_GAP_MS = 50;
23
+ /** A journal row's id: the request's own for its first hop, and one per redirect hop after it, so a hop never replaces the row before it. */
24
+ const rowId = (id, hop) => (hop > 1 ? `${id}#${hop}` : id);
11
25
  /** An extension's pages (its offscreen document, its wake page) send nothing a model chose; its service worker is where
12
26
  * run code executes, and is watched like a page. */
13
27
  const ownsExtensionPage = (type, url) => url.startsWith(EXTENSION) && type !== "service_worker";
14
- /** Where Stagehand's trace exporter, which cannot be turned off, is pointed: a closed loopback port, so a request to it
15
- * arrives nowhere and is neither held nor journaled. */
16
- export const INERT_TRACE_ENDPOINT = "http://127.0.0.1:9/v1/traces";
17
- /** A request to an extension's own files, or to the closed trace port, goes nowhere a model chose. */
18
- const isOwnTraffic = (url) => url.startsWith(EXTENSION) || url === INERT_TRACE_ENDPOINT;
28
+ /** A request to an extension's own files goes nowhere a model chose. */
29
+ const isOwnTraffic = (url) => url.startsWith(EXTENSION);
19
30
  /** Judgments are memoized per request shape, so a page that beacons every second costs one question; `ask` approvals
20
31
  * are not. No judge, a null answer or a failure leaves the request judged irreversible. */
21
32
  export function effectDecider(policy, decisions = {}) {
@@ -69,6 +80,48 @@ export class EffectObserver {
69
80
  /** Announced by `Network.requestWillBeSent` (in order with page commands) but not yet paused by `Fetch.requestPaused`
70
81
  * (which can lag). A holding session journals only at the pause, so `flush` waits for these. */
71
82
  announced = new Map();
83
+ /** By network id, how many times a holding session paused a non-GET request (once per redirect hop), so a late
84
+ * announcement of a hop already paused is never taken for a request still on its way. */
85
+ pauses = new Map();
86
+ /** By network id, how many hops of a non-GET request were announced: a redirect announces the same id again. */
87
+ hops = new Map();
88
+ /** Allowed requests, continued and not yet answered: until the response's head says whether the request redirects (its
89
+ * next hop is then announced) or ends, a flush waits for them, so a redirect's next hop is decided under the same call. */
90
+ responding = new Map();
91
+ respondSeq = 0;
92
+ lastAskAt = 0;
93
+ /** Chrome's network service runs in a process of its own. When it dies, Chrome starts another, and a request the dead one
94
+ * carried before its pause is gone: it was never sent (a holding session sends nothing it has not paused), and the page
95
+ * may never hear of it. While an announced request waits for its pause, the service's pid is asked for (never when
96
+ * nothing waits); a new pid means the requests announced before the old one was last seen, and still unpaused, were lost
97
+ * with it. `confirmedSeq`: how far `announceSeq` had got when the old pid was last asked for. */
98
+ servicePid = null;
99
+ confirmedSeq = 0;
100
+ /** How far `announceSeq` had got when the service was last asked, whatever it answered. */
101
+ askedSeq = 0;
102
+ watching = false;
103
+ /** Questions in a row left unanswered; `UNANSWERED_STALL` of them stall the watch until a new held request. */
104
+ unanswered = 0;
105
+ stalled = false;
106
+ /** The browser refused `SystemInfo.getProcessInfo` (a provider's endpoint may), or kept answering without a network
107
+ * service of its own (one in-process) for `NO_SERVICE_MS`: it is not asked again. */
108
+ noService = false;
109
+ /** Since when the answers have named no network service. In a browser that never named one, `NO_SERVICE_MS` of that
110
+ * means it has none of its own (in-process). After a known one, it is a restart whose new service is slow to show:
111
+ * `SERVICE_GONE_MS` of that and the old one's waiting requests are told lost. */
112
+ missingSince = null;
113
+ /** A network service was named at least once in this observer's life. */
114
+ seenService = false;
115
+ /** Ends the watch's wait between questions early: a request just announced is asked about at once, so a service that dies
116
+ * a moment after it is found to have died with it. */
117
+ nudge = null;
118
+ checking = Promise.resolve("unknown");
119
+ /** Requests that ended unpaused (`loadingFailed`) since the service was last asked for: one that failed because the
120
+ * service died is lost too. */
121
+ endedUnpaused = new Map();
122
+ /** Lost requests the call was told were not sent: a pause of one that comes after all is refused, never sent. */
123
+ lost = new Set();
124
+ lostListener = null;
72
125
  announceSeq = 0;
73
126
  announcedWaiters = [];
74
127
  closed = false;
@@ -122,13 +175,17 @@ export class EffectObserver {
122
175
  throw error;
123
176
  }
124
177
  }
125
- /** Journal every effect from now on (a held one before it is sent); returns the stop. Lifts the previous call's cut. */
126
- record(listener) {
178
+ /** Journal every effect from now on (a held one before it is sent); returns the stop. Lifts the previous call's cut.
179
+ * `lost` hears of each request the browser lost before it was sent (see `servicePid`), while this call records. */
180
+ record(listener, lost) {
127
181
  if (this.isCut)
128
182
  this.arm();
129
183
  this.listener = listener;
130
- return () => { if (this.listener === listener)
131
- this.listener = null; };
184
+ this.lostListener = lost ?? null;
185
+ return () => { if (this.listener === listener) {
186
+ this.listener = null;
187
+ this.lostListener = null;
188
+ } };
132
189
  }
133
190
  /** Resolves once everything the page started before this call is journaled. */
134
191
  async flush(signal, timeoutMs = 1000) {
@@ -139,7 +196,10 @@ export class EffectObserver {
139
196
  else
140
197
  signal?.addEventListener("abort", cut, { once: true });
141
198
  try {
142
- await this.announcedSettled(timeoutMs);
199
+ await this.announcedSettled(timeoutMs, signal);
200
+ // A request that ended unpaused during the call may be one a dead network service took: asked now, while the call can be told.
201
+ if (this.endedUnpaused.size)
202
+ await this.conclusiveCheck(timeoutMs, signal);
143
203
  while (this.inflight.size)
144
204
  await Promise.allSettled([...this.inflight]);
145
205
  }
@@ -152,6 +212,22 @@ export class EffectObserver {
152
212
  }
153
213
  catch { } }
154
214
  arm() { this.isCut = false; this.cutoff = new Promise((resolve) => { this.cut = () => resolve(REFUSED); }); }
215
+ /** `send`, whose question is forgotten when it goes unanswered for `ms`: "late", and nothing kept pending for it. */
216
+ sendWithin(method, ms) {
217
+ const id = this.next++;
218
+ return new Promise((resolve, reject) => {
219
+ const timer = setTimeout(() => { this.pending.delete(id); resolve("late"); }, ms);
220
+ this.pending.set(id, { resolve: (value) => { clearTimeout(timer); resolve(value); }, reject: (error) => { clearTimeout(timer); reject(error); } });
221
+ try {
222
+ this.ws.send(JSON.stringify({ id, method, params: {} }));
223
+ }
224
+ catch (error) {
225
+ clearTimeout(timer);
226
+ this.pending.delete(id);
227
+ reject(error);
228
+ }
229
+ });
230
+ }
155
231
  send(method, params = {}, sessionId) {
156
232
  const id = this.next++;
157
233
  return new Promise((resolve, reject) => {
@@ -182,46 +258,276 @@ export class EffectObserver {
182
258
  for (const [id, entry] of [...this.announced])
183
259
  if (entry.sessionId === m.params.sessionId)
184
260
  this.unannounce(id);
261
+ for (const [id, entry] of [...this.responding])
262
+ if (entry.sessionId === m.params.sessionId)
263
+ this.answered(id);
185
264
  }
186
265
  else if (m.method === "Network.requestWillBeSent") {
187
- this.announce(m.sessionId, m.params);
188
- this.track(this.sent(m.sessionId, m.params));
266
+ const hop = this.hopOf(m.params);
267
+ this.announce(m.sessionId, m.params, hop);
268
+ // A redirect is the previous hop's answer; its next hop, just announced, is waited for in its place. A next hop
269
+ // already paused (its pause came before this announcement) stays waited for.
270
+ if (m.params.redirectResponse && (this.responding.get(m.params.requestId)?.hop ?? 0) < hop)
271
+ this.answered(m.params.requestId);
272
+ this.track(this.sent(m.sessionId, m.params, hop));
189
273
  }
274
+ else if (m.method === "Network.responseReceived")
275
+ this.answered(m.params.requestId);
190
276
  else if (m.method === "Fetch.requestPaused") {
191
- this.track(this.paused(m.sessionId, m.params));
192
277
  // A preflight (OPTIONS) is paused first and says nothing about the request it precedes.
193
- if (!SAFE.has(m.params.request.method)) {
194
- this.unannounce(m.params.networkId ?? m.params.requestId);
278
+ const id = m.params.networkId ?? m.params.requestId;
279
+ const hop = SAFE.has(m.params.request.method) ? 0 : (this.pauses.get(id) ?? 0) + 1;
280
+ // A held request is waited for from its pause, through its decision, to its answer (paused() lets it go when it is
281
+ // refused): it is covered before it stops being announced, so a flush never sees a gap between the two.
282
+ if (hop && this.decide && !isOwnTraffic(m.params.request.url))
283
+ this.responding.set(id, { sessionId: m.sessionId, seq: (this.respondSeq += 1), hop });
284
+ this.track(this.paused(m.sessionId, m.params, hop));
285
+ if (hop) {
286
+ this.pauses.set(id, hop);
287
+ this.unannounce(id);
195
288
  if (m.params.resourceType === "Document")
196
289
  this.unannounce(`navigation:${m.params.frameId}`);
197
290
  }
198
291
  }
199
- else if (m.method === "Network.loadingFailed" || m.method === "Network.loadingFinished")
292
+ else if (m.method === "Network.loadingFailed") {
293
+ const entry = this.announced.get(m.params.requestId);
294
+ if (entry) {
295
+ this.endedUnpaused.set(m.params.requestId, entry);
296
+ this.watch();
297
+ }
200
298
  this.unannounce(m.params.requestId);
299
+ this.answered(m.params.requestId);
300
+ }
301
+ else if (m.method === "Network.loadingFinished") {
302
+ this.unannounce(m.params.requestId);
303
+ this.answered(m.params.requestId);
304
+ }
201
305
  else if (m.method === "Network.webSocketCreated")
202
306
  this.track(this.socket(m.sessionId, m.params));
203
- else if (m.method === "Page.frameRequestedNavigation" && m.params.reason === "formSubmissionPost" && this.sessions.get(m.sessionId)?.holds)
204
- this.announced.set(`navigation:${m.params.frameId}`, { sessionId: m.sessionId, seq: (this.announceSeq += 1) });
307
+ else if (m.method === "Page.frameRequestedNavigation" && m.params.reason === "formSubmissionPost" && this.sessions.get(m.sessionId)?.holds) {
308
+ // A new intent in the frame is a new form: an earlier one told lost no longer refuses it, and it is asked about.
309
+ this.lost.delete(`navigation:${m.params.frameId}`);
310
+ this.stalled = false;
311
+ this.announced.set(`navigation:${m.params.frameId}`, { sessionId: m.sessionId, seq: (this.announceSeq += 1), method: "POST", url: m.params.url });
312
+ this.watch();
313
+ }
314
+ }
315
+ /** Which hop of its request a non-GET announcement is: 1, then one more for each redirect; 0 for a GET. */
316
+ hopOf(p) {
317
+ if (SAFE.has(p.request.method))
318
+ return 0;
319
+ const hop = p.redirectResponse ? (this.hops.get(p.requestId) ?? 1) + 1 : 1;
320
+ this.hops.set(p.requestId, hop);
321
+ return hop;
322
+ }
323
+ /** A redirect announces its next hop under the same id; it is waited for as the first was, unless already paused. */
324
+ announce(sessionId, p, hop) {
325
+ if (!hop || !this.sessions.get(sessionId)?.holds || (this.pauses.get(p.requestId) ?? 0) >= hop)
326
+ return;
327
+ // A new held request is asked about even after a browser left questions unanswered.
328
+ this.stalled = false;
329
+ this.announced.set(p.requestId, { sessionId, seq: (this.announceSeq += 1), method: p.request.method, url: p.request.url, ...(p.type === "Document" && p.frameId ? { frameId: p.frameId } : {}), ...(hop > 1 ? { sent: true } : {}) });
330
+ this.watch();
331
+ }
332
+ /** Asks for the network service's pid while a request waits for its pause or one ended unpaused, and never otherwise:
333
+ * at once for a request just announced, then every `SERVICE_POLL_MS` while it waits. */
334
+ watch() {
335
+ if (this.watching) {
336
+ this.nudge?.();
337
+ return;
338
+ }
339
+ if (this.closed || !this.decide || this.noService || this.stalled)
340
+ return;
341
+ this.watching = true;
342
+ void (async () => {
343
+ try {
344
+ while (!this.closed && !this.noService && !this.stalled && (this.announced.size || this.endedUnpaused.size)) {
345
+ if ((await this.checkService()) !== "unknown" && this.announceSeq > this.askedSeq)
346
+ continue;
347
+ await new Promise((resolve) => {
348
+ const timer = setTimeout(() => { this.nudge = null; resolve(); }, SERVICE_POLL_MS);
349
+ this.nudge = () => { clearTimeout(timer); this.nudge = null; resolve(); };
350
+ });
351
+ }
352
+ }
353
+ finally {
354
+ this.watching = false;
355
+ this.nudge = null;
356
+ }
357
+ })().catch(() => undefined);
205
358
  }
206
- announce(sessionId, p) {
207
- if (this.sessions.get(sessionId)?.holds && !SAFE.has(p.request.method))
208
- this.announced.set(p.requestId, { sessionId, seq: (this.announceSeq += 1) });
359
+ /** One question about the network service at a time, so one restart is found once. */
360
+ checkService() {
361
+ this.checking = this.checking.then(() => this.askService(), () => this.askService());
362
+ return this.checking;
363
+ }
364
+ /** Asks until the answer says whether the service restarted, within `ms`, or the call's `signal` ends. A browser that
365
+ * never named a network service (one in-process, or a refused question) is asked once. While a known service is missing
366
+ * the wait runs to the end of its window (`SERVICE_GONE_MS`), so a successor slow to show still has the call told what
367
+ * the old one took; the call's own end ends it sooner. */
368
+ async conclusiveCheck(ms, signal) {
369
+ if (this.noService || !this.decide)
370
+ return;
371
+ const end = Date.now() + ms;
372
+ for (;;) {
373
+ if ((await this.checkService()) !== "unknown" || this.servicePid === null || this.noService || this.stalled || this.closed || signal?.aborted)
374
+ return;
375
+ const until = this.seenService && this.missingSince !== null ? Math.max(end, this.missingSince + SERVICE_GONE_MS + SERVICE_POLL_MS) : end;
376
+ if (Date.now() >= until)
377
+ return;
378
+ await new Promise((resolve) => {
379
+ const timer = setTimeout(finish, Math.min(SERVICE_POLL_MS, 100));
380
+ function finish() { clearTimeout(timer); signal?.removeEventListener("abort", finish); resolve(); }
381
+ signal?.addEventListener("abort", finish, { once: true });
382
+ });
383
+ }
384
+ }
385
+ async askService() {
386
+ // At most one question per `ASK_GAP_MS`; what is announced before it goes is covered by its answer.
387
+ const wait = this.lastAskAt + ASK_GAP_MS - Date.now();
388
+ if (wait > 0)
389
+ await new Promise((r) => setTimeout(r, wait));
390
+ this.lastAskAt = Date.now();
391
+ const covered = this.announceSeq;
392
+ // An unanswered question, one answered with no result, or one that failed is no answer. A browser that gives no answer
393
+ // three times in a row is not asked again until a new held request is announced: what waits now is left to the
394
+ // flush's own bound, never called lost.
395
+ const noAnswer = () => {
396
+ this.unanswered += 1;
397
+ if (this.unanswered >= UNANSWERED_STALL) {
398
+ this.stalled = true;
399
+ this.endedUnpaused.clear();
400
+ }
401
+ return "unknown";
402
+ };
403
+ let pid = null;
404
+ try {
405
+ const answer = await this.sendWithin("SystemInfo.getProcessInfo", ASK_MS);
406
+ if (answer === "late" || answer === null || typeof answer !== "object")
407
+ return noAnswer();
408
+ const service = Array.isArray(answer.processInfo) ? answer.processInfo.find((p) => typeof p?.type === "string" && p.type.includes("NetworkService")) : undefined;
409
+ pid = typeof service?.id === "number" ? service.id : null;
410
+ this.unanswered = 0;
411
+ }
412
+ catch (error) {
413
+ if (observerFailure(error) === "cdp_error") {
414
+ this.noService = true;
415
+ return "unknown";
416
+ }
417
+ return noAnswer();
418
+ }
419
+ this.askedSeq = Math.max(this.askedSeq, covered);
420
+ // No pid: Chrome has not started the new service yet, or runs none of its own (see `missingSince`).
421
+ if (pid === null) {
422
+ this.missingSince ??= Date.now();
423
+ const missing = Date.now() - this.missingSince;
424
+ if (!this.seenService) {
425
+ if (missing >= NO_SERVICE_MS) {
426
+ this.noService = true;
427
+ this.endedUnpaused.clear();
428
+ }
429
+ return "unknown";
430
+ }
431
+ if (this.servicePid === null || missing < SERVICE_GONE_MS)
432
+ return "unknown";
433
+ // The known service has been gone too long to wait for its successor: what it carried is lost, and the next pid
434
+ // named is learned afresh.
435
+ this.missingSince = null;
436
+ await this.lose(covered, null);
437
+ return "restarted";
438
+ }
439
+ this.missingSince = null;
440
+ this.seenService = true;
441
+ if (this.servicePid === null || pid === this.servicePid) {
442
+ this.servicePid = pid;
443
+ this.confirmedSeq = covered;
444
+ this.endedUnpaused.clear();
445
+ return "same";
446
+ }
447
+ await this.lose(covered, pid);
448
+ return "restarted";
449
+ }
450
+ /** The service last seen died: the requests seen waiting while it was alive, and still unpaused, are lost and told; one
451
+ * announced since may be the new service's, on its way. Not paused means never sent, and a later pause of one is refused. */
452
+ async lose(covered, pid) {
453
+ const gone = [...this.announced, ...this.endedUnpaused].filter(([id, entry]) => entry.seq <= this.confirmedSeq && !entry.sent && !this.pauses.has(id));
454
+ this.servicePid = pid;
455
+ this.confirmedSeq = covered;
456
+ this.endedUnpaused.clear();
457
+ // Both keys of a form refuse a late pause, but the call is told of the form once: by its Document request when that was seen.
458
+ const forms = new Set(gone.flatMap(([, entry]) => (entry.frameId ? [`navigation:${entry.frameId}`] : [])));
459
+ const told = gone.filter(([id]) => !forms.has(id));
460
+ // The call is told of every loss before a flush that was waiting for these requests returns: the telling is in flight
461
+ // before they stop being waited for, and to the call recording when they were found.
462
+ const listener = this.lostListener;
463
+ const telling = (async () => {
464
+ for (const [id, entry] of told) {
465
+ let request;
466
+ try {
467
+ request = describeRequest(entry.method, entry.url);
468
+ }
469
+ catch {
470
+ continue;
471
+ }
472
+ try {
473
+ await listener?.({ requestId: id, method: request.method, origin: request.origin, path: request.path });
474
+ }
475
+ catch { /* a listener's failure is its own */ }
476
+ }
477
+ })();
478
+ this.track(telling);
479
+ for (const [id] of gone) {
480
+ this.lost.add(id);
481
+ this.unannounce(id);
482
+ }
483
+ await telling;
209
484
  }
210
485
  unannounce(requestId) {
211
- if (this.announced.delete(requestId) && this.announced.size === 0)
486
+ if (this.announced.delete(requestId))
487
+ this.wakeIfSettled();
488
+ }
489
+ answered(requestId) {
490
+ if (this.responding.delete(requestId))
491
+ this.wakeIfSettled();
492
+ }
493
+ wakeIfSettled() {
494
+ if (this.announced.size === 0 && this.responding.size === 0)
212
495
  for (const wake of this.announcedWaiters.splice(0))
213
496
  wake();
214
497
  }
215
- /** Bounded: a request the browser never pauses (it ended some other way) must not hold a flush forever. */
216
- announcedSettled(ms) {
217
- if (this.announced.size === 0)
498
+ /** Bounded: a request the browser never pauses (it ended some other way) must not hold a flush forever. One still waiting
499
+ * when the wait ends may be one a dead network service took: the service is asked about it, while the call can be told,
500
+ * before it is given up. */
501
+ announcedSettled(ms, signal) {
502
+ // A cancelled call does not wait for an allowed request's answer: nothing it could still be told depends on it.
503
+ const stopResponding = () => { for (const id of [...this.responding.keys()])
504
+ this.answered(id); };
505
+ if (signal?.aborted)
506
+ stopResponding();
507
+ if (this.announced.size === 0 && this.responding.size === 0)
218
508
  return Promise.resolve();
219
509
  return new Promise((resolve) => {
220
- const done = () => { clearTimeout(timer); this.announcedWaiters = this.announcedWaiters.filter((w) => w !== done); resolve(); };
510
+ const done = () => { clearTimeout(timer); signal?.removeEventListener("abort", stopResponding); this.announcedWaiters = this.announcedWaiters.filter((w) => w !== done); resolve(); };
511
+ signal?.addEventListener("abort", stopResponding, { once: true });
221
512
  const covered = this.announceSeq;
222
- const timer = setTimeout(() => { for (const [id, entry] of [...this.announced])
223
- if (entry.seq <= covered)
224
- this.unannounce(id); done(); }, ms);
513
+ const coveredResponses = this.respondSeq;
514
+ const timer = setTimeout(() => {
515
+ void (async () => {
516
+ try {
517
+ if ([...this.announced.values()].some((entry) => entry.seq <= covered))
518
+ await this.conclusiveCheck(ms, signal);
519
+ }
520
+ finally {
521
+ for (const [id, entry] of [...this.announced])
522
+ if (entry.seq <= covered)
523
+ this.unannounce(id);
524
+ for (const [id, entry] of [...this.responding])
525
+ if (entry.seq <= coveredResponses)
526
+ this.answered(id);
527
+ done();
528
+ }
529
+ })().catch(() => undefined);
530
+ }, ms);
225
531
  this.announcedWaiters.push(done);
226
532
  });
227
533
  }
@@ -264,11 +570,11 @@ export class EffectObserver {
264
570
  return false;
265
571
  }
266
572
  }
267
- async sent(sessionId, p) {
573
+ async sent(sessionId, p, hop) {
268
574
  const session = this.sessions.get(sessionId);
269
575
  if (SAFE.has(p.request.method) || !session || ownsExtensionPage(session.type, session.url) || isOwnTraffic(p.request.url) || session.holds)
270
576
  return;
271
- await this.journal(p.requestId, describeRequest(p.request.method, p.request.url), null, null);
577
+ await this.journal(rowId(p.requestId, hop), describeRequest(p.request.method, p.request.url), null, null);
272
578
  }
273
579
  /** A socket cannot be held (Fetch does not see it), so it is journaled when it is created and never decided, whoever opens
274
580
  * it. The browser's own DevTools endpoint is the extension's connection to its host, not a request out. */
@@ -293,17 +599,34 @@ export class EffectObserver {
293
599
  return false;
294
600
  }
295
601
  }
296
- async paused(sessionId, p) {
602
+ /** A held request stays in `responding` (set at its pause) only once it is let go: refused, or not decided at all, it
603
+ * is not waited for. */
604
+ async paused(sessionId, p, hop) {
605
+ const id = p.networkId ?? p.requestId;
606
+ let continued = false;
607
+ try {
608
+ continued = await this.decidePaused(sessionId, p, hop, id);
609
+ }
610
+ finally {
611
+ if (!continued)
612
+ this.answered(id);
613
+ }
614
+ }
615
+ /** True when the held request was continued (allowed and recorded). */
616
+ async decidePaused(sessionId, p, hop, id) {
297
617
  const { method, url, postData, headers } = p.request;
298
- if (SAFE.has(method) || !this.decide || isOwnTraffic(url))
299
- return this.send("Fetch.continueRequest", { requestId: p.requestId }, sessionId);
618
+ if (SAFE.has(method) || !this.decide || isOwnTraffic(url)) {
619
+ await this.send("Fetch.continueRequest", { requestId: p.requestId }, sessionId);
620
+ return false;
621
+ }
300
622
  let request;
301
623
  // A request the observer cannot describe cannot be judged or journaled, and a held request nobody answers waits forever: refuse it.
302
624
  try {
303
625
  request = describeRequest(method, url, postData, headers);
304
626
  }
305
627
  catch {
306
- return this.send("Fetch.failRequest", { requestId: p.requestId, errorReason: "BlockedByClient" }, sessionId);
628
+ await this.send("Fetch.failRequest", { requestId: p.requestId, errorReason: "BlockedByClient" }, sessionId);
629
+ return false;
307
630
  }
308
631
  // Only the extension's own worker runs the model's code: a website's worker sends what the website sent.
309
632
  const session = this.sessions.get(sessionId);
@@ -312,14 +635,24 @@ export class EffectObserver {
312
635
  const cutoff = this.cutoff;
313
636
  // Journaled `pending` and committed before deciding: a process that dies mid-decision loses the hold and the
314
637
  // request goes, so the journal must already name it. A request whose row could not be saved never leaves.
315
- const id = p.networkId ?? p.requestId;
316
- const saved = await this.journal(id, request, "pending", null);
638
+ const row = rowId(id, hop);
639
+ const saved = await this.journal(row, request, "pending", null);
317
640
  let timer;
318
641
  const limit = new Promise((resolve) => { timer = setTimeout(() => resolve(REFUSED), this.decideMs); });
319
- const { allow, verdict } = saved ? await Promise.race([this.decide(request), cutoff, limit]).finally(() => clearTimeout(timer)) : REFUSED;
320
- const recorded = await this.journal(id, request, allow ? "allowed" : "denied", verdict);
321
- if (allow && !recorded)
322
- return this.send("Fetch.failRequest", { requestId: p.requestId, errorReason: "BlockedByClient" }, sessionId);
642
+ // A request the call was told the browser lost, and so was not sent, stays not sent: by its own id, or for a form's
643
+ // Document by its frame's intent, which is what the call was told of when the form's request did not exist yet.
644
+ const intent = p.resourceType === "Document" && p.frameId ? `navigation:${p.frameId}` : null;
645
+ // The intent is used up whether or not the id matched too, so it never refuses a later Document in the frame.
646
+ const intentLost = intent !== null && this.lost.delete(intent);
647
+ const told = this.lost.has(id) || intentLost;
648
+ const { allow, verdict } = saved && !told ? await Promise.race([this.decide(request), cutoff, limit]).finally(() => clearTimeout(timer)) : REFUSED;
649
+ clearTimeout(timer);
650
+ const recorded = await this.journal(row, request, allow ? "allowed" : "denied", verdict);
651
+ if (allow && !recorded) {
652
+ await this.send("Fetch.failRequest", { requestId: p.requestId, errorReason: "BlockedByClient" }, sessionId);
653
+ return false;
654
+ }
323
655
  await this.send(allow ? "Fetch.continueRequest" : "Fetch.failRequest", allow ? { requestId: p.requestId } : { requestId: p.requestId, errorReason: "BlockedByClient" }, sessionId);
656
+ return allow;
324
657
  }
325
658
  }