Skip to content

Commit 9191a30

Browse files
kazemek21claude
andcommitted
feat(plugins): report conclusively retired update providers
This lets a plugin distinguish a conclusively retired update provider from an unknown submission without bypassing native review. The optional getOwnerStatus(ownerId) answers "retired" only after the host saw that exact provider lifetime disposed with no queued, reviewing or confirmed operation left; every other case stays "unknown". Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Kyle Zemek <[email protected]>
1 parent 0c66ed0 commit 9191a30

5 files changed

Lines changed: 253 additions & 1 deletion

File tree

‎docs/plugin-architecture.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -462,6 +462,7 @@ type PluginUpdateCapability = {
462462
getQueue(id: string): PluginUpdateQueueSnapshot | undefined;
463463
subscribeQueue(id: string, listener: () => void): () => void;
464464
cancelQueue(id: string): boolean;
465+
getOwnerStatus?(ownerId: PluginUpdateOwnerId): "retired" | "unknown"; // missing on older hosts
465466
};
466467
```
467468

@@ -546,6 +547,23 @@ this contract does not provide cross-restart idempotency. An absent capability
546547
or an `unavailable` snapshot is not evidence that a prior ambiguous submission
547548
was rejected. A refresh does not resolve an earlier ambiguous submission.
548549

550+
`getOwnerStatus(ownerId)` tells a caller whether a provider lifetime it captured
551+
earlier is over. It reports `retired` only after this host process saw that exact
552+
provider disposed with no queued or reviewing item and no confirmed operation
553+
left, so that lifetime can no longer open a review or install anything. A
554+
confirmed update keeps its provider unretired until the operation finishes and
555+
releases the shared review. Everything else is `unknown`: any provider not yet
556+
disposed, whether current, replaced or unregistered; an ID this host never
557+
registered; a lifetime older than the 16 most recently registered lifetimes; and
558+
any ID after a host restart. It is a point-in-time read: retirement does not
559+
notify subscribers. Feature-check the method; an older host without it gives no
560+
retirement evidence. `retired` does not say
561+
what happened to an earlier request: a `getQueueRequest()` result of `unknown`
562+
stays unknown, and retirement is not evidence of rejection, cancellation,
563+
installation or activation. It only means no review or operation from that
564+
lifetime remains, so any new submission goes through the current provider and
565+
the normal explicit review.
566+
549567
`requestInstall` never installs silently. It opens Settings → Plugins with the Git
550568
source prefilled and read-only, and the user still chooses **Find**, reviews the
551569
existing access review, and confirms. The promise resolves with what the user did:

‎src/plugins/installer.test.ts‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -421,6 +421,58 @@ it("isolates request identities by plugin and replays after that caller remounts
421421
}
422422
});
423423

424+
it("reports an old provider retired to plugins only after its confirmed update releases the shared review", async () => {
425+
const f = await setupUpdates();
426+
const replacement = createPluginUpdates(f.manager as never, async () => null);
427+
let stopReplacement = () => {};
428+
try {
429+
const market = (await f.as("example.market")).updates;
430+
const other = (await f.as("example.other")).updates;
431+
const ownerId = market?.ownerId;
432+
if (!market || !other || !ownerId) throw new Error("Expected updates");
433+
const queue = market.queueUpdates([f.token]);
434+
const review = f.updates.startNextReview(f.requests.tryHoldReview);
435+
if (!queue || !review) throw new Error("Expected an open update review");
436+
expect(f.updates.beginOperation(queue.id, review.token)).toBeDefined();
437+
438+
stopReplacement = f.requests.registerUpdates(replacement);
439+
f.unregister();
440+
f.updates.dispose();
441+
expect(market.ownerId).toBe(replacement.capability.ownerId);
442+
expect(market.getOwnerStatus?.(ownerId)).toBe("unknown");
443+
expect(f.requests.tryHoldReview()).toBeUndefined();
444+
await expect(
445+
f.core.submit(base, { id: "example.market", lifetime: () => () => {} }),
446+
).resolves.toBe("unavailable");
447+
await replacement.check();
448+
const next = replacement.capability.getSnapshot().candidates[0]?.token;
449+
if (!next) throw new Error("Expected a replacement candidate");
450+
expect(market.queueUpdates([next])).toBeDefined();
451+
expect(
452+
replacement.startNextReview(f.requests.tryHoldReview),
453+
).toBeUndefined();
454+
455+
expect(f.updates.finishReview(queue.id, review.token, "updated")).toBe(
456+
true,
457+
);
458+
expect(market.getOwnerStatus?.(ownerId)).toBe("retired");
459+
expect(other.getOwnerStatus?.(ownerId)).toBe("retired");
460+
await f.fibers[0]?.dispose();
461+
const remounted = (await f.as("example.market")).updates;
462+
expect(remounted?.getOwnerStatus?.(ownerId)).toBe("retired");
463+
const replacementId = replacement.capability.ownerId;
464+
if (!replacementId) throw new Error("Expected a replacement identity");
465+
expect(remounted?.getOwnerStatus?.(replacementId)).toBe("unknown");
466+
expect(replacement.startNextReview(f.requests.tryHoldReview)).toBeDefined();
467+
} finally {
468+
stopReplacement();
469+
replacement.dispose();
470+
f.unregister();
471+
f.updates.dispose();
472+
await Promise.all(f.fibers.map((fiber) => fiber.dispose()));
473+
}
474+
});
475+
424476
it("bounds sequential plugin refreshes without throttling host-forced checks", async () => {
425477
vi.useFakeTimers();
426478
const f = await setupUpdates();

‎src/plugins/installer.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -476,6 +476,8 @@ export function createPluginInstallerService(
476476
getQueueRequest: updates.getQueueRequest,
477477
getQueue: updates.getQueue,
478478
cancelQueue: updates.cancelQueue,
479+
getOwnerStatus: (ownerId) =>
480+
updates.getOwnerStatus?.(ownerId) ?? "unknown",
479481
subscribe(listener) {
480482
const stop = caller.effect(() => updates.subscribe(listener));
481483
return () => void stop();

‎src/plugins/updates.test.ts‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -933,6 +933,161 @@ it("returns unknown when a queue request's provider is replaced", async () => {
933933
replacement.dispose();
934934
});
935935

936+
it("reports a replaced provider retired only after disposal ends its queued and unopened reviews", async () => {
937+
const f = fixture();
938+
const bridge = createPluginUpdateCapabilityBridge();
939+
const original = createPluginUpdates(f.manager, f.authorize);
940+
bridge.register(original);
941+
const token = (await bridge.capability.refresh()).candidates[0]?.token;
942+
const ownerId = bridge.capability.ownerId;
943+
if (!token || !ownerId) throw new Error("Expected a retained provider");
944+
const reviewing = bridge.capability.queueUpdates([token]);
945+
const queued = bridge.capability.queueUpdates([token]);
946+
const review = startReview(original);
947+
if (!reviewing || !queued || !review) throw new Error("Expected a review");
948+
949+
const replacement = createPluginUpdates(f.manager, f.authorize);
950+
const unregisterReplacement = bridge.register(replacement);
951+
const nextOwnerId = bridge.capability.ownerId;
952+
if (!nextOwnerId) throw new Error("Expected a replacement provider");
953+
expect(original.capability.getQueue(reviewing.id)?.status).toBe("reviewing");
954+
expect(original.capability.getQueue(queued.id)?.status).toBe("queued");
955+
for (const id of [ownerId, nextOwnerId, "unseen" as typeof ownerId])
956+
expect(bridge.capability.getOwnerStatus?.(id)).toBe("unknown");
957+
958+
original.dispose();
959+
expect(original.capability.getQueue(reviewing.id)?.status).toBe("cancelled");
960+
expect(original.capability.getQueue(queued.id)?.status).toBe("cancelled");
961+
for (let query = 0; query < 3; query++)
962+
expect(bridge.capability.getOwnerStatus?.(ownerId)).toBe("retired");
963+
expect(bridge.forCaller("example.market").getOwnerStatus?.(ownerId)).toBe(
964+
"retired",
965+
);
966+
expect(original.beginOperation(review.queueId, review.token)).toBeUndefined();
967+
expect(startReview(original)).toBeUndefined();
968+
expect(original.capability.queueUpdates([token])).toBeUndefined();
969+
expect(bridge.capability.getOwnerStatus?.(nextOwnerId)).toBe("unknown");
970+
expect(
971+
bridge.capability.getQueueRequest({
972+
ownerId,
973+
requestId: "historical-request",
974+
tokens: [token],
975+
}),
976+
).toEqual({ status: "unknown" });
977+
978+
unregisterReplacement();
979+
replacement.dispose();
980+
});
981+
982+
it.each([
983+
["finished", "installed"],
984+
["ended", "failed"],
985+
["cancelled", "cancelled"],
986+
["reconfirmed", "failed"],
987+
] as const)(
988+
"keeps a confirmed operation's provider unknown past disposal until it is %s",
989+
async (completion, itemStatus) => {
990+
const f = fixture();
991+
const bridge = createPluginUpdateCapabilityBridge();
992+
const original = createPluginUpdates(f.manager, f.authorize);
993+
bridge.register(original);
994+
const token = (await bridge.capability.refresh()).candidates[0]?.token;
995+
const ownerId = bridge.capability.ownerId;
996+
if (!token || !ownerId) throw new Error("Expected a retained provider");
997+
const queue = bridge.capability.queueUpdates([token]);
998+
let held = false;
999+
const statusAtRelease = vi.fn(() =>
1000+
bridge.capability.getOwnerStatus?.(ownerId),
1001+
);
1002+
const hold = () => {
1003+
held = true;
1004+
return () => {
1005+
statusAtRelease();
1006+
held = false;
1007+
};
1008+
};
1009+
const review = original.startNextReview(hold);
1010+
if (!queue || !review) throw new Error("Expected a review");
1011+
const unconfirm = original.beginOperation(queue.id, review.token);
1012+
expect(unconfirm).toEqual(expect.any(Function));
1013+
1014+
const replacement = createPluginUpdates(f.manager, f.authorize);
1015+
const unregisterReplacement = bridge.register(replacement);
1016+
original.dispose();
1017+
if (completion === "finished" || completion === "ended")
1018+
expect(original.capability.cancelQueue(queue.id)).toBe(true);
1019+
expect(original.getActiveReview()).toBeDefined();
1020+
expect(held).toBe(true);
1021+
expect(bridge.capability.getOwnerStatus?.(ownerId)).toBe("unknown");
1022+
if (completion === "finished") {
1023+
expect(original.finishReview(queue.id, review.token, "updated")).toBe(
1024+
true,
1025+
);
1026+
} else {
1027+
unconfirm?.();
1028+
expect(original.getActiveReview()).toBeDefined();
1029+
expect(bridge.capability.getOwnerStatus?.(ownerId)).toBe("unknown");
1030+
if (completion === "ended")
1031+
expect(
1032+
original.endReview(queue.id, review.token, "install failed"),
1033+
).toBe(true);
1034+
else if (completion === "cancelled")
1035+
expect(original.capability.cancelQueue(queue.id)).toBe(true);
1036+
else
1037+
expect(original.beginOperation(queue.id, review.token)).toBeUndefined();
1038+
}
1039+
1040+
expect(statusAtRelease).toHaveReturnedWith("unknown");
1041+
expect(held).toBe(false);
1042+
expect(original.getActiveReview()).toBeUndefined();
1043+
expect(bridge.capability.getOwnerStatus?.(ownerId)).toBe("retired");
1044+
expect(original.capability.getQueue(queue.id)?.items[0]?.status).toBe(
1045+
itemStatus,
1046+
);
1047+
expect(original.capability.queueUpdates([token])).toBeUndefined();
1048+
expect(original.startNextReview(hold)).toBeUndefined();
1049+
expect(held).toBe(false);
1050+
unregisterReplacement();
1051+
replacement.dispose();
1052+
},
1053+
);
1054+
1055+
it("keeps live, unregistered, evicted and restarted provider lifetimes unknown", async () => {
1056+
const f = fixture();
1057+
const bridge = createPluginUpdateCapabilityBridge();
1058+
const original = createPluginUpdates(f.manager, f.authorize);
1059+
const ownerId = original.capability.ownerId;
1060+
if (!ownerId) throw new Error("Expected a provider identity");
1061+
expect(bridge.capability.getOwnerStatus?.(ownerId)).toBe("unknown");
1062+
const unregister = bridge.register(original);
1063+
expect(bridge.capability.getOwnerStatus?.(ownerId)).toBe("unknown");
1064+
unregister();
1065+
expect(bridge.capability.getOwnerStatus?.(ownerId)).toBe("unknown");
1066+
original.dispose();
1067+
expect(bridge.capability.getOwnerStatus?.(ownerId)).toBe("retired");
1068+
expect(
1069+
createPluginUpdateCapabilityBridge().capability.getOwnerStatus?.(ownerId),
1070+
).toBe("unknown");
1071+
1072+
const later: ReturnType<typeof createPluginUpdates>[] = [];
1073+
for (let index = 0; index < 15; index++) {
1074+
const next = createPluginUpdates(f.manager, f.authorize);
1075+
bridge.register(next)();
1076+
next.dispose();
1077+
later.push(next);
1078+
}
1079+
expect(bridge.capability.getOwnerStatus?.(ownerId)).toBe("retired");
1080+
const newest = createPluginUpdates(f.manager, f.authorize);
1081+
const unregisterNewest = bridge.register(newest);
1082+
expect(bridge.capability.getOwnerStatus?.(ownerId)).toBe("unknown");
1083+
const laterIds = later.map((next) => next.capability.ownerId);
1084+
expect(laterIds).not.toContain(undefined);
1085+
for (const id of laterIds)
1086+
if (id) expect(bridge.capability.getOwnerStatus?.(id)).toBe("retired");
1087+
unregisterNewest();
1088+
newest.dispose();
1089+
});
1090+
9361091
it("does not replay an ambiguous update request across checker lifetimes", async () => {
9371092
const f = fixture();
9381093
const first = createPluginUpdates(f.manager, f.authorize);

‎src/plugins/updates.ts‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -156,6 +156,12 @@ export type PluginUpdateCapability = Readonly<{
156156
subscribeQueue(id: string, listener: () => void): () => void;
157157
/** Stops queued/unopened reviews; an already-confirmed operation is not undone. */
158158
cancelQueue(id: string): boolean;
159+
/**
160+
* `retired` only when this host process saw that exact provider lifetime end
161+
* with no queued, reviewing, or confirmed operation left; otherwise `unknown`.
162+
* Missing on older hosts. Says nothing about the outcome of an earlier request.
163+
*/
164+
getOwnerStatus?(ownerId: PluginUpdateOwnerId): "retired" | "unknown";
159165
}>;
160166

161167
function freezeSnapshot(snapshot: PluginUpdateSnapshot): PluginUpdateSnapshot {
@@ -244,6 +250,7 @@ export const updateSourceKey = (source: GitUpdateSource) =>
244250

245251
const MAX_RETAINED_UPDATE_QUEUES = 50;
246252
const MAX_RETAINED_UPDATE_REQUESTS = 1024;
253+
const MAX_RETAINED_UPDATE_OWNERS = 16;
247254

248255
function uniqueQueueTokens(tokens: readonly PluginUpdateToken[]) {
249256
return [...new Set(tokens)];
@@ -260,6 +267,7 @@ export function createPluginUpdates(
260267
) => Promise<{ repository: string; token: string } | null>,
261268
) {
262269
const ownerId = crypto.randomUUID() as PluginUpdateOwnerId;
270+
const lifetime = { ownerId, retired: false };
263271
let updates: readonly PluginUpdate[] = [];
264272
let closed = false;
265273
let pending: Promise<number | undefined> | undefined;
@@ -286,6 +294,8 @@ export function createPluginUpdates(
286294
const release = releaseActiveReview;
287295
releaseActiveReview = undefined;
288296
release?.();
297+
// A confirmed operation keeps its review, and so this lifetime, open past dispose.
298+
if (closed && !activeReview) lifetime.retired = true;
289299
};
290300
const key = (update: PluginUpdate) =>
291301
`${update.id}:${updateSourceKey(update.source)}:${update.candidate?.revision ?? update.error}`;
@@ -949,6 +959,7 @@ export function createPluginUpdates(
949959
return {
950960
snapshot: () => updates,
951961
capability,
962+
lifetime: lifetime as Readonly<typeof lifetime>,
952963
forCaller(callerId: string): PluginUpdateCapability {
953964
return {
954965
...capability,
@@ -1019,8 +1030,16 @@ export function createPluginUpdateCapabilityBridge() {
10191030
candidates: Object.freeze([]),
10201031
errors: Object.freeze([]),
10211032
});
1022-
let provider: Pick<PluginUpdates, "capability" | "forCaller"> | undefined;
1033+
let provider:
1034+
| Pick<PluginUpdates, "capability" | "forCaller" | "lifetime">
1035+
| undefined;
10231036
let unsubscribeProvider: (() => void) | undefined;
1037+
// Keep lifetime records, not providers, so replaced providers can be collected.
1038+
const lifetimes = new Map<PluginUpdateOwnerId, PluginUpdates["lifetime"]>();
1039+
const getOwnerStatus = (ownerId: PluginUpdateOwnerId) =>
1040+
lifetimes.get(ownerId)?.retired
1041+
? ("retired" as const)
1042+
: ("unknown" as const);
10241043
const listeners = new Set<() => void>();
10251044
const notify = () => {
10261045
notifySafely(listeners);
@@ -1054,6 +1073,7 @@ export function createPluginUpdateCapabilityBridge() {
10541073
});
10551074
},
10561075
cancelQueue: (id) => resolve()?.cancelQueue(id) ?? false,
1076+
getOwnerStatus,
10571077
};
10581078
return capability;
10591079
};
@@ -1066,6 +1086,11 @@ export function createPluginUpdateCapabilityBridge() {
10661086
register(next: NonNullable<typeof provider>) {
10671087
unsubscribeProvider?.();
10681088
provider = next;
1089+
lifetimes.delete(next.lifetime.ownerId);
1090+
lifetimes.set(next.lifetime.ownerId, next.lifetime);
1091+
// An evicted lifetime becomes unknown, never retired.
1092+
for (const id of lifetimes.keys())
1093+
if (lifetimes.size > MAX_RETAINED_UPDATE_OWNERS) lifetimes.delete(id);
10691094
unsubscribeProvider = next.capability.subscribe(notify);
10701095
notify();
10711096
return () => {

0 commit comments

Comments
 (0)