@remit/mailbox-service 0.0.27 → 0.0.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/mailbox-service",
-  "version": "0.0.27",
+  "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-management.test.ts

@@ -1,10 +1,18 @@
 import assert from "node:assert";
 import { describe, it } from "node:test";
+import type { IMailboxRepository } from "@remit/data-ports";
+import { MailboxSyncStatus } from "@remit/domain-enums";
 import {
+	MailboxManagementService,
 	parseMailboxPath,
 	validateMailboxOperation,
 	validateMailboxPath,
 } from "./mailbox-management.js";
+import type {
+	FlatMailboxInfo,
+	IImapConnection,
+	ImapBoxStatus,
+} from "./types.js";
 
 describe("parseMailboxPath", () => {
 	it("parses simple path", () => {
@@ -76,6 +84,161 @@ describe("validateMailboxPath", () => {
 	});
 });
 
+const boxStatus = (path: string): ImapBoxStatus => ({
+	name: path,
+	readOnly: true,
+	uidvalidity: 42,
+	uidnext: 7,
+	flags: [],
+	permFlags: [],
+	persistentUIDs: true,
+	messages: { total: 0, new: 0 },
+	newKeywords: false,
+});
+
+const recordingRepo = () => {
+	const updates: Array<{ mailboxId: string; patch: Record<string, unknown> }> =
+		[];
+	const repo = {
+		update: async (
+			_accountId: string,
+			mailboxId: string,
+			patch: Record<string, unknown>,
+		) => {
+			updates.push({ mailboxId, patch });
+			return {} as never;
+		},
+	} as unknown as IMailboxRepository;
+	return { repo, updates };
+};
+
+const stubConnection = (
+	createdPath: string,
+	listed: string[],
+): { connection: IImapConnection; opened: string[] } => {
+	const opened: string[] = [];
+	const connection = {
+		createMailbox: async (_path: string) => ({
+			path: createdPath,
+			created: true,
+		}),
+		subscribeMailbox: async () => undefined,
+		listMailboxes: async (): Promise<FlatMailboxInfo[]> =>
+			listed.map((fullPath) => ({
+				fullPath,
+				name: fullPath.split("/").pop() ?? fullPath,
+				delimiter: "/",
+				attributes: [],
+				parentPath: null,
+			})),
+		openBox: async (path: string) => {
+			opened.push(path);
+			return boxStatus(path);
+		},
+		closeBox: async () => undefined,
+	} as unknown as IImapConnection;
+	return { connection, opened };
+};
+
+describe("MailboxManagementService.syncCreate — server path normalization", () => {
+	it("adopts the server-materialized path as the row's identity when it is prefixed", async () => {
+		const { repo, updates } = recordingRepo();
+		const { connection, opened } = stubConnection("INBOX/Notifications", [
+			"INBOX/Notifications",
+		]);
+		const service = new MailboxManagementService(repo);
+
+		const result = await service.syncCreate(
+			"acc-1",
+			"mbx-1",
+			"Notifications",
+			async () => connection,
+		);
+
+		assert.strictEqual(result.success, true);
+		// The mailbox is opened at the server's path, not the requested leaf.
+		assert.deepStrictEqual(opened, ["INBOX/Notifications"]);
+		assert.strictEqual(updates.length, 1);
+		// The row keeps its id and takes on the prefixed path, so the next reconcile
+		// updates it in place instead of insert+delete — every reference survives.
+		assert.strictEqual(updates[0].mailboxId, "mbx-1");
+		assert.strictEqual(updates[0].patch.fullPath, "INBOX/Notifications");
+		assert.strictEqual(updates[0].patch.syncStatus, MailboxSyncStatus.synced);
+	});
+
+	it("leaves the path untouched when the server keeps it as requested", async () => {
+		const { repo, updates } = recordingRepo();
+		const { connection } = stubConnection("Work", ["Work"]);
+		const service = new MailboxManagementService(repo);
+
+		await service.syncCreate("acc-1", "mbx-2", "Work", async () => connection);
+
+		assert.strictEqual(updates.length, 1);
+		assert.ok(!("fullPath" in updates[0].patch));
+		assert.strictEqual(updates[0].patch.syncStatus, MailboxSyncStatus.synced);
+	});
+
+	it("still adopts the server path when the fresh list cannot resolve it", async () => {
+		const { repo, updates } = recordingRepo();
+		const { connection, opened } = stubConnection("INBOX/Notifications", []);
+		const service = new MailboxManagementService(repo);
+
+		await service.syncCreate(
+			"acc-1",
+			"mbx-3",
+			"Notifications",
+			async () => connection,
+		);
+
+		assert.deepStrictEqual(opened, []);
+		assert.strictEqual(updates.length, 1);
+		assert.strictEqual(updates[0].patch.fullPath, "INBOX/Notifications");
+		assert.strictEqual(updates[0].patch.syncStatus, MailboxSyncStatus.synced);
+	});
+
+	it("falls back to the requested path when the create result carries none", async () => {
+		const { repo, updates } = recordingRepo();
+		const opened: string[] = [];
+		const subscribed: string[] = [];
+		const connection = {
+			createMailbox: async (_path: string) => ({ created: true }),
+			subscribeMailbox: async (p: string) => {
+				subscribed.push(p);
+			},
+			listMailboxes: async (): Promise<FlatMailboxInfo[]> => [
+				{
+					fullPath: "Archive",
+					name: "Archive",
+					delimiter: "/",
+					attributes: [],
+					parentPath: null,
+				},
+			],
+			openBox: async (p: string) => {
+				opened.push(p);
+				return boxStatus(p);
+			},
+			closeBox: async () => undefined,
+		} as unknown as IImapConnection;
+		const service = new MailboxManagementService(repo);
+
+		await service.syncCreate(
+			"acc-1",
+			"mbx-4",
+			"Archive",
+			async () => connection,
+			true,
+		);
+
+		// A thin result never blanks fullPath — the requested path is used throughout.
+		assert.deepStrictEqual(subscribed, ["Archive"]);
+		assert.deepStrictEqual(opened, ["Archive"]);
+		assert.strictEqual(updates.length, 1);
+		assert.ok(!("fullPath" in updates[0].patch));
+		assert.strictEqual(updates[0].patch.syncStatus, MailboxSyncStatus.synced);
+	});
+});
+
 describe("validateMailboxOperation", () => {
 	it("throws when deleting INBOX", () => {
 		assert.throws(() => validateMailboxOperation("delete", "INBOX"), {

package/src/mailbox-management.ts

@@ -135,25 +135,41 @@ export class MailboxManagementService {
 
 		const result = await connection.createMailbox(path);
 
+		// The server is free to materialize the requested path under a namespace
+		// prefix — a Dovecot INBOX namespace turns "Notifications" into
+		// "INBOX/Notifications". `mailboxCreate` reports the canonical path the
+		// server assigned; adopt it as this row's identity so the next mailbox
+		// reconcile matches it by fullPath and updates it in place, rather than
+		// inserting a fresh row for the prefixed path and deleting this one — which
+		// would strand every filter and placement that references this mailboxId.
+		// Fall back to the requested path when the result carries no usable path,
+		// so a thin result never blanks the row's fullPath to undefined.
+		const serverPath =
+			typeof result.path === "string" && result.path.length > 0
+				? result.path
+				: path;
+		const pathUpdate = serverPath !== path ? { fullPath: serverPath } : {};
+
 		this.log.info(
-			{ mailboxId, path, created: result.created },
+			{ mailboxId, path, serverPath, created: result.created },
 			"Created mailbox on IMAP server",
 		);
 
 		if (subscribe) {
-			await connection.subscribeMailbox(path);
-			this.log.info({ mailboxId, path }, "Subscribed to mailbox");
+			await connection.subscribeMailbox(serverPath);
+			this.log.info({ mailboxId, path: serverPath }, "Subscribed to mailbox");
 		}
 
 		// Refresh mailbox list to get UIDVALIDITY and other attributes
 		const mailboxes = await connection.listMailboxes();
-		const mailboxInfo = mailboxes.find((m) => m.fullPath === path);
+		const mailboxInfo = mailboxes.find((m) => m.fullPath === serverPath);
 
 		if (mailboxInfo) {
 			// Open the mailbox to get UIDVALIDITY and other status info
-			const status = await connection.openBox(path, true);
+			const status = await connection.openBox(serverPath, true);
 
 			await this.mailboxService.update(accountId, mailboxId, {
+				...pathUpdate,
 				uidValidity: status.uidvalidity,
 				uidNext: status.uidnext,
 				messageCount: status.messages.total,
@@ -164,6 +180,7 @@ export class MailboxManagementService {
 		} else {
 			// Mark as synced even if we couldn't get full info
 			await this.mailboxService.update(accountId, mailboxId, {
+				...pathUpdate,
 				syncStatus: MailboxSyncStatus.synced,
 			});
 		}

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++;
 					}