@remit/imap-worker 0.0.90 → 0.0.91

package/src/handlers/placement-move-push.test.ts

@@ -1,137 +0,0 @@
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import {
-	eml,
-	FakeImapServer,
-} from "@remit/mailbox-service/test-helpers/fake-imap";
-import { attemptMove } from "./placement-move-push.js";
-
-const HEADER = "<abc@example.com>";
-
-/** Junk holds the message at uid 42; INBOX is where the placement sends it. */
-const arrange = (
-	options: { inJunk?: boolean; inInbox?: boolean; inboxExists?: boolean } = {},
-) => {
-	const server = new FakeImapServer();
-	server.addFolder("Junk");
-	if (options.inboxExists !== false) server.addFolder("INBOX");
-	if (options.inJunk !== false)
-		server.deliver("Junk", eml({ "Message-ID": HEADER }), { uid: 42 });
-	if (options.inInbox) server.deliver("INBOX", eml({ "Message-ID": HEADER }));
-	return server;
-};
-
-const move = (
-	server: FakeImapServer,
-	header: string | undefined = HEADER,
-	source = server.connection(),
-) => attemptMove(source, server.connection(), "Junk", "INBOX", 42, header);
-
-describe("attemptMove — the IMAP push (issue #1271)", () => {
-	it("moves the message and returns the uid from the COPYUID map", async () => {
-		const server = arrange();
-
-		const outcome = await move(server);
-
-		assert.deepEqual(outcome, {
-			kind: "moved",
-			newUid: server.uids("INBOX", HEADER)[0],
-		});
-		assert.deepEqual(server.uids("Junk"), []);
-	});
-
-	it("answers trycreate when the destination does not exist yet", async () => {
-		const server = arrange({ inboxExists: false });
-
-		assert.equal((await move(server)).kind, "trycreate");
-	});
-
-	it("propagates any other failure untouched for the caller to retry", async () => {
-		const server = arrange();
-		server.failNext.MOVE = new Error("ECONNRESET");
-
-		await assert.rejects(move(server), /ECONNRESET/);
-	});
-
-	// PR #1289 review finding 2: neither a missing COPYUID entry nor an explicit
-	// not-found is trusted without asking the server.
-	it("confirms a move by Message-ID when the server sends no COPYUID", async () => {
-		const server = arrange();
-		server.uidplus = false;
-
-		const outcome = await move(server);
-
-		assert.deepEqual(outcome, {
-			kind: "moved",
-			newUid: server.uids("INBOX", HEADER)[0],
-		});
-	});
-
-	it("confirms a move by Message-ID when the server answers NONEXISTENT for one that landed", async () => {
-		const server = arrange({ inJunk: false, inInbox: true });
-		server.failNext.MOVE = new Error(
-			"Command failed: NONEXISTENT no such message",
-		);
-
-		const outcome = await move(server);
-
-		assert.deepEqual(outcome, {
-			kind: "moved",
-			newUid: server.uids("INBOX", HEADER)[0],
-		});
-	});
-
-	// Issue #1122: the destination already held an older copy, and the row must
-	// bind to the one this MOVE delivered.
-	it("binds to the newest copy when the destination already held an older one", async () => {
-		const server = arrange({ inInbox: true });
-		server.uidplus = false;
-
-		const outcome = await move(server);
-
-		assert.deepEqual(outcome, {
-			kind: "moved",
-			newUid: Math.max(...server.uids("INBOX", HEADER)),
-		});
-	});
-
-	it("never settles a move the destination does not confirm while the source still holds it", async () => {
-		const server = arrange();
-		server.uidplus = false;
-		server.ignoreNext.add("MOVE");
-
-		await assert.rejects(move(server), /unresolved/);
-	});
-
-	it("never settles when the source FETCH drops the row for a message the server still lists", async () => {
-		const server = arrange();
-		server.uidplus = false;
-		server.ignoreNext.add("MOVE");
-		const source = server.connection();
-		source.fetchMessages = async () => [];
-
-		await assert.rejects(move(server, HEADER, source), /unresolved/);
-	});
-
-	it("answers not-found once neither folder holds the message", async () => {
-		const server = arrange({ inJunk: false });
-		server.uidplus = false;
-
-		assert.equal((await move(server)).kind, "not-found");
-	});
-
-	it("falls back to the source alone without a Message-ID, and still never settles while it holds the message", async () => {
-		const server = arrange();
-		server.uidplus = false;
-		server.ignoreNext.add("MOVE");
-
-		await assert.rejects(move(server, undefined));
-	});
-
-	it("answers not-found without a Message-ID once the source no longer holds the message", async () => {
-		const server = arrange({ inJunk: false });
-		server.uidplus = false;
-
-		assert.equal((await move(server, undefined)).kind, "not-found");
-	});
-});

