Files
reverse-engineering-anything/src/process/RegularFileRead.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

387 lines
14 KiB
TypeScript

import { decodeStrictUtf8 } from "../domain/strictUtf8.js";
import type { Stats } from "node:fs";
import type { FileHandle } from "node:fs/promises";
import {
assertStableRegularFileIdentity,
RegularFileChangedError,
RegularFileOperationCancelled,
assertRegularFileActive,
} from "../filesystem/RegularFile.js";
import {
RegularFileCleanupFailure,
RegularFileCancelled,
regularFileCancellation,
withOwnedRegularFile,
OwnedRegularFileOperationFailure,
type RegularFileOperationOutcome,
} from "../filesystem/OwnedRegularFile.js";
import { readBoundedFileBytes } from "./BoundedFileBytes.js";
import {
AnalysisCleanupLeaseGroup,
AnalysisCleanupLease,
type ArtifactResourceOwner,
type ArtifactResourceScope,
ArtifactReaderFailure,
} from "../resources/index.js";
import type {
AnalysisCleanupObservation,
AnalysisError,
} from "../domain/analysisErrorBase.js";
import { errorMessage } from "../kernel/errorMessage.js";
/** A scope handoff preserves the same descriptor outcome and exact retry capability. */
export class RetainedRegularFileCleanupFailure<
Value = unknown,
> extends RegularFileCleanupFailure<Value> {
readonly cleanupOwner: Extract<
ArtifactResourceOwner,
{ readonly kind: "lease" }
>;
readonly cleanupLease: AnalysisCleanupLease;
constructor(failure: RegularFileCleanupFailure<Value>) {
super(failure);
this.cleanupLease =
failure instanceof RetainedRegularFileCleanupFailure
? failure.cleanupLease
: new AnalysisCleanupLease(() => failure.owner.close(), [failure.path]);
this.cleanupOwner =
failure instanceof RetainedRegularFileCleanupFailure
? failure.cleanupOwner
: { kind: "lease", resource: failure.path, lease: this.cleanupLease };
}
}
/** Bind only explicit cleanup capabilities, never resource labels or opaque causes. */
export const regularFileCleanupLeases = (
cause: unknown,
): readonly AnalysisCleanupLease[] | undefined =>
cause instanceof RetainedRegularFileCleanupFailure
? [cause.cleanupLease]
: cause instanceof ArtifactReaderFailure
? cause.cleanupLeases
: undefined;
export const bindRegularFileCleanup = (
cause: unknown,
error: AnalysisError,
): void => {
const leases = regularFileCleanupLeases(cause);
if (leases !== undefined) new AnalysisCleanupLeaseGroup(error, leases);
};
/** Filesystem admission policy for one selected regular input. */
export interface RegularFileReadOptions {
readonly signal?: AbortSignal | undefined;
readonly symlinks?: "follow" | "reject";
readonly resources?: ArtifactResourceScope;
/** Runs on the opened file's own state before any byte is read; throw to refuse the read. */
readonly admit?: (state: Stats) => void;
/** Tags cancellation at the bounded reader's cooperative checkpoints. */
readonly cancellationFailure?: (reason: unknown) => Error;
}
/** Preserves a physical descriptor-read cause until its owner has finalized. */
export class RegularFileReadFailure extends OwnedRegularFileOperationFailure {
override readonly _tag = "RegularFileReadFailure";
constructor(operationCause: unknown) {
super(operationCause);
this.name = this._tag;
}
}
export class InvalidUtf8FileError extends TypeError {
readonly _tag = "InvalidUtf8FileError";
constructor(
readonly path: string,
cause: unknown,
) {
super(`File is not valid UTF-8: ${path}`, { cause });
this.name = this._tag;
}
}
/** Retry a failed close through its retained owner and report any remaining cleanup. */
export const retryRegularFileCleanup = async <Value>(
failure: RegularFileCleanupFailure<Value>,
resources: ArtifactResourceScope,
signal?: AbortSignal,
): Promise<{
readonly outcome: RegularFileOperationOutcome<Value>;
readonly cleanupLease?: AnalysisCleanupLease;
readonly cleanup?: AnalysisCleanupObservation;
readonly failure?: RetainedRegularFileCleanupFailure<Value>;
}> => {
const outcome: RegularFileOperationOutcome<Value> =
failure.outcome.kind === "failed" &&
failure.operationFailure === undefined &&
failure.outcome.cause instanceof RegularFileOperationCancelled &&
!(signal?.aborted === true && failure.outcome.cause === signal.reason)
? { kind: "failed", cause: failure.outcome.cause.reason }
: failure.outcome;
const retained =
failure instanceof RetainedRegularFileCleanupFailure
? failure
: new RetainedRegularFileCleanupFailure(failure);
const released = await resources.release(retained.cleanupOwner);
if (released.kind === "released") return { outcome };
return {
outcome,
cleanupLease: released.lease,
failure: retained,
cleanup: {
reason: `${errorMessage(failure.cleanupCause)}; retry: ${errorMessage(released.cause)}`,
resources: [failure.path],
},
};
};
/** Retry every explicit nested operation owner; close rejection values grant no authority. */
export const retryRegularFileCleanupFailures = async (
failure: RegularFileCleanupFailure,
resources: ArtifactResourceScope,
): Promise<{
readonly primary: unknown;
readonly failures: readonly RegularFileCleanupFailure[];
readonly cleanupLeases: readonly AnalysisCleanupLease[];
readonly cleanup?: AnalysisCleanupObservation;
}> => {
const failures: RegularFileCleanupFailure[] = [];
const cleanupLeases = new Set<AnalysisCleanupLease>();
const observations: AnalysisCleanupObservation[] = [];
let current = failure;
let primary: unknown;
for (;;) {
const retried = await retryRegularFileCleanup(current, resources);
if (retried.cleanupLease !== undefined)
cleanupLeases.add(retried.cleanupLease);
failures.push(retried.failure ?? current);
if (retried.cleanup !== undefined) observations.push(retried.cleanup);
primary =
retried.outcome.kind === "failed"
? retried.outcome.cause
: current.cleanupCause;
const nested =
current.operationFailure === undefined &&
current.outcome.kind === "failed"
? current.outcome.cause
: undefined;
if (!(nested instanceof RegularFileCleanupFailure)) break;
current = nested;
}
return {
primary,
failures,
cleanupLeases: [...cleanupLeases],
...(observations.length === 0
? {}
: {
cleanup: {
reason: observations.map(({ reason }) => reason).join("; "),
resources: observations.flatMap(({ resources }) => resources),
},
}),
};
};
/** Completed stable read facts survive cancellation during descriptor finalization. */
export interface RegularFileCompletion<Value> {
readonly value: Value;
readonly cancellation?: { readonly reason: unknown } | undefined;
}
/** Admit one regular-file handle, retaining completion through close and cleanup retry. */
export const withRegularFileCompletion = async <Value>(
path: string,
read: (handle: FileHandle, stats: Stats) => Promise<Value>,
options: RegularFileReadOptions = {},
): Promise<RegularFileCompletion<Value>> => {
const { signal, resources } = options;
let admitted: FileHandle | undefined;
const operation = async (): Promise<RegularFileCompletion<Value>> => {
try {
const value = await withOwnedRegularFile(
path,
{
...(signal === undefined ? {} : { signal }),
symlinks: options.symlinks ?? "follow",
},
async ({ handle, initial: stats }) => {
admitted = handle;
assertRegularFileActive(signal);
const value = await read(handle, stats);
assertRegularFileActive(signal);
await assertStableRegularFileIdentity(handle, path, stats, {
symlinks: options.symlinks ?? "follow",
...(signal === undefined ? {} : { signal }),
});
assertRegularFileActive(signal);
return value;
},
);
return { value };
} catch (cause: unknown) {
// Caller reasons are opaque, including objects shaped like file failures.
// They do not transfer ownership of any descriptor to this operation.
if (signal?.aborted === true && cause === signal.reason) throw cause;
if (cause instanceof RegularFileReadFailure) throw cause;
if (
cause instanceof RegularFileCancelled &&
cause.owner.handle !== admitted
)
throw cause;
if (cause instanceof RegularFileCleanupFailure) {
if (resources === undefined)
throw new RetainedRegularFileCleanupFailure(cause);
const retry = await retryRegularFileCleanup(cause, resources, signal);
if (retry.failure !== undefined) throw retry.failure;
if (retry.outcome.kind === "failed") {
if (
cause.operationFailure === undefined &&
signal?.aborted === true &&
retry.outcome.cause === signal.reason
)
throw signal.reason;
const cancellation =
cause.operationFailure === undefined
? (regularFileCancellation(retry.outcome.cause) ??
regularFileCancellation(cause))
: undefined;
if (cancellation !== undefined) {
if (options.cancellationFailure !== undefined)
throw options.cancellationFailure(cancellation.reason);
throw cancellation.reason;
}
if (
cause.operationFailure !== undefined &&
options.cancellationFailure !== undefined
)
throw cause.operationFailure;
throw retry.outcome.cause;
}
return {
value: retry.outcome.value as Value,
cancellation: regularFileCancellation(cause),
};
}
if (cause instanceof RegularFileCancelled)
return {
value: cause.outcome.value as Value,
cancellation: { reason: cause.reason },
};
const cancellation = regularFileCancellation(cause);
if (cancellation !== undefined) {
if (options.cancellationFailure !== undefined)
throw options.cancellationFailure(cancellation.reason);
throw cancellation.reason;
}
if (options.cancellationFailure !== undefined)
throw new RegularFileReadFailure(cause);
throw cause;
}
};
const completion = await (resources === undefined
? operation()
: resources.run(operation));
// Include successful cleanup retries and scope finalization in cancellation.
return completion.cancellation !== undefined || signal?.aborted !== true
? completion
: { ...completion, cancellation: { reason: signal.reason } };
};
/** Read consumers without completion facts retain their existing cancellation contract. */
export const withRegularFile = async <Value>(
path: string,
read: (handle: FileHandle, stats: Stats) => Promise<Value>,
options: RegularFileReadOptions = {},
): Promise<Value> => {
const completion = await withRegularFileCompletion(path, read, options);
const cancellation =
completion.cancellation ??
(options.signal?.aborted === true
? { reason: options.signal.reason }
: undefined);
if (cancellation !== undefined) {
const { reason } = cancellation;
if (options.cancellationFailure !== undefined)
throw options.cancellationFailure(reason);
throw reason;
}
return completion.value;
};
/** Admit a regular file without waiting for a pipe, then read its verified handle. */
export const readRegularFile = (
path: string,
options: RegularFileReadOptions = {},
): Promise<Buffer> => readRegularFileContent(path, (bytes) => bytes, options);
/** Read valid UTF-8 without replacing source bytes or stripping an initial BOM. */
export const readRegularFileText = (
path: string,
options: RegularFileReadOptions = {},
): Promise<string> =>
readRegularFileContent(path, (bytes) => decodeFileText(path, bytes), options);
/** Retain the read owner's verified file state together with its decoded text. */
export const readRegularFileTextSnapshot = (
path: string,
options: RegularFileReadOptions = {},
): Promise<{ readonly text: string; readonly state: Stats }> =>
readRegularFileContent(
path,
(bytes, state) => ({
text: decodeFileText(path, bytes),
state,
}),
options,
);
const decodeFileText = (path: string, bytes: Buffer): string => {
try {
return decodeStrictUtf8(bytes, "preserve");
} catch (cause: unknown) {
if (!(cause instanceof TypeError)) throw cause;
throw new InvalidUtf8FileError(path, cause);
}
};
const readRegularFileContent = <Value>(
path: string,
decode: (bytes: Buffer, state: Stats) => Value,
options: RegularFileReadOptions,
): Promise<Value> => {
const operation = withRegularFile(
path,
async (handle, stats) => {
try {
options.admit?.(stats);
const bytes = await readBoundedFileBytes(handle, stats.size, {
...(options.signal === undefined ? {} : { signal: options.signal }),
cancellationFailure: (reason) =>
new RegularFileOperationCancelled(reason),
operationFailure: (cause) => new RegularFileReadFailure(cause),
});
if (bytes === undefined || bytes.length !== stats.size)
throw new RegularFileChangedError(path);
return decode(bytes, stats);
} catch (cause: unknown) {
if (
options.cancellationFailure !== undefined &&
!(cause instanceof RegularFileOperationCancelled) &&
!(cause instanceof RegularFileReadFailure)
)
throw new RegularFileReadFailure(cause);
throw cause;
}
},
options,
);
if (options.cancellationFailure !== undefined) return operation;
return operation.catch((cause: unknown) => {
if (cause instanceof RegularFileReadFailure) throw cause.operationCause;
throw cause;
});
};