@remit/imap-worker 0.0.1

package/src/handlers/sync-messages.ts

@@ -0,0 +1,412 @@
+import { getClient } from "@remit/backend/client";
+import type {
+	AccountItem,
+	IAccountRepository,
+	IAddressRepository,
+	IEnvelopeRepository,
+	IMailboxRepository,
+	IMessageFlagPushRepository,
+	IMessageRepository,
+	IThreadMessageRepository,
+	IUnitOfWork,
+} from "@remit/data-ports";
+import { SyncPhase } from "@remit/domain-enums";
+import { type Logger, MetricUnit, metrics } from "@remit/logger-lambda";
+import { RefreshTokenError } from "@remit/mail-oauth-service";
+import {
+	createManagedConnectionFactory,
+	MailConnectionError,
+	type MailCredentials,
+	MessageSyncService,
+	type SyncedMessage,
+} from "@remit/mailbox-service";
+import pMap from "p-map";
+import { isAccountDeleted, isUnsyncableHost } from "../account-check.js";
+import { emitEvent } from "../emit.js";
+import type {
+	FlagPushEvent,
+	SyncMessageBodyEvent,
+	SyncMessagesEvent,
+} from "../events.js";
+import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
+import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
+
+// One SYNC_MESSAGE_BODY event maps to one ranged UID FETCH on the consumer.
+export const BODY_BATCH_SIZE = 200;
+const EVENT_EMIT_CONCURRENCY = 10;
+const MESSAGE_BATCH_SIZE = 200;
+
+/** Slice synced messages into body-sync batches, each one ranged FETCH. */
+export const batchSyncedMessages = (
+	syncedMessages: SyncedMessage[],
+	batchSize: number = BODY_BATCH_SIZE,
+): SyncedMessage[][] => {
+	const batches: SyncedMessage[][] = [];
+	for (let i = 0; i < syncedMessages.length; i += batchSize) {
+		batches.push(syncedMessages.slice(i, i + batchSize));
+	}
+	return batches;
+};
+
+export const syncMessages = async (
+	event: SyncMessagesEvent,
+	log: Logger,
+): Promise<void> => {
+	log.info(
+		{
+			event: event.type,
+			accountId: event.accountId,
+			mailboxId: event.mailboxId,
+		},
+		"Handling event",
+	);
+
+	const {
+		account: accountService,
+		mailbox: mailboxService,
+		message: messageService,
+		envelope: envelopeService,
+		address: addressService,
+		threadMessage: threadMessageService,
+		mailboxLock: mailboxLockService,
+		flagPush: flagPushMarkerService,
+		unitOfWork,
+		secrets,
+	} = await getClient();
+
+	// A deleted account never has its DDB row purged in lockstep with the queued
+	// SYNC_MESSAGES triggers, so a trigger can outlive its account. The lookup
+	// then returns null (or throws a named NotFoundError), which can never succeed
+	// on retry — it would retry to maxReceiveCount and poison the messages DLQ
+	// forever (issue #911). Treat a missing account as terminal: ack the event
+	// with a WARN. Genuinely transient failures (throttle, network) surface as
+	// other errors and still propagate to be retried.
+	let account: AccountItem;
+	const rawAccount = await accountService.get(event.accountId).catch((err) => {
+		if ((err as { name?: string })?.name === "NotFoundError") return null;
+		throw err;
+	});
+	if (!rawAccount) {
+		log.warn(
+			{
+				accountId: event.accountId,
+				mailboxId: event.mailboxId,
+				eventId: event.eventId,
+			},
+			"Skipping SYNC_MESSAGES: account no longer exists",
+		);
+		return;
+	}
+	account = rawAccount;
+
+	if (isAccountDeleted(account, log)) {
+		return;
+	}
+
+	// A reserved/never-resolvable IMAP host (RFC 2606) can never connect, so a
+	// sync attempt would retry and dead-letter forever. Skip cleanly — ack the
+	// event without connecting or throwing.
+	if (isUnsyncableHost(account, log.child({ mailboxId: event.mailboxId }))) {
+		return;
+	}
+
+	// withOAuthLifecycle owns the reauth/ACK contract (skip-if-reauth, resolve
+	// credentials, flip on terminal auth failure, rethrow transient). The
+	// mailbox lock and the actual sync run inside the wrapper callback.
+	await withOAuthLifecycle(
+		buildLifecycleDeps(secrets, accountService),
+		account,
+		log,
+		async (credentials) => {
+			// Acquire lock before starting sync operation
+			const { executed } = await mailboxLockService.withMailboxLock(
+				event.mailboxId,
+				"SYNC_MESSAGES",
+				event.accountId,
+				async () => {
+					try {
+						await syncMailboxMessages(
+							event,
+							account,
+							credentials,
+							{
+								accountService,
+								mailboxService,
+								messageService,
+								envelopeService,
+								addressService,
+								threadMessageService,
+								flagPushMarkerService,
+								unitOfWork,
+							},
+							log,
+						);
+					} catch (err) {
+						// Auth failures are handled by the wrapper — rethrow untouched.
+						if (
+							err instanceof RefreshTokenError ||
+							(err instanceof MailConnectionError && err.kind === "auth")
+						) {
+							throw err;
+						}
+						// Record the terminal error phase before crashing (let-it-crash:
+						// record state, then rethrow so the event is retried/DLQ'd).
+						const message = err instanceof Error ? err.message : String(err);
+						await accountService.update(event.accountId, {
+							syncPhase: SyncPhase.error,
+							lastError: message,
+						});
+						throw err;
+					}
+				},
+			);
+
+			if (!executed) {
+				log.info(
+					{ mailboxId: event.mailboxId },
+					"Sync already in progress, skipping",
+				);
+			}
+		},
+	);
+};
+
+interface SyncDeps {
+	accountService: IAccountRepository;
+	mailboxService: IMailboxRepository;
+	messageService: IMessageRepository;
+	envelopeService: IEnvelopeRepository;
+	addressService: IAddressRepository;
+	threadMessageService: IThreadMessageRepository;
+	flagPushMarkerService: IMessageFlagPushRepository;
+	unitOfWork?: IUnitOfWork;
+}
+
+// Bounds concurrent SQS sends while re-arming stuck flag-push markers —
+// markers are expected to be few, but never unbounded (coding-standards.md).
+const FLAG_PUSH_DRAIN_CONCURRENCY = 5;
+
+/**
+ * Periodic per-mailbox drain point for pending flag-push markers (issue
+ * #1273, epic #1281). The SQS enqueue in `FlagPushService.flip` is only a
+ * wake-up hint and may fail freely — a marker left `state: "pending"` means
+ * that hint never landed (queue down, or a crash between the local write and
+ * the enqueue). This periodic tick — which already runs per mailbox on a
+ * schedule regardless of user activity — re-arms every such marker with a
+ * fresh `FLAG_PUSH` event, closing the gap without the caller ever having to
+ * retry.
+ *
+ * Markers already `queued`/`processing` are left alone: a live SQS message
+ * (or the single-marker handler currently running) already owns driving them
+ * forward, and re-arming them too would just duplicate work.
+ *
+ * A re-arm failure (the SQS send itself) is caught per-marker and logged
+ * loudly — it must never fail the surrounding SYNC_MESSAGES batch, which is
+ * unrelated message-header sync work. The marker stays durable regardless;
+ * the next periodic tick tries again.
+ *
+ * `emit` defaults to the real `emitEvent` (imap-worker's shared SQS
+ * producer) and is only ever overridden in tests.
+ */
+export const drainPendingFlagPushes = async (
+	flagPushMarkerService: IMessageFlagPushRepository,
+	account: AccountItem,
+	mailboxId: string,
+	log: Logger,
+	emit: typeof emitEvent = emitEvent,
+): Promise<void> => {
+	const markers = await flagPushMarkerService.listByMailboxId(mailboxId);
+	const stuck = markers.filter((marker) => marker.state === "pending");
+	if (stuck.length === 0) return;
+
+	log.info(
+		{ mailboxId, count: stuck.length },
+		"Periodic sync tick found flag-push marker(s) stuck before their wake-up hint; re-arming",
+	);
+
+	await pMap(
+		stuck,
+		(marker) => {
+			const rearmEvent: Omit<FlagPushEvent, "eventId" | "timestamp"> = {
+				type: "FLAG_PUSH",
+				accountId: account.accountId,
+				accountConfigId: account.accountConfigId,
+				messageId: marker.messageId,
+				flagName: marker.flagName,
+			};
+			return emit(rearmEvent).catch((error: unknown) => {
+				log.error(
+					{
+						alert: "flag_push_drain_rearm_failed",
+						mailboxId,
+						messageId: marker.messageId,
+						flagName: marker.flagName,
+						error: error instanceof Error ? error.message : String(error),
+					},
+					"Failed to re-arm a stuck pending flag-push marker during the periodic drain",
+				);
+			});
+		},
+		{ concurrency: FLAG_PUSH_DRAIN_CONCURRENCY },
+	);
+};
+
+/**
+ * Sync one batch of messages for a mailbox. Runs under the mailbox lock.
+ */
+const syncMailboxMessages = async (
+	event: SyncMessagesEvent,
+	account: AccountItem,
+	credentials: MailCredentials,
+	deps: SyncDeps,
+	log: Logger,
+): Promise<void> => {
+	const {
+		accountService,
+		mailboxService,
+		messageService,
+		envelopeService,
+		addressService,
+		threadMessageService,
+		flagPushMarkerService,
+		unitOfWork,
+	} = deps;
+
+	// Create a managed connection factory that caches and reuses the connection
+	const connectionFactory = createManagedConnectionFactory({
+		user: account.username,
+		credentials,
+		host: account.imapHost,
+		port: account.imapPort,
+		tls: account.imapTls,
+	});
+
+	// Get the mailbox - it must exist (should have been created by mailbox sync)
+	const mailbox = await mailboxService.get(account.accountId, event.mailboxId);
+	const mailboxId = mailbox.mailboxId;
+
+	// Periodic drain (issue #1273): independent of the IMAP sync below — no
+	// connection needed, just an SQS re-arm — so it runs regardless of this
+	// round's sync outcome.
+	await drainPendingFlagPushes(flagPushMarkerService, account, mailboxId, log);
+	const isInbox = mailbox.fullPath.toUpperCase() === "INBOX";
+
+	const syncService = new MessageSyncService(
+		connectionFactory,
+		mailboxService,
+		messageService,
+		envelopeService,
+		addressService,
+		threadMessageService,
+		log,
+		unitOfWork,
+	);
+
+	// Connect once, reuse for the entire sync operation
+	const connection = connectionFactory.getConnection();
+	await connection.connect();
+
+	const result = await syncService
+		.syncMessages(
+			mailboxId,
+			account.accountId,
+			account.accountConfigId,
+			MESSAGE_BATCH_SIZE,
+		)
+		.finally(() => connectionFactory.close());
+	log.info(
+		{
+			syncedCount: result.syncedCount,
+			hasMore: result.hasMore,
+			remainingCount: result.remainingCount,
+		},
+		"Message sync batch complete",
+	);
+
+	if (result.syncedCount > 0) {
+		metrics.addMetric(
+			"imapMessagesSynced",
+			MetricUnit.Count,
+			result.syncedCount,
+		);
+	}
+
+	// Emit body sync events for the messages we just synced. Each event carries
+	// messageId+uid pairs so the consumer issues one ranged FETCH per batch
+	// without re-resolving UIDs. messageIds stays populated for backward compat.
+	if (result.syncedMessages.length > 0) {
+		const batches = batchSyncedMessages(result.syncedMessages);
+
+		log.info(
+			{ count: result.syncedMessages.length, batches: batches.length },
+			"Emitting SYNC_MESSAGE_BODY events",
+		);
+
+		await pMap(
+			batches,
+			(batch) => {
+				const bodyEvent: Omit<SyncMessageBodyEvent, "eventId" | "timestamp"> = {
+					type: "SYNC_MESSAGE_BODY",
+					accountId: event.accountId,
+					mailboxId,
+					messageIds: batch.map((m) => m.messageId),
+					messages: batch.map((m) => ({ messageId: m.messageId, uid: m.uid })),
+				};
+				return emitEvent(bodyEvent);
+			},
+			{ concurrency: EVENT_EMIT_CONCURRENCY },
+		);
+	}
+
+	// If there are more messages to sync, emit another SYNC_MESSAGES event
+	if (result.hasMore) {
+		log.info(
+			{ remainingCount: result.remainingCount },
+			"Emitting SYNC_MESSAGES event for next batch",
+		);
+
+		const nextSyncEvent: Omit<SyncMessagesEvent, "eventId" | "timestamp"> = {
+			type: "SYNC_MESSAGES",
+			accountId: event.accountId,
+			mailboxId,
+			resumeCursor: result.remainingCount,
+		};
+		await emitEvent(nextSyncEvent);
+		return;
+	}
+
+	// Mailbox drained. Record the per-mailbox completion marker (used by the
+	// sync-status endpoint to derive the per-mailbox phase), and count it
+	// towards mailboxCountSynced — but only once per sync round, so that
+	// duplicate / no-op SYNC_MESSAGES completions don't inflate the counter.
+	// The check-then-write is safe: the mailbox lock serializes completions
+	// per mailbox, and `mailbox` was read under the lock.
+	const roundStartedAt = account.lastSyncAt ?? 0;
+	const previousCompletedAt = mailbox.initialSyncCompletedAt ?? 0;
+	const firstCompletionThisRound =
+		previousCompletedAt === 0 || previousCompletedAt < roundStartedAt;
+
+	await mailboxService.update(account.accountId, mailboxId, {
+		initialSyncCompletedAt: Date.now(),
+	});
+
+	if (!firstCompletionThisRound) {
+		log.info(
+			{ mailboxId },
+			"Mailbox already counted as synced this round, skipping increment",
+		);
+		return;
+	}
+
+	const currentAccount = await accountService.get(event.accountId);
+
+	if (isInbox && currentAccount.syncPhase === SyncPhase.syncing_inbox) {
+		// INBOX is drained; advance to syncing_others
+		await accountService.update(event.accountId, {
+			syncPhase: SyncPhase.syncing_others,
+		});
+	}
+
+	// Atomically increment mailboxCountSynced; transitions to complete when all done
+	await accountService.incrementMailboxSynced(event.accountId);
+};

