@remit/mailbox-service 0.0.95 → 0.0.97

package/src/mailbox-sync.ts

@@ -11,10 +11,8 @@ import type {
 	MailboxItem,
 } from "@remit/data-ports";
 import {
-	CANONICAL_ROLES,
-	type CanonicalMailboxRoleValue,
-	ROLE_NAME_HINTS,
 	ROLE_SPECIAL_USE,
+	roleForFolderName,
 } from "@remit/data-ports/folder-role";
 import {
 	MailboxCursorState,
@@ -59,30 +57,6 @@ const areSpecialUseSetsEqual = (
 	return true;
 };
 
-/**
- * The role a folder's own leaf name is most conventionally for, read from the
- * one hint table every special-folder lookup shares (`@remit/data-ports`,
- * #837). A name that several roles list goes to the role that ranks it highest,
- * so `All Mail` is an All folder rather than a lookalike of Archive.
- *
- * A second copy of these names lived here, and it is the one that could destroy
- * something: it still called `Deleted` and `Bin` Trash names, which #843 dropped
- * precisely because they are ordinary folders a user keeps mail in — and this
- * lookup does not merely skip a folder, it deletes the row and everything the
- * client can see in it.
- */
-const roleForFolderName = (
-	name: string,
-): CanonicalMailboxRoleValue | undefined => {
-	let best: { role: CanonicalMailboxRoleValue; rank: number } | undefined;
-	for (const role of CANONICAL_ROLES) {
-		const rank = ROLE_NAME_HINTS[role]?.indexOf(name) ?? -1;
-		if (rank < 0) continue;
-		if (!best || rank < best.rank) best = { role, rank };
-	}
-	return best?.role;
-};
-
 /**
  * Account info needed for mailbox sync
  */

package/src/mailbox-upstream.ts

@@ -0,0 +1,83 @@
+const stringField = (value: unknown, key: string): string => {
+	if (!(value instanceof Object)) return "";
+	const field = Reflect.get(value, key);
+	return typeof field === "string" ? field : "";
+};
+
+/**
+ * Read a tagged-NO outcome out of an IMAP failure.
+ *
+ * The two outcomes below are each a folder operation finding the server already
+ * in the state it was asked for — the operation having happened, not failing.
+ * Reading them as failures marks the row `failed` and rethrows, and since folder
+ * management shares the account's per-account FIFO group with mailbox sync, that
+ * un-acked rethrow holds back every later sync for the account.
+ *
+ * Both places the server can say so are read. `message` carries it when the
+ * client raises the error itself; RFC 5530's response code and its text carry it
+ * when the server does. ImapFlow surfaces a tagged NO as a bare "Command failed"
+ * with the code on the error, which is why matching the message alone never
+ * caught a real Dovecot answer.
+ */
+const saidByServer = (error: Error): string =>
+	`${error.message} ${stringField(error, "responseText")}`;
+
+/** The folder is not on the server: a delete has nothing left to do. */
+export const isMailboxAbsentUpstream = (error: unknown): boolean => {
+	if (!(error instanceof Error)) return false;
+	if (stringField(error, "serverResponseCode") === "NONEXISTENT") return true;
+	return /not found|does ?n.?t exist/i.test(saidByServer(error));
+};
+
+/** The folder is already on the server: a create has nothing left to do. */
+export const isMailboxPresentUpstream = (error: unknown): boolean => {
+	if (!(error instanceof Error)) return false;
+	if (stringField(error, "serverResponseCode") === "ALREADYEXISTS") return true;
+	return /already exists/i.test(saidByServer(error));
+};
+
+/**
+ * Something after the server RENAME failed — the local settle, not the
+ * mutation. The rename landed, so this is never a refused rename: marking the
+ * rows `failed` would offer a retry of work the server has already done, and
+ * `fullPath` would go on naming a path the server no longer holds.
+ *
+ * It is rethrown rather than swallowed. The rows are still `pending` with their
+ * targets recorded, so the redelivery's guard passes and the settle runs again;
+ * swallowing it would ack the message and leave the subtree `pending` forever,
+ * skipped by message sync with no route out.
+ */
+/**
+ * The folder a rename was to move is confirmed gone: the server refused the
+ * RENAME as non-existent, and its own listing holds neither the path being left
+ * nor the path being aimed at.
+ *
+ * It is a distinct kind because it is the only answer that may remove a folder
+ * and its mail. Re-reading the server's response code at the call site would
+ * make every unclassifiable `NONEXISTENT` — a listing that could not be read, a
+ * path the comparison normalized wrongly — destroy the user's mail; here the
+ * decision is made once, where the evidence is.
+ */
+export class FolderGoneUpstreamError extends Error {
+	name = "FolderGoneUpstreamError";
+	readonly cause: unknown;
+
+	constructor(mailboxId: string, oldPath: string, cause: unknown) {
+		super(
+			`Folder ${mailboxId} is gone from the mail server: neither "${oldPath}" nor its rename target is listed`,
+		);
+		this.cause = cause;
+	}
+}
+
+export class FolderRenameSettleError extends Error {
+	name = "FolderRenameSettleError";
+	readonly cause: unknown;
+
+	constructor(mailboxId: string, confirmedPath: string, cause: unknown) {
+		super(
+			`Folder ${mailboxId} was renamed to "${confirmedPath}" but the local settle did not finish`,
+		);
+		this.cause = cause;
+	}
+}

package/src/message-sync-changedsince.test.ts

@@ -265,11 +265,18 @@ const buildHarness = (options: HarnessOptions): Harness => {
 		},
 	) as IAddressRepository;
 
