Files
reverse-engineering-anything/src/application/environment/environmentBundleWrite.ts
T
morluto 5f718ce30e refactor(kernel): give error-message, byte-hex and SHA-256 hex helpers one owner in a new src/kernel layer (#11542)
* refactor(kernel): give error-to-message text one owner in a new src/kernel layer

* fix(kernel): keep the regex worker's own error text inside its isolated source

* refactor(kernel): exclude copies that run in another realm from the error-message guard by name

The regex worker's source string and the page.evaluate fetch in PlaywrightScenarioRequest cannot import errorMessage. The guard now names them, so the counted baseline does not invite a later slice to rewrite them.

* refactor(kernel): migrate the long tail of inline error-message copies to errorMessage (#11552)

Every provider and adapter folder with six or fewer copies now calls errorMessage from src/kernel. Local helpers whose whole body was the copy (failureMessage, gdbErrorMessage, message, describe, reasonOf, recoveryFailureMessage and four local errorMessage definitions) are removed and their call sites call the owner.

Refs #11548

* refactor(kernel): give byte-to-hex formatting one owner in src/kernel (#11560)

byteToHex returns the two lowercase hexadecimal digits of one byte. All eight inline copies (native, contracts, domain firmware and desktop, pcap) call it, keeping their own 0x, % or \x notation, and a counted guard with an empty baseline keeps new copies out.

Refs #11548

* refactor(kernel): give one-shot SHA-256 hex digests one owner in src/kernel (#11562)

sha256Hex digests one in-memory value. A counted guard records the one-shot createHash("sha256").update(x).digest("hex") chains (115 in 101 files) and the first slice migrates domain, contracts and process (35 copies), removing local wrappers (sha256, sha256Text, hash) and the exported sha256Text. Incremental and streamed hashing is not counted.

Refs #11548

* refactor(kernel): migrate the application layer's inline error-message copies to errorMessage (#11563)

All 69 copies in src/application call errorMessage from src/kernel. Local helpers whose whole body was the copy (errorDetail, causeReason and five local errorMessage definitions) are removed and their call sites call the owner.

Refs #11548

* refactor(kernel): migrate the native provider's inline error-message copies to errorMessage (#11567)

All 49 copies in src/native call errorMessage from src/kernel. The local errorReason helpers in LldbCallTracer and LldbRetainedObservations, whose whole body was the copy, are removed and their call sites call the owner.

Refs #11548

* refactor(kernel): migrate the remaining inline error-message copies to errorMessage (#11569)
2026-11-16 07:05:30 +08:00

357 lines
11 KiB
TypeScript

import { HOST_PLATFORM } from "../../platform/HostPlatform.js";
import { createHash } from "node:crypto";
import type { FileHandle } from "node:fs/promises";
import { join } from "node:path";
import { Readable } from "node:stream";
import {
AnalysisInputError,
AnalysisAccessDeniedError,
AnalysisArtifactChangedError,
} from "../../domain/analysisErrorCore.js";
import { AnalysisError } from "../../domain/analysisErrorBase.js";
import type { EnvironmentBundlePublication } from "../../domain/environmentBundleExport.js";
import {
AnalysisCleanupLease,
ArtifactFileCleanupFailure,
ArtifactReaderFailure,
ArtifactResourceScope,
streamChunkToBuffer,
SafeOutputTree,
outputDirectoryAdmissionRefusal,
SafeOutputTreeCreationFailure,
} from "../../resources/index.js";
import { RegularFileCleanupFailure } from "../../filesystem/OwnedRegularFile.js";
import { readFileHandleChunks } from "../../filesystem/readFileHandleChunks.js";
import { RegularFileChangedError } from "../../filesystem/RegularFile.js";
import { withRegularFile } from "../../process/RegularFileRead.js";
import {
ENVIRONMENT_EXPORT_OPERATION,
type EnvironmentBundlePlan,
} from "./environmentBundle.js";
import type {
EnvironmentExportInput,
WrittenBundleFile,
} from "./environmentExport.js";
import { errorMessage } from "../../kernel/errorMessage.js";
/**
* A host failure on one file the bundle writer was reading or writing.
* Descriptor operations such as `read`, `write` and `fsync` fail without a
* path, so this names the file and the direction of the failed operation.
*/
export class BundleFileHostFailure extends Error {
constructor(
readonly path: string,
readonly operation: "reading" | "writing",
cause: Error,
) {
super(`${cause.message}, ${operation} ${path}`, { cause });
}
}
/** An untyped host system failure, which carries an errno-style code. */
const isHostSystemFailure = (cause: unknown): cause is Error =>
cause instanceof Error &&
!(cause instanceof ArtifactReaderFailure) &&
typeof Reflect.get(cause, "code") === "string";
/** Attribute a pathless host failure to the bundle file being written. */
const writingBundleFile = async <Result>(
directory: string,
relative: string,
write: () => Promise<Result>,
): Promise<Result> => {
try {
return await write();
} catch (cause: unknown) {
if (isHostSystemFailure(cause) && Reflect.get(cause, "path") === undefined)
throw new BundleFileHostFailure(
join(directory, relative),
"writing",
cause,
);
throw cause;
}
};
/** Read the admitted tarball, attributing host failures to the source. */
async function* tarballChunks(source: BundleTarball): AsyncIterable<unknown> {
try {
yield* readFileHandleChunks(source.handle);
} catch (cause: unknown) {
if (isHostSystemFailure(cause))
throw new BundleFileHostFailure(source.path, "reading", cause);
throw cause;
}
}
const writeBytes = async (
tree: SafeOutputTree,
directory: string,
relative: string,
bytes: Buffer,
): Promise<WrittenBundleFile> => {
const written = await writingBundleFile(directory, relative, () =>
tree.write(relative, Readable.from([bytes]), {
bytes: bytes.length,
sha256: createHash("sha256").update(bytes).digest("hex"),
}),
);
return { path: written.relativePath, bytes: written.bytesWritten };
};
/** The package tarball instance admitted once and retained until its owner closes it. */
export interface BundleTarball {
readonly path: string;
readonly handle: FileHandle;
readonly size: number;
}
/** Report a changed selected tarball with any already-published bundle. */
export const changedArtifact = (
cause: RegularFileChangedError,
publication?: EnvironmentBundlePublication,
): AnalysisArtifactChangedError =>
new AnalysisArtifactChangedError(
ENVIRONMENT_EXPORT_OPERATION,
cause.path,
cause.message,
{
cause,
...(publication === undefined ? {} : { partialObservation: publication }),
},
);
/** Read and hash the admitted instance, checking its complete length without retaining its contents. */
export const bundleTarballDigest = async (
source: BundleTarball,
): Promise<string> => {
const hash = createHash("sha256");
let observed = 0;
for await (const chunk of tarballChunks(source)) {
const bytes = streamChunkToBuffer(chunk);
observed += bytes.length;
if (observed > source.size) throw new RegularFileChangedError(source.path);
hash.update(bytes);
}
if (observed !== source.size) throw new RegularFileChangedError(source.path);
return hash.digest("hex");
};
/** Hash and copy only the instance retained before destination admission. */
const writeTarball = async (
tree: SafeOutputTree,
directory: string,
relative: string,
source: BundleTarball,
): Promise<WrittenBundleFile> => {
const sha256 = await bundleTarballDigest(source);
const written = await writingBundleFile(directory, relative, () =>
tree.write(relative, Readable.from(tarballChunks(source)), {
bytes: source.size,
sha256,
}),
);
return { path: written.relativePath, bytes: written.bytesWritten };
};
/** The output owner anchors every create and verifies the complete tree before publication. */
const writeBundleFiles = async (
input: EnvironmentExportInput,
plan: EnvironmentBundlePlan,
tarball?: BundleTarball,
): Promise<readonly WrittenBundleFile[]> => {
const resources = new ArtifactResourceScope();
let tree: SafeOutputTree | undefined;
let written: WrittenBundleFile[] | undefined;
let outcome:
| {
readonly kind: "completed";
readonly files: readonly WrittenBundleFile[];
}
| { readonly kind: "failed"; readonly cause: unknown };
try {
try {
tree = await SafeOutputTree.create(
input.directory,
HOST_PLATFORM.platform,
{
acceptExistingEmpty: input.exclusiveDestination !== true,
createParents: input.exclusiveDestination !== true,
},
);
} catch (cause: unknown) {
if (cause instanceof SafeOutputTreeCreationFailure) tree = cause.tree;
throw cause;
}
written = [];
for (const file of plan.files)
written.push(
await writeBytes(
tree,
input.directory,
file.path,
Buffer.from(file.content),
),
);
written.push(
await writeBytes(
tree,
input.directory,
plan.copies.manifest,
input.manifest.bytes,
),
);
written.push(
await writeBytes(
tree,
input.directory,
plan.copies.evidence,
input.evidence.bytes,
),
);
if (plan.copies.tarball !== null && tarball !== undefined)
written.push(
await writeTarball(tree, input.directory, plan.copies.tarball, tarball),
);
await tree.commit();
outcome = { kind: "completed", files: written };
} catch (cause: unknown) {
outcome = { kind: "failed", cause };
}
const owner = tree;
if (owner !== undefined) {
const closed = await resources.release({
kind: "lease",
resource: input.directory,
lease: { release: () => owner.closeHandles() },
});
if (closed.kind === "failed")
throw resources.cleanupFailure(
outcome,
[closed],
owner.published && written !== undefined
? {
kind: "environment-bundle-publication",
directory: input.directory,
files: written,
}
: undefined,
);
}
if (outcome.kind === "failed") {
if (owner?.published === true && written !== undefined) return written;
// Only a destination refusal can blame the selected directory.
throw outputDirectoryAdmissionRefusal(
ENVIRONMENT_EXPORT_OPERATION,
"directory",
outcome.cause,
);
}
return outcome.files;
};
/** A package tarball path that names no readable regular file. */
export const packageTarballRefusal = (
path: string,
cause: unknown,
): AnalysisInputError =>
new AnalysisInputError(
ENVIRONMENT_EXPORT_OPERATION,
{
cause,
userMessage: `${path} must name a readable regular package tarball.`,
},
[
{
path: ["package_tarball"],
reason: "invalid_value",
message: "The package tarball must be an existing regular file.",
},
],
);
/** Admit the package tarball once and retain it through `use`; a close it cannot confirm stays bound to its owner. */
export const withBundleTarball = async <Value>(
path: string,
use: (tarball: BundleTarball) => Promise<Value>,
): Promise<Value> => {
const resources = new ArtifactResourceScope();
let admitted = false;
try {
return await withRegularFile(
path,
async (handle, state) => {
admitted = true;
return use({ path, handle, size: state.size });
},
{ resources },
);
} catch (cause: unknown) {
if (cause instanceof RegularFileCleanupFailure)
throw new ArtifactFileCleanupFailure(
cause,
AnalysisCleanupLease.forCloseOwner(cause.owner, path),
);
if (!admitted && cause instanceof Error && "code" in cause) {
if (cause.code === "EACCES" || cause.code === "EPERM")
throw new AnalysisAccessDeniedError(
ENVIRONMENT_EXPORT_OPERATION,
path,
cause.code,
{ cause },
);
if (
["ENOENT", "ENOTDIR", "ENAMETOOLONG", "EISDIR", "ENOTFILE"].includes(
String(cause.code),
)
)
throw packageTarballRefusal(path, cause);
}
throw cause;
}
};
/** Retain one tarball instance across planning output writes and final stability verification. */
export const writeEnvironmentBundle = async (
input: EnvironmentExportInput,
plan: EnvironmentBundlePlan,
): Promise<readonly WrittenBundleFile[]> => {
if (plan.packageSource.kind !== "tarball")
return writeBundleFiles(input, plan);
let published: readonly WrittenBundleFile[] | undefined;
try {
return await withBundleTarball(plan.packageSource.path, async (tarball) => {
published = await writeBundleFiles(input, plan, tarball);
return published;
});
} catch (cause: unknown) {
if (published !== undefined) {
const publication: EnvironmentBundlePublication = {
kind: "environment-bundle-publication",
directory: input.directory,
files: published,
};
if (cause instanceof ArtifactReaderFailure)
cause.retainPartialObservation(publication);
if (cause instanceof RegularFileChangedError)
throw changedArtifact(cause, publication);
if (cause instanceof AnalysisError) {
cause.retainPartialObservation(publication);
throw cause;
}
if (!(cause instanceof ArtifactReaderFailure)) {
const primary = isHostSystemFailure(cause)
? new BundleFileHostFailure(plan.packageSource.path, "reading", cause)
: cause;
throw new ArtifactReaderFailure("io", errorMessage(primary), {
cause: primary,
partialObservation: publication,
});
}
}
throw cause;
}
};