package/src/handlers/sync-reserved-host.test.ts

@@ -0,0 +1,97 @@
+/**
+ * Handler-level guard: an account whose IMAP host is a reserved, never-resolvable
+ * placeholder name (RFC 2606 — .invalid/.example) must be skipped cleanly.
+ * No connection attempt, no thrown error, so SQS acks the event instead of
+ * retrying it into the mailboxes DLQ forever (issue #835).
+ *
+ * The proof is structural: the only AccountService method the handler may touch
+ * is `get`. Any of the post-connect writes (`markAuthenticated`, `update`) firing
+ * would mean we passed the skip gate and tried to connect — so those are stubbed
+ * to throw, and the test asserts the handler still resolves cleanly.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it, mock } from "node:test";
+import {
+	_resetForTest,
+	_setClientForTest,
+	type RemitClient,
+} from "@remit/backend/client";
+import type { AccountItem } from "@remit/data-ports";
+import type { Logger } from "@remit/logger-lambda";
+import type { SyncMailboxesEvent, SyncMessagesEvent } from "../events.js";
+import { syncMailboxes } from "./sync-mailboxes.js";
+import { syncMessages } from "./sync-messages.js";
+
+const silentLogger = (() => {
+	const noop = () => {};
+	const log = {
+		info: noop,
+		warn: noop,
+		error: noop,
+		debug: noop,
+		fatal: noop,
+		trace: noop,
+		child: () => log,
+	} as unknown as Logger;
+	return log;
+})();
+
+const reservedAccount = (): AccountItem =>
+	({
+		accountId: "acct-reserved",
+		accountConfigId: "acfg-reserved",
+		connectionState: "authenticated",
+		username: "alice@imap.invalid",
+		imapHost: "imap.invalid",
+		imapPort: 993,
+		imapTls: true,
+	}) as unknown as AccountItem;
+
+const failIfReached = () => {
+	throw new Error("post-skip-gate account write must not run");
+};
+
+const setClientWithAccountGet = (get: ReturnType<typeof mock.fn>): void => {
+	_setClientForTest({
+		account: {
+			get,
+			markAuthenticated: failIfReached,
+			update: failIfReached,
+		},
+	} as unknown as RemitClient);
+};
+
+afterEach(() => {
+	mock.restoreAll();
+	_resetForTest();
+});
+
+describe("reserved-host skip gate", () => {
+	it("syncMailboxes skips a reserved host cleanly — no connect, no throw", async () => {
+		const get = mock.fn(async () => reservedAccount());
+		setClientWithAccountGet(get);
+
+		const event = {
+			type: "SYNC_MAILBOXES",
+			accountId: "acct-reserved",
+		} as unknown as SyncMailboxesEvent;
+
+		await assert.doesNotReject(() => syncMailboxes(event, silentLogger));
+		assert.equal(get.mock.callCount(), 1);
+	});
+
+	it("syncMessages skips a reserved host cleanly — no connect, no throw", async () => {
+		const get = mock.fn(async () => reservedAccount());
+		setClientWithAccountGet(get);
+
+		const event = {
+			type: "SYNC_MESSAGES",
+			accountId: "acct-reserved",
+			mailboxId: "mbox-1",
+		} as unknown as SyncMessagesEvent;
+
+		await assert.doesNotReject(() => syncMessages(event, silentLogger));
+		assert.equal(get.mock.callCount(), 1);
+	});
+});

package/src/index.test.ts

@@ -0,0 +1,22 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { parseReceiveCount } from "./index.js";
+
+describe("parseReceiveCount — SQS ApproximateReceiveCount parsing", () => {
+	it("parses the raw string attribute", () => {
+		assert.equal(parseReceiveCount("1"), 1);
+		assert.equal(parseReceiveCount("3"), 3);
+	});
+
+	it("defaults to 1 when the attribute is missing", () => {
+		// A record with no attribute (e.g. an older local harness) is treated as
+		// a first attempt, not fast-forwarded into retry-exhaustion handling.
+		assert.equal(parseReceiveCount(undefined), 1);
+	});
+
+	it("defaults to 1 on a non-numeric or non-positive value", () => {
+		assert.equal(parseReceiveCount("not-a-number"), 1);
+		assert.equal(parseReceiveCount("0"), 1);
+		assert.equal(parseReceiveCount("-1"), 1);
+	});
+});

package/src/index.ts

@@ -0,0 +1,70 @@
+import {
+	createLogger,
+	MetricUnit,
+	metrics,
+	withTelemetry,
+} from "@remit/logger-lambda";
+import type { SQSBatchResponse, SQSEvent, SQSHandler } from "aws-lambda";
+import type { WorkerEvent } from "./events.js";
+import { processEvent } from "./processor.js";
+
+const log = createLogger();
+
+/**
+ * Parse SQS's `ApproximateReceiveCount` record attribute (1 on first
+ * delivery). Missing/malformed defaults to 1 so a record with no attribute
+ * (e.g. an older local harness) is treated as a first attempt rather than
+ * skipping straight to retry-exhaustion handling.
+ */
+export const parseReceiveCount = (value: string | undefined): number => {
+	const parsed = Number.parseInt(value ?? "1", 10);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : 1;
+};
+
+export const handler: SQSHandler = withTelemetry(
+	async (event: SQSEvent): Promise<SQSBatchResponse> => {
+		const batchItemFailures: { itemIdentifier: string }[] = [];
+
+		for (const record of event.Records) {
+			const imapEvent: WorkerEvent = JSON.parse(record.body);
+			const receiveCount = parseReceiveCount(
+				record.attributes?.ApproximateReceiveCount,
+			);
+			log.info(
+				{
+					eventType: imapEvent.type,
+					eventId: "eventId" in imapEvent ? imapEvent.eventId : undefined,
+					receiveCount,
+				},
+				"Processing event",
+			);
+
+			metrics.addDimension("operation", imapEvent.type);
+			const opStart = Date.now();
+			const failed = await processEvent(imapEvent, log, receiveCount)
+				.then(() => {
+					metrics.addMetric(
+						"imapOperationLatency",
+						MetricUnit.Milliseconds,
+						Date.now() - opStart,
+					);
+					return false;
+				})
+				.catch((error) => {
+					log.error(
+						{ error, messageId: record.messageId },
+						"Event processing failed",
+					);
+					metrics.addMetric("imapOperationFailures", MetricUnit.Count, 1);
+					return true;
+				});
+			metrics.clearDimensions();
+
+			if (failed) {
+				batchItemFailures.push({ itemIdentifier: record.messageId });
+			}
+		}
+
+		return { batchItemFailures };
+	},
+);

