@remit/mailbox-service 0.0.1

package/src/mailbox-cursor.test.ts

@@ -0,0 +1,249 @@
+import assert from "node:assert/strict";
+import { describe, it, mock } from "node:test";
+import type { IMailboxRepository, MailboxItem } from "@remit/data-ports";
+import { MailboxCursorState } from "@remit/domain-enums";
+import {
+	guardConnectionCursor,
+	guardMailboxCursor,
+	isCursorRebuildNeeded,
+	MailboxCursorPausedError,
+} from "./mailbox-cursor.js";
+import type { IImapConnection, ImapBoxStatus } from "./types.js";
+
+const mailboxId = "mbx-1";
+const accountId = "acc-1";
+
+const baseMailbox: Pick<MailboxItem, "mailboxId" | "uidValidity"> & {
+	cursorState: MailboxItem["cursorState"] | undefined;
+} = {
+	mailboxId,
+	uidValidity: 100,
+	// A pre-migration row genuinely lacks this attribute at runtime despite the
+	// type saying it's total — see mailbox-cursor.ts for why `undefined` is
+	// accepted here.
+	cursorState: undefined,
+};
+
+describe("guardMailboxCursor", () => {
+	it("is ok and writes nothing when the served UIDVALIDITY matches the stored value", async () => {
+		const update = mock.fn(async () => ({}) as MailboxItem);
+		const mailboxService = {
+			update,
+		} as unknown as Pick<IMailboxRepository, "update">;
+
+		const result = await guardMailboxCursor(
+			{ mailboxService },
+			accountId,
+			baseMailbox,
+			100,
+		);
+
+		assert.deepEqual(result, { ok: true });
+		assert.equal(update.mock.calls.length, 0);
+	});
+
+	it("treats an absent cursorState as normal", async () => {
+		const update = mock.fn(async () => ({}) as MailboxItem);
+		const mailboxService = { update } as unknown as Pick<
+			IMailboxRepository,
+			"update"
+		>;
+
+		const result = await guardMailboxCursor(
+			{ mailboxService },
+			accountId,
+			{ ...baseMailbox, cursorState: undefined },
+			100,
+		);
+
+		assert.deepEqual(result, { ok: true });
+	});
+
+	it("trips cursor_invalid and persists it when the served UIDVALIDITY disagrees", async () => {
+		const update = mock.fn(async () => ({}) as MailboxItem);
+		const mailboxService = { update } as unknown as Pick<
+			IMailboxRepository,
+			"update"
+		>;
+
+		const result = await guardMailboxCursor(
+			{ mailboxService },
+			accountId,
+			{ ...baseMailbox, uidValidity: 100 },
+			200,
+		);
+
+		assert.deepEqual(result, { ok: false, state: "cursor_invalid" });
+		assert.equal(update.mock.calls.length, 1);
+		assert.deepEqual(update.mock.calls[0].arguments, [
+			accountId,
+			mailboxId,
+			{ cursorState: MailboxCursorState.cursor_invalid },
+		]);
+	});
+
+	it("short-circuits without a write when already cursor_invalid, even if UIDVALIDITY now matches", async () => {
+		const update = mock.fn(async () => ({}) as MailboxItem);
+		const mailboxService = { update } as unknown as Pick<
+			IMailboxRepository,
+			"update"
+		>;
+
+		const result = await guardMailboxCursor(
+			{ mailboxService },
+			accountId,
+			{ ...baseMailbox, cursorState: MailboxCursorState.cursor_invalid },
+			100,
+		);
+
+		assert.deepEqual(result, { ok: false, state: "cursor_invalid" });
+		assert.equal(
+			update.mock.calls.length,
+			0,
+			"paused mailboxes must not be re-tripped on every call (frugal — invariant 6)",
+		);
+	});
+
+	it("short-circuits without a write when rebuilding", async () => {
+		const update = mock.fn(async () => ({}) as MailboxItem);
+		const mailboxService = { update } as unknown as Pick<
+			IMailboxRepository,
+			"update"
+		>;
+
+		const result = await guardMailboxCursor(
+			{ mailboxService },
+			accountId,
+			{ ...baseMailbox, cursorState: MailboxCursorState.rebuilding },
+			999,
+		);
+
+		assert.deepEqual(result, { ok: false, state: "rebuilding" });
+		assert.equal(update.mock.calls.length, 0);
+	});
+});
+
+describe("guardConnectionCursor", () => {
+	const fakeBoxStatus = (uidvalidity: number): ImapBoxStatus =>
+		({
+			uidvalidity,
+		}) as unknown as ImapBoxStatus;
+
+	it("delegates to the real openBox and returns normally when normal and matching", async () => {
+		const openBox = mock.fn(async () => fakeBoxStatus(100));
+		const connection = { openBox } as unknown as IImapConnection;
+		const update = mock.fn(async () => ({}) as MailboxItem);
+		const mailboxService = { update } as unknown as Pick<
+			IMailboxRepository,
+			"update"
+		>;
+
+		const guarded = guardConnectionCursor(
+			connection,
+			{ mailboxService },
+			accountId,
+			{ ...baseMailbox, uidValidity: 100 },
+		);
+
+		const result = await guarded.openBox("INBOX", false);
+
+		assert.deepEqual(result, fakeBoxStatus(100));
+		assert.equal(openBox.mock.calls.length, 1);
+		assert.equal(update.mock.calls.length, 0);
+	});
+
+	it("throws MailboxCursorPausedError and never calls the real openBox when already paused", async () => {
+		const openBox = mock.fn(async () => fakeBoxStatus(100));
+		const connection = { openBox } as unknown as IImapConnection;
+		const mailboxService = {
+			update: mock.fn(async () => ({}) as MailboxItem),
+		} as unknown as Pick<IMailboxRepository, "update">;
+
+		const guarded = guardConnectionCursor(
+			connection,
+			{ mailboxService },
+			accountId,
+			{ ...baseMailbox, cursorState: MailboxCursorState.cursor_invalid },
+		);
+
+		await assert.rejects(
+			() => guarded.openBox("INBOX"),
+			(err: unknown) =>
+				err instanceof MailboxCursorPausedError &&
+				err.state === "cursor_invalid",
+		);
+		assert.equal(
+			openBox.mock.calls.length,
+			0,
+			"a mailbox already known paused must not touch the network (frugal — invariant 6)",
+		);
+	});
+
+	it("trips and throws MailboxCursorPausedError when the served UIDVALIDITY disagrees", async () => {
+		const openBox = mock.fn(async () => fakeBoxStatus(200));
+		const connection = { openBox } as unknown as IImapConnection;
+		const update = mock.fn(async () => ({}) as MailboxItem);
+		const mailboxService = { update } as unknown as Pick<
+			IMailboxRepository,
+			"update"
+		>;
+
+		const guarded = guardConnectionCursor(
+			connection,
+			{ mailboxService },
+			accountId,
+			{ ...baseMailbox, uidValidity: 100 },
+		);
+
+		await assert.rejects(
+			() => guarded.openBox("INBOX"),
+			(err: unknown) =>
+				err instanceof MailboxCursorPausedError &&
+				err.state === "cursor_invalid",
+		);
+		assert.equal(
+			openBox.mock.calls.length,
+			1,
+			"the real openBox must run once to learn the served UIDVALIDITY",
+		);
+		assert.equal(
+			update.mock.calls.length,
+			1,
+			"the mismatch must trip the mailbox",
+		);
+	});
+
+	it("passes other methods through untouched (e.g. fetchMessages)", async () => {
+		const fetchMessages = mock.fn(async () => []);
+		const connection = {
+			openBox: async () => fakeBoxStatus(100),
+			fetchMessages,
+		} as unknown as IImapConnection;
+
+		const guarded = guardConnectionCursor(
+			connection,
+			{ mailboxService: { update: async () => ({}) as MailboxItem } },
+			accountId,
+			{ ...baseMailbox, uidValidity: 100 },
+		);
+
+		await guarded.fetchMessages([1, 2, 3]);
+		assert.equal(fetchMessages.mock.calls.length, 1);
+		assert.deepEqual(fetchMessages.mock.calls[0].arguments, [[1, 2, 3]]);
+	});
+});
+
+describe("isCursorRebuildNeeded", () => {
+	it("is false for undefined and normal", () => {
+		assert.equal(isCursorRebuildNeeded(undefined), false);
+		assert.equal(isCursorRebuildNeeded(MailboxCursorState.normal), false);
+	});
+
+	it("is true for cursor_invalid and rebuilding", () => {
+		assert.equal(
+			isCursorRebuildNeeded(MailboxCursorState.cursor_invalid),
+			true,
+		);
+		assert.equal(isCursorRebuildNeeded(MailboxCursorState.rebuilding), true);
+	});
+});

