@remit/imap-worker 0.0.1

package/src/handlers/mailbox-management.ts

@@ -0,0 +1,266 @@
+import { getClient } from "@remit/backend/client";
+import { MailboxSyncStatus } from "@remit/domain-enums";
+import type { Logger } from "@remit/logger-lambda";
+import { MailboxManagementService } from "@remit/mailbox-service";
+import { isAccountDeleted } from "../account-check.js";
+import { createConnectionScopeWithCredentials } from "../connection-scope.js";
+import type {
+	MailboxCreateEvent,
+	MailboxDeleteEvent,
+	MailboxManagementEvent,
+	MailboxRenameEvent,
+} from "../events.js";
+import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
+import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
+
+/**
+ * Handle MAILBOX_CREATE event
+ */
+const handleCreate = async (
+	event: MailboxCreateEvent,
+	log: Logger,
+): Promise<void> => {
+	const {
+		account: accountService,
+		mailbox: mailboxService,
+		secrets,
+	} = await getClient();
+
+	const { accountId, mailboxId, path, subscribe } = event;
+
+	log.info({ event: event.type, accountId, mailboxId, path }, "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 scope = createConnectionScopeWithCredentials(account, credentials);
+			const managementService = new MailboxManagementService(
+				mailboxService,
+				log,
+			);
+
+			await managementService
+				.syncCreate(accountId, mailboxId, path, scope.getConnection, subscribe)
+				.then((result) => {
+					if (result.success) {
+						log.info({ accountId, mailboxId, path }, "Mailbox created on IMAP");
+					} else {
+						log.error(
+							{ accountId, mailboxId, path, error: result.error },
+							"Failed to create mailbox on IMAP",
+						);
+					}
+				})
+				.catch(async (error) => {
+					// Check if mailbox already exists (idempotent)
+					if (
+						error instanceof Error &&
+						error.message.includes("already exists")
+					) {
+						log.info(
+							{ accountId, mailboxId, path },
+							"Mailbox already exists, marking as synced",
+						);
+						await mailboxService.update(accountId, mailboxId, {
+							syncStatus: MailboxSyncStatus.synced,
+						});
+					} else {
+						await mailboxService.update(accountId, mailboxId, {
+							syncStatus: MailboxSyncStatus.failed,
+						});
+						throw error;
+					}
+				})
+				.finally(() => scope.disconnect());
+		},
+	);
+};
+
+/**
+ * Handle MAILBOX_RENAME event
+ */
+const handleRename = async (
+	event: MailboxRenameEvent,
+	log: Logger,
+): Promise<void> => {
+	const {
+		account: accountService,
+		mailbox: mailboxService,
+		secrets,
+	} = await getClient();
+
+	const { accountId, mailboxId, oldPath, newPath } = event;
+
+	log.info(
+		{ event: event.type, accountId, mailboxId, oldPath, newPath },
+		"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 scope = createConnectionScopeWithCredentials(account, credentials);
+			const managementService = new MailboxManagementService(
+				mailboxService,
+				log,
+			);
+
+			await managementService
+				.syncRename(accountId, mailboxId, oldPath, newPath, scope.getConnection)
+				.then((result) => {
+					if (result.success) {
+						log.info(
+							{ accountId, mailboxId, oldPath, newPath },
+							"Mailbox renamed on IMAP",
+						);
+					} else {
+						log.error(
+							{ accountId, mailboxId, oldPath, newPath, error: result.error },
+							"Failed to rename mailbox on IMAP",
+						);
+					}
+				})
+				.catch(async (error) => {
+					// If source not found, delete local mailbox
+					if (error instanceof Error && error.message.includes("not found")) {
+						log.info(
+							{ accountId, mailboxId, oldPath },
+							"Source mailbox not found, deleting local",
+						);
+						await mailboxService.delete(accountId, mailboxId);
+					} else {
+						// Rollback local rename by restoring old path
+						await mailboxService.update(accountId, mailboxId, {
+							fullPath: oldPath,
+							oldPath: undefined,
+							syncStatus: MailboxSyncStatus.failed,
+						});
+						throw error;
+					}
+				})
+				.finally(() => scope.disconnect());
+		},
+	);
+};
+
+/**
+ * Handle MAILBOX_DELETE event
+ */
+const handleDelete = async (
+	event: MailboxDeleteEvent,
+	log: Logger,
+): Promise<void> => {
+	const {
+		account: accountService,
+		mailbox: mailboxService,
+		secrets,
+	} = await getClient();
+
+	const { accountId, mailboxId, path } = event;
+
+	log.info({ event: event.type, accountId, mailboxId, path }, "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 scope = createConnectionScopeWithCredentials(account, credentials);
+			const managementService = new MailboxManagementService(
+				mailboxService,
+				log,
+			);
+
+			await managementService
+				.syncDelete(accountId, mailboxId, path, scope.getConnection)
+				.then((result) => {
+					if (result.success) {
+						log.info({ accountId, mailboxId, path }, "Mailbox deleted on IMAP");
+					} else {
+						log.error(
+							{ accountId, mailboxId, path, error: result.error },
+							"Failed to delete mailbox on IMAP",
+						);
+					}
+				})
+				.catch(async (error) => {
+					// If mailbox not found, it's already deleted (idempotent)
+					if (error instanceof Error && error.message.includes("not found")) {
+						log.info(
+							{ accountId, mailboxId, path },
+							"Mailbox not found on IMAP, deleting local",
+						);
+						await mailboxService.delete(accountId, mailboxId);
+					} else if (
+						error instanceof Error &&
+						error.message.includes("Cannot delete INBOX")
+					) {
+						// Restore the mailbox
+						await mailboxService.update(accountId, mailboxId, {
+							syncStatus: MailboxSyncStatus.synced,
+						});
+						log.error(
+							{ accountId, mailboxId, path },
+							"Cannot delete INBOX, restoring mailbox",
+						);
+						// Don't rethrow - this is an expected error
+					} else {
+						// Restore the mailbox on other errors
+						await mailboxService.update(accountId, mailboxId, {
+							syncStatus: MailboxSyncStatus.failed,
+						});
+						throw error;
+					}
+				})
+				.finally(() => scope.disconnect());
+		},
+	);
+};
+
+/**
+ * Process mailbox management events
+ */
+export const processMailboxManagement = async (
+	event: MailboxManagementEvent,
+	log: Logger,
+): Promise<void> => {
+	switch (event.type) {
+		case "MAILBOX_CREATE":
+			return handleCreate(event, log);
+		case "MAILBOX_RENAME":
+			return handleRename(event, log);
+		case "MAILBOX_DELETE":
+			return handleDelete(event, log);
+	}
+};

