@remit/mailbox-service 0.0.1

package/src/outbox-queue.ts

@@ -0,0 +1,294 @@
+import { randomUUID } from "node:crypto";
+import { SendMessageCommand, type SQSClient } from "@aws-sdk/client-sqs";
+import type {
+	IAccountRepository,
+	IOutboxMessageRepository,
+	OutboxMessageItem,
+} from "@remit/data-ports";
+import { OutboxMessageStatus } from "@remit/domain-enums";
+import { createQueueProducer } from "@remit/sqs-client/producer";
+
+interface SendMessageEvent {
+	type: "SEND_MESSAGE";
+	eventId: string;
+	timestamp: number;
+	accountId: string;
+	outboxMessageId: string;
+}
+
+export interface OutboxQueueLogger {
+	info(obj: Record<string, unknown>, msg: string): void;
+	error(obj: Record<string, unknown>, msg: string): void;
+}
+
+const noopLogger: OutboxQueueLogger = {
+	info: () => {},
+	error: () => {},
+};
+
+export interface OutboxQueueConfig {
+	outboxMessageService: IOutboxMessageRepository;
+	accountService: IAccountRepository;
+	sqsSmtpQueueUrl: string;
+	sqsEndpoint?: string;
+	logger?: OutboxQueueLogger;
+}
+
+export interface CreateDraftInput {
+	accountId: string;
+	accountConfigId: string;
+	fromAddress: string;
+	fromName?: string;
+	toAddresses: string[];
+	ccAddresses?: string[];
+	bccAddresses?: string[];
+	subject?: string;
+	textBody?: string;
+	htmlBody?: string;
+	inReplyTo?: string;
+	references?: string[];
+}
+
+export interface UpdateDraftInput {
+	toAddresses?: string[];
+	ccAddresses?: string[];
+	bccAddresses?: string[];
+	subject?: string;
+	textBody?: string;
+	htmlBody?: string;
+	inReplyTo?: string;
+	references?: string[];
+}
+
+const generateMessageId = (domain: string): string => {
+	const timestamp = Date.now();
+	const random = randomUUID().replace(/-/g, "").slice(0, 16);
+	return `${timestamp}.${random}@${domain}`;
+};
+
+const extractDomain = (email: string): string => {
+	const atIndex = email.lastIndexOf("@");
+	if (atIndex === -1) return "localhost";
+	return email.slice(atIndex + 1);
+};
+
+export class OutboxQueueService {
+	private outboxMessageService: IOutboxMessageRepository;
+	private accountService: IAccountRepository;
+	private sqs: SQSClient;
+	private queueUrl: string;
+	private log: OutboxQueueLogger;
+
+	constructor(config: OutboxQueueConfig) {
+		const {
+			outboxMessageService,
+			accountService,
+			sqsSmtpQueueUrl,
+			sqsEndpoint,
+		} = config;
+		this.outboxMessageService = outboxMessageService;
+		this.accountService = accountService;
+		this.queueUrl = sqsSmtpQueueUrl;
+		this.log = config.logger ?? noopLogger;
+
+		this.sqs = createQueueProducer({
+			queueUrl: sqsSmtpQueueUrl,
+			endpoint: sqsEndpoint,
+		});
+	}
+
+	createDraft = async (input: CreateDraftInput): Promise<OutboxMessageItem> => {
+		const domain = extractDomain(input.fromAddress);
+		const messageIdValue = generateMessageId(domain);
+
+		const outbox = await this.outboxMessageService.create({
+			accountId: input.accountId,
+			accountConfigId: input.accountConfigId,
+			fromAddress: input.fromAddress,
+			fromName: input.fromName,
+			toAddresses: input.toAddresses,
+			ccAddresses: input.ccAddresses,
+			bccAddresses: input.bccAddresses,
+			subject: input.subject,
+			textBody: input.textBody,
+			htmlBody: input.htmlBody,
+			inReplyTo: input.inReplyTo,
+			references: input.references,
+			messageIdValue,
+			status: OutboxMessageStatus.draft,
+		});
+
+		this.log.info(
+			{ outboxMessageId: outbox.outboxMessageId, accountId: input.accountId },
+			"Created draft outbox message",
+		);
+
+		return outbox;
+	};
+
+	updateDraft = async (
+		accountConfigId: string,
+		outboxMessageId: string,
+		input: UpdateDraftInput,
+	): Promise<OutboxMessageItem> => {
+		const existing = await this.outboxMessageService.get(
+			accountConfigId,
+			outboxMessageId,
+			"act",
+		);
+		if (existing.status !== OutboxMessageStatus.draft) {
+			throw new Error(
+				`Cannot update outbox message with status: ${existing.status}`,
+			);
+		}
+
+		const updated = await this.outboxMessageService.update(
+			accountConfigId,
+			outboxMessageId,
+			{
+				...(input.toAddresses !== undefined && {
+					toAddresses: input.toAddresses,
+				}),
+				...(input.ccAddresses !== undefined && {
+					ccAddresses: input.ccAddresses,
+				}),
+				...(input.bccAddresses !== undefined && {
+					bccAddresses: input.bccAddresses,
+				}),
+				...(input.subject !== undefined && { subject: input.subject }),
+				...(input.textBody !== undefined && { textBody: input.textBody }),
+				...(input.htmlBody !== undefined && { htmlBody: input.htmlBody }),
+				...(input.inReplyTo !== undefined && { inReplyTo: input.inReplyTo }),
+				...(input.references !== undefined && {
+					references: input.references,
+				}),
+			},
+		);
+
+		this.log.info({ outboxMessageId }, "Updated draft outbox message");
+
+		return updated;
+	};
+
+	send = async (
+		accountConfigId: string,
+		outboxMessageId: string,
+	): Promise<OutboxMessageItem> => {
+		const existing = await this.outboxMessageService.get(
+			accountConfigId,
+			outboxMessageId,
+			"act",
+		);
+		if (
+			existing.status !== OutboxMessageStatus.draft &&
+			existing.status !== OutboxMessageStatus.failed &&
+			existing.status !== OutboxMessageStatus.blocked
+		) {
+			throw new Error(
+				`Cannot send outbox message with status: ${existing.status}`,
+			);
+		}
+
+		const updated = await this.outboxMessageService.updateStatus(
+			accountConfigId,
+			outboxMessageId,
+			OutboxMessageStatus.queued,
+		);
+
+		await this.enqueueSend(existing.accountId, outboxMessageId);
+
+		this.log.info(
+			{ outboxMessageId, accountId: existing.accountId },
+			"Queued outbox message for sending",
+		);
+
+		return updated;
+	};
+
+	createAndSend = async (
+		input: CreateDraftInput,
+	): Promise<OutboxMessageItem> => {
+		const domain = extractDomain(input.fromAddress);
+		const messageIdValue = generateMessageId(domain);
+
+		const outbox = await this.outboxMessageService.create({
+			accountId: input.accountId,
+			accountConfigId: input.accountConfigId,
+			fromAddress: input.fromAddress,
+			fromName: input.fromName,
+			toAddresses: input.toAddresses,
+			ccAddresses: input.ccAddresses,
+			bccAddresses: input.bccAddresses,
+			subject: input.subject,
+			textBody: input.textBody,
+			htmlBody: input.htmlBody,
+			inReplyTo: input.inReplyTo,
+			references: input.references,
+			messageIdValue,
+			status: OutboxMessageStatus.queued,
+		});
+
+		await this.enqueueSend(input.accountId, outbox.outboxMessageId);
+
+		this.log.info(
+			{ outboxMessageId: outbox.outboxMessageId, accountId: input.accountId },
+			"Created and queued outbox message for sending",
+		);
+
+		return outbox;
+	};
+
+	deleteDraft = async (
+		accountConfigId: string,
+		outboxMessageId: string,
+	): Promise<void> => {
+		const existing = await this.outboxMessageService.get(
+			accountConfigId,
+			outboxMessageId,
+			"act",
+		);
+		if (
+			existing.status !== OutboxMessageStatus.draft &&
+			existing.status !== OutboxMessageStatus.failed &&
+			existing.status !== OutboxMessageStatus.blocked
+		) {
+			throw new Error(
+				`Cannot delete outbox message with status: ${existing.status}`,
+			);
+		}
+
+		await this.outboxMessageService.delete(accountConfigId, outboxMessageId);
+
+		this.log.info({ outboxMessageId }, "Deleted outbox message");
+	};
+
+	private enqueueSend = async (
+		accountId: string,
+		outboxMessageId: string,
+	): Promise<void> => {
+		const event: SendMessageEvent = {
+			type: "SEND_MESSAGE",
+			eventId: randomUUID(),
+			timestamp: Date.now(),
+			accountId,
+			outboxMessageId,
+		};
+
+		const useFifo = this.queueUrl.endsWith(".fifo");
+		await this.sqs.send(
+			new SendMessageCommand({
+				QueueUrl: this.queueUrl,
+				MessageBody: JSON.stringify(event),
+				...(useFifo && {
+					MessageGroupId: accountId,
+					MessageDeduplicationId: event.eventId,
+				}),
+			}),
+		);
+
+		this.log.info(
+			{ eventId: event.eventId, accountId, outboxMessageId },
+			"Enqueued SEND_MESSAGE event",
+		);
+	};
+}

