@nite07/search-core 0.1.5 → 0.1.7

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/dist/browser.js CHANGED
@@ -2,101 +2,884 @@
2
2
  // Both sides of the connection must share a major.minor, so the browser image pins the same version.
3
3
  import { chromium } from 'patchright-core';
4
4
  import { existsSync } from 'node:fs';
5
+ import { DEFAULT_MAX_CONCURRENT_READS, MAX_CONCURRENT_READS } from './browser-limits.js';
5
6
  import { SearchError } from './transport.js';
6
- const SITE_HOST = 'xiaohongshu.com';
7
+ // The bound itself lives in a browser-safe module: the settings UI bundles the configuration schema
8
+ // and must not pull patchright in. Re-exported here because this is where callers expect it.
9
+ export { DEFAULT_MAX_CONCURRENT_READS } from './browser-limits.js';
10
+ const DEFAULT_IDLE_MS = 300_000;
11
+ const DEFAULT_CLOSE_MS = 5_000;
12
+ const PERSIST_INTERVAL_MS = 60_000;
13
+ const message = (error) => (error instanceof Error ? error.message : String(error));
14
+ const cancelled = (detail) => new SearchError('cancelled', detail);
15
+ const defaultConnect = (options) => chromium.connect(options.wsEndpoint, {
16
+ timeout: options.timeoutMs,
17
+ ...(options.token ? { headers: { authorization: `Bearer ${options.token}` } } : {}),
18
+ });
19
+ /**
20
+ * The site owns a page only when the hostname is the configured one, a subdomain of it, or the
21
+ * bare apex when the configured host starts with `www.`. Arbitrary ancestors are refused: with
22
+ * `www.foo.co.uk` configured, `https://com` and `https://co.uk` are not the site. This is
23
+ * deliberately not a public-suffix implementation; the www/apex pair is the only alias allowed.
24
+ * An exactly configured `about:blank` is the one non-http exception, for local page checks.
25
+ */
26
+ function sameSite(current, target) {
27
+ // about:blank is the only non-http target accepted, exactly as configured. It is useful for a
28
+ // local page with no network at all; no other about: URL is treated as a site.
29
+ if (current === 'about:blank' && target === 'about:blank')
30
+ return true;
31
+ try {
32
+ const page = new URL(current);
33
+ const site = new URL(target);
34
+ if (page.protocol !== 'http:' && page.protocol !== 'https:')
35
+ return false;
36
+ const a = page.hostname.toLowerCase();
37
+ const b = site.hostname.toLowerCase();
38
+ if (a === b || a.endsWith(`.${b}`))
39
+ return true;
40
+ return b.startsWith('www.') && a === b.slice('www.'.length);
41
+ }
42
+ catch {
43
+ return false;
44
+ }
45
+ }
46
+ const siteName = (siteUrl) => {
47
+ try {
48
+ return new URL(siteUrl).hostname;
49
+ }
50
+ catch {
51
+ return 'the site';
52
+ }
53
+ };
54
+ function createGeneration(browser, context, page) {
55
+ let resolveDrained = () => undefined;
56
+ const drained = new Promise(resolve => {
57
+ resolveDrained = resolve;
58
+ });
59
+ const drainedResolved = { value: false };
60
+ return {
61
+ browser,
62
+ context,
63
+ page,
64
+ inflight: 0,
65
+ stale: false,
66
+ staleReason: undefined,
67
+ drained,
68
+ drainedResolved,
69
+ resolveDrained: () => {
70
+ if (drainedResolved.value)
71
+ return;
72
+ drainedResolved.value = true;
73
+ resolveDrained();
74
+ },
75
+ disposal: undefined,
76
+ };
77
+ }
78
+ /** Wait for a shared promise, but stop waiting as soon as the caller aborts. */
79
+ function abortable(promise, signal) {
80
+ if (!signal)
81
+ return promise;
82
+ if (signal.aborted) {
83
+ // Do not leave the shared promise without a rejection handler.
84
+ promise.catch(() => undefined);
85
+ return Promise.reject(cancelled('The browser read was cancelled while waiting for the session.'));
86
+ }
87
+ return new Promise((resolve, reject) => {
88
+ const stop = () => {
89
+ signal.removeEventListener('abort', stop);
90
+ reject(cancelled('The browser read was cancelled while waiting for the session.'));
91
+ };
92
+ signal.addEventListener('abort', stop, { once: true });
93
+ promise.then(value => {
94
+ signal.removeEventListener('abort', stop);
95
+ resolve(value);
96
+ }, error => {
97
+ signal.removeEventListener('abort', stop);
98
+ reject(error);
99
+ });
100
+ });
101
+ }
102
+ /** Wait at most `timeoutMs`; a rejected or timed-out operation is reported as incomplete. */
103
+ async function bounded(operation, timeoutMs) {
104
+ if (timeoutMs <= 0)
105
+ return false;
106
+ let timer;
107
+ const timeout = new Promise(resolve => {
108
+ timer = setTimeout(() => resolve(false), timeoutMs);
109
+ timer.unref?.();
110
+ });
111
+ const result = await Promise.race([operation.then(() => true, () => true), timeout]);
112
+ if (timer !== undefined)
113
+ clearTimeout(timer);
114
+ return result;
115
+ }
116
+ /**
117
+ * One kept browser connection per site.
118
+ *
119
+ * Reads are transactions. Up to `maxConcurrentReads` of them may be in flight on the same page;
120
+ * an admission limiter shared by every read API keeps that bound and a FIFO waiter list keeps
121
+ * admission fair. A transaction is health probe plus the page script plus mapping, so the two
122
+ * stages of different transactions can interleave while each result still belongs to its own
123
+ * async call.
124
+ *
125
+ * The page belongs to a generation with an in-flight reference count. Initialisation is
126
+ * single-flight. A stale generation (expired sign-in, lost connection, closed tab) stops admitting
127
+ * new reads, lets its in-flight reads finish, and is disposed before the next generation opens.
128
+ * The only things that release resources are an idle timeout, an explicit shutdown and that
129
+ * generation recycle. The window a human signs into belongs to the keeper's separate client, not
130
+ * to this context, and nothing here touches it.
131
+ */
7
132
  export class BrowserSession {
8
133
  options;
134
+ onDisposed;
9
135
  browser;
136
+ context;
10
137
  page;
11
138
  savedAt = 0;
12
- context;
13
- constructor(options) {
139
+ generation;
140
+ opening;
141
+ disposal;
142
+ idleTimer;
143
+ idleDisposed = false;
144
+ idleRunning = false;
145
+ retired = false;
146
+ closed = false;
147
+ closing;
148
+ admissionLimit;
149
+ activeCount = 0;
150
+ waiters = [];
151
+ activeJobs = new Set();
152
+ zeroWaiters = [];
153
+ pumping = false;
154
+ maintenance;
155
+ maintenanceRequested = false;
156
+ maintenanceRunning = false;
157
+ shutdown = new AbortController();
158
+ constructor(options,
159
+ /** Called after the session released its resources; the registry drops the idle entry. */
160
+ onDisposed) {
14
161
  this.options = options;
162
+ this.onDisposed = onDisposed;
163
+ const limit = options.maxConcurrentReads ?? DEFAULT_MAX_CONCURRENT_READS;
164
+ if (!Number.isInteger(limit) || limit < 1 || limit > MAX_CONCURRENT_READS) {
165
+ throw new SearchError('configuration', `maxConcurrentReads must be an integer from 1 through ${MAX_CONCURRENT_READS}; it is a local safety bound, not a Xiaohongshu quota.`);
166
+ }
167
+ this.admissionLimit = limit;
15
168
  }
16
- async connect() {
17
- if (this.browser?.isConnected())
18
- return this.browser;
169
+ get isClosed() {
170
+ return this.closed || this.retired;
171
+ }
172
+ /**
173
+ * Run one read transaction. The callback gets a narrow reader and owns one admission slot from
174
+ * before its first page operation until it settles. An abort that arrives while the transaction
175
+ * is waiting rejects at once; an abort that arrives while a page call is in flight is observed
176
+ * before the next operation, because a browser call cannot be interrupted mid-flight.
177
+ */
178
+ async read(run, signal) {
179
+ return this.enqueue((reader, _page) => run(reader), signal);
180
+ }
181
+ /** Legacy single-script entry point. It now uses the same admission limiter as `read`. */
182
+ async evaluate(script) {
183
+ return this.read(reader => reader.evaluate(script));
184
+ }
185
+ /** Legacy way to get the page. The admission slot is released before the caller uses it. */
186
+ async target() {
187
+ return this.enqueue((_reader, page) => Promise.resolve(page));
188
+ }
189
+ /**
190
+ * Persist the session so the next process starts signed in. Runs as exclusive maintenance:
191
+ * admission pauses and waits for in-flight reads to settle first. Skipped in `read-only` mode,
192
+ * rate-limited, and `savedAt` moves only after a save actually succeeded.
193
+ *
194
+ * Do not call this from inside a read transaction; it waits for the transaction to finish.
195
+ */
196
+ async persist() {
197
+ if (this.closed || this.retired || this.options.statePolicy === 'read-only')
198
+ return;
199
+ await this.runMaintenance(async () => {
200
+ await this.persistUnlocked();
201
+ }).catch(() => undefined);
202
+ }
203
+ /**
204
+ * Close this session for good. New reads are refused, queued reads are cancelled, in-flight
205
+ * reads get a bounded grace period (one total deadline with the teardown), and the connection is
206
+ * dropped even if a read is still stuck. Idempotent, including when called concurrently.
207
+ */
208
+ async close() {
209
+ if (this.closing)
210
+ return this.closing;
211
+ this.closed = true;
212
+ this.shutdown.abort();
213
+ this.clearIdleTimer();
214
+ this.cancelWaiters();
215
+ this.closing = this.disposeAfterClose().catch(() => undefined);
216
+ return this.closing;
217
+ }
218
+ // --- admission -----------------------------------------------------------------------------
219
+ enqueue(run, signal) {
220
+ if (this.closed || this.retired || this.closing) {
221
+ return Promise.reject(cancelled(this.retired
222
+ ? 'The browser session was retired after idling out; ask the registry for the current session.'
223
+ : 'The browser session was closed before this read started.'));
224
+ }
225
+ if (signal?.aborted) {
226
+ return Promise.reject(cancelled('The browser read was cancelled before it started.'));
227
+ }
228
+ return new Promise((resolve, reject) => {
229
+ let job;
230
+ const onAbort = () => {
231
+ if (job.settled)
232
+ return;
233
+ if (!job.started) {
234
+ job.cancelled = true;
235
+ job.reject(cancelled('The queued browser read was cancelled.'));
236
+ this.pump();
237
+ return;
238
+ }
239
+ job.cancelRequested = true;
240
+ };
241
+ job = {
242
+ run: run,
243
+ ...(signal ? { signal } : {}),
244
+ started: false,
245
+ settled: false,
246
+ cancelled: false,
247
+ cancelRequested: false,
248
+ resolve: value => {
249
+ if (job.settled)
250
+ return;
251
+ job.settled = true;
252
+ signal?.removeEventListener('abort', onAbort);
253
+ resolve(value);
254
+ },
255
+ reject: error => {
256
+ if (job.settled)
257
+ return;
258
+ job.settled = true;
259
+ signal?.removeEventListener('abort', onAbort);
260
+ reject(error);
261
+ },
262
+ };
263
+ if (signal)
264
+ signal.addEventListener('abort', onAbort, { once: true });
265
+ this.waiters.push(job);
266
+ this.pump();
267
+ });
268
+ }
269
+ pump() {
270
+ if (this.pumping)
271
+ return;
272
+ this.pumping = true;
273
+ try {
274
+ while (!this.closed &&
275
+ !this.retired &&
276
+ !this.idleRunning &&
277
+ !this.maintenanceRequested &&
278
+ !this.maintenanceRunning &&
279
+ this.activeCount < this.admissionLimit) {
280
+ const job = this.waiters.shift();
281
+ if (!job)
282
+ break;
283
+ if (job.cancelled)
284
+ continue;
285
+ job.started = true;
286
+ this.activeCount += 1;
287
+ this.activeJobs.add(job);
288
+ this.idleDisposed = false;
289
+ this.clearIdleTimer();
290
+ void this.runJob(job);
291
+ }
292
+ }
293
+ finally {
294
+ this.pumping = false;
295
+ }
296
+ this.afterActivity();
297
+ }
298
+ async runJob(job) {
299
+ let lease;
19
300
  try {
20
- this.browser = await chromium.connect(this.options.wsEndpoint, {
21
- timeout: this.options.timeoutMs,
22
- ...(this.options.token ? { headers: { authorization: `Bearer ${this.options.token}` } } : {}),
301
+ lease = await this.acquireLease(this.readSignal(job.signal));
302
+ if (this.closed || this.retired)
303
+ throw cancelled('The browser session was closed.');
304
+ if (job.signal?.aborted || job.cancelRequested)
305
+ throw cancelled('The browser read was cancelled.');
306
+ const reader = this.readerFor(job, lease);
307
+ const value = await job.run(reader, lease.generation.page);
308
+ if (job.cancelRequested)
309
+ throw cancelled('The browser read was cancelled; the operation in flight was allowed to finish.');
310
+ job.resolve(value);
311
+ }
312
+ catch (error) {
313
+ // A rate-limit answer means the site pushed back. Keep this session at one concurrent read
314
+ // for the rest of its life; in-flight reads are not interrupted and nothing is replayed.
315
+ if (error instanceof SearchError && error.kind === 'rate-limit')
316
+ this.lowerAdmission();
317
+ job.reject(job.cancelRequested && !(error instanceof SearchError && error.kind === 'cancelled')
318
+ ? cancelled('The browser read was cancelled; the operation in flight was allowed to finish.')
319
+ : error);
320
+ }
321
+ finally {
322
+ if (lease)
323
+ this.releaseLease(lease);
324
+ this.activeJobs.delete(job);
325
+ this.activeCount = Math.max(0, this.activeCount - 1);
326
+ if (this.activeCount === 0)
327
+ this.resolveZeroWaiters();
328
+ this.pump();
329
+ this.afterActivity();
330
+ }
331
+ }
332
+ readSignal(signal) {
333
+ return signal ? AbortSignal.any([signal, this.shutdown.signal]) : this.shutdown.signal;
334
+ }
335
+ lowerAdmission() {
336
+ // Conservative local slowdown, held until this BrowserSession is replaced. It is not a claimed
337
+ // official quota or cooldown and does not auto-recover on a page/context rebuild.
338
+ if (this.admissionLimit !== 1)
339
+ this.admissionLimit = 1;
340
+ }
341
+ // --- generation ----------------------------------------------------------------------------
342
+ async acquireLease(signal) {
343
+ for (;;) {
344
+ if (this.closed || this.retired)
345
+ throw cancelled('The browser session was closed.');
346
+ const generation = await this.ensureGeneration(signal);
347
+ if (this.closed || this.retired)
348
+ throw cancelled('The browser session was closed.');
349
+ if (generation.stale) {
350
+ await abortable(this.disposeGeneration(generation), signal);
351
+ continue;
352
+ }
353
+ // A tab closed or a connection lost between generations is noticed here, before a new read
354
+ // is bound to it, and rebuilt without failing the caller.
355
+ if (!generation.browser.isConnected()) {
356
+ this.markGenerationStale(generation, 'connection');
357
+ await abortable(this.disposeGeneration(generation), signal);
358
+ continue;
359
+ }
360
+ if (generation.page.isClosed()) {
361
+ this.markGenerationStale(generation, 'page');
362
+ await abortable(this.disposeGeneration(generation), signal);
363
+ continue;
364
+ }
365
+ generation.inflight += 1;
366
+ if (this.closed || this.retired || this.generation !== generation || generation.stale) {
367
+ this.releaseLease({ generation, released: false });
368
+ if (this.closed || this.retired)
369
+ throw cancelled('The browser session was closed.');
370
+ continue;
371
+ }
372
+ return { generation, released: false };
373
+ }
374
+ }
375
+ async ensureGeneration(signal) {
376
+ for (;;) {
377
+ if (this.closed || this.retired)
378
+ throw cancelled('The browser session was closed.');
379
+ const current = this.generation;
380
+ if (current?.stale) {
381
+ await abortable(this.disposeGeneration(current), signal);
382
+ continue;
383
+ }
384
+ if (current)
385
+ return current;
386
+ if (this.disposal) {
387
+ await abortable(this.disposal, signal);
388
+ continue;
389
+ }
390
+ if (!this.opening) {
391
+ const opening = this.openGeneration();
392
+ this.opening = opening;
393
+ void opening
394
+ .finally(() => {
395
+ if (this.opening === opening)
396
+ this.opening = undefined;
397
+ this.afterActivity();
398
+ })
399
+ .catch(() => undefined);
400
+ }
401
+ const opening = this.opening;
402
+ const generation = await abortable(opening, signal);
403
+ if (this.closed || this.retired)
404
+ throw cancelled('The browser session was closed.');
405
+ if (generation.stale)
406
+ continue;
407
+ return generation;
408
+ }
409
+ }
410
+ releaseLease(lease) {
411
+ if (lease.released)
412
+ return;
413
+ lease.released = true;
414
+ const generation = lease.generation;
415
+ generation.inflight = Math.max(0, generation.inflight - 1);
416
+ if (generation.stale && generation.inflight === 0) {
417
+ generation.resolveDrained();
418
+ void this.beginDisposal(generation);
419
+ }
420
+ }
421
+ markGenerationStale(generation, reason) {
422
+ if (this.generation !== generation)
423
+ return;
424
+ if (reason === 'connection' || generation.staleReason === undefined) {
425
+ generation.staleReason = reason === 'connection' ? 'connection' : (generation.staleReason ?? 'page');
426
+ }
427
+ generation.stale = true;
428
+ if (generation.inflight === 0) {
429
+ generation.resolveDrained();
430
+ void this.beginDisposal(generation);
431
+ }
432
+ }
433
+ /** Single-flight disposal of one stale generation; waits for its in-flight reads to exit. */
434
+ beginDisposal(generation) {
435
+ if (generation.disposal)
436
+ return generation.disposal;
437
+ const disposal = (async () => {
438
+ await generation.drained;
439
+ await bounded(this.disposeGenerationResources(generation), this.closeWaitMs());
440
+ })();
441
+ generation.disposal = disposal;
442
+ this.disposal = disposal;
443
+ void disposal
444
+ .finally(() => {
445
+ if (this.disposal === disposal)
446
+ this.disposal = undefined;
447
+ this.afterActivity();
448
+ })
449
+ .catch(() => undefined);
450
+ return disposal;
451
+ }
452
+ async disposeGeneration(generation) {
453
+ return this.beginDisposal(generation);
454
+ }
455
+ async disposeGenerationResources(generation) {
456
+ if (this.generation === generation)
457
+ this.generation = undefined;
458
+ if (this.page === generation.page)
459
+ this.page = undefined;
460
+ if (generation.staleReason === 'page') {
461
+ // The tab went away but the connection and context are healthy: only the page is rebuilt.
462
+ try {
463
+ await generation.page.close();
464
+ }
465
+ catch {
466
+ // Already closed.
467
+ }
468
+ return;
469
+ }
470
+ if (this.browser === generation.browser) {
471
+ const browser = this.browser;
472
+ this.browser = undefined;
473
+ try {
474
+ await browser.close();
475
+ }
476
+ catch {
477
+ // Already gone.
478
+ }
479
+ }
480
+ if (this.context === generation.context) {
481
+ const context = this.context;
482
+ this.context = undefined;
483
+ try {
484
+ await context.close();
485
+ }
486
+ catch {
487
+ // Already gone.
488
+ }
489
+ }
490
+ }
491
+ // --- page ----------------------------------------------------------------------------------
492
+ /** Single-flight open of a new generation, optionally reusing a healthy connection/context. */
493
+ async openGeneration() {
494
+ if (this.closed || this.retired)
495
+ throw cancelled('The browser session was closed before it could attach.');
496
+ let page;
497
+ if (this.browser?.isConnected() && this.context) {
498
+ try {
499
+ page = this.context.pages().find(candidate => !candidate.isClosed()) ?? await this.context.newPage();
500
+ }
501
+ catch {
502
+ await this.resetResources();
503
+ }
504
+ }
505
+ if (this.closed || this.retired) {
506
+ await this.resetResources();
507
+ throw cancelled('The browser session was closed while it was attaching.');
508
+ }
509
+ if (!page) {
510
+ await this.resetResources();
511
+ const browser = await this.connectBrowser();
512
+ if (this.closed || this.retired) {
513
+ this.browser = undefined;
514
+ await browser.close().catch(() => undefined);
515
+ throw cancelled('The browser session was closed while it was attaching.');
516
+ }
517
+ this.browser = browser;
518
+ // Contexts belong to the client that created them, so this process owns the only one it can
519
+ // see; the keeper's context is a different client's and is never touched. A saved session is
520
+ // loaded here, if one exists.
521
+ const saved = this.savedStatePath();
522
+ const context = await browser.newContext({
523
+ locale: 'zh-CN',
524
+ // viewport: null keeps the browser window at its real size instead of emulating one.
525
+ viewport: null,
526
+ ...(saved ? { storageState: saved } : {}),
23
527
  });
528
+ if (this.closed || this.retired) {
529
+ // close() won the race while newContext was in flight: close this late context now.
530
+ await bounded((async () => {
531
+ await context.close().catch(() => undefined);
532
+ await this.dropResources();
533
+ })(), this.closeWaitMs());
534
+ throw cancelled('The browser session was closed while it was creating its context.');
535
+ }
536
+ this.context = context;
537
+ page = context.pages().find(candidate => !candidate.isClosed()) ?? await context.newPage();
538
+ if (this.closed || this.retired) {
539
+ await this.resetResources();
540
+ throw cancelled('The browser session was closed while it was creating its page.');
541
+ }
542
+ }
543
+ this.page = page;
544
+ let ready;
545
+ try {
546
+ ready = await this.ensureOnSite(page);
547
+ }
548
+ catch (error) {
549
+ if (this.closed || this.retired)
550
+ await this.resetResources();
551
+ throw error;
552
+ }
553
+ if (this.closed || this.retired) {
554
+ await this.resetResources();
555
+ throw cancelled('The browser session was closed while it was attaching.');
556
+ }
557
+ const browser = this.browser;
558
+ const context = this.context;
559
+ if (!browser || !context) {
560
+ await this.resetResources();
561
+ throw new SearchError('protocol', 'The browser session lost its resources while attaching.');
562
+ }
563
+ const generation = createGeneration(browser, context, ready);
564
+ this.generation = generation;
565
+ return generation;
566
+ }
567
+ async connectBrowser() {
568
+ if (this.browser?.isConnected())
24
569
  return this.browser;
570
+ await this.resetResources();
571
+ try {
572
+ const browser = await (this.options.connect ?? defaultConnect)(this.options);
573
+ if (this.closed || this.retired) {
574
+ await browser.close().catch(() => undefined);
575
+ throw cancelled('The browser session was closed while it was attaching.');
576
+ }
577
+ this.browser = browser;
578
+ return browser;
25
579
  }
26
580
  catch (error) {
581
+ if (error instanceof SearchError)
582
+ throw error;
27
583
  throw connectFailure(error, this.options);
28
584
  }
29
585
  }
30
- /** Reuse the page the browser already has; open one only when it has none. */
31
- async target() {
32
- if (this.page && !this.page.isClosed())
33
- return this.ensureOnSite(this.page);
34
- const browser = await this.connect();
35
- // Contexts belong to the client that created them, so this process owns the only one: it is
36
- // also the window the VNC viewer sees. A saved session is loaded here, if one exists.
37
- const statePath = this.options.statePath;
38
- const saved = statePath && existsSync(statePath) ? statePath : undefined;
39
- const context = browser.contexts().find(candidate => candidate.pages().every(page => !page.isClosed()))
40
- // viewport: null keeps the browser window at its real size instead of emulating one, which is
41
- // what makes the window visible on the container's display for the one-time sign-in.
42
- ?? await browser.newContext({ locale: 'zh-CN', viewport: null, ...(saved ? { storageState: saved } : {}) });
43
- const existing = context.pages().find(page => !page.isClosed());
44
- this.page = existing ?? await context.newPage();
45
- this.context = context;
46
- const ready = await this.ensureOnSite(this.page);
47
- // Launching a browser server suppresses Chrome's startup window, so the tab has to ask for the
48
- // window: without this the page runs, but the display the VNC viewer looks at stays empty.
49
- await ready.bringToFront().catch(() => undefined);
50
- return ready;
51
- }
52
586
  async ensureOnSite(page) {
53
- if (page.url().includes(SITE_HOST))
587
+ if (sameSite(page.url(), this.options.siteUrl))
54
588
  return page;
589
+ if (this.closed)
590
+ throw cancelled('The browser session was closed while it was opening the site.');
55
591
  try {
56
592
  await page.goto(this.options.siteUrl, { waitUntil: 'domcontentloaded', timeout: this.options.timeoutMs });
57
593
  }
58
594
  catch (error) {
595
+ if (this.closed)
596
+ throw cancelled('The browser session was closed while it was opening the site.');
59
597
  throw new SearchError('network', `Could not open ${this.options.siteUrl} in the browser: ${message(error)}`);
60
598
  }
599
+ // No bringToFront here: the page window belongs to whoever signs in over VNC, and a read must
600
+ // not pull focus away from it.
61
601
  return page;
62
602
  }
63
- async evaluate(script) {
64
- const page = await this.target();
603
+ /** Bounded reset used by open/close paths so a wedged teardown cannot block a read forever. */
604
+ async resetResources() {
605
+ await bounded(this.dropResources(), this.closeWaitMs());
606
+ }
607
+ async dropResources() {
608
+ const browser = this.browser;
609
+ const context = this.context;
610
+ this.browser = undefined;
611
+ this.context = undefined;
612
+ this.page = undefined;
613
+ // Drop the connection first: it must not depend on a page or context closing gracefully.
65
614
  try {
66
- // Playwright treats a string argument as an expression and never calls it, so the generated
67
- // source becomes a function here and is serialised to the page like any other page function.
68
- const pageFunction = new Function(`return (${script});`)();
69
- // The site's own client lives in the main world, so this call opts out of patchright's
70
- // isolated-context default; isolation would hide the very runtime we need to reach.
71
- return await page.evaluate(pageFunction, undefined, {}, false);
615
+ await browser?.close();
72
616
  }
73
- catch (error) {
74
- throw new SearchError('protocol', `The Xiaohongshu page refused to run the read: ${message(error)}`);
617
+ catch {
618
+ // Already gone.
619
+ }
620
+ try {
621
+ await context?.close();
622
+ }
623
+ catch {
624
+ // Already gone.
75
625
  }
76
626
  }
77
- /**
78
- * Persist the session so the next process starts signed in. Writing on every read would be
79
- * wasteful, so it happens at most once a minute and only after a call actually succeeded.
80
- */
81
- async persist() {
627
+ savedStatePath() {
628
+ const statePath = this.options.statePath;
629
+ return statePath && existsSync(statePath) ? statePath : undefined;
630
+ }
631
+ // --- reader ---------------------------------------------------------------------------------
632
+ readerFor(job, lease) {
633
+ return {
634
+ evaluate: async (script) => {
635
+ const stop = () => {
636
+ throw cancelled('The browser read was cancelled before the next page operation started.');
637
+ };
638
+ if (this.closed || this.retired)
639
+ throw cancelled('The browser session was closed.');
640
+ if (job.signal?.aborted || job.cancelRequested)
641
+ stop();
642
+ const page = lease.generation.page;
643
+ if (page.isClosed()) {
644
+ this.markGenerationStale(lease.generation, 'page');
645
+ throw new SearchError('protocol', `The ${siteName(this.options.siteUrl)} page was closed before the read started.`);
646
+ }
647
+ try {
648
+ // Playwright treats a string argument as an expression and never calls it, so the
649
+ // generated source becomes a function here and is serialised like any page function.
650
+ const pageFunction = new Function(`return (${script});`)();
651
+ // The site's own client lives in the main world, so this call opts out of patchright's
652
+ // isolated-context default; isolation would hide the very runtime we need to reach.
653
+ return await page.evaluate(pageFunction, undefined, {}, false);
654
+ }
655
+ catch (error) {
656
+ if (this.closed || this.retired)
657
+ throw cancelled('The browser session was closed during the read.');
658
+ if (!lease.generation.browser.isConnected())
659
+ this.markGenerationStale(lease.generation, 'connection');
660
+ else if (page.isClosed())
661
+ this.markGenerationStale(lease.generation, 'page');
662
+ throw new SearchError('protocol', `The ${siteName(this.options.siteUrl)} page refused to run the read: ${message(error)}`);
663
+ }
664
+ },
665
+ invalidate: () => {
666
+ this.markGenerationStale(lease.generation, 'connection');
667
+ },
668
+ };
669
+ }
670
+ // --- persist -------------------------------------------------------------------------------
671
+ async persistUnlocked() {
672
+ if (this.options.statePolicy === 'read-only')
673
+ return;
82
674
  const statePath = this.options.statePath;
83
- if (!statePath || !this.context)
675
+ const context = this.context;
676
+ if (!statePath || !context)
84
677
  return;
85
- if (Date.now() - this.savedAt < 60_000)
678
+ if (Date.now() - this.savedAt < PERSIST_INTERVAL_MS)
86
679
  return;
87
- this.savedAt = Date.now();
88
- await this.context.storageState({ path: statePath }).catch(() => undefined);
680
+ try {
681
+ await context.storageState({ path: statePath });
682
+ // Only a completed save moves the clock, so a failed save is retried next time.
683
+ this.savedAt = Date.now();
684
+ }
685
+ catch {
686
+ // A failed save must not fail a read or a close; the next call tries again.
687
+ }
89
688
  }
90
- async close() {
91
- // Only the connection is dropped; the user's browser keeps running with whatever page state it had.
92
- await this.persist();
93
- await this.browser?.close().catch(() => undefined);
94
- this.browser = undefined;
689
+ runMaintenance(fn) {
690
+ if (this.maintenance)
691
+ return this.maintenance;
692
+ const task = (async () => {
693
+ if (this.closed || this.retired)
694
+ return;
695
+ this.maintenanceRequested = true;
696
+ this.clearIdleTimer();
697
+ try {
698
+ await abortable(new Promise(resolve => {
699
+ if (this.activeCount === 0)
700
+ resolve();
701
+ else
702
+ this.zeroWaiters.push(resolve);
703
+ }), this.shutdown.signal);
704
+ if (this.closed || this.retired)
705
+ return;
706
+ this.maintenanceRequested = false;
707
+ this.maintenanceRunning = true;
708
+ try {
709
+ await fn();
710
+ }
711
+ finally {
712
+ this.maintenanceRunning = false;
713
+ }
714
+ }
715
+ finally {
716
+ this.maintenanceRequested = false;
717
+ this.maintenanceRunning = false;
718
+ this.pump();
719
+ this.afterActivity();
720
+ }
721
+ })();
722
+ this.maintenance = task;
723
+ void task
724
+ .finally(() => {
725
+ if (this.maintenance === task)
726
+ this.maintenance = undefined;
727
+ })
728
+ .catch(() => undefined);
729
+ return task;
730
+ }
731
+ // --- idle ----------------------------------------------------------------------------------
732
+ scheduleIdle() {
733
+ this.clearIdleTimer();
734
+ if (!this.canIdle())
735
+ return;
736
+ const idleMs = this.options.idleTimeoutMs ?? DEFAULT_IDLE_MS;
737
+ if (idleMs <= 0)
738
+ return;
739
+ const timer = setTimeout(() => {
740
+ this.idleTimer = undefined;
741
+ void this.runIdle();
742
+ }, idleMs);
743
+ timer.unref?.();
744
+ this.idleTimer = timer;
745
+ }
746
+ canIdle() {
747
+ return (!this.closed &&
748
+ !this.retired &&
749
+ !this.idleDisposed &&
750
+ !this.idleRunning &&
751
+ !this.opening &&
752
+ !this.disposal &&
753
+ !this.maintenanceRequested &&
754
+ !this.maintenanceRunning &&
755
+ this.activeCount === 0 &&
756
+ this.waiters.length === 0);
757
+ }
758
+ async runIdle() {
759
+ if (!this.canIdle())
760
+ return;
761
+ this.idleRunning = true;
762
+ this.clearIdleTimer();
763
+ try {
764
+ this.generation = undefined;
765
+ this.page = undefined;
766
+ await bounded(this.dropResources(), this.closeWaitMs());
767
+ if (this.closed || this.retired)
768
+ return;
769
+ if (this.waiters.length > 0) {
770
+ // A read arrived while the teardown was running. Keep this instance and let it reattach.
771
+ this.idleDisposed = false;
772
+ return;
773
+ }
774
+ if (this.onDisposed) {
775
+ // A registered instance is retired with its map entry; a stale reference must not reattach
776
+ // and race the fresh instance the registry will hand out.
777
+ this.retired = true;
778
+ try {
779
+ this.onDisposed();
780
+ }
781
+ catch {
782
+ // The registry callback is best effort.
783
+ }
784
+ return;
785
+ }
786
+ this.idleDisposed = true;
787
+ }
788
+ finally {
789
+ this.idleRunning = false;
790
+ this.pump();
791
+ this.afterActivity();
792
+ }
793
+ }
794
+ afterActivity() {
795
+ if (this.activeCount === 0)
796
+ this.resolveZeroWaiters();
797
+ if (this.canIdle())
798
+ this.scheduleIdle();
799
+ else
800
+ this.clearIdleTimer();
801
+ }
802
+ clearIdleTimer() {
803
+ if (this.idleTimer === undefined)
804
+ return;
805
+ clearTimeout(this.idleTimer);
806
+ this.idleTimer = undefined;
807
+ }
808
+ // --- shutdown ------------------------------------------------------------------------------
809
+ closeWaitMs() {
810
+ return this.options.closeTimeoutMs ?? DEFAULT_CLOSE_MS;
811
+ }
812
+ cancelWaiters() {
813
+ const waiters = this.waiters;
814
+ this.waiters = [];
815
+ for (const job of waiters) {
816
+ job.cancelled = true;
817
+ job.reject(cancelled('The browser session was closed.'));
818
+ }
819
+ }
820
+ resolveZeroWaiters() {
821
+ if (this.activeCount !== 0 || this.zeroWaiters.length === 0)
822
+ return;
823
+ const waiters = this.zeroWaiters.splice(0);
824
+ for (const resolve of waiters)
825
+ resolve();
826
+ }
827
+ async waitForActiveZero(timeoutMs) {
828
+ if (this.activeCount === 0)
829
+ return true;
830
+ if (timeoutMs <= 0)
831
+ return false;
832
+ let timer;
833
+ const timeout = new Promise(resolve => {
834
+ timer = setTimeout(() => resolve(false), timeoutMs);
835
+ timer.unref?.();
836
+ });
837
+ const zero = new Promise(resolve => {
838
+ this.zeroWaiters.push(() => resolve(true));
839
+ });
840
+ const result = await Promise.race([zero, timeout]);
841
+ if (timer !== undefined)
842
+ clearTimeout(timer);
843
+ return result;
844
+ }
845
+ async disposeAfterClose() {
846
+ // One deadline for the whole shutdown: waiting for reads, the best-effort save and the forced
847
+ // teardown all spend from the same budget. A slice is reserved for the teardown, so a read that
848
+ // uses the whole wait still cannot leave the connection undropped.
849
+ const total = Math.max(0, this.closeWaitMs());
850
+ const deadline = Date.now() + total;
851
+ const teardownReserve = Math.min(1_000, Math.max(1, Math.floor(total / 4)));
852
+ const finished = await this.waitForActiveZero(Math.max(0, deadline - Date.now() - teardownReserve));
853
+ if (!finished) {
854
+ // The grace window expired. Mark every in-flight read as cancelled so the failure the forced
855
+ // close causes is reported as `cancelled`, not as a protocol error; a read that finished
856
+ // inside the window kept its own result.
857
+ for (const job of this.activeJobs)
858
+ job.cancelRequested = true;
859
+ }
860
+ else if (!this.maintenanceRunning && !this.maintenanceRequested) {
861
+ const persistBudget = Math.max(0, deadline - Date.now() - teardownReserve);
862
+ if (persistBudget > 0)
863
+ await bounded(this.persistUnlocked(), persistBudget);
864
+ }
865
+ this.generation = undefined;
95
866
  this.page = undefined;
96
- this.context = undefined;
867
+ // A wedged browser can also make the teardown hang; report completion after the budget and let
868
+ // it finish in the background. Nothing can use this session any more.
869
+ await bounded(this.dropResources(), Math.max(1, deadline - Date.now()));
870
+ // Settle internal zero-wait promises even if a stuck transaction never reached zero; their
871
+ // callers are already closed and this only prevents retained callbacks.
872
+ const zeroWaiters = this.zeroWaiters.splice(0);
873
+ for (const resolve of zeroWaiters)
874
+ resolve();
875
+ try {
876
+ this.onDisposed?.();
877
+ }
878
+ catch {
879
+ // The registry callback is best effort.
880
+ }
97
881
  }
98
882
  }
99
- const message = (error) => (error instanceof Error ? error.message : String(error));
100
883
  /** A refused endpoint, a missing one and a version mismatch each need a different fix. */
101
884
  export function connectFailure(error, options) {
102
885
  const text = message(error);
@@ -113,17 +896,25 @@ export function connectFailure(error, options) {
113
896
  }
114
897
  /** Sessions are shared by endpoint: one connection, many readers, one page per site. */
115
898
  const sessions = new Map();
116
- /** The session for an endpoint, created on first use and reused for the life of the process. */
899
+ /** The session for an endpoint, created on first use and reused until it closes or idles out. */
117
900
  export function sessionFor(key, options) {
118
- let session = sessions.get(key);
119
- if (!session) {
120
- session = new BrowserSession(options);
121
- sessions.set(key, session);
122
- }
123
- return session;
901
+ const existing = sessions.get(key);
902
+ if (existing && !existing.isClosed)
903
+ return existing;
904
+ let created;
905
+ created = new BrowserSession(options, () => {
906
+ // Idle release and an explicit close both free the map entry; the next caller gets a new
907
+ // session that reattaches on demand instead of the map growing with dead entries.
908
+ if (sessions.get(key) === created)
909
+ sessions.delete(key);
910
+ });
911
+ sessions.set(key, created);
912
+ return created;
124
913
  }
125
914
  /** Close every kept session; the host calls this when it shuts down. */
126
915
  export async function closeBrowserSessions() {
916
+ // Truncate synchronously so a sessionFor() racing the shutdown starts a fresh session instead
917
+ // of joining one that is being disposed.
127
918
  const open = [...sessions.values()];
128
919
  sessions.clear();
129
920
  await Promise.all(open.map(session => session.close().catch(() => undefined)));