@remit/imap-worker 0.0.90 → 0.0.92

package/dist/handlers/mailbox-management.js

@@ -0,0 +1,294 @@
+import { refreshFolderAppointmentLabels } from "@remit/backend/folder-role-labels";
+import { isNotFoundError, NotFoundError } from "@remit/data-ports/errors";
+import { MailboxSyncStatus } from "@remit/domain-enums";
+import { FolderGoneUpstreamError, FolderRenameSettleError, isMailboxAbsentUpstream, isMailboxPresentUpstream, isMailboxRefusedUpstream, MailboxManagementService, upstreamFailureReason, } from "@remit/mailbox-service";
+import { isAccountDeleted } from "../account-check.js";
+import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
+import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
+/**
+ * The outcome of a create, written against the state a create in flight is:
+ * `pending` with no recorded rename target (D3, D10). Without the absence
+ * check, a create redelivered after a lost acknowledgement settles a row a
+ * rename has since claimed and kills the rename silently.
+ */
+const recordCreateOutcome = async (mailboxService, accountId, mailboxId, to, syncFailureReason = "") => {
+    const written = await mailboxService.transition(accountId, mailboxId, {
+        from: [MailboxSyncStatus.pending],
+        wherePendingPath: null,
+        to,
+        set: { syncFailureReason },
+    });
+    if (!written)
+        throw new NotFoundError(`Mailbox not found: ${mailboxId}`);
+};
+/**
+ * Pinned invariant for the whole-chain terminal guards below.
+ *
+ * Each handler wraps its `MailboxManagementService.sync*` chain in a try/catch
+ * that treats a NotFoundError as terminal (ack with a WARN, issue #289). That is
+ * only sound while the sole row a NotFoundError can refer to is the target
+ * mailbox, so its absence can only mean the user deleted the folder mid-sync —
+ * never an unrelated missing entity that should have been retried.
+ *
+ * `syncCreate` and `syncDelete` hold to that by touching nothing but the target
+ * row. `syncRename` also writes every other row that recorded the same intent,
+ * and keeps the invariant by treating a lost predicate as an outcome rather than
+ * an error: a descendant deleted mid-settle is skipped, never raised. The
+ * appointment-label refresh writes `account_setting` rows, whose reads answer
+ * absent rather than throwing. Any sync method that reads or writes a second
+ * entity owes the same, or these catches must be narrowed (match the mailboxId /
+ * re-check existence) before a NotFoundError from elsewhere is silently acked.
+ */
+/**
+ * Handle MAILBOX_CREATE event
+ */
+const handleCreate = async (event, ctx) => {
+    const { log, pool } = ctx;
+    const { account: accountService, mailbox: mailboxService, secrets, } = ctx.client;
+    const { accountId, mailboxId, path, subscribe } = event;
+    log.info({ event: event.type, accountId, mailboxId, path }, "Handling event");
+    const account = await accountService.get(accountId);
+    if (!account) {
+        throw new Error(`Account ${accountId} not found`);
+    }
+    if (isAccountDeleted(account, log)) {
+        return;
+    }
+    await withOAuthLifecycle(buildLifecycleDeps(secrets, accountService, ctx.oauth), account, log, async (credentials) => {
+        const scope = pool.borrow(account, credentials);
+        const managementService = new MailboxManagementService(mailboxService, log);
+        try {
+            await managementService
+                .syncCreate(accountId, mailboxId, path, scope.getConnection, subscribe)
+                .then((result) => {
+                if (result.success) {
+                    log.info({
+                        accountId,
+                        mailboxId,
+                        path,
+                        existingMailboxId: result.existing?.mailboxId,
+                    }, "Mailbox created on IMAP");
+                }
+                else {
+                    log.error({ accountId, mailboxId, path, error: result.error }, "Failed to create mailbox on IMAP");
+                }
+            })
+                .catch(async (error) => {
+                // Check if mailbox already exists (idempotent)
+                if (isMailboxPresentUpstream(error)) {
+                    log.info({ accountId, mailboxId, path }, "Mailbox already exists, marking as synced");
+                    await recordCreateOutcome(mailboxService, accountId, mailboxId, MailboxSyncStatus.synced);
+                }
+                else {
+                    await recordCreateOutcome(mailboxService, accountId, mailboxId, MailboxSyncStatus.failed, upstreamFailureReason(error));
+                    if (isMailboxRefusedUpstream(error)) {
+                        log.error({ accountId, mailboxId, path, intent: "create", error }, "Mail server refused the create");
+                        return;
+                    }
+                    throw error;
+                }
+            })
+                .finally(() => scope.release());
+        }
+        catch (error) {
+            // The mailbox row was deleted between enqueue and this sync — the
+            // create-then-status-write throws NotFoundError, which can never
+            // succeed on retry and would poison the account's per-group FIFO
+            // forever (issue #289, same class as #287/#290). A folder the user
+            // deleted is an expected terminal outcome: ack with a WARN. Real
+            // IMAP/infra failures carry other errors and still propagate.
+            if (isNotFoundError(error)) {
+                log.warn({ accountId, mailboxId, path, eventId: event.eventId }, "Skipping MAILBOX_CREATE: mailbox no longer exists (deleted)");
+                return;
+            }
+            throw error;
+        }
+    });
+};
+/**
+ * Handle MAILBOX_RENAME event
+ */
+const handleRename = async (event, ctx) => {
+    const { log, pool } = ctx;
+    const { account: accountService, accountSetting: accountSettingService, mailbox: mailboxService, secrets, } = ctx.client;
+    const { accountId, mailboxId, oldPath, newPath } = event;
+    log.info({ event: event.type, accountId, mailboxId, oldPath, newPath }, "Handling event");
+    const account = await accountService.get(accountId);
+    if (!account) {
+        throw new Error(`Account ${accountId} not found`);
+    }
+    if (isAccountDeleted(account, log)) {
+        return;
+    }
+    await withOAuthLifecycle(buildLifecycleDeps(secrets, accountService, ctx.oauth), account, log, async (credentials) => {
+        const scope = pool.borrow(account, credentials);
+        const managementService = new MailboxManagementService(mailboxService, log);
+        try {
+            await managementService
+                .syncRename(accountId, mailboxId, oldPath, newPath, scope.getConnection)
+                .then(async (result) => {
+                if (!result.success) {
+                    log.error({ accountId, mailboxId, oldPath, newPath, error: result.error }, "Failed to rename mailbox on IMAP");
+                    return;
+                }
+                log.info({ accountId, mailboxId, oldPath, newPath }, "Mailbox renamed on IMAP");
+                if (!result.renamed)
+                    return;
+                // The path recorded beside each role appointment (#887) moves with
+                // the settle, because under D2 that is the first moment the new
+                // path is one the server holds.
+                //
+                // A label is display-only and this runs after the server rename
+                // landed, so letting it fail would take the job down the failure
+                // path and mark a completed rename refused. Logged and dropped;
+                // the next appointment write records the folder's current path
+                // anyway.
+                await refreshFolderAppointmentLabels(accountSettingService, account.accountConfigId, accountId, {
+                    mailboxId,
+                    oldPath: result.renamed.oldPath,
+                    newPath: result.renamed.newPath,
+                }, result.renamed.delimiter).catch((error) => {
+                    log.error({ accountId, mailboxId, oldPath, newPath, error }, "Renamed folder settled, but its role-appointment labels did not move");
+                });
+            })
+                .catch(async (error) => {
+                // The server executed the rename and only the local settle did not
+                // finish. That is not a refused rename: marking the rows `failed`
+                // would offer a retry of work already done and leave `fullPath`
+                // naming a path the server no longer holds. Rethrow, so the
+                // redelivery finishes the settle against an intent still standing.
+                if (error instanceof FolderRenameSettleError) {
+                    log.error({ accountId, mailboxId, oldPath, newPath, error }, "Rename landed on the server; the settle will finish on redelivery");
+                    throw error;
+                }
+                // The folder the rename was to move is confirmed gone: the
+                // server refused the RENAME as non-existent and its own listing
+                // held neither path. The rename decides that, once, where the
+                // evidence is — re-reading the response code here would make
+                // every `NONEXISTENT` this code cannot classify destroy the
+                // folder's mail. Removing the root row alone is the orphaning
+                // bug: every descendant recorded the same intent (D6) and would
+                // be left `pending` at a path that does not exist, with its mail
+                // stranded out of every reader (D8).
+                if (error instanceof FolderGoneUpstreamError) {
+                    log.info({ accountId, mailboxId, oldPath, intent: "rename" }, "Source mailbox not found, deleting local folder and its mail");
+                    await managementService.abandonRenameSubtree(accountId, mailboxId, oldPath, newPath);
+                    return;
+                }
+                // T6. Nothing is restored — `fullPath` was never written, and
+                // each intent-carrying row keeps its target so the client can
+                // name what the rename was aiming at and offer a retry.
+                await managementService.failRename(accountId, mailboxId, oldPath, newPath, upstreamFailureReason(error));
+                if (isMailboxRefusedUpstream(error)) {
+                    log.error({
+                        accountId,
+                        mailboxId,
+                        oldPath,
+                        newPath,
+                        intent: "rename",
+                        error,
+                    }, "Mail server refused the rename");
+                    return;
+                }
+                throw error;
+            })
+                .finally(() => scope.release());
+        }
+        catch (error) {
+            // The mailbox row was deleted between enqueue and this sync — the
+            // status write-back throws NotFoundError, unretryable and would poison
+            // the account's per-group FIFO forever (issue #289 class). Ack with a
+            // WARN; real IMAP/infra failures carry other errors and still propagate.
+            if (isNotFoundError(error)) {
+                log.warn({ accountId, mailboxId, oldPath, newPath, eventId: event.eventId }, "Skipping MAILBOX_RENAME: mailbox no longer exists (deleted)");
+                return;
+            }
+            throw error;
+        }
+    });
+};
+/**
+ * Handle MAILBOX_DELETE event
+ */
+const handleDelete = async (event, ctx) => {
+    const { log, pool } = ctx;
+    const { account: accountService, mailbox: mailboxService, secrets, } = ctx.client;
+    const { accountId, mailboxId, path } = event;
+    log.info({ event: event.type, accountId, mailboxId, path }, "Handling event");
+    const account = await accountService.get(accountId);
+    if (!account) {
+        throw new Error(`Account ${accountId} not found`);
+    }
+    if (isAccountDeleted(account, log)) {
+        return;
+    }
+    await withOAuthLifecycle(buildLifecycleDeps(secrets, accountService, ctx.oauth), account, log, async (credentials) => {
+        const scope = pool.borrow(account, credentials);
+        const managementService = new MailboxManagementService(mailboxService, log);
+        try {
+            await managementService
+                .syncDelete(accountId, mailboxId, path, scope.getConnection)
+                .then((result) => {
+                if (result.success) {
+                    log.info({ accountId, mailboxId, path }, "Mailbox deleted on IMAP");
+                }
+                else {
+                    log.error({ accountId, mailboxId, path, error: result.error }, "Failed to delete mailbox on IMAP");
+                }
+            })
+                .catch(async (error) => {
+                // The folder is already gone from the server, so the delete has
+                // happened. Its mail still goes with it (D8), which is the whole
+                // point of the settle.
+                if (isMailboxAbsentUpstream(error)) {
+                    log.info({ accountId, mailboxId, path, intent: "delete" }, "Mailbox not found on IMAP, removing the local folder and its mail");
+                    await managementService.settleDelete(accountId, mailboxId);
+                }
+                else {
+                    // T9, INBOX included. The API refuses a delete of INBOX, so the
+                    // worker's backstop is unreachable from it; if something else
+                    // reaches it, the honest outcome is `failed`, not `synced` —
+                    // the folder was never deleted and nothing was undone.
+                    await managementService.failDelete(accountId, mailboxId, upstreamFailureReason(error));
+                    if (error instanceof Error &&
+                        error.message.includes("Cannot delete INBOX")) {
+                        log.error({ accountId, mailboxId, path, intent: "delete" }, "Cannot delete INBOX");
+                        // Don't rethrow — no retry can make this succeed.
+                        return;
+                    }
+                    if (isMailboxRefusedUpstream(error)) {
+                        log.error({ accountId, mailboxId, path, intent: "delete", error }, "Mail server refused the delete");
+                        return;
+                    }
+                    throw error;
+                }
+            })
+                .finally(() => scope.release());
+        }
+        catch (error) {
+            // The mailbox row was already deleted (a duplicate/racing delete) — the
+            // error-recovery status write throws NotFoundError, unretryable and
+            // would poison the account's per-group FIFO forever (issue #289 class).
+            // The delete has effectively happened: ack with a WARN. Real IMAP/infra
+            // failures carry other errors and still propagate.
+            if (isNotFoundError(error)) {
+                log.warn({ accountId, mailboxId, path, eventId: event.eventId }, "Skipping MAILBOX_DELETE: mailbox no longer exists (deleted)");
+                return;
+            }
+            throw error;
+        }
+    });
+};
+/**
+ * Process mailbox management events
+ */
+export const processMailboxManagement = async (event, ctx) => {
+    switch (event.type) {
+        case "MAILBOX_CREATE":
+            return handleCreate(event, ctx);
+        case "MAILBOX_RENAME":
+            return handleRename(event, ctx);
+        case "MAILBOX_DELETE":
+            return handleDelete(event, ctx);
+    }
+};

