@remit/mailbox-service 0.0.38 → 0.0.40

package/README.md

@@ -1,11 +1,11 @@
 # @remit/mailbox-service
 
-IMAP mailbox synchronization service for Remit. Provides connection management, mailbox discovery, and message sync with DynamoDB persistence.
+IMAP mailbox synchronization service for Remit. Provides connection management, mailbox discovery, and message sync. Persistence is injected: the service takes repository ports, never a database client.
 
 ## Features
 
 - **ImapFlow-based**: Modern async/await IMAP client with native envelope parsing
-- **Mailbox Sync**: Discovers and syncs mailbox metadata from IMAP to DynamoDB
+- **Mailbox Sync**: Discovers and syncs mailbox metadata from IMAP into the mailbox repository
 - **Message Sync**: Newest-first sync strategy with dual-watermark tracking
 - **Address Extraction**: Parses and stores envelope addresses with role tracking
 
@@ -55,10 +55,11 @@ await connection.disconnect();
 ```typescript
 import { MailboxSyncService } from "@remit/mailbox-service";
 
-const syncService = new MailboxSyncService({
-  client: dynamoDBClient,
-  table: "remit-table",
-});
+const syncService = new MailboxSyncService(
+  mailboxRepository,
+  mailboxSpecialUseRepository,
+  logger,
+);
 
 const result = await syncService.syncMailboxes(
   { accountId: "acc-123" },
@@ -103,7 +104,7 @@ const synced = await messageSyncService.syncMessages(
 
 | Export               | Description                               |
 | -------------------- | ----------------------------------------- |
-| `MailboxSyncService` | Syncs mailbox list from IMAP to DynamoDB  |
+| `MailboxSyncService` | Syncs mailbox list from IMAP into the store |
 | `MessageSyncService` | Syncs messages with newest-first strategy |
 
 ### Types

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/mailbox-service",
-  "version": "0.0.38",
+  "version": "0.0.40",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/body-parse.ts

@@ -9,7 +9,7 @@ type FailureCode = QuarantineItem["failureCode"];
  *
  * This type is the whole reason the sync path can quarantine anything. Before
  * it, every catch site on the body path saw one undifferentiated `unknown`
- * covering mailparser, S3, DynamoDB and SQS alike, so "the message is built in
+ * covering mailparser, S3, the database and SQS alike, so "the message is built in
  * a way Remit could not read" was indistinguishable from "S3 returned a 503".
  * Recording the second as the first advances the cursor past mail that is
  * perfectly fine and never fetches it again.

package/src/mailbox-cursor.ts

@@ -33,8 +33,8 @@ export interface MailboxCursorGuardDeps {
 /**
  * `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
+ * before this migration (the column genuinely NULL) reads back absent
+ * despite the type
  * saying otherwise, so every consumer here treats `undefined` the same as
  * `normal` defensively rather than trusting the type.
  */

package/src/mailbox-management.test.ts

