@remit/mailbox-service 0.0.1

package/src/flag-push.test.ts

@@ -0,0 +1,408 @@
+import assert from "node:assert/strict";
+import { describe, it, mock } from "node:test";
+import type { IMessageFlagPushRepository } from "@remit/data-ports";
+import { MessageSystemFlag } from "@remit/domain-enums";
+import { type FlagPushConfig, FlagPushService } from "./flag-push.js";
+
+const accountId = "acc-1";
+const accountConfigId = "acc-cfg-1";
+const messageId = "msg-1";
+const mailboxId = "mbx-1";
+
+const createMockSqs = (impl?: () => Promise<unknown>) => {
+	const sent: unknown[] = [];
+	return {
+		send: mock.fn(async (cmd: { input: unknown }) => {
+			if (impl) await impl();
+			sent.push(cmd.input);
+			return { MessageId: "ok" };
+		}),
+		_sent: sent,
+	};
+};
+
+interface Harness {
+	service: FlagPushService;
+	markerPuts: Array<Record<string, unknown>>;
+	markerStateUpdates: Array<{
+		messageId: string;
+		flagName: string;
+		state: string;
+	}>;
+	mockSqs: ReturnType<typeof createMockSqs>;
+	logs: { info: unknown[]; error: unknown[] };
+}
+
+const createHarness = (opts?: {
+	sqsImpl?: () => Promise<unknown>;
+	queueUrl?: string;
+	updateStateImpl?: () => Promise<unknown>;
+	findImpl?: () => Promise<unknown>;
+}): Harness => {
+	const markerPuts: Array<Record<string, unknown>> = [];
+	const markerStateUpdates: Array<{
+		messageId: string;
+		flagName: string;
+		state: string;
+	}> = [];
+	const logs = { info: [] as unknown[], error: [] as unknown[] };
+
+	const markerService: IMessageFlagPushRepository = {
+		put: mock.fn(async (input: Record<string, unknown>) => {
+			markerPuts.push(input);
+			return {
+				...input,
+				state: "pending",
+				createdAt: 1,
+				updatedAt: 1,
+			} as never;
+		}),
+		find: mock.fn(async () =>
+			opts?.findImpl ? ((await opts.findImpl()) as never) : null,
+		),
+		updateState: mock.fn(
+			async (id: string, flagName: string, state: string) => {
+				if (opts?.updateStateImpl) return opts.updateStateImpl() as never;
+				markerStateUpdates.push({ messageId: id, flagName, state });
+				return {} as never;
+			},
+		),
+		delete: mock.fn(async () => {}),
+		listByAccountId: mock.fn(async () => []),
+		listByMailboxId: mock.fn(async () => []),
+	};
+
+	const mockSqs = createMockSqs(opts?.sqsImpl);
+
+	const config: FlagPushConfig = {
+		markerService,
+		sqsQueueUrl: opts?.queueUrl ?? "http://localhost:4566/test-queue",
+		logger: {
+			info: (fields: Record<string, unknown>) => {
+				logs.info.push(fields);
+			},
+			error: (fields: Record<string, unknown>) => {
+				logs.error.push(fields);
+			},
+		},
+	};
+
+	const service = new FlagPushService(config);
+	// @ts-expect-error - inject mock SQS client for testing
+	service.sqs = mockSqs;
+
+	return { service, markerPuts, markerStateUpdates, mockSqs, logs };
+};
+
+describe("FlagPushService.flip", () => {
+	it("persists a pending marker before enqueueing the wake-up hint", async () => {
+		const { service, markerPuts } = createHarness();
+
+		await service.flip({
+			accountId,
+			accountConfigId,
+			messageId,
+			mailboxId,
+			flagName: MessageSystemFlag.Seen,
+			operation: "add",
+		});
+
+		assert.equal(markerPuts.length, 1);
+		assert.deepEqual(markerPuts[0], {
+			messageId,
+			flagName: MessageSystemFlag.Seen,
+			accountId,
+			accountConfigId,
+			mailboxId,
+			operation: "add",
+		});
+	});
+
+	it("advances the marker to queued once the SQS hint is confirmed sent", async () => {
+		const { service, markerStateUpdates } = createHarness();
+
+		await service.flip({
+			accountId,
+			accountConfigId,
+			messageId,
+			mailboxId,
+			flagName: MessageSystemFlag.Flagged,
+			operation: "remove",
+		});
+
+		assert.deepEqual(markerStateUpdates, [
+			{ messageId, flagName: MessageSystemFlag.Flagged, state: "queued" },
+		]);
+	});
+
+	it("does NOT reject flip when the wake-up hint enqueue fails (queue down)", async () => {
+		const { service } = createHarness({
+			sqsImpl: () => {
+				throw Object.assign(new Error(""), {
+					name: "AggregateError",
+					code: "ECONNREFUSED",
+				});
+			},
+		});
+
+		await assert.doesNotReject(
+			service.flip({
+				accountId,
+				accountConfigId,
+				messageId,
+				mailboxId,
+				flagName: MessageSystemFlag.Seen,
+				operation: "add",
+			}),
+		);
+	});
+
+	it("leaves the marker in `pending` (never advances to queued) when the hint enqueue fails", async () => {
+		const { service, markerStateUpdates } = createHarness({
+			sqsImpl: () => {
+				throw new Error("ECONNREFUSED");
+			},
+		});
+
+		await service.flip({
+			accountId,
+			accountConfigId,
+			messageId,
+			mailboxId,
+			flagName: MessageSystemFlag.Seen,
+			operation: "add",
+		});
+
+		assert.deepEqual(markerStateUpdates, []);
+	});
+
+	it("logs the enqueue failure loudly with an alertable field (not silent)", async () => {
+		const { service, logs } = createHarness({
+			sqsImpl: () => {
+				throw Object.assign(new Error(""), {
+					name: "AggregateError",
+					code: "ECONNREFUSED",
+				});
+			},
+		});
+
+		await service.flip({
+			accountId,
+			accountConfigId,
+			messageId,
+			mailboxId,
+			flagName: MessageSystemFlag.Seen,
+			operation: "add",
+		});
+
+		const alerted = logs.error.find(
+			(entry) =>
+				(entry as { alert?: string }).alert === "flag_push_hint_enqueue_failed",
+		);
+		assert.ok(
+			alerted,
+			"expected an alertable flag_push_hint_enqueue_failed log",
+		);
+		assert.equal((alerted as { errorCode?: string }).errorCode, "ECONNREFUSED");
+	});
+
+	it("does NOT leak an unhandled rejection onto a concurrent caller when the enqueue fails", async () => {
+		const leaked: unknown[] = [];
+		const onUnhandled = (reason: unknown): void => {
+			leaked.push(reason);
+		};
+		process.on("unhandledRejection", onUnhandled);
+
+		const { service } = createHarness({
+			sqsImpl: () =>
+				new Promise((_resolve, reject) => {
+					setImmediate(() =>
+						reject(
+							Object.assign(new Error(""), {
+								name: "AggregateError",
+								code: "ECONNREFUSED",
+							}),
+						),
+					);
+				}),
+		});
+
+		try {
+			void service.flip({
+				accountId,
+				accountConfigId,
+				messageId,
+				mailboxId,
+				flagName: MessageSystemFlag.Seen,
+				operation: "add",
+			});
+			await new Promise((resolve) => setImmediate(resolve));
+			await new Promise((resolve) => setImmediate(resolve));
+			await new Promise((resolve) => setImmediate(resolve));
+		} finally {
+			process.off("unhandledRejection", onUnhandled);
+		}
+
+		assert.equal(leaked.length, 0);
+	});
+
+	it("sets MessageGroupId=accountId for FIFO queue URLs", async () => {
+		const { service, mockSqs } = createHarness({
+			queueUrl:
+				"https://sqs.eu-west-1.amazonaws.com/123456789012/remit-dev-mailboxes.fifo",
+		});
+
+		await service.flip({
+			accountId,
+			accountConfigId,
+			messageId,
+			mailboxId,
+			flagName: MessageSystemFlag.Seen,
+			operation: "add",
+		});
+
+		assert.equal(mockSqs._sent.length, 1);
+		const sent = mockSqs._sent[0] as { MessageGroupId?: string };
+		assert.equal(sent.MessageGroupId, accountId);
+	});
+
+	it("omits FIFO params for standard queue URLs", async () => {
+		const { service, mockSqs } = createHarness({
+			queueUrl:
+				"https://sqs.eu-west-1.amazonaws.com/123456789012/remit-dev-mailboxes",
+		});
+
+		await service.flip({
+			accountId,
+			accountConfigId,
+			messageId,
+			mailboxId,
+			flagName: MessageSystemFlag.Seen,
+			operation: "add",
+		});
+
+		assert.equal(mockSqs._sent.length, 1);
+		const sent = mockSqs._sent[0] as { MessageGroupId?: string };
+		assert.equal(sent.MessageGroupId, undefined);
+	});
+
+	it("event body carries only messageId + flagName — never the operation or a UID", async () => {
+		const { service, mockSqs } = createHarness();
+
+		await service.flip({
+			accountId,
+			accountConfigId,
+			messageId,
+			mailboxId,
+			flagName: MessageSystemFlag.Flagged,
+			operation: "remove",
+		});
+
+		const sent = mockSqs._sent[0] as { MessageBody: string };
+		const event = JSON.parse(sent.MessageBody);
+		assert.equal(event.type, "FLAG_PUSH");
+		assert.equal(event.messageId, messageId);
+		assert.equal(event.flagName, MessageSystemFlag.Flagged);
+		assert.equal(event.accountId, accountId);
+		assert.equal(event.accountConfigId, accountConfigId);
+		assert.equal("operation" in event, false);
+		assert.equal("uid" in event, false);
+	});
+
+	describe("fast-path race: the worker drains and deletes the marker before the queued-state transition runs (review finding on #1292)", () => {
+		it("does NOT log the flag_push_hint_enqueue_failed alarm when the marker is already gone", async () => {
+			const { service, logs } = createHarness({
+				updateStateImpl: () => {
+					throw new Error(
+						"Cannot update state on a MessageFlagPush that does not exist: msg-1/\\Seen",
+					);
+				},
+				findImpl: () => Promise.resolve(null),
+			});
+
+			await service.flip({
+				accountId,
+				accountConfigId,
+				messageId,
+				mailboxId,
+				flagName: MessageSystemFlag.Seen,
+				operation: "add",
+			});
+
+			assert.equal(
+				logs.error.length,
+				0,
+				"the enqueue succeeded; a fast-path race must never be logged as flag_push_hint_enqueue_failed",
+			);
+			assert.ok(
+				logs.info.length > 0,
+				"the race is still visible as routine info, not silent",
+			);
+		});
+
+		it("still logs the flag_push_hint_enqueue_failed alarm when updateState fails for a REAL reason (marker still present)", async () => {
+			const { service, logs } = createHarness({
+				updateStateImpl: () => {
+					throw new Error("ProvisionedThroughputExceededException");
+				},
+				findImpl: () =>
+					Promise.resolve({
+						messageId,
+						flagName: MessageSystemFlag.Seen,
+						state: "pending",
+					}),
+			});
+
+			await service.flip({
+				accountId,
+				accountConfigId,
+				messageId,
+				mailboxId,
+				flagName: MessageSystemFlag.Seen,
+				operation: "add",
+			});
+
+			const alerted = logs.error.find(
+				(entry) =>
+					(entry as { alert?: string }).alert ===
+					"flag_push_hint_enqueue_failed",
+			);
+			assert.ok(
+				alerted,
+				"a genuine failure behind the race-check must still alarm",
+			);
+		});
+
+		it("still logs the flag_push_hint_enqueue_failed alarm when the re-check itself fails (backend genuinely down)", async () => {
+			const { service, logs } = createHarness({
+				updateStateImpl: () => {
+					throw new Error(
+						"Cannot update state on a MessageFlagPush that does not exist: msg-1/\\Seen",
+					);
+				},
+				findImpl: () => {
+					throw new Error("ECONNREFUSED");
+				},
+			});
+
+			await service.flip({
+				accountId,
+				accountConfigId,
+				messageId,
+				mailboxId,
+				flagName: MessageSystemFlag.Seen,
+				operation: "add",
+			});
+
+			const alerted = logs.error.find(
+				(entry) =>
+					(entry as { alert?: string }).alert ===
+					"flag_push_hint_enqueue_failed",
+			);
+			assert.ok(
+				alerted,
+				"a re-check failure is a real infra problem — must alarm",
+			);
+		});
+	});
+});

package/src/flag-push.ts

@@ -0,0 +1,198 @@
+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)",
+				);
+			});
+	};
+}