Files
reverse-engineering-anything/src/application/desktop/DesktopRetainedContent.ts
T
morluto b51ed4c3ec refactor(kernel): migrate the remaining SHA-256 hex digests to sha256Hex and move isRecord into src/kernel (#11571)
* refactor(kernel): migrate the remaining one-shot SHA-256 hex digests to sha256Hex

* refactor(kernel): move isRecord into src/kernel and replace its inline copies (#11574)

* fix(scripts): import isRecord from src/kernel in the managed manifest parser
2026-11-15 20:53:36 -05:00

166 lines
5.3 KiB
TypeScript

import { DESKTOP_VIEW_DEFAULTS } from "../../domain/desktop/desktopViewPolicy.js";
import { join } from "node:path";
import {
ArtifactReaderFailure,
bindArtifactFileCleanup,
ArtifactResourceScope,
type ArtifactCleanupAttempt,
} from "../../resources/index.js";
import { err, ok, type Result } from "../../domain/result.js";
import { analysisErrorWithCleanupDependencies } from "../../domain/analysisErrorCleanup.js";
import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
import type { OwnedFileHandle } from "../../filesystem/OwnedFileHandle.js";
import {
RegularFileCleanupFailure,
regularFileCancellation,
withOwnedRegularFile,
} from "../../filesystem/OwnedRegularFile.js";
import {
RegularFileCapacityError,
readStableFileBytes,
} from "../../filesystem/readStableFileBytes.js";
import { sha256Hex } from "../../kernel/sha256Hex.js";
const MIB = 1024 * 1024;
/** Largest retained file the state view reads. */
const DEFAULT_MAX_BYTES = DESKTOP_VIEW_DEFAULTS.file_bytes;
type FailedRelease = Extract<
ArtifactCleanupAttempt,
{ readonly kind: "failed" }
>;
/**
* Reads retained content without following links and checks each digest.
* A handle whose close failed is kept, with its path, for `release`.
*/
export class RetainedContent {
readonly #unclosed: {
readonly path: string;
readonly owner: OwnedFileHandle;
}[] = [];
constructor(
readonly folder: string,
readonly maxBytes: number = DEFAULT_MAX_BYTES,
) {}
/**
* The bytes stored under a digest, or why they cannot be used, worded to
* follow the name of what was read.
*/
async read(
sha256: string,
signal?: AbortSignal,
): Promise<Result<Buffer, string>> {
const path = join(this.folder, "content", sha256);
const options = {
symlinks: "reject" as const,
retainFailedClose: (owner: OwnedFileHandle) => {
this.#unclosed.push({ path, owner });
},
...(signal === undefined ? {} : { signal }),
};
let bytes: Buffer;
try {
bytes = await withOwnedRegularFile(path, options, ({ handle }) =>
readStableFileBytes(handle, path, this.maxBytes, options),
);
} catch (cause: unknown) {
const cancellation = regularFileCancellation(cause);
if (cancellation !== undefined)
throw new ArtifactReaderFailure(
"cancelled",
"Retained content read cancelled",
{
cause: cancellation.reason,
cancellation,
},
);
const outcome =
cause instanceof RegularFileCleanupFailure ? cause.outcome : undefined;
// A read that finished keeps its bytes; its failed close is retried by `release`.
if (outcome?.kind === "completed" && Buffer.isBuffer(outcome.value))
bytes = outcome.value;
else if (
(outcome?.kind === "failed" ? outcome.cause : cause) instanceof
RegularFileCapacityError
)
return err(
`is larger than the ${String(this.maxBytes / MIB)} MiB read limit`,
);
else if (cause instanceof Error) return err("is missing or unreadable");
else throw cause;
}
return sha256Hex(bytes) === sha256
? ok(bytes)
: err("does not match its digest");
}
/** Close every kept handle; each close that fails again keeps its owner. */
async release(resources: ArtifactResourceScope): Promise<FailedRelease[]> {
const failures: FailedRelease[] = [];
for (const { path, owner } of this.#unclosed.splice(0)) {
const attempt = await resources.release({
kind: "file-handle",
resource: path,
handle: owner,
});
if (attempt.kind === "failed") failures.push(attempt);
}
return failures;
}
}
/**
* Run with a retained content reader whose handles are released on every
* exit. A release that fails is reported with the run's own outcome and the
* exact handle owners.
*/
export const withRetainedContent = async <Value>(
folder: string,
run: (content: RetainedContent) => Promise<Value>,
maxBytes?: number,
): Promise<Value> => {
const content = new RetainedContent(folder, maxBytes);
let outcome:
| { readonly kind: "completed"; readonly value: Value }
| { readonly kind: "failed"; readonly cause: unknown };
try {
outcome = { kind: "completed", value: await run(content) };
} catch (cause: unknown) {
outcome = { kind: "failed", cause };
}
const resources = new ArtifactResourceScope();
const [first, ...rest] = await content.release(resources);
if (first !== undefined) {
const failures = [first, ...rest] as const;
if (
outcome.kind === "failed" &&
outcome.cause instanceof ProviderCleanupError
) {
const fileFailure = resources.cleanupFailure(
{ kind: "completed" },
failures,
);
const fileCleanup = new ProviderCleanupError(
"rea-desktop",
fileFailure.cleanup?.resources ?? [],
{ reason: fileFailure.cleanup?.reason ?? fileFailure.message },
{ operation: outcome.cause.operation, cause: fileFailure },
);
bindArtifactFileCleanup(fileFailure, fileCleanup);
throw analysisErrorWithCleanupDependencies(
outcome.cause,
fileCleanup,
outcome.cause.operation,
);
}
throw resources.cleanupFailure(outcome, failures);
}
if (outcome.kind === "failed") throw outcome.cause;
return outcome.value;
};