@remit/imap-worker 0.0.90 → 0.0.92

package/dist/handlers/sync-message-body.js

@@ -0,0 +1,182 @@
+import { isNotFoundError } from "@remit/data-ports/errors";
+import { BodySyncService, guardConnectionCursor, isCursorRebuildNeeded, isFolderMutationInFlight, MailboxCursorPausedError, PlacementMoveService, QuarantineService, resolveExhaustedBodySyncFailures, resolveFolderPlacement, SyncWarningService, } from "@remit/mailbox-service";
+import { buildFilterConfig } from "@remit/mailbox-service/filter-config";
+import { isAccountDeleted } from "../account-check.js";
+import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
+import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
+export const resolveBatch = (event) => {
+    const force = event.force === true;
+    if (event.messages !== undefined) {
+        return {
+            messageIds: event.messages.map((m) => m.messageId),
+            uidByMessageId: new Map(event.messages.map((m) => [m.messageId, m.uid])),
+            force,
+        };
+    }
+    return { messageIds: event.messageIds, force };
+};
+/**
+ * Build the loud, structured error thrown when a batch still has failed
+ * messages and SQS redelivery budget left. Throwing (rather than swallowing
+ * into a fresh re-enqueue) is what lets a genuine processing failure reach
+ * the body-dlq once `BODY_SYNC_MAX_ATTEMPTS` is exhausted — the SQS-level
+ * redrive owns retry scheduling now, not this handler.
+ */
+export const buildRetryableFailureError = (failedMessageIds, receiveCount, maxAttempts) => new Error(`Body sync failed for ${failedMessageIds.length} message(s) ` +
+    `(attempt ${receiveCount}/${maxAttempts}): ${failedMessageIds.join(", ")}`);
+export const syncMessageBody = async (event, ctx, receiveCount) => {
+    const { log, queues, pool, metrics, config } = ctx;
+    const { accountId, mailboxId } = event;
+    // Prefer the messageId+uid pairs when present (one ranged FETCH, no
+    // per-message UID lookup); fall back to the legacy id-only list otherwise.
+    const { messageIds, force } = resolveBatch(event);
+    log.info({
+        event: event.type,
+        accountId,
+        mailboxId,
+        messageCount: messageIds.length,
+        hasUids: event.messages !== undefined,
+        force,
+        receiveCount,
+    }, "Handling event");
+    const { account: accountService, mailbox: mailboxService, mailboxSpecialUse: mailboxSpecialUseService, message: messageService, threadMessage: threadMessageService, address: addressService, envelope: envelopeService, placementMove: markerService, filter: filterService, messageLabel: messageLabelService, storage, secrets, mailboxSpecialUse: mailboxSpecialUseRepository, quarantine: quarantineRepository, syncWarning: syncWarningRepository, flagQueue: flagQueueService, calendarSuggestion: calendarSuggestionService, calendarStore, } = ctx.client;
+    const account = await accountService.get(accountId);
+    if (!account) {
+        throw new Error(`Account ${accountId} not found`);
+    }
+    if (isAccountDeleted(account, log)) {
+        return;
+    }
+    // PLACEMENT_MOVE_PUSH rides messageMgmtQueue (issue #1271) — same queue
+    // the general MessageMoveService move/delete/copy machinery uses, not a
+    // dedicated one.
+    const placementMoveService = new PlacementMoveService({
+        messageService,
+        threadMessageService,
+        markerService,
+        addressService,
+        mailboxSpecialUseService,
+        mailboxService,
+        queue: queues.messageManagement,
+    });
+    await withOAuthLifecycle(buildLifecycleDeps(secrets, accountService, ctx.oauth), account, log, async (credentials) => {
+        // A SYNC_MESSAGE_BODY trigger can outlive the mailbox it targets: deleting
+        // a folder that held mail leaves already-queued body events pointing at a
+        // row that is now gone, and the lookup then throws NotFoundError forever.
+        // Since the body queue carries MessageGroupId=accountId, that head message
+        // stalls the account's whole body pipeline (issues #287, #289, #290). A
+        // deleted folder is an expected terminal outcome: ack with a WARN.
+        const mailbox = await mailboxService
+            .get(accountId, mailboxId)
+            .catch((error) => {
+            if (isNotFoundError(error))
+                return null;
+            throw error;
+        });
+        // A folder still `pending` is terminal for the same reason: the batch
+        // was cut before the folder reached the server, so there is nothing
+        // there to fetch from and no retry that changes it.
+        if (!mailbox || isFolderMutationInFlight(mailbox)) {
+            log.warn({ accountId, mailboxId, eventId: event.eventId }, "Skipping SYNC_MESSAGE_BODY: a folder mutation is in flight");
+            return;
+        }
+        // Cheap frugal skip (epic #1281 invariant 6): a mailbox already known
+        // paused never even borrows a connection. This is an optimization only
+        // — guardConnectionCursor below is the structural guarantee, so a
+        // handler that forgot this check still cannot reach a stale UID.
+        if (isCursorRebuildNeeded(mailbox.cursorState)) {
+            log.info({ accountId, mailboxId, cursorState: mailbox.cursorState }, "Mailbox cursor not normal; pausing outbound body sync this round");
+            return;
+        }
+        const borrowed = pool.borrow(account, credentials);
+        // A confident, actionable placement verdict moves mail directly on
+        // body-sync. Safety lives in the verdict itself (only confident,
+        // INBOX/Junk-only) and the movedByRemit loop guard.
+        const placementConfig = {
+            mailboxSpecialUseService,
+            placementMoveService,
+        };
+        // A matched filter's actions (label upsert, exclusive move) apply on
+        // the same body-sync pass, reusing the placement mover for the move
+        // (RFC 034 Decision 3.1).
+        const filterConfig = buildFilterConfig({
+            filterService,
+            messageLabelService,
+            mailboxService,
+            placementMoveService,
+        });
+        const bodySyncService = new BodySyncService(messageService, storage, threadMessageService, addressService, envelopeService, new SyncWarningService(syncWarningRepository), log, placementConfig, filterConfig, {
+            quarantineService: new QuarantineService(quarantineRepository, mailboxSpecialUseRepository, config.workerVersion, log),
+            mailboxId,
+            uidValidity: mailbox.uidValidity ?? 0,
+            attempts: receiveCount,
+        }, { flagQueueService }, 
+        // An invitation becomes a card the first time the message is seen,
+        // alongside the filters that run on the same pass (issue #1033).
+        { calendarSuggestionService, calendarStore, filterService });
+        // Guard at the openBox choke point (epic #1281 invariants 3 & 5). The
+        // served UIDVALIDITY is only knowable by opening the box, which only a
+        // genuine fetch needs — BodySyncService.syncBodies skips connecting
+        // entirely when every message already has a stored body (nothing would
+        // touch a stored UID either way) — so the check fires lazily, the first
+        // time `openBox` is actually called, instead of forcing an extra open
+        // on every event.
+        const getConnectionChecked = async () => guardConnectionCursor(await borrowed.getConnection(), { mailboxService }, accountId, mailbox);
+        // Both the sync attempt AND the retry-exhaustion resolution below run
+        // against the SAME borrowed connection, so the mailbox stays open
+        // across the two — the connection is only released once both are done.
+        const folder = {
+            mailboxId: mailbox.mailboxId,
+            fullPath: mailbox.fullPath,
+            uidValidity: mailbox.uidValidity,
+            placement: await resolveFolderPlacement(mailboxSpecialUseService, accountId, mailbox.mailboxId),
+        };
+        await (async () => {
+            const result = await bodySyncService.syncBodies(messageIds, accountId, account.accountConfigId, folder, getConnectionChecked, force);
+            if (result.failedMessageIds.length === 0) {
+                return;
+            }
+            if (receiveCount < config.attempts.body) {
+                // Redelivery budget remains: let SQS retry the whole record
+                // naturally. Messages that already synced skip via the
+                // already-stored guard on the next attempt, so only the failed
+                // ones actually redo work. This — not a manual re-enqueue — is
+                // what lets a genuine processing failure ever reach the body-dlq.
+                throw buildRetryableFailureError(result.failedMessageIds, receiveCount, config.attempts.body);
+            }
+            // Redelivery budget exhausted: a persistent per-message failure is
+            // never a steady state (epic #1281 invariant 3). Resolve every
+            // failed id into exactly one of the two terminal outcomes instead of
+            // letting the record dead-letter with no diagnosis.
+            const { brokenMessageIds } = await resolveExhaustedBodySyncFailures({
+                messageService,
+                storageService: storage,
+                log,
+            }, {
+                accountId,
+                accountConfigId: account.accountConfigId,
+                mailboxId,
+                mailboxPath: mailbox.fullPath,
+                failedMessageIds: result.failedMessageIds,
+                getConnection: getConnectionChecked,
+            });
+            // A broken body is terminal on a record the handler acks, so the
+            // handler-outcome series never sees it.
+            if (brokenMessageIds.length > 0) {
+                metrics.imapFailure("SYNC_MESSAGE_BODY_BROKEN", "other", brokenMessageIds.length);
+            }
+        })()
+            .catch((error) => {
+            // Expected pause (epic #1281 invariant 3), not a fault: ack and
+            // skip rather than propagating into SQS retry/DLQ. The read stays
+            // served from whatever is already stored; the fetch resumes once
+            // the mailbox returns to normal.
+            if (error instanceof MailboxCursorPausedError) {
+                log.info({ accountId, mailboxId, cursorState: error.state }, "UIDVALIDITY changed; mailbox cursor tripped, pausing outbound body sync");
+                return;
+            }
+            throw error;
+        })
+            .finally(() => borrowed.release());
+    });
+};

