@remit/mailbox-service 0.0.9 → 0.0.11

package/package.json

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

package/src/imapflow-connection.test.ts

@@ -181,3 +181,88 @@ describe("ImapFlowConnection.getMailboxStatus — deletedCount (#1042)", () => {
 		assert.strictEqual(BigInt(status.highestModseq), modseq);
 	});
 });
+
+describe("ImapFlowConnection CONDSTORE (reader#20)", () => {
+	const buildCondstoreConnection = (options: {
+		enabled: Set<string>;
+		noModseq?: boolean;
+		fetched?: Array<Record<string, unknown>>;
+		record?: Array<{ range: string; options: Record<string, unknown> }>;
+	}): ImapFlowConnection => {
+		const connection = buildConnectionWithClient({
+			enabled: options.enabled,
+			mailbox: { ...fakeMailbox("INBOX", 1), noModseq: options.noModseq },
+			mailboxOpen: async (path: string) => fakeMailbox(path, 1),
+			fetch: (
+				range: string,
+				_query: Record<string, unknown>,
+				fetchOptions: Record<string, unknown>,
+			) => {
+				options.record?.push({ range, options: fetchOptions });
+				return (async function* () {
+					for (const row of options.fetched ?? []) yield row;
+				})();
+			},
+		});
+		Object.assign(connection as unknown as Record<string, unknown>, {
+			currentMailbox: "INBOX",
+		});
+		return connection;
+	};
+
+	it("reports CONDSTORE only when the session enabled it and the mailbox keeps mod-sequences", () => {
+		assert.strictEqual(
+			buildCondstoreConnection({
+				enabled: new Set(["CONDSTORE"]),
+			}).supportsCondstore(),
+			true,
+		);
+		assert.strictEqual(
+			buildCondstoreConnection({ enabled: new Set() }).supportsCondstore(),
+			false,
+		);
+		assert.strictEqual(
+			buildCondstoreConnection({
+				enabled: new Set(["CONDSTORE"]),
+				noModseq: true,
+			}).supportsCondstore(),
+			false,
+		);
+	});
+
+	it("refuses CHANGEDSINCE without CONDSTORE rather than fetching the whole mailbox", async () => {
+		const connection = buildCondstoreConnection({ enabled: new Set() });
+
+		await assert.rejects(
+			() => connection.fetchMessagesChangedSince(500n),
+			/CONDSTORE/,
+		);
+	});
+
+	it("passes the mod-sequence through as a BigInt over the whole UID space", async () => {
+		const record: Array<{ range: string; options: Record<string, unknown> }> =
+			[];
+		const connection = buildCondstoreConnection({
+			enabled: new Set(["CONDSTORE"]),
+			record,
+			fetched: [
+				{
+					uid: 7,
+					seq: 7,
+					flags: new Set(["\\Seen"]),
+					internalDate: new Date(0),
+					size: 10,
+					modseq: 18446744073709551615n,
+				},
+			],
+		});
+
+		const messages = await connection.fetchMessagesChangedSince(500n);
+
+		assert.deepStrictEqual(record, [
+			{ range: "1:*", options: { uid: true, changedSince: 500n } },
+		]);
+		assert.strictEqual(messages[0].modseq, "18446744073709551615");
+		assert.deepStrictEqual(messages[0].flags, ["\\Seen"]);
+	});
+});

package/src/imapflow-connection.ts