package/src/poller.ts

@@ -0,0 +1,49 @@
+import { createLogger } from "@remit/logger-lambda";
+import { runQueuePoller } from "@remit/sqs-client/poller";
+import { env } from "expect-env";
+import { handler } from "./index.js";
+
+/**
+ * Production queue poller — the deployed form of `e2e-processor-shim.ts`.
+ * Polls every imap-worker queue and invokes the production Lambda handler.
+ * The search-index queue is NOT polled here: it is its own image/deployment
+ * (`remit-search-index-worker`), unlike the e2e shim which piggybacks it
+ * onto this same process for test convenience.
+ */
+const log = createLogger();
+
+await runQueuePoller({
+	log,
+	targets: [
+		{
+			queueUrl: env.SQS_QUEUE_URL_MAILBOXES,
+			handler,
+			functionName: "imap-worker-mailboxes",
+		},
+		{
+			queueUrl: env.SQS_QUEUE_URL_MESSAGES,
+			handler,
+			functionName: "imap-worker-messages",
+		},
+		{
+			queueUrl: env.SQS_QUEUE_URL_FLAGS,
+			handler,
+			functionName: "imap-worker-flags",
+		},
+		{
+			queueUrl: env.SQS_QUEUE_URL_BODY,
+			handler,
+			functionName: "imap-worker-body",
+		},
+		{
+			queueUrl: env.SQS_QUEUE_URL_MAILBOX_MGMT,
+			handler,
+			functionName: "imap-worker-mailbox-mgmt",
+		},
+		{
+			queueUrl: env.SQS_QUEUE_URL_MESSAGE_MGMT,
+			handler,
+			functionName: "imap-worker-message-mgmt",
+		},
+	],
+});

