@remit/imap-worker 0.0.67 → 0.0.69

package/src/handlers/message-move.ts

@@ -1,5 +1,5 @@
 import { getClient } from "@remit/backend/client";
-import type { ThreadMessageItem } from "@remit/data-ports";
+import type { MessageItem, ThreadMessageItem } from "@remit/data-ports";
 import { MessageSyncStatus } from "@remit/domain-enums";
 import type { Logger } from "@remit/logger-lambda";
 import { recordImapFailure } from "@remit/logger-lambda";
@@ -19,6 +19,7 @@ import { isNotFoundError } from "../is-not-found.js";
 import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
 import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
 import { resolveExhaustedMessageMoveFailure } from "./message-move-terminal.js";
+import { restoreSourcePlacement } from "./restore-source-placement.js";
 
 export const getMessageMoveMaxAttempts = (
 	processEnv: NodeJS.ProcessEnv = process.env,
@@ -52,6 +53,18 @@ export const emitMoveResync = async (
 	);
 };
 
+/**
+ * The one-folder half of {@link emitMoveResync}, for a mutation that has no
+ * destination — a permanent delete removed local rows the server still holds,
+ * and only a resync of that folder puts them back.
+ */
+export const emitMailboxResync = async (
+	emit: EmitSyncMessages,
+	params: { accountId: string; mailboxId: string },
+): Promise<void> => {
+	await emit({ type: "SYNC_MESSAGES", ...params });
+};
+
 /**
  * SEARCH a mailbox for copies of a message identified by its RFC822 Message-ID
  * header and answer the HIGHEST matching uid. Read-only (EXAMINE, not SELECT) —
@@ -87,6 +100,79 @@ export const searchMailboxForHighestMessageIdUid = async (
 	return uids.reduce((highest, uid) => (uid > highest ? uid : highest));
 };
 
+/**
+ * Which side of a paused mutation the server actually holds the message on.
+ * `gone` is an answer both folders gave; `unprobeable` is the row that carries
+ * no Message-ID header, where the server was never asked and its silence says
+ * nothing.
+ */
+export type PausedPlacement =
+	| { kind: "at-source" }
+	| { kind: "at-destination"; uid: number }
+	| { kind: "gone" }
+	| { kind: "unprobeable" };
+
+/**
+ * Ask the server, by Message-ID, which folder holds a message whose mutation a
+ * paused cursor interrupted (issue #1203).
+ *
+ * Reached only on a redelivery, where "the command never left" has stopped
+ * being provable: the earlier attempt's tagged OK can be lost with the
+ * connection, so restoring the source pair on that assumption would write a
+ * settled placement naming a folder the server has already moved the mail out
+ * of. `message-copy.ts` asks the same question for the same reason.
+ *
+ * The SOURCE is asked first and a hit ends it, the gate `confirmTrashMoveUid`
+ * documents (#1122): where the mutation never ran, every hit at the destination
+ * is an older copy of the same Message-ID — a sieve `fileinto` + `keep`, a
+ * multi-label store, a resend — that `deriveMessageId` folds into this one local
+ * row, and binding to it hands a later delete somebody else's uid.
+ *
+ * The source's silence, however, is not the mirror image of its hit. Every
+ * caller here reaches this on a paused cursor, which means the source's
+ * UIDVALIDITY has moved and the folder may have been recreated holding nothing
+ * it held before — so "not at the source" is an answer about the folder, not
+ * about our mutation, and `at-destination` is a sighting rather than a
+ * confirmation. Callers settle it as unproven; see `settlePausedMove`.
+ *
+ * Identity, not position, is what makes this askable at all: a paused cursor
+ * means the source's UIDVALIDITY has moved, so every stored uid for it names
+ * something else, but a SEARCH by header is independent of the axis and answers
+ * the same question the cursor rebuild itself matches rows by. For that reason
+ * the caller passes the UNGUARDED connection — a `guardConnectionCursor` wrap
+ * refuses to open the mailbox at all, and it is bound to the source's snapshot
+ * anyway, so opening the destination through it would trip that mailbox too.
+ */
+export const probePausedPlacement = async (
+	connection: IImapConnection,
+	input: {
+		messageIdHeader: string | undefined;
+		sourceMailboxPath: string;
+		destinationMailboxPath: string | undefined;
+	},
+): Promise<PausedPlacement> => {
+	const { messageIdHeader, sourceMailboxPath, destinationMailboxPath } = input;
+	if (!messageIdHeader) return { kind: "unprobeable" };
+
+	const atSource = await searchMailboxForHighestMessageIdUid(
+		connection,
+		sourceMailboxPath,
+		messageIdHeader,
+	);
+	if (atSource !== null) return { kind: "at-source" };
+
+	if (!destinationMailboxPath) return { kind: "gone" };
+
+	const atDestination = await searchMailboxForHighestMessageIdUid(
+		connection,
+		destinationMailboxPath,
+		messageIdHeader,
+	);
+	return atDestination === null
+		? { kind: "gone" }
+		: { kind: "at-destination", uid: atDestination };
+};
+
 /**
  * Resync the affected folders only once the IMAP move has resolved. A move that
  * fails (or is retried) must not refresh counts off a move that didn't happen,
@@ -140,6 +226,22 @@ export const buildThreadMessageMoveUpdate = (
 	},
 });
 
+export interface MessageMoveDeps {
+	getClient: typeof getClient;
+	buildLifecycleDeps: typeof buildLifecycleDeps;
+	withOAuthLifecycle: typeof withOAuthLifecycle;
+	createConnectionScope: typeof createConnectionScopeWithCredentials;
+	emitEvent: typeof emitEvent;
+}
+
+const defaultDeps: MessageMoveDeps = {
+	getClient,
+	buildLifecycleDeps,
+	withOAuthLifecycle,
+	createConnectionScope: createConnectionScopeWithCredentials,
+	emitEvent,
+};
+
 /**
  * Handle MESSAGE_MOVE events.
  * Executes IMAP MOVE command and updates local state with new UID.
@@ -155,7 +257,16 @@ export const handleMessageMove = async (
 	event: MessageMoveEvent,
 	log: Logger,
 	receiveCount = 1,
+	deps: MessageMoveDeps = defaultDeps,
 ): Promise<void> => {
+	const {
+		getClient,
+		buildLifecycleDeps,
+		withOAuthLifecycle,
+		createConnectionScope: createConnectionScopeWithCredentials,
+		emitEvent,
+	} = deps;
+
 	const {
 		account: accountService,
 		message: messageService,
@@ -244,18 +355,190 @@ export const handleMessageMove = async (
 				return;
 			}
 
+			const settleMoved = async (newUid: number): Promise<void> => {
+				await messageService.updateUid(messageId, newUid, destinationMailboxId);
+
+				const threadMessage = await threadMessageService.findByMessageId(
+					account.accountConfigId,
+					messageId,
+				);
+				if (threadMessage) {
+					const args = buildThreadMessageMoveUpdate(
+						threadMessage,
+						newUid,
+						destinationMailboxId,
+					);
+					await threadMessageService.update(
+						threadMessage.accountConfigId,
+						threadMessage.threadMessageId,
+						args.set,
+						{ composites: args.composites },
+					);
+				}
+
+				log.info(
+					{
+						messageId,
+						oldUid: uid,
+						newUid,
+						destination: destinationMailboxPath,
+					},
+					"Message moved successfully",
+				);
+			};
+
+			/**
+			 * Put the row back on the pair it was moved off, and say so once.
+			 *
+			 * `metric` is the routine give-up the guard doc calls never-a-fault:
+			 * the user's move was silently dropped, which is worth counting and
+			 * not worth waking anyone for. `alert` is the give-up the server did
+			 * not settle — the row carries `failed` and an operator adjudicates.
+			 */
+			const handBackToSource = async (
+				syncStatus: MessageItem["syncStatus"],
+				signal: { alert: string } | { metric: string },
+				reason: string,
+			): Promise<void> => {
+				const context = {
+					...signal,
+					accountId,
+					messageId,
+					uid,
+					sourceMailboxPath,
+					destinationMailboxPath,
+					receiveCount,
+					reason,
+				};
+				if ("alert" in signal) {
+					log.error(
+						context,
+						"Move given up without a settled placement; row handed back to its source for adjudication",
+					);
+				} else {
+					log.warn(
+						context,
+						"Move not pushed to the server; row handed back to its source",
+					);
+				}
+
+				await restoreSourcePlacement(
+					{ messageService, threadMessageService },
+					{
+						accountConfigId: account.accountConfigId,
+						messageId,
+						sourceMailboxId,
+						uid,
+						syncStatus,
+					},
+				);
+			};
+
+			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,
+				);
+
+			// A paused cursor is never acked on the optimistic row: `updateForMove`
+			// has pointed it at the destination while `uid` still names the source,
+			// and that pair strands the row for good — the cursor rebuild matches
+			// rows by `(accountConfigId, mailboxId)`, so a row naming the
+			// destination is in neither folder's set, and nothing re-enqueues a
+			// MESSAGE_MOVE (issue #1203).
+			//
+			// This move 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 below
+			// plus the source's own cursor rebuild are its repair path.
+			//
+			// Putting the row back is an undo of this product's own write only where
+			// the MOVE provably never left. `commandIssued` says what this round
+			// did; `receiveCount` adds what an earlier one may have done and lost
+			// with its connection. Inferring the first from the second is what
+			// `settlePausedDelete` got wrong — attempt 1 reaches an exhausted settle
+			// too, with the MOVE already issued.
+			const settlePausedMove = async (
+				commandIssued: boolean,
+			): Promise<void> => {
+				const mayHaveIssued = commandIssued || receiveCount > 1;
+
+				const placement: PausedPlacement = mayHaveIssued
+					? await probePausedPlacement(await scope.getConnection(), {
+							messageIdHeader: message.messageIdHeader,
+							sourceMailboxPath,
+							destinationMailboxPath,
+						})
+					: { kind: "at-source" };
+
+				// A sighting at the destination is not proof this move 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 that `deriveMessageId` folds
+				// into this row — settling `moved` on it points the row at mail a
+				// later permanent delete would expunge. `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) the
+				// destination — not paused, no rebuild coming — does not have.
+				const unproven =
+					placement.kind === "at-destination" ||
+					placement.kind === "unprobeable";
+
+				if (unproven) {
+					await handBackToSource(
+						MessageSyncStatus.failed,
+						{ alert: "message_move_paused_placement_unproven" },
+						placement.kind === "at-destination"
+							? "destination holds this Message-ID but the source's uid axis has moved, so the sighting does not prove this move 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 handBackToSource(
+						MessageSyncStatus.synced,
+						{ metric: "message_move_dropped_on_pause" },
+						`source mailbox cursor paused, placement ${placement.kind}`,
+					);
+				}
+
+				await emitMoveResync(emitEvent, {
+					accountId,
+					sourceMailboxId,
+					destinationMailboxId,
+				});
+			};
+
 			// 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: sourceMailboxId },
