@remit/imap-worker 0.0.17 → 0.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/imap-worker",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "type": "module",
   "main": "dist/index.js",
   "exports": {
@@ -20,7 +20,7 @@
     "bundle": "esbuild src/index.ts --sourcemap --bundle --platform=node --format=esm --outfile=dist/index.js",
     "cli": "node --env-file=../../localhost-dev-aws.env src/cli.ts",
     "test:typecheck": "tsgo --noEmit",
-    "test:run": "node --env-file=../../localhost-test-unit.env --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-lines=83 --test 'src/**/*.test.ts'",
+    "test:run": "node --env-file=../../localhost-test-unit.env --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-lines=86 --test 'src/**/*.test.ts'",
     "test": "npm run test:typecheck && npm run test:run",
     "dev": "node --import tsx src/e2e-processor-shim.ts"
   },

package/src/e2e-processor-shim.ts

@@ -14,6 +14,7 @@ import type {
 	SQSHandler,
 } from "aws-lambda";
 import { env } from "expect-env";
+import { receiveVisibilitySeconds } from "./e2e-processor-visibility.js";
 import { handler } from "./index.js";
 
 /**
@@ -150,7 +151,13 @@ if (cluster.isPrimary) {
 					QueueUrl: queueUrl,
 					MaxNumberOfMessages: maxMessages,
 					WaitTimeSeconds: waitTime,
-					VisibilityTimeout: 300,
+					// A failed message is left un-deleted and only redelivers when this
+					// window lapses; on the per-account FIFO sync queues that window is
+					// also how long a single failure head-of-line blocks the account's
+					// whole pipeline (#290). Keep it short for FIFO, long for the
+					// standard queues whose slower work needs it. See
+					// `receiveVisibilitySeconds`.
+					VisibilityTimeout: receiveVisibilitySeconds(queueUrl),
 					MessageSystemAttributeNames: ["ApproximateReceiveCount"],
 				}),
 			);

package/src/e2e-processor-visibility.test.ts

@@ -0,0 +1,43 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	FIFO_RECEIVE_VISIBILITY_SECONDS,
+	receiveVisibilitySeconds,
+	STANDARD_RECEIVE_VISIBILITY_SECONDS,
+} from "./e2e-processor-visibility.js";
+
+describe("receiveVisibilitySeconds", () => {
+	it("gives the per-account FIFO sync queues a short window so a failure unblocks fast", () => {
+		for (const url of [
+			"http://localhost:9324/000/remit-mailboxes.fifo",
+			"http://localhost:9324/000/remit-messages.fifo",
+			"http://localhost:9324/000/remit-flags.fifo",
+		]) {
+			assert.equal(
+				receiveVisibilitySeconds(url),
+				FIFO_RECEIVE_VISIBILITY_SECONDS,
+			);
+		}
+	});
+
+	it("keeps the long window for the standard body and management queues", () => {
+		for (const url of [
+			"http://localhost:9324/000/remit-body",
+			"http://localhost:9324/000/remit-mailbox-mgmt",
+			"http://localhost:9324/000/remit-message-mgmt",
+			"http://localhost:9324/000/remit-search-index",
+		]) {
+			assert.equal(
+				receiveVisibilitySeconds(url),
+				STANDARD_RECEIVE_VISIBILITY_SECONDS,
+			);
+		}
+	});
+
+	it("keeps the FIFO window short enough to unblock within a spec's seed budget, above a sync round's own duration", () => {
+		assert.ok(FIFO_RECEIVE_VISIBILITY_SECONDS > 0);
+		assert.ok(
+			FIFO_RECEIVE_VISIBILITY_SECONDS < STANDARD_RECEIVE_VISIBILITY_SECONDS,
+		);
+	});
+});

package/src/e2e-processor-visibility.ts

@@ -0,0 +1,27 @@
+/**
+ * Receive-time visibility (seconds) the e2e drainer requests for a queue.
+ *
+ * A message the handler reports as failed is left un-deleted and only
+ * redelivers once its visibility lapses. The sync queues are per-account FIFO
+ * (`MessageGroupId = accountId`): while one message sits invisible, every later
+ * message in its group is held back too. So the visibility window a failed sync
+ * event sits out is also the window the whole account's sync pipeline stalls —
+ * and at a multi-minute window that stall swallows a spec's entire seed-and-wait
+ * budget when a transient IMAP hiccup fails one event mid-run, which is the
+ * recurring e2e-dev flake (#290).
+ *
+ * FIFO sync queues therefore get a short window: a transient failure costs one
+ * brief retry instead of a minutes-long group stall, and the handlers on these
+ * queues (a mailbox LIST, a header SEARCH/FETCH) finish well inside it — a rare
+ * slow round redelivers harmlessly, since the mailbox lock makes a concurrent
+ * re-run a no-op. The standard queues (body sync's ranged FETCH of up to 200
+ * message bodies, the management queues) keep the longer window their slower,
+ * non-FIFO work needs and where a redelivery blocks nothing but itself.
+ */
+export const FIFO_RECEIVE_VISIBILITY_SECONDS = 30;
+export const STANDARD_RECEIVE_VISIBILITY_SECONDS = 300;
+
+export const receiveVisibilitySeconds = (queueUrl: string): number =>
+	queueUrl.endsWith(".fifo")
+		? FIFO_RECEIVE_VISIBILITY_SECONDS
+		: STANDARD_RECEIVE_VISIBILITY_SECONDS;