package/src/mailbox-cursor.ts

@@ -0,0 +1,177 @@
+import type { IMailboxRepository, MailboxItem } from "@remit/data-ports";
+import { MailboxCursorState } from "@remit/domain-enums";
+import type { IImapConnection, ImapBoxStatus } from "./types.js";
+
+/**
+ * Detection + trip for the UIDVALIDITY cursor-integrity state machine (issue
+ * #1272, epic #1281 invariant 5): `normal -> cursor_invalid -> rebuilding ->
+ * normal`.
+ *
+ * A UIDVALIDITY bump invalidates every stored UID on a mailbox's axis
+ * (RFC 9051 Section 2.3.1.1) — `lastSyncUid`, `highWaterMarkUid`, and every
+ * per-message UID become meaningless the instant the server reports a
+ * different value than what is stored. The state machine is persisted (not a
+ * lock) because `MailboxLockService` only serializes one event type at a
+ * time (`(mailboxId, eventName)` is its primary key) — it does not stop a
+ * flag push from racing a sync round on the same mailbox. Every worker path
+ * that SELECTs a mailbox calls {@link guardMailboxCursor} with the served
+ * UIDVALIDITY right after opening the box, before issuing any command that
+ * references a stored UID.
+ */
+export type MailboxCursorCheck =
+	| { ok: true }
+	| {
+			ok: false;
+			/** The state the mailbox is (now) in — always non-`normal` here. */
+			state: "cursor_invalid" | "rebuilding";
+	  };
+
+export interface MailboxCursorGuardDeps {
+	mailboxService: Pick<IMailboxRepository, "update">;
+}
+
+/**
+ * `cursorState` is total per RFC 032 (defaults to `normal`) — but that default
+ * only applies to rows written after this field existed. A row persisted
+ * before this migration (DynamoDB attribute never written / Postgres column
+ * genuinely NULL) reads back with the attribute absent despite the type
+ * saying otherwise, so every consumer here treats `undefined` the same as
+ * `normal` defensively rather than trusting the type.
+ */
+type MailboxCursorStateOrLegacyAbsent = MailboxItem["cursorState"] | undefined;
+
+const isNormal = (state: MailboxCursorStateOrLegacyAbsent): boolean =>
+	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: MailboxCursorGuardDeps,
+	accountId: string,
+	mailbox: Pick<MailboxItem, "mailboxId" | "uidValidity"> & {
+		cursorState: MailboxCursorStateOrLegacyAbsent;
+	},
+	servedUidValidity: number,
+): Promise<MailboxCursorCheck> => {
+	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: MailboxCursorStateOrLegacyAbsent,
+): boolean =>
+	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 {
+	constructor(readonly state: "cursor_invalid" | "rebuilding") {
+		super(`Mailbox cursor is ${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: IImapConnection,
+	deps: MailboxCursorGuardDeps,
+	accountId: string,
+	mailbox: Pick<MailboxItem, "mailboxId" | "uidValidity"> & {
+		cursorState: MailboxCursorStateOrLegacyAbsent;
+	},
+): IImapConnection => {
+	const guardedOpenBox = async (
+		mailboxPath: string,
+		readOnly?: boolean,
+	): Promise<ImapBoxStatus> => {
+		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/src/mailbox-management.test.ts

@@ -0,0 +1,103 @@
+import assert from "node:assert";
+import { describe, it } from "node:test";
+import {
+	parseMailboxPath,
+	validateMailboxOperation,
+	validateMailboxPath,
+} from "./mailbox-management.js";
+
+describe("parseMailboxPath", () => {
+	it("parses simple path", () => {
+		const result = parseMailboxPath("INBOX");
+		assert.strictEqual(result.name, "INBOX");
+		assert.strictEqual(result.parent, null);
+		assert.strictEqual(result.depth, 1);
+	});
+
+	it("parses nested path with default delimiter", () => {
+		const result = parseMailboxPath("Work/Projects/ClientA");
+		assert.strictEqual(result.name, "ClientA");
+		assert.strictEqual(result.parent, "Work/Projects");
+		assert.strictEqual(result.depth, 3);
+	});
+
+	it("parses nested path with custom delimiter", () => {
+		const result = parseMailboxPath("Work.Projects.ClientA", ".");
+		assert.strictEqual(result.name, "ClientA");
+		assert.strictEqual(result.parent, "Work.Projects");
+		assert.strictEqual(result.depth, 3);
+	});
+
+	it("handles two-level path", () => {
+		const result = parseMailboxPath("Personal/Archive");
+		assert.strictEqual(result.name, "Archive");
+		assert.strictEqual(result.parent, "Personal");
+		assert.strictEqual(result.depth, 2);
+	});
+});
+
+describe("validateMailboxPath", () => {
+	it("throws on empty path", () => {
+		assert.throws(() => validateMailboxPath(""), {
+			message: "Mailbox path cannot be empty",
+		});
+	});
+
+	it("throws on whitespace-only path", () => {
+		assert.throws(() => validateMailboxPath("   "), {
+			message: "Mailbox path cannot be empty",
+		});
+	});
+
+	it("throws on double delimiters", () => {
+		assert.throws(() => validateMailboxPath("Work//Projects"), {
+			message: "Mailbox path cannot contain empty hierarchy levels",
+		});
+	});
+
+	it("throws on leading delimiter", () => {
+		assert.throws(() => validateMailboxPath("/Work/Projects"), {
+			message: "Mailbox path cannot start or end with hierarchy delimiter",
+		});
+	});
+
+	it("throws on trailing delimiter", () => {
+		assert.throws(() => validateMailboxPath("Work/Projects/"), {
+			message: "Mailbox path cannot start or end with hierarchy delimiter",
+		});
+	});
+
+	it("accepts valid simple path", () => {
+		assert.doesNotThrow(() => validateMailboxPath("INBOX"));
+	});
+
+	it("accepts valid nested path", () => {
+		assert.doesNotThrow(() => validateMailboxPath("Work/Projects/ClientA"));
+	});
+});
+
+describe("validateMailboxOperation", () => {
+	it("throws when deleting INBOX", () => {
+		assert.throws(() => validateMailboxOperation("delete", "INBOX"), {
+			message: "Cannot delete INBOX",
+		});
+	});
+
+	it("throws when deleting INBOX (case insensitive)", () => {
+		assert.throws(() => validateMailboxOperation("delete", "inbox"), {
+			message: "Cannot delete INBOX",
+		});
+	});
+
+	it("allows deleting other mailboxes", () => {
+		assert.doesNotThrow(() => validateMailboxOperation("delete", "Archive"));
+	});
+
+	it("allows renaming INBOX", () => {
+		assert.doesNotThrow(() => validateMailboxOperation("rename", "INBOX"));
+	});
+
+	it("allows renaming other mailboxes", () => {
+		assert.doesNotThrow(() => validateMailboxOperation("rename", "Archive"));
+	});
+});