@remit/mailbox-service 0.0.111 → 0.0.113

package/src/placement-move-terminal.test.ts

@@ -1,300 +0,0 @@
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import type {
-	MessageItem,
-	PlacementPredicate,
-	PlacementTransitionInput,
-} from "@remit/data-ports";
-import {
-	MessageMutation,
-	MessageStatus,
-	MessageSyncStatus,
-} from "@remit/domain-enums";
-import type { PlacementMoveLogger } from "./placement-move.js";
-import {
-	type ResolveExhaustedPlacementMoveDeps,
-	resolveExhaustedPlacementMoveFailure,
-} from "./placement-move-terminal.js";
-import type { IImapConnection } from "./types.js";
-
-interface LogEntry {
-	obj: Record<string, unknown>;
-	msg: string;
-}
-
-interface Transition {
-	messageId: string;
-	expected: PlacementPredicate;
-	next: PlacementTransitionInput;
-}
-
-interface Recorder {
-	deps: ResolveExhaustedPlacementMoveDeps;
-	infos: LogEntry[];
-	errors: LogEntry[];
-	markerDeletes: string[];
-	deletedMessages: string[];
-	deletedThreadMessages: Array<{
-		accountConfigId: string;
-		threadMessageId: string;
-	}>;
-	transitions: Transition[];
-	threadUpdates: string[];
-}
-
-const buildRecorder = (
-	threadMessages: Array<{ accountConfigId: string; threadMessageId: string }>,
-	transitionWins = true,
-): Recorder => {
-	const infos: LogEntry[] = [];
-	const errors: LogEntry[] = [];
-	const markerDeletes: string[] = [];
-	const deletedMessages: string[] = [];
-	const deletedThreadMessages: Array<{
-		accountConfigId: string;
-		threadMessageId: string;
-	}> = [];
-	const transitions: Transition[] = [];
-	const threadUpdates: string[] = [];
-
-	const log: PlacementMoveLogger = {
-		info: (obj, msg) => infos.push({ obj, msg }),
-		error: (obj, msg) => errors.push({ obj, msg }),
-	};
-
-	const deps: ResolveExhaustedPlacementMoveDeps = {
-		markerService: {
-			delete: async (id: string) => {
-				markerDeletes.push(id);
-			},
-		},
-		messageService: {
-			delete: async (id: string) => {
-				deletedMessages.push(id);
-			},
-			transitionPlacement: async (
-				messageId: string,
-				expected: PlacementPredicate,
-				next: PlacementTransitionInput,
-			) => {
-				transitions.push({ messageId, expected, next });
-				return transitionWins ? ({ messageId } as MessageItem) : undefined;
-			},
-		},
-		threadMessageService: {
-			findAllByMessageId: async () => threadMessages as never,
-			deleteMany: async (
-				keys: Array<{ accountConfigId: string; threadMessageId: string }>,
-			) => {
-				deletedThreadMessages.push(...keys);
-			},
-			update: async (_accountConfigId: string, threadMessageId: string) => {
-				threadUpdates.push(threadMessageId);
-				return undefined as never;
-			},
-		},
-		log,
-	};
-
-	return {
-		deps,
-		infos,
-		errors,
-		markerDeletes,
-		deletedMessages,
-		deletedThreadMessages,
-		transitions,
-		threadUpdates,
-	};
-};
-
-const buildConnection = (
-	present: Set<number>,
-	fetchDrops: Set<number> = new Set(),
-): IImapConnection =>
-	({
-		openBox: async () => ({}) as never,
-		fetchMessages: async (uids: number[]) =>
-			uids
-				.filter((uid) => present.has(uid) && !fetchDrops.has(uid))
-				.map((uid) => ({ uid }) as unknown as never),
-		search: async (criteria: unknown[]) => {
-			const [, value] = (criteria as Array<[string, string]>)[0];
-			const uid = Number(value);
-			return present.has(uid) ? [uid] : [];
-		},
-	}) as unknown as IImapConnection;
-
-describe("resolveExhaustedPlacementMoveFailure — the two terminal outcomes (mirrors #1270 for placement moves)", () => {
-	it("RECONCILED (expected): the message is gone from its pending-move source — marker dropped, stale row reconciled, no alarm", async () => {
-		const rec = buildRecorder([
-			{ accountConfigId: "cfg-1", threadMessageId: "tm-msg-gone" },
-		]);
-
-		const result = await resolveExhaustedPlacementMoveFailure(rec.deps, {
-			accountId: "acc-1",
-			accountConfigId: "cfg-1",
-			messageId: "msg-gone",
-			uid: 101,
-			sourceMailboxId: "mbx-junk",
-			sourceMailboxPath: "Junk",
-			getConnection: async () => buildConnection(new Set()),
-		});
-
-		assert.equal(result.outcome, "reconciled");
-		assert.deepEqual(rec.markerDeletes, ["msg-gone"]);
-		assert.deepEqual(rec.deletedMessages, ["msg-gone"]);
-		assert.deepEqual(rec.deletedThreadMessages, [
-			{ accountConfigId: "cfg-1", threadMessageId: "tm-msg-gone" },
-		]);
-		assert.equal(
-			rec.errors.length,
-			0,
-			"no alarm for the expected/routine outcome",
-		);
-		assert.ok(
-			rec.infos.some(
-				(e) => e.obj.metric === "placement_move_stale_row_reconciled",
-			),
-		);
-	});
-
-	it("BROKEN: the message is still at the source — the row goes back to the source pair rather than being left `moving` forever", async () => {
-		const rec = buildRecorder([
-			{ accountConfigId: "cfg-1", threadMessageId: "tm-msg-broken" },
-		]);
-
-		const result = await resolveExhaustedPlacementMoveFailure(rec.deps, {
-			accountId: "acc-1",
-			accountConfigId: "cfg-1",
-			messageId: "msg-broken",
-			uid: 202,
-			sourceMailboxId: "mbx-inbox",
-			sourceMailboxPath: "INBOX",
-			getConnection: async () => buildConnection(new Set([202])),
-		});
-
-		assert.equal(result.outcome, "broken");
-		assert.deepEqual(rec.transitions, [
-			{
-				messageId: "msg-broken",
-				expected: {
-					status: [MessageStatus.moving, MessageStatus.deleting],
-				},
-				next: {
-					mailboxId: "mbx-inbox",
-					uid: 202,
-					status: MessageStatus.active,
-					syncStatus: MessageSyncStatus.synced,
-					// Remit's own classification filing, not something the user asked
-					// for, so no per-message give-up marker — the alert is the surface.
-					abandonedMutation: MessageMutation.none,
-				},
-			},
-		]);
-		assert.deepEqual(rec.threadUpdates, ["tm-msg-broken"]);
-		// The marker predicted a move that has now been given up on; leaving it
-		// would keep a folder-count prediction nothing will ever settle.
-		assert.deepEqual(rec.markerDeletes, ["msg-broken"]);
-		assert.deepEqual(rec.deletedMessages, []);
-		assert.ok(
-			rec.errors.some((e) => e.obj.alert === "placement_move_failed"),
-			"the operator signal is the alert, not a stuck row",
-		);
-	});
-
-	// The marker is the operator's evidence that this move still owed IMAP a
-	// push. Dropping it first meant a restore that threw left the row stuck
-	// `moving` with nothing left to say why.
-	it("BROKEN: a restore that throws leaves the marker standing", async () => {
-		const rec = buildRecorder([
-			{ accountConfigId: "cfg-1", threadMessageId: "tm-msg-broken" },
-		]);
-		rec.deps.messageService.transitionPlacement = async () => {
-			throw new Error("ProvisionedThroughputExceeded");
-		};
-
-		await assert.rejects(
-			() =>
-				resolveExhaustedPlacementMoveFailure(rec.deps, {
-					accountId: "acc-1",
-					accountConfigId: "cfg-1",
-					messageId: "msg-broken",
-					uid: 202,
-					sourceMailboxId: "mbx-inbox",
-					sourceMailboxPath: "INBOX",
-					getConnection: async () => buildConnection(new Set([202])),
-				}),
-			/ProvisionedThroughputExceeded/,
-		);
-
-		assert.deepEqual(
-			rec.markerDeletes,
-			[],
-			"the record of the owed push outlives a failed restore",
-		);
-	});
-
-	it("BROKEN with another lane already settled: the restore loses its predicate and writes nothing", async () => {
-		const rec = buildRecorder(
-			[{ accountConfigId: "cfg-1", threadMessageId: "tm-msg-raced" }],
-			false,
-		);
-
-		const result = await resolveExhaustedPlacementMoveFailure(rec.deps, {
-			accountId: "acc-1",
-			accountConfigId: "cfg-1",
-			messageId: "msg-raced",
-			uid: 404,
-			sourceMailboxId: "mbx-inbox",
-			sourceMailboxPath: "INBOX",
-			getConnection: async () => buildConnection(new Set([404])),
-		});
-
-		assert.equal(result.outcome, "broken");
-		assert.equal(rec.transitions.length, 1);
-		assert.deepEqual(
-			rec.threadUpdates,
-			[],
-			"a lost predicate leaves the listing rows to whoever won",
-		);
-	});
-
-	it("a dropped FETCH row is not absence: the message is still at the source — local rows survive", async () => {
-		const rec = buildRecorder([
-			{ accountConfigId: "cfg-1", threadMessageId: "tm-msg-live" },
-		]);
-
-		const result = await resolveExhaustedPlacementMoveFailure(rec.deps, {
-			accountId: "acc-1",
-			accountConfigId: "cfg-1",
-			messageId: "msg-live",
-			uid: 303,
-			sourceMailboxId: "mbx-inbox",
-			sourceMailboxPath: "INBOX",
-			getConnection: async () =>
-				buildConnection(new Set([303]), new Set([303])),
-		});
-
-		assert.equal(result.outcome, "broken");
-		assert.deepEqual(rec.deletedMessages, []);
-		assert.deepEqual(rec.deletedThreadMessages, []);
-		assert.ok(rec.errors.some((e) => e.obj.alert === "placement_move_failed"));
-	});
-
-	it("never throws — both outcomes are terminal, the caller always acks", async () => {
-		const rec = buildRecorder([]);
-
-		await assert.doesNotReject(() =>
-			resolveExhaustedPlacementMoveFailure(rec.deps, {
-				accountId: "acc-1",
-				accountConfigId: "cfg-1",
-				messageId: "msg-x",
-				uid: 1,
-				sourceMailboxId: "mbx-inbox",
-				sourceMailboxPath: "INBOX",
-				getConnection: async () => buildConnection(new Set([1])),
-			}),
-		);
-	});
-});

