@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.d.ts CHANGED
@@ -1,9 +1,10 @@
1
- import { type Page } from 'patchright-core';
1
+ import { type Browser, type Page } from 'patchright-core';
2
2
  import { SearchError } from './transport.js';
3
+ export { DEFAULT_MAX_CONCURRENT_READS } from './browser-limits.js';
3
4
  /**
4
5
  * One connection to the browser the user runs. The browser belongs to them: this class never
5
6
  * launches anything, never installs anything and never touches the profile — it attaches, reuses
6
- * the page that is already there, and evaluates scripts inside it.
7
+ * its own context and page for the site, and admits a bounded number of concurrent reads.
7
8
  */
8
9
  export interface BrowserSessionOptions {
9
10
  /** Playwright server endpoint, for example ws://127.0.0.1:3000/xhs. */
@@ -18,29 +19,159 @@ export interface BrowserSessionOptions {
18
19
  * file only lets a fresh connection start already signed in.
19
20
  */
20
21
  statePath?: string;
22
+ /**
23
+ * What this session may do with `statePath`. The default, `read-write`, keeps the old contract:
24
+ * a caller that owns the file may persist it. A session that shares the browser with a process
25
+ * that already writes the file (the keeper in the shipped image) sets `read-only` instead: it
26
+ * loads the file into every new context and never writes it back.
27
+ */
28
+ statePolicy?: 'read-only' | 'read-write';
29
+ /**
30
+ * How many read transactions may be in flight on this site at once. The default of 2 is a
31
+ * deliberately conservative local starting point, not a Xiaohongshu limit and not verified
32
+ * against the live site. Accepted values are integers from 1 through 8; anything else is a
33
+ * configuration error rather than a silent clamp.
34
+ */
35
+ maxConcurrentReads?: number;
36
+ /**
37
+ * Whole shutdown budget for `close()`: the wait for in-flight reads plus the teardown are paid
38
+ * from this one deadline. Defaults to 5000ms.
39
+ */
40
+ closeTimeoutMs?: number;
41
+ /**
42
+ * How long the session may sit idle before it releases its own connection and context. The
43
+ * session object stays usable and reattaches on the next read. `0` disables idle release.
44
+ */
45
+ idleTimeoutMs?: number;
46
+ /** Injected in tests; production attaches with patchright. */
47
+ connect?: (options: BrowserSessionOptions) => Promise<Browser>;
48
+ }
49
+ /**
50
+ * The only thing a read transaction may do with the page: run one script and report that the
51
+ * cached page/context went stale. A transaction gets no way to close or persist the session,
52
+ * because the session belongs to the process, not to one read.
53
+ */
54
+ export interface BrowserReader {
55
+ /** Run one page script while the transaction owns one admission slot. */
56
+ evaluate<T>(script: string): Promise<T>;
57
+ /**
58
+ * Mark this read's page generation stale. Use it when the read proved the page is no longer
59
+ * usable (for example an expired sign-in), not for failures that belong to the subject of the
60
+ * read (a private note). New reads wait for the in-flight generation to drain and then start
61
+ * from the current state file; the failed read itself is never replayed.
62
+ */
63
+ invalidate(): void;
21
64
  }
65
+ /**
66
+ * One kept browser connection per site.
67
+ *
68
+ * Reads are transactions. Up to `maxConcurrentReads` of them may be in flight on the same page;
69
+ * an admission limiter shared by every read API keeps that bound and a FIFO waiter list keeps
70
+ * admission fair. A transaction is health probe plus the page script plus mapping, so the two
71
+ * stages of different transactions can interleave while each result still belongs to its own
72
+ * async call.
73
+ *
74
+ * The page belongs to a generation with an in-flight reference count. Initialisation is
75
+ * single-flight. A stale generation (expired sign-in, lost connection, closed tab) stops admitting
76
+ * new reads, lets its in-flight reads finish, and is disposed before the next generation opens.
77
+ * The only things that release resources are an idle timeout, an explicit shutdown and that
78
+ * generation recycle. The window a human signs into belongs to the keeper's separate client, not
79
+ * to this context, and nothing here touches it.
80
+ */
22
81
  export declare class BrowserSession {
23
82
  private readonly options;
83
+ /** Called after the session released its resources; the registry drops the idle entry. */
84
+ private readonly onDisposed?;
24
85
  private browser;
86
+ private context;
25
87
  private page;
26
88
  private savedAt;
27
- private context;
28
- constructor(options: BrowserSessionOptions);
29
- private connect;
30
- /** Reuse the page the browser already has; open one only when it has none. */
31
- target(): Promise<Page>;
32
- private ensureOnSite;
89
+ private generation;
90
+ private opening;
91
+ private disposal;
92
+ private idleTimer;
93
+ private idleDisposed;
94
+ private idleRunning;
95
+ private retired;
96
+ private closed;
97
+ private closing;
98
+ private admissionLimit;
99
+ private activeCount;
100
+ private waiters;
101
+ private readonly activeJobs;
102
+ private readonly zeroWaiters;
103
+ private pumping;
104
+ private maintenance;
105
+ private maintenanceRequested;
106
+ private maintenanceRunning;
107
+ private readonly shutdown;
108
+ constructor(options: BrowserSessionOptions,
109
+ /** Called after the session released its resources; the registry drops the idle entry. */
110
+ onDisposed?: (() => void) | undefined);
111
+ get isClosed(): boolean;
112
+ /**
113
+ * Run one read transaction. The callback gets a narrow reader and owns one admission slot from
114
+ * before its first page operation until it settles. An abort that arrives while the transaction
115
+ * is waiting rejects at once; an abort that arrives while a page call is in flight is observed
116
+ * before the next operation, because a browser call cannot be interrupted mid-flight.
117
+ */
118
+ read<T>(run: (reader: BrowserReader) => Promise<T>, signal?: AbortSignal): Promise<T>;
119
+ /** Legacy single-script entry point. It now uses the same admission limiter as `read`. */
33
120
  evaluate<T>(script: string): Promise<T>;
121
+ /** Legacy way to get the page. The admission slot is released before the caller uses it. */
122
+ target(): Promise<Page>;
34
123
  /**
35
- * Persist the session so the next process starts signed in. Writing on every read would be
36
- * wasteful, so it happens at most once a minute and only after a call actually succeeded.
124
+ * Persist the session so the next process starts signed in. Runs as exclusive maintenance:
125
+ * admission pauses and waits for in-flight reads to settle first. Skipped in `read-only` mode,
126
+ * rate-limited, and `savedAt` moves only after a save actually succeeded.
127
+ *
128
+ * Do not call this from inside a read transaction; it waits for the transaction to finish.
37
129
  */
38
130
  persist(): Promise<void>;
131
+ /**
132
+ * Close this session for good. New reads are refused, queued reads are cancelled, in-flight
133
+ * reads get a bounded grace period (one total deadline with the teardown), and the connection is
134
+ * dropped even if a read is still stuck. Idempotent, including when called concurrently.
135
+ */
39
136
  close(): Promise<void>;
137
+ private enqueue;
138
+ private pump;
139
+ private runJob;
140
+ private readSignal;
141
+ private lowerAdmission;
142
+ private acquireLease;
143
+ private ensureGeneration;
144
+ private releaseLease;
145
+ private markGenerationStale;
146
+ /** Single-flight disposal of one stale generation; waits for its in-flight reads to exit. */
147
+ private beginDisposal;
148
+ private disposeGeneration;
149
+ private disposeGenerationResources;
150
+ /** Single-flight open of a new generation, optionally reusing a healthy connection/context. */
151
+ private openGeneration;
152
+ private connectBrowser;
153
+ private ensureOnSite;
154
+ /** Bounded reset used by open/close paths so a wedged teardown cannot block a read forever. */
155
+ private resetResources;
156
+ private dropResources;
157
+ private savedStatePath;
158
+ private readerFor;
159
+ private persistUnlocked;
160
+ private runMaintenance;
161
+ private scheduleIdle;
162
+ private canIdle;
163
+ private runIdle;
164
+ private afterActivity;
165
+ private clearIdleTimer;
166
+ private closeWaitMs;
167
+ private cancelWaiters;
168
+ private resolveZeroWaiters;
169
+ private waitForActiveZero;
170
+ private disposeAfterClose;
40
171
  }
41
172
  /** A refused endpoint, a missing one and a version mismatch each need a different fix. */
42
173
  export declare function connectFailure(error: unknown, options: BrowserSessionOptions): SearchError;
43
- /** The session for an endpoint, created on first use and reused for the life of the process. */
174
+ /** The session for an endpoint, created on first use and reused until it closes or idles out. */
44
175
  export declare function sessionFor(key: string, options: BrowserSessionOptions): BrowserSession;
45
176
  /** Close every kept session; the host calls this when it shuts down. */
46
177
  export declare function closeBrowserSessions(): Promise<void>;