@remit/mailbox-service 0.0.112 → 0.0.113

package/dist/mailbox-cursor.js

@@ -0,0 +1,102 @@
+import { MailboxCursorState } from "@remit/domain-enums";
+const isNormal = (state) => state === undefined || state === MailboxCursorState.normal;
+/**
+ * Compare a mailbox's stored UIDVALIDITY against what the server just served
+ * (from an `openBox`/`STATUS` response) and act:
+ *
+ * - Already `cursor_invalid` or `rebuilding` — outbound IMAP is already
+ *   paused for this mailbox; short-circuit without a write (frugal — epic
+ *   #1281 invariant 6) and report why.
+ * - `normal` but the served value disagrees with the stored one — trip the
+ *   mailbox to `cursor_invalid` (the only write this function performs) and
+ *   report the pause. This is the detection edge: whichever worker path
+ *   notices the mismatch first is the one that flips the switch.
+ * - `normal` and the values agree — proceed, nothing to do.
+ *
+ * Callers must treat a `{ ok: false }` result as an expected, routine pause
+ * (epic #1281 invariant 3), not a fault: log/metric and skip the outbound
+ * operation for this round rather than throwing.
+ */
+export const guardMailboxCursor = async (deps, accountId, mailbox, servedUidValidity) => {
+    if (!isNormal(mailbox.cursorState)) {
+        return {
+            ok: false,
+            state: mailbox.cursorState === MailboxCursorState.rebuilding
+                ? "rebuilding"
+                : "cursor_invalid",
+        };
+    }
+    if (mailbox.uidValidity !== servedUidValidity) {
+        await deps.mailboxService.update(accountId, mailbox.mailboxId, {
+            cursorState: MailboxCursorState.cursor_invalid,
+        });
+        return { ok: false, state: "cursor_invalid" };
+    }
+    return { ok: true };
+};
+/** True when a mailbox row is in either non-`normal` cursor state. */
+export const isCursorRebuildNeeded = (cursorState) => cursorState === MailboxCursorState.cursor_invalid ||
+    cursorState === MailboxCursorState.rebuilding;
+/**
+ * Thrown by the `openBox` override on a {@link guardConnectionCursor}-wrapped
+ * connection when the mailbox cursor is (or just became) non-`normal`. Every
+ * caller must treat this as the routine, expected pause described on {@link
+ * guardMailboxCursor} — catch it around the outbound operation and skip
+ * (ack/log/return), never let it surface as an infrastructure fault.
+ */
+export class MailboxCursorPausedError extends Error {
+    state;
+    constructor(state) {
+        super(`Mailbox cursor is ${state}`);
+        this.state = state;
+        this.name = "MailboxCursorPausedError";
+    }
+}
+/**
+ * Wrap a live `IImapConnection` so its `openBox` is the single, structural
+ * choke point for UIDVALIDITY cursor guarding (epic #1281 invariants 3 & 5).
+ *
+ * Every outbound IMAP operation that touches a stored UID requires an
+ * `openBox`/SELECT first — that is an IMAP protocol requirement, not a
+ * convention — so gating there means a caller cannot reach `fetchMessages`,
+ * `addFlags`, `moveMessages`, `fetchMessageBody`, etc. against a paused
+ * mailbox's stale axis without going through the same wrapped `openBox` this
+ * function defines. A handler that forgets to call `guardMailboxCursor`
+ * manually can no longer skip the check by omission; wiring a connection
+ * through here makes that structural instead of per-callsite.
+ *
+ * - Already `cursor_invalid`/`rebuilding` — throws {@link
+ *   MailboxCursorPausedError} immediately, without calling the real
+ *   `openBox` (frugal — invariant 6, no network round-trip for a mailbox
+ *   already known paused).
+ * - `normal` but the served UIDVALIDITY disagrees — trips the mailbox (via
+ *   {@link guardMailboxCursor}) and throws the same error.
+ * - `normal` and it matches — delegates to the real `openBox` and returns
+ *   normally.
+ *
+ * `mailbox` is a snapshot taken once by the caller (they already need it for
+ * `mailboxPath`) — not re-fetched per call, so this adds no extra read.
+ */
+export const guardConnectionCursor = (connection, deps, accountId, mailbox) => {
+    const guardedOpenBox = async (mailboxPath, readOnly) => {
+        if (!isNormal(mailbox.cursorState)) {
+            throw new MailboxCursorPausedError(mailbox.cursorState === MailboxCursorState.rebuilding
+                ? "rebuilding"
+                : "cursor_invalid");
+        }
+        const boxStatus = await connection.openBox(mailboxPath, readOnly);
+        const check = await guardMailboxCursor(deps, accountId, mailbox, boxStatus.uidvalidity);
+        if (!check.ok) {
+            throw new MailboxCursorPausedError(check.state);
+        }
+        return boxStatus;
+    };
+    return new Proxy(connection, {
+        get(target, prop, receiver) {
+            if (prop === "openBox")
+                return guardedOpenBox;
+            const value = Reflect.get(target, prop, receiver);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+};

package/dist/mailbox-intent.d.ts

@@ -0,0 +1,41 @@
+import type { IMailboxRepository, MailboxItem } from "@remit/data-ports";
+/**
+ * The states a rename or a delete intent may be recorded from (T4, T7). Both
+ * failed variants are legal starting points — a retry re-records the same
+ * intent on the same row, so no duplicate folder can be created — and every
+ * other state means a mutation is already in flight on the folder.
+ */
+export declare const INTENT_RECORDABLE_FROM: readonly ["synced", "failed"];
+export declare const carriesIntent: (row: Pick<MailboxItem, "syncStatus">) => boolean;
+/**
+ * Whether a row was written by one particular rename intent
+ * (docs/architecture/folder-rename-and-delete.md D15).
+ *
+ * A recorded target that merely sits at or under the rename's target is not
+ * enough to identify one. Two folders can hold targets under the same path —
+ * `Work → Projects` in flight while `Other → Projects/Old` is recorded — and a
+ * settle that claimed both would stamp a row this rename never touched onto a
+ * path it never asked for, leaving that folder's own rename unrepresented and
+ * two rows claiming one path for the sweep to reap and re-insert.
+ *
+ * The identity is the pair: the row sits at or under the path the rename is
+ * leaving, **and** the target it recorded is exactly what this rename's own
+ * rebase would have written for it. Nothing but this intent writes that pair,
+ * because the intent is recorded over one subtree in one batch (D6) and
+ * the transition is the only writer of either field (D3).
+ */
+export declare const recordedByRename: (row: Pick<MailboxItem, "fullPath" | "pendingPath">, oldPath: string, newPath: string, delimiter: string) => boolean;
+export declare const folderInFlight: (row: MailboxItem) => string;
+/**
+ * Say why a folder intent lost its compare-and-set (D3).
+ *
+ * Existence was established by the read the caller took before recording, so a
+ * lost predicate is a conflict rather than a 404 — but the row can have gone in
+ * between, and one primary-key read tells the two apart. For a subtree intent
+ * the blocker may be a descendant, and the message says so: a subtree cannot be
+ * half-renamed (D6), so a descendant mid-mutation refuses the whole rename and
+ * a user who was not thinking about it has to be told which folder it is.
+ *
+ * Always rejects.
+ */
+export declare const refuseContestedIntent: (mailboxService: Pick<IMailboxRepository, "get" | "findByPathPrefix">, accountId: string, mailboxId: string, scope: "folder" | "subtree") => Promise<never>;

package/{src/mailbox-intent.ts → dist/mailbox-intent.js}

@@ -1,9 +1,7 @@
-import type { IMailboxRepository, MailboxItem } from "@remit/data-ports";
 import { ConflictError, NotFoundError } from "@remit/data-ports/errors";
 import { rebaseMailboxPath } from "@remit/data-ports/mailbox-name";
 import { MailboxSyncStatus } from "@remit/domain-enums";
 import { isNotFoundError } from "./mailbox-presence.js";
-
 /**
  * The states a rename or a delete intent may be recorded from (T4, T7). Both
  * failed variants are legal starting points — a retry re-records the same
@@ -11,13 +9,10 @@ import { isNotFoundError } from "./mailbox-presence.js";
  * other state means a mutation is already in flight on the folder.
  */
 export const INTENT_RECORDABLE_FROM = [
-	MailboxSyncStatus.synced,
-	MailboxSyncStatus.failed,
-] as const;
-
-export const carriesIntent = (row: Pick<MailboxItem, "syncStatus">): boolean =>
-	(INTENT_RECORDABLE_FROM as readonly string[]).includes(row.syncStatus);
-
+    MailboxSyncStatus.synced,
+    MailboxSyncStatus.failed,
+];
+export const carriesIntent = (row) => INTENT_RECORDABLE_FROM.includes(row.syncStatus);
 /**
  * Whether a row was written by one particular rename intent
  * (docs/architecture/folder-rename-and-delete.md D15).
@@ -35,33 +30,24 @@ export const carriesIntent = (row: Pick<MailboxItem, "syncStatus">): boolean =>
  * because the intent is recorded over one subtree in one batch (D6) and
  * the transition is the only writer of either field (D3).
  */
-export const recordedByRename = (
-	row: Pick<MailboxItem, "fullPath" | "pendingPath">,
-	oldPath: string,
-	newPath: string,
-	delimiter: string,
-): boolean =>
-	row.pendingPath !== undefined &&
-	rebaseMailboxPath(row.fullPath, oldPath, newPath, delimiter) ===
-		row.pendingPath;
-
+export const recordedByRename = (row, oldPath, newPath, delimiter) => row.pendingPath !== undefined &&
+    rebaseMailboxPath(row.fullPath, oldPath, newPath, delimiter) ===
+        row.pendingPath;
 /**
  * What is already happening to a folder, as a clause naming the folder. The
  * six states, not the four enum values: `pending` covers a create in flight and
  * a rename in flight, and only `pendingPath` tells them apart.
  */
-const inFlight = (row: MailboxItem): string => {
-	if (row.syncStatus === MailboxSyncStatus.deleting) {
-		return `A delete is already in progress for "${row.fullPath}"`;
-	}
-	if (row.pendingPath !== undefined) {
-		return `A rename is in progress for "${row.fullPath}"`;
-	}
-	return `"${row.fullPath}" is still being created`;
+const inFlight = (row) => {
+    if (row.syncStatus === MailboxSyncStatus.deleting) {
+        return `A delete is already in progress for "${row.fullPath}"`;
+    }
+    if (row.pendingPath !== undefined) {
+        return `A rename is in progress for "${row.fullPath}"`;
+    }
+    return `"${row.fullPath}" is still being created`;
 };
-
-export const folderInFlight = (row: MailboxItem): string => `${inFlight(row)}.`;
-
+export const folderInFlight = (row) => `${inFlight(row)}.`;
 /**
  * Say why a folder intent lost its compare-and-set (D3).
  *
@@ -74,38 +60,26 @@ export const folderInFlight = (row: MailboxItem): string => `${inFlight(row)}.`;
  *
  * Always rejects.
  */
-export const refuseContestedIntent = async (
-	mailboxService: Pick<IMailboxRepository, "get" | "findByPathPrefix">,
-	accountId: string,
-	mailboxId: string,
-	scope: "folder" | "subtree",
-): Promise<never> => {
-	const root = await mailboxService
-		.get(accountId, mailboxId)
-		.catch((error: unknown) => {
-			if (isNotFoundError(error)) return undefined;
-			throw error;
-		});
-	if (!root) throw new NotFoundError(`Mailbox not found: ${mailboxId}`);
-
-	if (!carriesIntent(root)) throw new ConflictError(folderInFlight(root));
-
-	const descendants =
-		scope === "subtree"
-			? await mailboxService.findByPathPrefix(
-					accountId,
-					root.fullPath,
-					root.hierarchyDelimiter,
-				)
-			: [];
-	const blocking = descendants.find((row) => !carriesIntent(row));
-	if (blocking) {
-		throw new ConflictError(`${inFlight(blocking)}, inside this folder.`);
-	}
-
-	// Every row reads recordable now, so the row that blocked has already moved
-	// on. Nothing to name, and the same request succeeds on a retry.
-	throw new ConflictError(
-		`"${root.fullPath}" changed while this request was being recorded. Try again.`,
-	);
+export const refuseContestedIntent = async (mailboxService, accountId, mailboxId, scope) => {
+    const root = await mailboxService
+        .get(accountId, mailboxId)
+        .catch((error) => {
+        if (isNotFoundError(error))
+            return undefined;
+        throw error;
+    });
+    if (!root)
+        throw new NotFoundError(`Mailbox not found: ${mailboxId}`);
+    if (!carriesIntent(root))
+        throw new ConflictError(folderInFlight(root));
+    const descendants = scope === "subtree"
+        ? await mailboxService.findByPathPrefix(accountId, root.fullPath, root.hierarchyDelimiter)
+        : [];
+    const blocking = descendants.find((row) => !carriesIntent(row));
+    if (blocking) {
+        throw new ConflictError(`${inFlight(blocking)}, inside this folder.`);
+    }
+    // Every row reads recordable now, so the row that blocked has already moved
+    // on. Nothing to name, and the same request succeeds on a retry.
+    throw new ConflictError(`"${root.fullPath}" changed while this request was being recorded. Try again.`);
 };

package/dist/mailbox-management.d.ts

@@ -0,0 +1,240 @@
+import type { IMailboxRepository } from "@remit/data-ports";
+import type { IImapConnection } from "./types.js";
+/**
+ * Input for creating a mailbox
+ */
+export interface CreateMailboxInput {
+    accountId: string;
+    path: string;
+    subscribe?: boolean;
+}
+/**
+ * Input for renaming a mailbox
+ */
+export interface RenameMailboxInput {
+    mailboxId: string;
+    newPath: string;
+}
+/**
+ * Input for deleting a mailbox
+ */
+export interface DeleteMailboxInput {
+    mailboxId: string;
+    force?: boolean;
+}
+/**
+ * Result of syncing mailbox operation to IMAP
+ */
+export interface MailboxManagementSyncResult {
+    success: boolean;
+    error?: string;
+    /**
+     * Where the folder ended up, on a rename the server confirmed. Absent when
+     * the recorded intent had already moved on, so no RENAME was issued —
+     * which is how a caller tells the two apart without a second read.
+     */
+    renamed?: {
+        oldPath: string;
+        newPath: string;
+        delimiter: string;
+    };
+    existing?: {
+        mailboxId: string;
+        fullPath: string;
+    };
+}
+/**
+ * Logger interface for MailboxManagementService
+ */
+export interface MailboxManagementLogger {
+    info(obj: Record<string, unknown>, msg: string): void;
+    error(obj: Record<string, unknown>, msg: string): void;
+}
+/**
+ * Parse a mailbox path to extract name and parent path
+ */
+export declare const parseMailboxPath: (path: string, delimiter?: string) => {
+    name: string;
+    parent: string | null;
+    depth: number;
+};
+/**
+ * Validate mailbox path for invalid characters and operations
+ */
+export declare const validateMailboxPath: (path: string) => void;
+/**
+ * Validate that an operation can be performed on a mailbox path
+ */
+export declare const validateMailboxOperation: (operation: "delete" | "rename", path: string) => void;
+/**
+ * Service for managing mailbox operations (create, rename, delete).
+ *
+ * Implements an optimistic local-first pattern:
+ * 1. Updates are applied locally first
+ * 2. Changes are queued for IMAP sync via SQS
+ * 3. Worker processes queue and syncs to IMAP server
+ */
+export declare class MailboxManagementService {
+    private mailboxService;
+    private log;
+    constructor(mailboxService: IMailboxRepository, logger?: MailboxManagementLogger);
+    /**
+     * Settle a create: `pending` with **no** recorded rename target, which is the
+     * state a create in flight is (D3, D10).
+     *
+     * The absence check is what the whole `wherePendingPath` predicate exists
+     * for. A create whose acknowledgement was lost, redelivered against a row a
+     * rename has since claimed, passes a `pending`-only guard; the CREATE
+     * collides, ImapFlow reports the collision as `{created: false}` rather than
+     * an error, and this write then strands the row `synced` with a rename
+     * target on it — the seventh combination — leaving the rename's own settle
+     * with nothing to match and the RENAME never running.
+     *
+     * A null means the row is gone or the intent moved on. The handlers'
+     * #289-class terminal guards classify the NotFoundError as the user having
+     * deleted the folder mid-sync.
+     */
+    private settleCreate;
+    /**
+     * The rows one rename intent recorded, each with the path it settles to.
+     *
+     * The settle deliberately does not re-resolve the subtree (D15): membership
+     * changes between the intent and the settle — the sweep inserts a row,
+     * another client deletes a descendant — and an all-or-nothing settle then
+     * either throws, poisoning the account's FIFO group (#339), or resolves
+     * leaving every row `pending` forever with no route out, because `failed` is
+     * only reachable from a settle that ran.
+     *
+     * So the rows identify themselves, by the pair `recordedByRename` tests: a
+     * target at or under the rename's target is not on its own enough, because a
+     * second folder renamed under the same branch would be claimed by a rename
+     * that never touched it. A row that appeared afterwards carries no such pair
+     * and is not touched.
+     *
+     * `confirmedPath` re-prefixes each recorded target off the path the rename
+     * actually resolved to, so a normalization the requested string did not carry
+     * moves the whole branch rather than the folder alone.
+     *
+     * `delimiter` is the renamed folder's own, read from the row the caller
+     * already holds — deriving one from whatever the listing happens to contain
+     * strands every descendant when that row has gone.
+     */
+    private intentCarryingRows;
+    /**
+     * Sync a CREATE operation to IMAP.
+     * Called by worker after dequeuing MAILBOX_CREATE event.
+     *
+     * @param accountId - Account that owns the mailbox (tenant scope)
+     * @param mailboxId - ID of the mailbox to create
+     * @param path - Path of the mailbox to create
+     * @param getConnection - Factory to get IMAP connection
+     * @param subscribe - Whether to subscribe after creation
+     */
+    syncCreate: (accountId: string, mailboxId: string, path: string, getConnection: () => Promise<IImapConnection>, subscribe?: boolean) => Promise<MailboxManagementSyncResult>;
+    /**
+     * Sync a RENAME operation to IMAP and settle the rows that recorded it (T5).
+     * Called by worker after dequeuing MAILBOX_RENAME event.
+     *
+     * Guarded on the intent, not on the event (D10): the row must still be
+     * `pending` with this event's target recorded, or the rename resolves with no
+     * IMAP call at all. That is what stops a redelivered MAILBOX_RENAME re-issuing
+     * a RENAME from a path that has already moved.
+     *
+     * @param accountId - Account that owns the mailbox (tenant scope)
+     * @param mailboxId - ID of the mailbox to rename
+     * @param oldPath - Path the intent was recorded against
+     * @param newPath - Target the intent recorded
+     * @param getConnection - Factory to get IMAP connection
+     */
+    syncRename: (accountId: string, mailboxId: string, oldPath: string, newPath: string, getConnection: () => Promise<IImapConnection>) => Promise<MailboxManagementSyncResult>;
+    /**
+     * Issue the RENAME and read back the path it resolved to.
+     *
+     * A `NONEXISTENT` here has three readings, and only one of them may destroy
+     * anything. Either another client deleted the folder; or this rename already
+     * landed and only its settle was lost, in which case the folder is alive at
+     * the target; or the server is saying something this code cannot classify.
+     * The listing separates the first two, and everything it cannot answer is a
+     * refused rename (T6) — a rename that failed costs the user a retry, while
+     * reading an unclear answer as a delete costs them the folder's mail.
+     *
+     * So the caller is told which of the two it is by the *kind* of error, never
+     * by re-reading the server's code: only `FolderGoneUpstreamError` removes a
+     * folder, and it is raised exactly where the listing held neither path.
+     */
+    private issueRename;
+    /**
+     * Whether the rename this event was enqueued for is still the folder's live
+     * intent. `pending` alone cannot answer it — that state covers a create in
+     * flight too — so the recorded target is half the predicate, and it is the
+     * same predicate the settling write carries, so the guard and the write
+     * cannot disagree between the read and the write.
+     */
+    private renameIntentStanding;
+    /**
+     * T5, per row (D15): each intent-carrying row adopts its own confirmed path,
+     * drops the recorded target and settles `synced`, on its own conditional
+     * write. A row another client moved in between fails its predicate and is
+     * skipped rather than overwritten; a row that is gone is skipped for free.
+     *
+     * **The named folder is written last, and that ordering is load-bearing.**
+     * The redelivery's guard reads that row and nothing else, so it is the
+     * witness for the whole settle: while it still carries the intent, a
+     * redelivery re-enters and finishes whatever the last attempt left. Settling
+     * it first would ack a run that died part-way through its descendants, and
+     * those rows would stay `pending` forever — invisible to message sync, and
+     * with no route out, because an intent may only be recorded from `synced` or
+     * `failed`, so neither a retry nor a dismissal can reach them.
+     */
+    private settleRenameIntent;
+    /**
+     * T6: the rename did not land, so every row that recorded it goes to
+     * `failed`, keeping its target so the client can name what the rename was
+     * aiming at and offer a retry. Nothing is restored — `fullPath` was never
+     * written, which is the whole point of recording the target instead (D2).
+     */
+    failRename: (accountId: string, mailboxId: string, oldPath: string, newPath: string, reason: string) => Promise<void>;
+    /**
+     * The folder the rename was to move was found gone from the server, and
+     * the target was not there either, so it was deleted by another client
+     * mid-rename (D8). Every row that recorded this rename's intent — the
+     * root and each descendant — goes with its mail, the same walk `failRename`
+     * uses: deleting the root alone strands every descendant `pending` with
+     * nothing left to revisit it, which is the orphaning bug this closes.
+     */
+    abandonRenameSubtree: (accountId: string, mailboxId: string, oldPath: string, newPath: string) => Promise<void>;
+    /**
+     * Sync a DELETE operation to IMAP.
+     * Called by worker after dequeuing MAILBOX_DELETE event.
+     *
+     * @param accountId - Account that owns the mailbox (tenant scope)
+     * @param mailboxId - ID of the mailbox to delete
+     * @param path - Path of the mailbox to delete
+     * @param getConnection - Factory to get IMAP connection
+     */
+    syncDelete: (accountId: string, mailboxId: string, path: string, getConnection: () => Promise<IImapConnection>) => Promise<MailboxManagementSyncResult>;
+    /**
+     * Whether the delete this event was enqueued for is still the folder's live
+     * intent (D10). Anything else resolves the job with no IMAP call — never a
+     * throw, which would hold back every later job in the account's FIFO group
+     * (#339).
+     */
+    private deleteIntentStanding;
+    /**
+     * T8: the confirmed delete takes the folder's local mail with it (D8).
+     * Removing the row alone leaves every `message` and `thread_message` row
+     * keyed to a dead mailboxId — out of every reader.
+     *
+     * The removal is batched and the mailbox row goes last, so the row stays
+     * `deleting` throughout and an SQS redelivery re-enters the handler, passes
+     * the guard above, and resumes where it stopped.
+     */
+    settleDelete: (accountId: string, mailboxId: string) => Promise<void>;
+    /**
+     * T9: the server refused the delete. Nothing is unwound — DELETE is
+     * all-or-nothing, so `fullPath` is still what the server holds, and no rename
+     * target is written, which is how the client tells a failed delete from a
+     * failed rename.
+     */
+    failDelete: (accountId: string, mailboxId: string, reason: string) => Promise<void>;
+}