package/src/placement-move-terminal.ts

@@ -1,148 +0,0 @@
-import { MessageMutation, MessageSyncStatus } from "@remit/domain-enums";
-import { isMessageGoneFromOpenMailbox } from "./message-presence.js";
-import type { PlacementMoveLogger } from "./placement-move.js";
-import {
-	type RestoreSourcePlacementDeps,
-	restoreSourcePlacement,
-} from "./restore-source-placement.js";
-import {
-	reconcileStaleMessage,
-	type StaleMessageReconcileDeps,
-} from "./stale-message-reconcile.js";
-import type { IImapConnection } from "./types.js";
-
-export interface ResolveExhaustedPlacementMoveDeps {
-	messageService: StaleMessageReconcileDeps["messageService"] &
-		RestoreSourcePlacementDeps["messageService"];
-	threadMessageService: StaleMessageReconcileDeps["threadMessageService"] &
-		RestoreSourcePlacementDeps["threadMessageService"];
-	markerService: { delete(messageId: string): Promise<void> };
-	log: PlacementMoveLogger;
-}
-
-export interface ResolveExhaustedPlacementMoveInput {
-	accountId: string;
-	accountConfigId: string;
-	messageId: string;
-	uid: number;
-	sourceMailboxId: string;
-	sourceMailboxPath: string;
-	getConnection: () => Promise<IImapConnection>;
-}
-
-export type PlacementMoveTerminalOutcome = "reconciled" | "broken";
-
-export interface ResolveExhaustedPlacementMoveResult {
-	outcome: PlacementMoveTerminalOutcome;
-}
-
-/**
- * Resolve a PLACEMENT_MOVE_PUSH failure that has exhausted the placement-move
- * queue's redelivery budget into exactly one of two terminal outcomes,
- * mirroring `resolveExhaustedBodySyncFailures` (#1270) for the same failure
- * taxonomy (epic #1281 invariant 3) — no third, softer outcome.
- *
- * 1. RECONCILED (expected) — the message no longer exists at its pending-move
- *    source on IMAP, confirmed by {@link isMessageGoneFromOpenMailbox} rather
- *    than by a FETCH coming back empty. Per invariant 2, an external delete
- *    supersedes the marker entirely: the marker is dropped and the stale
- *    Message/ThreadMessage rows are deleted via
- *    {@link reconcileStaleMessage}. This is also the
- *    outcome for the (rarer, functionally indistinguishable from here) case
- *    where a foreign client moved the message elsewhere — either way, our
- *    prediction no longer holds, and the marker cannot be honoured. Metric
- *    only, no alarm — routine.
- * 2. BROKEN — the message still exists at the source, but the move keeps
- *    failing. This indicates broken code or a broken account (issue #1271),
- *    not a transient blip. The row is put back on the source pair the server
- *    has just confirmed, exactly as the move and delete resolvers do, and the
- *    marker goes with it: an auto-file whose push gave up must not leave
- *    `moving` plus the destination folder plus the source's uid standing
- *    forever, because that pair refuses every later delete and move with a
- *    409, blocks the sighting repair, and nothing else clears it. The failure
- *    is an operator's to read, so it lives in the `alert`-shaped log entry and
- *    the alarm on it — not in a row the user's own mail is stuck behind.
- *    Never re-thrown (terminal — the caller acks either way, since retrying a
- *    stale or permanently-broken move can never succeed).
- *
- * An operator reading `placement_move_failed` should know one case where the
- * message is not actually at the source: a message another client expunged
- * mid-session can answer an empty FETCH while the server still lists its UID
- * in SEARCH, until it is allowed to send the untagged EXPUNGE. That message
- * lands in BROKEN, and BROKEN is terminal — the alert stands until someone
- * clears it, and the row goes back to a source the message may already have
- * left. The reverse mistake deletes live mail, so the cost is paid
- * deliberately: a stale alert over a row the next sync re-points is
- * recoverable, a deleted message is not.
- */
-export const resolveExhaustedPlacementMoveFailure = async (
-	deps: ResolveExhaustedPlacementMoveDeps,
-	input: ResolveExhaustedPlacementMoveInput,
-): Promise<ResolveExhaustedPlacementMoveResult> => {
-	const {
-		accountId,
-		accountConfigId,
-		messageId,
-		uid,
-		sourceMailboxId,
-		sourceMailboxPath,
-		getConnection,
-	} = input;
-
-	const connection = await getConnection();
-	await connection.openBox(sourceMailboxPath);
-
-	if (await isMessageGoneFromOpenMailbox(connection, uid)) {
-		await deps.markerService.delete(messageId);
-		const { threadMessagesDeleted } = await reconcileStaleMessage(
-			deps,
-			accountConfigId,
-			messageId,
-		);
-		deps.log.info(
-			{
-				metric: "placement_move_stale_row_reconciled",
-				accountId,
-				accountConfigId,
-				messageId,
-				uid,
-				sourceMailboxPath,
-				threadMessagesDeleted,
-			},
-			"Message no longer at its pending-move source after retry exhaustion (external delete or move); marker dropped, stale row reconciled",
-		);
-		return { outcome: "reconciled" };
-	}
-
-	// The row first, the marker second. The marker is the operator's evidence
-	// that this move still owed IMAP a push; dropping it before the restore
-	// means a restore that throws leaves the row stuck `moving` with nothing
-	// left to say why.
-	await restoreSourcePlacement(deps, {
-		accountConfigId,
-		messageId,
-		sourceMailboxId,
-		uid,
-		// No give-up marker: this move is Remit's own classification filing, not
-		// something the user asked for, so a per-message "your move failed" would
-		// report a failure against an intent nobody formed. The alert below is the
-		// whole surface, and it is an operator's.
-		syncStatus: MessageSyncStatus.synced,
-		abandonedMutation: MessageMutation.none,
-	});
-	await deps.markerService.delete(messageId);
-
-	deps.log.error(
-		{
-			alert: "placement_move_failed",
-			accountId,
-			accountConfigId,
-			messageId,
-			uid,
-			sourceMailboxId,
-			sourceMailboxPath,
-		},
-		"Placement move could not be pushed to IMAP after retry exhaustion; message still exists at its source — row restored to the source pair, marker dropped, alert left for operator investigation",
-	);
-	return { outcome: "broken" };
-};