@remit/mailbox-service 0.0.112 → 0.0.113

package/src/flag-push.ts

@@ -1,198 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { SendMessageCommand, type SQSClient } from "@aws-sdk/client-sqs";
-import type { IMessageFlagPushRepository } from "@remit/data-ports";
-import { createQueueProducer } from "@remit/sqs-client/producer";
-
-/**
- * Event the reconciler (imap-worker `handleFlagPush`) drains. Carries ONLY
- * our own message id + the flag field — never a UID and never the desired
- * operation (that lives on the marker, resolved fresh at push time, epic
- * #1281 invariant 1). The event stays valid across any amount of queue delay
- * or a later local flip of the SAME field (which replaces the marker before
- * this event is ever processed).
- */
-export interface FlagPushEvent {
-	type: "FLAG_PUSH";
-	eventId: string;
-	timestamp: number;
-	accountId: string;
-	accountConfigId: string;
-	messageId: string;
-	flagName: string;
-}
-
-export interface FlagPushLogger {
-	info(obj: Record<string, unknown>, msg: string): void;
-	error(obj: Record<string, unknown>, msg: string): void;
-}
-
-const noopLogger: FlagPushLogger = {
-	info: () => {},
-	error: () => {},
-};
-
-export interface FlagPushConfig {
-	markerService: IMessageFlagPushRepository;
-	sqsQueueUrl: string;
-	sqsEndpoint?: string;
-	logger?: FlagPushLogger;
-}
-
-export type FlagPushOperationValue = "add" | "remove";
-
-/**
- * Writes a pending flag-push marker and best-effort enqueues a wake-up hint
- * (issue #1273, epic #1281). Called AFTER the caller (`FlagQueueService`) has
- * already durably written the local `MessageFlag`/`ThreadMessage` state in
- * the SAME request — the user's intent is durable the moment `flip` writes
- * the marker, before the enqueue even runs.
- *
- * Mirrors `PlacementMoveService` (#1289)'s marker lifecycle, scoped per
- * (`messageId`, `flagName`) instead of per `messageId` — a message can carry
- * an independent pending read-state marker and pending star marker at once
- * (epic FAQ: "a flag flip replaces a pending flag flip", scoped per field).
- * `put` (not `create`) always resets the marker to `pending`, so a later flip
- * of the SAME field simply replaces the earlier marker — "later intent wins
- * locally".
- *
- * Unlike #1289's placement move (where an enqueue failure must propagate,
- * because nothing besides the marker+enqueue sequence has committed the
- * user's intent), the flag flip here is durable the instant the marker write
- * lands — the enqueue is purely a latency optimization so the push does not
- * have to wait for the next periodic sync tick. An enqueue failure is
- * therefore swallowed on purpose: it must never fail the caller's request.
- * It must also never be silent — logged with an `alert`-shaped entry so a
- * string of failures (SQS itself unhealthy) is operationally visible, same
- * convention as the enqueue this replaces (`flag-queue.ts`'s prior
- * `flag_sync_enqueue_failed`).
- */
-export class FlagPushService {
-	private markerService: IMessageFlagPushRepository;
-	private sqs: SQSClient;
-	private queueUrl: string;
-	private log: FlagPushLogger;
-
-	constructor(config: FlagPushConfig) {
-		this.markerService = config.markerService;
-		this.queueUrl = config.sqsQueueUrl;
-		this.log = config.logger ?? noopLogger;
-		this.sqs = createQueueProducer({
-			queueUrl: config.sqsQueueUrl,
-			endpoint: config.sqsEndpoint,
-		});
-	}
-
-	flip = async (params: {
-		accountId: string;
-		accountConfigId: string;
-		messageId: string;
-		mailboxId: string;
-		flagName: string;
-		operation: FlagPushOperationValue;
-	}): Promise<void> => {
-		const {
-			accountId,
-			accountConfigId,
-			messageId,
-			mailboxId,
-			flagName,
-			operation,
-		} = params;
-
-		await this.markerService.put({
-			messageId,
-			flagName,
-			accountId,
-			accountConfigId,
-			mailboxId,
-			operation,
-		});
-
-		await this.enqueueHint({ accountId, accountConfigId, messageId, flagName });
-	};
-
-	private enqueueHint = async (params: {
-		accountId: string;
-		accountConfigId: string;
-		messageId: string;
-		flagName: string;
-	}): Promise<void> => {
-		const event: FlagPushEvent = {
-			type: "FLAG_PUSH",
-			eventId: randomUUID(),
-			timestamp: Date.now(),
-			...params,
-		};
-
-		const useFifo = this.queueUrl.endsWith(".fifo");
-
-		// The marker persisted in `flip` is the durable record — the queue,
-		// per the issue's own words. This send is only a wake-up hint: a
-		// queue-down failure must NOT fail the caller's flip (intent is
-		// already durable) and must NOT be silent either (standing rule: our
-		// infra failing is never a quiet blip). The periodic per-mailbox
-		// drain (issue #1273) still finds and pushes the marker regardless.
-		await this.sqs
-			.send(
-				new SendMessageCommand({
-					QueueUrl: this.queueUrl,
-					MessageBody: JSON.stringify(event),
-					...(useFifo && {
-						MessageGroupId: params.accountId,
-						MessageDeduplicationId: event.eventId,
-					}),
-				}),
-			)
-			.then(async () => {
-				// Only advance past `pending` once the hint is CONFIRMED sent — a
-				// marker still `pending` is exactly the periodic drain's query
-				// target (`sync-messages.ts`'s `drainPendingFlagPushes`), so a
-				// failed send below must leave it there, never here.
-				await this.markerService
-					.updateState(params.messageId, params.flagName, "queued")
-					.catch(async (error: unknown) => {
-						// Fast-path race (review finding on #1292): the worker can
-						// drain AND delete the marker before this transition runs —
-						// SQS delivery + processing can outrun this .then(). The
-						// enqueue itself already succeeded, so re-check whether the
-						// marker still exists before treating this as an infra
-						// failure: if it's already gone, the push already completed
-						// and this is expected, routine — never the
-						// flag_push_hint_enqueue_failed alarm shape. Any OTHER
-						// failure (e.g. the re-check itself fails because the
-						// backend is genuinely down) still propagates to the outer
-						// catch below.
-						const stillPending = await this.markerService.find(
-							params.messageId,
-							params.flagName,
-						);
-						if (!stillPending) {
-							this.log.info(
-								{ eventId: event.eventId, ...params },
-								"Marker already drained before the queued-state transition (fast-path race, harmless)",
-							);
-							return;
-						}
-						throw error;
-					});
-				this.log.info(
-					{ eventId: event.eventId, ...params },
-					"Enqueued FLAG_PUSH wake-up hint",
-				);
-			})
-			.catch((error: unknown) => {
-				this.log.error(
-					{
-						alert: "flag_push_hint_enqueue_failed",
-						eventId: event.eventId,
-						...params,
-						errorName: (error as { name?: string })?.name,
-						errorCode:
-							(error as { Code?: string })?.Code ??
-							(error as { code?: string })?.code,
-					},
-					"Failed to enqueue FLAG_PUSH wake-up hint (marker persisted; the periodic sync tick will still drain it)",
-				);
-			});
-	};
-}

