2026-10-13 19:36:37 +03:00
|
|
|
import type { BrowserObservationEndpoint } from "../domain/browserObservation.js";
|
2026-10-16 06:46:26 +08:00
|
|
|
import { AnalysisError } from "../domain/analysisErrorBase.js";
|
|
|
|
|
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
|
2026-10-06 05:57:38 +08:00
|
|
|
import { BrowserObservationError } from "../domain/browserObservationError.js";
|
2026-10-10 21:04:05 -07:00
|
|
|
import type { BrowserObservationOperation } from "../domain/browserObservationErrors.js";
|
2026-07-14 20:22:12 +00:00
|
|
|
import { CdpConnection } from "./CdpConnection.js";
|
2026-10-17 00:33:10 +08:00
|
|
|
import {
|
|
|
|
|
CdpTargetSessionOwner,
|
|
|
|
|
bindCdpTransportCleanup,
|
|
|
|
|
} from "./CdpTargetSessionOwner.js";
|
2026-07-14 20:22:12 +00:00
|
|
|
import {
|
|
|
|
|
cdpTargetWebSocket,
|
2026-10-13 19:36:37 +03:00
|
|
|
discoverCdpBrowserSocket,
|
|
|
|
|
discoverCdpEndpoint,
|
|
|
|
|
withCdpDiscoveryDeadline,
|
2026-07-14 20:22:12 +00:00
|
|
|
type CdpEndpointDiscovery,
|
|
|
|
|
type CdpEndpointTarget,
|
|
|
|
|
} from "./CdpEndpoint.js";
|
|
|
|
|
|
|
|
|
|
/** One CDP connection scoped either by a flat browser session or page socket. */
|
|
|
|
|
export interface CdpTargetSession {
|
|
|
|
|
readonly connection: CdpConnection;
|
|
|
|
|
readonly sessionId: string | undefined;
|
|
|
|
|
}
|
|
|
|
|
|
2026-10-13 19:36:37 +03:00
|
|
|
/** Discovery for one caller-selected endpoint and the browser socket that read it. */
|
|
|
|
|
export interface CdpOpenedEndpoint {
|
|
|
|
|
readonly discovery: CdpEndpointDiscovery;
|
|
|
|
|
/**
|
|
|
|
|
* Browser socket kept for the target session, because a browser may ask
|
|
|
|
|
* the user to approve each socket. HTTP discovery opens no socket.
|
|
|
|
|
*/
|
|
|
|
|
readonly connection: CdpConnection | undefined;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Discover one passive browser endpoint through its selected transport. A
|
|
|
|
|
* browser socket's handshake and discovery share one discovery deadline.
|
|
|
|
|
*/
|
|
|
|
|
export const openCdpEndpoint = async (
|
|
|
|
|
endpoint: BrowserObservationEndpoint,
|
|
|
|
|
operation: BrowserObservationOperation,
|
|
|
|
|
signal?: AbortSignal,
|
|
|
|
|
timeoutMs?: number,
|
2026-10-16 06:46:26 +08:00
|
|
|
owner?: CdpTargetSessionOwner,
|
2026-10-13 19:36:37 +03:00
|
|
|
): Promise<CdpOpenedEndpoint> => {
|
|
|
|
|
if (endpoint.transport === "http_discovery")
|
|
|
|
|
return {
|
|
|
|
|
discovery: await discoverCdpEndpoint(endpoint.url, operation, signal),
|
|
|
|
|
connection: undefined,
|
|
|
|
|
};
|
|
|
|
|
return await withCdpDiscoveryDeadline(
|
|
|
|
|
operation,
|
|
|
|
|
signal,
|
|
|
|
|
async (deadlineSignal) => {
|
2026-10-16 06:46:26 +08:00
|
|
|
const connection =
|
|
|
|
|
owner === undefined
|
|
|
|
|
? await CdpConnection.connect(endpoint.url, operation, deadlineSignal)
|
|
|
|
|
: await owner.connect(
|
|
|
|
|
endpoint.url,
|
|
|
|
|
operation,
|
|
|
|
|
{ signal: deadlineSignal },
|
|
|
|
|
"browser-endpoint",
|
|
|
|
|
);
|
2026-10-13 19:36:37 +03:00
|
|
|
try {
|
|
|
|
|
return {
|
|
|
|
|
discovery: await discoverCdpBrowserSocket(
|
|
|
|
|
connection,
|
|
|
|
|
endpoint.url,
|
|
|
|
|
operation,
|
|
|
|
|
deadlineSignal,
|
|
|
|
|
),
|
|
|
|
|
connection,
|
|
|
|
|
};
|
|
|
|
|
} catch (cause: unknown) {
|
2026-10-16 06:46:26 +08:00
|
|
|
if (owner === undefined) {
|
|
|
|
|
await connection.close();
|
|
|
|
|
throw cause;
|
|
|
|
|
}
|
|
|
|
|
try {
|
|
|
|
|
await owner.finish(connection);
|
|
|
|
|
} catch (cleanupCause: unknown) {
|
|
|
|
|
throw combineOpenFailure(cause, cleanupCause, operation);
|
|
|
|
|
}
|
2026-10-13 19:36:37 +03:00
|
|
|
throw cause;
|
|
|
|
|
}
|
|
|
|
|
},
|
|
|
|
|
timeoutMs,
|
|
|
|
|
);
|
|
|
|
|
};
|
|
|
|
|
|
2026-07-14 20:22:12 +00:00
|
|
|
/** Open one authorized target through its supported browser or page transport. */
|
|
|
|
|
export const openCdpTargetSession = async (
|
|
|
|
|
discovery: CdpEndpointDiscovery,
|
|
|
|
|
target: CdpEndpointTarget,
|
|
|
|
|
operation: BrowserObservationOperation,
|
|
|
|
|
signal?: AbortSignal,
|
2026-10-07 21:45:07 +08:00
|
|
|
limits?: { readonly maxPayloadBytes: number },
|
2026-10-16 06:46:26 +08:00
|
|
|
owner?: CdpTargetSessionOwner,
|
2026-07-14 20:22:12 +00:00
|
|
|
): Promise<CdpTargetSession> => {
|
|
|
|
|
const webSocket = cdpTargetWebSocket(discovery, target, operation);
|
2026-10-16 06:46:26 +08:00
|
|
|
const connection =
|
|
|
|
|
owner === undefined
|
|
|
|
|
? await CdpConnection.connect(webSocket.url, operation, signal, limits)
|
|
|
|
|
: await owner.connect(
|
|
|
|
|
webSocket.url,
|
|
|
|
|
operation,
|
|
|
|
|
signal === undefined ? {} : { signal },
|
|
|
|
|
target.id,
|
|
|
|
|
limits,
|
|
|
|
|
);
|
2026-07-14 20:22:12 +00:00
|
|
|
if (webSocket.scope === "page") return { connection, sessionId: undefined };
|
2026-10-16 06:46:26 +08:00
|
|
|
try {
|
|
|
|
|
return await attachCdpTargetSession(
|
|
|
|
|
connection,
|
|
|
|
|
target,
|
|
|
|
|
operation,
|
|
|
|
|
signal,
|
|
|
|
|
owner,
|
|
|
|
|
);
|
|
|
|
|
} catch (cause: unknown) {
|
|
|
|
|
if (owner === undefined) throw cause;
|
|
|
|
|
try {
|
|
|
|
|
await owner.finish(connection);
|
|
|
|
|
} catch (cleanupCause: unknown) {
|
|
|
|
|
throw combineOpenFailure(cause, cleanupCause, operation);
|
|
|
|
|
}
|
|
|
|
|
throw cause;
|
|
|
|
|
}
|
2026-10-13 19:36:37 +03:00
|
|
|
};
|
|
|
|
|
|
|
|
|
|
/** Attach one target through an open browser socket, which the session then owns. */
|
|
|
|
|
export const attachCdpTargetSession = async (
|
|
|
|
|
connection: CdpConnection,
|
|
|
|
|
target: CdpEndpointTarget,
|
|
|
|
|
operation: BrowserObservationOperation,
|
|
|
|
|
signal?: AbortSignal,
|
2026-10-16 06:46:26 +08:00
|
|
|
owner?: CdpTargetSessionOwner,
|
2026-10-13 19:36:37 +03:00
|
|
|
): Promise<CdpTargetSession> => {
|
2026-07-14 20:22:12 +00:00
|
|
|
try {
|
|
|
|
|
const attached = await connection.send(
|
|
|
|
|
"Target.attachToTarget",
|
|
|
|
|
{ targetId: target.id, flatten: true },
|
|
|
|
|
undefined,
|
|
|
|
|
signal,
|
|
|
|
|
);
|
|
|
|
|
return { connection, sessionId: attachedSessionId(attached, operation) };
|
|
|
|
|
} catch (cause: unknown) {
|
2026-10-16 06:46:26 +08:00
|
|
|
if (owner === undefined) {
|
|
|
|
|
await connection.close();
|
|
|
|
|
throw cause;
|
|
|
|
|
}
|
2026-07-14 20:22:12 +00:00
|
|
|
throw cause;
|
|
|
|
|
}
|
|
|
|
|
};
|
|
|
|
|
|
2026-10-16 06:46:26 +08:00
|
|
|
const combineOpenFailure = (
|
|
|
|
|
primary: unknown,
|
|
|
|
|
cleanup: unknown,
|
|
|
|
|
operation: BrowserObservationOperation,
|
|
|
|
|
): unknown =>
|
|
|
|
|
primary instanceof AnalysisError && cleanup instanceof AnalysisError
|
2026-10-17 00:33:10 +08:00
|
|
|
? bindCdpTransportCleanup(
|
|
|
|
|
cleanup,
|
|
|
|
|
analysisErrorWithCleanupFailure(primary, cleanup, operation),
|
|
|
|
|
)
|
2026-10-16 06:46:26 +08:00
|
|
|
: new AggregateError(
|
|
|
|
|
[primary, cleanup],
|
|
|
|
|
`CDP operation ${operation} failed and its transport cleanup is incomplete.`,
|
|
|
|
|
{ cause: primary },
|
|
|
|
|
);
|
|
|
|
|
|
2026-07-14 20:22:12 +00:00
|
|
|
/** Disable enabled domains, detach browser sessions, and close REA's socket. */
|
|
|
|
|
export const closeCdpTargetSession = async (
|
|
|
|
|
targetSession: CdpTargetSession,
|
|
|
|
|
enabledDomains: readonly string[],
|
2026-10-05 02:58:33 -04:00
|
|
|
signal?: AbortSignal,
|
2026-10-16 06:46:26 +08:00
|
|
|
owner?: CdpTargetSessionOwner,
|
|
|
|
|
): Promise<void> => {
|
|
|
|
|
if (owner !== undefined) {
|
|
|
|
|
await owner.finish(targetSession.connection, () =>
|
|
|
|
|
cleanupCdpTargetCommands(targetSession, enabledDomains, signal),
|
|
|
|
|
);
|
|
|
|
|
return;
|
|
|
|
|
}
|
|
|
|
|
await cleanupCdpTargetCommands(targetSession, enabledDomains, signal);
|
|
|
|
|
await targetSession.connection.close();
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
const cleanupCdpTargetCommands = async (
|
|
|
|
|
targetSession: CdpTargetSession,
|
|
|
|
|
enabledDomains: readonly string[],
|
|
|
|
|
signal?: AbortSignal,
|
2026-07-14 20:22:12 +00:00
|
|
|
): Promise<void> => {
|
|
|
|
|
const { connection, sessionId } = targetSession;
|
2026-10-11 00:03:22 +08:00
|
|
|
const cleanup = new AbortController();
|
2026-10-11 02:54:12 +08:00
|
|
|
const domainSignal =
|
|
|
|
|
signal === undefined
|
|
|
|
|
? cleanup.signal
|
|
|
|
|
: AbortSignal.any([cleanup.signal, signal]);
|
2026-10-11 00:03:22 +08:00
|
|
|
const timeout = setTimeout(() => cleanup.abort(), 1_000);
|
|
|
|
|
timeout.unref();
|
2026-10-05 02:58:33 -04:00
|
|
|
try {
|
2026-10-11 00:03:22 +08:00
|
|
|
if (signal?.aborted !== true) {
|
|
|
|
|
for (const domain of enabledDomains) {
|
2026-10-11 02:54:12 +08:00
|
|
|
if (domainSignal.aborted) break;
|
2026-10-11 00:03:22 +08:00
|
|
|
try {
|
|
|
|
|
await connection.send(
|
|
|
|
|
`${domain}.disable`,
|
|
|
|
|
{},
|
|
|
|
|
sessionId,
|
2026-10-11 02:54:12 +08:00
|
|
|
domainSignal,
|
2026-10-11 00:03:22 +08:00
|
|
|
);
|
|
|
|
|
} catch {
|
|
|
|
|
// Best-effort domain cleanup; transport close is the definitive boundary.
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
2026-10-11 01:00:30 +08:00
|
|
|
// Cancellation skips optional domain shutdown but still releases the
|
|
|
|
|
// attached session using its independent, bounded cleanup signal.
|
|
|
|
|
if (!cleanup.signal.aborted && sessionId !== undefined)
|
|
|
|
|
try {
|
|
|
|
|
await connection.send(
|
|
|
|
|
"Target.detachFromTarget",
|
|
|
|
|
{ sessionId },
|
|
|
|
|
undefined,
|
|
|
|
|
cleanup.signal,
|
|
|
|
|
);
|
|
|
|
|
} catch {
|
|
|
|
|
// Best-effort detach; transport close is the definitive boundary.
|
|
|
|
|
}
|
2026-10-05 02:58:33 -04:00
|
|
|
} finally {
|
2026-10-11 00:03:22 +08:00
|
|
|
clearTimeout(timeout);
|
|
|
|
|
cleanup.abort();
|
2026-10-05 02:58:33 -04:00
|
|
|
}
|
|
|
|
|
};
|
|
|
|
|
|
2026-07-14 20:22:12 +00:00
|
|
|
const attachedSessionId = (
|
|
|
|
|
value: unknown,
|
|
|
|
|
operation: BrowserObservationOperation,
|
|
|
|
|
): string => {
|
|
|
|
|
if (
|
|
|
|
|
typeof value !== "object" ||
|
|
|
|
|
value === null ||
|
|
|
|
|
!("sessionId" in value) ||
|
|
|
|
|
typeof value.sessionId !== "string" ||
|
2026-09-29 13:56:49 +08:00
|
|
|
value.sessionId.length === 0
|
2026-07-14 20:22:12 +00:00
|
|
|
)
|
|
|
|
|
throw new BrowserObservationError(operation, "protocol_error");
|
|
|
|
|
return value.sessionId;
|
|
|
|
|
};
|