package/src/processor.test.ts

@@ -0,0 +1,58 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { Logger } from "@remit/logger-lambda";
+import type { ImapWorkerStopEvent } from "./events.js";
+import { processEvent } from "./processor.js";
+
+interface CapturedLogEntry {
+	args: unknown[];
+}
+
+const createCapturingLogger = (): {
+	log: Logger;
+	infoCalls: CapturedLogEntry[];
+} => {
+	const infoCalls: CapturedLogEntry[] = [];
+	const noop = () => {};
+	const log = {
+		info: (...args: unknown[]) => infoCalls.push({ args }),
+		warn: noop,
+		error: noop,
+		debug: noop,
+		fatal: noop,
+		trace: noop,
+		child: () => log,
+	} as unknown as Logger;
+	return { log, infoCalls };
+};
+
+describe("processEvent — IMAP_WORKER_STOP", () => {
+	it("returns undefined and logs the stop signal — tombstone fence on the account row already halts work", async () => {
+		const event: ImapWorkerStopEvent = {
+			type: "IMAP_WORKER_STOP",
+			accountConfigId: "acfg_alice_replay_safe_test_id",
+			accountId: "acct_alice_replay_safe_test_id",
+		};
+		const { log, infoCalls } = createCapturingLogger();
+
+		const result = await processEvent(event, log);
+
+		assert.equal(result, undefined);
+		const matched = infoCalls.find((c) => {
+			const [meta, msg] = c.args;
+			return (
+				typeof msg === "string" &&
+				msg === "Imap worker stop signal received" &&
+				typeof meta === "object" &&
+				meta !== null &&
+				(meta as { accountConfigId?: string }).accountConfigId ===
+					event.accountConfigId &&
+				(meta as { accountId?: string }).accountId === event.accountId
+			);
+		});
+		assert.ok(
+			matched,
+			"processor must log the cascade-contract stop signal with both ids",
+		);
+	});
+});