package/src/handlers/placement-move-push.ts

@@ -1,478 +0,0 @@
-import { getClient } from "@remit/backend/client";
-import { MessageMutation, MessageSyncStatus } from "@remit/domain-enums";
-import type { Logger } from "@remit/logger";
-import { recordImapFailure } from "@remit/logger-lambda/metrics";
-import {
-	guardConnectionCursor,
-	type IImapConnection,
-	isCursorRebuildNeeded,
-	isMessageGoneFromOpenMailbox,
-	MailboxCursorPausedError,
-	resolveExhaustedPlacementMoveFailure,
-	restoreSourcePlacement,
-} from "@remit/mailbox-service";
-import { attemptBudget } from "@remit/sqs-client/attempt-budget";
-import { isAccountDeleted } from "../account-check.js";
-import { createConnectionScopeWithCredentials } from "../connection-scope.js";
-import { createEmitEvent } from "../emit.js";
-import type { PlacementMovePushEvent } from "../events.js";
-import { findMailboxRow } from "../mailbox-row.js";
-import type { WorkerQueues } from "../queues.js";
-import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
-import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
-import {
-	buildThreadMessageMoveUpdate,
-	emitMailboxResync,
-	emitMoveResync,
-	searchMailboxForHighestMessageIdUid,
-} from "./message-move.js";
-import { probeableMessageIdHeader } from "./probe-message-id.js";
-
-export const getPlacementMoveMaxAttempts = (
-	processEnv: NodeJS.ProcessEnv = process.env,
-): number => attemptBudget("PLACEMENT_MOVE_MAX_ATTEMPTS", 3, processEnv);
-
-export const PLACEMENT_MOVE_MAX_ATTEMPTS = getPlacementMoveMaxAttempts();
-
-interface MoveOutcome {
-	kind: "moved" | "not-found" | "trycreate";
-	newUid?: number;
-}
-
-/**
- * Attempt the IMAP MOVE.
- *
- * Takes two connection handles rather than one: `sourceConnection` and
- * `destinationConnection` wrap the SAME underlying connection but are each
- * cursor-guarded (#1272) against their OWN mailbox — a `guardConnectionCursor`
- * wrap binds `openBox` checks to whichever ONE mailbox snapshot it was built
- * with, so verifying at the destination must never run through the source's
- * guard (it would compare the destination's served UIDVALIDITY against the
- * source's stored one and misfire).
- *
- * - `moved` with a `newUid` — confirmed, either via COPYUID or (see below)
- *   an explicit destination verification.
- * - `trycreate` — the destination mailbox doesn't exist yet; the caller
- *   creates it and retries.
- * - `not-found` — confirmed absent from BOTH source and destination. Only
- *   this outcome supersedes the pending-move marker (drops it, reconciles
- *   the row as an external delete).
- * - Any other case throws (propagates for SQS retry, or as
- *   `MailboxCursorPausedError` for the caller's cursor-pause handling) —
- *   including an UNCONFIRMED move (no COPYUID, or an explicit "not
- *   found"/NONEXISTENT from the server) whose message is still sitting at
- *   the source. A MOVE that resolves without a uidMap entry on a
- *   non-UIDPLUS server is a plausible SUCCESS, not evidence the message is
- *   gone (PR #1289 review finding 2) — deleting the local row on that
- *   ambiguity would be data loss. `not-found` is only returned once BOTH a
- *   destination Message-ID search (when the header is known) misses AND
- *   {@link isMessageGoneFromOpenMailbox} confirms the message absent from the
- *   source — a FETCH returning no row does not, on its own, confirm anything.
- */
-export const attemptMove = async (
-	sourceConnection: IImapConnection,
-	destinationConnection: IImapConnection,
-	sourceMailboxPath: string,
-	destinationMailboxPath: string,
-	uid: number,
-	messageIdHeader: string | undefined,
-): Promise<MoveOutcome> => {
-	await sourceConnection.openBox(sourceMailboxPath, false);
-
-	const resolved = await sourceConnection
-		.moveMessages([uid], destinationMailboxPath)
-		.then((result) => ({ ok: true as const, newUid: result.uidMap.get(uid) }))
-		.catch((error: unknown) => {
-			const message = error instanceof Error ? error.message : String(error);
-			if (message.includes("TRYCREATE")) {
-				return { ok: false as const, trycreate: true as const };
-			}
-			if (message.includes("not found") || message.includes("NONEXISTENT")) {
-				return { ok: false as const, trycreate: false as const };
-			}
-			throw error;
-		});
-
-	if (resolved.ok && resolved.newUid) {
-		return { kind: "moved", newUid: resolved.newUid };
-	}
-	if (!resolved.ok && resolved.trycreate) {
-		return { kind: "trycreate" };
-	}
-
-	// Unconfirmed: either no COPYUID entry, or the server explicitly claimed
-	// "not found" — never trust either without independent verification. A
-	// message this MOVE delivered is the newest copy of that Message-ID at the
-	// destination, so the probe binds to the highest matching uid (#1122).
-	// Unlike `confirmTrashMoveUid`, this probe is ungated: where the MOVE never
-	// ran and an older copy filed there earlier is the only match, the marker
-	// binds to that unrelated mail. Pre-existing, and not narrowed by taking the
-	// highest — the source is not asked first here, so nothing rules the case
-	// out.
-	if (messageIdHeader) {
-		const destinationUid = await searchMailboxForHighestMessageIdUid(
-			destinationConnection,
-			destinationMailboxPath,
-			messageIdHeader,
-		);
-		if (destinationUid) return { kind: "moved", newUid: destinationUid };
-	}
-
-	await sourceConnection.openBox(sourceMailboxPath, true);
-	if (!(await isMessageGoneFromOpenMailbox(sourceConnection, uid))) {
-		throw new Error(
-			"Placement move unresolved (unconfirmed at destination, still present at source) — retrying",
-		);
-	}
-
-	return { kind: "not-found" };
-};
-
-/**
- * Handle PLACEMENT_MOVE_PUSH events (issue #1271, epic #1281). Drains ONE
- * pending placement-move marker: resolves the UID fresh from the Message row
- * (never trusts a captured value — invariant 1), pushes the IMAP MOVE, and
- * clears the marker ONLY on confirmed success. Every precedence rule (epic
- * invariant 2) is enforced here:
- * - Pending Remit move wins on location: nothing in this handler ever
- *   corrects `message.mailboxId` back toward the source — a resync elsewhere
- *   (message-sync.ts) never overwrites an existing row's `mailboxId` either
- *   (create-only-if-not-exists semantics), so the local move is never undone.
- * - A NEWER local action superseding this marker (drop without pushing) —
- *   see the `message.mailboxId !== marker.destinationMailboxId` check below.
- * - An external delete supersedes the marker entirely — the `not-found`
- *   outcome drops the marker and reconciles the stale row.
- *
- * Cursor-guarded (#1272, epic #1281 invariant 5): both the source and
- * destination mailbox are checked for a non-`normal` `cursorState` before
- * connecting, and the connection is wrapped per-mailbox via
- * `guardConnectionCursor` so no stored UID touches the server while either
- * mailbox's axis is being rebuilt. A trip pauses the push (routine, no
- * alarm) — the marker stays durable and pushes again on the next event.
- */
-export const handlePlacementMovePush = async (
-	event: PlacementMovePushEvent,
-	log: Logger,
-	queues: WorkerQueues,
-	receiveCount = 1,
-	createConnectionScope = createConnectionScopeWithCredentials,
-): Promise<void> => {
-	const emit = createEmitEvent(queues);
-	const {
-		account: accountService,
-		mailbox: mailboxService,
-		message: messageService,
-		threadMessage: threadMessageService,
-		placementMove: markerService,
-		secrets,
-	} = await getClient();
-
-	const { accountId, accountConfigId, messageId } = event;
-
-	const marker = await markerService.find(messageId);
-	if (!marker) {
-		log.info(
-			{ messageId, accountId },
-			"No pending placement-move marker (already confirmed or superseded); nothing to push",
-		);
-		return;
-	}
-
-	const account = await accountService.get(accountId);
-	if (!account) {
-		throw new Error(`Account ${accountId} not found`);
-	}
-	if (isAccountDeleted(account, log)) {
-		return;
-	}
-
-	const message = await messageService.get(messageId);
-	const placementRead = {
-		status: message.status,
-		mailboxId: message.mailboxId,
-		uid: message.uid,
-	};
-
-	// A newer local action (drag-and-drop move, auto-moved Undo) already
-	// changed the message's location away from what this marker still
-	// promises — that later intent wins locally. Drop the now-stale marker
-	// without touching IMAP.
-	if (message.mailboxId !== marker.destinationMailboxId) {
-		await markerService.delete(messageId);
-		log.info(
-			{
-				messageId,
-				accountId,
-				markerDestination: marker.destinationMailboxId,
-				currentMailboxId: message.mailboxId,
-			},
-			"Placement move superseded by a newer local action; marker dropped without pushing",
-		);
-		return;
-	}
-
-	// The worker has picked up the event and is about to actually attempt the
-	// IMAP MOVE — advance the state engine (pending/queued -> processing).
-	// Idempotent to call again on a redelivered event (a prior attempt that
-	// died mid-flight already left it here).
-	await markerService.updateState(messageId, "processing");
-
-	// No MOVE has left for this marker, so the row is settled, not just unmarked.
-	const [source, destination] = await Promise.all([
-		findMailboxRow(mailboxService, accountId, marker.sourceMailboxId),
-		findMailboxRow(mailboxService, accountId, marker.destinationMailboxId),
-	]);
-	if (source.kind === "gone" || destination.kind === "gone") {
-		const context = {
-			alert: "placement_move_mailbox_unreachable",
-			messageId,
-			accountId,
-			sourceMailboxId: marker.sourceMailboxId,
-			destinationMailboxId: marker.destinationMailboxId,
-		};
-		if (source.kind === "gone") {
-			const reconciled = await messageService.deleteIfPlacement(
-				messageId,
-				placementRead,
-			);
-			await markerService.delete(messageId);
-			log.error(
-				{ ...context, reconciled },
-				"Placement move not pushed: its source folder is gone; the stale row was reconciled",
-			);
-			if (destination.kind === "present") {
-				await emitMailboxResync(emit, {
-					accountId,
-					mailboxId: marker.destinationMailboxId,
-				});
-			}
-			return;
-		}
-		await restoreSourcePlacement(
-			{ messageService, threadMessageService },
-			{
-				accountConfigId,
-				messageId,
-				sourceMailboxId: marker.sourceMailboxId,
-				uid: message.uid,
-				syncStatus: MessageSyncStatus.synced,
-				abandonedMutation: MessageMutation.none,
-			},
-		);
-		await markerService.delete(messageId);
-		log.error(
-			context,
-			"Placement move not pushed: its destination folder is gone; the row was handed back to its source",
-		);
-		await emitMailboxResync(emit, {
-			accountId,
-			mailboxId: marker.sourceMailboxId,
-		});
-		return;
-	}
-	const sourceMailbox = source.mailbox;
-	const destinationMailbox = destination.mailbox;
-
-	// Cheap frugal skip (epic #1281 invariant 6): either mailbox already known
-	// paused never even borrows a connection. Optimization only — the
-	// guardConnectionCursor wraps below are the structural guarantee (#1272).
-	if (
-		isCursorRebuildNeeded(sourceMailbox.cursorState) ||
-		isCursorRebuildNeeded(destinationMailbox.cursorState)
-	) {
-		log.info(
-			{
-				messageId,
-				accountId,
-				sourceCursorState: sourceMailbox.cursorState,
-				destinationCursorState: destinationMailbox.cursorState,
-			},
-			"Mailbox cursor not normal; pausing outbound placement-move push this round",
-		);
-		return;
-	}
-
-	await withOAuthLifecycle(
-		buildLifecycleDeps(secrets, accountService),
-		account,
-		log,
-		async (credentials) => {
-			const scope = createConnectionScope(account, credentials);
-
-			await scope
-				.getConnection()
-				.then(async (rawConnection) => {
-					// Guard at the openBox choke point (epic #1281 invariants 3 & 5).
-					// Two independently-scoped wraps around the SAME connection — see
-					// the attemptMove doc comment for why one guard per mailbox matters.
-					const sourceConnection = guardConnectionCursor(
-						rawConnection,
-						{ mailboxService },
-						accountId,
-						sourceMailbox,
-					);
-					const destinationConnection = guardConnectionCursor(
-						rawConnection,
-						{ mailboxService },
-						accountId,
-						destinationMailbox,
-					);
-
-					const outcome = await attemptMove(
-						sourceConnection,
-						destinationConnection,
-						sourceMailbox.fullPath,
-						destinationMailbox.fullPath,
-						message.uid,
-						await probeableMessageIdHeader(
-							threadMessageService,
-							accountConfigId,
-							messageId,
-						),
-					);
-
-					if (outcome.kind === "trycreate") {
-						await destinationConnection.createMailbox(
-							destinationMailbox.fullPath,
-						);
-						throw new Error(
-							`Destination mailbox ${destinationMailbox.fullPath} did not exist; created, retrying`,
-						);
-					}
-
-					if (outcome.kind === "not-found") {
-						// External delete supersedes the marker entirely (epic invariant 2).
-						await markerService.delete(messageId);
-						const reconciled = await messageService.deleteIfPlacement(
-							messageId,
-							placementRead,
-						);
-						log.info(
-							{
-								messageId,
-								accountId,
-								uid: message.uid,
-								sourceMailboxPath: sourceMailbox.fullPath,
-								reconciled,
-							},
-							"Message no longer at its pending-move source (external delete or moved away); marker dropped, stale row reconciled",
-						);
-						await emitMoveResync(emit, {
-							accountId,
-							sourceMailboxId: marker.sourceMailboxId,
-							destinationMailboxId: marker.destinationMailboxId,
-						});
-						return;
-					}
-
-					const newUid = outcome.newUid as number;
-					await messageService.updateUid(
-						messageId,
-						newUid,
-						marker.destinationMailboxId,
-					);
-
-					const threadMessage = await threadMessageService.findByMessageId(
-						accountConfigId,
-						messageId,
-					);
-					if (threadMessage) {
-						const args = buildThreadMessageMoveUpdate(
-							threadMessage,
-							newUid,
-							marker.destinationMailboxId,
-						);
-						await threadMessageService.update(
-							threadMessage.accountConfigId,
-							threadMessage.threadMessageId,
-							args.set,
-							{ composites: args.composites },
-						);
-					}
-
-					// Confirmed IMAP acknowledgement — the "processed" terminal state.
-					// Deleted immediately rather than persisted first (epic invariant
-					// 4: no lingering row once the move is no longer pending) — clears
-					// ONLY here, never on attempt (the defect issue #1271 fixes).
-					await markerService.delete(messageId);
-
-					log.info(
-						{
-							messageId,
-							accountId,
-							oldUid: message.uid,
-							newUid,
-							destination: destinationMailbox.fullPath,
-						},
-						"Placement move confirmed on IMAP; marker cleared",
-					);
-
-					await emitMoveResync(emit, {
-						accountId,
-						sourceMailboxId: marker.sourceMailboxId,
-						destinationMailboxId: marker.destinationMailboxId,
-					});
-				})
-				.catch(async (error: unknown) => {
-					// Expected pause (epic #1281 invariant 3), not a fault: ack and
-					// skip rather than propagating into SQS retry/DLQ. The marker
-					// stays durable; the push resumes once the mailbox returns to
-					// normal (driven by the next PLACEMENT_MOVE_PUSH for this message,
-					// or the surviving-marker re-enqueue in PlacementMoveService).
-					if (error instanceof MailboxCursorPausedError) {
-						log.info(
-							{ messageId, accountId, cursorState: error.state },
-							"UIDVALIDITY changed; mailbox cursor tripped, pausing outbound placement-move push",
-						);
-						return;
-					}
-
-					if (receiveCount < PLACEMENT_MOVE_MAX_ATTEMPTS) {
-						// Transient push failure — expected (connections drop). No alarm;
-						// SQS redelivery retries from the still-durable marker.
-						throw error;
-					}
-
-					// Redelivery budget exhausted: resolve into exactly one of the two
-					// terminal outcomes (epic invariant 3) instead of dead-lettering
-					// with no diagnosis.
-					const { outcome } = await resolveExhaustedPlacementMoveFailure(
-						{ markerService, messageService, threadMessageService, log },
-						{
-							placement: {
-								status: message.status,
-								mailboxId: message.mailboxId,
-								uid: message.uid,
-							},
-							accountId,
-							accountConfigId,
-							messageId,
-							uid: message.uid,
-							sourceMailboxId: marker.sourceMailboxId,
-							sourceMailboxPath: sourceMailbox.fullPath,
-							getConnection: scope.getConnection,
-						},
-					);
-
-					if (outcome === "reconciled") {
-						await emitMoveResync(emit, {
-							accountId,
-							sourceMailboxId: marker.sourceMailboxId,
-							destinationMailboxId: marker.destinationMailboxId,
-						});
-						return;
-					}
-
-					// Terminal and never re-thrown, so the handler-outcome series
-					// records this record as a success. Counted here or it is invisible.
-					recordImapFailure("PLACEMENT_MOVE_EXHAUSTED", "other");
-					log.error(
-						{ error: error instanceof Error ? error.message : String(error) },
-						"Placement move retry exhausted; message still exists at its source",
-					);
-					// Terminal — never re-thrown, so the caller acks either way.
-				})
-				.finally(() => scope.disconnect());
-		},
-	);
-};