@remit/imap-worker 0.0.73 → 0.0.74

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/imap-worker",
-  "version": "0.0.73",
+  "version": "0.0.74",
   "type": "module",
   "main": "dist/index.js",
   "exports": {

package/src/handlers/mailbox-management.test.ts

@@ -42,6 +42,7 @@ interface Harness {
 	} | null;
 	connection: Connection;
 	mailboxUpdateError?: Error;
+	mailboxRowGone?: boolean;
 	disconnectCount: number;
 }
 
@@ -96,6 +97,13 @@ const deps = (): MailboxManagementDeps =>
 					h.calls.push({ method: "mailbox.update", args });
 					if (h.mailboxUpdateError) throw h.mailboxUpdateError;
 				},
+				// The conditional write the folder state now goes through: a row
+				// that is gone matches nothing, so the loser gets a null rather
+				// than a throw and the handler raises the NotFoundError itself.
+				transition: async (...args: unknown[]) => {
+					h.calls.push({ method: "mailbox.transition", args });
+					return h.mailboxRowGone ? null : {};
+				},
 				findByPathPrefix: async (...args: unknown[]) => {
 					h.calls.push({ method: "mailbox.findByPathPrefix", args });
 					return [];
@@ -147,6 +155,12 @@ const called = (method: string): Call[] =>
 const lastUpdate = (): Record<string, unknown> =>
 	(called("mailbox.update").at(-1)?.args[2] ?? {}) as Record<string, unknown>;
 
+const lastSettle = (): { to?: string; set?: Record<string, unknown> } =>
+	(called("mailbox.transition").at(-1)?.args[2] ?? {}) as {
+		to?: string;
+		set?: Record<string, unknown>;
+	};
+
 describe("processMailboxManagement — MAILBOX_CREATE", () => {
 	beforeEach(() => {
 		h = fresh();
@@ -160,8 +174,8 @@ describe("processMailboxManagement — MAILBOX_CREATE", () => {
 			uidValidity: 7,
 			uidNext: 42,
 			messageCount: 3,
-			syncStatus: "synced",
 		});
+		assert.equal(lastSettle().to, "synced");
 		assert.equal(h.disconnectCount, 1, "the scope is always disconnected");
 	});
 
@@ -183,7 +197,8 @@ describe("processMailboxManagement — MAILBOX_CREATE", () => {
 
 		await processMailboxManagement(createEvent, noopLogger, deps());
 
-		assert.deepEqual(lastUpdate(), { syncStatus: "synced" });
+		assert.equal(called("mailbox.update").length, 0);
+		assert.equal(lastSettle().to, "synced");
 	});
 
 	it("treats an already-existing folder as success rather than a failure", async () => {
@@ -193,7 +208,7 @@ describe("processMailboxManagement — MAILBOX_CREATE", () => {
 
 		await processMailboxManagement(createEvent, noopLogger, deps());
 
-		assert.deepEqual(lastUpdate(), { syncStatus: "synced" });
+		assert.equal(lastSettle().to, "synced");
 	});
 
 	it("marks the mailbox failed and rethrows on any other create error", async () => {
@@ -206,14 +221,14 @@ describe("processMailboxManagement — MAILBOX_CREATE", () => {
 			/server exploded/,
 		);
 
-		assert.deepEqual(lastUpdate(), { syncStatus: "failed" });
+		assert.equal(lastSettle().to, "failed");
 		assert.equal(h.disconnectCount, 1);
 	});
 
 	it("acks terminally without rethrowing when the mailbox row was deleted mid-create (#289)", async () => {
-		// The status write-back throws NotFoundError because the row is gone; the
-		// create is moot and must not poison the account's FIFO.
-		h.mailboxUpdateError = notFoundError();
+		// The settle matches no row because the row is gone; the create is moot
+		// and must not poison the account's FIFO.
+		h.mailboxRowGone = true;
 
 		await processMailboxManagement(createEvent, noopLogger, deps());
 
@@ -247,17 +262,14 @@ describe("processMailboxManagement — MAILBOX_RENAME", () => {
 		h = fresh();
 	});
 
-	it("renames on the server and clears the pending oldPath", async () => {
+	it("renames on the server and settles the row", async () => {
 		await processMailboxManagement(renameEvent, noopLogger, deps());
 
 		assert.deepEqual(called("connection.renameMailbox")[0]?.args, [
 			"Archive",
 			"Archive 2024",
 		]);
-		assert.deepEqual(lastUpdate(), {
-			oldPath: undefined,
-			syncStatus: "synced",
-		});
+		assert.equal(lastSettle().to, "synced");
 	});
 
 	it("drops the local row when the source folder is gone on the server", async () => {
@@ -268,14 +280,14 @@ describe("processMailboxManagement — MAILBOX_RENAME", () => {
 		await processMailboxManagement(renameEvent, noopLogger, deps());
 
 		assert.deepEqual(called("mailbox.delete")[0]?.args, ["acc-1", "mbx-1"]);
-		assert.equal(called("mailbox.update").length, 0);
+		assert.equal(called("mailbox.transition").length, 0);
 	});
 
 	it("acks terminally without rethrowing when the rollback write finds the row gone", async () => {
 		h.connection.renameMailbox = async () => {
 			throw new Error("server exploded");
 		};
-		h.mailboxUpdateError = notFoundError();
+		h.mailboxRowGone = true;
 
 		await processMailboxManagement(renameEvent, noopLogger, deps());
 
@@ -292,11 +304,8 @@ describe("processMailboxManagement — MAILBOX_RENAME", () => {
 			/server exploded/,
 		);
 
-		assert.deepEqual(lastUpdate(), {
-			fullPath: "Archive",
-			oldPath: undefined,
-			syncStatus: "failed",
-		});
+		assert.equal(lastSettle().to, "failed");
+		assert.equal(lastSettle().set?.fullPath, "Archive");
 	});
 });
 
@@ -329,7 +338,7 @@ describe("processMailboxManagement — MAILBOX_DELETE", () => {
 
 		await processMailboxManagement(deleteEvent, noopLogger, deps());
 
-		assert.deepEqual(lastUpdate(), { syncStatus: "synced" });
+		assert.equal(lastSettle().to, "synced");
 		assert.equal(called("mailbox.delete").length, 0);
 	});
 
@@ -343,14 +352,14 @@ describe("processMailboxManagement — MAILBOX_DELETE", () => {
 			/server exploded/,
 		);
 
-		assert.deepEqual(lastUpdate(), { syncStatus: "failed" });
+		assert.equal(lastSettle().to, "failed");
 	});
 
 	it("acks terminally without rethrowing when the rollback write finds the row gone", async () => {
 		h.connection.deleteMailbox = async () => {
 			throw new Error("server exploded");
 		};
-		h.mailboxUpdateError = notFoundError();
+		h.mailboxRowGone = true;
 
 		await processMailboxManagement(deleteEvent, noopLogger, deps());
 
@@ -381,7 +390,7 @@ describe("processMailboxManagement — a tagged NO the server means as success (
 			processMailboxManagement(deleteEvent, noopLogger, deps()),
 		);
 		assert.deepEqual(called("mailbox.delete")[0]?.args, ["acc-1", "mbx-1"]);
-		assert.equal(called("mailbox.update").length, 0);
+		assert.equal(called("mailbox.transition").length, 0);
 	});
 
 	it("still marks failed and rethrows when the server fails for any other reason", async () => {
@@ -396,7 +405,7 @@ describe("processMailboxManagement — a tagged NO the server means as success (
 			processMailboxManagement(deleteEvent, noopLogger, deps()),
 			/Command failed/,
 		);
-		assert.deepEqual(lastUpdate(), { syncStatus: "failed" });
+		assert.equal(lastSettle().to, "failed");
 	});
 
 	/**
@@ -416,7 +425,7 @@ describe("processMailboxManagement — a tagged NO the server means as success (
 		await assert.doesNotReject(
 			processMailboxManagement(createEvent, noopLogger, deps()),
 		);
-		assert.deepEqual(lastUpdate(), { syncStatus: "synced" });
+		assert.equal(lastSettle().to, "synced");
 	});
 
 	it("still marks failed and rethrows when a CREATE fails for any other reason", async () => {
@@ -431,7 +440,7 @@ describe("processMailboxManagement — a tagged NO the server means as success (
 			processMailboxManagement(createEvent, noopLogger, deps()),
 			/Command failed/,
 		);
-		assert.deepEqual(lastUpdate(), { syncStatus: "failed" });
+		assert.equal(lastSettle().to, "failed");
 	});
 
 	it("reads NONEXISTENT on a RENAME as the source folder being gone", async () => {
@@ -460,6 +469,6 @@ describe("processMailboxManagement — a tagged NO the server means as success (
 			processMailboxManagement(renameEvent, noopLogger, deps()),
 			/Command failed/,
 		);
-		assert.equal(lastUpdate()?.syncStatus, "failed");
+		assert.equal(lastSettle().to, "failed");
 	});
 });

package/src/handlers/mailbox-management.ts

@@ -1,8 +1,12 @@
 import { getClient } from "@remit/backend/client";
-import { isNotFoundError } from "@remit/data-ports/errors";
+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-lambda";
-import { MailboxManagementService } from "@remit/mailbox-service";
+import {
+	EVERY_MAILBOX_STATE,
+	MailboxManagementService,
+} from "@remit/mailbox-service";
 import { isAccountDeleted } from "../account-check.js";
 import { createConnectionScopeWithCredentials } from "../connection-scope.js";
 import type {
@@ -59,6 +63,36 @@ const isMailboxAbsentUpstream = (error: unknown): boolean => {
 	return /not found|does ?n.?t exist/i.test(saidByServer(error));
 };
 
+/**
+ * Write the outcome of a folder operation back, as the conditional write that
+ * is the only way to write a folder's state
+ * (docs/architecture/folder-rename-and-delete.md D3).
+ *
+ * The from-set is every state because that is what these write-backs decide
+ * against today — they are the unconditional writes they replace, moved onto
+ * the door. #363 narrows each to the state its intent recorded, and gives a
+ * lost predicate its `superseded` outcome. A null means the row is gone, which
+ * is the NotFoundError the whole-chain guards below classify as the user having
+ * deleted the folder mid-sync.
+ */
+const recordOutcome = async (
+	mailboxService: Pick<IMailboxRepository, "transition">,
+	accountId: string,
+	mailboxId: string,
+	to: (typeof MailboxSyncStatus)[keyof typeof MailboxSyncStatus],
+	confirmedPath?: string,
+): Promise<void> => {
+	const written = await mailboxService.transition(accountId, mailboxId, {
+		from: EVERY_MAILBOX_STATE,
+		to,
+		// `failed` keeps whatever rename target the row carries, so the UI can
+		// name what the rename was aiming at (T6); every other outcome drops it,
+		// which the transition does on its own.
+		set: confirmedPath !== undefined ? { fullPath: confirmedPath } : {},
+	});
+	if (!written) throw new NotFoundError(`Mailbox not found: ${mailboxId}`);
+};
+
 /** The folder is already on the server: a create has nothing left to do. */
 const isMailboxPresentUpstream = (error: unknown): boolean => {
 	if (!(error instanceof Error)) return false;
@@ -158,13 +192,19 @@ const handleCreate = async (
 								{ accountId, mailboxId, path },
 								"Mailbox already exists, marking as synced",
 							);
-							await mailboxService.update(accountId, mailboxId, {
-								syncStatus: MailboxSyncStatus.synced,
-							});
+							await recordOutcome(
+								mailboxService,
+								accountId,
+								mailboxId,
+								MailboxSyncStatus.synced,
+							);
 						} else {
-							await mailboxService.update(accountId, mailboxId, {
-								syncStatus: MailboxSyncStatus.failed,
-							});
+							await recordOutcome(
+								mailboxService,
+								accountId,
+								mailboxId,
+								MailboxSyncStatus.failed,
+							);
 							throw error;
 						}
 					})
@@ -269,11 +309,13 @@ const handleRename = async (
 							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,
-							});
+							await recordOutcome(
+								mailboxService,
+								accountId,
+								mailboxId,
+								MailboxSyncStatus.failed,
+								oldPath,
+							);
 							throw error;
 						}
 					})
@@ -370,9 +412,12 @@ const handleDelete = async (
 							error.message.includes("Cannot delete INBOX")
 						) {
 							// Restore the mailbox
-							await mailboxService.update(accountId, mailboxId, {
-								syncStatus: MailboxSyncStatus.synced,
-							});
+							await recordOutcome(
+								mailboxService,
+								accountId,
+								mailboxId,
+								MailboxSyncStatus.synced,
+							);
 							log.error(
 								{ accountId, mailboxId, path },
 								"Cannot delete INBOX, restoring mailbox",
@@ -380,9 +425,12 @@ const handleDelete = async (
 							// Don't rethrow - this is an expected error
 						} else {
 							// Restore the mailbox on other errors
-							await mailboxService.update(accountId, mailboxId, {
-								syncStatus: MailboxSyncStatus.failed,
-							});
+							await recordOutcome(
+								mailboxService,
+								accountId,
+								mailboxId,
+								MailboxSyncStatus.failed,
+							);
 							throw error;
 						}
 					})

package/src/handlers/sync-message-body.ts

@@ -6,7 +6,7 @@ import {
 	BodySyncService,
 	guardConnectionCursor,
 	isCursorRebuildNeeded,
-	isFolderOffServer,
+	isFolderMutationInFlight,
 	MailboxCursorPausedError,
 	PlacementMoveService,
 	QuarantineService,
@@ -179,10 +179,10 @@ export const syncMessageBody = async (
 			// A folder still `pending` is terminal for the same reason: the batch
 			// was cut before the folder reached the server, so there is nothing
 			// there to fetch from and no retry that changes it.
-			if (!mailbox || isFolderOffServer(mailbox)) {
+			if (!mailbox || isFolderMutationInFlight(mailbox)) {
 				log.warn(
 					{ accountId, mailboxId, eventId: event.eventId },
-					"Skipping SYNC_MESSAGE_BODY: the server does not hold this folder",
+					"Skipping SYNC_MESSAGE_BODY: a folder mutation is in flight",
 				);
 				return;
 			}

package/src/handlers/sync-messages.test.ts

@@ -320,7 +320,7 @@ describe("syncMessages — terminal handling of events for a deleted mailbox (is
 			"a deleted mailbox must short-circuit before the OAuth/connection lifecycle",
 		);
 		const skip = warns.find((w) =>
-			w.msg.includes("the server does not hold this folder"),
+			w.msg.includes("a folder mutation is in flight"),
 		);
 		assert.ok(skip, "expected a WARN naming the skipped deleted mailbox");
 		assert.equal(skip.fields.accountId, "acc-1");
@@ -371,9 +371,7 @@ describe("syncMessages — terminal handling of events for a deleted mailbox (is
 
 			assert.equal(harness.lifecycleCalls, 0);
 			assert.ok(
-				warns.find((w) =>
-					w.msg.includes("the server does not hold this folder"),
-				),
+				warns.find((w) => w.msg.includes("a folder mutation is in flight")),
 			);
 		});
 	}

package/src/handlers/sync-messages.ts

@@ -19,7 +19,7 @@ import { type Logger, recordImapFailure } from "@remit/logger-lambda";
 import { RefreshTokenError } from "@remit/mail-oauth-service";
 import {
 	createManagedConnectionFactory,
-	isMailboxNotOnServer,
+	isMailboxMutationInFlight,
 	MailConnectionError,
 	type MailCredentials,
 	MessageSyncService,
@@ -133,17 +133,23 @@ export const syncMessages = async (
 		return;
 	}
 
-	// A SYNC_MESSAGES trigger can address a folder the server does not hold: the
-	// fan-out enqueues one for a folder whose own create has not landed yet, and
-	// a `hasMore` next-batch or a periodic tick outlives a folder the user
-	// deleted. Such an event can never succeed on retry, and the account's
-	// per-group FIFO ordering lets that one poison message stall the
-	// whole account's message pipeline for the full visibility window (issue
-	// #287, #339). A folder the server does not hold — not yet created, or being
-	// deleted — is an expected terminal outcome, not an infra failure: ack the
-	// event with a WARN.
+	// A SYNC_MESSAGES trigger can address a folder a mutation still owns: the
+	// fan-out enqueues one for a folder whose own create has not landed yet, a
+	// `hasMore` next-batch or a periodic tick outlives a folder the user
+	// deleted, and a rename in flight leaves the folder on the server but under
+	// the worker that is moving it. Such an event can never succeed on retry,
+	// and the account's per-group FIFO ordering lets that one poison message
+	// stall the whole account's message pipeline for the full visibility window
+	// (issue #287, #339). A folder with a create, rename or delete outstanding
+	// is an expected terminal outcome, not an infra failure: ack the event with
+	// a WARN. The rename case is conservative rather than necessary — syncing it
+	// would be safe — and keeps the guard a single expression (D12).
 	if (
-		await isMailboxNotOnServer(mailboxService, event.accountId, event.mailboxId)
+		await isMailboxMutationInFlight(
+			mailboxService,
+			event.accountId,
+			event.mailboxId,
+		)
 	) {
 		log.warn(
 			{
@@ -152,7 +158,7 @@ export const syncMessages = async (
 				eventId: event.eventId,
 				event: event.type,
 			},
-			"Skipping SYNC_MESSAGES: the server does not hold this folder",
+			"Skipping SYNC_MESSAGES: a folder mutation is in flight",
 		);
 		return;
 	}
@@ -214,7 +220,7 @@ export const syncMessages = async (
 						// never become the failure that is reported. A read that cannot answer
 						// leaves the round on the loud path below, with the real error and the
 						// state write that goes with it intact.
-						const folderIsGone = await isMailboxNotOnServer(
+						const folderIsGone = await isMailboxMutationInFlight(
 							mailboxService,
 							event.accountId,
 							event.mailboxId,