-					"Mailbox cursor not normal; pausing outbound move this round",
+					"Mailbox cursor not normal; pausing outbound move this round and settling the row against the server",
 				);
+				await settlePausedMove(false).finally(() => scope.disconnect());
 				return;
 			}
 
-			const scope = createConnectionScopeWithCredentials(account, credentials);
+			// Flipped the instant the MOVE leaves, so every settle downstream of it
+			// knows the server was asked.
+			let commandIssued = false;
 
 			await scope
 				.getConnection()
@@ -275,6 +558,7 @@ export const handleMessageMove = async (
 							await connection.openBox(sourceMailboxPath, false);
 
 							// Execute IMAP MOVE
+							commandIssued = true;
 							const result = await connection.moveMessages(
 								[uid],
 								destinationMailboxPath,
@@ -304,41 +588,7 @@ export const handleMessageMove = async (
 								);
 							}
 
-							// Update message with new UID
-							await messageService.updateUid(
-								messageId,
-								newUid,
-								destinationMailboxId,
-							);
-
-							// Update ThreadMessage UID and mailboxId
-							const threadMessage = await threadMessageService.findByMessageId(
-								account.accountConfigId,
-								messageId,
-							);
-							if (threadMessage) {
-								const args = buildThreadMessageMoveUpdate(
-									threadMessage,
-									newUid,
-									destinationMailboxId,
-								);
-								await threadMessageService.update(
-									threadMessage.accountConfigId,
-									threadMessage.threadMessageId,
-									args.set,
-									{ composites: args.composites },
-								);
-							}
-
-							log.info(
-								{
-									messageId,
-									oldUid: uid,
-									newUid,
-									destination: destinationMailboxPath,
-								},
-								"Message moved successfully",
-							);
+							await settleMoved(newUid);
 						},
 						() =>
 							emitMoveResync(emitEvent, {
@@ -357,8 +607,9 @@ export const handleMessageMove = async (
 								mailboxId: sourceMailboxId,
 								cursorState: error.state,
 							},
-							"Mailbox cursor not normal; pausing outbound move this round",
+							"Mailbox cursor not normal; pausing outbound move this round and settling the row against the server",
 						);
+						await settlePausedMove(commandIssued);
 						return;
 					}
 
