Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
import { createHash } from "node:crypto";
import { open, type FileHandle } from "node:fs/promises";
import { z } from "zod";
import type { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
import {
AnalysisCleanupLease,
AnalysisCleanupLeaseGroup,
} from "../artifacts/AnalysisCleanupLease.js";
import type { RetainedResourceScope } from "../application/AnalysisProvider.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
import { BinaryTargetError } from "../domain/configurationErrors.js";
import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import {
readFatSliceDeclarations,
validateFatSlice,
type FatSliceDeclaration,
} from "../domain/apple/machoContainer.js";
import { machoCpuSubtypeBase } from "../domain/apple/machoCpuIdentity.js";
import type { HeaderArchitecture } from "../domain/binaryTargetTypes.js";
import {
HopperCancelledError,
HopperStartError,
} from "../domain/hopperErrors.js";
import { err, ok, type Result } from "../domain/result.js";
import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
import { readFileHandleChunks } from "../filesystem/readFileHandleChunks.js";
/** Narrow file-opening dependency for the owned prepared-image copy. */
export interface HopperMachOImageFileSystem {
readonly open: typeof open;
}
export interface HopperMachOImageCopyDependencies {
/** Persistent owner that can retry any retained descriptor cleanup. */
readonly resourceScope: ArtifactResourceScope;
readonly fileSystem?: HopperMachOImageFileSystem;
}
export interface HopperMachOImagePreparationOptions extends HopperMachOImageCopyDependencies {
readonly signal?: AbortSignal;
readonly observer?: HopperMachOImageCopyObserver;
}
const defaultHopperMachOImageFileSystem: HopperMachOImageFileSystem = { open };
const hopperFatMachOImageSchema = z.strictObject({
method: z.enum(["fat32_thin_slice", "fat64_thin_slice"]),
architecture_count: z.int().min(1).max(128),
container_table_sha256: z.string().regex(/^[a-f0-9]{64}$/u),
source_offset: z.int().nonnegative().max(Number.MAX_SAFE_INTEGER),
byte_length: z.int().positive().max(Number.MAX_SAFE_INTEGER),
cpu_type: z.int().nonnegative(),
cpu_subtype: z.int().nonnegative(),
});
const hopperThinMachOImageSchema = z.strictObject({
method: z.literal("thin_verified_copy"),
byte_length: z.int().positive().max(Number.MAX_SAFE_INTEGER),
cpu_type: z.int().nonnegative(),
cpu_subtype: z.int().nonnegative(),
});
/** Stable source coordinates committed before preparing an owned thin image. */
export const hopperMachOImageSchema = z.discriminatedUnion("method", [
hopperFatMachOImageSchema,
hopperThinMachOImageSchema,
]);
export type HopperMachOImage = z.infer<typeof hopperMachOImageSchema>;
type HopperMachOImageResolutionError =
| BinaryTargetError
| AnalysisCancelledError;
/** Controlled checkpoint for deterministic interruption of a real copy. */
export interface HopperMachOImageCopyObserver {
readonly afterChunkWritten?: (copiedBytes: number) => Promise<void>;
}
/** Filesystem access used by the admitted Mach-O preflight. */
export interface HopperMachOImageResolutionFileSystem {
readonly open: typeof open;
}
export interface HopperMachOImageResolutionOptions {
readonly resourceScope: RetainedResourceScope;
readonly signal?: AbortSignal;
readonly fileSystem?: HopperMachOImageResolutionFileSystem;
}
const defaultHopperMachOImageResolutionFileSystem: HopperMachOImageResolutionFileSystem =
{
open,
};
/** Validate the selected Mach-O image without depending on Apple's lipo tool. */
export const resolveHopperMachOImage = async (
target: BinaryTarget & { readonly kind: "executable" },
options: HopperMachOImageResolutionOptions,
): Promise<Result<HopperMachOImage, AnalysisError>> => {
const invalid = (reason: string, cause?: unknown) =>
err(
new BinaryTargetError(
target.path,
reason,
cause === undefined ? undefined : { cause },
),
);
if (options.signal?.aborted)
return err(
new AnalysisCancelledError("open_binary", {
cause: options.signal.reason,
}),
);
if (target.format !== "mach-o" && target.format !== "mach-o-universal")
return invalid("Hopper image preparation requires a Mach-O target");
let opened: FileHandle;
try {
opened = await (
options.fileSystem ?? defaultHopperMachOImageResolutionFileSystem
).open(target.path, "r");
} catch (cause: unknown) {
// Keep the OS error so a read-permission denial reports access_denied.
return invalid(
`Cannot read Mach-O source for Hopper image preparation: ${cause instanceof Error ? cause.message : String(cause)}`,
cause,
);
}
return inspectAndFinalizeHopperMachOImage(
target,
new OwnedFileHandle(opened),
options,
);
};
const inspectAndFinalizeHopperMachOImage = async (
target: BinaryTarget & { readonly kind: "executable" },
owner: OwnedFileHandle,
options: HopperMachOImageResolutionOptions,
): Promise<Result<HopperMachOImage, AnalysisError>> => {
let result: Result<HopperMachOImage, HopperMachOImageResolutionError>;
try {
result = await inspectHopperMachOImage(
target,
owner.handle,
options.signal,
);
} catch (cause: unknown) {
result =
cause instanceof BinaryTargetError ||
cause instanceof AnalysisCancelledError
? err(cause)
: err(
new BinaryTargetError(
target.path,
`Cannot validate Mach-O image: ${cause instanceof Error ? cause.message : String(cause)}`,
{ cause },
),
);
}
const cancellationBeforeClose = options.signal?.aborted === true;
let closeOutcome:
| { readonly kind: "closed" }
| { readonly kind: "failed"; readonly cause: unknown };
try {
await owner.close();
closeOutcome = { kind: "closed" };
} catch (cause: unknown) {
closeOutcome = { kind: "failed", cause };
}
if (closeOutcome.kind === "closed") {
if (result.ok && options.signal?.aborted)
return err(
new AnalysisCancelledError("open_binary", {
cause: options.signal.reason,
}),
);
return result;
}
return retainHopperPreflightCloseFailure({
target,
owner,
resourceScope: options.resourceScope,
result,
cancellationBeforeClose,
signal: options.signal,
closeFailure: closeOutcome.cause,
});
};
const retainHopperPreflightCloseFailure = (options: {
readonly target: BinaryTarget & { readonly kind: "executable" };
readonly owner: OwnedFileHandle;
readonly resourceScope: RetainedResourceScope;
readonly result: Result<HopperMachOImage, HopperMachOImageResolutionError>;
readonly cancellationBeforeClose: boolean;
readonly signal: AbortSignal | undefined;
readonly closeFailure: unknown;
}): Result<HopperMachOImage, AnalysisError> => {
const resource = `hopper-macho-preflight:${options.target.path}`;
const lease = AnalysisCleanupLease.forCloseOwner(options.owner, resource);
options.resourceScope.retain(
{
close: () => lease.release(),
get cleanupResources() {
return lease.cleanupResources;
},
},
resource,
);
const cleanup = {
reason:
options.closeFailure instanceof Error
? options.closeFailure.message
: String(options.closeFailure),
resources: [resource],
};
const cancellationIsPrimary =
(!options.result.ok &&
options.result.error instanceof AnalysisCancelledError) ||
(options.result.ok && options.cancellationBeforeClose);
let failure: AnalysisError;
let closeIsPrimary = false;
if (!options.result.ok) {
failure =
options.result.error instanceof BinaryTargetError
? new BinaryTargetError(
options.result.error.path,
options.result.error.reason,
{
...(options.result.error.cause === undefined
? {}
: { cause: options.result.error.cause }),
...(options.result.error.constraint === undefined
? {}
: { constraint: options.result.error.constraint }),
cleanup,
},
)
: new AnalysisCancelledError("open_binary", {
cause: options.result.error.cause,
cleanup,
});
} else if (options.cancellationBeforeClose) {
failure = new AnalysisCancelledError("open_binary", {
cause: options.signal?.reason,
cleanup,
});
} else {
failure = new BinaryTargetError(
options.target.path,
"Could not confirm closure of the Mach-O preflight handle",
{ cause: options.closeFailure, cleanup },
);
closeIsPrimary = true;
}
const cleanupError = new ProviderCleanupError(
"hopper",
[resource],
{ reason: cleanup.reason },
{
cause: options.closeFailure,
operation: "resolve_analysis_profile",
},
);
if (!closeIsPrimary) {
lease.bindCleanupError(cleanupError);
failure.retainSecondaryFailure(cleanupError);
}
if (options.signal?.aborted && !cancellationIsPrimary)
failure.retainSecondaryFailure(
new AnalysisCancelledError("open_binary", {
cause: options.signal.reason,
}),
);
new AnalysisCleanupLeaseGroup(failure, [lease]);
return err(failure);
};
const inspectHopperMachOImage = async (
target: BinaryTarget & { readonly kind: "executable" },
file: FileHandle,
signal: AbortSignal | undefined,
): Promise<Result<HopperMachOImage, HopperMachOImageResolutionError>> => {
const invalid = (reason: string, cause?: unknown) =>
err(
new BinaryTargetError(
target.path,
reason,
cause === undefined ? undefined : { cause },
),
);
const read = async (offset: number, length: number): Promise<Buffer> => {
const bytes = Buffer.alloc(length);
const { bytesRead } = await file.read(bytes, 0, length, offset);
return bytes.subarray(0, bytesRead);
};
const header = await read(0, 8);
const magic = header.length === 8 ? header.readUInt32BE(0) : 0;
if ([0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(magic)) {
if (target.format !== "mach-o")
return invalid("Thin Mach-O source disagrees with its admitted format");
const prefix = Buffer.alloc(12);
const hash = createHash("sha256");
let prefixLength = 0;
let size = 0;
for await (const chunk of readFileHandleChunks(file, {
...(signal === undefined ? {} : { signal }),
cancellationFailure: (reason) =>
new AnalysisCancelledError("open_binary", { cause: reason }),
})) {
if (signal?.aborted)
return err(
new AnalysisCancelledError("open_binary", {
cause: signal.reason,
}),
);
const bytes = Buffer.from(chunk);
hash.update(bytes);
size += bytes.length;
if (!Number.isSafeInteger(size))
return invalid("Thin Mach-O exceeds exact selection coordinates");
const copied = Math.min(prefix.length - prefixLength, bytes.length);
if (copied > 0) {
bytes.copy(prefix, prefixLength, 0, copied);
prefixLength += copied;
}
}
if (signal?.aborted)
return err(
new AnalysisCancelledError("open_binary", { cause: signal.reason }),
);
if (prefixLength !== prefix.length)
return invalid("Thin Mach-O header is truncated");
const observedSha256 = hash.digest("hex");
if (observedSha256 !== target.sha256)
return invalid(
`Thin Mach-O source changed after target admission: expected SHA-256 ${target.sha256}, observed ${observedSha256}`,
);
const little = magic === 0xcefaedfe || magic === 0xcffaedfe;
const headerMagic = prefix.readUInt32BE(0);
if (headerMagic !== magic)
return invalid("Thin Mach-O header changed during profile resolution");
return ok({
method: "thin_verified_copy",
byte_length: size,
cpu_type: little ? prefix.readUInt32LE(4) : prefix.readUInt32BE(4),
cpu_subtype: little ? prefix.readUInt32LE(8) : prefix.readUInt32BE(8),
});
}
const isFatMagic = [0xcafebabe, 0xcafebabf, 0xbebafeca, 0xbfbafeca].includes(
magic,
);
if (!isFatMagic)
return invalid(
"Mach-O source header changed before Hopper image preparation",
);
const wide = magic === 0xcafebabf || magic === 0xbfbafeca;
const littleEndian = magic === 0xbebafeca || magic === 0xbfbafeca;
const entrySize = wide ? 32 : 20;
const count = littleEndian ? header.readUInt32LE(4) : header.readUInt32BE(4);
const size = (await file.stat()).size;
const tableEnd = 8 + count * entrySize;
if (count === 0 || count > 128 || tableEnd > size)
return invalid(
"FAT architecture table is truncated or exceeds the supported 128 entries",
);
const table = await read(8, count * entrySize);
const parsed = readFatSliceDeclarations(table, {
count,
wide,
littleEndian,
});
if (parsed.status === "malformed") return invalid(parsed.reason);
if (
target.architecture !== "x86" &&
target.architecture !== "x86_64" &&
target.architecture !== "arm" &&
target.architecture !== "arm64"
)
return invalid("Hopper cannot select the admitted Mach-O architecture");
const architecture = target.architecture;
const cpuTypes = { x86: 7, x86_64: 0x1000007, arm: 12, arm64: 0x100000c };
const matches = [];
const ranges = [];
for (const slice of parsed.slices) {
if (signal?.aborted)
return err(
new AnalysisCancelledError("open_binary", { cause: signal.reason }),
);
const rangeError = validateFatSlice(slice, size, tableEnd);
if (rangeError !== null) return invalid(rangeError);
if (wide) {
const reserved = littleEndian
? table.readUInt32LE(slice.index * 32 + 28)
: table.readUInt32BE(slice.index * 32 + 28);
if (reserved !== 0)
return invalid(
`FAT64 architecture ${slice.index} has a nonzero reserved field`,
);
}
if (slice.size < 12)
return invalid(
`FAT architecture ${slice.index} has a truncated Mach-O header`,
);
const embedded = await read(slice.offset, 12);
if (embedded.length !== 12)
return invalid(`FAT architecture ${slice.index} became truncated`);
const thinMagic = embedded.readUInt32BE(0);
if (![0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(thinMagic))
return invalid(
`FAT architecture ${slice.index} does not contain a Mach-O image`,
);
const little = thinMagic === 0xcefaedfe || thinMagic === 0xcffaedfe;
const identity = {
cpuType: little ? embedded.readUInt32LE(4) : embedded.readUInt32BE(4),
cpuSubtype: little ? embedded.readUInt32LE(8) : embedded.readUInt32BE(8),
};
const identityError = validateFatSlice(slice, size, tableEnd, identity);
if (identityError !== null) return invalid(identityError);
ranges.push(slice);
if (slice.cpuType === cpuTypes[architecture]) matches.push(slice);
}
ranges.sort((a, b) => a.offset - b.offset);
for (let index = 1; index < ranges.length; index++) {
const previous = ranges[index - 1];
const current = ranges[index];
if (
previous !== undefined &&
current !== undefined &&
current.offset < previous.offset + previous.size
)
return invalid("FAT slices overlap");
}
const selected = selectHopperSlice(matches, architecture);
if (selected === undefined)
return invalid(
`FAT selection for ${architecture} is ${matches.length === 0 ? "missing" : "ambiguous"}; extract the exact architecture into a thin image before opening it`,
);
return ok({
method: wide ? "fat64_thin_slice" : "fat32_thin_slice",
architecture_count: count,
container_table_sha256: createHash("sha256")
.update(header)
.update(table)
.digest("hex"),
source_offset: selected.offset,
byte_length: selected.size,
cpu_type: selected.cpuType,
cpu_subtype: selected.cpuSubtype,
});
};
/**
* Plain arm64 (cpusubtype 0) and arm64e (cpusubtype 2) function-entry encodings
* decode under Hopper's --aarch64; Apple's arm64e.x1 variant (cpusubtype 12)
* does not, so it is selected only when it is the arm64 family's only candidate.
* Every other ambiguity stays fail-closed.
*/
const selectHopperSlice = (
matches: readonly FatSliceDeclaration[],
architecture: HeaderArchitecture,
): FatSliceDeclaration | undefined => {
if (matches.length === 1) return matches[0];
if (architecture !== "arm64") return undefined;
for (const cpuSubtype of [0, 2]) {
const preferred = matches.filter(
(slice) => machoCpuSubtypeBase(slice.cpuSubtype) === cpuSubtype,
);
if (preferred.length === 1) return preferred[0];
if (preferred.length > 1) return undefined;
}
return undefined;
};
/** Copy a selected slice and verify the entire original source in the same pass. */
export const prepareHopperMachOImage = async (
sourcePath: string,
sourceSha256: string,
image: HopperMachOImage,
destination: string,
options: HopperMachOImagePreparationOptions,
): Promise<Result<string, HopperStartError | HopperCancelledError>> => {
const copyDependencies = {
resourceScope: options.resourceScope,
fileSystem: options.fileSystem ?? defaultHopperMachOImageFileSystem,
};
const { signal, observer } = options;
if (signal?.aborted) return err(new HopperCancelledError(signal.reason));
if (image.method === "thin_verified_copy") {
const prepared = await prepareThinHopperMachOImage(
sourcePath,
sourceSha256,
image,
destination,
{ signal, observer, ...copyDependencies },
);
return signal?.aborted && prepared.ok
? err(new HopperCancelledError(signal.reason))
: prepared;
}
const tableEntrySize = image.method === "fat64_thin_slice" ? 32 : 20;
const hash = createHash("sha256");
const tableHash = createHash("sha256");
const tableEnd = 8 + image.architecture_count * tableEntrySize;
const thinHeader: Buffer[] = [];
let copied = 0;
const copiedResult = await copyHopperSource({
sourcePath,
destination,
signal,
observer,
...copyDependencies,
selectBytes: (bytes, position) => {
hash.update(bytes);
if (position < tableEnd)
tableHash.update(
bytes.subarray(0, Math.min(bytes.length, tableEnd - position)),
);
const start = Math.max(0, image.source_offset - position);
const end = Math.min(
bytes.length,
image.source_offset + image.byte_length - position,
);
if (end <= start) return undefined;
if (copied < 12)
thinHeader.push(
bytes.subarray(start, Math.min(end, start + 12 - copied)),
);
copied += end - start;
return bytes.subarray(start, end);
},
failureContext: `Cannot prepare the selected FAT image from ${sourcePath}`,
});
if (!copiedResult.ok) return copiedResult;
const observed = hash.digest("hex");
const header = Buffer.concat(thinHeader);
const magic = header.length === 12 ? header.readUInt32BE(0) : 0;
const little = magic === 0xcefaedfe || magic === 0xcffaedfe;
const headerMatches =
header.length === 12 &&
[0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(magic) &&
(little ? header.readUInt32LE(4) : header.readUInt32BE(4)) ===
image.cpu_type &&
(little ? header.readUInt32LE(8) : header.readUInt32BE(8)) ===
image.cpu_subtype;
if (
tableHash.digest("hex") !== image.container_table_sha256 ||
!headerMatches
)
return err(
new HopperStartError({
userMessage: `FAT source ${sourcePath} no longer agrees with its committed architecture table or selected Mach-O header. Open the stable source again.`,
}),
);
if (observed !== sourceSha256 || copied !== image.byte_length)
return err(
new HopperStartError({
userMessage: `FAT source ${sourcePath} changed before launch: expected SHA-256 ${sourceSha256}, observed ${observed}; copied ${copied} of ${image.byte_length} selected bytes. Open the stable source again.`,
}),
);
return signal?.aborted
? err(new HopperCancelledError(signal.reason))
: ok(destination);
};
const prepareThinHopperMachOImage = async (
sourcePath: string,
sourceSha256: string,
image: Extract<HopperMachOImage, { method: "thin_verified_copy" }>,
destination: string,
options: {
readonly signal: AbortSignal | undefined;
readonly observer: HopperMachOImageCopyObserver | undefined;
readonly resourceScope: ArtifactResourceScope;
readonly fileSystem: HopperMachOImageFileSystem;
},
): Promise<Result<string, HopperStartError | HopperCancelledError>> => {
const { signal, observer, resourceScope, fileSystem } = options;
const hash = createHash("sha256");
const prefix = Buffer.alloc(12);
let prefixLength = 0;
const copiedResult = await copyHopperSource({
sourcePath,
destination,
signal,
observer,
resourceScope,
fileSystem,
selectBytes: (bytes) => {
hash.update(bytes);
const prefixBytes = Math.min(prefix.length - prefixLength, bytes.length);
if (prefixBytes > 0) {
bytes.copy(prefix, prefixLength, 0, prefixBytes);
prefixLength += prefixBytes;
}
return bytes;
},
failureContext: `Cannot prepare the verified thin image from ${sourcePath}`,
});
if (!copiedResult.ok) return copiedResult;
const copied = copiedResult.value;
if (!Number.isSafeInteger(copied))
return err(
new HopperStartError({
userMessage: `Thin Mach-O source ${sourcePath} exceeds exact copy coordinates.`,
}),
);
const observed = hash.digest("hex");
const magic = prefixLength === prefix.length ? prefix.readUInt32BE(0) : 0;
const little = magic === 0xcefaedfe || magic === 0xcffaedfe;
const headerMatches =
prefixLength === prefix.length &&
[0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe].includes(magic) &&
(little ? prefix.readUInt32LE(4) : prefix.readUInt32BE(4)) ===
image.cpu_type &&
(little ? prefix.readUInt32LE(8) : prefix.readUInt32BE(8)) ===
image.cpu_subtype;
if (
observed !== sourceSha256 ||
copied !== image.byte_length ||
!headerMatches
)
return err(
new HopperStartError({
userMessage: `Thin Mach-O source ${sourcePath} no longer agrees with its admitted digest, size, or selected header. Open the stable source again.`,
}),
);
return signal?.aborted
? err(new HopperCancelledError(signal.reason))
: ok(destination);
};
type HopperImageHandle = OwnedFileHandle | undefined;
type HopperImageCloseFailure = {
readonly resource: string;
readonly cause: unknown;
};
type HopperImageCleanupAttempt = Extract<
Awaited<ReturnType<ArtifactResourceScope["release"]>>,
{ readonly kind: "failed" }
>;
interface HopperImageCopyOperation {
readonly copied: number;
readonly operationFailure:
| { readonly failed: false }
| {
readonly failed: true;
readonly cause: unknown;
};
readonly cancelled:
| { readonly cancelled: false }
| {
readonly cancelled: true;
readonly reason: unknown;
};
readonly source: HopperImageHandle;
readonly output: HopperImageHandle;
}
interface HopperImageCopyFinalization {
readonly closeFailures: readonly HopperImageCloseFailure[];
readonly retained: readonly HopperImageCleanupAttempt[];
}
/** Own source/output handles and copy finalization for both Mach-O layouts. */
const copyHopperSource = async (options: {
readonly sourcePath: string;
readonly destination: string;
readonly signal: AbortSignal | undefined;
readonly observer: HopperMachOImageCopyObserver | undefined;
readonly resourceScope: ArtifactResourceScope;
readonly fileSystem: HopperMachOImageFileSystem;
readonly selectBytes: (chunk: Buffer, position: number) => Buffer | undefined;
readonly failureContext: string;
}): Promise<Result<number, HopperStartError | HopperCancelledError>> => {
if (options.signal?.aborted)
return err(new HopperCancelledError(options.signal.reason));
const operation = await performHopperImageCopy(options);
const cancellationBeforeFinalization = operation.cancelled.cancelled
? operation.cancelled
: options.signal?.aborted === true
? { cancelled: true as const, reason: options.signal.reason }
: { cancelled: false as const };
const finalization = await closeHopperImageHandles(operation, options);
const cancelled =
cancellationBeforeFinalization.cancelled ||
(finalization.closeFailures.length === 0 &&
options.signal?.aborted === true);
const cancelReason = cancellationBeforeFinalization.cancelled
? cancellationBeforeFinalization.reason
: options.signal?.reason;
if (
!operation.operationFailure.failed &&
!cancelled &&
finalization.closeFailures.length === 0
)
return ok(operation.copied);
return hopperImageCopyFailure({
operation,
finalization,
failureContext: options.failureContext,
cancelled,
cancelReason,
});
};
const performHopperImageCopy = async (options: {
readonly sourcePath: string;
readonly destination: string;
readonly signal: AbortSignal | undefined;
readonly observer: HopperMachOImageCopyObserver | undefined;
readonly fileSystem: HopperMachOImageFileSystem;
readonly selectBytes: (chunk: Buffer, position: number) => Buffer | undefined;
}): Promise<HopperImageCopyOperation> => {
let copied = 0;
let source: HopperImageHandle;
let output: HopperImageHandle;
try {
source = new OwnedFileHandle(
await options.fileSystem.open(options.sourcePath, "r"),
);
output = new OwnedFileHandle(
await options.fileSystem.open(options.destination, "wx", 0o600),
);
} catch (cause: unknown) {
return {
copied,
operationFailure: { failed: true, cause },
cancelled: { cancelled: false },
source,
output,
};
}
try {
let position = 0;
for await (const bytes of readFileHandleChunks(source.handle)) {
if (options.signal?.aborted)
return {
copied,
operationFailure: { failed: false },
cancelled: { cancelled: true, reason: options.signal.reason },
source,
output,
};
const selected = options.selectBytes(bytes, position);
if (selected !== undefined && selected.length > 0) {
await output.handle.writeFile(selected);
copied += selected.length;
await options.observer?.afterChunkWritten?.(copied);
}
position += bytes.length;
}
return {
copied,
operationFailure: { failed: false },
cancelled: { cancelled: false },
source,
output,
};
} catch (cause: unknown) {
return {
copied,
operationFailure: { failed: true, cause },
cancelled: { cancelled: false },
source,
output,
};
}
};
const closeHopperImageHandles = async (
operation: HopperImageCopyOperation,
options: {
readonly sourcePath: string;
readonly destination: string;
readonly resourceScope: ArtifactResourceScope;
},
): Promise<HopperImageCopyFinalization> => {
const closeFailures: HopperImageCloseFailure[] = [];
const retained: HopperImageCleanupAttempt[] = [];
const close = async (
owner: HopperImageHandle,
resource: string,
): Promise<void> => {
if (owner === undefined) return;
try {
await owner.close();
} catch (cause: unknown) {
closeFailures.push({ resource, cause });
const attempt = await options.resourceScope.release({
kind: "file-handle",
resource,
handle: owner,
});
if (attempt.kind === "failed") retained.push(attempt);
}
};
await close(operation.output, `hopper-prepared-image:${options.destination}`);
await close(operation.source, `hopper-image-source:${options.sourcePath}`);
return { closeFailures, retained };
};
const hopperImageCopyFailure = (options: {
readonly operation: HopperImageCopyOperation;
readonly finalization: HopperImageCopyFinalization;
readonly failureContext: string;
readonly cancelled: boolean;
readonly cancelReason: unknown;
}): Result<number, HopperStartError | HopperCancelledError> => {
const { operation, finalization } = options;
const cleanupErrors = finalization.retained.map((attempt) => {
const cleanupError = new ProviderCleanupError(
"hopper",
[attempt.owner.resource],
{
reason:
attempt.cause instanceof Error
? attempt.cause.message
: String(attempt.cause),
},
{ cause: attempt.cause },
);
attempt.lease.bindCleanupError(cleanupError);
return cleanupError;
});
const cleanup =
cleanupErrors.length === 0
? undefined
: {
reason: cleanupErrors.map((failure) => failure.message).join("; "),
resources: [
...new Set(
cleanupErrors.flatMap((failure) => failure.cleanupResources),
),
],
};
const primaryFailure = operation.operationFailure.failed
? operation.operationFailure.cause
: finalization.closeFailures[0]?.cause;
const resultError =
options.cancelled && !operation.operationFailure.failed
? new HopperCancelledError(
options.cancelReason,
cleanup === undefined ? {} : { cleanup },
)
: new HopperStartError({
...(operation.operationFailure.failed ||
finalization.closeFailures.length > 0
? { cause: primaryFailure }
: {}),
userMessage: `${options.failureContext}: ${primaryFailure instanceof Error ? primaryFailure.message : String(primaryFailure ?? "caller cancellation")}`,
...(cleanup === undefined ? {} : { cleanup }),
});
for (const closeFailure of finalization.closeFailures) {
if (
!operation.operationFailure.failed &&
!options.cancelled &&
closeFailure === finalization.closeFailures[0]
)
continue;
resultError.retainSecondaryFailure(
new HopperStartError({
cause: closeFailure.cause,
userMessage: `Could not confirm closure of ${closeFailure.resource}.`,
}),
);
}
for (const cleanupError of cleanupErrors)
resultError.retainSecondaryFailure(cleanupError);
if (cleanupErrors.length > 0)
resultError.bindCleanupDependencies(cleanupErrors);
return err(resultError);
};