package/src/handlers/sync-messages.test.ts

@@ -4,30 +4,40 @@ import type {
 	AccountItem,
 	IMessageFlagPushRepository,
 } from "@remit/data-ports";
+import { NotFoundError } from "@remit/data-ports/errors";
 import type { Logger } from "@remit/logger-lambda";
-import { drainPendingFlagPushes } from "./sync-messages.js";
+import type { SyncMessagesEvent } from "../events.js";
+import {
+	drainPendingFlagPushes,
+	type SyncMessagesDeps,
+	syncMessages,
+} from "./sync-messages.js";
 
 const buildLogger = (): {
 	log: Logger;
 	infos: Array<{ fields: Record<string, unknown>; msg: string }>;
+	warns: Array<{ fields: Record<string, unknown>; msg: string }>;
 	errors: Array<{ fields: Record<string, unknown>; msg: string }>;
 } => {
 	const infos: Array<{ fields: Record<string, unknown>; msg: string }> = [];
+	const warns: Array<{ fields: Record<string, unknown>; msg: string }> = [];
 	const errors: Array<{ fields: Record<string, unknown>; msg: string }> = [];
 	const log = {
 		info: (fields: Record<string, unknown>, msg: string) => {
 			infos.push({ fields, msg });
 		},
+		warn: (fields: Record<string, unknown>, msg: string) => {
+			warns.push({ fields, msg });
+		},
 		error: (fields: Record<string, unknown>, msg: string) => {
 			errors.push({ fields, msg });
 		},
-		warn: () => {},
 		debug: () => {},
 		fatal: () => {},
 		trace: () => {},
 		child: () => log,
 	} as unknown as Logger;
-	return { log, infos, errors };
+	return { log, infos, warns, errors };
 };
 
 const account = {
@@ -241,3 +251,122 @@ describe("drainPendingFlagPushes — periodic per-mailbox re-arm (issue #1273)",
 		);
 	});
 });
+
+const liveAccount = {
+	accountId: "acc-1",
+	accountConfigId: "acc-cfg-1",
+	imapHost: "localhost",
+	username: "user@localhost",
+} as unknown as AccountItem;
+
+const syncEvent = (mailboxId: string): SyncMessagesEvent => ({
+	type: "SYNC_MESSAGES",
+	accountId: "acc-1",
+	mailboxId,
+	eventId: `evt-${mailboxId}`,
+	timestamp: 1,
+});
+
+/**
+ * A deps factory whose `withOAuthLifecycle` is a spy that records the call but
+ * never invokes the sync callback — the only thing under test here is the
+ * terminal gate BEFORE the lifecycle, so reaching (or not reaching) the spy is
+ * the observable outcome.
+ */
+const buildSyncDeps = (opts: {
+	mailboxGet: () => Promise<unknown>;
+	accountGet?: () => Promise<AccountItem>;
+}): { deps: SyncMessagesDeps; lifecycleCalls: number } => {
+	const state = { lifecycleCalls: 0 };
+	const deps = {
+		getClient: async () => ({
+			account: {
+				get: opts.accountGet ?? (async () => liveAccount),
+			},
+			mailbox: {
+				get: opts.mailboxGet,
+			},
+			secrets: {},
+		}),
+		buildLifecycleDeps: () => ({}),
+		withOAuthLifecycle: async () => {
+			state.lifecycleCalls += 1;
+		},
+	} as unknown as SyncMessagesDeps;
+	return {
+		deps,
+		get lifecycleCalls() {
+			return state.lifecycleCalls;
+		},
+	};
+};
+
+describe("syncMessages — terminal handling of events for a deleted mailbox (issue #287)", () => {
+	it("acks a SYNC_MESSAGES event whose mailbox row is gone — resolves without throwing, never connects", async () => {
+		const { log, warns } = buildLogger();
+		const harness = buildSyncDeps({
+			mailboxGet: async () => {
+				throw new NotFoundError("Mailbox not found: mbx-gone");
+			},
+		});
+
+		await assert.doesNotReject(
+			syncMessages(syncEvent("mbx-gone"), log, harness.deps),
+		);
+
+		assert.equal(
+			harness.lifecycleCalls,
+			0,
+			"a deleted mailbox must short-circuit before the OAuth/connection lifecycle",
+		);
+		const skip = warns.find((w) => w.msg.includes("mailbox no longer exists"));
+		assert.ok(skip, "expected a WARN naming the skipped deleted mailbox");
+		assert.equal(skip.fields.accountId, "acc-1");
+		assert.equal(skip.fields.mailboxId, "mbx-gone");
+		assert.equal(skip.fields.event, "SYNC_MESSAGES");
+	});
+
+	it("propagates a non-NotFound failure from the mailbox lookup — a transient read stays loud", async () => {
+		const { log } = buildLogger();
+		const harness = buildSyncDeps({
+			mailboxGet: async () => {
+				throw new Error("connection reset by peer");
+			},
+		});
+
+		await assert.rejects(
+			syncMessages(syncEvent("mbx-1"), log, harness.deps),
+			/connection reset by peer/,
+		);
+		assert.equal(harness.lifecycleCalls, 0);
+	});
+
+	it("proceeds to the sync lifecycle for a live mailbox", async () => {
+		const { log } = buildLogger();
+		const harness = buildSyncDeps({
+			mailboxGet: async () => ({ mailboxId: "mbx-1", fullPath: "INBOX" }),
+		});
+
+		await syncMessages(syncEvent("mbx-1"), log, harness.deps);
+
+		assert.equal(harness.lifecycleCalls, 1);
+	});
+
+	it("a deleted-mailbox event does not stall the group — a following live-mailbox event still processes", async () => {
+		const { log } = buildLogger();
+		const gone = buildSyncDeps({
+			mailboxGet: async () => {
+				throw new NotFoundError("Mailbox not found: mbx-gone");
+			},
+		});
+		const live = buildSyncDeps({
+			mailboxGet: async () => ({ mailboxId: "mbx-live", fullPath: "INBOX" }),
+		});
+
+		await syncMessages(syncEvent("mbx-gone"), log, gone.deps);
+		await syncMessages(syncEvent("mbx-live"), log, live.deps);
+
+		assert.equal(gone.lifecycleCalls, 0);
+		assert.equal(live.lifecycleCalls, 1);
+	});
+});

