mirror of
https://github.com/morluto/rea.git
synced 2026-11-16 19:53:50 +00:00
* refactor(errors): give caller aborts a typed reason at the adapters Squashes 908813551f, 87858de4dc (fix(mcp): preserve cancellation reasons in handlers) and fa151dc3f6 (test(server): race handler-entry gates against the triggering tool call) onto main without #10566's pre-squash commits. * refactor(errors): give owner-initiated aborts a typed reason outside the browser adapters (#10692) * refactor(errors): give owner-initiated aborts a typed reason outside the browser adapters * refactor(verify): keep the abort-reason scan receiver-independent Playwright's route.abort takes a network error code; the one call site now names its default code instead of the guard exempting a variable name. * refactor(browser): give owner-initiated CDP aborts typed reasons (#10706) * refactor(browser): give owner-initiated CDP aborts typed reasons * fix(browser): give the page-side request fetch page-native abort reasons The request callback runs in the page through page.evaluate and cannot reach REA's modules. Define its deadline and cleanup reasons as DOMExceptions inside the callback, and make the test fake evaluate the callback from its source so module imports are unavailable, as in a page. * test(process): expect the reader close's typed owner reason Closing the Darwin run-token reader aborts its compilation with OwnerCancellation.ownerClosed since the owner-abort change in this PR; the boundary test still expected the default DOMException. * fix(server): report HTTP session replacement and shutdown to pending tools as an owner close
839 lines
30 KiB
TypeScript
839 lines
30 KiB
TypeScript
import { Deadline } from "../domain/deadline.js";
|
|
import { jsonStringByteLength } from "../domain/jsonStringByteLength.js";
|
|
import { jsonValueByteLength } from "../domain/jsonValueByteLength.js";
|
|
import type { JsonValue } from "../domain/jsonValue.js";
|
|
import {
|
|
MAX_SAVED_RESPONSE_CHARACTERS,
|
|
MAX_SAVED_RESPONSE_BYTES,
|
|
responsePointerValue,
|
|
parseScenarioValueJson,
|
|
readResponseValues,
|
|
readBoundedResponseBody,
|
|
} from "./BrowserScenarioResponseValues.js";
|
|
import type { Page, Request, Route } from "playwright-core";
|
|
|
|
import {
|
|
HEADER_FIELD_VALUE,
|
|
SAVED_PLACEHOLDER,
|
|
validBasicCredentialUsername,
|
|
type BrowserScenarioAction,
|
|
type BrowserScenarioCredentialPart,
|
|
type BrowserScenarioRequestHeader,
|
|
type BrowserScenarioSaveEntry,
|
|
type BrowserScenarioSaveResponse,
|
|
} from "../domain/browserScenarioValues.js";
|
|
import type { BrowserScenarioSecrets } from "./BrowserScenarioSecrets.js";
|
|
import {
|
|
scenarioSerializationAllowance,
|
|
scenarioQueryLength,
|
|
uriComponentLength,
|
|
} from "./BrowserScenarioSerialization.js";
|
|
|
|
type RequestAction = Extract<BrowserScenarioAction, { action: "request" }>;
|
|
|
|
/** What the page's fetch returned; a redirect is not followed, so its status is unknown. */
|
|
type PageResponse =
|
|
| { readonly status: number; readonly body?: string }
|
|
| { readonly redirected: true }
|
|
| { readonly left: string }
|
|
| { readonly error: string };
|
|
|
|
/** A request step that could not be sent or did not answer as expected. */
|
|
class ScenarioRequestError extends Error {
|
|
override readonly name = "ScenarioRequestError";
|
|
}
|
|
|
|
const originOf = (url: string): string | undefined => {
|
|
try {
|
|
return new URL(url).origin;
|
|
} catch {
|
|
return undefined;
|
|
}
|
|
};
|
|
|
|
interface PageValueStep {
|
|
readonly page: Page;
|
|
readonly url: URL;
|
|
readonly stepId: string;
|
|
readonly secrets: BrowserScenarioSecrets;
|
|
}
|
|
|
|
/** Read a value from the page, a cookie or a local storage entry, and redact it from later records under a label. */
|
|
const readPageValue = async (
|
|
step: PageValueStep,
|
|
value: Extract<
|
|
BrowserScenarioCredentialPart,
|
|
{ source: "cookie" | "local_storage" }
|
|
>,
|
|
label: string,
|
|
): Promise<string> => {
|
|
const { page, url, stepId, secrets } = step;
|
|
let read: string | undefined;
|
|
if (value.source === "cookie") {
|
|
const cookies = await page.context().cookies(url.href);
|
|
read = cookies.find((cookie) => cookie.name === value.name)?.value;
|
|
if (read === undefined)
|
|
throw new ScenarioRequestError(
|
|
`Request step ${stepId}: cookie ${value.name} is not set for ${url.origin}.`,
|
|
);
|
|
} else {
|
|
const stored = await page.evaluate(
|
|
({ key, origin }) => {
|
|
if (
|
|
(globalThis as { readonly location?: { origin: string } }).location
|
|
?.origin !== origin
|
|
)
|
|
throw new Error(
|
|
"The page moved off the start origin before its local storage was read.",
|
|
);
|
|
return (
|
|
(
|
|
globalThis as {
|
|
readonly localStorage?: { getItem(key: string): string | null };
|
|
}
|
|
).localStorage?.getItem(key) ?? null
|
|
);
|
|
},
|
|
{ key: value.key, origin: url.origin },
|
|
);
|
|
if (stored === null)
|
|
throw new ScenarioRequestError(
|
|
`Request step ${stepId}: local storage has no ${value.key} on ${url.origin}.`,
|
|
);
|
|
if (value.json_pointer === undefined) read = stored;
|
|
else {
|
|
const parsed = parseScenarioValueJson(stored);
|
|
if (!parsed.ok) {
|
|
throw new ScenarioRequestError(
|
|
`Request step ${stepId}: local storage ${value.key} is not JSON.`,
|
|
);
|
|
}
|
|
const selected = responsePointerValue(parsed.value, value.json_pointer);
|
|
if (typeof selected === "number" && !Number.isFinite(selected))
|
|
throw new ScenarioRequestError(
|
|
`Request step ${stepId}: local storage ${value.key} has a number at ${value.json_pointer} that cannot be read exactly.`,
|
|
);
|
|
read =
|
|
typeof selected === "string" || typeof selected === "number"
|
|
? String(selected)
|
|
: undefined;
|
|
if (read === undefined)
|
|
throw new ScenarioRequestError(
|
|
`Request step ${stepId}: local storage ${value.key} has no string or number at ${value.json_pointer}.`,
|
|
);
|
|
}
|
|
}
|
|
secrets.admitPageValue(label, read);
|
|
return read;
|
|
};
|
|
|
|
/** One part of Basic credentials: a literal, secret or saved value, or a value read from the page. */
|
|
const credentialPart = (
|
|
step: PageValueStep,
|
|
part: BrowserScenarioCredentialPart,
|
|
label: string,
|
|
): Promise<string> | string =>
|
|
part.source === "cookie" || part.source === "local_storage"
|
|
? readPageValue(step, part, label)
|
|
: step.secrets.value(part);
|
|
|
|
/** Resolve one header value; values read from the page, and credentials built from them, are redacted from later records. */
|
|
const headerValue = async (
|
|
step: PageValueStep,
|
|
header: BrowserScenarioRequestHeader,
|
|
): Promise<string> => {
|
|
const { stepId, secrets } = step;
|
|
const { value } = header;
|
|
const label = `${stepId}.${header.name}`;
|
|
if (
|
|
value.source === "literal" ||
|
|
value.source === "secret" ||
|
|
value.source === "saved"
|
|
)
|
|
return secrets.value(value);
|
|
if (value.source === "basic_credentials") {
|
|
const [username, password] = value.parts;
|
|
const user = await credentialPart(step, username!, `${label}.username`);
|
|
if (!validBasicCredentialUsername(user))
|
|
throw new ScenarioRequestError(
|
|
`Request step ${stepId} has a Basic username with a colon, which the server would read as the end of the username.`,
|
|
);
|
|
const pass = await credentialPart(step, password!, `${label}.password`);
|
|
return secrets.basicCredential(label, user, pass);
|
|
}
|
|
return readPageValue(step, value, label);
|
|
};
|
|
|
|
/** Append admitted query entries after any literal query the path carries, leaving that query as written. */
|
|
const withQuery = (
|
|
url: URL,
|
|
entries: readonly (readonly [string, string])[],
|
|
): string => {
|
|
if (entries.length === 0) return url.href;
|
|
// fetch drops the fragment; cut it at its "#" even when nothing follows it.
|
|
const hash = url.href.indexOf("#");
|
|
const base = hash < 0 ? url.href : url.href.slice(0, hash);
|
|
const separator = !base.includes("?")
|
|
? "?"
|
|
: base.endsWith("?") || base.endsWith("&")
|
|
? ""
|
|
: "&";
|
|
const budget =
|
|
scenarioSerializationAllowance() - base.length - separator.length;
|
|
if (scenarioQueryLength(entries, budget, "uri-component") > budget)
|
|
throw requestEnvelopeError();
|
|
const added = entries
|
|
.map(
|
|
([name, value]) =>
|
|
`${encodeURIComponent(name)}=${encodeURIComponent(value)}`,
|
|
)
|
|
.join("&");
|
|
return `${base}${separator}${added}`;
|
|
};
|
|
|
|
/** What a request step sends: the URL, the origin it must be sent from, and the call. */
|
|
interface PageRequest {
|
|
readonly url: string;
|
|
readonly origin: string;
|
|
readonly method: string;
|
|
readonly headers: [string, string][];
|
|
readonly body: string | undefined;
|
|
/**
|
|
* The step deadline on the page's wall clock. The host keeps a monotonic
|
|
* deadline and converts what is left of it when the request is built,
|
|
* because the page cannot read the host's monotonic clock.
|
|
*/
|
|
readonly deadlineEpochMs: number | undefined;
|
|
/** Return the response text up to this many characters, for a step that saves values from it. */
|
|
readonly readLimit: number | undefined;
|
|
}
|
|
|
|
/** Send the request with the page's own fetch, from the page's main world, and read the whole answer. */
|
|
const sendFromPage = (
|
|
page: Page,
|
|
request: PageRequest,
|
|
): Promise<PageResponse> =>
|
|
page.evaluate(async (request): Promise<PageResponse> => {
|
|
// The page may have navigated since the origin check; never send from another origin.
|
|
const here = (globalThis as { readonly location?: { origin: string } })
|
|
.location?.origin;
|
|
if (here !== request.origin) return { left: String(here) };
|
|
if (
|
|
(
|
|
globalThis as {
|
|
readonly navigator?: { serviceWorker?: { controller?: unknown } };
|
|
}
|
|
).navigator?.serviceWorker?.controller
|
|
)
|
|
return {
|
|
error:
|
|
"Request steps require a page without a controlling service worker so cancellation can guard dispatch.",
|
|
};
|
|
const remaining =
|
|
request.deadlineEpochMs === undefined
|
|
? undefined
|
|
: request.deadlineEpochMs - Date.now();
|
|
if (remaining !== undefined && remaining <= 0)
|
|
return { error: "The request ran out of time before it was sent." };
|
|
// This callback runs in the page, which cannot reach REA's modules, so
|
|
// its abort reasons are page-native DOMExceptions defined here.
|
|
const controller = new AbortController();
|
|
const timer =
|
|
remaining === undefined
|
|
? undefined
|
|
: setTimeout(
|
|
() =>
|
|
controller.abort(
|
|
new DOMException(
|
|
"The request ran out of time.",
|
|
"TimeoutError",
|
|
),
|
|
),
|
|
remaining,
|
|
);
|
|
try {
|
|
const answer = await fetch(request.url, {
|
|
method: request.method,
|
|
headers: request.headers,
|
|
credentials: "same-origin",
|
|
redirect: "manual",
|
|
signal: controller.signal,
|
|
...(request.body === undefined ? {} : { body: request.body }),
|
|
});
|
|
if (answer.type === "opaqueredirect") return { redirected: true };
|
|
if (request.readLimit !== undefined) {
|
|
// Keep the text only up to the limit, so a large answer is never held whole.
|
|
const reader = answer.body?.getReader();
|
|
if (reader === undefined) return { status: answer.status, body: "" };
|
|
const decoder = new TextDecoder("utf-8", {
|
|
fatal: true,
|
|
ignoreBOM: true,
|
|
});
|
|
let text = "";
|
|
try {
|
|
for (;;) {
|
|
const chunk = await reader.read();
|
|
if (chunk.done) break;
|
|
text += decoder.decode(chunk.value, { stream: true });
|
|
if (text.length > request.readLimit) {
|
|
await reader.cancel();
|
|
return { status: answer.status };
|
|
}
|
|
}
|
|
} finally {
|
|
reader.releaseLock();
|
|
}
|
|
return { status: answer.status, body: text + decoder.decode() };
|
|
}
|
|
const reader = answer.body?.getReader();
|
|
if (reader !== undefined)
|
|
try {
|
|
while (!(await reader.read()).done) {
|
|
// Wait for completion without retaining a second response body.
|
|
}
|
|
} finally {
|
|
reader.releaseLock();
|
|
}
|
|
return { status: answer.status };
|
|
} catch (cause: unknown) {
|
|
controller.abort(
|
|
new DOMException("The request is no longer needed.", "AbortError"),
|
|
);
|
|
return {
|
|
error: cause instanceof Error ? cause.message : String(cause),
|
|
};
|
|
} finally {
|
|
if (timer !== undefined) clearTimeout(timer);
|
|
}
|
|
}, request);
|
|
|
|
/**
|
|
* Send one request from the page with its own fetch, cookies and session, as
|
|
* the application's frontend would, and read the whole response so the
|
|
* capture can record it. The page must be on the scenario's start origin.
|
|
*/
|
|
export const performScenarioRequest = async (input: {
|
|
readonly page: Page;
|
|
readonly action: RequestAction;
|
|
readonly secrets: BrowserScenarioSecrets;
|
|
readonly startOrigin: string;
|
|
readonly signal?: AbortSignal | undefined;
|
|
readonly onOpaqueRedirect?: (() => void) | undefined;
|
|
}): Promise<void> => {
|
|
const { page, action, secrets, startOrigin, signal } = input;
|
|
const deadline =
|
|
action.timeout_ms === undefined
|
|
? undefined
|
|
: Deadline.after(action.timeout_ms);
|
|
const pageOrigin = originOf(page.url());
|
|
if (pageOrigin !== startOrigin)
|
|
throw new ScenarioRequestError(
|
|
`Request step ${action.step_id} runs from a page on the start origin ${startOrigin}; navigate back to it with a goto step first.`,
|
|
);
|
|
const url = new URL(withSavedPlaceholders(action.path, secrets), startOrigin);
|
|
if (url.origin !== startOrigin)
|
|
throw new ScenarioRequestError(
|
|
`Request step ${action.step_id} must stay on the start origin ${startOrigin}.`,
|
|
);
|
|
const target = withQuery(
|
|
url,
|
|
action.query.map(({ name, value }) => [name, secrets.value(value)]),
|
|
);
|
|
const step = { page, url, stepId: action.step_id, secrets };
|
|
const headers: [string, string][] = [];
|
|
const envelopeLimit = scenarioSerializationAllowance();
|
|
let headerBytes = 2;
|
|
const headerValues = new Map<string, number>();
|
|
const appendHeader = (name: string, value: string): void => {
|
|
const knownSize = headerValues.get(value);
|
|
const size =
|
|
knownSize ?? jsonStringByteLength(value, envelopeLimit - headerBytes);
|
|
headerBytes +=
|
|
(headers.length === 0 ? 0 : 1) +
|
|
jsonValueByteLength([name, null], envelopeLimit - headerBytes) -
|
|
4 +
|
|
size;
|
|
if (headerBytes > envelopeLimit) throw requestEnvelopeError();
|
|
if (knownSize === undefined) {
|
|
if (!HEADER_FIELD_VALUE.test(value))
|
|
throw new ScenarioRequestError(
|
|
`Request step ${action.step_id}: the ${name} value holds characters a header cannot carry, such as a line break.`,
|
|
);
|
|
headerValues.set(value, size);
|
|
}
|
|
headers.push([name, value]);
|
|
};
|
|
for (const header of action.headers)
|
|
appendHeader(
|
|
header.name,
|
|
`${header.prefix ?? ""}${await headerValue(step, header)}`,
|
|
);
|
|
const hasContentType = headers.some(
|
|
([name]) => name.toLowerCase() === "content-type",
|
|
);
|
|
if (action.json !== undefined && !hasContentType)
|
|
appendHeader("content-type", "application/json");
|
|
// A step the boundary abandoned, or whose time ran out while values were read, sends nothing.
|
|
if (signal?.aborted === true || deadline?.expired() === true)
|
|
throw new ScenarioRequestError(
|
|
`Request step ${action.step_id} ran out of time before its request was sent.`,
|
|
);
|
|
if (action.json !== undefined) admitSavedJson(action.json, secrets);
|
|
const json =
|
|
action.json === undefined ? undefined : withSavedJson(action.json, secrets);
|
|
const request = {
|
|
url: target,
|
|
origin: startOrigin,
|
|
method: action.method,
|
|
headers,
|
|
body: json === undefined ? undefined : JSON.stringify(json),
|
|
deadlineEpochMs:
|
|
deadline === undefined ? undefined : Date.now() + deadline.remainingMs(),
|
|
readLimit:
|
|
action.save.length > 0 ? MAX_SAVED_RESPONSE_CHARACTERS : undefined,
|
|
};
|
|
if (
|
|
jsonValueByteLength(
|
|
{
|
|
url: target,
|
|
origin: startOrigin,
|
|
method: action.method,
|
|
headers: [],
|
|
body: request.body ?? null,
|
|
deadlineEpochMs: request.deadlineEpochMs ?? null,
|
|
readLimit: request.readLimit ?? null,
|
|
},
|
|
envelopeLimit,
|
|
) +
|
|
headerBytes -
|
|
2 >
|
|
envelopeLimit
|
|
)
|
|
throw requestEnvelopeError();
|
|
// The browser can queue evaluate behind a busy page. Keep a host-side gate
|
|
// until that evaluation settles, including after the step boundary stops
|
|
// waiting. A queued fetch then observes live cancellation at dispatch.
|
|
const dispatchUrl = new URL(target);
|
|
dispatchUrl.hash = "";
|
|
const matches = (url: URL): boolean => url.href === dispatchUrl.href;
|
|
const protectResponse = secrets.responseProtector(
|
|
action.step_id,
|
|
action.save,
|
|
);
|
|
const matchesRequest = (sent: Request): boolean =>
|
|
sent.method() === request.method &&
|
|
sent.postData() === (request.body ?? null);
|
|
let observedRequest: Request | undefined;
|
|
let ambiguousRequest = false;
|
|
const watch = (sent: Request): void => {
|
|
if (sent.url() === dispatchUrl.href && matchesRequest(sent)) {
|
|
if (observedRequest === undefined) observedRequest = sent;
|
|
else if (observedRequest !== sent) ambiguousRequest = true;
|
|
protectResponse?.(sent);
|
|
}
|
|
};
|
|
const gate = async (route: Route): Promise<void> => {
|
|
const sent = route.request();
|
|
if (!matchesRequest(sent)) {
|
|
await route.fallback();
|
|
return;
|
|
}
|
|
if (signal?.aborted === true || deadline?.expired() === true)
|
|
await route.abort("aborted");
|
|
else {
|
|
await route.fallback();
|
|
}
|
|
};
|
|
await page.route(matches, gate);
|
|
if (protectResponse !== undefined) page.on("request", watch);
|
|
let primaryFailure: { readonly cause: unknown } | undefined;
|
|
let response: PageResponse;
|
|
try {
|
|
response = await sendFromPage(page, request);
|
|
if ("error" in response)
|
|
throw new ScenarioRequestError(
|
|
`Request step ${action.step_id} failed in the page: ${response.error}`,
|
|
);
|
|
if ("left" in response)
|
|
throw new ScenarioRequestError(
|
|
`Request step ${action.step_id} runs from a page on the start origin ${startOrigin}; the page moved before the request was sent.`,
|
|
);
|
|
if ("redirected" in response) {
|
|
input.onOpaqueRedirect?.();
|
|
throw new ScenarioRequestError(
|
|
`Request step ${action.step_id} was answered with a redirect, which request steps do not follow; a write may already have been applied. The browser may withhold the redirect status and Location from network capture.`,
|
|
);
|
|
}
|
|
if (
|
|
action.expected_status !== undefined &&
|
|
!action.expected_status.includes(response.status)
|
|
)
|
|
throw new ScenarioRequestError(
|
|
`Request step ${action.step_id} answered ${String(response.status)}; expected ${action.expected_status.join(" or ")}.`,
|
|
);
|
|
} catch (cause: unknown) {
|
|
primaryFailure = { cause };
|
|
throw cause;
|
|
} finally {
|
|
if (protectResponse !== undefined) page.off("request", watch);
|
|
try {
|
|
await page.unroute(matches, gate);
|
|
} catch (cause: unknown) {
|
|
if (primaryFailure !== undefined)
|
|
throw new AggregateError(
|
|
[primaryFailure.cause, cause],
|
|
`Scenario request failed: ${primaryFailure.cause instanceof Error ? primaryFailure.cause.message : String(primaryFailure.cause)}; route cleanup failed: ${cause instanceof Error ? cause.message : String(cause)}`,
|
|
{ cause: primaryFailure.cause },
|
|
);
|
|
throw cause;
|
|
}
|
|
}
|
|
if (action.save.length > 0) {
|
|
assertResponseSaveActive(action.step_id, deadline, signal);
|
|
saveValues(action.step_id, response.body, action.save, secrets);
|
|
if (observedRequest !== undefined && !ambiguousRequest)
|
|
secrets.markResponseSecretsReady(observedRequest);
|
|
}
|
|
};
|
|
|
|
/** A URL path segment a URL parser drops or folds into its parent: `.`, `..` or a percent-encoded spelling of one. */
|
|
const DOT_SEGMENT = /^(?:\.|%2e){1,2}$/iu;
|
|
|
|
/** A path or URL with its `placeholder`s filled, each value percent-encoded; a request path's are spelled as written. A filled path segment a URL path would drop as a dot segment fails the step. */
|
|
export const withSavedPlaceholders = (
|
|
text: string,
|
|
secrets: BrowserScenarioSecrets,
|
|
placeholder: RegExp = SAVED_PLACEHOLDER,
|
|
): string => {
|
|
const limit = scenarioSerializationAllowance();
|
|
let expandedUnits = text.length;
|
|
if (expandedUnits > limit)
|
|
throw new ScenarioRequestError(
|
|
"Saved URL exceeds the current heap/string serialization allowance.",
|
|
);
|
|
const encoded = new Map<string, string>();
|
|
const fill = (part: string): string =>
|
|
part.replace(placeholder, (matched, name: string) => {
|
|
let replacement = encoded.get(name);
|
|
if (replacement === undefined) {
|
|
const raw = String(secrets.savedValue(name));
|
|
if (uriComponentLength(raw, limit) > limit)
|
|
throw new ScenarioRequestError(
|
|
"Saved URL encoding exceeds the current heap/string serialization allowance.",
|
|
);
|
|
replacement = encodeURIComponent(raw);
|
|
encoded.set(name, replacement);
|
|
}
|
|
expandedUnits += replacement.length - matched.length;
|
|
if (expandedUnits > limit)
|
|
throw new ScenarioRequestError(
|
|
"Expanded saved URL exceeds the current heap/string serialization allowance.",
|
|
);
|
|
return replacement;
|
|
});
|
|
const pathEnd = text.search(/[?#]/u);
|
|
const path = pathEnd < 0 ? text : text.slice(0, pathEnd);
|
|
// WHATWG special URLs treat literal backslashes as path separators too.
|
|
const filledPath = path.replace(/[^/\\]+/gu, (segment) => {
|
|
const filled = fill(segment);
|
|
if (filled !== segment && DOT_SEGMENT.test(filled))
|
|
throw new Error(
|
|
`A saved value makes the path segment ${JSON.stringify(segment)} a dot segment, which a URL path drops, so the step cannot send it.`,
|
|
);
|
|
return filled;
|
|
});
|
|
return filledPath + (pathEnd < 0 ? "" : fill(text.slice(pathEnd)));
|
|
};
|
|
|
|
/** Whether a request a UI step triggered is the one its `save_response` names: method, start origin, and path with `{*}` matching one segment. */
|
|
/** A `save_response` path's segments as a browser spells a URL path, percent-encoded as its URL parser would, `{*}` kept. */
|
|
const pathPattern = (path: string): readonly string[] => {
|
|
const pathname = path.split("?")[0]!;
|
|
let wildcard = "~rea-wildcard~";
|
|
while (pathname.includes(wildcard)) wildcard += "~";
|
|
const marked = pathname
|
|
.split(/[\\/]/u)
|
|
.map((segment) => (segment === "{*}" ? wildcard : segment))
|
|
.join("/");
|
|
return new URL(marked, "http://path.invalid").pathname
|
|
.split("/")
|
|
.map((segment) => (segment === wildcard ? "{*}" : segment));
|
|
};
|
|
|
|
const namesResponse = (
|
|
spec: BrowserScenarioSaveResponse,
|
|
pattern: readonly string[],
|
|
startOrigin: string,
|
|
request: { readonly method: string; readonly url: string },
|
|
): boolean => {
|
|
if (request.method !== spec.method) return false;
|
|
const url = URL.parse(request.url);
|
|
if (url === null || url.origin !== startOrigin) return false;
|
|
const segments = url.pathname.split("/");
|
|
return (
|
|
segments.length === pattern.length &&
|
|
pattern.every((part, index) => part === "{*}" || part === segments[index])
|
|
);
|
|
};
|
|
|
|
/** Publication must still belong to the step after its last asynchronous boundary. */
|
|
const assertResponseSaveActive = (
|
|
stepId: string,
|
|
deadline: Deadline | undefined,
|
|
signal: AbortSignal | undefined,
|
|
): void => {
|
|
if (signal?.aborted === true || deadline?.expired() === true)
|
|
throw new ScenarioRequestError(
|
|
`Step ${stepId} ended before its saved response was read, so nothing was saved.`,
|
|
);
|
|
};
|
|
|
|
/** Settle as the work does, or fail the step once its deadline passes or it is cancelled, so late work saves nothing. */
|
|
const beforeStepEnds = <T>(
|
|
work: Promise<T>,
|
|
stepId: string,
|
|
deadline: Deadline | undefined,
|
|
signal: AbortSignal | undefined,
|
|
): Promise<T> =>
|
|
new Promise<T>((resolve, reject) => {
|
|
let timer: ReturnType<typeof setTimeout> | undefined;
|
|
const settle = (): void => {
|
|
if (timer !== undefined) clearTimeout(timer);
|
|
signal?.removeEventListener("abort", end);
|
|
};
|
|
const end = (): void => {
|
|
settle();
|
|
reject(
|
|
new ScenarioRequestError(
|
|
`Step ${stepId} ended before its saved response was read, so nothing was saved.`,
|
|
),
|
|
);
|
|
};
|
|
work.catch(() => undefined);
|
|
const remaining = deadline?.remainingMs();
|
|
if (
|
|
signal?.aborted === true ||
|
|
(remaining !== undefined && remaining <= 0)
|
|
) {
|
|
end();
|
|
return;
|
|
}
|
|
if (remaining !== undefined) timer = setTimeout(end, remaining);
|
|
signal?.addEventListener("abort", end, { once: true });
|
|
work.then(
|
|
(value) => {
|
|
settle();
|
|
resolve(value);
|
|
},
|
|
(cause: unknown) => {
|
|
settle();
|
|
reject(cause);
|
|
},
|
|
);
|
|
});
|
|
|
|
/** A UI step's wait for the response its `save_response` names: `saved` waits and saves, `stop` stops watching requests. */
|
|
export interface SavedResponseWait {
|
|
readonly saved: () => Promise<void>;
|
|
readonly stop: () => void;
|
|
}
|
|
|
|
/**
|
|
* Observe a new matching response while the UI step waits; matching does not prove action causality.
|
|
* Requests already running are excluded. Competing requests observed before binding are ambiguous.
|
|
* The step still requires a 2xx JSON response within its timeout or the page's default timeout.
|
|
*/
|
|
export const awaitSavedResponse = (
|
|
page: Page,
|
|
step: {
|
|
readonly stepId: string;
|
|
readonly spec: BrowserScenarioSaveResponse;
|
|
readonly startOrigin: string;
|
|
readonly timeout: number | undefined;
|
|
readonly secrets: BrowserScenarioSecrets;
|
|
readonly signal?: AbortSignal | undefined;
|
|
},
|
|
): SavedResponseWait => {
|
|
const { stepId, spec, startOrigin, timeout, secrets, signal } = step;
|
|
const deadline = timeout === undefined ? undefined : Deadline.after(timeout);
|
|
const pattern = pathPattern(spec.path);
|
|
const started = new Set<Request>();
|
|
const protectResponse = secrets.responseProtector(stepId, spec.save);
|
|
const watch = (request: Request): void => {
|
|
if (
|
|
namesResponse(spec, pattern, startOrigin, {
|
|
method: request.method(),
|
|
url: request.url(),
|
|
})
|
|
) {
|
|
if (started.size < 2) started.add(request);
|
|
protectResponse?.(request);
|
|
}
|
|
};
|
|
page.on("request", watch);
|
|
const waiting = page.waitForResponse(
|
|
(response) => started.has(response.request()),
|
|
timeout === undefined ? {} : { timeout },
|
|
);
|
|
// The step may fail before it waits; the rejection is reported by the wait, or not at all.
|
|
waiting.catch(() => undefined);
|
|
const saved = async (): Promise<void> => {
|
|
let response: Awaited<typeof waiting>;
|
|
try {
|
|
response = await beforeStepEnds(waiting, stepId, deadline, signal);
|
|
} catch (cause: unknown) {
|
|
if (cause instanceof ScenarioRequestError) throw cause;
|
|
throw new ScenarioRequestError(
|
|
`Step ${stepId}: no ${spec.method} ${spec.path} response could be read, so nothing was saved: ${cause instanceof Error ? cause.message : String(cause)}`,
|
|
{ cause },
|
|
);
|
|
}
|
|
const assertUnambiguous = (): void => {
|
|
if (started.size !== 1)
|
|
throw new ScenarioRequestError(
|
|
`Step ${stepId}: multiple matching requests make the response ambiguous, so nothing was saved. Narrow the response path or record without competing background requests.`,
|
|
);
|
|
};
|
|
assertUnambiguous();
|
|
if (response.status() < 200 || response.status() > 299)
|
|
throw new ScenarioRequestError(
|
|
`Step ${stepId}: the ${spec.method} ${spec.path} response answered ${String(response.status())}; values are saved only from a 2xx response.`,
|
|
);
|
|
const body = await beforeStepEnds(
|
|
readBoundedResponseBody(response, MAX_SAVED_RESPONSE_BYTES),
|
|
stepId,
|
|
deadline,
|
|
signal,
|
|
);
|
|
if (!body.ok)
|
|
throw new ScenarioRequestError(`Step ${stepId}: ${body.error.message}`);
|
|
assertUnambiguous();
|
|
assertResponseSaveActive(stepId, deadline, signal);
|
|
saveValues(stepId, body.value, spec.save, secrets);
|
|
secrets.markResponseSecretsReady(response.request());
|
|
};
|
|
return { saved, stop: () => page.off("request", watch) };
|
|
};
|
|
|
|
const requestEnvelopeError = (): ScenarioRequestError =>
|
|
new ScenarioRequestError(
|
|
"Expanded request envelope exceeds the current heap/string serialization allowance; reduce repeated values or raise the parent Node heap and restart.",
|
|
);
|
|
|
|
/** Count serialization expansion without allocating substituted strings or their serialized copies. */
|
|
const admitSavedJson = (
|
|
value: JsonValue,
|
|
secrets: BrowserScenarioSecrets,
|
|
): void => {
|
|
const limit = scenarioSerializationAllowance();
|
|
let bytes = 0;
|
|
const savedSizes = new Map<string, number>();
|
|
const charge = (size: number): void => {
|
|
bytes += size;
|
|
if (bytes > limit)
|
|
throw new ScenarioRequestError(
|
|
`Expanded request JSON exceeds its ${String(limit)}-byte serialization allowance, derived from current V8 heap headroom and the string limit. Reduce payload/repeated saved references, or raise the parent Node heap and restart.`,
|
|
);
|
|
};
|
|
const stringPart = (text: string): void =>
|
|
charge(jsonStringByteLength(text, limit - bytes + 2) - 2);
|
|
const visit = (item: JsonValue): void => {
|
|
if (typeof item === "string") {
|
|
const first = item.matchAll(SAVED_PLACEHOLDER).next().value;
|
|
if (first !== undefined && first[0] === item) {
|
|
const saved = secrets.savedValue(first[1]!);
|
|
if (typeof saved === "number") {
|
|
charge(jsonValueByteLength(saved));
|
|
return;
|
|
}
|
|
}
|
|
charge(2);
|
|
let offset = 0;
|
|
for (const match of item.matchAll(SAVED_PLACEHOLDER)) {
|
|
stringPart(item.slice(offset, match.index));
|
|
const name = match[1]!;
|
|
let size = savedSizes.get(name);
|
|
if (size === undefined) {
|
|
size =
|
|
jsonStringByteLength(
|
|
String(secrets.savedValue(name)),
|
|
limit - bytes + 2,
|
|
) - 2;
|
|
savedSizes.set(name, size);
|
|
}
|
|
charge(size);
|
|
offset = match.index + match[0].length;
|
|
}
|
|
stringPart(item.slice(offset));
|
|
} else if (Array.isArray(item)) {
|
|
charge(2 + Math.max(0, item.length - 1));
|
|
for (const child of item) visit(child);
|
|
} else if (item !== null && typeof item === "object") {
|
|
charge(2);
|
|
let count = 0;
|
|
for (const key in item) {
|
|
if (!Object.hasOwn(item, key)) continue;
|
|
charge(
|
|
(count++ === 0 ? 0 : 1) +
|
|
jsonStringByteLength(key, limit - bytes) +
|
|
1,
|
|
);
|
|
visit(item[key]!);
|
|
}
|
|
} else charge(jsonValueByteLength(item));
|
|
};
|
|
visit(value);
|
|
};
|
|
|
|
/**
|
|
* The step's JSON body with its `{saved:name}` placeholders filled: a string that is only a placeholder becomes the
|
|
* saved value, keeping its JSON type, and a placeholder inside a longer string is filled as text.
|
|
*/
|
|
const withSavedJson = (
|
|
value: unknown,
|
|
secrets: BrowserScenarioSecrets,
|
|
): unknown => {
|
|
if (typeof value === "string") {
|
|
const [whole] = [...value.matchAll(SAVED_PLACEHOLDER)];
|
|
if (whole !== undefined && whole[0] === value)
|
|
return secrets.savedValue(whole[1]!);
|
|
return value.replace(SAVED_PLACEHOLDER, (_placeholder, name: string) =>
|
|
String(secrets.savedValue(name)),
|
|
);
|
|
}
|
|
if (Array.isArray(value))
|
|
return value.map((item) => withSavedJson(item, secrets));
|
|
if (value !== null && typeof value === "object")
|
|
return Object.fromEntries(
|
|
Object.entries(value).map(([key, item]) => [
|
|
key,
|
|
withSavedJson(item, secrets),
|
|
]),
|
|
);
|
|
return value;
|
|
};
|
|
|
|
/** Save the values a step names from a JSON response, for later steps. */
|
|
const saveValues = (
|
|
stepId: string,
|
|
body: string | Uint8Array | undefined,
|
|
entries: readonly BrowserScenarioSaveEntry[],
|
|
secrets: BrowserScenarioSecrets,
|
|
): void => {
|
|
const selected = readResponseValues(body, entries, "fail");
|
|
if (!selected.ok)
|
|
throw new ScenarioRequestError(`Step ${stepId}: ${selected.error.message}`);
|
|
for (const {
|
|
entry: { name, secret },
|
|
value,
|
|
} of selected.value.values) {
|
|
try {
|
|
secrets.save(`${stepId}.${name}`, name, value, secret);
|
|
} catch (cause) {
|
|
throw new ScenarioRequestError(
|
|
`Step ${stepId}: ${cause instanceof Error ? cause.message : String(cause)}`,
|
|
);
|
|
}
|
|
}
|
|
};
|