@remit/imap-worker 0.0.1

package/src/handlers/message-move.ts

@@ -0,0 +1,298 @@
+import { getClient } from "@remit/backend/client";
+import type { ThreadMessageItem } from "@remit/data-ports";
+import { MessageStatus, MessageSyncStatus } from "@remit/domain-enums";
+import type { Logger } from "@remit/logger-lambda";
+import {
+	guardConnectionCursor,
+	isCursorRebuildNeeded,
+	MailboxCursorPausedError,
+} from "@remit/mailbox-service";
+import { isAccountDeleted } from "../account-check.js";
+import { createConnectionScopeWithCredentials } from "../connection-scope.js";
+import { emitEvent } from "../emit.js";
+import type { MessageMoveEvent, SyncMessagesEvent } from "../events.js";
+import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
+import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
+
+type EmitSyncMessages = (
+	event: Omit<SyncMessagesEvent, "eventId" | "timestamp">,
+) => Promise<unknown>;
+
+/**
+ * Re-read both folders' counts from IMAP after a move by enqueuing the existing
+ * per-folder SYNC_MESSAGES sync. Counts are a projection of IMAP, never mutated
+ * locally — the move shifted a message between source and destination, so both
+ * folders must refresh through the one-way pipeline.
+ */
+export const emitMoveResync = async (
+	emit: EmitSyncMessages,
+	params: {
+		accountId: string;
+		sourceMailboxId: string;
+		destinationMailboxId: string;
+	},
+): Promise<void> => {
+	const { accountId, sourceMailboxId, destinationMailboxId } = params;
+	await Promise.all(
+		[sourceMailboxId, destinationMailboxId].map((mailboxId) =>
+			emit({ type: "SYNC_MESSAGES", accountId, mailboxId }),
+		),
+	);
+};
+
+/**
+ * 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,
+ * so the resync is sequenced strictly after `performMove`.
+ */
+export const moveThenResync = async (
+	performMove: () => Promise<void>,
+	resync: () => Promise<void>,
+): Promise<void> => {
+	await performMove();
+	await resync();
+};
+
+/**
+ * Build the `set` and `composites` payload for the ThreadMessage update on a
+ * MESSAGE_MOVE.
+ *
+ * The CURRENT row state goes in `composites`; the NEW values go in `set`.
+ * ElectroDB uses `composites` to run the conditional check on the existing row
+ * AND to compute the previous sort-key values needed to recompute the new ones.
+ * Passing the NEW values in `composites` makes the conditional check fail with
+ * ConditionalCheckFailedException, which ElectroDB wraps as NotFoundError, and
+ * the caller silently drops the update. Same root cause as PR #186 fixed for
+ * `flag-queue.ts`.
+ */
+export const buildThreadMessageMoveUpdate = (
+	threadMessage: Pick<
+		ThreadMessageItem,
+		| "sentDate"
+		| "mailboxId"
+		| "isRead"
+		| "isDeleted"
+		| "hasStars"
+		| "hasAttachment"
+	>,
+	newUid: number,
+	destinationMailboxId: string,
+) => ({
+	set: {
+		uid: newUid,
+		mailboxId: destinationMailboxId,
+		isDeleted: false,
+	},
+	composites: {
+		sentDate: threadMessage.sentDate,
+		mailboxId: threadMessage.mailboxId,
+		isRead: threadMessage.isRead,
+		isDeleted: threadMessage.isDeleted,
+		hasStars: threadMessage.hasStars,
+		hasAttachment: threadMessage.hasAttachment,
+	},
+});
+
+/**
+ * Handle MESSAGE_MOVE events.
+ * Executes IMAP MOVE command and updates local state with new UID.
+ */
+export const handleMessageMove = async (
+	event: MessageMoveEvent,
+	log: Logger,
+): Promise<void> => {
+	const {
+		account: accountService,
+		message: messageService,
+		threadMessage: threadMessageService,
+		mailbox: mailboxService,
+		secrets,
+	} = await getClient();
+
+	const {
+		accountId,
+		messageId,
+		sourceMailboxId,
+		sourceMailboxPath,
+		destinationMailboxPath,
+		destinationMailboxId,
+		uid,
+	} = event;
+
+	log.info(
+		{
+			event: event.type,
+			accountId,
+			messageId,
+			from: sourceMailboxPath,
+			to: destinationMailboxPath,
+		},
+		"Handling event",
+	);
+
+	const account = await accountService.get(accountId);
+	if (!account) {
+		throw new Error(`Account ${accountId} not found`);
+	}
+
+	if (isAccountDeleted(account, log)) {
+		return;
+	}
+
+	await withOAuthLifecycle(
+		buildLifecycleDeps(secrets, accountService),
+		account,
+		log,
+		async (credentials) => {
+			const mailbox = await mailboxService.get(accountId, sourceMailboxId);
+
+			// 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: sourceMailboxId },
+					"Mailbox cursor not normal; pausing outbound move this round",
+				);
+				return;
+			}
+
+			const scope = createConnectionScopeWithCredentials(account, credentials);
+
+			await scope
+				.getConnection()
+				.then((rawConnection) => {
+					// Guard at the openBox choke point (epic #1281 invariants 3 & 5):
+					// a fresh mismatch trips the mailbox and throws once the SELECT
+					// reveals it. The move stays applied locally either way.
+					const connection = guardConnectionCursor(
+						rawConnection,
+						{ mailboxService },
+						accountId,
+						mailbox,
+					);
+					return moveThenResync(
+						async () => {
+							// Open source mailbox (not read-only)
+							await connection.openBox(sourceMailboxPath, false);
+
+							// Execute IMAP MOVE
+							const result = await connection.moveMessages(
+								[uid],
+								destinationMailboxPath,
+							);
+
+							// Get new UID from COPYUID response
+							const newUid = result.uidMap.get(uid);
+
+							if (newUid) {
+								// 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",
+								);
+							} else {
+								// Message may have been deleted on server
+								log.error(
+									{ messageId, uid },
+									"Message not found in COPYUID response - may have been deleted",
+								);
+								await messageService.update(messageId, {
+									syncStatus: MessageSyncStatus.failed,
+								});
+							}
+						},
+						() =>
+							emitMoveResync(emitEvent, {
+								accountId,
+								sourceMailboxId,
+								destinationMailboxId,
+							}),
+					);
+				})
+				.catch(async (error: unknown) => {
+					if (error instanceof MailboxCursorPausedError) {
+						log.info(
+							{
+								accountId,
+								messageId,
+								mailboxId: sourceMailboxId,
+								cursorState: error.state,
+							},
+							"Mailbox cursor not normal; pausing outbound move this round",
+						);
+						return;
+					}
+
+					const errorMessage =
+						error instanceof Error ? error.message : String(error);
+
+					// Handle TRYCREATE - destination doesn't exist
+					if (errorMessage.includes("TRYCREATE")) {
+						log.info(
+							{ destinationMailboxPath },
+							"Destination mailbox doesn't exist, creating",
+						);
+						const connection = await scope.getConnection();
+						await connection.createMailbox(destinationMailboxPath);
+						// Re-throw to let the event be retried
+						throw error;
+					}
+
+					// Handle message not found on IMAP - already moved/deleted (idempotent)
+					if (
+						errorMessage.includes("not found") ||
+						errorMessage.includes("NONEXISTENT")
+					) {
+						log.info(
+							{ messageId, uid },
+							"Message not found on IMAP, updating local state as synced",
+						);
+						await messageService.update(messageId, {
+							status: MessageStatus.active,
+							syncStatus: MessageSyncStatus.synced,
+						});
+						return;
+					}
+
+					// Mark as failed for other errors
+					await messageService.update(messageId, {
+						syncStatus: MessageSyncStatus.failed,
+					});
+					throw error;
+				})
+				.finally(() => scope.disconnect());
+		},
+	);
+};