@@ -395,36 +646,64 @@ export const handleMessageMove = async (
 					// Redelivery budget exhausted: resolve into exactly one of the two
 					// terminal outcomes instead of dead-lettering with no diagnosis,
 					// and never by inferring the server's state from our own failures.
-					const { outcome } = await resolveExhaustedMessageMoveFailure(
+					const settled = await resolveExhaustedMessageMoveFailure(
 						{ messageService, threadMessageService, log },
 						{
 							accountId,
 							accountConfigId: account.accountConfigId,
 							messageId,
+							sourceMailboxId,
 							uid,
 							sourceMailboxPath,
-							getConnection: scope.getConnection,
+							getConnection: getGuardedConnection,
 						},
-					);
+					).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 this catch. The row is still settled, on the
+						// identity axis instead: `settlePausedMove` asks by Message-ID,
+						// which a UIDVALIDITY change does not invalidate.
+						if (settleError instanceof MailboxCursorPausedError) {
+							log.info(
+								{
+									accountId,
+									messageId,
+									mailboxId: sourceMailboxId,
+									cursorState: settleError.state,
+								},
+								"Mailbox cursor not normal; settling the exhausted move against the server by Message-ID",
+							);
+							await settlePausedMove(commandIssued);
+							return null;
+						}
+						throw settleError;
+					});
 
