@remit/imap-worker 0.0.72 → 0.0.74

package/src/handlers/mailbox-management.ts

@@ -1,7 +1,12 @@
 import { getClient } from "@remit/backend/client";
+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 {
@@ -10,7 +15,6 @@ import type {
 	MailboxManagementEvent,
 	MailboxRenameEvent,
 } from "../events.js";
-import { isNotFoundError } from "../is-not-found.js";
 import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
 import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
 
@@ -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/message-copy.test.ts

@@ -112,6 +112,10 @@ const deps = (): MessageCopyDeps =>
 				},
 				updateUid: record("message.updateUid"),
 				update: record("message.update"),
+				transitionPlacement: async (...args: unknown[]) => {
+					h.calls.push({ method: "message.transitionPlacement", args });
+					return { messageId: "new-msg" };
+				},
 				delete: record("message.delete"),
 			},
 			threadMessage: {
@@ -191,11 +195,9 @@ describe("handleMessageCopy", () => {
 			20,
 			"dst-mbx",
 		]);
-		const statusUpdate = called("message.update")[0];
-		assert.equal(
-			(statusUpdate?.args[1] as { syncStatus?: string })?.syncStatus,
-			"synced",
-		);
+		// `updateUid` writes the confirmed uid, `active` and `synced` in one
+		// statement, so there is no second, unpredicated write behind it.
+		assert.equal(called("message.update").length, 0);
 		assert.equal(called("threadMessage.update").length, 1);
 		assert.equal(h.disconnectCount, 1, "the scope is always disconnected");
 	});
@@ -212,11 +214,7 @@ describe("handleMessageCopy", () => {
 			42,
 			"dst-mbx",
 		]);
-		assert.equal(
-			(called("message.update")[0]?.args[1] as { syncStatus?: string })
-				?.syncStatus,
-			"synced",
-		);
+		assert.equal(called("message.update").length, 0);
 		assert.equal(called("threadMessage.update").length, 1);
 	});
 