package/src/handlers/placement-move-push.test.ts

@@ -0,0 +1,234 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { IImapConnection } from "@remit/mailbox-service";
+import {
+	attemptMove,
+	getPlacementMoveMaxAttempts,
+	PLACEMENT_MOVE_MAX_ATTEMPTS,
+} from "./placement-move-push.js";
+
+const buildConnection = (opts: {
+	uidMap?: Map<number, number>;
+	moveError?: Error;
+	/** Message-ID search hits in the destination mailbox — the verification probe. */
+	destinationSearchUids?: number[];
+	/** Whether the uid is still found via fetchMessages on the source mailbox. */
+	stillAtSource?: boolean;
+}): IImapConnection =>
+	({
+		openBox: async () => ({}) as never,
+		moveMessages: async (_uids: number[], destination: string) => {
+			if (opts.moveError) throw opts.moveError;
+			return {
+				destination,
+				uidValidity: 1,
+				uidMap: opts.uidMap ?? new Map(),
+			};
+		},
+		search: async (_criteria: unknown[]) => opts.destinationSearchUids ?? [],
+		fetchMessages: async (uids: number[]) =>
+			opts.stillAtSource
+				? uids.map((uid) => ({ uid }) as unknown as never)
+				: [],
+	}) as unknown as IImapConnection;
+
+const MESSAGE_ID_HEADER = "<abc@example.com>";
+
+describe("attemptMove — the IMAP push (issue #1271)", () => {
+	// Tests use the SAME fake connection for both the source and destination
+	// params — attemptMove treats them as independent handles (real cursor
+	// guarding per mailbox is #1272's `guardConnectionCursor`, tested in
+	// remit-mailbox-service; not re-tested here).
+	it("moved: returns the new uid from the COPYUID map", async () => {
+		const connection = buildConnection({ uidMap: new Map([[42, 99]]) });
+
+		const outcome = await attemptMove(
+			connection,
+			connection,
+			"Junk",
+			"INBOX",
+			42,
+			MESSAGE_ID_HEADER,
+		);
+
+		assert.equal(outcome.kind, "moved");
+		assert.equal(outcome.newUid, 99);
+	});
+
+	it("trycreate: the destination mailbox does not exist yet", async () => {
+		const connection = buildConnection({
+			moveError: new Error("Command failed: TRYCREATE"),
+		});
+
+		const outcome = await attemptMove(
+			connection,
+			connection,
+			"Junk",
+			"NewLabel",
+			42,
+			MESSAGE_ID_HEADER,
+		);
+
+		assert.equal(outcome.kind, "trycreate");
+	});
+
+	it("propagates any other error untouched (transient/infra failure, retried by the caller)", async () => {
+		const connection = buildConnection({
+			moveError: new Error("ECONNRESET"),
+		});
+
+		await assert.rejects(
+			() =>
+				attemptMove(
+					connection,
+					connection,
+					"Junk",
+					"INBOX",
+					42,
+					MESSAGE_ID_HEADER,
+				),
+			/ECONNRESET/,
+		);
+	});
+
+	describe("no COPYUID entry / explicit not-found — never trust either without verification (PR #1289 review finding 2)", () => {
+		it("moved: no COPYUID entry, but a Message-ID search finds it at the destination (non-UIDPLUS server, genuine success)", async () => {
+			const connection = buildConnection({
+				uidMap: new Map(),
+				destinationSearchUids: [77],
+			});
+
+			const outcome = await attemptMove(
+				connection,
+				connection,
+				"Junk",
+				"INBOX",
+				42,
+				MESSAGE_ID_HEADER,
+			);
+
+			assert.equal(outcome.kind, "moved");
+			assert.equal(outcome.newUid, 77);
+		});
+
+		it("moved: explicit NONEXISTENT error, but a Message-ID search finds it at the destination", async () => {
+			const connection = buildConnection({
+				moveError: new Error("Command failed: NONEXISTENT no such message"),
+				destinationSearchUids: [77],
+			});
+
+			const outcome = await attemptMove(
+				connection,
+				connection,
+				"Junk",
+				"INBOX",
+				42,
+				MESSAGE_ID_HEADER,
+			);
+
+			assert.equal(outcome.kind, "moved");
+			assert.equal(outcome.newUid, 77);
+		});
+
+		it("throws (never deletes) when unconfirmed at the destination but STILL present at the source", async () => {
+			const connection = buildConnection({
+				uidMap: new Map(),
+				destinationSearchUids: [],
+				stillAtSource: true,
+			});
+
+			await assert.rejects(
+				() =>
+					attemptMove(
+						connection,
+						connection,
+						"Junk",
+						"INBOX",
+						42,
+						MESSAGE_ID_HEADER,
+					),
+				/unresolved/,
+			);
+		});
+
+		it("not-found: confirmed absent from BOTH destination (search miss) AND source (fetch miss)", async () => {
+			const connection = buildConnection({
+				uidMap: new Map(),
+				destinationSearchUids: [],
+				stillAtSource: false,
+			});
+
+			const outcome = await attemptMove(
+				connection,
+				connection,
+				"Junk",
+				"INBOX",
+				42,
+				MESSAGE_ID_HEADER,
+			);
+
+			assert.equal(outcome.kind, "not-found");
+		});
+
+		it("no messageIdHeader to verify with: falls back to the source-presence check alone — still never deletes while present at source", async () => {
+			const connection = buildConnection({
+				uidMap: new Map(),
+				stillAtSource: true,
+			});
+
+			await assert.rejects(() =>
+				attemptMove(connection, connection, "Junk", "INBOX", 42, undefined),
+			);
+		});
+
+		it("no messageIdHeader to verify with: resolves not-found once confirmed absent from source", async () => {
+			const connection = buildConnection({
+				uidMap: new Map(),
+				stillAtSource: false,
+			});
+
+			const outcome = await attemptMove(
+				connection,
+				connection,
+				"Junk",
+				"INBOX",
+				42,
+				undefined,
+			);
+
+			assert.equal(outcome.kind, "not-found");
+		});
+	});
+});
+
+describe("getPlacementMoveMaxAttempts — env-derived threshold (mirrors #1270's getBodySyncMaxAttempts)", () => {
+	it("parses the CDK-injected env var", () => {
+		assert.equal(
+			getPlacementMoveMaxAttempts({ PLACEMENT_MOVE_MAX_ATTEMPTS: "3" }),
+			3,
+		);
+		assert.equal(
+			getPlacementMoveMaxAttempts({ PLACEMENT_MOVE_MAX_ATTEMPTS: "5" }),
+			5,
+		);
+	});
+
+	it("defaults to 3 when unset", () => {
+		assert.equal(getPlacementMoveMaxAttempts({}), 3);
+	});
+
+	it("defaults to 3 on a non-numeric or non-positive value", () => {
+		assert.equal(
+			getPlacementMoveMaxAttempts({ PLACEMENT_MOVE_MAX_ATTEMPTS: "nope" }),
+			3,
+		);
+		assert.equal(
+			getPlacementMoveMaxAttempts({ PLACEMENT_MOVE_MAX_ATTEMPTS: "0" }),
+			3,
+		);
+	});
+
+	it("PLACEMENT_MOVE_MAX_ATTEMPTS is a concrete, positive number at module load", () => {
+		assert.ok(PLACEMENT_MOVE_MAX_ATTEMPTS > 0);
+	});
+});