@remit/imap-worker 0.0.90 → 0.0.91

package/src/handlers/sync-messages.ts

@@ -1,537 +0,0 @@
-import { getClient } from "@remit/backend/client";
-import type {
-	AccountItem,
-	IAccountRepository,
-	IAddressRepository,
-	IEnvelopeRepository,
-	IMailboxRepository,
-	IMailboxSpecialUseRepository,
-	IMessageFlagPushRepository,
-	IMessageFlagRepository,
-	IMessageRepository,
-	IQuarantineRepository,
-	ISyncWarningRepository,
-	IThreadMessageRepository,
-} from "@remit/data-ports";
-import { isNotFoundError } from "@remit/data-ports/errors";
-import { SyncPhase } from "@remit/domain-enums";
-import type { Logger } from "@remit/logger";
-import { recordImapFailure } from "@remit/logger-lambda/metrics";
-import { RefreshTokenError } from "@remit/mail-oauth-service";
-import {
-	createManagedConnectionFactory,
-	isMailboxMutationInFlight,
-	MailConnectionError,
-	type MailCredentials,
-	type ManagedConnectionFactory,
-	MessageSyncService,
-	QuarantineService,
-	type SyncedMessage,
-	SyncWarningService,
-} from "@remit/mailbox-service";
-import pMap from "p-map";
-import {
-	isAccountDeleted,
-	isMailSyncDisabled,
-	isUnsyncableHost,
-} from "../account-check.js";
-import {
-	createEmitEvent,
-	type EmitEvent,
-	SYNC_MESSAGES_PENDING,
-} from "../emit.js";
-import type {
-	FlagPushEvent,
-	SyncMessageBodyEvent,
-	SyncMessagesEvent,
-} from "../events.js";
-import type { WorkerQueues } from "../queues.js";
-import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
-import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
-import { workerVersion } from "../worker-version.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 managedConnectionFor = (
-	account: Pick<AccountItem, "username" | "imapHost" | "imapPort" | "imapTls">,
-	credentials: MailCredentials,
-): ManagedConnectionFactory =>
-	createManagedConnectionFactory({
-		user: account.username,
-		credentials,
-		host: account.imapHost,
-		port: account.imapPort,
-		tls: account.imapTls,
-	});
-
-export const syncMessages = async (
-	event: SyncMessagesEvent,
-	log: Logger,
-	queues: WorkerQueues,
-	createConnectionFactory = managedConnectionFor,
-): 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,
-		mailboxSpecialUse: mailboxSpecialUseService,
-		quarantine: quarantineService,
-		syncWarning: syncWarningRepository,
-		flagPush: flagPushMarkerService,
-		messageFlag: messageFlagService,
-		secrets,
-	} = await getClient();
-
-	await mailboxLockService.releaseLock(
-		event.accountId,
-		event.mailboxId,
-		SYNC_MESSAGES_PENDING,
-		event.eventId,
-	);
-
-	// 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 (isNotFoundError(err)) 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;
-	}
-
-	if (isMailSyncDisabled(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;
-	}
-
-	// 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 isMailboxMutationInFlight(
-			mailboxService,
-			event.accountId,
-			event.mailboxId,
-		)
-	) {
-		log.warn(
-			{
-				accountId: event.accountId,
-				mailboxId: event.mailboxId,
-				eventId: event.eventId,
-				event: event.type,
-			},
-			"Skipping SYNC_MESSAGES: a folder mutation is in flight",
-		);
-		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,
-							createConnectionFactory(account, credentials),
-							{
-								accountService,
-								mailboxService,
-								messageService,
-								envelopeService,
-								addressService,
-								threadMessageService,
-								mailboxSpecialUseService,
-								quarantineService,
-								syncWarningRepository,
-								flagPushMarkerService,
-								messageFlagService,
-								emit: createEmitEvent(queues),
-							},
-							log,
-						);
-					} catch (err) {
-						// Auth failures are handled by the wrapper — rethrow untouched.
-						if (
-							err instanceof RefreshTokenError ||
-							(err instanceof MailConnectionError && err.kind === "auth")
-						) {
-							throw err;
-						}
-						// The guard above is a check-then-act: a delete asked for while
-						// this round was in flight lands inside it, and the round then
-						// fails somewhere deeper — on the row (NotFoundError from the
-						// service's own re-read) or on the server (the SELECTed folder
-						// vanished, so the next command runs against no mailbox). Both are
-						// the same expected outcome as an event that arrived after the
-						// delete, so they resolve the same way rather than head-of-line
-						// blocking the account's FIFO group (issue #339). Recording an
-						// error phase is skipped too: the account is healthy, one of its
-						// folders is not there.
-						//
-						// This read only classifies the failure already in hand, so it must
-						// 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 isMailboxMutationInFlight(
-							mailboxService,
-							event.accountId,
-							event.mailboxId,
-						).catch(() => false);
-						if (folderIsGone) {
-							log.warn(
-								{
-									accountId: event.accountId,
-									mailboxId: event.mailboxId,
-									eventId: event.eventId,
-									event: event.type,
-									error: err instanceof Error ? err.message : String(err),
-								},
-								"Resolving SYNC_MESSAGES: the folder left the server while the sync was in flight",
-							);
-							return;
-						}
-						// 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;
-	mailboxSpecialUseService: IMailboxSpecialUseRepository;
-	quarantineService: IQuarantineRepository;
-	syncWarningRepository: ISyncWarningRepository;
-	flagPushMarkerService: IMessageFlagPushRepository;
-	messageFlagService: IMessageFlagRepository;
-	emit: EmitEvent;
-}
-
-// 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.
- */
-export const drainPendingFlagPushes = async (
-	flagPushMarkerService: IMessageFlagPushRepository,
-	account: AccountItem,
-	mailboxId: string,
-	log: Logger,
-	emit: 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,
-	connectionFactory: ManagedConnectionFactory,
-	deps: SyncDeps,
-	log: Logger,
-): Promise<void> => {
-	const {
-		accountService,
-		mailboxService,
-		messageService,
-		envelopeService,
-		addressService,
-		threadMessageService,
-		mailboxSpecialUseService,
-		quarantineService,
-		syncWarningRepository,
-		flagPushMarkerService,
-		messageFlagService,
-		emit,
-	} = deps;
-
-	// 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,
-		emit,
-	);
-	const isInbox = mailbox.fullPath.toUpperCase() === "INBOX";
-
-	const syncService = new MessageSyncService(
-		connectionFactory,
-		mailboxService,
-		mailboxSpecialUseService,
-		messageService,
-		envelopeService,
-		addressService,
-		threadMessageService,
-		new SyncWarningService(syncWarningRepository),
-		log,
-		flagPushMarkerService,
-		messageFlagService,
-		new QuarantineService(
-			quarantineService,
-			mailboxSpecialUseService,
-			workerVersion(),
-			log,
-		),
-	);
-
-	// 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",
-	);
-
-	// A stalled cursor is the one failure on this path that produces no error:
-	// unapplicable messages are caught and held back, so the round returns
-	// normally, the SQS record is deleted, and neither redrive nor the DLQ ever
-	// engages. Without this counter the mailbox stops syncing behind a worker
-	// that looks healthy. Per-mailbox detail is in the accompanying ERROR log.
-	if (result.cursorStalled) {
-		recordImapFailure("SYNC_MESSAGES_CURSOR_STALLED", "other");
-	}
-
-	// 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 emit(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,
-		};
-		await emit(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/index.test.ts

@@ -1,22 +0,0 @@
-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

@@ -1,82 +0,0 @@
-import { createLogger } from "@remit/logger";
-import {
-	queueNameFromEventSource,
-	recordImapFailure,
-	recordQueueEvent,
-} from "@remit/logger-lambda/metrics";
-import { installNodeLogger, withTelemetry } from "@remit/logger-lambda/node";
-import type { SQSBatchResponse, SQSEvent, SQSHandler } from "aws-lambda";
-import type { WorkerEvent } from "./events.js";
-import { imapFailureKind } from "./failure-kind.js";
-import { processEvent } from "./processor.js";
-import { sqsWorkerQueues, workerQueueUrlsFromEnv } from "./queues.js";
-
-installNodeLogger();
-const queues = sqsWorkerQueues(workerQueueUrlsFromEnv());
-
-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",
-			);
-
-			const queue = queueNameFromEventSource(record.eventSourceARN);
-			const opStart = Date.now();
-			const failed = await processEvent(imapEvent, log, queues, receiveCount)
-				.then(() => {
-					recordQueueEvent({
-						queue,
-						eventType: imapEvent.type,
-						outcome: "success",
-						durationMs: Date.now() - opStart,
-					});
-					return false;
-				})
-				.catch((error) => {
-					log.error(
-						{ error, messageId: record.messageId },
-						"Event processing failed",
-					);
-					recordQueueEvent({
-						queue,
-						eventType: imapEvent.type,
-						outcome: "failure",
-						durationMs: Date.now() - opStart,
-					});
-					recordImapFailure(imapEvent.type, imapFailureKind(error));
-					return true;
-				});
-
-			if (failed) {
-				batchItemFailures.push({ itemIdentifier: record.messageId });
-			}
-		}
-
-		return { batchItemFailures };
-	},
-);