@remit/mailbox-service 0.0.28 → 0.0.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/mailbox-service",
-  "version": "0.0.28",
+  "version": "0.0.29",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/index.ts

@@ -148,6 +148,10 @@ export {
 	validateMailboxOperation,
 	validateMailboxPath,
 } from "./mailbox-management.js";
+export {
+	isFolderOffServer,
+	isMailboxNotOnServer,
+} from "./mailbox-presence.js";
 export {
 	type CreateMailboxQueueInput,
 	type MailboxQueueConfig,

package/src/mailbox-presence.ts

@@ -0,0 +1,57 @@
+import type { IMailboxRepository, MailboxItem } from "@remit/data-ports";
+import { MailboxSyncStatus } from "@remit/domain-enums";
+
+const isNotFoundError = (error: unknown): boolean =>
+	error instanceof Error && error.name === "NotFoundError";
+
+/**
+ * Whether the IMAP server is not known to hold this folder — the row is gone,
+ * its creation has not reached the server yet, or its deletion has been asked
+ * for and not finished. Folders are written locally first and reconciled to the
+ * server by the worker, so both ends of that lifecycle are states in which
+ * syncing the folder can only fail.
+ *
+ * This is the terminal test for a sync event whose folder is not there. The
+ * row's absence alone does not decide it, at either end: on the way out the row
+ * is removed only after the IMAP folder is, so an event that fails against the
+ * server still sees a live row for as long as that write takes; on the way in
+ * the row exists before the folder does. `pending` and `deleting` are written by
+ * the request itself, before the event that resolves it is enqueued, which is
+ * what makes them sound proxies for presence: neither can be observed unless a
+ * create has yet to land or a delete has been asked for.
+ *
+ * `failed` is deliberately not one of them, though it is the fourth state a
+ * mailbox row can carry. It records that the last management operation failed
+ * and says nothing about whether the folder is on the server: `handleDelete` and
+ * `handleRename` set it on folders that exist and hold the user's mail, and
+ * nothing ever clears it — `syncStatus` returns to `synced` only from a
+ * subsequent successful create or rename, never from the sweep. Treating it as
+ * off-server would stop syncing such a folder permanently and silently, which is
+ * worse than the bounded stall it would remove. A `failed` row whose folder is
+ * genuinely absent is reaped by the sweep's own cleanup, which runs before the
+ * fan-out that would enqueue work for it.
+ *
+ * Mailbox management is judged differently — it is what establishes and removes
+ * the folder, so it terminates on a not-found row alone.
+ */
+export const isFolderOffServer = (
+	mailbox: Pick<MailboxItem, "syncStatus">,
+): boolean =>
+	mailbox.syncStatus === MailboxSyncStatus.pending ||
+	mailbox.syncStatus === MailboxSyncStatus.deleting;
+
+/** {@link isFolderOffServer} for a mailbox that has to be read first, an absent row included. */
+export const isMailboxNotOnServer = async (
+	mailboxService: Pick<IMailboxRepository, "get">,
+	accountId: string,
+	mailboxId: string,
+): Promise<boolean> => {
+	const mailbox = await mailboxService
+		.get(accountId, mailboxId)
+		.catch((error: unknown) => {
+			if (isNotFoundError(error)) return undefined;
+			throw error;
+		});
+	if (!mailbox) return true;
+	return isFolderOffServer(mailbox);
+};

package/src/mailbox-sync.test.ts

@@ -4,6 +4,7 @@ import type {
 	IMailboxRepository,
 	IMailboxSpecialUseRepository,
 } from "@remit/data-ports";
+import { NotFoundError } from "@remit/data-ports/errors";
 import {
 	MailboxCursorState,
 	MailboxSpecialUse,
@@ -309,3 +310,161 @@ describe("MailboxSyncService.syncMailboxes — reconcile does not delete pending
 		assert.equal(result.deleted, 1);
 	});
 });