@@ -502,6 +502,61 @@ export class ImapFlowConnection {
 	 */
 	fetchMessages = async (uids: number[]): Promise<ImapMessage[]> => {
 		this.ensureConnected();
+
+		if (uids.length === 0) {
+			return [];
+		}
+
+		return this.runMessageFetch(uids.join(","), {});
+	};
+
+	/**
+	 * True when this session negotiated CONDSTORE (RFC 7162) and the open
+	 * mailbox keeps persistent mod-sequences.
+	 *
+	 * Both halves matter. `enabled` reflects the ENABLE exchange, not merely
+	 * the advertised capability, and a server may still answer NOMODSEQ for an
+	 * individual mailbox — in which case RFC 7162 Section 3.1.2.2 requires it
+	 * to reject CHANGEDSINCE with a BAD response.
+	 */
+	supportsCondstore = (): boolean => {
+		const { client } = this;
+		if (!client?.mailbox) return false;
+		return client.enabled.has("CONDSTORE") && !client.mailbox.noModseq;
+	};
+
+	/**
+	 * FETCH everything in the open mailbox whose MODSEQ is strictly greater
+	 * than `sinceModseq` — new arrivals and metadata changes to messages
+	 * already synced, in one pass over the whole UID space.
+	 *
+	 * The CONDSTORE guard is load-bearing rather than defensive: imapflow drops
+	 * the CHANGEDSINCE modifier when the extension is unavailable, so the same
+	 * call would degrade into a fetch of every message in the mailbox.
+	 */
+	fetchMessagesChangedSince = async (
+		sinceModseq: bigint,
+	): Promise<ImapMessage[]> => {
+		this.ensureConnected();
+
+		if (!this.supportsCondstore()) {
+			throw new Error(
+				"CHANGEDSINCE requires CONDSTORE on both the session and the open mailbox",
+			);
+		}
+
+		return this.runMessageFetch("1:*", { changedSince: sinceModseq });
+	};
+
+	/**
+	 * One UID FETCH over `range`, mapped to {@link ImapMessage}. The shared
+	 * body of {@link fetchMessages} and {@link fetchMessagesChangedSince} —
+	 * both need identical message shapes and differ only in what they select.
+	 */
+	private runMessageFetch = async (
+		range: string,
+		options: { changedSince?: bigint },
+	): Promise<ImapMessage[]> => {
 		const { client } = this;
 
 		if (!client) {
@@ -512,17 +567,10 @@ export class ImapFlowConnection {
 			throw new Error("No mailbox selected");
 		}
 
-		if (uids.length === 0) {
-			return [];
-		}
-
 		const messages: ImapMessage[] = [];
 
-		// ImapFlow fetch with native envelope support + References header
-		const uidRange = uids.join(",");
-
 		const fetchIterator = client.fetch(
-			uidRange,
+			range,
 			{
 				uid: true,
 				flags: true,
@@ -532,14 +580,12 @@ export class ImapFlowConnection {
 				size: true,
 				headers: ["references"],
 			},
-			{ uid: true },
+			{ uid: true, ...options },
 		);
 
 		// Connection may have been lost - fetch returns an async iterable
 		if (!fetchIterator) {
-			throw new Error(
-				`IMAP connection lost while fetching messages: ${uidRange}`,
-			);
+			throw new Error(`IMAP connection lost while fetching messages: ${range}`);
 		}
 
 		for await (const msg of fetchIterator) {
@@ -572,6 +618,7 @@ export class ImapFlowConnection {
 				envelope: this.convertEnvelope(msg.envelope),
 				references,
 				bodyStructure: msg.bodyStructure,
+				...(msg.modseq != null ? { modseq: msg.modseq.toString() } : {}),
 			});
 		}
 

package/src/mailbox-sync.test.ts

@@ -44,7 +44,10 @@ describe("MailboxSyncService.syncMailboxes — UIDVALIDITY cursor detection (#12
 		shared: [],
 	};
 
-	const buildConnection = (uidValidity: number): IImapConnection =>
+	const buildConnection = (
+		uidValidity: number,
+		highestModseq = "0",
+	): IImapConnection =>
 		({
 			getNamespaces: async () => namespaces,
 			listMailboxes: async () => [
@@ -62,7 +65,7 @@ describe("MailboxSyncService.syncMailboxes — UIDVALIDITY cursor detection (#12
 				unseen: 1,
 				uidNext: 100,
 				uidValidity,
-				highestModseq: "0",
+				highestModseq,
 				deletedCount: 0,
 			}),
 		}) as unknown as IImapConnection;
@@ -136,6 +139,32 @@ describe("MailboxSyncService.syncMailboxes — UIDVALIDITY cursor detection (#12
 		assert.equal(updateCalls.length, 0);
 	});
 
+	it("never writes the message-sync cursor, whatever the server reports", async () => {
+		// `highestModseq` on the mailbox row is message sync's own cursor over
+		// applied changes, not a status projection. The sweep overwriting it with
+		// the server's current value would step it over every change message sync
+		// had not yet applied.
+		const { mailboxService, specialUseService, updateCalls } = buildServices(1);
+		const service = new MailboxSyncService(mailboxService, specialUseService);
+		const connection = buildConnection(2, "99999");
+
+		await service.syncMailboxes({ accountId: "acc-1" }, connection);
+
+		for (const call of updateCalls) {
+			assert.equal("highestModseq" in call, false);
+		}
+	});
+
+	it("does not sweep-write a mailbox whose only difference is the server mod-sequence", async () => {
+		const { mailboxService, specialUseService, updateCalls } = buildServices(1);
+		const service = new MailboxSyncService(mailboxService, specialUseService);
+		const connection = buildConnection(1, "4242");
+
+		await service.syncMailboxes({ accountId: "acc-1" }, connection);
+
+		assert.equal(updateCalls.length, 0);
+	});
+
 	it("does not re-trip (no cursorState write) when the mailbox is already cursor_invalid", async () => {
 		const { mailboxService, specialUseService, updateCalls } = buildServices(
 			1,

package/src/mailbox-sync.ts

@@ -353,7 +353,13 @@ export class MailboxSyncService {
 			fullPath: mailboxInfo.fullPath,
 			uidValidity: status.uidValidity,
 			uidNext: status.uidNext,
-			highestModseq: status.highestModseq,
+			// The message-sync cursor, not a status projection: it records how
+			// far THIS mailbox's messages have been applied, and nothing has
+			// been. Seeding it from the server's current HIGHESTMODSEQ would
+			// declare an unsynced folder already caught up and skip every
+			// message in it. Message sync seeds it once it has enumerated the
+			// folder.
+			highestModseq: "0",
 			messageCount: status.messages,
 			unseenCount: status.unseen,
 			deletedCount: status.deletedCount,
@@ -429,8 +435,6 @@ export class MailboxSyncService {
 			existing.messageCount !== status.messages ||
 			existing.unseenCount !== status.unseen ||
 			existing.deletedCount !== status.deletedCount ||
-			(BigInt(status.highestModseq) > 0n &&
-				existing.highestModseq !== status.highestModseq) ||
 			specialUseChanged;
 
 		// Sync special-use attributes (handles migration of existing mailboxes)
@@ -458,13 +462,6 @@ export class MailboxSyncService {
 			changes.push(
 				`deletedCount: ${existing.deletedCount} -> ${status.deletedCount}`,
 			);
-		if (
-			BigInt(status.highestModseq) > 0n &&
-			existing.highestModseq !== status.highestModseq
-		)
-			changes.push(
-				`highestModseq: ${existing.highestModseq} -> ${status.highestModseq}`,
-			);
 		if (specialUseChanged)
 			changes.push(
 				`specialUse: [${(existing.specialUse ?? []).join(",")}] -> [${parsed.specialUse.join(",")}]`,
@@ -480,7 +477,10 @@ export class MailboxSyncService {
 			hierarchyDelimiter: mailboxInfo.delimiter,
 			uidValidity: status.uidValidity,
 			uidNext: status.uidNext,
-			highestModseq: status.highestModseq,
+			// `highestModseq` is deliberately absent: it is message sync's
+			// cursor over this mailbox's own applied changes, and overwriting it
+			// with the server's current value here would step it over every
+			// change message sync had not yet applied.
 			messageCount: status.messages,
 			unseenCount: status.unseen,
 			deletedCount: status.deletedCount,

package/src/message-move.ts

@@ -695,10 +695,14 @@ export class MessageMoveService {
 	/**
 	 * Delete every ThreadMessage row that points at this messageId.
 	 *
-	 * A single Message can have multiple ThreadMessage rows — one per mailbox
-	 * the message exists in (e.g. INBOX + a label/folder copy). Deleting them
-	 * up-front in the permanent-delete optimistic step prevents stale rows from
-	 * leaking into mailbox listings while IMAP catches up. See issue #212.
+	 * A row is keyed by (threadId, messageId), so this is one row in practice —
+	 * a message filed in several folders keeps a single row, because its
+	 * messageId is derived from the Message-ID header and not from the mailbox.
+	 * The query stays a list because the key permits more than one thread per
+	 * message and nothing enforces otherwise.
+	 *
+	 * Deleting up-front in the permanent-delete optimistic step prevents stale
+	 * rows from leaking into mailbox listings while IMAP catches up (#212).
 	 */
 	private deleteThreadMessagesForMessage = async (
 		accountConfigId: string,