@remit/imap-worker 0.0.89 → 0.0.91

package/dist/handlers/message-move-terminal.js

@@ -0,0 +1,94 @@
+import { MessageMutation, MessageSyncStatus } from "@remit/domain-enums";
+import { isMessageGoneFromOpenMailbox, restoreSourcePlacement, } from "@remit/mailbox-service";
+/**
+ * Resolve a MESSAGE_MOVE failure that has exhausted the message queue's
+ * redelivery budget into exactly one of two terminal outcomes, mirroring
+ * `resolveExhaustedPlacementMoveFailure` and `resolveExhaustedFlagPushFailure`
+ * for the same failure taxonomy (issue #655) — no third, softer outcome.
+ *
+ * The move's pending state is the Message row itself (`status: moving`,
+ * `originalMailboxId`/`originalUid`, `mailboxId` already pointing at the
+ * destination), not a separate marker, so the outcomes act on that row.
+ *
+ * 1. RECONCILED (expected) — the message no longer exists at the move's source
+ *    on IMAP, confirmed by {@link isMessageGoneFromOpenMailbox} rather than by
+ *    a FETCH coming back empty. Either the MOVE did execute server-side and
+ *    the connection dropped before the tagged OK was read, or a foreign client
+ *    moved or expunged the message; from here those are indistinguishable and
+ *    have the same answer. The stale Message/ThreadMessage rows are deleted
+ *    via `deleteIfPlacement` and the caller resyncs both folders, so
+ *    whichever folder actually holds the message re-projects it with the
+ *    server's own UID. Metric only, no alarm — routine.
+ * 2. BROKEN — the message is still at the source, so the move never took
+ *    effect, but it keeps failing: broken code or a broken account, not a
+ *    transient blip. The row is put back where the server has just said the
+ *    message is, as `resolveExhaustedMessageDeleteFailure` does (#1098). Logged
+ *    with an `alert`-shaped entry for an operator alarm; never re-thrown
+ *    (terminal — the caller acks either way, since retrying a
+ *    permanently-broken move can never succeed).
+ *
+ *    Leaving the row `moving` is what this replaces. BROKEN is terminal, so
+ *    nothing was ever going to come back and settle it, and only `updateUid`
+ *    clears `moving` — the row kept a `mailboxId` naming the destination and a
+ *    `uid` belonging to the source, which `bindsForeignUid` refuses to act on,
+ *    leaving the message undeletable and unmovable for good (issue #1005).
+ *    Restoring the pair is not the revert-on-ambiguity PR #652 was pulled for:
+ *    the presence probe above has just answered, so this writes a placement the
+ *    server confirmed, and a MOVE that lands after all is re-projected by the
+ *    resync the caller runs.
+ *
+ * A server that cannot be reached at exhaustion time never reaches either
+ * verdict: the probe throws and the record dead-letters with the row untouched.
+ * Absence is only ever concluded from an answer the server gave.
+ *
+ * An operator reading `message_move_failed` should know one case where the
+ * message is not actually at the source: a message another client expunged
+ * mid-session can answer an empty FETCH while the server still lists its UID
+ * in SEARCH, until it is allowed to send the untagged EXPUNGE. That message
+ * lands in BROKEN, and BROKEN is terminal — the row is bound to a source the
+ * message has already left and the alert stands until someone clears it. The
+ * reverse mistake discards the row for live mail, so the cost is paid
+ * deliberately.
+ */
+export const resolveExhaustedMessageMoveFailure = async (deps, input) => {
+    const { accountId, accountConfigId, messageId, sourceMailboxId, uid, sourceMailboxPath, getConnection, } = input;
+    const connection = await getConnection();
+    await connection.openBox(sourceMailboxPath, true);
+    if (await isMessageGoneFromOpenMailbox(connection, uid)) {
+        const reconciled = await deps.messageService.deleteIfPlacement(messageId, input.placement);
+        deps.log.info({
+            metric: "message_move_stale_row_reconciled",
+            accountId,
+            accountConfigId,
+            messageId,
+            uid,
+            sourceMailboxPath,
+            reconciled,
+        }, "Message no longer at its move source after retry exhaustion (move landed server-side, or an external delete or move); stale row reconciled");
+        return { outcome: "reconciled" };
+    }
+    deps.log.error({
+        alert: "message_move_failed",
+        accountId,
+        accountConfigId,
+        messageId,
+        uid,
+        sourceMailboxId,
+        sourceMailboxPath,
+    }, "Message move could not be pushed to IMAP after retry exhaustion; the message is still at its source — row moved back to the source folder");
+    await restoreSourcePlacement(deps, {
+        accountConfigId,
+        messageId,
+        sourceMailboxId,
+        uid,
+        // The probe above just confirmed the pair, so the row is a faithful
+        // projection of the source again — and the move the user asked for did
+        // not happen, with nothing left to try it. `abandoned` is the value that
+        // says so without claiming a retry is coming (imap-mutations R3); the
+        // alert stays for the operator, and the mutation names itself so the
+        // reading pane offers the right way out (issue #1229).
+        syncStatus: MessageSyncStatus.abandoned,
+        abandonedMutation: MessageMutation.move,
+    });
+    return { outcome: "broken" };
+};

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

