test(composition): consolidate external writer cleanup checks (#12980)

This commit is contained in:
morluto authored and GitHub committed 2026-11-21 03:45:06 +00:00
1 parent 7cc9fa1166
commit d7cebb77a6
1 file changed
+131 -178
@@ -42,7 +42,6 @@ import {
} from "node:fs/promises";
import { dirname, extname, join } from "node:path";
import { describe, expect, it, onTestFinished, vi } from "vitest";
import { releaseOwnedCleanup } from "../../support/cleanupRelease.js";
const client = (fail = false): AnalysisClient => ({
execute: () => Promise.resolve(fail ? err(new HopperStartError()) : ok(null)),
@@ -201,76 +200,74 @@ it("preserves the exact abort reason before external mutation admission", async
await session.close();
});
it("drains session calls and retires analysis after an admitted external mutation", async () => {
const [target] = await createBinarySessionTargets();
const alias = join(dirname(target), "first-alias.hop");
await symlink(target, alias);
const calls: string[] = [];
const clients: { closed: number; targetSha256: string }[] = [];
const base = createCacheProvider(calls);
const session = createTestBinarySession({
...base,
createClient: (...arguments_) => {
const client = base.createClient(...arguments_);
const tracked = { closed: 0, targetSha256: arguments_[0].sha256 };
clients.push(tracked);
return {
...client,
close: async () => {
tracked.closed += 1;
return client.close();
},
};
},
});
expect((await session.open(target)).ok).toBe(true);
expect(session.activeTarget()?.path).toBe(target);
const originalDigest = session.activeTarget()?.sha256;
expect(originalDigest).toEqual(expect.any(String));
const started = createDeferred<void>();
const release = createDeferred<void>();
it.each([
["symlink", symlink],
["hard link", link],
] as const)(
"queues analysis and retires the target after an external mutation through a %s",
async (_kind, createAlias) => {
const [target] = await createBinarySessionTargets();
const alias = join(dirname(target), "alias.hop");
await createAlias(target, alias);
const calls: string[] = [];
const clientDigests: string[] = [];
const base = createCacheProvider(calls);
const session = createTestBinarySession({
...base,
createClient: (...arguments_) => {
clientDigests.push(arguments_[0].sha256);
return base.createClient(...arguments_);
},
});
expect((await session.open(target)).ok).toBe(true);
expect(session.activeTarget()?.path).toBe(target);
const originalDigest = session.activeTarget()?.sha256;
expect(originalDigest).toEqual(expect.any(String));
const started = createDeferred<void>();
const release = createDeferred<void>();
const mutation = session.withAdmittedExternalMutation(
alias,
undefined,
async () => {
expect(session.activeTarget()?.path).toBe(target);
started.resolve();
await release.promise;
await writeFile(alias, "changed by external provider");
return resultOk("provider finished");
},
(_value, error) => error,
);
onTestFinished(async () => {
release.resolve();
try {
await mutation;
} finally {
await session.close();
}
});
await awaitAcknowledgement(started.promise, mutation, "external mutation");
const queuedAnalysis = session.execute("address_name", {});
expect(calls).toEqual([]);
const mutation = session.withAdmittedExternalMutation(
alias,
undefined,
async () => {
expect(session.activeTarget()?.path).toBe(target);
started.resolve();
await release.promise;
await writeFile(alias, "changed by external provider");
return resultOk("provider finished");
},
(_value, error) => error,
);
onTestFinished(async () => {
release.resolve();
try {
await mutation;
} finally {
await session.close();
}
});
await awaitAcknowledgement(started.promise, mutation, "external mutation");
const queuedAnalysis = session.execute("address_name", {});
expect(calls).toEqual([]);
release.resolve();
await expect(mutation).resolves.toMatchObject({
ok: true,
value: { ok: true, value: "provider finished" },
});
expect((await queuedAnalysis).ok).toBe(false);
expect(session.activeTarget()).toBeUndefined();
expect(calls).toEqual([]);
expect(clients).toHaveLength(0);
expect((await session.open(target)).ok).toBe(true);
expect((await session.execute("address_name", {})).ok).toBe(true);
expect(session.activeTarget()?.sha256).toEqual(expect.any(String));
expect(session.activeTarget()?.sha256).not.toBe(originalDigest);
expect(clients.at(-1)?.targetSha256).toBe(session.activeTarget()?.sha256);
expect(calls).toEqual(["address_name"]);
await session.close();
});
await expect(mutation).resolves.toMatchObject({
ok: true,
value: { ok: true, value: "provider finished" },
});
expect((await queuedAnalysis).ok).toBe(false);
expect(session.activeTarget()).toBeUndefined();
expect(calls).toEqual([]);
expect(clientDigests).toEqual([]);
expect((await session.open(target)).ok).toBe(true);
expect((await session.execute("address_name", {})).ok).toBe(true);
expect(session.activeTarget()?.sha256).toEqual(expect.any(String));
expect(session.activeTarget()?.sha256).not.toBe(originalDigest);
expect(clientDigests).toEqual([session.activeTarget()?.sha256]);
expect(calls).toEqual(["address_name"]);
await session.close();
},
);
it("leaves analysis unbound when a command returns before its writer finishes", async () => {
const [target] = await createBinarySessionTargets();
@@ -280,6 +277,14 @@ it("leaves analysis unbound when a command returns before its writer finishes",
expect(originalDigest).toEqual(expect.any(String));
const releaseWriter = createDeferred<void>();
let writer: Promise<void> | undefined;
onTestFinished(async () => {
releaseWriter.resolve();
try {
await writer;
} finally {
await session.close();
}
});
const result = await session.withAdmittedExternalMutation(
target,
undefined,
@@ -294,7 +299,7 @@ it("leaves analysis unbound when a command returns before its writer finishes",
expect(result).toEqual(resultOk(resultOk("command replied")));
expect(session.activeTarget()).toBeUndefined();
releaseWriter.resolve();
await writer;
await expect(writer).resolves.toBeUndefined();
expect((await session.execute("address_name", {})).ok).toBe(false);
expect((await session.open(target)).ok).toBe(true);
expect(session.activeTarget()?.sha256).toEqual(expect.any(String));
@@ -302,47 +307,63 @@ it("leaves analysis unbound when a command returns before its writer finishes",
await session.close();
});
it("reports an external cleanup blocker until its exact owner confirms release", async () => {
const [target] = await createBinarySessionTargets();
const session = createTestBinarySession(createCacheProvider([]));
const failure = new ProviderCleanupError(
"external-debugger",
["external-run"],
{},
);
let released = false;
const lease = new AnalysisCleanupLease(async () => {
released = true;
}, ["external-run"]);
lease.bindCleanupError(failure);
try {
expect(await session.status()).toMatchObject({ cleanup_pending: false });
await session.withAdmittedExternalMutation(
target,
undefined,
async () => err(failure),
(_value, error) => error,
it.each([false, true])(
"reports external writer cleanup until its owner releases it (target already open: %s)",
async (alreadyOpen) => {
const [target] = await createBinarySessionTargets();
const session = createTestBinarySession(createCacheProvider([]));
const failure = new ProviderCleanupError(
"external-debugger",
["external-run"],
{},
);
expect(await session.status()).toMatchObject({ cleanup_pending: true });
expect(await session.open(target)).toEqual({
ok: false,
error: failure,
targetAtCompletion: null,
providerIdAtCompletion: null,
selection: { kind: "none" },
});
await session.close({ cleanupRetry: { operation: "close_binary" } });
expect(released).toBe(false);
expect(await session.status()).toMatchObject({ cleanup_pending: true });
expect(await session.status()).not.toHaveProperty("cleanup_retry");
await lease.release();
expect(await session.status()).toMatchObject({ cleanup_pending: false });
expect((await session.open(target)).ok).toBe(true);
} finally {
await lease.release();
await session.close();
}
});
const release = vi.fn(async () => {});
const lease = new AnalysisCleanupLease(release, ["external-run"]);
lease.bindCleanupError(failure);
try {
if (alreadyOpen) expect((await session.open(target)).ok).toBe(true);
expect(await session.status()).toMatchObject({ cleanup_pending: false });
const mutation = await session.withAdmittedExternalMutation(
target,
undefined,
async () => err(failure),
(_value, error) => error,
);
expect(mutation).toEqual(resultOk(err(failure)));
expect(session.activeTarget()).toBeUndefined();
expect(await session.status()).toMatchObject({ cleanup_pending: true });
expect(await session.open(target)).toEqual({
ok: false,
error: failure,
targetAtCompletion: null,
providerIdAtCompletion: null,
selection: { kind: "none" },
});
const anotherMutation = vi.fn(async () => resultOk(null));
expect(
await session.withAdmittedExternalMutation(
target,
undefined,
anotherMutation,
(_value, error) => error,
),
).toEqual(err(failure));
expect(anotherMutation).not.toHaveBeenCalled();
await session.close({ cleanupRetry: { operation: "close_binary" } });
expect(release).not.toHaveBeenCalled();
const status = await session.status();
expect(status).toMatchObject({ cleanup_pending: true });
expect(status).not.toHaveProperty("cleanup_retry");
await lease.release();
expect(await session.status()).toMatchObject({ cleanup_pending: false });
expect((await session.open(target)).ok).toBe(true);
} finally {
await lease.release();
await session.close();
}
},
);
it("does not offer close retry while an external owner also blocks cleanup", async () => {
const [target] = await createBinarySessionTargets();
@@ -401,36 +422,6 @@ it("does not offer close retry while an external owner also blocks cleanup", asy
}
});
it("retires analysis when an external mutation uses a hard link", async () => {
const [target] = await createBinarySessionTargets();
const alias = join(dirname(target), "hard-link-alias.hop");
await link(target, alias);
const session = createTestBinarySession(createCacheProvider([]));
expect((await session.open(target)).ok).toBe(true);
const before = session.activeTarget()?.sha256;
expect(before).toEqual(expect.any(String));
const result = await session.withAdmittedExternalMutation(
alias,
undefined,
async () => {
await writeFile(alias, "changed through hard link");
return resultOk("changed");
},
(_value, error) => error,
);
expect(result).toMatchObject({
ok: true,
value: { ok: true, value: "changed" },
});
expect(session.activeTarget()).toBeUndefined();
expect((await session.open(target)).ok).toBe(true);
expect(session.activeTarget()?.sha256).toEqual(expect.any(String));
expect(session.activeTarget()?.sha256).not.toBe(before);
await session.close();
});
it("preserves Evidence records while retiring the client after an external mutation", async () => {
const [target] = await createBinarySessionTargets();
const session = createTestBinarySession(createCacheProvider([]));
@@ -1934,44 +1925,6 @@ describe("selector origin forwarding", () => {
});
});
it("blocks analysis rebinding until the external writer cleanup settles", async () => {
const [target] = await createBinarySessionTargets();
const session = createTestBinarySession(createCacheProvider([]));
expect((await session.open(target)).ok).toBe(true);
const failure = new ProviderCleanupError("rizin", ["writer"], {
reason: "writer remains alive",
});
const result = await session.withAdmittedExternalMutation(
target,
undefined,
async () => err(failure),
(_value, error) => error,
);
expect(result).toEqual(resultOk(err(failure)));
expect(session.activeTarget()).toBeUndefined();
expect(await session.open(target)).toEqual({
ok: false,
error: failure,
targetAtCompletion: null,
providerIdAtCompletion: null,
selection: { kind: "none" },
});
const anotherMutation = vi.fn(async () => resultOk("unrelated command"));
expect(
await session.withAdmittedExternalMutation(
target,
undefined,
anotherMutation,
(_value, error) => error,
),
).toEqual(err(failure));
expect(anotherMutation).not.toHaveBeenCalled();
// Only the resource owner may acknowledge completed cleanup.
releaseOwnedCleanup(failure);
expect((await session.open(target)).ok).toBe(true);
await session.close();
});
it("requires explicit close before an external mutation of an active Ghidra session", async () => {
const [target] = await createBinarySessionTargets();
const base = createCacheProvider([]);