package/src/pass-through-unit-of-work.ts

@@ -0,0 +1,17 @@
+import type { IUnitOfWork, UnitOfWorkRepositories } from "@remit/data-ports";
+
+/**
+ * Runs the write set against fixed repositories with no surrounding
+ * transaction. For backends (DynamoDB) that have no cross-entity transaction:
+ * the writes are not atomic, matching that backend's own guarantees. The
+ * Postgres path injects a real transactional unit of work instead.
+ */
+export class PassThroughUnitOfWork implements IUnitOfWork {
+	constructor(private repos: UnitOfWorkRepositories) {}
+
+	transaction<T>(
+		fn: (repos: UnitOfWorkRepositories) => Promise<T>,
+	): Promise<T> {
+		return fn(this.repos);
+	}
+}

package/src/placement-move-terminal.test.ts

@@ -0,0 +1,179 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type {
+	IMessageRepository,
+	IThreadMessageRepository,
+} from "@remit/data-ports";
+import type { PlacementMoveLogger } from "./placement-move.js";
+import {
+	type ResolveExhaustedPlacementMoveDeps,
+	resolveExhaustedPlacementMoveFailure,
+} from "./placement-move-terminal.js";
+import type { IImapConnection } from "./types.js";
+
+interface LogEntry {
+	obj: Record<string, unknown>;
+	msg: string;
+}
+
+const buildLogger = (): {
+	log: PlacementMoveLogger;
+	infos: LogEntry[];
+	errors: LogEntry[];
+} => {
+	const infos: LogEntry[] = [];
+	const errors: LogEntry[] = [];
+	return {
+		log: {
+			info: (obj, msg) => infos.push({ obj, msg }),
+			error: (obj, msg) => errors.push({ obj, msg }),
+		},
+		infos,
+		errors,
+	};
+};
+
+const buildConnection = (present: Set<number>): IImapConnection =>
+	({
+		openBox: async () => ({}) as never,
+		fetchMessages: async (uids: number[]) =>
+			uids
+				.filter((uid) => present.has(uid))
+				.map((uid) => ({ uid }) as unknown as never),
+	}) as unknown as IImapConnection;
+
+describe("resolveExhaustedPlacementMoveFailure — the two terminal outcomes (mirrors #1270 for placement moves)", () => {
+	it("RECONCILED (expected): the message is gone from its pending-move source — marker dropped, stale row reconciled, no alarm", async () => {
+		const deletedMessages: string[] = [];
+		const deletedThreadMessages: Array<{
+			accountConfigId: string;
+			threadMessageId: string;
+		}> = [];
+		const markerDeletes: string[] = [];
+		const { log, infos, errors } = buildLogger();
+
+		const deps: ResolveExhaustedPlacementMoveDeps = {
+			markerService: {
+				delete: async (id: string) => {
+					markerDeletes.push(id);
+				},
+			},
+			messageService: {
+				delete: async (id: string) => {
+					deletedMessages.push(id);
+				},
+			} as unknown as Pick<IMessageRepository, "delete">,
+			threadMessageService: {
+				findAllByMessageId: async (
+					accountConfigId: string,
+					messageId: string,
+				) => [{ accountConfigId, threadMessageId: `tm-${messageId}` }],
+				deleteMany: async (
+					keys: Array<{ accountConfigId: string; threadMessageId: string }>,
+				) => {
+					deletedThreadMessages.push(...keys);
+				},
+			} as unknown as Pick<
+				IThreadMessageRepository,
+				"findAllByMessageId" | "deleteMany"
+			>,
+			log,
+		};
+
+		const result = await resolveExhaustedPlacementMoveFailure(deps, {
+			accountId: "acc-1",
+			accountConfigId: "cfg-1",
+			messageId: "msg-gone",
+			uid: 101,
+			sourceMailboxPath: "Junk",
+			getConnection: async () => buildConnection(new Set()),
+		});
+
+		assert.equal(result.outcome, "reconciled");
+		assert.deepEqual(markerDeletes, ["msg-gone"]);
+		assert.deepEqual(deletedMessages, ["msg-gone"]);
+		assert.deepEqual(deletedThreadMessages, [
+			{ accountConfigId: "cfg-1", threadMessageId: "tm-msg-gone" },
+		]);
+		assert.equal(errors.length, 0, "no alarm for the expected/routine outcome");
+		assert.ok(
+			infos.some((e) => e.obj.metric === "placement_move_stale_row_reconciled"),
+		);
+	});
+
+	it("BROKEN: the message still exists at the source — marker LEFT PENDING (never dropped), alarm logged, never re-thrown", async () => {
+		const deletedMessages: string[] = [];
+		const markerDeletes: string[] = [];
+		const { log, errors } = buildLogger();
+
+		const deps: ResolveExhaustedPlacementMoveDeps = {
+			markerService: {
+				delete: async (id: string) => {
+					markerDeletes.push(id);
+				},
+			},
+			messageService: {
+				delete: async (id: string) => {
+					deletedMessages.push(id);
+				},
+			} as unknown as Pick<IMessageRepository, "delete">,
+			threadMessageService: {
+				findAllByMessageId: async () => [],
+				deleteMany: async () => {},
+			} as unknown as Pick<
+				IThreadMessageRepository,
+				"findAllByMessageId" | "deleteMany"
+			>,
+			log,
+		};
+
+		const result = await resolveExhaustedPlacementMoveFailure(deps, {
+			accountId: "acc-1",
+			accountConfigId: "cfg-1",
+			messageId: "msg-broken",
+			uid: 202,
+			sourceMailboxPath: "INBOX",
+			getConnection: async () => buildConnection(new Set([202])),
+		});
+
+		assert.equal(result.outcome, "broken");
+		// The marker is the lock that stops a resync from correcting the message
+		// back to its server location (rule 3) — dropping it here would remove
+		// that protection while the move is still unresolved.
+		assert.deepEqual(markerDeletes, []);
+		assert.deepEqual(deletedMessages, []);
+		assert.ok(
+			errors.some((e) => e.obj.alert === "placement_move_failed"),
+			"expected an alert-shaped log for the broken case",
+		);
+	});
+
+	it("never throws — both outcomes are terminal, the caller always acks", async () => {
+		const { log } = buildLogger();
+		const deps: ResolveExhaustedPlacementMoveDeps = {
+			markerService: { delete: async () => {} },
+			messageService: {
+				delete: async () => {},
+			} as unknown as Pick<IMessageRepository, "delete">,
+			threadMessageService: {
+				findAllByMessageId: async () => [],
+				deleteMany: async () => {},
+			} as unknown as Pick<
+				IThreadMessageRepository,
+				"findAllByMessageId" | "deleteMany"
+			>,
+			log,
+		};
+
+		await assert.doesNotReject(() =>
+			resolveExhaustedPlacementMoveFailure(deps, {
+				accountId: "acc-1",
+				accountConfigId: "cfg-1",
+				messageId: "msg-x",
+				uid: 1,
+				sourceMailboxPath: "INBOX",
+				getConnection: async () => buildConnection(new Set([1])),
+			}),
+		);
+	});
+});