+	// The rows sync reads back before it saves, to ask whether a message sighted
+	// here has left the folder its row points at (#1146). This harness stores
+	// none, so nothing is contested and the probe issues no IMAP.
+	const messageRepository = {
+		get: async () => [],
+	} as unknown as IMessageRepository;
+
 	const service = new MessageSyncService(
 		connectionFactory,
 		mailboxService,
 		noFolderRoles,
-		{} as IMessageRepository,
+		messageRepository,
 		{} as IEnvelopeRepository,
 		addressRepository,
 		threadMessageService,

package/src/message-sync-quarantine.test.ts

@@ -174,6 +174,13 @@ const buildHarness = (options: {
 		},
 	} satisfies IQuarantineRepository;
 
+	// The rows sync reads back before it saves, to ask whether a message sighted
+	// here has left the folder its row points at (#1146). This harness stores
+	// none, so nothing is contested and the probe issues no IMAP.
+	const messageRepository = {
+		get: async () => [],
+	} as unknown as IMessageRepository;
+
 	const service = new MessageSyncService(
 		{
 			getConnection: () => connection,
@@ -181,7 +188,7 @@ const buildHarness = (options: {
 		} as ManagedConnectionFactory,
 		mailboxService,
 		noFolderRoles,
-		{} as IMessageRepository,
+		messageRepository,
 		{} as IEnvelopeRepository,
 		{} as IAddressRepository,
 		threadMessageService,

package/src/message-sync-repoint.test.ts

@@ -11,13 +11,11 @@ import type {
 	ThreadMessageItem,
 	UpdateThreadMessageInput,
 } from "@remit/data-ports";
+import { deriveMessageId } from "@remit/data-ports/id";
 import { MessageStatus, MessageSyncStatus } from "@remit/domain-enums";
 import type { ManagedConnectionFactory } from "./connection-factory.js";
-import {
-	type AccountFolderRoles,
-	MessageSyncService,
-	repointsOnSighting,
-} from "./message-sync.js";
+import { type DepartureVerdicts, placementKey } from "./external-move.js";
+import { type AccountFolderRoles, MessageSyncService } from "./message-sync.js";
 import { folderRoles, NO_JUNK_ROLES } from "./test-helpers/folder-roles.js";
 import type { ImapEnvelope, ImapMessage } from "./types.js";
 
@@ -85,8 +83,22 @@ interface Observed {
 	threadUpdates: UpdateThreadMessageInput[];
 	reconciled: string[];
 	owned: boolean;
+	unresolved: boolean;
 }
 
+/**
+ * What `confirmDepartures` had answered about the stored placement by the time
+ * the batch was saved (#1146).
+ *
+ * - `departed` — the source folder no longer holds it: a move another client made.
+ * - `held` — the source folder still holds it: the labelled message, in two
+ *   folders at once.
+ * - `none` — no verdict at all: the source could not be asked this round.
+ * - `stale` — a verdict, but for a placement this row no longer has, because it
+ *   moved between the probe and the save.
+ */
+type Verdict = "departed" | "held" | "none" | "stale";
+
 /**
  * Sync one message out of `sighting`, against a database that already holds it
  * under `stored`. The account's Junk folder is `JUNK` and its Trash is `TRASH`,
@@ -97,12 +109,14 @@ const sync = async (
 	stored: MessageItem,
 	threadRow: ThreadMessageItem | null = threadRowIn(INBOX),
 	copiesHere: MessageItem[] = [],
+	verdict: Verdict = "departed",
 ): Promise<Observed> => {
 	const observed: Observed = {
 		repointedTo: [],
 		threadUpdates: [],
 		reconciled: [],
 		owned: false,
+		unresolved: false,
 	};
 
 	const messageService = {
@@ -164,6 +178,19 @@ const sync = async (
 		envelope,
 	} as unknown as ImapMessage;
 
+	const answeredFor = placementKey(
+		deriveMessageId("acct-1", envelope.messageId),
+		stored.mailboxId,
+		verdict === "stale" ? stored.uid + 1 : stored.uid,
+	);
+	const departures: DepartureVerdicts = {
+		departed:
+			verdict === "held" || verdict === "none"
+				? new Set()
+				: new Set([answeredFor]),
+		settled: verdict === "none" ? new Set() : new Set([answeredFor]),
+	};
+
 	const result = (await (
 		service as unknown as {
 			saveMessage: (
@@ -172,15 +199,24 @@ const sync = async (
 				accountConfigId: string,
 				msg: ImapMessage,
 				roles: AccountFolderRoles,
-			) => Promise<{ owned: boolean }>;
+				departures: DepartureVerdicts,
+			) => Promise<{ owned: boolean; unresolvedSighting: boolean }>;
 		}
-	).saveMessage(sighting, "acct-1", "cfg-1", msg, {
-		junkMailboxId: JUNK.mailboxId,
-		trashMailboxId: TRASH.mailboxId,
-		configJunkRoles: NO_JUNK_ROLES,
-	})) as { owned: boolean };
+	).saveMessage(
+		sighting,
+		"acct-1",
+		"cfg-1",
+		msg,
+		{
+			junkMailboxId: JUNK.mailboxId,
+			trashMailboxId: TRASH.mailboxId,
+			configJunkRoles: NO_JUNK_ROLES,
+		},
+		departures,
+	)) as { owned: boolean; unresolvedSighting: boolean };
 
 	observed.owned = result.owned;
+	observed.unresolved = result.unresolvedSighting;
 	return observed;
 };
 
@@ -227,6 +263,87 @@ describe("which folder a message the database already holds lives in", () => {
 		assert.equal(observed.owned, false);
 	});
 
+	/**
+	 * The reported bug (#1146): a message that legitimately sits in two real
+	 * folders — a Gmail user label, a Sieve `fileinto` beside a `keep`, a Sent
+	 * copy a list echoes back — was re-pointed out of the Inbox by whichever
+	 * folder the round enumerated last.
+	 */
+	it("leaves a labelled message in the folder that still holds it", async () => {
+		const observed = await sync(
+			mailboxAt("Receipts"),
+			storedIn(INBOX),
+			threadRowIn(INBOX),
+			[],
+			"held",
+		);
+
+		assert.deepEqual(observed.repointedTo, []);
+		assert.deepEqual(observed.threadUpdates, []);
+		assert.equal(observed.owned, false);
+	});
+
+	/**
+	 * A decided sighting is decided for good: the message is in two folders and
+	 * asking again next round would get the same answer. Only an UNDECIDED one
+	 * comes back, so a settled decline must not hold the watermark.
+	 */
+	it("finishes with a labelled message rather than holding the watermark for it", async () => {
+		const observed = await sync(
+			mailboxAt("Receipts"),
+			storedIn(INBOX),
+			threadRowIn(INBOX),
+			[],
+			"held",
+		);
+
+		assert.equal(observed.unresolved, false);
+	});
+
+	it("holds the watermark when the source folder could not be asked", async () => {
+		const observed = await sync(
+			JUNK,
+			storedIn(INBOX),
+			threadRowIn(INBOX),
+			[],
+			"none",
+		);
+
+		assert.deepEqual(observed.repointedTo, []);
+		assert.equal(observed.unresolved, true);
+	});
+
+	/**
+	 * The probe reads the row outside the transaction that acts on it, so a user
+	 * move landing in between leaves a verdict about a placement this row no
+	 * longer has. Spending it would re-point the row against an answer reached
+	 * for somewhere else.
+	 */
+	it("spends no verdict reached for a placement the row has since left", async () => {
+		const observed = await sync(
+			JUNK,
+			storedIn(INBOX),
+			threadRowIn(INBOX),
+			[],
+			"stale",
+		);
+
+		assert.deepEqual(observed.repointedTo, []);
+		assert.equal(observed.unresolved, true);
+	});
+
+	it("holds the watermark for nothing when the row is already ours", async () => {
+		const observed = await sync(
+			INBOX,
+			storedIn(INBOX),
+			threadRowIn(INBOX),
+			[],
+			"none",
+		);
+
+		assert.equal(observed.unresolved, false);
+	});
+
 	it("declines a sighting in a folder that copies every message", async () => {
 		const observed = await sync(ALL_MAIL, storedIn(INBOX));
 
@@ -300,95 +417,3 @@ describe("what a re-pointed message does to its sender's standing", () => {
 		assert.deepEqual(observed.reconciled, []);
 	});
 });
-
-describe("repointsOnSighting", () => {
-	it("refuses a Gmail virtual folder the server never flagged", () => {
-		assert.equal(
-			repointsOnSighting(mailboxAt("[Gmail]/All Mail"), storedIn(INBOX)),
-			false,
-		);
-	});
-
-	it("accepts a folder the user named after a virtual one", () => {
-		assert.equal(
-			repointsOnSighting(mailboxAt("Starred ideas"), storedIn(INBOX)),
-			true,
-		);
-	});
-
-	it("accepts an ordinary inbound row the sync path left pending", () => {
-		assert.equal(
-			repointsOnSighting(
-				JUNK,
-				storedIn(INBOX, { syncStatus: MessageSyncStatus.pending }),
-			),
-			true,
-		);
-	});
-
-	it("accepts a row a settled mutation marked synced", () => {
-		assert.equal(
-			repointsOnSighting(
-				JUNK,
-				storedIn(INBOX, { syncStatus: MessageSyncStatus.synced }),
-			),
-			true,
-		);
-	});
-
-	/**
-	 * The row `abandonDelete` hands back: reader refused the delete, put the
-	 * message back where the server still has it, and nothing else is coming
-	 * for the row. Reader shares its mailboxes, so the user moving that same
-	 * message in another client is ordinary — and before R3 the sighting was
-	 * refused on `syncStatus` alone and the row never followed the move.
-	 */
-	it("accepts a row whose delete was abandoned, so a move made elsewhere still lands", () => {
-		assert.equal(
-			repointsOnSighting(
-				JUNK,
-				storedIn(INBOX, {
-					status: MessageStatus.active,
-					syncStatus: MessageSyncStatus.abandoned,
-				}),
-			),
-			true,
-		);
-	});
-
-	it("accepts a row left `failed` by a transient attempt that has since settled", () => {
-		assert.equal(
-			repointsOnSighting(
-				JUNK,
-				storedIn(INBOX, { syncStatus: MessageSyncStatus.failed }),
-			),
-			true,
-		);
-	});
-
-	it("refuses a row whose own move is still in flight", () => {
-		assert.equal(
-			repointsOnSighting(
-				JUNK,
-				storedIn(INBOX, {
-					status: MessageStatus.moving,
-					syncStatus: MessageSyncStatus.pending,
-				}),
-			),
-			false,
-		);
-	});
-
-	it("refuses a row whose own delete is still in flight", () => {
-		assert.equal(
-			repointsOnSighting(
-				JUNK,
-				storedIn(INBOX, {
-					status: MessageStatus.deleting,
-					syncStatus: MessageSyncStatus.pending,
-				}),
-			),
-			false,
-		);
-	});
-});