@remit/imap-worker 0.0.67 → 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,13 +323,95 @@ 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 { outcome } = await resolveExhaustedMessageDeleteFailure(
+		const settled = await resolveExhaustedMessageDeleteFailure(
 			{ messageService, threadMessageService, log },
 			{
 				accountId,
@@ -270,9 +422,27 @@ export const handleMessageDelete = async (
 				sourceMailboxPath: mailboxPath,
 				getConnection,
 			},
-		);
+		).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; settling the exhausted delete against the server by Message-ID",
+				);
+				await settlePaused();
+				return null;
+			}
+			throw settleError;
+		});
+
+		if (!settled) return;
 
-		if (outcome === "broken") {
+		if (settled.outcome === "broken") {
 			recordImapFailure("MESSAGE_DELETE_EXHAUSTED", "other");
 		}
 
@@ -282,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();
 	};
 
 	/**
@@ -301,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,
@@ -326,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;
 		}
 
@@ -367,19 +532,43 @@ export const handleMessageDelete = async (
 				return;
 			}
 
+			const scope = createConnectionScopeWithCredentials(account, credentials);
+
+			// The terminal resolver opens the source itself, and its answer now
+			// WRITES a placement, so it has to reach IMAP through the same
+			// UIDVALIDITY choke point every other outbound operation does. An
+			// unguarded probe on a folder that was deleted and recreated finds
+			// whatever the server has renumbered onto this uid, reads it as "still
+			// at source", and binds the row to a stranger the next permanent delete
+			// would expunge.
+			const getGuardedConnection = async (): Promise<IImapConnection> =>
+				guardConnectionCursor(
+					await scope.getConnection(),
+					{ mailboxService },
+					accountId,
+					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 even opens a connection. Optimization only — the
-			// guardConnectionCursor openBox wrap below is the structural guarantee.
+			// 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",
+					"Mailbox cursor not normal; pausing outbound delete this round and settling the row against the server",
 				);
+				await settlePaused(false).finally(() => scope.disconnect());
 				return;
 			}
 
-			const scope = createConnectionScopeWithCredentials(account, credentials);
-
 			await scope
 				.getConnection()
 				.then(async (rawConnection) => {
@@ -419,6 +608,7 @@ export const handleMessageDelete = async (
 						destinationMailboxId
 					) {
 						// Move to Trash
+						commandIssued = true;
 						const result = await connection.moveMessages(
 							[uid],
 							destinationMailboxPath,
@@ -456,44 +646,22 @@ 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;
 						}
 
 						await settleUnconfirmedTrashMove(
 							confirmation,
 							account.accountConfigId,
-							scope.getConnection,
+							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
@@ -520,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;
 					}
 
@@ -594,7 +763,8 @@ export const handleMessageDelete = async (
 					// failure this budget exists for.
 					await settleExhaustedDelete(
 						account.accountConfigId,
-						scope.getConnection,
+						getGuardedConnection,
+						() => settlePaused(commandIssued),
 					);
 					log.error(
 						{ accountId, messageId, uid, mailboxPath, error: errorMessage },