@remit/imap-worker 0.0.90 → 0.0.91

package/src/handlers/mailbox-management.ts

@@ -1,486 +0,0 @@
-import { getClient } from "@remit/backend/client";
-import { refreshFolderAppointmentLabels } from "@remit/backend/folder-role-labels";
-import type { IMailboxRepository } from "@remit/data-ports";
-import { isNotFoundError, NotFoundError } from "@remit/data-ports/errors";
-import { MailboxSyncStatus } from "@remit/domain-enums";
-import type { Logger } from "@remit/logger";
-import {
-	FolderGoneUpstreamError,
-	FolderRenameSettleError,
-	isMailboxAbsentUpstream,
-	isMailboxPresentUpstream,
-	isMailboxRefusedUpstream,
-	MailboxManagementService,
-	upstreamFailureReason,
-} 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";
-
-/**
- * The outcome of a create, written against the state a create in flight is:
- * `pending` with no recorded rename target (D3, D10). Without the absence
- * check, a create redelivered after a lost acknowledgement settles a row a
- * rename has since claimed and kills the rename silently.
- */
-const recordCreateOutcome = async (
-	mailboxService: Pick<IMailboxRepository, "transition">,
-	accountId: string,
-	mailboxId: string,
-	to: (typeof MailboxSyncStatus)[keyof typeof MailboxSyncStatus],
-	syncFailureReason = "",
-): Promise<void> => {
-	const written = await mailboxService.transition(accountId, mailboxId, {
-		from: [MailboxSyncStatus.pending],
-		wherePendingPath: null,
-		to,
-		set: { syncFailureReason },
-	});
-	if (!written) throw new NotFoundError(`Mailbox not found: ${mailboxId}`);
-};
-
-/**
- * Pinned invariant for the whole-chain terminal guards below.
- *
- * Each handler wraps its `MailboxManagementService.sync*` chain in a try/catch
- * that treats a NotFoundError as terminal (ack with a WARN, issue #289). That is
- * only sound while the sole row a NotFoundError can refer to is the target
- * mailbox, so its absence can only mean the user deleted the folder mid-sync —
- * never an unrelated missing entity that should have been retried.
- *
- * `syncCreate` and `syncDelete` hold to that by touching nothing but the target
- * row. `syncRename` also writes every other row that recorded the same intent,
- * and keeps the invariant by treating a lost predicate as an outcome rather than
- * an error: a descendant deleted mid-settle is skipped, never raised. The
- * appointment-label refresh writes `account_setting` rows, whose reads answer
- * absent rather than throwing. Any sync method that reads or writes a second
- * entity owes the same, or these catches must be narrowed (match the mailboxId /
- * re-check existence) before a NotFoundError from elsewhere is silently acked.
- */
-
-/**
- * Handle MAILBOX_CREATE event
- */
-const handleCreate = async (
-	event: MailboxCreateEvent,
-	log: Logger,
-	createConnectionScope: typeof createConnectionScopeWithCredentials,
-): 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 = createConnectionScope(account, credentials);
-			const managementService = new MailboxManagementService(
-				mailboxService,
-				log,
-			);
-
-			try {
-				await managementService
-					.syncCreate(
-						accountId,
-						mailboxId,
-						path,
-						scope.getConnection,
-						subscribe,
-					)
-					.then((result) => {
-						if (result.success) {
-							log.info(
-								{
-									accountId,
-									mailboxId,
-									path,
-									existingMailboxId: result.existing?.mailboxId,
-								},
-								"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 (isMailboxPresentUpstream(error)) {
-							log.info(
-								{ accountId, mailboxId, path },
-								"Mailbox already exists, marking as synced",
-							);
-							await recordCreateOutcome(
-								mailboxService,
-								accountId,
-								mailboxId,
-								MailboxSyncStatus.synced,
-							);
-						} else {
-							await recordCreateOutcome(
-								mailboxService,
-								accountId,
-								mailboxId,
-								MailboxSyncStatus.failed,
-								upstreamFailureReason(error),
-							);
-							if (isMailboxRefusedUpstream(error)) {
-								log.error(
-									{ accountId, mailboxId, path, intent: "create", error },
-									"Mail server refused the create",
-								);
-								return;
-							}
-							throw error;
-						}
-					})
-					.finally(() => scope.disconnect());
-			} catch (error) {
-				// The mailbox row was deleted between enqueue and this sync — the
-				// create-then-status-write throws NotFoundError, which can never
-				// succeed on retry and would poison the account's per-group FIFO
-				// forever (issue #289, same class as #287/#290). A folder the user
-				// deleted is an expected terminal outcome: ack with a WARN. Real
-				// IMAP/infra failures carry other errors and still propagate.
-				if (isNotFoundError(error)) {
-					log.warn(
-						{ accountId, mailboxId, path, eventId: event.eventId },
-						"Skipping MAILBOX_CREATE: mailbox no longer exists (deleted)",
-					);
-					return;
-				}
-				throw error;
-			}
-		},
-	);
-};
-
-/**
- * Handle MAILBOX_RENAME event
- */
-const handleRename = async (
-	event: MailboxRenameEvent,
-	log: Logger,
-	createConnectionScope: typeof createConnectionScopeWithCredentials,
-): Promise<void> => {
-	const {
-		account: accountService,
-		accountSetting: accountSettingService,
-		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 = createConnectionScope(account, credentials);
-			const managementService = new MailboxManagementService(
-				mailboxService,
-				log,
-			);
-
-			try {
-				await managementService
-					.syncRename(
-						accountId,
-						mailboxId,
-						oldPath,
-						newPath,
-						scope.getConnection,
-					)
-					.then(async (result) => {
-						if (!result.success) {
-							log.error(
-								{ accountId, mailboxId, oldPath, newPath, error: result.error },
-								"Failed to rename mailbox on IMAP",
-							);
-							return;
-						}
-						log.info(
-							{ accountId, mailboxId, oldPath, newPath },
-							"Mailbox renamed on IMAP",
-						);
-						if (!result.renamed) return;
-						// The path recorded beside each role appointment (#887) moves with
-						// the settle, because under D2 that is the first moment the new
-						// path is one the server holds.
-						//
-						// A label is display-only and this runs after the server rename
-						// landed, so letting it fail would take the job down the failure
-						// path and mark a completed rename refused. Logged and dropped;
-						// the next appointment write records the folder's current path
-						// anyway.
-						await refreshFolderAppointmentLabels(
-							accountSettingService,
-							account.accountConfigId,
-							accountId,
-							{
-								mailboxId,
-								oldPath: result.renamed.oldPath,
-								newPath: result.renamed.newPath,
-							},
-							result.renamed.delimiter,
-						).catch((error: unknown) => {
-							log.error(
-								{ accountId, mailboxId, oldPath, newPath, error },
-								"Renamed folder settled, but its role-appointment labels did not move",
-							);
-						});
-					})
-					.catch(async (error) => {
-						// The server executed the rename and only the local settle did not
-						// finish. That is not a refused rename: marking the rows `failed`
-						// would offer a retry of work already done and leave `fullPath`
-						// naming a path the server no longer holds. Rethrow, so the
-						// redelivery finishes the settle against an intent still standing.
-						if (error instanceof FolderRenameSettleError) {
-							log.error(
-								{ accountId, mailboxId, oldPath, newPath, error },
-								"Rename landed on the server; the settle will finish on redelivery",
-							);
-							throw error;
-						}
-						// The folder the rename was to move is confirmed gone: the
-						// server refused the RENAME as non-existent and its own listing
-						// held neither path. The rename decides that, once, where the
-						// evidence is — re-reading the response code here would make
-						// every `NONEXISTENT` this code cannot classify destroy the
-						// folder's mail. Removing the root row alone is the orphaning
-						// bug: every descendant recorded the same intent (D6) and would
-						// be left `pending` at a path that does not exist, with its mail
-						// stranded out of every reader (D8).
-						if (error instanceof FolderGoneUpstreamError) {
-							log.info(
-								{ accountId, mailboxId, oldPath, intent: "rename" },
-								"Source mailbox not found, deleting local folder and its mail",
-							);
-							await managementService.abandonRenameSubtree(
-								accountId,
-								mailboxId,
-								oldPath,
-								newPath,
-							);
-							return;
-						}
-						// T6. Nothing is restored — `fullPath` was never written, and
-						// each intent-carrying row keeps its target so the client can
-						// name what the rename was aiming at and offer a retry.
-						await managementService.failRename(
-							accountId,
-							mailboxId,
-							oldPath,
-							newPath,
-							upstreamFailureReason(error),
-						);
-						if (isMailboxRefusedUpstream(error)) {
-							log.error(
-								{
-									accountId,
-									mailboxId,
-									oldPath,
-									newPath,
-									intent: "rename",
-									error,
-								},
-								"Mail server refused the rename",
-							);
-							return;
-						}
-						throw error;
-					})
-					.finally(() => scope.disconnect());
-			} catch (error) {
-				// The mailbox row was deleted between enqueue and this sync — the
-				// status write-back throws NotFoundError, unretryable and would poison
-				// the account's per-group FIFO forever (issue #289 class). Ack with a
-				// WARN; real IMAP/infra failures carry other errors and still propagate.
-				if (isNotFoundError(error)) {
-					log.warn(
-						{ accountId, mailboxId, oldPath, newPath, eventId: event.eventId },
-						"Skipping MAILBOX_RENAME: mailbox no longer exists (deleted)",
-					);
-					return;
-				}
-				throw error;
-			}
-		},
-	);
-};
-
-/**
- * Handle MAILBOX_DELETE event
- */
-const handleDelete = async (
-	event: MailboxDeleteEvent,
-	log: Logger,
-	createConnectionScope: typeof createConnectionScopeWithCredentials,
-): 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 = createConnectionScope(account, credentials);
-			const managementService = new MailboxManagementService(
-				mailboxService,
-				log,
-			);
-
-			try {
-				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) => {
-						// The folder is already gone from the server, so the delete has
-						// happened. Its mail still goes with it (D8), which is the whole
-						// point of the settle.
-						if (isMailboxAbsentUpstream(error)) {
-							log.info(
-								{ accountId, mailboxId, path, intent: "delete" },
-								"Mailbox not found on IMAP, removing the local folder and its mail",
-							);
-							await managementService.settleDelete(accountId, mailboxId);
-						} else {
-							// T9, INBOX included. The API refuses a delete of INBOX, so the
-							// worker's backstop is unreachable from it; if something else
-							// reaches it, the honest outcome is `failed`, not `synced` —
-							// the folder was never deleted and nothing was undone.
-							await managementService.failDelete(
-								accountId,
-								mailboxId,
-								upstreamFailureReason(error),
-							);
-							if (
-								error instanceof Error &&
-								error.message.includes("Cannot delete INBOX")
-							) {
-								log.error(
-									{ accountId, mailboxId, path, intent: "delete" },
-									"Cannot delete INBOX",
-								);
-								// Don't rethrow — no retry can make this succeed.
-								return;
-							}
-							if (isMailboxRefusedUpstream(error)) {
-								log.error(
-									{ accountId, mailboxId, path, intent: "delete", error },
-									"Mail server refused the delete",
-								);
-								return;
-							}
-							throw error;
-						}
-					})
-					.finally(() => scope.disconnect());
-			} catch (error) {
-				// The mailbox row was already deleted (a duplicate/racing delete) — the
-				// error-recovery status write throws NotFoundError, unretryable and
-				// would poison the account's per-group FIFO forever (issue #289 class).
-				// The delete has effectively happened: ack with a WARN. Real IMAP/infra
-				// failures carry other errors and still propagate.
-				if (isNotFoundError(error)) {
-					log.warn(
-						{ accountId, mailboxId, path, eventId: event.eventId },
-						"Skipping MAILBOX_DELETE: mailbox no longer exists (deleted)",
-					);
-					return;
-				}
-				throw error;
-			}
-		},
-	);
-};
-
-/**
- * Process mailbox management events
- */
-export const processMailboxManagement = async (
-	event: MailboxManagementEvent,
-	log: Logger,
-	createConnectionScope = createConnectionScopeWithCredentials,
-): Promise<void> => {
-	switch (event.type) {
-		case "MAILBOX_CREATE":
-			return handleCreate(event, log, createConnectionScope);
-		case "MAILBOX_RENAME":
-			return handleRename(event, log, createConnectionScope);
-		case "MAILBOX_DELETE":
-			return handleDelete(event, log, createConnectionScope);
-	}
-};

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

@@ -1,93 +0,0 @@
-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

@@ -1,65 +0,0 @@
-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);
-	});