@remit/mailbox-service 0.0.1

package/src/imapflow-connection.e2e.test.ts

@@ -0,0 +1,355 @@
+import assert from "node:assert";
+import { after, before, describe, test } from "node:test";
+import {
+	seedMailbox,
+	uniqueMailboxName,
+} from "./test-helpers/isolated-mailbox.js";
+import {
+	createMailfuzzConnection,
+	withMailfuzzConnection,
+} from "./test-helpers/mailfuzz-connection.js";
+
+describe(
+	"Mailbox listing (Dovecot)",
+	{
+		skip: !process.env.RUN_E2E_TESTS,
+	},
+	() => {
+		test("lists mailboxes and INBOX exists", async () => {
+			await withMailfuzzConnection(async (connection) => {
+				const mailboxes = await connection.listMailboxes();
+
+				assert.ok(mailboxes.length > 0, "Should have at least one mailbox");
+
+				const inbox = mailboxes.find((m) => m.fullPath === "INBOX");
+				assert.ok(inbox, "INBOX should exist in mailbox list");
+				assert.equal(inbox.name, "INBOX");
+			});
+		});
+
+		test("returns mailbox status with uidValidity and uidNext", async () => {
+			await withMailfuzzConnection(async (connection) => {
+				const status = await connection.getMailboxStatus("INBOX");
+
+				assert.ok(status.uidValidity > 0, "uidValidity should be positive");
+				assert.ok(status.uidNext > 0, "uidNext should be positive");
+				assert.ok(status.messages > 0, "INBOX should have messages");
+			});
+		});
+	},
+);
+
+describe(
+	"Message fetch (Dovecot)",
+	{
+		skip: !process.env.RUN_E2E_TESTS,
+	},
+	() => {
+		test("fetches messages with ENVELOPE data", async () => {
+			await withMailfuzzConnection(async (connection) => {
+				const boxStatus = await connection.openBox("INBOX", true);
+				assert.ok(boxStatus.messages.total > 0, "INBOX should have messages");
+
+				const uids = await connection.search(["ALL"]);
+				assert.ok(uids.length > 0, "Should find messages");
+
+				const fetchUids = uids.slice(0, 5);
+				const messages = await connection.fetchMessages(fetchUids);
+
+				assert.equal(
+					messages.length,
+					fetchUids.length,
+					"Should fetch all requested messages",
+				);
+
+				for (const msg of messages) {
+					assert.ok(msg.uid > 0, "Message should have a UID");
+					assert.ok(msg.envelope, "Message should have envelope data");
+					assert.ok(msg.envelope.subject, "Envelope should have a subject");
+					assert.ok(msg.envelope.messageId, "Envelope should have a messageId");
+					assert.ok(msg.envelope.date, "Envelope should have a date");
+					assert.ok(
+						msg.envelope.from.length > 0,
+						"Envelope should have from addresses",
+					);
+					assert.ok(
+						msg.envelope.to.length > 0,
+						"Envelope should have to addresses",
+					);
+
+					for (const addr of msg.envelope.from) {
+						assert.ok(addr.mailbox, "From address should have mailbox");
+						assert.ok(addr.host, "From address should have host");
+					}
+				}
+			});
+		});
+
+		test("fetched message count matches status", async () => {
+			// Seed a mailbox this test owns so the SELECT-vs-SEARCH invariant holds
+			// regardless of what other e2e files do in parallel — the TOCTOU race
+			// that #501 papered over with --test-concurrency=1 is removed by
+			// isolation, not serialisation (#508).
+			const mailbox = uniqueMailboxName("E2E_count");
+			await withMailfuzzConnection(async (connection) => {
+				await seedMailbox(connection, mailbox, 3);
+				try {
+					const boxStatus = await connection.openBox(mailbox, true);
+					const uids = await connection.search(["ALL"]);
+
+					assert.equal(
+						uids.length,
+						boxStatus.messages.total,
+						"Search ALL count should match SELECT messages count",
+					);
+				} finally {
+					await connection.closeBox().catch(() => {});
+					await connection.deleteMailbox(mailbox).catch(() => {});
+				}
+			});
+		});
+	},
+);
+
+describe(
+	"Message bodies (Dovecot)",
+	{
+		skip: !process.env.RUN_E2E_TESTS,
+	},
+	() => {
+		test("fetches message body with text content", async () => {
+			await withMailfuzzConnection(async (connection) => {
+				await connection.openBox("INBOX", true);
+				const uids = await connection.search(["ALL"]);
+				assert.ok(uids.length > 0, "Should have messages to fetch body for");
+
+				const body = await connection.fetchMessageBody(uids[0]);
+				assert.ok(body.length > 0, "Body should not be empty");
+
+				const bodyText = body.toString("utf-8");
+				assert.ok(bodyText.length > 0, "Body text should not be empty");
+			});
+		});
+	},
+);
+
+describe(
+	"Flag operations (Dovecot)",
+	{
+		skip: !process.env.RUN_E2E_TESTS,
+		// These three subtests all mutate uids[0] of the same seeded mailbox, so
+		// they must run sequentially relative to each other. node:test already
+		// serialises subtests within a describe; concurrency: 1 pins that intent.
+		// Cross-file isolation (a dedicated seeded mailbox, not the shared INBOX)
+		// is what makes the whole suite safe to run in parallel — see #508.
+		concurrency: 1,
+	},
+	() => {
+		let targetUid: number;
+		const mailbox = uniqueMailboxName("E2E_flags");
+
+		before(async () => {
+			await withMailfuzzConnection(async (connection) => {
+				await seedMailbox(connection, mailbox, 3);
+			});
+		});
+
+		after(async () => {
+			const connection = createMailfuzzConnection();
+			await connection.connect();
+			await connection.deleteMailbox(mailbox).catch(() => {});
+			if (connection.isConnected) {
+				await connection.disconnect();
+			}
+		});
+
+		test("sets \\Seen flag and verifies it persists", async () => {
+			await withMailfuzzConnection(async (connection) => {
+				await connection.openBox(mailbox, false);
+				const uids = await connection.search(["ALL"]);
+				assert.ok(uids.length > 0, "Should have messages");
+				targetUid = uids[0];
+
+				await connection.removeFlags([targetUid], ["\\Seen"]);
+				await connection.addFlags([targetUid], ["\\Seen"]);
+
+				const messages = await connection.fetchMessages([targetUid]);
+				assert.equal(messages.length, 1);
+				assert.ok(
+					messages[0].flags.includes("\\Seen"),
+					"Message should have \\Seen flag",
+				);
+			});
+		});
+
+		test("clears \\Seen flag and verifies it is cleared", async () => {
+			await withMailfuzzConnection(async (connection) => {
+				await connection.openBox(mailbox, false);
+				const uids = await connection.search(["ALL"]);
+				targetUid = uids[0];
+
+				await connection.addFlags([targetUid], ["\\Seen"]);
+				await connection.removeFlags([targetUid], ["\\Seen"]);
+
+				const messages = await connection.fetchMessages([targetUid]);
+				assert.equal(messages.length, 1);
+				assert.ok(
+					!messages[0].flags.includes("\\Seen"),
+					"Message should not have \\Seen flag after removal",
+				);
+			});
+		});
+
+		test("sets custom keyword flag", async () => {
+			await withMailfuzzConnection(async (connection) => {
+				await connection.openBox(mailbox, false);
+				const uids = await connection.search(["ALL"]);
+				targetUid = uids[0];
+
+				await connection.addFlags([targetUid], ["$label1"]);
+
+				const messages = await connection.fetchMessages([targetUid]);
+				assert.equal(messages.length, 1);
+				assert.ok(
+					messages[0].flags.includes("$label1"),
+					"Message should have custom keyword $label1",
+				);
+
+				await connection.removeFlags([targetUid], ["$label1"]);
+			});
+		});
+	},
+);
+
+describe(
+	"Message operations (Dovecot)",
+	{
+		skip: !process.env.RUN_E2E_TESTS,
+	},
+	() => {
+		const testFolder = uniqueMailboxName("E2E_TestCopy");
+		// Copy/move source their messages from a mailbox this file owns rather than
+		// the shared INBOX, so nothing here appends to or mutates INBOX (#508).
+		const sourceFolder = uniqueMailboxName("E2E_TestSource");
+
+		before(async () => {
+			await withMailfuzzConnection(async (connection) => {
+				await seedMailbox(connection, sourceFolder, 3);
+			});
+		});
+
+		test("copy returns COPYUID response with uidMap entries", async () => {
+			await withMailfuzzConnection(async (connection) => {
+				await connection.createMailbox(testFolder);
+
+				await connection.openBox(sourceFolder, false);
+				const uids = await connection.search(["ALL"]);
+				assert.ok(uids.length > 0, "Should have messages to copy");
+
+				const result = await connection.copyMessages([uids[0]], testFolder);
+
+				assert.equal(result.destination, testFolder);
+				assert.ok(
+					result.uidMap.size > 0,
+					"COPYUID response should have uidMap entries",
+				);
+				assert.ok(
+					result.uidMap.has(uids[0]),
+					"uidMap should contain the source UID",
+				);
+			});
+		});
+
+		test("move returns COPYUID response with uidMap entries", async () => {
+			const moveFolder = uniqueMailboxName("E2E_TestMove");
+
+			await withMailfuzzConnection(async (connection) => {
+				await connection.createMailbox(moveFolder);
+
+				const appendResult = await connection.append(
+					sourceFolder,
+					[
+						"From: test@example.com",
+						"To: vmail@localhost",
+						"Subject: Move test message",
+						`Date: ${new Date().toUTCString()}`,
+						`Message-ID: <move-test-${Date.now()}@test.example.com>`,
+						"",
+						"Body for move test",
+					].join("\r\n"),
+				);
+
+				await connection.openBox(sourceFolder, false);
+				const result = await connection.moveMessages(
+					[appendResult.uid],
+					moveFolder,
+				);
+
+				assert.equal(result.destination, moveFolder);
+				assert.ok(
+					result.uidMap.size > 0,
+					"COPYUID response should have uidMap entries",
+				);
+
+				await connection.closeBox();
+				await connection.deleteMailbox(moveFolder);
+			});
+		});
+
+		after(async () => {
+			const connection = createMailfuzzConnection();
+			await connection.connect();
+			await connection.deleteMailbox(testFolder).catch(() => {});
+			await connection.deleteMailbox(sourceFolder).catch(() => {});
+			if (connection.isConnected) {
+				await connection.disconnect();
+			}
+		});
+	},
+);
+
+describe("Mailbox CRUD (Dovecot)", { skip: !process.env.RUN_E2E_TESTS }, () => {
+	const crudFolder = `CrudTest_${Date.now()}`;
+	const renamedFolder = `CrudRenamed_${Date.now()}`;
+
+	test("creates a new mailbox", async () => {
+		await withMailfuzzConnection(async (connection) => {
+			const result = await connection.createMailbox(crudFolder);
+			assert.ok(result.created, "Mailbox should be created");
+
+			const mailboxes = await connection.listMailboxes();
+			const found = mailboxes.find((m) => m.fullPath === crudFolder);
+			assert.ok(found, `Mailbox ${crudFolder} should exist after creation`);
+		});
+	});
+
+	test("renames a mailbox", async () => {
+		await withMailfuzzConnection(async (connection) => {
+			const result = await connection.renameMailbox(crudFolder, renamedFolder);
+			assert.ok(result.newPath, "Should return new path");
+
+			const mailboxes = await connection.listMailboxes();
+			const oldFound = mailboxes.find((m) => m.fullPath === crudFolder);
+			assert.ok(
+				!oldFound,
+				`Old mailbox ${crudFolder} should not exist after rename`,
+			);
+
+			const newFound = mailboxes.find((m) => m.fullPath === renamedFolder);
+			assert.ok(newFound, `Renamed mailbox ${renamedFolder} should exist`);
+		});
+	});
+
+	test("deletes a mailbox", async () => {
+		await withMailfuzzConnection(async (connection) => {
+			await connection.deleteMailbox(renamedFolder);
+
+			const mailboxes = await connection.listMailboxes();
+			const found = mailboxes.find((m) => m.fullPath === renamedFolder);
+			assert.ok(
+				!found,
+				`Mailbox ${renamedFolder} should not exist after deletion`,
+			);
+		});
+	});
+});