package/dist/handlers/mailbox-sync-order.d.ts

@@ -0,0 +1,21 @@
+export type MailboxSyncOrderEntry = {
+    mailboxId: string;
+    fullPath: string;
+    specialUse?: readonly string[];
+};
+/**
+ * Sync priority for a single mailbox. INBOX always leads; otherwise the
+ * mailbox's special-use flags resolve to a priority, defaulting to
+ * NORMAL_PRIORITY for plain user folders and unflagged mailboxes. When a
+ * mailbox carries both a leading flag (Sent/Drafts) and a trailing one
+ * (Junk/Trash) — rare, but possible with misconfigured servers — the trailing
+ * one wins: de-prioritising a bulk folder is the safer first-impression
+ * choice.
+ */
+export declare const mailboxSyncPriority: (entry: MailboxSyncOrderEntry) => number;
+/**
+ * Order mailboxes for sync fan-out: INBOX first, then Sent/Drafts, then normal
+ * folders, with Junk/Spam and Trash last. Ties break alphabetically by
+ * fullPath so the order is deterministic.
+ */
+export declare const orderMailboxesForSync: <T extends MailboxSyncOrderEntry>(mailboxes: readonly T[]) => T[];

package/dist/handlers/mailbox-sync-order.js

@@ -0,0 +1,50 @@
+import { MailboxSpecialUse } from "@remit/domain-enums";
+// Sync priority by special-use, lowest first. Real mail leads (INBOX, then
+// Sent and Drafts), normal folders sit in the middle at NORMAL_PRIORITY, and
+// the low-value bulk folders (Junk/Spam, Trash) are pushed to the end so a
+// fresh account fills its inbox before its spam (issue #567). Keyed by the
+// bare runtime values from `@remit/domain-enums` (e.g. "Junk"), which match the
+// values stored in the Mailbox `specialUse` DynamoDB set.
+const INBOX_PRIORITY = 0;
+const NORMAL_PRIORITY = 4;
+const SPECIAL_USE_PRIORITY = {
+    [MailboxSpecialUse.Sent]: 1,
+    [MailboxSpecialUse.Drafts]: 2,
+    [MailboxSpecialUse.Flagged]: 3,
+    [MailboxSpecialUse.Junk]: 5,
+    [MailboxSpecialUse.Trash]: 6,
+};
+const isInbox = (fullPath) => fullPath.toUpperCase() === "INBOX";
+/**
+ * Sync priority for a single mailbox. INBOX always leads; otherwise the
+ * mailbox's special-use flags resolve to a priority, defaulting to
+ * NORMAL_PRIORITY for plain user folders and unflagged mailboxes. When a
+ * mailbox carries both a leading flag (Sent/Drafts) and a trailing one
+ * (Junk/Trash) — rare, but possible with misconfigured servers — the trailing
+ * one wins: de-prioritising a bulk folder is the safer first-impression
+ * choice.
+ */
+export const mailboxSyncPriority = (entry) => {
+    if (isInbox(entry.fullPath))
+        return INBOX_PRIORITY;
+    const priorities = (entry.specialUse ?? [])
+        .map((flag) => SPECIAL_USE_PRIORITY[flag])
+        .filter((priority) => priority !== undefined);
+    if (priorities.length === 0)
+        return NORMAL_PRIORITY;
+    const trailing = priorities.filter((priority) => priority > NORMAL_PRIORITY);
+    if (trailing.length > 0)
+        return Math.max(...trailing);
+    return Math.min(...priorities);
+};
+/**
+ * Order mailboxes for sync fan-out: INBOX first, then Sent/Drafts, then normal
+ * folders, with Junk/Spam and Trash last. Ties break alphabetically by
+ * fullPath so the order is deterministic.
+ */
+export const orderMailboxesForSync = (mailboxes) => [...mailboxes].sort((a, b) => {
+    const priorityDelta = mailboxSyncPriority(a) - mailboxSyncPriority(b);
+    if (priorityDelta !== 0)
+        return priorityDelta;
+    return a.fullPath.localeCompare(b.fullPath);
+});

