@remit/imap-worker 0.0.90 → 0.0.92

package/dist/e2e-processor-shim.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+import cluster from "node:cluster";
+import { randomUUID } from "node:crypto";
+import { DeleteMessageCommand, ReceiveMessageCommand, } from "@aws-sdk/client-sqs";
+import { createLogger } from "@remit/logger";
+import { installNodeLogger } from "@remit/logger-lambda/node";
+import { createSqsClient } from "@remit/sqs-client/producer";
+import { env } from "expect-env";
+import { handler } from "./index.js";
+installNodeLogger();
+/**
+ * E2E-only queue drainer.
+ *
+ * Production binds the Lambda `handler` (`src/index.ts`) to each queue via an
+ * SQS event-source mapping. The e2e/CI stack runs on ElasticMQ, which has no
+ * event-source mapping, so this process supplies that missing piece: it
+ * long-polls each queue, wraps every received batch in an `SQSEvent`, and
+ * invokes the exact production `handler`. It then honours the returned
+ * `batchItemFailures` the way the SQS service would — deleting the messages
+ * that succeeded and leaving the failures un-deleted so their visibility
+ * timeout lapses and SQS redelivers them. No processing or failure logic lives
+ * here; the prod handler owns all of it.
+ *
+ * This is a test harness, not production code. If it crashes the e2e suite
+ * fails loudly, which is the desired signal — there is no crash net.
+ */
+// Collect all unique queue URLs to poll. Every required queue URL crashes at
+// init via expect-env instead of silently dropping queues.
+const queueUrls = [
+    ...new Set([
+        // FIFO queues for sync operations
+        env.SQS_QUEUE_URL_MAILBOXES,
+        env.SQS_QUEUE_URL_MESSAGES,
+        env.SQS_QUEUE_URL_FLAGS,
+        // Standard body queue (#612) + management queues
+        env.SQS_QUEUE_URL_BODY,
+        env.SQS_QUEUE_URL_MAILBOX_MGMT,
+        env.SQS_QUEUE_URL_MESSAGE_MGMT,
+    ]),
+];
+if (cluster.isPrimary) {
+    // Primary process: fork a worker for each queue
+    const log = createLogger();
+    log.info({ queueUrls, workerCount: queueUrls.length }, "Primary started");
+    // Track which queue each worker handles for restart
+    const workerQueues = new Map();
+    // Fork a worker for each queue
+    for (const queueUrl of queueUrls) {
+        const worker = cluster.fork({ WORKER_QUEUE_URL: queueUrl });
+        workerQueues.set(worker.id, queueUrl);
+        const queueName = new URL(queueUrl).pathname.split("/").pop();
+        log.info({ workerId: worker.id, queueName }, "Forked worker for queue");
+    }
+    // Restart workers that crash
+    cluster.on("exit", (worker, code, signal) => {
+        const queueUrl = workerQueues.get(worker.id);
+        const queueName = queueUrl
+            ? new URL(queueUrl).pathname.split("/").pop()
+            : "unknown";
+        if (signal) {
+            log.info({ workerId: worker.id, queueName, signal }, "Worker killed");
+        }
+        else if (code !== 0) {
+            log.error({ workerId: worker.id, queueName, code }, "Worker crashed, exiting primary");
+            process.exit(1);
+        }
+        else {
+            log.info({ workerId: worker.id, queueName }, "Worker exited cleanly");
+            workerQueues.delete(worker.id);
+        }
+    });
+    // Graceful shutdown: signal all workers
+    const shutdown = () => {
+        log.info("Primary received shutdown signal, stopping workers...");
+        for (const worker of Object.values(cluster.workers ?? {})) {
+            worker?.process.kill("SIGTERM");
+        }
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+else {
+    // Worker process: poll a single queue
+    const queueUrl = env.WORKER_QUEUE_URL;
+    const queueName = new URL(queueUrl).pathname.split("/").pop();
+    const log = createLogger().child({ queue: queueName });
+    const maxMessages = 10; // SQS API limit
+    const sqs = createSqsClient({ queueUrl });
+    let isShuttingDown = false;
+    process.on("SIGINT", () => {
+        log.info("Worker received SIGINT, shutting down...");
+        isShuttingDown = true;
+    });
+    process.on("SIGTERM", () => {
+        log.info("Worker received SIGTERM, shutting down...");
+        isShuttingDown = true;
+    });
+    // Minimal Lambda Context: `withTelemetry` reads `functionName` for the line it
+    // logs per invocation and `awsRequestId` for the scope it opens around it, so
+    // every line one batch produces shares a `requestId` (deploy/vps/README.md,
+    // "Logs"). Minted per batch, like the production poller does — a context built
+    // once would put the whole run under one id, which correlates nothing.
+    const nextContext = () => ({
+        functionName: `e2e-imap-worker-${queueName}`,
+        awsRequestId: randomUUID(),
+    });
+    const pollQueue = async () => {
+        log.info({ maxMessages }, "Worker started, polling...");
+        let consecutiveEmptyPolls = 0;
+        while (!isShuttingDown) {
+            // Use short polling when we just processed messages (likely more waiting)
+            // Use long polling after empty polls to reduce API calls
+            const waitTime = consecutiveEmptyPolls > 0 ? 20 : 0;
+            const response = await sqs.send(new ReceiveMessageCommand({
+                QueueUrl: queueUrl,
+                MaxNumberOfMessages: maxMessages,
+                WaitTimeSeconds: waitTime,
+                VisibilityTimeout: 300,
+                MessageSystemAttributeNames: ["ApproximateReceiveCount"],
+            }));
+            if (!response.Messages || response.Messages.length === 0) {
+                consecutiveEmptyPolls++;
+                continue;
+            }
+            consecutiveEmptyPolls = 0;
+            const messages = response.Messages.flatMap((m) => m.Body && m.ReceiptHandle && m.MessageId
+                ? [
+                    {
+                        messageId: m.MessageId,
+                        receiptHandle: m.ReceiptHandle,
+                        body: m.Body,
+                        receiveCount: m.Attributes?.ApproximateReceiveCount ?? "1",
+                    },
+                ]
+                : []);
+            if (messages.length === 0) {
+                continue;
+            }
+            log.info({ count: messages.length }, "Invoking handler for batch");
+            const event = {
+                Records: messages.map((m) => ({
+                    messageId: m.messageId,
+                    receiptHandle: m.receiptHandle,
+                    body: m.body,
+                    attributes: {
+                        ApproximateReceiveCount: m.receiveCount,
+                        SentTimestamp: "0",
+                        SenderId: "e2e",
+                        ApproximateFirstReceiveTimestamp: "0",
+                    },
+                    messageAttributes: {},
+                    md5OfBody: "",
+                    eventSource: "aws:sqs",
+                    eventSourceARN: queueUrl,
+                    awsRegion: "local",
+                })),
+            };
+            const result = (await handler(event, nextContext(), () => { }));
+            const failedIds = new Set((result?.batchItemFailures ?? []).map((f) => f.itemIdentifier));
+            // Mirror SQS partial-batch-failure semantics: delete the messages the
+            // handler reported as succeeded; leave failures un-deleted so their
+            // visibility timeout lapses and SQS redelivers them (and eventually
+            // dead-letters once maxReceiveCount is hit).
+            const succeeded = messages.filter((m) => !failedIds.has(m.messageId));
+            for (const message of succeeded) {
+                await sqs.send(new DeleteMessageCommand({
+                    QueueUrl: queueUrl,
+                    ReceiptHandle: message.receiptHandle,
+                }));
+            }
+            log.info({ deleted: succeeded.length, leftForRedelivery: failedIds.size }, "Batch processed");
+        }
+        log.info("Worker polling stopped");
+    };
+    pollQueue()
+        .then(() => process.exit(0))
+        .catch((error) => {
+        log.error({ error }, "Worker error");
+        process.exit(1);
+    });
+}

package/dist/emit.d.ts

@@ -0,0 +1,15 @@
+import type { IMailboxLockRepository } from "@remit/data-ports";
+import type { ProcessContext, WorkerMetrics } from "./context.js";
+import type { ImapEvent } from "./events.js";
+import type { WorkerQueues } from "./queues.js";
+type EventInput = Omit<ImapEvent, "eventId" | "timestamp">;
+export type EmitEvent = (event: EventInput) => Promise<void>;
+export declare const SYNC_MESSAGES_PENDING = "SYNC_MESSAGES_PENDING";
+export interface EmitDeps {
+    queues: WorkerQueues;
+    mailboxLock: IMailboxLockRepository;
+    metrics: WorkerMetrics;
+}
+export declare const createEmitEvent: ({ queues, mailboxLock, metrics }: EmitDeps) => EmitEvent;
+export declare const emitFrom: (ctx: Pick<ProcessContext, "queues" | "client" | "metrics">) => EmitEvent;
+export {};

package/dist/emit.js

@@ -0,0 +1,76 @@
+// The deduplication id is the event's own id, so the queue suppresses a
+// re-send of one event (the retry SQS's own idempotency guard is for) and
+// nothing else. A shared id per account or per mailbox instead made the
+// 5-minute window a rate limiter: the second sync of a mailbox within five
+// minutes was discarded before any worker saw it, so mail that arrived after
+// a sync could not be fetched until the window elapsed (issue #37).
+const fifo = (queue) => (event) => queue.send({
+    body: event,
+    groupId: event.accountId,
+    deduplicationId: event.eventId,
+});
+const standard = (queue) => (event) => queue.send({ body: event });
+export const SYNC_MESSAGES_PENDING = "SYNC_MESSAGES_PENDING";
+const SYNC_MESSAGES_PENDING_TTL_SECONDS = 300;
+const senderFor = (type, queues) => {
+    switch (type) {
+        case "SYNC_MAILBOXES":
+            return fifo(queues.mailboxes);
+        case "SYNC_MESSAGES":
+            return fifo(queues.messages);
+        // SYNC_MESSAGE_BODY routes to the single standard body queue (#612).
+        case "SYNC_MESSAGE_BODY":
+            return standard(queues.body);
+        case "MAILBOX_CREATE":
+        case "MAILBOX_RENAME":
+        case "MAILBOX_DELETE":
+            return standard(queues.mailboxManagement);
+        case "MESSAGE_DELETE":
+        case "MESSAGE_MOVE":
+        case "MESSAGE_COPY":
+        case "EMPTY_TRASH":
+        case "APPEND_SENT_MESSAGE":
+        // Rides messageMgmtQueue (issue #1271) rather than a dedicated queue — its
+        // payload carries only our message id (never a UID, unlike the legacy
+        // MESSAGE_MOVE event); per-event-type payload shape, same queue.
+        case "PLACEMENT_MOVE_PUSH":
+            return standard(queues.messageManagement);
+        // Rides the existing flags queue (issue #1273) — this is imap-worker's OWN
+        // re-arm hint (the periodic per-mailbox sync tick catching up a marker
+        // stuck `pending`), distinct from `FlagPushService`'s user-facing hint
+        // sent from the API onto the sync queue. Both land on a queue this worker
+        // already consumes; dispatch is by `type`, not by which queue delivered
+        // the message.
+        case "FLAG_PUSH":
+            return fifo(queues.flags);
+    }
+};
+export const createEmitEvent = ({ queues, mailboxLock, metrics }) => async (event) => {
+    const fullEvent = {
+        ...event,
+        eventId: crypto.randomUUID(),
+        timestamp: Date.now(),
+    };
+    const send = () => senderFor(fullEvent.type, queues)(fullEvent);
+    if (fullEvent.type !== "SYNC_MESSAGES") {
+        await send();
+        return;
+    }
+    const { accountId, mailboxId, eventId } = fullEvent;
+    const previous = await mailboxLock.get(accountId, mailboxId, SYNC_MESSAGES_PENDING);
+    const acquired = await mailboxLock.tryAcquireLock(mailboxId, SYNC_MESSAGES_PENDING, accountId, eventId, SYNC_MESSAGES_PENDING_TTL_SECONDS);
+    if (!acquired)
+        return;
+    if (previous && previous.ttl < Math.floor(Date.now() / 1000)) {
+        metrics.imapFailure("SYNC_PENDING_EXPIRED", "other", 1);
+    }
+    await send().catch(async (error) => {
+        await mailboxLock.releaseLock(accountId, mailboxId, SYNC_MESSAGES_PENDING, eventId);
+        throw error;
+    });
+};
+export const emitFrom = (ctx) => createEmitEvent({
+    queues: ctx.queues,
+    mailboxLock: ctx.client.mailboxLock,
+    metrics: ctx.metrics,
+});

package/dist/events.d.ts

@@ -0,0 +1,203 @@
+import type { MUTATION_EVENT_SCHEMA_VERSION, PATHLESS_MUTATION_EVENT_SCHEMA_VERSION } from "@remit/data-ports/mutation-events";
+export interface BaseEvent {
+    accountId: string;
+    eventId: string;
+    timestamp: number;
+}
+export interface SyncMailboxesEvent extends BaseEvent {
+    type: "SYNC_MAILBOXES";
+    /**
+     * Set by POST /sync — the only trigger a person asks for by name. It makes
+     * the fan-out sync every mailbox, skipping the freshness gate that keeps
+     * incidental triggers (config load, OAuth connect, the scheduled tick) from
+     * re-enumerating folders that were just enumerated.
+     */
+    explicitRequest?: boolean;
+}
+export interface SyncMessagesEvent extends BaseEvent {
+    type: "SYNC_MESSAGES";
+    mailboxId: string;
+    fullSync?: boolean;
+}
+/**
+ * A message to body-sync, carrying the UID resolved at envelope-sync time so
+ * the consumer can issue one ranged FETCH without a per-message DDB lookup.
+ */
+export interface SyncMessageBodyTarget {
+    messageId: string;
+    uid: number;
+}
+export interface SyncMessageBodyEvent extends BaseEvent {
+    type: "SYNC_MESSAGE_BODY";
+    mailboxId: string;
+    /**
+     * Message ids to sync. Always present for backward compatibility; the
+     * consumer falls back to this list (looking up each UID) when `messages`
+     * is absent.
+     */
+    messageIds: string[];
+    /**
+     * Preferred shape: messageId+uid pairs. When present, the consumer skips the
+     * per-message UID lookup and fetches the whole batch in one ranged FETCH.
+     * Optional so older in-flight events (ids only) still process.
+     */
+    messages?: SyncMessageBodyTarget[];
+    /**
+     * Set only by the read-miss re-arm cue (`BodySyncQueueService.requestBodySync`,
+     * called when a `/content` read finds `bodyStorageKey` set but the storage
+     * object missing). Tells the consumer to bypass the "already stored" skip
+     * guard and re-fetch + rewrite the body even though the DB row already
+     * carries a `bodyStorageKey` — otherwise stale metadata (key set, object
+     * gone) makes the read-miss retry loop forever, since the bulk skip guard
+     * would keep treating the message as already synced. Optional so older
+     * in-flight events (no force) keep the original skip behavior.
+     */
+    force?: boolean;
+}
+export interface MailboxCreateEvent extends BaseEvent {
+    type: "MAILBOX_CREATE";
+    mailboxId: string;
+    path: string;
+    subscribe?: boolean;
+}
+export interface MailboxRenameEvent extends BaseEvent {
+    type: "MAILBOX_RENAME";
+    mailboxId: string;
+    oldPath: string;
+    newPath: string;
+}
+export interface MailboxDeleteEvent extends BaseEvent {
+    type: "MAILBOX_DELETE";
+    mailboxId: string;
+    path: string;
+}
+export type MailboxManagementEvent = MailboxCreateEvent | MailboxRenameEvent | MailboxDeleteEvent;
+/**
+ * Event for deleting a message (move to trash or permanent delete).
+ */
+interface MessageDeleteEventFields extends BaseEvent {
+    type: "MESSAGE_DELETE";
+    messageId: string;
+    mailboxId: string;
+    uid: number;
+    operation: "move_to_trash" | "permanent_delete";
+    destinationMailboxId?: string;
+}
+export interface MessageDeleteEventV2 extends MessageDeleteEventFields {
+    schemaVersion: typeof MUTATION_EVENT_SCHEMA_VERSION;
+    mailboxPath: string;
+    destinationMailboxPath?: string;
+}
+export interface MessageDeleteEventV3 extends MessageDeleteEventFields {
+    schemaVersion: typeof PATHLESS_MUTATION_EVENT_SCHEMA_VERSION;
+}
+export type MessageDeleteEvent = MessageDeleteEventV2 | MessageDeleteEventV3;
+/**
+ * Event for moving a message to another mailbox.
+ */
+interface MessageMoveEventFields extends BaseEvent {
+    type: "MESSAGE_MOVE";
+    messageId: string;
+    sourceMailboxId: string;
+    destinationMailboxId: string;
+    uid: number;
+}
+export interface MessageMoveEventV1 extends MessageMoveEventFields {
+    schemaVersion?: undefined;
+    sourceMailboxPath: string;
+    destinationMailboxPath: string;
+}
+export interface MessageMoveEventV3 extends MessageMoveEventFields {
+    schemaVersion: typeof PATHLESS_MUTATION_EVENT_SCHEMA_VERSION;
+}
+export type MessageMoveEvent = MessageMoveEventV1 | MessageMoveEventV3;
+/**
+ * Event for emptying the Trash mailbox.
+ */
+interface EmptyTrashEventFields extends BaseEvent {
+    type: "EMPTY_TRASH";
+    trashMailboxId: string;
+    /**
+     * The Trash folder's UIDVALIDITY at the moment the user consented. The
+     * handler compares it against what the SELECT serves: a path reused by a
+     * different folder (rename plus recreate) answers with a different value,
+     * and this is the only comparison the mutating connection cannot race.
+     */
+    trashUidValidity: number;
+}
+export interface EmptyTrashEventV2 extends EmptyTrashEventFields {
+    schemaVersion: typeof MUTATION_EVENT_SCHEMA_VERSION;
+    trashMailboxPath: string;
+}
+export interface EmptyTrashEventV3 extends EmptyTrashEventFields {
+    schemaVersion: typeof PATHLESS_MUTATION_EVENT_SCHEMA_VERSION;
+}
+export type EmptyTrashEvent = EmptyTrashEventV2 | EmptyTrashEventV3;
+/**
+ * Event for copying a message to another mailbox.
+ */
+interface MessageCopyEventFields extends BaseEvent {
+    type: "MESSAGE_COPY";
+    sourceMessageId: string;
+    newMessageId: string;
+    sourceMailboxId: string;
+    destinationMailboxId: string;
+    uid: number;
+}
+export interface MessageCopyEventV1 extends MessageCopyEventFields {
+    schemaVersion?: undefined;
+    sourceMailboxPath: string;
+    destinationMailboxPath: string;
+}
+export interface MessageCopyEventV3 extends MessageCopyEventFields {
+    schemaVersion: typeof PATHLESS_MUTATION_EVENT_SCHEMA_VERSION;
+}
+export type MessageCopyEvent = MessageCopyEventV1 | MessageCopyEventV3;
+/**
+ * Event for appending a sent message to the Sent mailbox via IMAP APPEND.
+ */
+export interface AppendSentMessageEvent extends BaseEvent {
+    type: "APPEND_SENT_MESSAGE";
+    outboxMessageId: string;
+}
+/**
+ * Drains one pending placement-move marker (issue #1271, epic #1281) to
+ * IMAP. Deliberately carries no UID and no destination — both are resolved
+ * fresh from the Message row and the `MessagePlacementMove` marker at push
+ * time (epic invariant 1), so this event stays valid across any amount of
+ * queue delay or an unrelated UIDVALIDITY rebuild (#1272). If the marker is
+ * gone by the time this is processed (confirmed, superseded, or an external
+ * delete already reconciled it), the handler is a no-op.
+ */
+export interface PlacementMovePushEvent extends BaseEvent {
+    type: "PLACEMENT_MOVE_PUSH";
+    accountConfigId: string;
+    messageId: string;
+}
+/**
+ * Wake-up hint for one pending flag-push marker (issue #1273, epic #1281).
+ * Carries only our message id + the flag field — never a UID and never the
+ * desired add/remove transition (both live on the `MessageFlagPush` marker,
+ * resolved fresh at push time, epic invariant 1). Produced two ways: by
+ * `FlagPushService` (remit-mailbox-service) right after a user's flag flip
+ * commits locally, and by the periodic per-mailbox sync tick
+ * (`sync-messages.ts`) re-arming any marker it finds still stuck `pending`
+ * (a prior enqueue that never landed). If the marker is gone or has moved
+ * past `pending` by the time this is processed, the handler is a no-op.
+ */
+export interface FlagPushEvent extends BaseEvent {
+    type: "FLAG_PUSH";
+    accountConfigId: string;
+    messageId: string;
+    flagName: string;
+}
+export interface DeleteAccountObjectsEvent {
+    type: "DELETE_ACCOUNT_OBJECTS";
+    accountConfigId: string;
+    continuationToken?: string;
+}
+/** Union of all event types the worker can process (including non-IMAP ones). */
+export type WorkerEvent = ImapEvent | DeleteAccountObjectsEvent;
+export type MessageManagementEvent = MessageDeleteEvent | MessageMoveEvent | EmptyTrashEvent | MessageCopyEvent;
+export type ImapEvent = SyncMailboxesEvent | SyncMessagesEvent | SyncMessageBodyEvent | MailboxManagementEvent | MessageManagementEvent | AppendSentMessageEvent | PlacementMovePushEvent | FlagPushEvent;
+export {};

package/dist/events.js

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

package/dist/failure-kind.d.ts

@@ -0,0 +1,10 @@
+import type { ImapFailureKind } from "./context.js";
+/**
+ * Which class of failure ended an IMAP operation, for the exported failure
+ * counter (standalone-observability D3). `auth` is its own kind because it is
+ * the one class that never resolves itself — an expired OAuth grant or a
+ * changed password fails identically forever, and it is the most common way a
+ * self-hosted mailbox goes quiet. A refresh that cannot mint a token is the
+ * same condition arriving one layer earlier.
+ */
+export declare const imapFailureKind: (error: unknown) => ImapFailureKind;

package/{src/failure-kind.ts → dist/failure-kind.js}

@@ -1,7 +1,5 @@
-import type { MailFailureKind } from "@remit/logger-lambda/metrics";
 import { RefreshTokenError } from "@remit/mail-oauth-service";
 import { MailConnectionError } from "@remit/mailbox-service";
-
 /**
  * Which class of failure ended an IMAP operation, for the exported failure
  * counter (standalone-observability D3). `auth` is its own kind because it is
@@ -10,8 +8,10 @@ import { MailConnectionError } from "@remit/mailbox-service";
  * self-hosted mailbox goes quiet. A refresh that cannot mint a token is the
  * same condition arriving one layer earlier.
  */
-export const imapFailureKind = (error: unknown): MailFailureKind => {
-	if (error instanceof RefreshTokenError) return "auth";
-	if (error instanceof MailConnectionError) return error.kind;
-	return "other";
+export const imapFailureKind = (error) => {
+    if (error instanceof RefreshTokenError)
+        return "auth";
+    if (error instanceof MailConnectionError)
+        return error.kind;
+    return "other";
 };

package/dist/handlers/append-sent-message.d.ts

@@ -0,0 +1,3 @@
+import type { ProcessContext } from "../context.js";
+import type { AppendSentMessageEvent } from "../events.js";
+export declare const handleAppendSentMessage: (event: AppendSentMessageEvent, ctx: ProcessContext, receiveCount: number) => Promise<void>;

package/dist/handlers/append-sent-message.js

@@ -0,0 +1,152 @@
+import { APPENDED_UID_NONE, APPENDED_UID_UNREPORTED, isSentCopyFiled, } from "@remit/data-ports";
+import { isNotFoundError } from "@remit/data-ports/errors";
+import { OutboxMessageStatus } from "@remit/domain-enums";
+import { OutboxAttachmentUnavailableError } from "@remit/mailbox-service/outbox-attachment-content";
+import { buildMailMessage, renderRawMessage, } from "@remit/smtp-service/message-builder";
+import { isAccountDeleted } from "../account-check.js";
+import { withOAuthLifecycle } from "../with-oauth-lifecycle.js";
+import { buildLifecycleDeps } from "../with-oauth-lifecycle-deps.js";
+const UNFILED_NO_SENT_MAILBOX = "Sent, but not filed: this account has no folder appointed to the Sent role and none that a Sent folder could be recognised by. Appoint one in the account's folder settings and later messages will be filed there.";
+const UNFILED_SIGNED_OUT = "Sent, but not filed: this account has to be signed in again before a copy can be stored in Sent.";
+const ROW_SURVIVED_ITS_DELETE = "Sent message was filed but its outbox row survived its delete and stays hidden until the boot-time repair";
+const unfiledAppendRefused = (fullPath, error) => error instanceof OutboxAttachmentUnavailableError
+    ? `Sent, but not filed: the copy for ${fullPath} could not be built because ${error.message}.`
+    : `Sent, but not filed: the mail server refused to store a copy in ${fullPath} (${error instanceof Error ? error.message : String(error)}).`;
+export const handleAppendSentMessage = async (event, ctx, receiveCount) => {
+    const { log, pool, config } = ctx;
+    const { account: accountService, outboxMessage: outboxMessageService, outboxAttachment: outboxAttachmentService, mailboxSpecialUse: mailboxSpecialUseService, secrets, } = ctx.client;
+    const { accountId, outboxMessageId } = event;
+    log.info({ event: event.type, accountId, outboxMessageId }, "Handling event");
+    const account = await accountService.get(accountId);
+    if (isAccountDeleted(account, log)) {
+        return;
+    }
+    // A row this event names can be gone by the time the event is redelivered:
+    // its own last attempt deleted it, or the boot repair dropped it on the
+    // strength of a recorded uid. Either way the work is done, and re-throwing
+    // the same NotFoundError on every redelivery only dead-letters it.
+    const outbox = await outboxMessageService
+        .get(account.accountConfigId, outboxMessageId)
+        .catch((error) => {
+        if (isNotFoundError(error))
+            return null;
+        throw error;
+    });
+    if (!outbox) {
+        log.warn({ accountId, outboxMessageId }, "Skipping APPEND_SENT_MESSAGE: the outbox row is already gone");
+        return;
+    }
+    if (outbox.status !== OutboxMessageStatus.sent) {
+        log.info({ outboxMessageId, status: outbox.status }, "Outbox message not in sent status, skipping APPEND");
+        return;
+    }
+    // The message left over SMTP; only the filing can still fail. Settling the
+    // row as `unfiled` keeps it in the Outbox list rather than deleting it, so a
+    // delivered message stays readable somewhere. Every path out of this handler
+    // that is not a confirmed APPEND ends here.
+    const settleUnfiled = async (reason) => {
+        log.error({ accountId, outboxMessageId, reason }, "Sent message could not be filed, settling the outbox row as unfiled");
+        await outboxMessageService.update(account.accountConfigId, outboxMessageId, {
+            status: OutboxMessageStatus.unfiled,
+            lastError: reason,
+        });
+    };
+    // The copy is in Sent, so the row is a leftover and deleting it is all that
+    // is left to do. Both steps are idempotent against a row that is already
+    // gone, so nothing here needs to know how far the last attempt got.
+    //
+    // Files first, row second, the same order outbox-queue.ts discards a draft
+    // in. Nothing but this row points at those objects: a row that outlives its
+    // files is hidden and the boot repair drops it, while files that outlive
+    // their row name a message nothing can reach and are vouched for forever.
+    const dropOutboxRow = async () => {
+        await outboxAttachmentService.discardAll(account.accountConfigId, accountId, outboxMessageId);
+        await outboxMessageService.delete(account.accountConfigId, outboxMessageId);
+        log.info({ outboxMessageId }, "Deleted outbox row after successful APPEND to Sent");
+    };
+    // Everything this recovers from happened after the copy reached Sent, so
+    // re-appending is off the table and the delete is the only step left to
+    // retry. Below the redrive budget that retry is worth having; at it the
+    // record would dead-letter, so the row is left at `sent` for the repair.
+    const retryDropWithinBudget = (error) => {
+        if (receiveCount < config.attempts.appendSent)
+            throw error;
+        log.error({ accountId, outboxMessageId, error }, ROW_SURVIVED_ITS_DELETE);
+    };
+    // A redelivery of an event whose APPEND already landed. The copy is in the
+    // user's Sent folder and the only step still owed is the delete that failed
+    // last time; starting from the top would file a second copy of a message the
+    // user sent once (#858). Ahead of the Sent-mailbox lookup on purpose — a
+    // message that is already filed does not need one, and an account that lost
+    // its Sent appointment in between must not settle as unfiled.
+    if (isSentCopyFiled(outbox)) {
+        log.info({ outboxMessageId, appendedUid: outbox.appendedUid }, "Sent copy was already filed by an earlier attempt, skipping the APPEND");
+        await dropOutboxRow().catch(retryDropWithinBudget);
+        return;
+    }
+    const sentMailbox = await mailboxSpecialUseService.findSentMailbox(accountId);
+    if (!sentMailbox) {
+        await settleUnfiled(UNFILED_NO_SENT_MAILBOX);
+        return;
+    }
+    let appendedUid = APPENDED_UID_NONE;
+    const failure = await withOAuthLifecycle(buildLifecycleDeps(secrets, accountService, ctx.oauth), account, log, async (credentials) => {
+        // Inside the retried unit: a file that cannot be read is retried below
+        // the budget and settles `unfiled` at it, rather than dead-lettering a
+        // delivered message out of every view.
+        const attachments = await outboxAttachmentService.contentsFor(account.accountConfigId, accountId, outboxMessageId);
+        const scope = pool.borrow(account, credentials);
+        await scope
+            .getConnection()
+            .then(async (connection) => {
+            const rawMessage = await renderRawMessage(buildMailMessage(outbox, attachments));
+            const result = await connection.append(sentMailbox.fullPath, rawMessage, ["\\Seen"]);
+            log.info({
+                outboxMessageId,
+                sentMailbox: sentMailbox.fullPath,
+                uid: result.uid,
+                uidValidity: result.uidValidity,
+            }, "Appended sent message to Sent mailbox");
+            // A server without UIDPLUS files the copy and names no uid for
+            // it, which is still a filed copy and has to read as one.
+            appendedUid = result.uid > 0 ? result.uid : APPENDED_UID_UNREPORTED;
+        })
+            .finally(() => scope.release());
+        // The idempotency key, and the only reason a redelivery is safe. It is
+        // written before the delete and never after it: from here on every step
+        // can fail and be retried without the user gaining a second copy, and
+        // the one window that still can is this single row update.
+        await outboxMessageService.update(account.accountConfigId, outboxMessageId, { appendedUid });
+        // The message now lives in the IMAP Sent folder. Drop the outbox row so
+        // the user does not see it twice in the UI (Outbox + Sent). Issue #178.
+        await dropOutboxRow();
+    }).then(() => null, (error) => {
+        // Below the redrive budget this is an ordinary retry — connections
+        // drop, servers go away, and the row is still `sent` for the next
+        // attempt to pick up. At the budget the record would dead-letter, and a
+        // dead-lettered APPEND is exactly how a delivered message goes missing.
+        //
+        // The budget still binds after a landed APPEND, though no longer to
+        // hold off a duplicate: the recorded uid does that, and the retries
+        // the budget allows re-drive the delete alone.
+        if (receiveCount < config.attempts.appendSent)
+            throw error;
+        return error;
+    });
+    // The APPEND landed: the copy is in Sent whatever failed after it, so there
+    // is nothing to settle as unfiled. A row that outlives its delete holds
+    // `sent`, which every view hides, until the migrator's boot-time stranded-row
+    // repair drops it — the next container start, not sooner (#824).
+    if (isSentCopyFiled({ appendedUid })) {
+        if (failure) {
+            log.error({ accountId, outboxMessageId, reason: String(failure) }, ROW_SURVIVED_ITS_DELETE);
+        }
+        return;
+    }
+    // A terminal auth failure returns here without throwing — withOAuthLifecycle
+    // flips the account to reauth_required and ACKs the record, which without
+    // this would leave the row at `sent` and the message nowhere.
+    await settleUnfiled(failure
+        ? unfiledAppendRefused(sentMailbox.fullPath, failure)
+        : UNFILED_SIGNED_OUT);
+};