@@ -0,0 +1,146 @@
+import type { ThreadMessageItem } from "@remit/data-ports";
+import { type IImapConnection } from "@remit/mailbox-service";
+import type { ProcessContext } from "../context.js";
+import type { MessageMoveEvent, SyncMessagesEvent } from "../events.js";
+type EmitSyncMessages = (event: Omit<SyncMessagesEvent, "eventId" | "timestamp">) => Promise<unknown>;
+/**
+ * Re-read both folders' counts from IMAP after a move by enqueuing the existing
+ * per-folder SYNC_MESSAGES sync. Counts are a projection of IMAP, never mutated
+ * locally — the move shifted a message between source and destination, so both
+ * folders must refresh through the one-way pipeline.
+ */
+export declare const emitMoveResync: (emit: EmitSyncMessages, params: {
+    accountId: string;
+    sourceMailboxId: string;
+    destinationMailboxId: string;
+}) => Promise<void>;
+/**
+ * The one-folder half of {@link emitMoveResync}, for a mutation that has no
+ * destination — a permanent delete removed local rows the server still holds,
+ * and only a resync of that folder puts them back.
+ */
+export declare const emitMailboxResync: (emit: EmitSyncMessages, params: {
+    accountId: string;
+    mailboxId: string;
+}) => Promise<void>;
+/**
+ * SEARCH a mailbox for copies of a message identified by its RFC822 Message-ID
+ * header and answer the HIGHEST matching uid. Read-only (EXAMINE, not SELECT) —
+ * this is a verification probe, never a write. `null` when nothing matched.
+ *
+ * The highest uid is the freshly delivered copy only when one exists; deciding
+ * that it does is the caller's job, not this function's. Every probe in this
+ * package wants the highest: uids ascend with arrival inside a UIDVALIDITY, so a
+ * copy that has just landed outranks every copy of the same Message-ID the
+ * folder already held. Where nothing was delivered, the highest is simply the
+ * newest pre-existing copy, and a caller that has not ruled that case out binds
+ * itself to unrelated mail.
+ * One Message-ID can have several server copies in one account (a sieve
+ * `fileinto` + `keep`, a resend, a repeated COPY — `deriveCopyMessageId` reuses
+ * the row, so the second copy is a second server COPY), while `deriveMessageId`
+ * is folder-independent and gives them one local row. Taking the lowest bound
+ * the fresh copy's row to an older copy's uid and orphaned the fresh one, which
+ * a later delete or Empty Trash then expunged by the wrong uid (issue #1122).
+ *
+ * The maximum is computed rather than read off the tail: RFC 3501 leaves the
+ * order of a SEARCH response unspecified, so "last returned" is not "highest".
+ */
+export declare const searchMailboxForHighestMessageIdUid: (connection: IImapConnection, mailboxPath: string, messageIdHeader: string) => Promise<number | null>;
+/**
+ * Which side of a paused mutation the server actually holds the message on.
+ * `gone` is an answer both folders gave; `unprobeable` is the row that carries
+ * no Message-ID header, where the server was never asked and its silence says
+ * nothing.
+ */
+export type PausedPlacement = {
+    kind: "at-source";
+} | {
+    kind: "at-destination";
+    uid: number;
+} | {
+    kind: "gone";
+} | {
+    kind: "unprobeable";
+};
+/**
+ * Ask the server, by Message-ID, which folder holds a message whose mutation a
+ * paused cursor interrupted (issue #1203).
+ *
+ * Reached only on a redelivery, where "the command never left" has stopped
+ * being provable: the earlier attempt's tagged OK can be lost with the
+ * connection, so restoring the source pair on that assumption would write a
+ * settled placement naming a folder the server has already moved the mail out
+ * of. `message-copy.ts` asks the same question for the same reason.
+ *
+ * The SOURCE is asked first and a hit ends it, the gate `confirmTrashMoveUid`
+ * documents (#1122): where the mutation never ran, every hit at the destination
+ * is an older copy of the same Message-ID — a sieve `fileinto` + `keep`, a
+ * multi-label store, a resend — that `deriveMessageId` folds into this one local
+ * row, and binding to it hands a later delete somebody else's uid.
+ *
+ * The source's silence, however, is not the mirror image of its hit. Every
+ * caller here reaches this on a paused cursor, which means the source's
+ * UIDVALIDITY has moved and the folder may have been recreated holding nothing
+ * it held before — so "not at the source" is an answer about the folder, not
+ * about our mutation, and `at-destination` is a sighting rather than a
+ * confirmation. Callers settle it as unproven; see `settlePausedMove`.
+ *
+ * Identity, not position, is what makes this askable at all: a paused cursor
+ * means the source's UIDVALIDITY has moved, so every stored uid for it names
+ * something else, but a SEARCH by header is independent of the axis and answers
+ * the same question the cursor rebuild itself matches rows by. For that reason
+ * the caller passes the UNGUARDED connection — a `guardConnectionCursor` wrap
+ * refuses to open the mailbox at all, and it is bound to the source's snapshot
+ * anyway, so opening the destination through it would trip that mailbox too.
+ */
+export declare const probePausedPlacement: (connection: IImapConnection, input: {
+    messageIdHeader: string | undefined;
+    sourceMailboxPath: string;
+    destinationMailboxPath: string | undefined;
+}) => Promise<PausedPlacement>;
+/**
+ * Resync the affected folders only once the IMAP move has resolved. A move that
+ * fails (or is retried) must not refresh counts off a move that didn't happen,
+ * so the resync is sequenced strictly after `performMove`.
+ */
+export declare const moveThenResync: (performMove: () => Promise<void>, resync: () => Promise<void>) => Promise<void>;
+/**
+ * Build the `set` and `composites` payload for the ThreadMessage update on a
+ * MESSAGE_MOVE.
+ *
+ * The CURRENT row state goes in `composites`; the NEW values go in `set`.
+ * ElectroDB uses `composites` to run the conditional check on the existing row
+ * AND to compute the previous sort-key values needed to recompute the new ones.
+ * Passing the NEW values in `composites` makes the conditional check fail with
+ * ConditionalCheckFailedException, which ElectroDB wraps as NotFoundError, and
+ * the caller silently drops the update. Same root cause as PR #186 fixed for
+ * `flag-queue.ts`.
+ */
+export declare const buildThreadMessageMoveUpdate: (threadMessage: Pick<ThreadMessageItem, "sentDate" | "mailboxId" | "isRead" | "isDeleted" | "hasStars" | "hasAttachment">, newUid: number, destinationMailboxId: string) => {
+    set: {
+        uid: number;
+        mailboxId: string;
+        isDeleted: boolean;
+    };
+    composites: {
+        sentDate: number;
+        mailboxId: string;
+        isRead: boolean;
+        isDeleted: boolean;
+        hasStars: boolean;
+        hasAttachment: boolean;
+    };
+};
+/**
+ * Handle MESSAGE_MOVE events.
+ * Executes IMAP MOVE command and updates local state with new UID.
+ *
+ * A failing move retries on SQS redelivery until `receiveCount` reaches
+ * the `config.attempts.messageMove` budget, at which point
+ * {@link resolveExhaustedMessageMoveFailure} asks IMAP where the message
+ * actually is and settles the row into one terminal outcome (issue #655).
+ * Before that, `syncStatus: failed` marked every attempt and nothing ever
+ * settled the row, so an exhausted move sat `moving`/`failed` forever.
+ */
+export declare const handleMessageMove: (event: MessageMoveEvent, ctx: ProcessContext, receiveCount: number) => Promise<void>;
+export {};