package/dist/handlers/message-copy.d.ts

@@ -0,0 +1,40 @@
+import type { ProcessContext } from "../context.js";
+import type { MessageCopyEvent } from "../events.js";
+/**
+ * Where the destination says this copy is. `unprobeable` is the row that
+ * carries no usable Message-ID header (drafts, automated senders and bounces
+ * do arrive without one): the server was never
+ * asked, so its silence says nothing.
+ */
+export type CopyProbe = {
+    kind: "confirmed";
+    uid: number;
+} | {
+    kind: "absent";
+} | {
+    kind: "unprobeable";
+};
+/**
+ * Handle MESSAGE_COPY events.
+ * Executes IMAP COPY command and updates local state with new UID.
+ *
+ * IMAP COPY is not idempotent and the message queue is FIFO per account, so
+ * this handler never manufactures a retry to resolve an ambiguous answer: a
+ * second COPY duplicates the mail, and a record that keeps coming back blocks
+ * every later move, copy and delete for that account (issues #287, #289,
+ * #290). Ambiguity is resolved in place, by asking the destination.
+ *
+ * A fault the server threw is still retried up to
+ * the `config.attempts.messageCopy` budget, because it may be a dropped connection.
+ * Two guards make that safe: a redelivery asks the destination BEFORE issuing
+ * COPY again, and the last attempt settles the row instead of dead-lettering
+ * it. The copy row is a reconcile-model dependent (`copySettledMessage` writes
+ * its ThreadMessage row at `uid: 0` before the server has confirmed anything,
+ * docs/architecture/imap-mutations.md R2) and these terminal settles are its
+ * reconciliation path: every verdict the server gives an answer for settles the
+ * row out of `uid: 0`/`moving` (#1097). A server that cannot be reached at all
+ * gives no verdict — the record dead-letters with the row untouched, the same
+ * caveat `resolveExhaustedMessageMoveFailure` carries, because absence is only
+ * ever concluded from an answer.
+ */
+export declare const handleMessageCopy: (event: MessageCopyEvent, ctx: ProcessContext, receiveCount: number) => Promise<void>;