package/src/handlers/sync-messages.ts

@@ -53,9 +53,22 @@ export const batchSyncedMessages = (
 	return batches;
 };
 
+export interface SyncMessagesDeps {
+	getClient: typeof getClient;
+	withOAuthLifecycle: typeof withOAuthLifecycle;
+	buildLifecycleDeps: typeof buildLifecycleDeps;
+}
+
+const defaultDeps: SyncMessagesDeps = {
+	getClient,
+	withOAuthLifecycle,
+	buildLifecycleDeps,
+};
+
 export const syncMessages = async (
 	event: SyncMessagesEvent,
 	log: Logger,
+	deps: SyncMessagesDeps = defaultDeps,
 ): Promise<void> => {
 	log.info(
 		{
@@ -80,7 +93,7 @@ export const syncMessages = async (
 		messageFlag: messageFlagService,
 		unitOfWork,
 		secrets,
-	} = await getClient();
+	} = await deps.getClient();
 
 	// A deleted account never has its DDB row purged in lockstep with the queued
 	// SYNC_MESSAGES triggers, so a trigger can outlive its account. The lookup
@@ -118,11 +131,40 @@ export const syncMessages = async (
 		return;
 	}
 
+	// A SYNC_MESSAGES trigger can outlive the mailbox it targets. Deleting a
+	// mailbox that has held mail leaves already-queued events — a `hasMore`
+	// next-batch, a periodic sync tick — pointing at a row that is now gone. The
+	// lookup then throws a named NotFoundError that can never succeed on retry,
+	// and the account's per-group FIFO ordering lets that one poison message
+	// stall the whole account's message pipeline forever (issue #287). A mailbox
+	// the user deliberately deleted is an expected terminal outcome, not an infra
+	// failure: ack the event with a WARN. Any other error — a transient read, a
+	// NotFoundError from elsewhere — still propagates to be retried.
+	const mailboxExists = await mailboxService
+		.get(event.accountId, event.mailboxId)
+		.then(() => true)
+		.catch((err) => {
+			if ((err as { name?: string })?.name === "NotFoundError") return false;
+			throw err;
+		});
+	if (!mailboxExists) {
+		log.warn(
+			{
+				accountId: event.accountId,
+				mailboxId: event.mailboxId,
+				eventId: event.eventId,
+				event: event.type,
+			},
+			"Skipping SYNC_MESSAGES: mailbox no longer exists (deleted)",
+		);
+		return;
+	}
+
 	// withOAuthLifecycle owns the reauth/ACK contract (skip-if-reauth, resolve
 	// credentials, flip on terminal auth failure, rethrow transient). The
 	// mailbox lock and the actual sync run inside the wrapper callback.
-	await withOAuthLifecycle(
-		buildLifecycleDeps(secrets, accountService),
+	await deps.withOAuthLifecycle(
+		deps.buildLifecycleDeps(secrets, accountService),
 		account,
 		log,
 		async (credentials) => {