package/src/flag-queue.test.ts

@@ -1,197 +0,0 @@
-import assert from "node:assert/strict";
-import { afterEach, beforeEach, describe, it } from "node:test";
-import type { AccountItem, MailboxItem } from "@remit/data-ports";
-import { MessageSystemFlag } from "@remit/domain-enums";
-import { FlagPushService } from "./flag-push.js";
-import { resolveExhaustedFlagPushFailure } from "./flag-push-terminal.js";
-import { FlagQueueService, type UpdateFlagsInput } from "./flag-queue.js";
-import {
-	eml,
-	type FakeImapConnection,
-	FakeImapServer,
-} from "./test-helpers/fake-imap.js";
-import {
-	captureQueue,
-	openStore,
-	type QueueCapture,
-	type Store,
-	seedAccount,
-	seedMailbox,
-	seedMessage,
-	silentLog,
-} from "./test-helpers/test-store.js";
-
-let store: Store;
-let capture: QueueCapture;
-let account: AccountItem;
-let inbox: MailboxItem;
-let messageId: string;
-
-beforeEach(async () => {
-	capture = captureQueue();
-	store = await openStore();
-	account = await seedAccount(store);
-	inbox = await seedMailbox(store, account, "INBOX");
-	messageId = (await seedMessage(store, account, inbox, 1)).message.messageId;
-});
-
-afterEach(async () => {
-	capture.restore();
-	await store.close();
-});
-
-const flags = () =>
-	new FlagQueueService({
-		messageFlagService: store.messageFlag,
-		messageService: store.message,
-		threadMessageService: store.threadMessage,
-		flagPushService: new FlagPushService({
-			markerService: store.flagPush,
-			sqsQueueUrl: "https://sqs.test/flags",
-		}),
-	});
-
-const update = (input: UpdateFlagsInput) =>
-	flags().updateFlags(
-		account.accountConfigId,
-		messageId,
-		account.accountId,
-		input,
-	);
-
-const listing = async () =>
-	(
-		await store.threadMessage.findAllByMessageId(
-			account.accountConfigId,
-			messageId,
-		)
-	)[0];
-
-const owedFlagged = async () =>
-	(await store.flagPush.find(messageId, MessageSystemFlag.Flagged))?.operation;
-
-describe("updateFlags keeps the star and its colour in step", () => {
-	for (const [input, hasStars, star, owed] of [
-		[{ isStarred: true }, true, "yellow", "add"],
-		[{ isStarred: true, starColor: "red" }, true, "red", "add"],
-		[{ starColor: "blue" }, true, "blue", "add"],
-		[{ isStarred: true, starColor: "none" }, true, "none", "add"],
-	] as const) {
-		it(`${JSON.stringify(input)} stars as ${star} and owes the server \\Flagged`, async () => {
-			await update(input);
-
-			const row = await listing();
-			assert.equal(row.hasStars, hasStars);
-			assert.equal(row.star, star);
-			assert.equal(await owedFlagged(), owed);
-		});
-	}
-
-	for (const input of [{ isStarred: false }, { starColor: "none" }] as const) {
-		it(`${JSON.stringify(input)} unstars a starred message`, async () => {
-			await update({ isStarred: true });
-
-			await update(input);
-
-			const row = await listing();
-			assert.equal(row.hasStars, false);
-			assert.equal(row.star, "none");
-			assert.equal(await owedFlagged(), "remove");
-		});
-	}
-
-	it("marks read once and treats a repeat as no change", async () => {
-		await update({ isRead: true });
-		const first = await store.flagPush.find(messageId, MessageSystemFlag.Seen);
-
-		const result = await update({ isRead: true });
-
-		assert.equal(result.isRead, true);
-		assert.equal((await listing()).isRead, true);
-		assert.deepEqual(
-			await store.flagPush.find(messageId, MessageSystemFlag.Seen),
-			first,
-		);
-	});
-});
-
-describe("a flag push that exhausted its retries", () => {
-	const resolve = async (
-		connect: () => FakeImapConnection,
-		afterRead: () => Promise<unknown> = async () => {},
-	) => {
-		await update({ isRead: true });
-		const read = await store.message.get(messageId);
-		await afterRead();
-		return resolveExhaustedFlagPushFailure(
-			{
-				messageService: store.message,
-				markerService: store.flagPush,
-				log: silentLog,
-			},
-			{
-				placement: {
-					status: read.status,
-					mailboxId: read.mailboxId,
-					uid: read.uid,
-				},
-				accountId: account.accountId,
-				accountConfigId: account.accountConfigId,
-				messageId,
-				flagName: MessageSystemFlag.Seen,
-				uid: 1,
-				mailboxPath: "INBOX",
-				getConnection: async () => connect(),
-			},
-		);
-	};
-
-	it("drops the push and the stale rows of a message the server no longer holds", async () => {
-		const imap = new FakeImapServer();
-		imap.addFolder("INBOX");
-
-		const { outcome } = await resolve(() => imap.connection());
-
-		assert.equal(outcome, "reconciled");
-		assert.equal(
-			await store.flagPush.find(messageId, MessageSystemFlag.Seen),
-			null,
-		);
-		await assert.rejects(store.message.get(messageId));
-	});
-
-	it("leaves a row the user moved after the push read it", async () => {
-		const imap = new FakeImapServer();
-		imap.addFolder("INBOX");
-		const archive = await seedMailbox(store, account, "Archive");
-
-		const { outcome } = await resolve(
-			() => imap.connection(),
-			() =>
-				store.message.transitionPlacement(
-					messageId,
-					{ mailboxId: inbox.mailboxId },
-					{ mailboxId: archive.mailboxId, uid: 7 },
-				),
-		);
-
-		assert.equal(outcome, "reconciled");
-		const moved = await store.message.get(messageId);
-		assert.equal(moved.mailboxId, archive.mailboxId);
-		assert.equal(moved.uid, 7);
-	});
-
-	it("keeps the push and the rows of a message still there, dropped FETCH row or not", async () => {
-		const imap = new FakeImapServer();
-		imap.addFolder("INBOX");
-		imap.deliver("INBOX", eml({}));
-		const connection = imap.connection();
-		connection.fetchMessages = async () => [];
-
-		const { outcome } = await resolve(() => connection);
-
-		assert.equal(outcome, "broken");
-		assert.ok(await store.flagPush.find(messageId, MessageSystemFlag.Seen));
-		assert.ok(await store.message.get(messageId));
-	});
-});