package/src/imapflow-connection.integ.test.ts

@@ -0,0 +1,327 @@
+/**
+ * Integration tests for ImapFlowConnection using mokapi.
+ *
+ * These tests require mokapi to be running:
+ *   npm run start:mokapi
+ *
+ * Run with:
+ *   npm run test:integ -w packages/mailbox-service
+ *
+ * Note: mokapi has some limitations:
+ * - Doesn't return COPYUID responses (uidMap is empty)
+ * - Doesn't return ENVELOPE data
+ * - Closes connection after APPEND
+ * - Requires mailbox close/reopen to see changes
+ */
+
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import { ImapFlowConnection } from "./imapflow-connection.js";
+
+const MOKAPI_CONFIG = {
+	host: "localhost",
+	port: 143,
+	user: "alice@mokapi.io",
+	credentials: { kind: "password" as const, password: "alice123" },
+	tls: false,
+};
+
+/**
+ * Helper to create a connection.
+ */
+const createConnection = (): ImapFlowConnection => {
+	return new ImapFlowConnection(MOKAPI_CONFIG);
+};
+
+/**
+ * Helper to run a test with a managed connection.
+ * Creates a connection, runs the test, and ensures cleanup.
+ */
+const withConnection = async (
+	fn: (connection: ImapFlowConnection) => Promise<void>,
+): Promise<void> => {
+	const connection = createConnection();
+	await connection.connect();
+	await fn(connection).finally(() => {
+		if (connection.isConnected) {
+			return connection.disconnect();
+		}
+	});
+};
+
+/**
+ * Helper to append a test message to a mailbox and find its UID.
+ * Works around mokapi closing connection after APPEND by using
+ * a separate connection for seeding.
+ *
+ * @returns The UID of the appended message
+ */
+const seedTestMessage = async (
+	mailbox: string,
+	subject: string,
+): Promise<number> => {
+	const seedConn = createConnection();
+	await seedConn.connect();
+
+	const message = [
+		"From: test@example.com",
+		"To: alice@mokapi.io",
+		`Subject: ${subject}`,
+		`Date: ${new Date().toUTCString()}`,
+		`Message-ID: <${Date.now()}-${Math.random()}@test.example.com>`,
+		"",
+		`Test message body for ${subject}`,
+	].join("\r\n");
+
+	// Append the message (connection may close after this in mokapi)
+	await seedConn.append(mailbox, message);
+
+	// mokapi closes connection after APPEND, so reconnect to find the UID
+	const findConn = createConnection();
+	await findConn.connect();
+	await findConn.openBox(mailbox, true);
+	const uids = await findConn.search(["ALL"]);
+
+	// Find the message by fetching headers (mokapi doesn't support ENVELOPE)
+	// biome-ignore lint/suspicious/noExplicitAny: Accessing private client for test purposes
+	const client = (findConn as any).client;
+	let foundUid: number | undefined;
+
+	for await (const msg of client.fetch(
+		uids.slice(-10).join(","),
+		{ uid: true, headers: ["subject"] },
+		{ uid: true },
+	)) {
+		const headerText = msg.headers?.toString() || "";
+		const subjectMatch = headerText.match(/^subject:\s*(.+)$/im);
+		if (subjectMatch && subjectMatch[1].trim() === subject) {
+			foundUid = msg.uid;
+			break;
+		}
+	}
+
+	await findConn.disconnect();
+
+	if (!foundUid) {
+		throw new Error(`Could not find seeded message with subject: ${subject}`);
+	}
+
+	return foundUid;
+};
+
+/**
+ * Helper to count messages in a mailbox using a fresh connection.
+ * This works around mokapi's caching by using a new connection.
+ */
+const countMessagesInMailbox = async (mailbox: string): Promise<number> => {
+	const conn = createConnection();
+	await conn.connect();
+	await conn.openBox(mailbox, true);
+	const uids = await conn.search(["ALL"]);
+	await conn.disconnect();
+	return uids.length;
+};
+
+/**
+ * Helper to get all UIDs in a mailbox using a fresh connection.
+ */
+const getMailboxUids = async (mailbox: string): Promise<number[]> => {
+	const conn = createConnection();
+	await conn.connect();
+	await conn.openBox(mailbox, true);
+	const uids = await conn.search(["ALL"]);
+	await conn.disconnect();
+	return uids;
+};
+
+describe(
+	"ImapFlowConnection integration tests",
+	{
+		skip: !process.env.RUN_INTEG_TESTS,
+	},
+	() => {
+		describe("moveMessages", () => {
+			test("moves a message to another mailbox", async () => {
+				// Seed the test message first
+				const subject = `Move test ${Date.now()}`;
+				const uid = await seedTestMessage("INBOX", subject);
+
+				// Count messages in Work before
+				const workCountBefore = await countMessagesInMailbox("Work");
+
+				await withConnection(async (connection) => {
+					// Open INBOX
+					await connection.openBox("INBOX", false);
+
+					// Move to Work folder
+					const result = await connection.moveMessages([uid], "Work");
+
+					// mokapi doesn't return uidMap, but should return destination
+					assert.equal(
+						result.destination,
+						"Work",
+						"Destination should be Work",
+					);
+				});
+
+				// Verify message moved using fresh connections (mokapi caching workaround)
+				const inboxUids = await getMailboxUids("INBOX");
+				assert.ok(
+					!inboxUids.includes(uid),
+					"Original UID should not be in INBOX",
+				);
+
+				const workCountAfter = await countMessagesInMailbox("Work");
+				assert.ok(
+					workCountAfter > workCountBefore,
+					`Work folder should have more messages (before: ${workCountBefore}, after: ${workCountAfter})`,
+				);
+			});
+
+			test("returns empty uidMap when no UIDs provided", async () => {
+				await withConnection(async (connection) => {
+					await connection.openBox("INBOX", false);
+
+					const result = await connection.moveMessages([], "Work");
+
+					assert.equal(result.destination, "Work");
+					assert.equal(result.uidMap.size, 0);
+				});
+			});
+		});
+
+		describe("copyMessages", () => {
+			test("copies a message to another mailbox", async () => {
+				// Seed the test message first
+				const subject = `Copy test ${Date.now()}`;
+				const uid = await seedTestMessage("INBOX", subject);
+
+				// Count messages in Archive before
+				const archiveCountBefore = await countMessagesInMailbox("Archive");
+
+				await withConnection(async (connection) => {
+					// Open INBOX
+					await connection.openBox("INBOX", false);
+
+					// Copy to Archive folder
+					const result = await connection.copyMessages([uid], "Archive");
+
+					assert.equal(
+						result.destination,
+						"Archive",
+						"Destination should be Archive",
+					);
+				});
+
+				// Verify original message is still in INBOX
+				const inboxUids = await getMailboxUids("INBOX");
+				assert.ok(
+					inboxUids.includes(uid),
+					"Original UID should still be in INBOX",
+				);
+
+				// Verify copy is in Archive (count increased)
+				const archiveCountAfter = await countMessagesInMailbox("Archive");
+				assert.ok(
+					archiveCountAfter > archiveCountBefore,
+					`Archive folder should have more messages (before: ${archiveCountBefore}, after: ${archiveCountAfter})`,
+				);
+
+				// Cleanup: delete the original from INBOX
+				await withConnection(async (connection) => {
+					await connection.openBox("INBOX", false);
+					await connection.deleteMessages([uid]);
+				});
+			});
+
+			test("returns empty uidMap when no UIDs provided", async () => {
+				await withConnection(async (connection) => {
+					await connection.openBox("INBOX", false);
+
+					const result = await connection.copyMessages([], "Archive");
+
+					assert.equal(result.destination, "Archive");
+					assert.equal(result.uidMap.size, 0);
+				});
+			});
+		});
+
+		describe("deleteMessages", () => {
+			test("permanently deletes a message", async () => {
+				// Seed the test message first
+				const subject = `Delete test ${Date.now()}`;
+				const uid = await seedTestMessage("INBOX", subject);
+
+				// Verify message exists
+				let uids = await getMailboxUids("INBOX");
+				assert.ok(uids.includes(uid), "Message should exist before delete");
+
+				await withConnection(async (connection) => {
+					// Open INBOX
+					await connection.openBox("INBOX", false);
+
+					// Delete the message
+					const deleted = await connection.deleteMessages([uid]);
+					// mokapi may return true instead of count
+					assert.ok(deleted, "Should report message deleted");
+
+					// mokapi requires mailbox close for delete to persist
+					await connection.closeBox();
+
+					// Verify within same connection
+					await connection.openBox("INBOX", true);
+					uids = await connection.search(["ALL"]);
+					assert.ok(
+						!uids.includes(uid),
+						"Message should not exist after delete",
+					);
+				});
+			});
+
+			test("returns 0 when no UIDs provided", async () => {
+				await withConnection(async (connection) => {
+					await connection.openBox("INBOX", false);
+
+					const deleted = await connection.deleteMessages([]);
+					assert.equal(deleted, 0);
+				});
+			});
+		});
+
+		describe("move to Trash workflow", () => {
+			test("moves message to Trash folder", async () => {
+				// Seed the test message first
+				const subject = `Trash test ${Date.now()}`;
+				const uid = await seedTestMessage("INBOX", subject);
+
+				// Count messages in Trash before
+				const trashCountBefore = await countMessagesInMailbox("Trash");
+
+				await withConnection(async (connection) => {
+					// Open INBOX
+					await connection.openBox("INBOX", false);
+
+					// Move to Trash
+					const result = await connection.moveMessages([uid], "Trash");
+
+					assert.equal(
+						result.destination,
+						"Trash",
+						"Destination should be Trash",
+					);
+				});
+
+				// Verify message is no longer in INBOX
+				const inboxUids = await getMailboxUids("INBOX");
+				assert.ok(!inboxUids.includes(uid), "Message should not be in INBOX");
+
+				// Verify message is in Trash (count increased)
+				const trashCountAfter = await countMessagesInMailbox("Trash");
+				assert.ok(
+					trashCountAfter > trashCountBefore,
+					`Trash folder should have more messages (before: ${trashCountBefore}, after: ${trashCountAfter})`,
+				);
+			});
+		});
+	},
+);