package/src/handlers/mailbox-sync-order.test.ts

@@ -0,0 +1,93 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import { MailboxSpecialUse } from "@remit/domain-enums";
+import {
+	type MailboxSyncOrderEntry,
+	mailboxSyncPriority,
+	orderMailboxesForSync,
+} from "./mailbox-sync-order.js";
+
+const mailbox = (
+	fullPath: string,
+	specialUse?: readonly string[],
+): MailboxSyncOrderEntry => ({
+	mailboxId: `id-${fullPath}`,
+	fullPath,
+	specialUse,
+});
+
+describe("orderMailboxesForSync", () => {
+	it("orders INBOX first, Sent/Drafts next, Junk and Trash last", () => {
+		const mailboxes = [
+			mailbox("INBOX/Spam", [MailboxSpecialUse.Junk]),
+			mailbox("Trash", [MailboxSpecialUse.Trash]),
+			mailbox("Projects"),
+			mailbox("INBOX"),
+			mailbox("Sent", [MailboxSpecialUse.Sent]),
+			mailbox("Drafts", [MailboxSpecialUse.Drafts]),
+		];
+
+		const ordered = orderMailboxesForSync(mailboxes).map((m) => m.fullPath);
+
+		assert.deepStrictEqual(ordered, [
+			"INBOX",
+			"Sent",
+			"Drafts",
+			"Projects",
+			"INBOX/Spam",
+			"Trash",
+		]);
+	});
+
+	it("places INBOX ahead of an alphabetically-earlier Junk folder", () => {
+		const ordered = orderMailboxesForSync([
+			mailbox("Bulk", [MailboxSpecialUse.Junk]),
+			mailbox("INBOX"),
+		]).map((m) => m.fullPath);
+
+		assert.deepStrictEqual(ordered, ["INBOX", "Bulk"]);
+	});
+
+	it("is deterministic: ties break alphabetically by fullPath", () => {
+		const ordered = orderMailboxesForSync([
+			mailbox("Work"),
+			mailbox("Archive", [MailboxSpecialUse.Archive]),
+			mailbox("Newsletters"),
+		]).map((m) => m.fullPath);
+
+		assert.deepStrictEqual(ordered, ["Archive", "Newsletters", "Work"]);
+	});
+
+	it("does not mutate the input array", () => {
+		const input = [
+			mailbox("Trash", [MailboxSpecialUse.Trash]),
+			mailbox("INBOX"),
+		];
+		const before = input.map((m) => m.fullPath);
+		orderMailboxesForSync(input);
+		assert.deepStrictEqual(
+			input.map((m) => m.fullPath),
+			before,
+		);
+	});
+
+	it("treats INBOX case-insensitively", () => {
+		assert.strictEqual(mailboxSyncPriority(mailbox("inbox")), 0);
+		assert.strictEqual(mailboxSyncPriority(mailbox("Inbox")), 0);
+	});
+
+	it("de-prioritises a folder carrying both a leading and a Junk flag", () => {
+		assert.ok(
+			mailboxSyncPriority(
+				mailbox("Weird", [MailboxSpecialUse.Sent, MailboxSpecialUse.Junk]),
+			) > mailboxSyncPriority(mailbox("Plain")),
+		);
+	});
+
+	it("gives unflagged user folders the normal priority", () => {
+		assert.strictEqual(
+			mailboxSyncPriority(mailbox("Projects")),
+			mailboxSyncPriority(mailbox("Personal", [])),
+		);
+	});
+});