package/src/placement-move-terminal.ts

@@ -0,0 +1,104 @@
+import type { PlacementMoveLogger } from "./placement-move.js";
+import {
+	reconcileStaleMessage,
+	type StaleMessageReconcileDeps,
+} from "./stale-message-reconcile.js";
+import type { IImapConnection } from "./types.js";
+
+export interface ResolveExhaustedPlacementMoveDeps
+	extends StaleMessageReconcileDeps {
+	markerService: { delete(messageId: string): Promise<void> };
+	log: PlacementMoveLogger;
+}
+
+export interface ResolveExhaustedPlacementMoveInput {
+	accountId: string;
+	accountConfigId: string;
+	messageId: string;
+	uid: number;
+	sourceMailboxPath: string;
+	getConnection: () => Promise<IImapConnection>;
+}
+
+export type PlacementMoveTerminalOutcome = "reconciled" | "broken";
+
+export interface ResolveExhaustedPlacementMoveResult {
+	outcome: PlacementMoveTerminalOutcome;
+}
+
+/**
+ * Resolve a PLACEMENT_MOVE_PUSH failure that has exhausted the placement-move
+ * queue's redelivery budget into exactly one of two terminal outcomes,
+ * mirroring `resolveExhaustedBodySyncFailures` (#1270) for the same failure
+ * taxonomy (epic #1281 invariant 3) — no third, softer outcome.
+ *
+ * 1. RECONCILED (expected) — the message no longer exists at its pending-move
+ *    source on IMAP. Per invariant 2, an external delete supersedes the
+ *    marker entirely: the marker is dropped and the stale Message/ThreadMessage
+ *    rows are deleted via {@link reconcileStaleMessage}. This is also the
+ *    outcome for the (rarer, functionally indistinguishable from here) case
+ *    where a foreign client moved the message elsewhere — either way, our
+ *    prediction no longer holds, and the marker cannot be honoured. Metric
+ *    only, no alarm — routine.
+ * 2. BROKEN — the message still exists at the source, but the move keeps
+ *    failing. This indicates broken code or a broken account (issue #1271),
+ *    not a transient blip. The marker is left in place (not cleared) so a
+ *    later resync can never "correct" the message back to its server
+ *    location out from under an operator's investigation — dropping it here
+ *    would remove the very lock rule 3 depends on. Logged with an
+ *    `alert`-shaped entry for an operator alarm; never re-thrown (terminal —
+ *    the caller acks either way, since retrying a stale or permanently-broken
+ *    move can never succeed).
+ */
+export const resolveExhaustedPlacementMoveFailure = async (
+	deps: ResolveExhaustedPlacementMoveDeps,
+	input: ResolveExhaustedPlacementMoveInput,
+): Promise<ResolveExhaustedPlacementMoveResult> => {
+	const {
+		accountId,
+		accountConfigId,
+		messageId,
+		uid,
+		sourceMailboxPath,
+		getConnection,
+	} = input;
+
+	const connection = await getConnection();
+	await connection.openBox(sourceMailboxPath);
+	const found = await connection.fetchMessages([uid]);
+
+	if (found.length === 0) {
+		await deps.markerService.delete(messageId);
+		const { threadMessagesDeleted } = await reconcileStaleMessage(
+			deps,
+			accountConfigId,
+			messageId,
+		);
+		deps.log.info(
+			{
+				metric: "placement_move_stale_row_reconciled",
+				accountId,
+				accountConfigId,
+				messageId,
+				uid,
+				sourceMailboxPath,
+				threadMessagesDeleted,
+			},
+			"Message no longer at its pending-move source after retry exhaustion (external delete or move); marker dropped, stale row reconciled",
+		);
+		return { outcome: "reconciled" };
+	}
+
+	deps.log.error(
+		{
+			alert: "placement_move_failed",
+			accountId,
+			accountConfigId,
+			messageId,
+			uid,
+			sourceMailboxPath,
+		},
+		"Placement move could not be pushed to IMAP after retry exhaustion; message still exists at its source — marker left pending for operator investigation",
+	);
+	return { outcome: "broken" };
+};