@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/README.md +84 -56
- package/README.zh.md +111 -0
- package/dist/adapters.d.ts +6 -1
- package/dist/adapters.js +65 -15
- package/dist/browser-backends.js +1 -0
- package/dist/browser-limits.d.ts +11 -0
- package/dist/browser-limits.js +11 -0
- package/dist/browser.d.ts +142 -11
- package/dist/browser.js +856 -65
- package/dist/catalog.js +1 -1
- package/dist/config.js +27 -17
- package/dist/index.d.ts +5 -2
- package/dist/index.js +3 -1
- package/dist/static.d.ts +1 -0
- package/dist/static.js +1 -0
- package/dist/types.d.ts +5 -0
- package/dist/xhs/index.d.ts +13 -3
- package/dist/xhs/index.js +77 -44
- package/dist/xhs/render.d.ts +33 -0
- package/dist/xhs/render.js +52 -0
- package/package.json +5 -4
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
|
-
*
|
|
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
|
|
28
|
-
|
|
29
|
-
private
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
private
|
|
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.
|
|
36
|
-
*
|
|
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
|
|
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>;
|