@remit/imap-worker 0.0.68 → 0.0.69

package/src/handlers/message-delete.ts

@@ -2,9 +2,10 @@ import { getClient } from "@remit/backend/client";
 import type {
 	IMessageRepository,
 	IThreadMessageRepository,
+	MessageItem,
 } from "@remit/data-ports";
 import { isCurrentSchemaVersion } from "@remit/data-ports/mutation-events";
-import { MessageStatus, MessageSyncStatus } from "@remit/domain-enums";
+import { MessageSyncStatus } from "@remit/domain-enums";
 import type { Logger } from "@remit/logger-lambda";
 import { recordImapFailure } from "@remit/logger-lambda";
 import {
@@ -24,13 +25,14 @@ import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
 import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
 import { resolveExhaustedMessageDeleteFailure } from "./message-delete-terminal.js";
 import {
+	emitMailboxResync,
 	emitMoveResync,
+	type PausedPlacement,
+	probePausedPlacement,
 	searchMailboxForHighestMessageIdUid,
 } from "./message-move.js";
-import {
-	buildThreadMessageMoveRevert,
-	buildThreadMessageTrashUpdate,
-} from "./thread-message-rows.js";
+import { restoreSourcePlacement } from "./restore-source-placement.js";
+import { buildThreadMessageTrashUpdate } from "./thread-message-rows.js";
 
 export const getMessageDeleteMaxAttempts = (
 	processEnv: NodeJS.ProcessEnv = process.env,
@@ -194,6 +196,98 @@ export const handleMessageDelete = async (
 		return;
 	}
 
+	/**
+	 * Re-read the folders this delete touched. A move to trash has two; a
+	 * permanent delete has only the source, and it is owed one just as much —
+	 * the local rows are gone while the server copy survives, so with no resync
+	 * the mail is invisible until the next scheduled sync. SYNC_MESSAGES on a
+	 * mailbox whose cursor is not normal routes to the rebuild, which is what
+	 * re-projects the rows this handler removed (`message-sync.ts`).
+	 */
+	const emitSettleResync = async (): Promise<void> => {
+		if (destinationMailboxId) {
+			await emitMoveResync(emitEvent, {
+				accountId,
+				sourceMailboxId: mailboxId,
+				destinationMailboxId,
+			});
+			return;
+		}
+		await emitMailboxResync(emitEvent, { accountId, mailboxId });
+	};
+
+	/**
+	 * Undo the optimistic local delete, for every reason this handler has to
+	 * give one up, and say so exactly once. The verdict differs — a refused
+	 * event is a failure the row carries, a paused cursor is a mutation the
+	 * server never heard of — but the way back is one rule, and it is the
+	 * listing rows that pick it.
+	 *
+	 * Rows still there is the ordinary move to trash: the row goes back on the
+	 * source pair, which is also the set the cursor rebuild adjudicates.
+	 *
+	 * No rows left is a permanent delete, which drops them at enqueue; they are
+	 * denormalized off an envelope only the sync path shapes and cannot be
+	 * rebuilt from here, so restoring the Message alone would leave mail nothing
+	 * can list — the silent vanish rather than a visible failure. The local
+	 * removal finishes instead. Nothing was expunged, so the server copy
+	 * survives and the mailbox's own sync re-projects it.
+	 *
+	 * `alert` is a refusal or a placement the server never settled, both of
+	 * which an operator adjudicates. `metric` is the routine pause the guard doc
+	 * calls never-a-fault: the user's delete was silently dropped, worth
+	 * counting and not worth waking anyone for. Either way `localRowsRemoved`
+	 * keeps the disappearance of local mail visible.
+	 */
+	const handBackDelete = async (
+		syncStatus: MessageItem["syncStatus"],
+		signal: { alert: string } | { metric: string },
+		reason: string,
+	): Promise<void> => {
+		const threadMessages = await threadMessageService.findAllByMessageId(
+			account.accountConfigId,
+			messageId,
+		);
+		const localRowsRemoved = threadMessages.length === 0;
+
+		const context = {
+			...signal,
+			accountId,
+			messageId,
+			uid,
+			mailboxPath,
+			operation,
+			receiveCount,
+			reason,
+			localRowsRemoved,
+		};
+		const summary = localRowsRemoved
+			? "Delete given up with no listing rows left to restore; the local row was removed and the server copy was not expunged"
+			: "Delete given up; the row was handed back to its source pair";
+		if ("alert" in signal) {
+			log.error(context, summary);
+		} else {
+			log.warn(context, summary);
+		}
+
+		if (localRowsRemoved) {
+			await messageService.delete(messageId);
+			return;
+		}
+
+		await restoreSourcePlacement(
+			{ messageService, threadMessageService },
+			{
+				accountConfigId: account.accountConfigId,
+				messageId,
+				sourceMailboxId: mailboxId,
+				uid,
+				syncStatus,
+				threadMessages,
+			},
+		);
+	};
+
 	// Only an operation that explicitly says so destroys mail. The event is
 	// `JSON.parse`d and cast in the queue handler with no validation, so a
 	// missing, misspelled or future field must abandon the delete — the
@@ -201,51 +295,27 @@ export const handleMessageDelete = async (
 	// one that destroyed mail in the service, and an unrecoverable EXPUNGE is
 	// not a default. Abandoning hands the row back where the server still has
 	// it: an invisible `failed` on a row the user cannot see is the shape of
-	// the incident this whole change is about.
-	const abandonDelete = async (
-		reason: string,
-		alert: string,
+	// the incident this whole change is about. The row keeps `failed`, because
+	// the product refused something the user asked for.
+	const abandonDelete = (reason: string, alert: string): Promise<void> =>
+		handBackDelete(MessageSyncStatus.failed, { alert }, reason);
+
+	const settleTrashMoveConfirmed = async (
+		newUid: number,
+		trashMailboxId: string,
 	): Promise<void> => {
-		log.error(
-			{ alert, accountId, messageId, uid, mailboxPath, operation },
-			reason,
-		);
+		await messageService.updateUid(messageId, newUid, trashMailboxId);
 
-		const threadMessages = await threadMessageService.findAllByMessageId(
+		const threadMessage = await threadMessageService.findByMessageId(
 			account.accountConfigId,
 			messageId,
 		);
-
-		// A permanent delete removes the listing rows before it enqueues, and
-		// they cannot be rebuilt from here — the row is denormalized off an
-		// envelope only the sync path shapes. Restoring the Message alone would
-		// leave mail nothing can list, which is the silent vanish rather than a
-		// visible failure, so the local removal finishes instead. The server copy
-		// survives (nothing was expunged) and a full sync of the mailbox brings
-		// it back. Reachable only through the rollout window, where a v1 event
-		// carries no `schemaVersion`.
-		if (threadMessages.length === 0) {
-			log.error(
-				{
-					alert: "message_delete_abandoned_after_local_cleanup",
-					accountId,
-					messageId,
-					uid,
-					mailboxPath,
-				},
-				"Abandoned delete had no listing rows left to restore; the server copy was not expunged",
+		if (threadMessage) {
+			const args = buildThreadMessageTrashUpdate(
+				threadMessage,
+				newUid,
+				trashMailboxId,
 			);
-			await messageService.delete(messageId);
-			return;
-		}
-
-		await messageService.updateUid(messageId, uid, mailboxId);
-		await messageService.update(messageId, {
-			status: MessageStatus.active,
-			syncStatus: MessageSyncStatus.failed,
-		});
-		for (const threadMessage of threadMessages) {
-			const args = buildThreadMessageMoveRevert(threadMessage, uid, mailboxId);
 			await threadMessageService.update(
 				threadMessage.accountConfigId,
 				threadMessage.threadMessageId,
@@ -253,11 +323,93 @@ export const handleMessageDelete = async (
 				{ composites: args.composites },
 			);
 		}
+
+		log.info({ messageId, newUid }, "Message moved to trash");
+	};
+
+	/**
+	 * Settle the optimistic local delete when a paused cursor stops this round
+	 * from issuing it. Acking on the optimistic row strands it: nothing
+	 * re-enqueues a MESSAGE_DELETE, and the cursor rebuild matches rows by
+	 * `(accountConfigId, mailboxId)`, so it never even sees a move-to-trash row
+	 * that already names Trash (issue #1203).
+	 *
+	 * The delete therefore reconciles rather than waits (R2,
+	 * docs/architecture/imap-mutations.md): the row is settled onto whichever
+	 * pair the server can be shown to hold, and the resync plus the source's own
+	 * cursor rebuild are its repair path.
+	 *
+	 * Undoing the local write claims nothing about the server only where the
+	 * command provably never left. `commandIssued` says what this round did;
+	 * `receiveCount` adds what an earlier one may have done and lost with its
+	 * connection. `receiveCount === 1` alone is not that proof: an unprobeable
+	 * confirmation reaches {@link settleExhaustedDelete} on the first attempt,
+	 * with the MOVE already issued and the source already saying it no longer
+	 * holds the message. Where either says the server may have been asked, it is
+	 * asked again — {@link probePausedPlacement}, on the unguarded handle. A
+	 * permanent delete has nothing to ask: its answer is the same either way,
+	 * since the row is unlistable and goes.
+	 */
+	const settlePausedDelete = async (
+		getRawConnection: () => Promise<IImapConnection>,
+		commandIssued: boolean,
+	): Promise<void> => {
+		const mayHaveIssued = commandIssued || receiveCount > 1;
+		const isProbeableTrashMove =
+			mayHaveIssued &&
+			operation === "move_to_trash" &&
+			destinationMailboxId !== undefined &&
+			destinationMailboxPath !== undefined;
+
+		const placement: PausedPlacement = isProbeableTrashMove
+			? await probePausedPlacement(await getRawConnection(), {
+					messageIdHeader: (await messageService.get([messageId]))[0]
+						?.messageIdHeader,
+					sourceMailboxPath: mailboxPath,
+					destinationMailboxPath,
+				})
+			: { kind: "at-source" };
+
+		// A sighting in Trash is not proof this delete ran. The pause means the
+		// source's UIDVALIDITY has moved, so its "no" can be a recreated folder
+		// answering about mail it never held, and the hit can be an older copy of
+		// the same Message-ID — a sieve `fileinto` + `keep`, a resend — that
+		// `deriveMessageId` folds into this row; settling `moved` on it hands
+		// Empty Trash a stranger's uid. `unprobeable` is silence, and silence
+		// settles nothing either (the rule `message-copy.ts` already applies).
+		// Both hand the row back on the source pair carrying `failed`: that is the
+		// set the source's own cursor rebuild walks and adjudicates by Message-ID,
+		// which is the reconcile path (R2) Trash — not paused, no rebuild coming —
+		// does not have.
+		const unproven =
+			placement.kind === "at-destination" || placement.kind === "unprobeable";
+
+		if (unproven) {
+			await handBackDelete(
+				MessageSyncStatus.failed,
+				{ alert: "message_delete_paused_placement_unproven" },
+				placement.kind === "at-destination"
+					? "the destination holds this Message-ID but the source's uid axis has moved, so the sighting does not prove this delete ran"
+					: "no Message-ID header to ask either folder with",
+			);
+		} else {
+			// `gone` lands here with `at-source`: the source pair is the set the
+			// rebuild walks, and a row it cannot match against a fresh envelope
+			// snapshot is the one thing it reconciles away.
+			await handBackDelete(
+				MessageSyncStatus.synced,
+				{ metric: "message_delete_dropped_on_pause" },
+				`source mailbox cursor paused, placement ${placement.kind}`,
+			);
+		}
+
+		await emitSettleResync();
 	};
 
 	const settleExhaustedDelete = async (
 		accountConfigId: string,
 		getConnection: () => Promise<IImapConnection>,
+		settlePaused: () => Promise<void>,
 	): Promise<void> => {
 		const settled = await resolveExhaustedMessageDeleteFailure(
 			{ messageService, threadMessageService, log },
@@ -270,17 +422,19 @@ export const handleMessageDelete = async (
 				sourceMailboxPath: mailboxPath,
 				getConnection,
 			},
-		).catch((settleError: unknown) => {
-			// The guarded probe found a mailbox whose UIDVALIDITY has moved. Every
-			// stored uid for this folder now names something else, so there is
-			// nothing here that may be settled off them, and the pause is the
-			// routine skip `guardMailboxCursor` documents, not a fault to re-throw
-			// out of the caller's catch.
+		).catch(async (settleError: unknown) => {
+			// The guarded probe found a mailbox whose UIDVALIDITY has moved. Nothing
+			// may be settled off a uid on a dead axis, and the pause is the routine
+			// skip `guardMailboxCursor` documents, not a fault to re-throw out of
+			// the caller's catch. The delete is still settled, on the identity axis
+			// instead: the paused settle asks by Message-ID, which a UIDVALIDITY
+			// change does not invalidate.
 			if (settleError instanceof MailboxCursorPausedError) {
 				log.info(
 					{ accountId, messageId, mailboxId, cursorState: settleError.state },
-					"Mailbox cursor not normal; leaving the exhausted delete for the cursor rebuild",
+					"Mailbox cursor not normal; settling the exhausted delete against the server by Message-ID",
 				);
+				await settlePaused();
 				return null;
 			}
 			throw settleError;
@@ -298,13 +452,7 @@ export const handleMessageDelete = async (
 		// rows are gone and the resync rebuilds them. BROKEN, the row has just
 		// been put back at the source the server confirmed, and the resync is
 		// what carries any drift either folder has picked up since.
-		if (destinationMailboxId) {
-			await emitMoveResync(emitEvent, {
-				accountId,
-				sourceMailboxId: mailboxId,
-				destinationMailboxId,
-			});
-		}
+		await emitSettleResync();
 	};
 
 	/**
@@ -317,6 +465,7 @@ export const handleMessageDelete = async (
 		confirmation: Exclude<TrashMoveConfirmation, { outcome: "confirmed" }>,
 		accountConfigId: string,
 		getConnection: () => Promise<IImapConnection>,
+		settlePaused: () => Promise<void>,
 	): Promise<void> => {
 		const context = {
 			accountId,
@@ -342,7 +491,7 @@ export const handleMessageDelete = async (
 				context,
 				"Move to trash carries no Message-ID header to probe the destination with; settling on the source's answer alone",
 			);
-			await settleExhaustedDelete(accountConfigId, getConnection);
+			await settleExhaustedDelete(accountConfigId, getConnection, settlePaused);
 			return;
 		}
 
@@ -383,17 +532,6 @@ export const handleMessageDelete = async (
 				return;
 			}
 
-			// Cheap frugal skip (epic #1281 invariant 6): a mailbox already known
-			// paused never even opens a connection. Optimization only — the
-			// guardConnectionCursor openBox wrap below is the structural guarantee.
-			if (isCursorRebuildNeeded(mailbox.cursorState)) {
-				log.info(
-					{ accountId, messageId, mailboxId },
-					"Mailbox cursor not normal; pausing outbound delete this round",
-				);
-				return;
-			}
-
 			const scope = createConnectionScopeWithCredentials(account, credentials);
 
 			// The terminal resolver opens the source itself, and its answer now
@@ -411,6 +549,26 @@ export const handleMessageDelete = async (
 					mailbox,
 				);
 
+			const settlePaused = (commandIssued: boolean): Promise<void> =>
+				settlePausedDelete(scope.getConnection, commandIssued);
+
+			// Flipped the instant the MOVE or the EXPUNGE leaves, so every settle
+			// downstream of it knows the server was asked.
+			let commandIssued = false;
+
+			// Cheap frugal skip (epic #1281 invariant 6): a mailbox already known
+			// paused never opens a connection on a first delivery. Optimization
+			// only — the guardConnectionCursor openBox wrap below is the structural
+			// guarantee.
+			if (isCursorRebuildNeeded(mailbox.cursorState)) {
+				log.info(
+					{ accountId, messageId, mailboxId },
+					"Mailbox cursor not normal; pausing outbound delete this round and settling the row against the server",
+				);
+				await settlePaused(false).finally(() => scope.disconnect());
+				return;
+			}
+
 			await scope
 				.getConnection()
 				.then(async (rawConnection) => {
@@ -450,6 +608,7 @@ export const handleMessageDelete = async (
 						destinationMailboxId
 					) {
 						// Move to Trash
+						commandIssued = true;
 						const result = await connection.moveMessages(
 							[uid],
 							destinationMailboxPath,
@@ -487,34 +646,10 @@ export const handleMessageDelete = async (
 								});
 
 						if (confirmation.outcome === "confirmed") {
-							const newUid = confirmation.uid;
-							// Update message with new UID in Trash
-							await messageService.updateUid(
-								messageId,
-								newUid,
+							await settleTrashMoveConfirmed(
+								confirmation.uid,
 								destinationMailboxId,
 							);
-
-							// Update ThreadMessage with new UID and isDeleted = true
-							const threadMessage = await threadMessageService.findByMessageId(
-								account.accountConfigId,
-								messageId,
-							);
-							if (threadMessage) {
-								const args = buildThreadMessageTrashUpdate(
-									threadMessage,
-									newUid,
-									destinationMailboxId,
-								);
-								await threadMessageService.update(
-									threadMessage.accountConfigId,
-									threadMessage.threadMessageId,
-									args.set,
-									{ composites: args.composites },
-								);
-							}
-
-							log.info({ messageId, newUid }, "Message moved to trash");
 							return;
 						}
 
@@ -522,9 +657,11 @@ export const handleMessageDelete = async (
 							confirmation,
 							account.accountConfigId,
 							getGuardedConnection,
+							() => settlePaused(true),
 						);
 					} else {
 						// Permanent delete — reached only by `operation === "permanent_delete"`.
+						commandIssued = true;
 						await connection.deleteMessages([uid]);
 
 						// Delete ThreadMessage rows BEFORE the Message row to collapse the
@@ -551,8 +688,9 @@ export const handleMessageDelete = async (
 					if (error instanceof MailboxCursorPausedError) {
 						log.info(
 							{ accountId, messageId, mailboxId, cursorState: error.state },
-							"Mailbox cursor not normal; pausing outbound delete this round",
+							"Mailbox cursor not normal; pausing outbound delete this round and settling the row against the server",
 						);
+						await settlePaused(commandIssued);
 						return;
 					}
 
@@ -626,6 +764,7 @@ export const handleMessageDelete = async (
 					await settleExhaustedDelete(
 						account.accountConfigId,
 						getGuardedConnection,
+						() => settlePaused(commandIssued),
 					);
 					log.error(
 						{ accountId, messageId, uid, mailboxPath, error: errorMessage },

package/src/handlers/message-move-terminal.test.ts

@@ -75,8 +75,8 @@ interface ThreadRow {
  * The move's pending state IS the Message row, so these fakes hold real rows
  * and the assertions read the rows back — a resolver that settled the row on
  * anything but the server's own answer shows up here as a changed row, not as
- * an uncalled mock. `updateUid` writes what the repository writes: the settled
- * pair AND the `active`/`synced` that clears `moving`.
+ * an uncalled mock. `updateForMove` writes what the repository writes: whatever
+ * fields the caller set, and nothing it left out.
  */
 const buildRepositories = (row: MessageRow) => {
 	const messages = new Map<string, MessageRow>([[row.messageId, row]]);
@@ -104,22 +104,11 @@ const buildRepositories = (row: MessageRow) => {
 				const current = messages.get(messageId);
 				if (current) messages.set(messageId, { ...current, ...input });
 			},
-			updateUid: async (
-				messageId: string,
-				newUid: number,
-				newMailboxId: string,
-			) => {
+			updateForMove: async (messageId: string, set: Partial<MessageRow>) => {
 				const current = messages.get(messageId);
-				if (current)
-					messages.set(messageId, {
-						...current,
-						uid: newUid,
-						mailboxId: newMailboxId,
-						status: "active",
-						syncStatus: "synced",
-					});
+				if (current) messages.set(messageId, { ...current, ...set });
 			},
-		} as unknown as Pick<IMessageRepository, "delete" | "updateUid">,
+		} as unknown as Pick<IMessageRepository, "delete" | "updateForMove">,
 		threadMessageService: {
 			findAllByMessageId: async () => [...threadMessages.values()],
 			deleteMany: async (
@@ -215,10 +204,9 @@ describe("resolveExhaustedMessageMoveFailure — the two terminal outcomes (issu
 		assert.ok(errors.some((e) => e.obj.alert === "message_move_failed"));
 	});
 
-	// Issue #1005: only `updateUid` clears `moving`, so a give-up that returned
-	// without calling it left the row naming the destination with the source's
-	// uid — a pair `bindsForeignUid` refuses, which made the message
-	// undeletable and unmovable for good.
+	// Issue #1005: a give-up that never writes `status` leaves the row naming
+	// the destination with the source's uid — a pair `bindsForeignUid` refuses,
+	// which made the message undeletable and unmovable for good.
 	it("BROKEN: the settled row is no longer refused by the placement guard (#1005)", async () => {
 		const repos = buildRepositories(pendingMoveRow());
 		const { log } = buildLogger();
@@ -281,7 +269,7 @@ describe("resolveExhaustedMessageMoveFailure — the two terminal outcomes (issu
 		const deps: ResolveExhaustedMessageMoveDeps = {
 			messageService: {
 				...repos.messageService,
-				updateUid: async () => {
+				updateForMove: async () => {
 					throw notFound;
 				},
 			} as unknown as ResolveExhaustedMessageMoveDeps["messageService"],
@@ -332,7 +320,7 @@ describe("resolveExhaustedMessageMoveFailure — the two terminal outcomes (issu
 		const deps: ResolveExhaustedMessageMoveDeps = {
 			messageService: {
 				...repos.messageService,
-				updateUid: async () => {
+				updateForMove: async () => {
 					throw new Error("ProvisionedThroughputExceeded");
 				},
 			} as unknown as ResolveExhaustedMessageMoveDeps["messageService"],

package/src/handlers/message-move-terminal.ts

@@ -2,6 +2,7 @@ import type {
 	IMessageRepository,
 	IThreadMessageRepository,
 } from "@remit/data-ports";
+import { MessageSyncStatus } from "@remit/domain-enums";
 import {
 	type IImapConnection,
 	isMessageGoneFromOpenMailbox,
@@ -17,7 +18,7 @@ export interface MessageMoveTerminalLogger {
 
 export interface ResolveExhaustedMessageMoveDeps
 	extends StaleMessageReconcileDeps {
-	messageService: Pick<IMessageRepository, "delete" | "updateUid">;
+	messageService: Pick<IMessageRepository, "delete" | "updateForMove">;
 	threadMessageService: Pick<
 		IThreadMessageRepository,
 		"findAllByMessageId" | "deleteMany" | "update"
@@ -147,6 +148,10 @@ export const resolveExhaustedMessageMoveFailure = async (
 		messageId,
 		sourceMailboxId,
 		uid,
+		// The probe above just confirmed the pair, so the row is a faithful
+		// projection of the source again. The move's own failure is the alert, not
+		// a `failed` left on a row nothing is still trying to move.
+		syncStatus: MessageSyncStatus.synced,
 	});
 
 	return { outcome: "broken" };