@remit/mailbox-service 0.0.96 → 0.0.97

package/src/mailbox-queue.ts

@@ -9,6 +9,11 @@ import { NotFoundError } from "@remit/data-ports/errors";
 import { rebaseMailboxPath } from "@remit/data-ports/mailbox-name";
 import { MailboxSyncStatus } from "@remit/domain-enums";
 import { createQueueProducer } from "@remit/sqs-client/producer";
+import {
+	INTENT_RECORDABLE_FROM,
+	recordedByRename,
+	refuseContestedIntent,
+} from "./mailbox-intent.js";
 import { EVERY_MAILBOX_STATE } from "./mailbox-presence.js";
 
 /**
@@ -149,13 +154,19 @@ export class MailboxQueueService {
 	};
 
 	/**
-	 * Rename a mailbox.
-	 * Updates local state (including children) and enqueues IMAP RENAME.
+	 * Record a rename intent over the folder and every descendant, then enqueue
+	 * IMAP RENAME.
+	 *
+	 * The target is recorded, not the path (D2): every row keeps the `fullPath`
+	 * the server holds and takes its own rewritten target in `pendingPath`, so a
+	 * rename that never lands needs no unwinding — dropping `pendingPath` is the
+	 * whole revert — and nothing that resolves a folder path from a row can
+	 * resolve one the server does not have.
 	 *
 	 * @param mailboxId - The mailbox to rename
-	 * @param newPath - The new path for the mailbox
+	 * @param newPath - The path the rename is aiming at
 	 * @param accountId - The account ID for the IMAP sync event
-	 * @returns The updated mailbox
+	 * @returns The folder that was named, carrying its recorded target
 	 */
 	renameMailbox = async (
 		mailboxId: string,
@@ -168,32 +179,58 @@ export class MailboxQueueService {
 
 		// One intent over the folder and every descendant, in one transaction:
 		// IMAP RENAME moves the subtree in one command, so a partially recorded
-		// rename is the state that produced today's phantom rows (D6). Each
-		// descendant's new path is equally absent from the server until
-		// MAILBOX_RENAME lands, so each is `pending` too — otherwise a reconcile
-		// in that window reaps it as server-deleted (#290).
+		// rename is the state that produced today's phantom rows (D6). A
+		// descendant already mid-mutation refuses the whole rename.
 		const written = await this.mailboxService.transitionSubtree(
 			accountId,
 			mailboxId,
 			{
-				from: EVERY_MAILBOX_STATE,
+				from: INTENT_RECORDABLE_FROM,
 				to: MailboxSyncStatus.pending,
 				rowSet: (row) => {
-					const moved = rebaseMailboxPath(
+					const target = rebaseMailboxPath(
 						row.fullPath,
 						oldPath,
 						newPath,
 						mailbox.hierarchyDelimiter,
 					);
-					return moved === undefined ? {} : { fullPath: moved };
+					// The subtree is the folder and the rows under its own prefix, so
+					// every one of them rebases. A row that does not is a resolution
+					// bug, and recording an intent with no target for it would strand
+					// it `pending` with nothing able to settle it.
+					if (target === undefined) {
+						throw new Error(
+							`Mailbox ${row.mailboxId} at "${row.fullPath}" is not under "${oldPath}"`,
+						);
+					}
+					return { pendingPath: target };
 				},
 			},
 		);
-		if (!written) throw new NotFoundError(`Mailbox not found: ${mailboxId}`);
+		if (!written) {
+			return refuseContestedIntent(
+				this.mailboxService,
+				accountId,
+				mailboxId,
+				"subtree",
+			);
+		}
 		const updated = written.find((row) => row.mailboxId === mailboxId);
 		if (!updated) throw new NotFoundError(`Mailbox not found: ${mailboxId}`);
 
-		this.log.info({ mailboxId, oldPath, newPath }, "Renamed mailbox (local)");
+		this.log.info(
+			{
+				accountId,
+				mailboxId,
+				intent: "rename",
+				from: mailbox.syncStatus,
+				to: MailboxSyncStatus.pending,
+				oldPath,
+				newPath,
+				subtreeSize: written.length,
+			},
+			"Recorded rename intent",
+		);
 
 		// Enqueue IMAP sync
 		await this.enqueueEvent({
@@ -209,6 +246,89 @@ export class MailboxQueueService {
 		return updated;
 	};
 
+	/**
+	 * The route out of a failed rename or a failed delete that keeps the folder
+	 * as it is (T10, T11): the recorded target is dropped and the row settles
+	 * back to `synced`. Nothing is enqueued — `fullPath` was never written, so
+	 * the server has nothing to undo.
+	 *
+	 * Reached without new API surface, from a PATCH whose `fullPath` equals the
+	 * row's confirmed one. From `synced` it is a no-op; from a state with a
+	 * mutation in flight it is a 409, because dismissing an intent that is still
+	 * running would leave the settle with no row to write.
+	 */
+	dismissMailboxIntent = async (
+		mailboxId: string,
+		accountId: string,
+	): Promise<MailboxItem> => {
+		const current = await this.mailboxService.get(accountId, mailboxId);
+		if (current.syncStatus === MailboxSyncStatus.synced) return current;
+		if (current.syncStatus !== MailboxSyncStatus.failed) {
+			return refuseContestedIntent(
+				this.mailboxService,
+				accountId,
+				mailboxId,
+				"folder",
+			);
+		}
+
+		// A failed rename was recorded over a subtree, so it is dismissed over the
+		// same one. A failed delete carries no target and was recorded on the
+		// folder alone, so there is nothing else to clear.
+		const target = current.pendingPath;
+		const alsoRecorded =
+			target === undefined
+				? []
+				: (
+						await this.mailboxService.findBySyncStatus(
+							accountId,
+							MailboxSyncStatus.failed,
+						)
+					).filter(
+						(row) =>
+							row.mailboxId !== mailboxId &&
+							recordedByRename(
+								row,
+								current.fullPath,
+								target,
+								current.hierarchyDelimiter,
+							),
+					);
+
+		let dismissed: MailboxItem | undefined;
+		// The named folder first, so a caller always gets back the row it asked
+		// about. Each write carries its own predicate, so a row somebody else
+		// moved between the read and the write is skipped, not overwritten (D3).
+		for (const row of [current, ...alsoRecorded]) {
+			const written = await this.mailboxService.transition(
+				accountId,
+				row.mailboxId,
+				{
+					from: [MailboxSyncStatus.failed],
+					wherePendingPath: row.pendingPath ?? null,
+					to: MailboxSyncStatus.synced,
+				},
+			);
+			if (row.mailboxId === mailboxId) dismissed = written ?? undefined;
+			this.log.info(
+				{
+					accountId,
+					mailboxId: row.mailboxId,
+					intent: "dismiss",
+					from: MailboxSyncStatus.failed,
+					to: MailboxSyncStatus.synced,
+					outcome: written ? "settled" : "superseded",
+				},
+				"Dismissed folder intent",
+			);
+		}
+
+		if (dismissed) return dismissed;
+		// The row moved between the read and its write. Re-read rather than
+		// reporting a dismissal that did not happen.
+		return this.mailboxService.get(accountId, mailboxId);
+	};
+
 	/**
 	 * Delete a mailbox.
 	 * Marks for deletion (syncStatus=deleting) and enqueues IMAP DELETE.

package/src/mailbox-rename-intent.test.ts

@@ -4,13 +4,18 @@ import type { IMailboxRepository, MailboxItem } from "@remit/data-ports";
 import { MailboxSyncStatus } from "@remit/domain-enums";
 import { MailboxQueueService } from "./mailbox-queue.js";
 
-const row = (mailboxId: string, fullPath: string): MailboxItem =>
+const row = (
+	mailboxId: string,
+	fullPath: string,
+	over: Partial<MailboxItem> = {},
+): MailboxItem =>
 	({
 		mailboxId,
 		accountId: "acc-1",
 		fullPath,
 		hierarchyDelimiter: "/",
 		syncStatus: MailboxSyncStatus.synced,
+		...over,
 	}) as MailboxItem;
 
 /**
@@ -19,8 +24,21 @@ const row = (mailboxId: string, fullPath: string): MailboxItem =>
  */
 const store = (rows: MailboxItem[]) => {
 	const byId = new Map(rows.map((r) => [r.mailboxId, { ...r }]));
+	const subtreeOf = (root: MailboxItem) => {
+		const prefix = `${root.fullPath}${root.hierarchyDelimiter}`;
+		return [...byId.values()].filter(
+			(r) => r.mailboxId !== root.mailboxId && r.fullPath.startsWith(prefix),
+		);
+	};
 
-	const repo: Pick<IMailboxRepository, "get" | "transitionSubtree"> = {
+	const repo: Pick<
+		IMailboxRepository,
+		| "get"
+		| "transition"
+		| "transitionSubtree"
+		| "findByPathPrefix"
+		| "findBySyncStatus"
+	> = {
 		get: (async (_accountId: string, mailboxId: string) => {
 			const found = byId.get(mailboxId as string);
 			if (!found) {
@@ -30,19 +48,45 @@ const store = (rows: MailboxItem[]) => {
 			}
 			return found;
 		}) as IMailboxRepository["get"],
+		findByPathPrefix: async (_accountId, pathPrefix) => {
+			const root = [...byId.values()].find((r) => r.fullPath === pathPrefix);
+			return root ? subtreeOf(root) : [];
+		},
+		findBySyncStatus: async (_accountId, syncStatus) =>
+			[...byId.values()].filter((r) => r.syncStatus === syncStatus),
+		transition: async (_accountId, mailboxId, intent) => {
+			const current = byId.get(mailboxId);
+			if (!current) return null;
+			if (!intent.from.includes(current.syncStatus)) return null;
+			if (
+				intent.wherePendingPath !== undefined &&
+				(intent.wherePendingPath ?? undefined) !== current.pendingPath
+			) {
+				return null;
+			}
+			const keepsTarget =
+				intent.to === MailboxSyncStatus.pending ||
+				intent.to === MailboxSyncStatus.failed;
+			const next = {
+				...current,
+				...(intent.set?.fullPath !== undefined
+					? { fullPath: intent.set.fullPath }
+					: {}),
+				syncStatus: intent.to,
+			} as MailboxItem;
+			if (!keepsTarget) delete (next as { pendingPath?: string }).pendingPath;
+			byId.set(mailboxId, next);
+			return next;
+		},
 		transitionSubtree: async (_accountId, mailboxId, intent) => {
 			const root = byId.get(mailboxId);
 			if (!root) return null;
-			const prefix = `${root.fullPath}${root.hierarchyDelimiter}`;
-			const subtree = [
-				root,
-				...[...byId.values()].filter(
-					(r) => r !== root && r.fullPath.startsWith(prefix),
-				),
-			];
+			const subtree = [root, ...subtreeOf(root)];
+			// All-or-nothing, the way the real transaction is: one row that is not
+			// in an accepted from-state refuses the whole intent and writes nothing.
+			if (subtree.some((c) => !intent.from.includes(c.syncStatus))) return null;
 			const written: MailboxItem[] = [];
 			for (const candidate of subtree) {
-				if (!intent.from.includes(candidate.syncStatus)) return null;
 				const next = {
 					...candidate,
 					...intent.rowSet(candidate),
@@ -59,7 +103,7 @@ const store = (rows: MailboxItem[]) => {
 
 	return {
 		repo: repo as IMailboxRepository,
-		pathOf: (id: string) => byId.get(id)?.fullPath,
+		rowOf: (id: string) => byId.get(id),
 	};
 };
 
@@ -84,27 +128,40 @@ const queueOver = (repo: IMailboxRepository) => {
 };
 
 describe("MailboxQueueService.renameMailbox — the recorded intent", () => {
+	it("records the target and leaves every confirmed path alone", async () => {
+		// D2: `fullPath` is always a path the server holds. Writing the target onto
+		// the row is what made a failed rename strand a subtree at paths the server
+		// never had, which the next sweep then inserted second rows for.
+		const { repo, rowOf } = store([
+			row("mbx-parent", "Work"),
+			row("mbx-child", "Work/2026"),
+		]);
+		const { service } = queueOver(repo);
+
+		await service.renameMailbox("mbx-parent", "Projects", "acc-1");
+
+		assert.equal(rowOf("mbx-parent")?.fullPath, "Work");
+		assert.equal(rowOf("mbx-parent")?.pendingPath, "Projects");
+		assert.equal(rowOf("mbx-child")?.fullPath, "Work/2026");
+		assert.equal(rowOf("mbx-child")?.pendingPath, "Projects/2026");
+		assert.equal(rowOf("mbx-child")?.syncStatus, MailboxSyncStatus.pending);
+	});
+
 	it("records the path the RENAME will carry, `$` patterns and all", async () => {
 		// `String.prototype.replace` expands `$&`, "$`", `$'` and `$$` in the
 		// replacement, so a folder renamed to a name containing one of them was
 		// stored under a different path from the one the event carries to the
-		// server. The row and the server then disagree, and the next sweep finds
-		// no row for the real path and inserts a second one.
-		const { repo, pathOf } = store([
+		// server. The row and the server then disagree.
+		const { repo, rowOf } = store([
 			row("mbx-parent", "Work"),
 			row("mbx-child", "Work/2026"),
 		]);
 		const { service, sent } = queueOver(repo);
 
-		const renamed = await service.renameMailbox(
-			"mbx-parent",
-			"Q1$&Q2",
-			"acc-1",
-		);
+		await service.renameMailbox("mbx-parent", "Q1$&Q2", "acc-1");
 
-		assert.equal(renamed.fullPath, "Q1$&Q2");
-		assert.equal(pathOf("mbx-parent"), "Q1$&Q2");
-		assert.equal(pathOf("mbx-child"), "Q1$&Q2/2026");
+		assert.equal(rowOf("mbx-parent")?.pendingPath, "Q1$&Q2");
+		assert.equal(rowOf("mbx-child")?.pendingPath, "Q1$&Q2/2026");
 		assert.equal(
 			(JSON.parse(sent[0]) as { newPath: string }).newPath,
 			"Q1$&Q2",
@@ -113,7 +170,7 @@ describe("MailboxQueueService.renameMailbox — the recorded intent", () => {
 	});
 
 	it("moves only what is under the renamed branch", async () => {
-		const { repo, pathOf } = store([
+		const { repo, rowOf } = store([
 			row("mbx-parent", "Work"),
 			row("mbx-lookalike", "Workshop"),
 		]);
@@ -121,8 +178,9 @@ describe("MailboxQueueService.renameMailbox — the recorded intent", () => {
 
 		await service.renameMailbox("mbx-parent", "Projects", "acc-1");
 
-		assert.equal(pathOf("mbx-parent"), "Projects");
-		assert.equal(pathOf("mbx-lookalike"), "Workshop");
+		assert.equal(rowOf("mbx-parent")?.pendingPath, "Projects");
+		assert.equal(rowOf("mbx-lookalike")?.pendingPath, undefined);
+		assert.equal(rowOf("mbx-lookalike")?.syncStatus, MailboxSyncStatus.synced);
 	});
 
 	it("returns the folder that was asked for, not whichever row came back first", async () => {
@@ -139,5 +197,193 @@ describe("MailboxQueueService.renameMailbox — the recorded intent", () => {
 		);
 
 		assert.equal(renamed.mailboxId, "mbx-parent");
+		assert.equal(renamed.pendingPath, "Projects");
+	});
+
+	it("records a retry from a failed rename onto the same row", async () => {
+		const { repo, rowOf } = store([
+			row("mbx-parent", "Work", {
+				syncStatus: MailboxSyncStatus.failed,
+				pendingPath: "Projects",
+			}),
+		]);
+		const { service } = queueOver(repo);
+
+		await service.renameMailbox("mbx-parent", "Projects", "acc-1");
+
+		assert.equal(rowOf("mbx-parent")?.syncStatus, MailboxSyncStatus.pending);
+		assert.equal(rowOf("mbx-parent")?.pendingPath, "Projects");
+	});
+
+	it("refuses the whole subtree with a 409 naming the descendant that blocks it", async () => {
+		// A subtree cannot be half-renamed (D6), so a descendant mid-mutation
+		// refuses the rename of everything above it — and the user has to be told
+		// which folder, because it is not the one they named.
+		const { repo, rowOf } = store([
+			row("mbx-parent", "Archive"),
+			row("mbx-child", "Archive/2025/Receipts", {
+				syncStatus: MailboxSyncStatus.pending,
+				pendingPath: "Archive/2025/Bonnen",
+			}),
+		]);
+		const { service, sent } = queueOver(repo);
+
+		await assert.rejects(
+			service.renameMailbox("mbx-parent", "Archief", "acc-1"),
+			(error: unknown) =>
+				(error as { statusCode?: number }).statusCode === 409 &&
+				(error as Error).message ===
+					'A rename is in progress for "Archive/2025/Receipts", inside this folder.',
+		);
+
+		assert.equal(rowOf("mbx-parent")?.syncStatus, MailboxSyncStatus.synced);
+		assert.equal(rowOf("mbx-parent")?.pendingPath, undefined);
+		assert.equal(sent.length, 0, "nothing is enqueued for a refused intent");
+	});
+
+	it("refuses with a 409 naming the folder's own delete when it is the blocker", async () => {
+		const { repo } = store([
+			row("mbx-parent", "Archive", {
+				syncStatus: MailboxSyncStatus.deleting,
+			}),
+		]);
+		const { service } = queueOver(repo);
+
+		await assert.rejects(
+			service.renameMailbox("mbx-parent", "Archief", "acc-1"),
+			(error: unknown) =>
+				(error as { statusCode?: number }).statusCode === 409 &&
+				(error as Error).message ===
+					'A delete is already in progress for "Archive".',
+		);
+	});
+
+	it("answers 404 when the folder went between the read and the intent", async () => {
+		const { repo } = store([row("mbx-parent", "Work")]);
+		let read = 0;
+		// The read that establishes existence sees the row; the classifying read
+		// on the lost predicate does not, so the answer is 404, not a conflict.
+		const vanishing = {
+			...repo,
+			get: (async (accountId: string, mailboxId: string) => {
+				read += 1;
+				if (read > 1) {
+					throw Object.assign(new Error(`Mailbox not found: ${mailboxId}`), {
+						name: "NotFoundError",
+					});
+				}
+				return repo.get(accountId, mailboxId as string);
+			}) as IMailboxRepository["get"],
+			transitionSubtree: async () => null,
+		} as IMailboxRepository;
+		const { service } = queueOver(vanishing);
+
+		await assert.rejects(
+			service.renameMailbox("mbx-parent", "Projects", "acc-1"),
+			(error: unknown) => (error as Error).name === "NotFoundError",
+		);
+	});
+});
+
+describe("MailboxQueueService.dismissMailboxIntent", () => {
+	it("clears a failed rename's target and settles the row, enqueuing nothing", async () => {
+		const { repo, rowOf } = store([
+			row("mbx-1", "Work", {
+				syncStatus: MailboxSyncStatus.failed,
+				pendingPath: "Projects",
+			}),
+		]);
+		const { service, sent } = queueOver(repo);
+
+		const dismissed = await service.dismissMailboxIntent("mbx-1", "acc-1");
+
+		assert.equal(dismissed.syncStatus, MailboxSyncStatus.synced);
+		assert.equal(rowOf("mbx-1")?.pendingPath, undefined);
+		assert.equal(rowOf("mbx-1")?.fullPath, "Work");
+		assert.equal(sent.length, 0);
+	});
+
+	it("clears the whole subtree the failed rename was recorded over", async () => {
+		// The refusal marks every row the intent recorded, so dismissing the named
+		// folder alone leaves each descendant `failed` with a stale target on it,
+		// offering a retry of a rename the user has already dropped and with
+		// nothing left that would ever clear it.
+		const { repo, rowOf } = store([
+			row("mbx-parent", "Work", {
+				syncStatus: MailboxSyncStatus.failed,
+				pendingPath: "Projects",
+			}),
+			row("mbx-child", "Work/2026", {
+				syncStatus: MailboxSyncStatus.failed,
+				pendingPath: "Projects/2026",
+			}),
+		]);
+		const { service } = queueOver(repo);
+
+		await service.dismissMailboxIntent("mbx-parent", "acc-1");
+
+		for (const id of ["mbx-parent", "mbx-child"]) {
+			assert.equal(rowOf(id)?.syncStatus, MailboxSyncStatus.synced);
+			assert.equal(rowOf(id)?.pendingPath, undefined);
+		}
+	});
+
+	it("leaves a failed folder a different rename recorded alone", async () => {
+		const { repo, rowOf } = store([
+			row("mbx-parent", "Work", {
+				syncStatus: MailboxSyncStatus.failed,
+				pendingPath: "Projects",
+			}),
+			row("mbx-other", "Other", {
+				syncStatus: MailboxSyncStatus.failed,
+				pendingPath: "Projects/Old",
+			}),
+		]);
+		const { service } = queueOver(repo);
+
+		await service.dismissMailboxIntent("mbx-parent", "acc-1");
+
+		assert.equal(rowOf("mbx-other")?.syncStatus, MailboxSyncStatus.failed);
+		assert.equal(rowOf("mbx-other")?.pendingPath, "Projects/Old");
+	});
+
+	it("dismisses a failed delete on the named folder alone", async () => {
+		// No recorded target, so there is no subtree the intent was written over.
+		const { repo, rowOf } = store([
+			row("mbx-parent", "Work", { syncStatus: MailboxSyncStatus.failed }),
+			row("mbx-child", "Work/2026", { syncStatus: MailboxSyncStatus.failed }),
+		]);
+		const { service } = queueOver(repo);
+
+		await service.dismissMailboxIntent("mbx-parent", "acc-1");
+
+		assert.equal(rowOf("mbx-parent")?.syncStatus, MailboxSyncStatus.synced);
+		assert.equal(rowOf("mbx-child")?.syncStatus, MailboxSyncStatus.failed);
+	});
+
+	it("is a no-op on a folder with nothing to dismiss", async () => {
+		const { repo } = store([row("mbx-1", "Work")]);
+		const { service } = queueOver(repo);
+
+		const dismissed = await service.dismissMailboxIntent("mbx-1", "acc-1");
+
+		assert.equal(dismissed.syncStatus, MailboxSyncStatus.synced);
+	});
+
+	it("refuses with a 409 while a mutation is still in flight", async () => {
+		const { repo } = store([
+			row("mbx-1", "Work", {
+				syncStatus: MailboxSyncStatus.pending,
+				pendingPath: "Projects",
+			}),
+		]);
+		const { service } = queueOver(repo);
+
+		await assert.rejects(
+			service.dismissMailboxIntent("mbx-1", "acc-1"),
+			(error: unknown) =>
+				(error as { statusCode?: number }).statusCode === 409 &&
+				(error as Error).message === 'A rename is in progress for "Work".',
+		);
 	});
 });