Files
reverse-engineering-anything/src/artifacts/ArtifactEmbeddedFormatProbes.ts
T
morluto 6fa58b0ec8 feat(artifacts): require every integrity reader failure to name its check (#11505)
ArtifactReaderFailure overloads require integrityCheck for a literal
"integrity" reason and an explicit (possibly undefined) check for a rebuild
whose reason is not a literal; primaryFacts always carries it. The .NET bundle
reader uses assertProducedEntry, and the PyInstaller cookie probe and owned
lease cleanup rewrap keep the check they previously dropped.
2026-11-16 08:10:08 +08:00

204 lines
6.7 KiB
TypeScript

import {
probeBunStandaloneGraph,
type BunStandaloneProbe,
} from "./bun/BunModuleGraphLayout.js";
import {
locateDenoStandalone,
type DenoStandaloneProbe,
} from "./deno/DenoStandaloneLocation.js";
import {
resolveArtifactReaderLimits,
type ArtifactReaderLimits,
} from "../domain/artifactReaderLimits.js";
import type {
StableRegularFileDescriptor,
RegularFileState,
} from "../filesystem/RegularFile.js";
import {
regularFileState,
sameRegularFileState,
} from "../filesystem/RegularFile.js";
import { findDotnetBundleHeader } from "./dotnet/DotnetBundle.js";
import { ArtifactReaderFailure, abortIfNeeded } from "../resources/index.js";
import { locateGodotPck, type GodotPckLocation } from "./GodotPckLocation.js";
import {
locateNodeSea,
type NodeSeaLocation,
} from "./nodeSea/NodeSeaLocation.js";
import {
observePyInstallerCookie,
type PyInstallerCookie,
type PyInstallerCookieObservation,
} from "./pyinstaller/CArchiveLayout.js";
import { pyInstallerReaderFailure } from "./pyinstaller/PyInstallerFailure.js";
/** Completed observations and explicit recognition limits; null alone is examined absence. */
export interface ArtifactEmbeddedFormatProbeFacts {
readonly sourceState: RegularFileState;
readonly readerLimits?: ArtifactReaderLimits;
readonly bunStandalone?: BunStandaloneProbe;
readonly denoStandalone?: DenoStandaloneProbe;
readonly godotPck?: GodotPckLocation | null;
readonly nodeSea?: NodeSeaLocation | null;
readonly nodeSeaRecognitionFailure?: ArtifactReaderFailure;
readonly dotnetBundleHeaderOffset?: number | null;
readonly pyInstaller?: PyInstallerCookieObservation;
}
/** Share format observations only across admissions of the same unchanged regular file. */
export class ArtifactEmbeddedFormatProbes {
#facts: ArtifactEmbeddedFormatProbeFacts;
constructor(
path: string,
private readonly source: StableRegularFileDescriptor,
private readonly signal?: AbortSignal,
previous?: ArtifactEmbeddedFormatProbeFacts,
private readonly limits: ArtifactReaderLimits = resolveArtifactReaderLimits(),
) {
abortIfNeeded(signal);
if (
previous !== undefined &&
!sameRegularFileState(previous.sourceState, source.initial)
)
throw new ArtifactReaderFailure(
"integrity",
`Root artifact changed before inventory: ${path}`,
{ integrityCheck: "container-identity" },
);
const reusable =
previous !== undefined &&
JSON.stringify(previous.readerLimits) === JSON.stringify(limits);
if (previous !== undefined && !reusable) {
const {
bunStandalone: _bun,
nodeSea: _sea,
nodeSeaRecognitionFailure: _seaLimit,
...facts
} = previous;
this.#facts = { ...facts, readerLimits: limits };
} else
this.#facts = previous ?? {
sourceState: regularFileState(source.initial),
readerLimits: limits,
};
}
async godotPck(prefix?: Uint8Array): Promise<GodotPckLocation | undefined> {
abortIfNeeded(this.signal);
if (this.#facts.godotPck !== undefined)
return this.#facts.godotPck ?? undefined;
const location = await locateGodotPck(
this.source.handle,
this.source.initial.size,
this.signal,
prefix,
);
this.#facts = { ...this.#facts, godotPck: location ?? null };
return location;
}
async nodeSea(): Promise<NodeSeaLocation | undefined> {
abortIfNeeded(this.signal);
if (this.#facts.nodeSea !== undefined)
return this.#facts.nodeSea ?? undefined;
if (this.#facts.nodeSeaRecognitionFailure !== undefined) return undefined;
try {
const location = await locateNodeSea(
this.source.handle,
this.source.initial.size,
this.signal,
this.limits.node_sea,
);
this.#facts = { ...this.#facts, nodeSea: location ?? null };
return location;
} catch (cause) {
if (
cause instanceof ArtifactReaderFailure &&
(cause.readerLimit?.parameter ===
"artifact_limits.node_sea.recognition_header_count" ||
cause.readerLimit?.parameter ===
"artifact_limits.node_sea.recognition_load_command_bytes")
) {
this.#facts = { ...this.#facts, nodeSeaRecognitionFailure: cause };
return undefined;
}
throw cause;
}
}
async pyInstaller(): Promise<PyInstallerCookie | undefined> {
abortIfNeeded(this.signal);
if (this.#facts.pyInstaller !== undefined)
return this.#facts.pyInstaller.state === "located"
? this.#facts.pyInstaller.cookie
: undefined;
const found = await observePyInstallerCookie(
this.source.handle,
this.source.initial.size,
this.signal,
);
abortIfNeeded(this.signal);
if (!found.ok) throw pyInstallerReaderFailure(found.error);
this.#facts = { ...this.#facts, pyInstaller: found.value };
return found.value.state === "located" ? found.value.cookie : undefined;
}
async dotnetBundle(): Promise<number | undefined> {
abortIfNeeded(this.signal);
if (this.#facts.dotnetBundleHeaderOffset !== undefined)
return this.#facts.dotnetBundleHeaderOffset ?? undefined;
// An apphost inside a recognized CArchive cannot claim its outer carrier.
const packaged = await this.pyInstaller();
const header = await findDotnetBundleHeader(
this.source.handle,
this.source.initial.size,
this.signal,
packaged?.archiveStart ?? this.source.initial.size,
);
abortIfNeeded(this.signal);
this.#facts = { ...this.#facts, dotnetBundleHeaderOffset: header ?? null };
return header;
}
async bunStandalone(): Promise<BunStandaloneProbe> {
abortIfNeeded(this.signal);
if (this.#facts.bunStandalone !== undefined)
return this.#facts.bunStandalone;
const observed = await probeBunStandaloneGraph(
this.source.handle,
this.source.initial.size,
this.signal,
this.limits.bun,
);
abortIfNeeded(this.signal);
this.#facts = { ...this.#facts, bunStandalone: observed };
return observed;
}
async denoStandalone(): Promise<DenoStandaloneProbe> {
abortIfNeeded(this.signal);
if (this.#facts.denoStandalone !== undefined)
return this.#facts.denoStandalone;
const packaged = await this.pyInstaller();
const observed = await locateDenoStandalone(
this.source.handle,
this.source.initial.size,
this.signal,
packaged === undefined
? undefined
: {
start: packaged.archiveStart,
end: packaged.archiveStart + packaged.packageLength,
},
);
abortIfNeeded(this.signal);
this.#facts = { ...this.#facts, denoStandalone: observed };
return observed;
}
completedFacts(): ArtifactEmbeddedFormatProbeFacts {
return this.#facts;
}
}