package/src/handlers/mailbox-sync-order.ts

@@ -0,0 +1,65 @@
+import { MailboxSpecialUse } from "@remit/domain-enums";
+
+export type MailboxSyncOrderEntry = {
+	mailboxId: string;
+	fullPath: string;
+	specialUse?: readonly string[];
+};
+
+// Sync priority by special-use, lowest first. Real mail leads (INBOX, then
+// Sent and Drafts), normal folders sit in the middle at NORMAL_PRIORITY, and
+// the low-value bulk folders (Junk/Spam, Trash) are pushed to the end so a
+// fresh account fills its inbox before its spam (issue #567). Keyed by the
+// bare runtime values from `@remit/domain-enums` (e.g. "Junk"), which match the
+// values stored in the Mailbox `specialUse` DynamoDB set.
+const INBOX_PRIORITY = 0;
+const NORMAL_PRIORITY = 4;
+
+const SPECIAL_USE_PRIORITY: Record<string, number> = {
+	[MailboxSpecialUse.Sent]: 1,
+	[MailboxSpecialUse.Drafts]: 2,
+	[MailboxSpecialUse.Flagged]: 3,
+	[MailboxSpecialUse.Junk]: 5,
+	[MailboxSpecialUse.Trash]: 6,
+};
+
+const isInbox = (fullPath: string): boolean =>
+	fullPath.toUpperCase() === "INBOX";
+
+/**
+ * Sync priority for a single mailbox. INBOX always leads; otherwise the
+ * mailbox's special-use flags resolve to a priority, defaulting to
+ * NORMAL_PRIORITY for plain user folders and unflagged mailboxes. When a
+ * mailbox carries both a leading flag (Sent/Drafts) and a trailing one
+ * (Junk/Trash) — rare, but possible with misconfigured servers — the trailing
+ * one wins: de-prioritising a bulk folder is the safer first-impression
+ * choice.
+ */
+export const mailboxSyncPriority = (entry: MailboxSyncOrderEntry): number => {
+	if (isInbox(entry.fullPath)) return INBOX_PRIORITY;
+
+	const priorities = (entry.specialUse ?? [])
+		.map((flag) => SPECIAL_USE_PRIORITY[flag])
+		.filter((priority): priority is number => priority !== undefined);
+
+	if (priorities.length === 0) return NORMAL_PRIORITY;
+
+	const trailing = priorities.filter((priority) => priority > NORMAL_PRIORITY);
+	if (trailing.length > 0) return Math.max(...trailing);
+
+	return Math.min(...priorities);
+};
+
+/**
+ * Order mailboxes for sync fan-out: INBOX first, then Sent/Drafts, then normal
+ * folders, with Junk/Spam and Trash last. Ties break alphabetically by
+ * fullPath so the order is deterministic.
+ */
+export const orderMailboxesForSync = <T extends MailboxSyncOrderEntry>(
+	mailboxes: readonly T[],
+): T[] =>
+	[...mailboxes].sort((a, b) => {
+		const priorityDelta = mailboxSyncPriority(a) - mailboxSyncPriority(b);
+		if (priorityDelta !== 0) return priorityDelta;
+		return a.fullPath.localeCompare(b.fullPath);
+	});