-					if (outcome === "reconciled") {
-						// Whichever folder the message actually sits in re-projects it
-						// with the server's own UID.
-						await emitMoveResync(emitEvent, {
-							accountId,
-							sourceMailboxId,
-							destinationMailboxId,
-						});
-						return;
+					if (!settled) return;
+
+					if (settled.outcome === "broken") {
+						// Terminal and never re-thrown, so the handler-outcome series
+						// records this record as a success. Counted here or it is
+						// invisible.
+						recordImapFailure("MESSAGE_MOVE_EXHAUSTED", "other");
+						log.error(
+							{ error: errorMessage },
+							"Message move retry exhausted; message still exists at its source",
+						);
 					}
 
-					// Terminal and never re-thrown, so the handler-outcome series
-					// records this record as a success. Counted here or it is invisible.
-					recordImapFailure("MESSAGE_MOVE_EXHAUSTED", "other");
-					log.error(
-						{ error: errorMessage },
-						"Message move retry exhausted; message still exists at its source",
-					);
+					// Both verdicts end in a row the server has contradicted, so this
+					// move reconciles rather than waits (R2). RECONCILED, the local rows
+					// are gone and whichever folder actually holds the message
+					// re-projects it with the server's own UID. 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.
+					await emitMoveResync(emitEvent, {
+						accountId,
+						sourceMailboxId,
+						destinationMailboxId,
+					});
 					// Terminal — never re-thrown, so the caller acks either way.
 				})
 				.finally(() => scope.disconnect());

package/src/handlers/restore-source-placement.ts

