refactor(browser): align inspector exclusions with canonical vocabulary (#834)

Report canonical BrowserExclusionReasons from runtime location
authorization (unsupported_url, not_approved) and collapse them
onto the fixed V8 wire bucket via inspectorExclusionKey, keeping
describeInspectorTargetLimitations text stable. Document the
provider authority split (attach-only CDP/V8 vs owned-runtime
Playwright) so the shared vocabulary is not re-split.
This commit is contained in:
morluto
2026-10-07 11:34:57 +08:00
committed by GitHub
parent ef535b81fe
commit de9593ad48
5 changed files with 76 additions and 10 deletions
+21 -6
View File
@@ -4,6 +4,7 @@ import {
browserOriginSchema,
sanitizeBrowserUrl,
} from "../domain/browserObservation.js";
import type { BrowserExclusionReason } from "../domain/browserCompleteness.js";
import type {
JavaScriptRuntimeLocation,
JavaScriptRuntimeTargetLocation,
@@ -14,9 +15,23 @@ export type RuntimeLocationDecision =
| { readonly allowed: true; readonly location: JavaScriptRuntimeLocation }
| {
readonly allowed: false;
readonly reason: "unsupported_location";
readonly reason: BrowserExclusionReason;
};
/**
* Wire bucket for inspector script exclusions. The V8 observation schemas
* fix the `unsupported_location` key, so every canonical denial reason maps
* onto it; the reason itself stays available on the decision for logs and
* limitations text.
*/
export const inspectorExclusionKey = (
reason: BrowserExclusionReason,
): "unsupported_location" => {
// Every canonical denial collapses onto the fixed V8 wire bucket.
void reason;
return "unsupported_location";
};
/** Resolve a protocol location exposed by the explicitly selected Inspector endpoint. */
export const authorizeRuntimeLocation = async (
value: string,
@@ -29,7 +44,7 @@ export const authorizeRuntimeLocation = async (
if (value.startsWith("file:")) {
const filePath = await authorizedElectronFile(value);
return filePath === undefined
? { allowed: false, reason: "unsupported_location" }
? { allowed: false, reason: "not_approved" }
: { allowed: true, location: { kind: "file", file_path: filePath } };
}
let url: URL;
@@ -38,13 +53,13 @@ export const authorizeRuntimeLocation = async (
} catch (cause: unknown) {
// Non-URL input is outside the authorized runtime scope.
void cause;
return { allowed: false, reason: "unsupported_location" };
return { allowed: false, reason: "unsupported_url" };
}
if (!["http:", "https:"].includes(url.protocol))
return { allowed: false, reason: "unsupported_location" };
return { allowed: false, reason: "unsupported_url" };
const parsedOrigin = browserOriginSchema.safeParse(url.origin);
if (!parsedOrigin.success)
return { allowed: false, reason: "unsupported_location" };
return { allowed: false, reason: "unsupported_url" };
return {
allowed: true,
location: {
@@ -64,7 +79,7 @@ export const authorizeRuntimeTargetLocation = async (
readonly allowed: true;
readonly location: JavaScriptRuntimeTargetLocation;
}
| { readonly allowed: false; readonly reason: "unsupported_location" }
| { readonly allowed: false; readonly reason: BrowserExclusionReason }
> => {
if (
context.type !== "node" ||