Files
reverse-engineering-anything/src/artifacts/PositionalArtifactReader.ts
T
morluto b5a9d48734 fix(artifacts): preserve member stream failures through reader close (#12489)
* fix(artifacts): preserve positional read failures during close

* fix(artifacts): share member-stream shutdown with uImage

* fix(artifacts): retain standalone read failures during close
2026-11-19 19:28:27 +00:00

244 lines
7.7 KiB
TypeScript

import { ArtifactPreparation } from "./ArtifactPreparation.js";
import { Readable, Transform } from "node:stream";
import { setImmediate } from "node:timers/promises";
import {
ArtifactReaderFailure,
copyArtifactEntry,
assertProducedEntry,
type ArtifactEntry,
type ArtifactReader,
type ArtifactReaderTraversal,
type ArtifactTraversalOptions,
ArtifactResourceScope,
assertArtifactReadActive,
ArtifactFileSource,
} from "../resources/index.js";
import {
ArtifactStreamLifecycle,
ownArtifactStream,
type ArtifactMemberLifecycle,
} from "./OwnedArtifactStream.js";
import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js";
import type { StableRegularFileDescriptor } from "../filesystem/RegularFile.js";
import type { ArtifactFormatMetadata } from "../domain/artifactFormatMetadata.js";
import { invariantViolation } from "../domain/internalInvariant.js";
/** An entry whose bytes are one range of the carrier. */
export type PositionalArtifactEntry = ArtifactEntry & {
readonly byteOffset: number;
readonly declaredSize: number;
};
/** The entries one preparation established and the coverage to report. */
export interface PositionalArtifactEntries<Metadata = never> {
readonly entries: readonly PositionalArtifactEntry[];
/** The coverage the preparation established, including complete coverage. */
readonly coverage: ArtifactReaderTraversal;
readonly formatMetadata?: Metadata;
}
/**
* Serve entries that are byte ranges of one carrier file. Preparation runs
* once; every traversal, open and completed entry stream rechecks the
* carrier's identity, and close retires open streams before the carrier.
* Encrypted entries are listed but never opened.
*/
export abstract class PositionalArtifactReader<
Metadata extends ArtifactFormatMetadata = never,
> implements ArtifactReader {
abstract readonly format: ArtifactReader["format"];
readonly #scope = new ArtifactResourceScope();
readonly #lifecycle: ArtifactStreamLifecycle;
readonly #label: string;
readonly #source: ArtifactFileSource;
readonly #preparation = new ArtifactPreparation();
#prepared:
| {
readonly entries: ReadonlyMap<string, PositionalArtifactEntry>;
readonly coverage: ArtifactReaderTraversal;
readonly formatMetadata: Metadata | undefined;
}
| undefined;
constructor(
path: string,
label: string,
admitted?: StableRegularFileDescriptor,
) {
this.#label = label;
this.#lifecycle = new ArtifactStreamLifecycle(label);
this.#source = new ArtifactFileSource(path, label, admitted);
}
/** Read the carrier once and describe its entries. */
protected abstract prepareEntries(
signal?: AbortSignal,
): Promise<PositionalArtifactEntries<Metadata>>;
/** Metadata from the same validated preparation that established entries and coverage. */
protected get preparedFormatMetadata(): Metadata | undefined {
return this.#prepared?.formatMetadata;
}
async prepareContainer(
expectedSha256: string,
signal?: AbortSignal,
): Promise<void> {
await this.#scope.run(async () => {
this.assertOpen(signal);
await this.#source.bindSha256(expectedSha256, signal);
});
}
async *entries(
signal?: AbortSignal,
options?: ArtifactTraversalOptions,
): AsyncIterable<ArtifactEntry> {
await this.#scope.run(async () => {
this.assertOpen(signal);
// The first preparation validates before publishing; cached traversals
// still need their own freshness admission.
if (this.#prepared !== undefined) await this.#source.read(signal);
await this.#preparation.run(
signal,
() => this.#prepare(signal),
() => this.assertOpen(signal),
);
});
this.assertOpen(signal);
const prepared = this.#prepared;
if (prepared === undefined)
throw invariantViolation(
"Positional artifact preparation did not complete",
);
options?.onCoverage?.({
...prepared.coverage,
limitations: [...prepared.coverage.limitations],
});
let index = 0;
for (const entry of prepared.entries.values()) {
// Yield between batches so a large inventory does not hold the loop.
if (index++ % 256 === 0) await setImmediate();
this.assertOpen(signal);
yield copyArtifactEntry(entry);
}
this.assertOpen(signal);
}
async open(entry: ArtifactEntry, signal?: AbortSignal): Promise<Readable> {
return this.#scope.run(async () => {
this.assertOpen(signal);
const stored = this.#prepared?.entries.get(entry.adapterKey);
assertProducedEntry(
entry,
stored,
`${this.#label} entry does not match its owning inventory`,
);
if (stored.encrypted)
throw new ArtifactReaderFailure(
"unavailable",
`Encrypted ${this.#label} member is unsupported: ${stored.path}`,
);
const { handle } = await this.#source.read(signal);
this.assertOpen(signal);
const lifecycle = this.#lifecycle.member(signal);
const { signal: streamSignal, cancellationFailure } = lifecycle;
const source =
stored.declaredSize === 0
? Readable.from([])
: readFileHandleChunks(handle, {
start: stored.byteOffset,
end: stored.byteOffset + stored.declaredSize - 1,
signal: streamSignal,
cancellationFailure,
});
const output = this.#entryStream(stored, lifecycle);
ownArtifactStream(source, output, {
scope: this.#scope,
signal: streamSignal,
cancellationFailure,
label: this.#label,
});
return output;
});
}
async close(): Promise<void> {
this.#lifecycle.close();
await this.#scope.close();
await this.#source.close();
this.#prepared = undefined;
this.#preparation.clear();
}
provenance(): readonly [] {
return [];
}
/** Recheck the carrier's identity and borrow its descriptor. */
protected verifyCarrier(
signal?: AbortSignal,
): Promise<StableRegularFileDescriptor> {
return this.#source.read(signal);
}
/** Refuse work once the caller cancels or close begins. */
protected assertOpen(signal?: AbortSignal): void {
assertArtifactReadActive(signal);
if (this.#lifecycle.closed)
throw new ArtifactReaderFailure(
"unavailable",
`${this.#label} reader is closed`,
);
}
async #prepare(signal?: AbortSignal): Promise<void> {
const prepared = await this.prepareEntries(signal);
const entries = new Map(
prepared.entries.map((entry) => [entry.adapterKey, entry] as const),
);
await this.#source.read(signal);
this.assertOpen(signal);
this.#prepared = {
entries,
coverage: prepared.coverage,
formatMetadata: prepared.formatMetadata,
};
}
#entryStream(
entry: PositionalArtifactEntry,
lifecycle: ArtifactMemberLifecycle,
): Transform {
const label = this.#label;
let bytes = 0;
const check = async (): Promise<void> => {
if (bytes !== entry.declaredSize)
throw new ArtifactReaderFailure(
"integrity",
`${label} entry ended early: ${entry.path}`,
{ integrityCheck: "declared-size" },
);
await lifecycle.verify((signal) => this.#source.read(signal));
};
return new Transform({
transform(chunk: Buffer, _encoding, callback) {
bytes += chunk.length;
callback(null, chunk);
},
flush(callback) {
void check().then(
() => callback(),
(cause: unknown) =>
callback(
cause instanceof Error
? cause
: new Error(`${label} read failed`, { cause }),
),
);
},
});
}
}