package/dist/handlers/sync-messages.d.ts

@@ -0,0 +1,29 @@
+import type { AccountItem, IMessageFlagPushRepository } from "@remit/data-ports";
+import type { Logger } from "@remit/logger";
+import { type SyncedMessage } from "@remit/mailbox-service";
+import type { ProcessContext } from "../context.js";
+import { type EmitEvent } from "../emit.js";
+import type { SyncMessagesEvent } from "../events.js";
+/** Slice synced messages into body-sync batches, each one ranged FETCH. */
+export declare const batchSyncedMessages: (syncedMessages: SyncedMessage[], batchSize: number) => SyncedMessage[][];
+export declare const syncMessages: (event: SyncMessagesEvent, ctx: ProcessContext) => Promise<void>;
+/**
+ * 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 declare const drainPendingFlagPushes: (flagPushMarkerService: IMessageFlagPushRepository, account: AccountItem, mailboxId: string, log: Logger, emit: EmitEvent) => Promise<void>;

package/dist/handlers/sync-messages.js

@@ -0,0 +1,285 @@
+import { isNotFoundError } from "@remit/data-ports/errors";
+import { SyncPhase } from "@remit/domain-enums";
+import { RefreshTokenError } from "@remit/mail-oauth-service";
+import { isMailboxMutationInFlight, MailConnectionError, MessageSyncService, QuarantineService, SyncWarningService, } from "@remit/mailbox-service";
+import pMap from "p-map";
+import { isAccountDeleted, isMailSyncDisabled, isUnsyncableHost, } from "../account-check.js";
+import { emitFrom, SYNC_MESSAGES_PENDING } from "../emit.js";
+import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
+import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
+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, batchSize) => {
+    const batches = [];
+    for (let i = 0; i < syncedMessages.length; i += batchSize) {
+        batches.push(syncedMessages.slice(i, i + batchSize));
+    }
+    return batches;
+};
+export const syncMessages = async (event, ctx) => {
+    const { log, pool, metrics, config } = ctx;
+    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, } = ctx.client;
+    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;
+    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, ctx.oauth), 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, pool.borrow(account, credentials), {
+                    accountService,
+                    mailboxService,
+                    messageService,
+                    envelopeService,
+                    addressService,
+                    threadMessageService,
+                    mailboxSpecialUseService,
+                    quarantineService,
+                    syncWarningRepository,
+                    flagPushMarkerService,
+                    messageFlagService,
+                    emit: emitFrom(ctx),
+                    metrics,
+                    config,
+                }, 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");
+        }
+    });
+};
+// 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, account, mailboxId, log, emit) => {
+    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 = {
+            type: "FLAG_PUSH",
+            accountId: account.accountId,
+            accountConfigId: account.accountConfigId,
+            messageId: marker.messageId,
+            flagName: marker.flagName,
+        };
+        return emit(rearmEvent).catch((error) => {
+            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, account, borrowed, deps, log) => {
+    const { accountService, mailboxService, messageService, envelopeService, addressService, threadMessageService, mailboxSpecialUseService, quarantineService, syncWarningRepository, flagPushMarkerService, messageFlagService, emit, metrics, config, } = 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 result = await (async () => {
+        const connection = await borrowed.getConnection();
+        const syncService = new MessageSyncService(connection, mailboxService, mailboxSpecialUseService, messageService, envelopeService, addressService, threadMessageService, new SyncWarningService(syncWarningRepository), log, flagPushMarkerService, messageFlagService, new QuarantineService(quarantineService, mailboxSpecialUseService, config.workerVersion, log));
+        return syncService.syncMessages(mailboxId, account.accountId, account.accountConfigId, MESSAGE_BATCH_SIZE);
+    })().finally(() => borrowed.release());
+    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) {
+        metrics.imapFailure("SYNC_MESSAGES_CURSOR_STALLED", "other", 1);
+    }
+    // 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, config.bodyBatchSize);
+        log.info({ count: result.syncedMessages.length, batches: batches.length }, "Emitting SYNC_MESSAGE_BODY events");
+        await pMap(batches, (batch) => {
+            const bodyEvent = {
+                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 = {
+            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/dist/index.d.ts

@@ -0,0 +1,9 @@
+import type { SQSHandler } from "aws-lambda";
+/**
+ * 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 declare const parseReceiveCount: (value: string | undefined) => number;
+export declare const handler: SQSHandler;

package/dist/index.js

@@ -0,0 +1,67 @@
+import { createLogger } from "@remit/logger";
+import { queueNameFromEventSource, recordImapFailure, recordQueueEvent, } from "@remit/logger-lambda/metrics";
+import { installNodeLogger, withTelemetry } from "@remit/logger-lambda/node";
+import { env } from "expect-env";
+import { isBodySyncEnabled } from "./body-sync-gate.js";
+import { imapFailureKind } from "./failure-kind.js";
+import { lambdaProcessContext } from "./lambda-context.js";
+import { processEvent } from "./processor.js";
+installNodeLogger();
+const log = createLogger();
+const bodySyncParameterName = env.BODY_SYNC_ENABLED_PARAMETER_NAME;
+const isPausedBodySync = async (event) => event.type === "SYNC_MESSAGE_BODY" &&
+    !(await isBodySyncEnabled(bodySyncParameterName, log));
+/**
+ * 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) => {
+    const parsed = Number.parseInt(value ?? "1", 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 1;
+};
+export const handler = withTelemetry(async (event) => {
+    const batchItemFailures = [];
+    const ctx = await lambdaProcessContext(log);
+    for (const record of event.Records) {
+        const imapEvent = 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");
+        if (await isPausedBodySync(imapEvent)) {
+            log.info({ eventType: imapEvent.type, messageId: record.messageId }, "Body sync paused via SSM toggle, acking and skipping");
+            continue;
+        }
+        const queue = queueNameFromEventSource(record.eventSourceARN);
+        const opStart = Date.now();
+        const failed = await processEvent(imapEvent, ctx, 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 };
+});

package/dist/lambda-context.d.ts

@@ -0,0 +1,8 @@
+import type { IMailboxLockRepository } from "@remit/data-ports";
+import type { Logger } from "@remit/logger";
+import type { ProcessContext, WorkerMetrics } from "./context.js";
+import { type EmitEvent } from "./emit.js";
+import type { WorkerQueues } from "./queues.js";
+export declare const lambdaMetrics: WorkerMetrics;
+export declare const lambdaEmitEvent: (queues: WorkerQueues, mailboxLock: IMailboxLockRepository) => EmitEvent;
+export declare const lambdaProcessContext: (log: Logger) => Promise<ProcessContext>;

package/dist/lambda-context.js

@@ -0,0 +1,33 @@
+import { getClient } from "@remit/backend/client";
+import { recordImapFailure } from "@remit/logger-lambda/metrics";
+import { createMailOAuthService, microsoftProviderConfig, } from "@remit/mail-oauth-service";
+import { env } from "expect-env";
+import { imapWorkerConfigFromEnv, poolOptionsFromEnv } from "./config-env.js";
+import { createConnectionPool } from "./connection-pool.js";
+import { createConnectionScopeWithCredentials } from "./connection-scope.js";
+import { createEmitEvent } from "./emit.js";
+import { s3AccountObjects } from "./s3-account-objects.js";
+import { sqsWorkerQueues, workerQueueUrlsFromEnv } from "./sqs-queues.js";
+export const lambdaMetrics = { imapFailure: recordImapFailure };
+export const lambdaEmitEvent = (queues, mailboxLock) => createEmitEvent({ queues, mailboxLock, metrics: lambdaMetrics });
+const buildContext = async (log) => ({
+    client: await getClient(),
+    queues: sqsWorkerQueues(workerQueueUrlsFromEnv()),
+    pool: createConnectionPool(poolOptionsFromEnv(process.env), createConnectionScopeWithCredentials),
+    metrics: lambdaMetrics,
+    config: imapWorkerConfigFromEnv(process.env),
+    log,
+    oauth: createMailOAuthService(microsoftProviderConfig({
+        clientId: process.env.MSOAUTH_CLIENT_ID ?? "",
+        clientSecret: process.env.MSOAUTH_CLIENT_SECRET ?? "",
+        overrides: process.env.MSOAUTH_TOKEN_ENDPOINT
+            ? { tokenEndpoint: process.env.MSOAUTH_TOKEN_ENDPOINT }
+            : undefined,
+    })),
+    accountObjects: s3AccountObjects(() => env.S3_BUCKET_NAME),
+});
+let context;
+export const lambdaProcessContext = (log) => {
+    context ??= buildContext(log);
+    return context;
+};

package/dist/mailbox-row.d.ts

@@ -0,0 +1,9 @@
+import type { IMailboxRepository, MailboxItem } from "@remit/data-ports";
+export type MailboxRow = {
+    kind: "present";
+    mailbox: MailboxItem;
+} | {
+    kind: "gone";
+    mailboxId: string;
+};
+export declare const findMailboxRow: (mailboxService: Pick<IMailboxRepository, "get">, accountId: string, mailboxId: string) => Promise<MailboxRow>;

package/dist/mailbox-row.js

@@ -0,0 +1,6 @@
+import { isNotFoundError } from "@remit/data-ports/errors";
+export const findMailboxRow = (mailboxService, accountId, mailboxId) => mailboxService.get(accountId, mailboxId).then((mailbox) => mailbox ? { kind: "present", mailbox } : { kind: "gone", mailboxId }, (error) => {
+    if (isNotFoundError(error))
+        return { kind: "gone", mailboxId };
+    throw error;
+});

package/dist/poller.d.ts

@@ -0,0 +1 @@
+export {};