@@ -99,7 +99,7 @@ const boxStatus = (path: string): ImapBoxStatus => ({
 const recordingRepo = () => {
 	const updates: Array<{ mailboxId: string; patch: Record<string, unknown> }> =
 		[];
-	const repo = {
+	const repo: Pick<IMailboxRepository, "update" | "findByPathPrefix"> = {
 		update: async (
 			_accountId: string,
 			mailboxId: string,
@@ -108,8 +108,9 @@ const recordingRepo = () => {
 			updates.push({ mailboxId, patch });
 			return {} as never;
 		},
-	} as unknown as IMailboxRepository;
-	return { repo, updates };
+		findByPathPrefix: async () => [],
+	};
+	return { repo: repo as IMailboxRepository, updates };
 };
 
 const stubConnection = (

package/src/mailbox-management.ts

@@ -1,5 +1,6 @@
 import type { IMailboxRepository } from "@remit/data-ports";
 import { MailboxSyncStatus } from "@remit/domain-enums";
+import { isNotFoundError } from "./mailbox-presence.js";
 import type { IImapConnection } from "./types.js";
 
 /**
@@ -100,7 +101,7 @@ export const validateMailboxOperation = (
  * Service for managing mailbox operations (create, rename, delete).
  *
  * Implements an optimistic local-first pattern:
- * 1. Updates are applied locally first (DynamoDB)
+ * 1. Updates are applied locally first
  * 2. Changes are queued for IMAP sync via SQS
  * 3. Worker processes queue and syncs to IMAP server
  */
@@ -220,9 +221,66 @@ export class MailboxManagementService {
 			syncStatus: MailboxSyncStatus.synced,
 		});
 
+		// The server rename is done and the row records it. The settle is repair
+		// work on top of that, so nothing it hits — the listing included — may reach
+		// the caller's failure path, which rolls the row back to a path the server
+		// no longer has and hands it to the reconcile sweep to reap.
+		await this.settleRenamedSubtree(accountId, newPath, connection).catch(
+			(error: unknown) => {
+				this.log.error(
+					{ mailboxId, newPath, error },
+					"Renamed subtree left pending",
+				);
+			},
+		);
+
 		return { success: true };
 	};
 
+	/**
+	 * IMAP RENAME moves the whole subtree in one command, so the descendants the
+	 * local rename marked pending are on the server the moment the parent's is.
+	 * Nothing else settles them: the reconcile sweep treats pending as in-flight
+	 * and leaves it alone, and a descendant left pending is read as off-server, so
+	 * its sync events are terminally acked and its mail never arrives.
+	 *
+	 * A descendant is settled only where the server's own listing holds its path.
+	 * A local path the server has not materialized is still in flight behind
+	 * another queued operation, and stripping its pending marker would expose the
+	 * row to the reconcile sweep.
+	 */
+	private settleRenamedSubtree = async (
+		accountId: string,
+		newPath: string,
+		connection: IImapConnection,
+	): Promise<void> => {
+		const listed = await connection.listMailboxes();
+		const onServer = new Set(listed.map((mailbox) => mailbox.fullPath));
+		const delimiter =
+			listed.find((mailbox) => mailbox.fullPath === newPath)?.delimiter ??
+			listed[0]?.delimiter ??
+			"/";
+
+		const descendants = await this.mailboxService.findByPathPrefix(
+			accountId,
+			newPath,
+			delimiter,
+		);
+
+		for (const descendant of descendants) {
+			if (descendant.syncStatus !== MailboxSyncStatus.pending) continue;
+			if (!onServer.has(descendant.fullPath)) continue;
+			await this.mailboxService
+				.update(accountId, descendant.mailboxId, {
+					syncStatus: MailboxSyncStatus.synced,
+				})
+				.catch((error: unknown) => {
+					if (isNotFoundError(error)) return;
+					throw error;
+				});
+		}
+	};
+
 	/**
 	 * Sync a DELETE operation to IMAP.
 	 * Called by worker after dequeuing MAILBOX_DELETE event.
@@ -244,7 +302,7 @@ export class MailboxManagementService {
 
 		this.log.info({ mailboxId, path }, "Deleted mailbox on IMAP server");
 
-		// Delete the mailbox entity from DynamoDB
+		// Delete the mailbox entity from the local store
 		await this.mailboxService.delete(accountId, mailboxId);
 
 		return { success: true };

package/src/mailbox-presence.ts

@@ -1,7 +1,7 @@
 import type { IMailboxRepository, MailboxItem } from "@remit/data-ports";
 import { MailboxSyncStatus } from "@remit/domain-enums";
 
-const isNotFoundError = (error: unknown): boolean =>
+export const isNotFoundError = (error: unknown): boolean =>
 	error instanceof Error && error.name === "NotFoundError";
 
 /**

package/src/mailbox-queue.ts

@@ -83,7 +83,7 @@ export interface MailboxQueueConfig {
  * Service for mailbox management with automatic IMAP sync queueing.
  *
  * Implements optimistic local-first pattern:
- * 1. Updates local DynamoDB state immediately
+ * 1. Updates local state immediately
  * 2. Enqueues mailbox management event to SQS for worker to sync to IMAP
  *
  * This follows the same pattern as FlagQueueService (RFC 014).

package/src/mailbox-rename-subtree.test.ts

@@ -0,0 +1,225 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { IMailboxRepository, MailboxItem } from "@remit/data-ports";
+import { MailboxSyncStatus } from "@remit/domain-enums";
+import { MailboxManagementService } from "./mailbox-management.js";
+import type { FlatMailboxInfo, IImapConnection } from "./types.js";
+
+const row = (
+	mailboxId: string,
+	fullPath: string,
+	syncStatus: MailboxItem["syncStatus"],
+): MailboxItem =>
+	({
+		mailboxId,
+		accountId: "acc-1",
+		fullPath,
+		hierarchyDelimiter: "/",
+		syncStatus,
+	}) as MailboxItem;
+
+const store = (rows: MailboxItem[], vanishAfterSweep: string[] = []) => {
+	const byId = new Map(rows.map((r) => [r.mailboxId, { ...r }]));
+
+	const repo: Pick<IMailboxRepository, "update" | "findByPathPrefix"> = {
+		update: async (_accountId, mailboxId, patch) => {
+			const existing = byId.get(mailboxId);
+			if (!existing) {
+				throw Object.assign(new Error(`Mailbox not found: ${mailboxId}`), {
+					name: "NotFoundError",
+				});
+			}
+			const next = { ...existing, ...patch } as MailboxItem;
+			byId.set(mailboxId, next);
+			return next;
+		},
+		findByPathPrefix: async (_accountId, pathPrefix, delimiter = "/") => {
+			const prefix = `${pathPrefix}${delimiter}`;
+			const found = [...byId.values()].filter((r) =>
+				r.fullPath.startsWith(prefix),
+			);
+			for (const mailboxId of vanishAfterSweep) byId.delete(mailboxId);
+			return found;
+		},
+	};
+
+	return {
+		repo: repo as IMailboxRepository,
+		statusOf: (mailboxId: string) => byId.get(mailboxId)?.syncStatus,
+	};
+};
+
+const connectionListing = (paths: string[]): IImapConnection =>
+	({
+		renameMailbox: async () => undefined,
+		listMailboxes: async (): Promise<FlatMailboxInfo[]> =>
+			paths.map((fullPath) => ({
+				fullPath,
+				name: fullPath.split("/").pop() ?? fullPath,
+				delimiter: "/",
+				attributes: [],
+				parentPath: null,
+			})),
+	}) as unknown as IImapConnection;
+
+const connectionWithoutListing = (): IImapConnection =>
+	({
+		renameMailbox: async () => undefined,
+		listMailboxes: async () => {
+			throw new Error("IMAP connection lost");
+		},
+	}) as unknown as IImapConnection;
+
+/**
+ * The local rename writes the new path across the whole subtree and marks every
+ * row pending, so a reconcile in that window cannot reap them (#290). These
+ * fixtures are that state at the moment the worker picks the event up: the
+ * parent and its descendants already carry their new paths.
+ */
+describe("MailboxManagementService.syncRename — subtree settle", () => {
+	it("settles every descendant the rename carried, not just the renamed row", async () => {
+		const { repo, statusOf } = store([
+			row("mbx-parent", "Projects", MailboxSyncStatus.pending),
+			row("mbx-child", "Projects/2026", MailboxSyncStatus.pending),
+			row("mbx-grandchild", "Projects/2026/Q1", MailboxSyncStatus.pending),
+		]);
+		const service = new MailboxManagementService(repo);
+
+		const result = await service.syncRename(
+			"acc-1",
+			"mbx-parent",
+			"Work",
+			"Projects",
+			async () =>
+				connectionListing(["Projects", "Projects/2026", "Projects/2026/Q1"]),
+		);
+
+		assert.equal(result.success, true);
+		assert.equal(statusOf("mbx-parent"), MailboxSyncStatus.synced);
+		assert.equal(statusOf("mbx-child"), MailboxSyncStatus.synced);
+		assert.equal(statusOf("mbx-grandchild"), MailboxSyncStatus.synced);
+	});
+
+	it("leaves a descendant behind a rename of its own pending", async () => {
+		// Two renames in one per-account FIFO group: `Projects` → `Work` moves the
+		// child row to `Work/2026`, then `Work/2026` → `Work/Archive` moves it
+		// again before the first RENAME is worked. When the first one lands the
+		// server holds `Work/2026`; `Work/Archive` exists only locally, and
+		// stripping its pending marker would let the reconcile sweep reap the row
+		// and rebuild it under a fresh mailboxId, dangling every filter bound to
+		// the old one.
+		const { repo, statusOf } = store([
+			row("mbx-parent", "Work", MailboxSyncStatus.pending),
+			row("mbx-child", "Work/Archive", MailboxSyncStatus.pending),
+		]);
+		const service = new MailboxManagementService(repo);
+
+		await service.syncRename(
+			"acc-1",
+			"mbx-parent",
+			"Projects",
+			"Work",
+			async () => connectionListing(["Work", "Work/2026"]),
+		);
+
+		assert.equal(statusOf("mbx-parent"), MailboxSyncStatus.synced);
+		assert.equal(statusOf("mbx-child"), MailboxSyncStatus.pending);
+	});
+
+	it("leaves a descendant the user has asked to delete on its way out", async () => {
+		// A delete requested after the local rename wrote the subtree pending: the
+		// folder is still on the server, and settling it would undo the request.
+		const { repo, statusOf } = store([
+			row("mbx-parent", "Projects", MailboxSyncStatus.pending),
+			row("mbx-deleting", "Projects/Old", MailboxSyncStatus.deleting),
+			row("mbx-child", "Projects/2026", MailboxSyncStatus.pending),
+		]);
+		const service = new MailboxManagementService(repo);
+
+		await service.syncRename(
+			"acc-1",
+			"mbx-parent",
+			"Work",
+			"Projects",
+			async () =>
+				connectionListing(["Projects", "Projects/Old", "Projects/2026"]),
+		);
+
+		assert.equal(statusOf("mbx-deleting"), MailboxSyncStatus.deleting);
+		assert.equal(statusOf("mbx-child"), MailboxSyncStatus.synced);
+	});
+
+	it("settles inside the renamed subtree without reaching a lookalike sibling", async () => {
+		const { repo, statusOf } = store([
+			row("mbx-parent", "Projects", MailboxSyncStatus.pending),
+			row("mbx-child", "Projects/2026", MailboxSyncStatus.pending),
+			row("mbx-lookalike", "Projectsy/2026", MailboxSyncStatus.pending),
+		]);
+		const service = new MailboxManagementService(repo);
+
+		await service.syncRename(
+			"acc-1",
+			"mbx-parent",
+			"Work",
+			"Projects",
+			async () =>
+				connectionListing(["Projects", "Projects/2026", "Projectsy/2026"]),
+		);
+
+		assert.equal(statusOf("mbx-child"), MailboxSyncStatus.synced);
+		assert.equal(statusOf("mbx-lookalike"), MailboxSyncStatus.pending);
+	});
+
+	it("reports the rename as done when a descendant row vanishes mid-settle", async () => {
+		// The settle is repair work, not the mutation. A descendant deleted while
+		// it runs has nothing left to settle, and must not roll a completed server
+		// rename back to failed — the handler's catch treats any throw from here
+		// as an IMAP failure and restores the old path.
+		const { repo, statusOf } = store(
+			[
+				row("mbx-parent", "Projects", MailboxSyncStatus.pending),
+				row("mbx-gone", "Projects/Gone", MailboxSyncStatus.pending),
+				row("mbx-child", "Projects/2026", MailboxSyncStatus.pending),
+			],
+			["mbx-gone"],
+		);
+		const service = new MailboxManagementService(repo);
+
+		const result = await service.syncRename(
+			"acc-1",
+			"mbx-parent",
+			"Work",
+			"Projects",
+			async () =>
+				connectionListing(["Projects", "Projects/Gone", "Projects/2026"]),
+		);
+
+		assert.equal(result.success, true);
+		assert.equal(statusOf("mbx-child"), MailboxSyncStatus.synced);
+	});
+
+	it("reports the rename as done when the listing it settles against fails", async () => {
+		// The listing runs after the server rename has landed. Letting it fail the
+		// rename would send the caller down its IMAP-failure path, restoring a path
+		// the server no longer has and marking the row failed — which drops the
+		// pending marker that keeps the reconcile sweep from reaping it. A
+		// descendant left pending is the safe outcome.
+		const { repo, statusOf } = store([
+			row("mbx-parent", "Projects", MailboxSyncStatus.pending),
+			row("mbx-child", "Projects/2026", MailboxSyncStatus.pending),
+		]);
+		const service = new MailboxManagementService(repo);
+
+		const result = await service.syncRename(
+			"acc-1",
+			"mbx-parent",
+			"Work",
+			"Projects",
+			async () => connectionWithoutListing(),
+		);
+
+		assert.equal(result.success, true);
+		assert.equal(statusOf("mbx-parent"), MailboxSyncStatus.synced);
+		assert.equal(statusOf("mbx-child"), MailboxSyncStatus.pending);
+	});
+});

package/src/message-move.ts

@@ -115,7 +115,7 @@ export interface DeleteOptions {
  * Service for moving, copying, and deleting messages.
  *
  * Implements optimistic local-first pattern:
- * 1. Updates local DynamoDB state immediately (Message + ThreadMessage)
+ * 1. Updates local state immediately (Message + ThreadMessage)
  * 2. Enqueues event to SQS for worker to sync to IMAP
  *
  * Following RFC 016 for message deletion and moving.

package/src/mime-walker.ts

@@ -266,8 +266,8 @@ const toRecord = (
  * **Part-path uniqueness**: some IMAP servers (and the `message/rfc822`
  * inner-body convention) return child nodes with an empty `part` field.
  * Assigning ROOT_PART_PATH to every such node would produce duplicate keys
- * and cause a DynamoDB "multiple operations on one item" error in
- * `upsertBodyParts`. Non-root nodes without a `part` therefore receive a
+ * and make `upsertBodyParts` write the same body part twice. Non-root nodes
+ * without a `part` therefore receive a
  * synthetic path `<parentPath>.<siblingIndex>` that is stable across
  * repeated syncs of the same message.
  */
@@ -287,7 +287,7 @@ export const walkMimeStructure = (root: MimeNode): BodyPartRecord[] => {
 			partPath = ROOT_PART_PATH;
 		} else {
 			// Non-root node without an IMAP part path — synthesise one so
-			// the DynamoDB keys remain unique. This happens most commonly
+			// the body-part keys remain unique. This happens most commonly
 			// for the body of a message/rfc822 attachment, whose inner
 			// structure imapflow attaches as a childNode with part="".
 			partPath = `${parentPath}.${siblingIndex}`;

package/src/pass-through-unit-of-work.ts

@@ -2,9 +2,9 @@ import type { IUnitOfWork, UnitOfWorkRepositories } from "@remit/data-ports";
 
 /**
  * Runs the write set against fixed repositories with no surrounding
- * transaction. For backends (DynamoDB) that have no cross-entity transaction:
- * the writes are not atomic, matching that backend's own guarantees. The
- * Postgres path injects a real transactional unit of work instead.
+ * transaction: the writes are not atomic. For a backend that has no
+ * cross-entity transaction this matches its own guarantees; the SQLite path
+ * injects a real transactional unit of work instead.
  */
 export class PassThroughUnitOfWork implements IUnitOfWork {
 	constructor(private repos: UnitOfWorkRepositories) {}