@@ -263,11 +261,15 @@ describe("handleMessageCopy", () => {
 
 		assert.equal(copies, 1, "the COPY is issued once");
 		assert.equal(called("search").length, 0, "there is nothing to ask with");
-		const update = called("message.update")[0];
-		assert.equal((update?.args[1] as { status?: string })?.status, "deleted");
-		assert.equal(
-			(update?.args[1] as { syncStatus?: string })?.syncStatus,
-			"failed",
+		const [givenUp] = called("message.transitionPlacement");
+		assert.deepEqual(
+			givenUp?.args[2],
+			{
+				status: "deleted",
+				syncStatus: "abandoned",
+				abandonedMutation: "copy",
+			},
+			"a copy that gave up carries the give-up value and names itself",
 		);
 		assert.equal(called("message.delete").length, 0, "no row is thrown away");
 	});
@@ -302,8 +304,8 @@ describe("handleMessageCopy", () => {
 
 		assert.equal(copies, 1, "the redelivery issues no second COPY");
 		assert.equal(called("search").length, 0);
-		const settled = called("message.update").at(-1);
-		assert.equal((settled?.args[1] as { status?: string })?.status, "deleted");
+		const settled = called("message.transitionPlacement").at(-1);
+		assert.equal((settled?.args[2] as { status?: string })?.status, "deleted");
 	});
 
 	it("acks a copy that already settled without touching IMAP", async () => {
@@ -327,6 +329,7 @@ describe("handleMessageCopy", () => {
 
 		assert.equal(h.getConnectionCount, 0);
 		assert.equal(called("message.update").length, 0);
+		assert.equal(called("message.transitionPlacement").length, 0);
 	});
 
 	it("returns early without connecting when the account is soft-deleted", async () => {
@@ -358,6 +361,7 @@ describe("handleMessageCopy", () => {
 		assert.equal(h.getConnectionCount, 0);
 		assert.equal(called("message.updateUid").length, 0);
 		assert.equal(called("message.update").length, 0);
+		assert.equal(called("message.transitionPlacement").length, 0);
 	});
 
 	// Issue #1203. Both pauses are reached before `copyMessages`, so the COPY
@@ -427,7 +431,11 @@ describe("handleMessageCopy", () => {
 			"silence is never grounds to delete a row that may describe real mail",
 		);
 		assert.equal(
-			(called("message.update")[0]?.args[1] as { status?: string })?.status,
+			(
+				called("message.transitionPlacement")[0]?.args[2] as {
+					status?: string;
+				}
+			)?.status,
 			"deleted",
 		);
 	});
@@ -505,11 +513,33 @@ describe("handleMessageCopy", () => {
 
 		await handleMessageCopy(event, noopLogger, 1, deps());
 
-		const update = called("message.update")[0];
-		assert.equal((update?.args[1] as { status?: string })?.status, "deleted");
+		const [givenUp] = called("message.transitionPlacement");
+		assert.equal((givenUp?.args[2] as { status?: string })?.status, "deleted");
+		assert.equal(
+			(givenUp?.args[2] as { abandonedMutation?: string })?.abandonedMutation,
+			"copy",
+		);
 		assert.equal(called("createMailbox").length, 0);
 	});
 
+	// The guard asks whether THIS copy is still outstanding, not whether anything
+	// is. A row a delete has claimed is `deleting`, and reading that as unsettled
+	// let a redelivery COPY the message a second time — COPY has no source-side
+	// effect to make that a no-op, so the duplicate is permanent.
+	it("skips a redelivered copy whose row a delete has claimed", async () => {
+		let copies = 0;
+		h.connection.copyMessages = async () => {
+			copies += 1;
+			return { uidMap: new Map([[10, 20]]) };
+		};
+		h.copyRow = { ...unsettledCopyRow(), status: "deleting" };
+
+		await handleMessageCopy(event, noopLogger, 2, deps());
+
+		assert.equal(copies, 0, "no second copy is issued");
+		assert.equal(called("message.updateUid").length, 0);
+	});
+
 	it("marks failed and rethrows on an unclassified IMAP error within the budget", async () => {
 		h.connection.copyMessages = async () => {
 			throw new Error("server exploded");
@@ -520,11 +550,12 @@ describe("handleMessageCopy", () => {
 			/server exploded/,
 		);
 
-		const update = called("message.update")[0];
-		assert.equal(
-			(update?.args[1] as { syncStatus?: string })?.syncStatus,
-			"failed",
-		);
+		// The attempt marker is a transition too, predicated on this copy still
+		// being outstanding: a row another mutation has claimed keeps its own
+		// placement rather than picking up this attempt's failure.
+		const [marker] = called("message.transitionPlacement");
+		assert.deepEqual(marker?.args[1], { status: "moving" });
+		assert.deepEqual(marker?.args[2], { syncStatus: "failed" });
 	});
 
 	it("settles on the destination UID instead of dead-lettering the last attempt", async () => {

package/src/handlers/message-copy.ts

@@ -1,11 +1,15 @@
 import { getClient } from "@remit/backend/client";
-import { MessageStatus, MessageSyncStatus } from "@remit/domain-enums";
+import { isNotFoundError } from "@remit/data-ports/errors";
+import {
+	MessageMutation,
+	MessageStatus,
+	MessageSyncStatus,
+} from "@remit/domain-enums";
 import type { Logger } from "@remit/logger-lambda";
 import {
 	guardConnectionCursor,
 	type IImapConnection,
 	isCursorRebuildNeeded,
-	isPlacementUnsettled,
 	MailboxCursorPausedError,
 	reconcileStaleMessage,
 } from "@remit/mailbox-service";
@@ -14,7 +18,6 @@ import { isAccountDeleted } from "../account-check.js";
 import { createConnectionScopeWithCredentials } from "../connection-scope.js";
 import { emitEvent } from "../emit.js";
 import type { MessageCopyEvent } from "../events.js";
-import { isNotFoundError } from "../is-not-found.js";
 import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
 import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
 import {
@@ -147,7 +150,12 @@ export const handleMessageCopy = async (
 	// This copy already settled — `updateUid` cleared `status: moving` when the
 	// server confirmed it. A redelivery reaching here would COPY the message a
 	// second time, and COPY has no source-side effect to make that a no-op.
-	if (!isPlacementUnsettled(copyRow)) {
+	//
+	// `moving` specifically, not the shared unsettled predicate: the question is
+	// whether THIS copy is still outstanding, and a `deleting` row is somebody
+	// else's work — reading it as unsettled is what would let the second COPY
+	// through.
+	if (copyRow.status !== MessageStatus.moving) {
 		log.info(
 			{ accountId, newMessageId, uid: copyRow.uid, status: copyRow.status },
 			"Skipping MESSAGE_COPY: the copy already settled against confirmed IMAP state",
@@ -206,17 +214,15 @@ export const handleMessageCopy = async (
 			};
 
 			const settleCopied = async (newUid: number): Promise<void> => {
+				// `updateUid` writes the confirmed uid, `active` and `synced` in one
+				// statement, so the second write this used to make said nothing the
+				// first had not — and said it without a predicate.
 				await messageService.updateUid(
 					newMessageId,
 					newUid,
 					destinationMailboxId,
 				);
 
-				await messageService.update(newMessageId, {
-					status: MessageStatus.active,
-					syncStatus: MessageSyncStatus.synced,
-				});
-
 				const threadMessage = await threadMessageService.findByMessageId(
 					account.accountConfigId,
 					newMessageId,
@@ -293,10 +299,20 @@ export const handleMessageCopy = async (
 			// that turns out to be there. Silence buys the safer half of one pair
 			// and the worse half of the other.
 			const settleBroken = async (reason: string): Promise<void> => {
-				await messageService.update(newMessageId, {
-					status: MessageStatus.deleted,
-					syncStatus: MessageSyncStatus.failed,
-				});
+				// A transition, not a plain update (imap-mutations R3): the copy row
+				// is only this handler's to settle while its own placement is still
+				// unsettled. The row it leaves is `deleted`, so no listing carries it
+				// and the marker is read by nothing — it is written anyway, because a
+				// give-up that does not name itself is the gap #1229 came from.
+				await messageService.transitionPlacement(
+					newMessageId,
+					{ status: MessageStatus.moving },
+					{
+						status: MessageStatus.deleted,
+						syncStatus: MessageSyncStatus.abandoned,
+						abandonedMutation: MessageMutation.copy,
+					},
+				);
 				log.error(
 					{
 						alert: "message_copy_unconfirmed",
@@ -495,10 +511,15 @@ export const handleMessageCopy = async (
 							{ sourceMessageId, uid },
 							"Source message not found on IMAP, marking copy as failed",
 						);
-						await messageService.update(newMessageId, {
-							status: MessageStatus.deleted,
-							syncStatus: MessageSyncStatus.failed,
-						});
+						await messageService.transitionPlacement(
+							newMessageId,
+							{ status: MessageStatus.moving },
+							{
+								status: MessageStatus.deleted,
+								syncStatus: MessageSyncStatus.abandoned,
+								abandonedMutation: MessageMutation.copy,
+							},
+						);
 						return;
 					}
 
@@ -506,9 +527,11 @@ export const handleMessageCopy = async (
 						// Transient copy failure — expected (connections drop). Queue
 						// redelivery retries, and the probe above keeps the retry from
 						// copying the message twice.
-						await messageService.update(newMessageId, {
-							syncStatus: MessageSyncStatus.failed,
-						});
+						await messageService.transitionPlacement(
+							newMessageId,
+							{ status: MessageStatus.moving },
+							{ syncStatus: MessageSyncStatus.failed },
+						);
 						throw error;
 					}
 

package/src/handlers/message-delete-terminal.ts

@@ -2,14 +2,14 @@ import type {
 	IMessageRepository,
 	IThreadMessageRepository,
 } from "@remit/data-ports";
-import { MessageSyncStatus } from "@remit/domain-enums";
+import { MessageMutation, MessageSyncStatus } from "@remit/domain-enums";
 import {
 	type IImapConnection,
 	isMessageGoneFromOpenMailbox,
 	reconcileStaleMessage,
+	restoreSourcePlacement,
 	type StaleMessageReconcileDeps,
 } from "@remit/mailbox-service";
-import { restoreSourcePlacement } from "./restore-source-placement.js";
 
 export interface MessageDeleteTerminalLogger {
 	info(obj: Record<string, unknown>, msg: string): void;
@@ -18,7 +18,7 @@ export interface MessageDeleteTerminalLogger {
 
 export interface ResolveExhaustedMessageDeleteDeps
 	extends StaleMessageReconcileDeps {
-	messageService: Pick<IMessageRepository, "delete" | "updateForMove">;
+	messageService: Pick<IMessageRepository, "delete" | "transitionPlacement">;
 	threadMessageService: Pick<
 		IThreadMessageRepository,
 		"findAllByMessageId" | "deleteMany" | "update"
@@ -60,7 +60,7 @@ export interface ResolveExhaustedMessageDeleteResult {
  *    effect, but it keeps failing: broken code or a broken account, not a
  *    transient blip. The row is put back where the server has just said the
  *    message is: `mailboxId` and `uid` return to the delete's source pair, and
- *    the thread rows lose the deletion mark the optimistic `updateForMove`
+ *    the thread rows lose the deletion mark the optimistic transition
  *    wrote (issue #1098).
  *
  *    Settling `status` to `active` while leaving `mailboxId` on Trash is what
@@ -132,9 +132,13 @@ export const resolveExhaustedMessageDeleteFailure = async (
 		sourceMailboxId,
 		uid,
 		// The probe above just confirmed the pair, so the row is a faithful
-		// projection of the source again. The delete's own failure is the alert,
-		// not a `failed` left on a row nothing is still trying to delete.
-		syncStatus: MessageSyncStatus.synced,
+		// projection of the source again — and the delete the user asked for did
+		// not happen, with nothing left to try it. `abandoned` is the value that
+		// says so without claiming a retry is coming (imap-mutations R3); the
+		// alert stays for the operator, and the mutation names itself so the
+		// reading pane offers the right way out (issue #1229).
+		syncStatus: MessageSyncStatus.abandoned,
+		abandonedMutation: MessageMutation.delete,
 	});
 
 	return { outcome: "broken" };