package/src/handlers/message-copy.ts

@@ -0,0 +1,219 @@
+import { getClient } from "@remit/backend/client";
+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 type { MessageCopyEvent } from "../events.js";
+import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
+import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
+
+/**
+ * Handle MESSAGE_COPY events.
+ * Executes IMAP COPY command and updates local state with new UID.
+ */
+export const handleMessageCopy = async (
+	event: MessageCopyEvent,
+	log: Logger,
+): Promise<void> => {
+	const {
+		account: accountService,
+		message: messageService,
+		threadMessage: threadMessageService,
+		mailbox: mailboxService,
+		secrets,
+	} = await getClient();
+
+	const {
+		accountId,
+		sourceMessageId,
+		newMessageId,
+		sourceMailboxId,
+		sourceMailboxPath,
+		destinationMailboxPath,
+		destinationMailboxId,
+		uid,
+	} = event;
+
+	log.info(
+		{
+			event: event.type,
+			accountId,
+			sourceMessageId,
+			newMessageId,
+			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, sourceMessageId, mailboxId: sourceMailboxId },
+					"Mailbox cursor not normal; pausing outbound copy this round",
+				);
+				return;
+			}
+
+			const scope = createConnectionScopeWithCredentials(account, credentials);
+
+			await scope
+				.getConnection()
+				.then(async (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.
+					const connection = guardConnectionCursor(
+						rawConnection,
+						{ mailboxService },
+						accountId,
+						mailbox,
+					);
+					// Open source mailbox (read-only is fine for COPY)
+					await connection.openBox(sourceMailboxPath, true);
+
+					// Execute IMAP COPY
+					const result = await connection.copyMessages(
+						[uid],
+						destinationMailboxPath,
+					);
+
+					// Get new UID from COPYUID response
+					const newUid = result.uidMap.get(uid);
+
+					if (newUid) {
+						// Update the new message with the actual UID
+						await messageService.updateUid(
+							newMessageId,
+							newUid,
+							destinationMailboxId,
+						);
+
+						// Update message status to active
+						await messageService.update(newMessageId, {
+							status: MessageStatus.active,
+							syncStatus: MessageSyncStatus.synced,
+						});
+
+						// Update ThreadMessage UID
+						const threadMessage = await threadMessageService.findByMessageId(
+							account.accountConfigId,
+							newMessageId,
+						);
+						if (threadMessage) {
+							await threadMessageService.update(
+								threadMessage.accountConfigId,
+								threadMessage.threadMessageId,
+								{ uid: newUid },
+								{
+									composites: {
+										sentDate: threadMessage.sentDate,
+										mailboxId: threadMessage.mailboxId,
+										isRead: threadMessage.isRead,
+										isDeleted: threadMessage.isDeleted,
+										hasStars: threadMessage.hasStars,
+										hasAttachment: threadMessage.hasAttachment,
+									},
+								},
+							);
+						}
+
+						log.info(
+							{
+								sourceMessageId,
+								newMessageId,
+								oldUid: uid,
+								newUid,
+								destination: destinationMailboxPath,
+							},
+							"Message copied successfully",
+						);
+					} else {
+						// Source message may have been deleted on server
+						log.error(
+							{ sourceMessageId, uid },
+							"Source message not found in COPYUID response - may have been deleted",
+						);
+						await messageService.update(newMessageId, {
+							syncStatus: MessageSyncStatus.failed,
+						});
+					}
+				})
+				.catch(async (error: unknown) => {
+					if (error instanceof MailboxCursorPausedError) {
+						log.info(
+							{
+								accountId,
+								sourceMessageId,
+								mailboxId: sourceMailboxId,
+								cursorState: error.state,
+							},
+							"Mailbox cursor not normal; pausing outbound copy 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 source message not found on IMAP - already deleted (fail the copy)
+					if (
+						errorMessage.includes("not found") ||
+						errorMessage.includes("NONEXISTENT")
+					) {
+						log.info(
+							{ sourceMessageId, uid },
+							"Source message not found on IMAP, marking copy as failed",
+						);
+						await messageService.update(newMessageId, {
+							status: MessageStatus.deleted,
+							syncStatus: MessageSyncStatus.failed,
+						});
+						return;
+					}
+
+					// Mark as failed for other errors
+					await messageService.update(newMessageId, {
+						syncStatus: MessageSyncStatus.failed,
+					});
+					throw error;
+				})
+				.finally(() => scope.disconnect());
+		},
+	);
+};