@remit/mailbox-service 0.0.112 → 0.0.113

package/src/flag-queue.ts

@@ -1,509 +0,0 @@
-import type {
-	IMessageFlagRepository,
-	IMessageRepository,
-	IThreadMessageRepository,
-} from "@remit/data-ports";
-import { NotFoundError } from "@remit/data-ports/errors";
-import { MessageSystemFlag, StarColor } from "@remit/domain-enums";
-import type { FlagPushOperationValue, FlagPushService } from "./flag-push.js";
-
-/**
- * StarColor type derived from the StarColor const object
- */
-type StarColorValue = (typeof StarColor)[keyof typeof StarColor];
-
-/**
- * Logger interface
- */
-export interface FlagQueueLogger {
-	info(obj: Record<string, unknown>, msg: string): void;
-	error(obj: Record<string, unknown>, msg: string): void;
-}
-
-const noopLogger: FlagQueueLogger = {
-	info: () => {},
-	error: () => {},
-};
-
-/**
- * Input for updateFlags API method
- */
-export interface UpdateFlagsInput {
-	isRead?: boolean;
-	isStarred?: boolean;
-	starColor?: StarColorValue;
-}
-
-/**
- * Result of updateFlags API method
- */
-export interface UpdateFlagsResult {
-	messageId: string;
-	isRead: boolean;
-	isStarred: boolean;
-}
-
-/**
- * Configuration for FlagQueueService
- */
-export interface FlagQueueConfig {
-	messageFlagService: IMessageFlagRepository;
-	messageService: IMessageRepository;
-	threadMessageService: IThreadMessageRepository;
-	flagPushService: FlagPushService;
-	logger?: FlagQueueLogger;
-}
-
-/**
- * Service for marking messages as read/unread/starred, local-first with a
- * durable pending-flag marker (issue #1273, epic #1281).
- *
- * Every flip below follows the SAME sequence: persist the pending marker
- * FIRST via {@link FlagPushService.flip} (the durable record IMAP still owes
- * this push, and best-effort enqueues a wake-up hint), THEN apply locally
- * (MessageFlag + ThreadMessage). The marker write is what makes the user's
- * intent durable — not the enqueue, which may fail freely (see
- * `FlagPushService`'s own doc) — and writing it first means a crash before
- * the local write leaves an unapplied local flip behind an already-durable
- * marker, never a flipped flag with no marker (review finding on #1292;
- * mirrors #1289's `PlacementMoveService.moveMessage` ordering). This class
- * therefore no longer touches
- * `Mailbox.unseenCount` at all: that field is a pure projection, recomputed
- * only from IMAP (`doc/rules/data-flow.md`); the displayed count is adjusted
- * at READ TIME from pending markers (`applyPendingMoveCountPrediction`,
- * `packages/backend/src/derive/pendingMoveCounts.ts`).
- *
- * The service updates BOTH entities locally:
- * - MessageFlag: The canonical flag record
- * - ThreadMessage.isRead / hasStars / star: Denormalized for efficient queries
- */
-export class FlagQueueService {
-	private messageFlagService: IMessageFlagRepository;
-	private messageService: IMessageRepository;
-	private threadMessageService: IThreadMessageRepository;
-	private flagPushService: FlagPushService;
-	private log: FlagQueueLogger;
-
-	constructor(config: FlagQueueConfig) {
-		const {
-			messageFlagService,
-			messageService,
-			threadMessageService,
-			flagPushService,
-		} = config;
-		this.messageFlagService = messageFlagService;
-		this.messageService = messageService;
-		this.threadMessageService = threadMessageService;
-		this.flagPushService = flagPushService;
-		this.log = config.logger ?? noopLogger;
-	}
-
-	/**
-	 * Update ThreadMessage.isRead for ALL ThreadMessages matching this messageId.
-	 *
-	 * A message can exist in multiple mailboxes (e.g., inbox and archive), so we
-	 * must update all instances to keep the isRead status consistent.
-	 *
-	 * The `composites` map carries the CURRENT values of every attribute that
-	 * participates in a sort key. ElectroDB uses them for the conditional check
-	 * on the existing row and combines them with `set()` to recompute the new
-	 * sort keys. Passing the NEW `isRead` value here would make the conditional
-	 * check fail (existing row still has the old value) and the patch would be
-	 * misreported as NotFoundError, silently dropping the update.
-	 *
-	 * Handles race condition where ThreadMessage may be deleted between find and update.
-	 */
-	private updateThreadMessageIsRead = async (
-		accountConfigId: string,
-		messageId: string,
-		isRead: boolean,
-	): Promise<void> => {
-		const threadMessages = await this.threadMessageService.findAllByMessageId(
-			accountConfigId,
-			messageId,
-		);
-		if (threadMessages.length === 0) {
-			this.log.info(
-				{ messageId },
-				"ThreadMessage not found for messageId - skipping isRead update",
-			);
-			return;
-		}
-
-		for (const threadMessage of threadMessages) {
-			try {
-				await this.threadMessageService.update(
-					threadMessage.accountConfigId,
-					threadMessage.threadMessageId,
-					{ isRead },
-					{
-						composites: {
-							sentDate: threadMessage.sentDate,
-							mailboxId: threadMessage.mailboxId,
-							isRead: threadMessage.isRead,
-							isDeleted: threadMessage.isDeleted,
-							hasStars: threadMessage.hasStars,
-							hasAttachment: threadMessage.hasAttachment,
-						},
-					},
-				);
-				this.log.info(
-					{ messageId, threadMessageId: threadMessage.threadMessageId, isRead },
-					"Updated ThreadMessage.isRead",
-				);
-			} catch (err) {
-				if (err instanceof NotFoundError) {
-					this.log.info(
-						{ messageId, threadMessageId: threadMessage.threadMessageId },
-						"ThreadMessage deleted during update - skipping isRead update",
-					);
-					continue;
-				}
-				throw err;
-			}
-		}
-	};
-
-	/**
-	 * Update ThreadMessage.hasStars and star color for ALL ThreadMessages matching this messageId.
-	 *
-	 * A message can exist in multiple mailboxes (e.g., inbox and archive), so we
-	 * must update all instances to keep the star status consistent.
-	 *
-	 * Handles race condition where ThreadMessage may be deleted between find and update.
-	 */
-	private updateThreadMessageStars = async (
-		accountConfigId: string,
-		messageId: string,
-		updates: { hasStars?: boolean; star?: StarColorValue },
-	): Promise<void> => {
-		if (Object.keys(updates).length === 0) return;
-
-		const threadMessages = await this.threadMessageService.findAllByMessageId(
-			accountConfigId,
-			messageId,
-		);
-		if (threadMessages.length === 0) {
-			this.log.info(
-				{ messageId },
-				"ThreadMessage not found for messageId - skipping star update",
-			);
-			return;
-		}
-
-		for (const threadMessage of threadMessages) {
-			try {
-				await this.threadMessageService.update(
-					threadMessage.accountConfigId,
-					threadMessage.threadMessageId,
-					updates,
-					{
-						composites: {
-							sentDate: threadMessage.sentDate,
-							mailboxId: threadMessage.mailboxId,
-							isRead: threadMessage.isRead,
-							isDeleted: threadMessage.isDeleted,
-							hasStars: threadMessage.hasStars,
-							hasAttachment: threadMessage.hasAttachment,
-						},
-					},
-				);
-				this.log.info(
-					{
-						messageId,
-						threadMessageId: threadMessage.threadMessageId,
-						updates,
-					},
-					"Updated ThreadMessage stars",
-				);
-			} catch (err) {
-				if (err instanceof NotFoundError) {
-					this.log.info(
-						{ messageId, threadMessageId: threadMessage.threadMessageId },
-						"ThreadMessage deleted during update - skipping star update",
-					);
-					continue;
-				}
-				throw err;
-			}
-		}
-	};
-
-	/**
-	 * Flip one flag field: persist the pending marker FIRST, then apply
-	 * locally. Every caller in this class routes through here so the marker
-	 * write is never skipped. Returns whether a change actually happened —
-	 * `false` for a redundant flip (already in the desired state), which
-	 * every caller uses to skip the (otherwise redundant) ThreadMessage
-	 * update too.
-	 *
-	 * Ordering matters (review finding on #1292): a marker written AFTER the
-	 * local `MessageFlag` flip means a crash between the two awaits strands a
-	 * flipped flag with no marker — no hint was ever sent, the pending-only
-	 * drain never finds it (no marker to find), and message-sync never
-	 * rewrites `MessageFlag` from IMAP for an existing row, so nothing else
-	 * reconciles it either. That is a permanent, silent divergence — exactly
-	 * the defect #1273 exists to kill. Writing the marker first (matching
-	 * #1289's `PlacementMoveService.moveMessage` ordering) makes that
-	 * scenario impossible: the marker's existence is the record of how far
-	 * the sequence got, so a crash after it can strand at worst an
-	 * un-applied LOCAL write behind an already-durable marker — recoverable
-	 * (the caller's natural retry re-applies both steps; `put` and
-	 * `addFlag`/`removeFlag` are both idempotent) — never the reverse.
-	 *
-	 * The current-state check (review finding on #1292) matters for a
-	 * different reason: `markAsRead`/`markAsUnread`/`updateFlags` take the
-	 * DESIRED boolean from the caller rather than deriving it from current
-	 * state (unlike `toggleFlagged`, which already reads `hasFlag` first and
-	 * so can never generate a redundant marker). A redundant "mark as read"
-	 * on an already-read message would otherwise still write a fresh `add
-	 * \Seen` marker; the read-time unseenCount prediction
-	 * (`applyPendingMoveCountPrediction`) would then subtract one for a
-	 * message IMAP already counts as seen, transiently under-counting the
-	 * badge until the marker clears. Skipping the marker (and the local
-	 * write) entirely when the flag already matches removes the false
-	 * prediction at the source, not just its symptom.
-	 */
-	private flipFlag = async (
-		accountId: string,
-		accountConfigId: string,
-		messageId: string,
-		mailboxId: string,
-		flagName: string,
-		operation: FlagPushOperationValue,
-	): Promise<boolean> => {
-		const alreadyInState = await this.messageFlagService.hasFlag(
-			messageId,
-			flagName,
-		);
-		if (
-			(operation === "add" && alreadyInState) ||
-			(operation === "remove" && !alreadyInState)
-		) {
-			this.log.info(
-				{ messageId, flagName, operation },
-				"Flag already in the desired state — skipping redundant marker + local write",
-			);
-			return false;
-		}
-
-		await this.flagPushService.flip({
-			accountId,
-			accountConfigId,
-			messageId,
-			mailboxId,
-			flagName,
-			operation,
-		});
-
-		if (operation === "add") {
-			await this.messageFlagService.addFlag(messageId, flagName);
-		} else {
-			await this.messageFlagService.removeFlag(messageId, flagName);
-		}
-
-		return true;
-	};
-
-	/**
-	 * Mark a message as read (add \Seen flag).
-	 * Updates MessageFlag, ThreadMessage.isRead, and persists a pending
-	 * flag-push marker for IMAP sync.
-	 *
-	 * @param accountConfigId - The owning account config (tenant scope)
-	 * @param messageId - The message to mark as read
-	 * @param accountId - The account ID for the IMAP sync event
-	 */
-	markAsRead = async (
-		accountConfigId: string,
-		messageId: string,
-		accountId: string,
-	): Promise<void> => {
-		const message = await this.messageService.get(messageId);
-
-		const changed = await this.flipFlag(
-			accountId,
-			accountConfigId,
-			messageId,
-			message.mailboxId,
-			MessageSystemFlag.Seen,
-			"add",
-		);
-
-		if (changed) {
-			await this.updateThreadMessageIsRead(accountConfigId, messageId, true);
-		}
-
-		this.log.info(
-			{ messageId, changed },
-			"Marked message as read (local, push pending)",
-		);
-	};
-
-	/**
-	 * Mark a message as unread (remove \Seen flag).
-	 * Updates MessageFlag, ThreadMessage.isRead, and persists a pending
-	 * flag-push marker for IMAP sync.
-	 *
-	 * @param accountConfigId - The owning account config (tenant scope)
-	 * @param messageId - The message to mark as unread
-	 * @param accountId - The account ID for the IMAP sync event
-	 */
-	markAsUnread = async (
-		accountConfigId: string,
-		messageId: string,
-		accountId: string,
-	): Promise<void> => {
-		const message = await this.messageService.get(messageId);
-
-		const changed = await this.flipFlag(
-			accountId,
-			accountConfigId,
-			messageId,
-			message.mailboxId,
-			MessageSystemFlag.Seen,
-			"remove",
-		);
-
-		if (changed) {
-			await this.updateThreadMessageIsRead(accountConfigId, messageId, false);
-		}
-
-		this.log.info(
-			{ messageId, changed },
-			"Marked message as unread (local, push pending)",
-		);
-	};
-
-	/**
-	 * Toggle the starred/flagged status of a message.
-	 * Updates local state and persists a pending flag-push marker for IMAP
-	 * sync.
-	 *
-	 * @param accountConfigId - The owning account config (tenant scope)
-	 * @param messageId - The message to toggle
-	 * @param accountId - The account ID for the IMAP sync event
-	 * @returns true if flag was added, false if removed
-	 */
-	toggleFlagged = async (
-		accountConfigId: string,
-		messageId: string,
-		accountId: string,
-	): Promise<boolean> => {
-		const message = await this.messageService.get(messageId);
-
-		const hasFlag = await this.messageFlagService.hasFlag(
-			messageId,
-			MessageSystemFlag.Flagged,
-		);
-		const operation: FlagPushOperationValue = hasFlag ? "remove" : "add";
-
-		await this.flipFlag(
-			accountId,
-			accountConfigId,
-			messageId,
-			message.mailboxId,
-			MessageSystemFlag.Flagged,
-			operation,
-		);
-
-		this.log.info(
-			{ messageId, operation },
-			"Toggled flagged status (local, push pending)",
-		);
-
-		return operation === "add";
-	};
-
-	/**
-	 * Update message flags using API-friendly input format.
-	 * Maps isRead/isStarred to IMAP flags and updates ThreadMessage accordingly.
-	 *
-	 * @param accountConfigId - The owning account config (tenant scope)
-	 * @param messageId - The message to update
-	 * @param accountId - The account ID for the IMAP sync event
-	 * @param input - The flag updates to apply
-	 * @returns The current flag state after updates
-	 */
-	updateFlags = async (
-		accountConfigId: string,
-		messageId: string,
-		accountId: string,
-		input: UpdateFlagsInput,
-	): Promise<UpdateFlagsResult> => {
-		const message = await this.messageService.get(messageId);
-
-		// Handle isRead -> \Seen flag
-		if (input.isRead !== undefined) {
-			const changed = await this.flipFlag(
-				accountId,
-				accountConfigId,
-				messageId,
-				message.mailboxId,
-				MessageSystemFlag.Seen,
-				input.isRead ? "add" : "remove",
-			);
-			if (changed) {
-				await this.updateThreadMessageIsRead(
-					accountConfigId,
-					messageId,
-					input.isRead,
-				);
-			}
-		}
-
-		// `hasStars` is the boolean of record (the byStarred index sort key) and
-		// the server-side \Flagged keyword; `star` is its presentation colour,
-		// whose absent state is the None sentinel. The two must never disagree,
-		// whichever field the caller sent:
-		//
-		//   isStarred alone  → colour follows the boolean (standard colour on,
-		//                      None off)
-		//   starColor alone  → boolean follows the colour, so `none` unstars and
-		//                      any real colour stars
-		//   both             → isStarred decides the boolean, starColor the colour
-		//
-		// The \Flagged push follows the resulting boolean in every case, so a
-		// colour-only request still reaches the server. `flipFlag` no-ops when the
-		// flag already holds the desired state.
-		if (input.isStarred !== undefined || input.starColor !== undefined) {
-			const starred =
-				input.isStarred ??
-				(input.starColor ?? StarColor.None) !== StarColor.None;
-			const color =
-				input.starColor ?? (starred ? StarColor.Yellow : StarColor.None);
-
-			await this.flipFlag(
-				accountId,
-				accountConfigId,
-				messageId,
-				message.mailboxId,
-				MessageSystemFlag.Flagged,
-				starred ? "add" : "remove",
-			);
-
-			// Update ThreadMessage hasStars and star color for ALL instances
-			await this.updateThreadMessageStars(accountConfigId, messageId, {
-				hasStars: starred,
-				star: color,
-			});
-		}
-
-		// Return current state
-		const isRead = await this.messageFlagService.hasFlag(
-			messageId,
-			MessageSystemFlag.Seen,
-		);
-		const isStarred = await this.messageFlagService.hasFlag(
-			messageId,
-			MessageSystemFlag.Flagged,
-		);
-
-		this.log.info(
-			{ messageId, isRead, isStarred, input },
-			"Updated message flags",
-		);
-
-		return { messageId, isRead, isStarred };
-	};
-}