@@ -0,0 +1,135 @@
+import type {
+	IMessageRepository,
+	IThreadMessageRepository,
+	MessageItem,
+	ThreadMessageItem,
+} from "@remit/data-ports";
+import { MessageStatus } from "@remit/domain-enums";
+import { isNotFoundError } from "../is-not-found.js";
+import { buildThreadMessageMoveRevert } from "./thread-message-rows.js";
+
+export interface RestoreSourcePlacementDeps {
+	messageService: Pick<IMessageRepository, "updateForMove">;
+	threadMessageService: Pick<
+		IThreadMessageRepository,
+		"findAllByMessageId" | "update"
+	>;
+}
+
+export interface RestoreSourcePlacementInput {
+	accountConfigId: string;
+	messageId: string;
+	sourceMailboxId: string;
+	uid: number;
+	/**
+	 * What the row records about the mutation that will now never happen.
+	 * `synced` where the row is a faithful projection of the source again — the
+	 * server never received the command, or has just said the message is still
+	 * there. `failed` where the product refused an operation the user asked for,
+	 * which is a failure the row has to carry.
+	 */
+	syncStatus: MessageItem["syncStatus"];
+	/**
+	 * The listing rows, where the caller has already read them to pick this
+	 * outcome. Omitted, they are read here.
+	 */
+	threadMessages?: ThreadMessageItem[];
+}
+
+/**
+ * Put a row back on the pre-mutation source pair and hand its listing rows back
+ * with it.
+ *
+ * `status: moving` has to be cleared here or the row is stuck: a give-up that
+ * writes `syncStatus: failed` and returns leaves the row naming the destination
+ * with the source's uid — the pair `bindsForeignUid` calls a lie and
+ * `MessagePlacementUnsettledError` refuses to act on. Nothing routine repairs it
+ * (sync does not touch `status`, and the cursor rebuild's `updateUid` runs only
+ * on a UIDVALIDITY change), so the message is undeletable and unmovable for good
+ * (issue #1005).
+ *
+ * `updateForMove`, not `updateUid`: both write the same settled pair, but
+ * `updateUid` also appends a `message.moved` outbox row so the search index can
+ * refresh the mailbox it stores per message. Nothing here moved. The optimistic
+ * `updateForMove` that pointed the row at the destination never enqueued one
+ * either, so the index still holds the source and a revert has nothing to
+ * correct — the re-index would be a forced pass over an unchanged document.
+ *
+ * The caller must have evidence, not an inference: this writes a placement, and
+ * a placement written on a guess binds live mail to a uid that names somebody
+ * else's message. Two kinds of caller qualify, and nothing else does.
+ *
+ * A terminal resolver reaches here from {@link isMessageGoneFromOpenMailbox}
+ * answering that the message is STILL at `sourceMailboxId`/`uid`, which makes
+ * this the server's own answer rather than a revert on ambiguity (what PR #652
+ * was pulled for).
+ *
+ * A paused-cursor caller reaches here from a `MailboxCursorPausedError` the
+ * openBox guard threw before the outbound command was issued (issue #1203), and
+ * restores the pre-mutation pair off its own event. On a FIRST delivery that is
+ * not an inference but an undo: the command provably never left, so the row is
+ * put back exactly as it was found. A redelivery cannot claim that — the
+ * earlier attempt's tagged OK can be lost with the connection — so it asks
+ * `probePausedPlacement` which folder holds the message and only reaches here
+ * once the answer rules the destination out. Either way the source mailbox is
+ * by definition awaiting a cursor rebuild, which matches its rows by Message-ID
+ * and adjudicates the uid: handing the row back is what puts it in the set the
+ * rebuild walks, since a row still naming the destination is in neither
+ * folder's.
+ *
+ * A row another path deleted while the probe was in flight has nothing left to
+ * restore, and a thread row whose composites have moved on is being rewritten
+ * by that other path anyway. Both surface as `NotFoundError` — ElectroDB wraps
+ * the conditional-check miss as one — and both are settled states here, not
+ * faults. Throwing on them would escape the caller's `.catch()` and cost the
+ * record its ack and its resync, which is the contract the terminal resolvers
+ * state: never re-thrown.
+ */
+export const restoreSourcePlacement = async (
+	deps: RestoreSourcePlacementDeps,
+	input: RestoreSourcePlacementInput,
+): Promise<void> => {
+	const { accountConfigId, messageId, sourceMailboxId, uid, syncStatus } =
+		input;
+
+	const skipNotFound = (error: unknown): void => {
+		if (isNotFoundError(error)) return;
+		throw error;
+	};
+
+	const messageRestored = await deps.messageService
+		.updateForMove(messageId, {
+			mailboxId: sourceMailboxId,
+			uid,
+			status: MessageStatus.active,
+			syncStatus,
+		})
+		.then(() => true)
+		.catch((error: unknown) => {
+			skipNotFound(error);
+			return false;
+		});
+	if (!messageRestored) return;
+
+	const threadMessages =
+		input.threadMessages ??
+		(await deps.threadMessageService.findAllByMessageId(
+			accountConfigId,
+			messageId,
+		));
+	for (const threadMessage of threadMessages) {
+		const args = buildThreadMessageMoveRevert(
+			threadMessage,
+			uid,
+			sourceMailboxId,
+		);
+		await deps.threadMessageService
+			.update(
+				threadMessage.accountConfigId,
+				threadMessage.threadMessageId,
+				args.set,
+				{ composites: args.composites },
+			)
+			.catch(skipNotFound);
+	}
+};