+
+/**
+ * The folder set can also change under a running sweep: a delete asked for while
+ * the account is enumerating lands between the LIST and one folder's STATUS.
+ * Failing the whole account's enumeration over that one folder stalls every
+ * later sync for the account, on a per-account FIFO queue, for the queue's whole
+ * visibility window (issue #339).
+ */
+describe("MailboxSyncService.syncMailboxes — a folder leaving mid-sweep (#339)", () => {
+	const namespaces: ImapNamespaces = {
+		personal: [{ prefix: "", delimiter: "/" }],
+		other: [],
+		shared: [],
+	};
+
+	const status = () => ({
+		messages: 3,
+		recent: 0,
+		unseen: 0,
+		uidNext: 100,
+		uidValidity: 1,
+		highestModseq: "0",
+		deletedCount: 0,
+	});
+
+	const buildConnection = (
+		statusFor: (path: string) => Promise<ReturnType<typeof status>>,
+	): { connection: IImapConnection; statusPaths: string[] } => {
+		const statusPaths: string[] = [];
+		const connection = {
+			getNamespaces: async () => namespaces,
+			listMailboxes: async () =>
+				["INBOX", "Doomed"].map((fullPath) => ({
+					fullPath,
+					name: fullPath,
+					delimiter: "/",
+					attributes: [],
+					parentPath: null,
+				})),
+			getMailboxStatus: async (path: string) => {
+				statusPaths.push(path);
+				return statusFor(path);
+			},
+		} as unknown as IImapConnection;
+		return { connection, statusPaths };
+	};
+
+	const buildServices = (options: {
+		doomedSyncStatus?: string;
+		getDoomed?: () => Promise<unknown>;
+	}) => {
+		const updatedIds: string[] = [];
+		const row = (mailboxId: string, fullPath: string, syncStatus?: string) => ({
+			mailboxId,
+			fullPath,
+			uidNext: 1,
+			uidValidity: 1,
+			messageCount: 0,
+			unseenCount: 0,
+			deletedCount: 0,
+			highestModseq: "0",
+			specialUse: undefined,
+			syncStatus,
+		});
+
+		const mailboxService = {
+			listByAccount: async () => ({
+				items: [
+					row("mbx-inbox", "INBOX", MailboxSyncStatus.synced),
+					row("mbx-doomed", "Doomed", options.doomedSyncStatus),
+				],
+				continuationToken: undefined,
+			}),
+			get: async (_accountId: string, mailboxId: string) => {
+				if (mailboxId === "mbx-doomed" && options.getDoomed) {
+					return options.getDoomed();
+				}
+				return row(mailboxId, mailboxId, MailboxSyncStatus.synced);
+			},
+			update: async (
+				_accountId: string,
+				mailboxId: string,
+				_patch: Record<string, unknown>,
+			) => {
+				updatedIds.push(mailboxId);
+				return {};
+			},
+			delete: async () => undefined,
+			create: async () => ({}),
+		} as unknown as IMailboxRepository;
+
+		const specialUseService = {
+			listByMailboxId: async () => [],
+			deleteByMailboxId: async () => undefined,
+			createMany: async () => undefined,
+		} as unknown as IMailboxSpecialUseRepository;
+
+		return { mailboxService, specialUseService, updatedIds };
+	};
+
+	for (const syncStatus of [
+		MailboxSyncStatus.pending,
+		MailboxSyncStatus.deleting,
+	]) {
+		it(`leaves a \`${syncStatus}\` folder untouched — no STATUS, no write`, async () => {
+			const { mailboxService, specialUseService, updatedIds } = buildServices({
+				doomedSyncStatus: syncStatus,
+			});
+			const { connection, statusPaths } = buildConnection(async () => status());
+			const service = new MailboxSyncService(mailboxService, specialUseService);
+
+			await service.syncMailboxes({ accountId: "acc-1" }, connection);
+
+			assert.deepEqual(statusPaths, ["INBOX"]);
+			assert.deepEqual(updatedIds, ["mbx-inbox"]);
+		});
+	}
+
+	it("finishes the sweep when a folder's STATUS fails and that folder has since been deleted", async () => {
+		const { mailboxService, specialUseService, updatedIds } = buildServices({
+			doomedSyncStatus: MailboxSyncStatus.synced,
+			getDoomed: async () => {
+				throw new NotFoundError("Mailbox not found: mbx-doomed");
+			},
+		});
+		const { connection } = buildConnection(async (path) => {
+			if (path === "Doomed") throw new Error("Mailbox doesn't exist: Doomed");
+			return status();
+		});
+		const service = new MailboxSyncService(mailboxService, specialUseService);
+
+		await assert.doesNotReject(
+			service.syncMailboxes({ accountId: "acc-1" }, connection),
+		);
+		assert.deepEqual(updatedIds, ["mbx-inbox"]);
+	});
+
+	it("fails the sweep when a folder's STATUS fails and the folder is still live", async () => {
+		const { mailboxService, specialUseService } = buildServices({
+			doomedSyncStatus: MailboxSyncStatus.synced,
+			getDoomed: async () => ({
+				mailboxId: "mbx-doomed",
+				fullPath: "Doomed",
+				syncStatus: MailboxSyncStatus.synced,
+			}),
+		});
+		const { connection } = buildConnection(async (path) => {
+			if (path === "Doomed") throw new Error("connection reset by peer");
+			return status();
+		});
+		const service = new MailboxSyncService(mailboxService, specialUseService);
+
+		await assert.rejects(
+			service.syncMailboxes({ accountId: "acc-1" }, connection),
+			/connection reset by peer/,
+		);
+	});
+});

package/src/mailbox-sync.ts

@@ -19,6 +19,7 @@ import {
 import pMap from "p-map";
 import { isNoSelect, parseImapAttributes } from "./attribute-mapper.js";
 import { isCursorRebuildNeeded } from "./mailbox-cursor.js";
+import { isMailboxNotOnServer } from "./mailbox-presence.js";
 import type {
 	FlatMailboxInfo,
 	IImapConnection,
@@ -175,12 +176,39 @@ export class MailboxSyncService {
 				const existing = existingByPath.get(mailboxInfo.fullPath);
 
 				if (existing) {
+					// A folder at either end of its lifecycle is left alone: the worker
+					// that establishes or removes it writes its own identity back, and
+					// reading its status meanwhile is work whose only possible outcome is
+					// a failure that fails this whole account's fan-out with it.
+					if (
+						existing.syncStatus === MailboxSyncStatus.pending ||
+						existing.syncStatus === MailboxSyncStatus.deleting
+					) {
+						return;
+					}
+					// The folder set can change under this sweep. A delete that lands
+					// between the LIST above and this mailbox's STATUS fails on the
+					// server or on the row, and that would abort the enumeration of every
+					// other folder and the SYNC_MESSAGES fan-out behind it — on a
+					// per-account FIFO queue, for the whole visibility window (issue
+					// #339). One folder leaving is not a failed account sync. Anything
+					// else still propagates.
 					const updated = await this.updateMailbox(
 						account.accountId,
 						existing,
 						mailboxInfo,
 						connection,
-					);
+					).catch(async (error: unknown) => {
+						// The read only classifies the failure in hand; one that cannot
+						// answer must not replace it.
+						const gone = await isMailboxNotOnServer(
+							this.mailboxService,
+							account.accountId,
+							existing.mailboxId,
+						).catch(() => false);
+						if (gone) return null;
+						throw error;
+					});
 					if (updated) {
 						result.updated++;
 					}