@remit/imap-worker 0.0.25 → 0.0.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/imap-worker",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "type": "module",
   "main": "dist/index.js",
   "exports": {

package/src/failure-kind.test.ts

@@ -0,0 +1,42 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { RefreshTokenError } from "@remit/mail-oauth-service";
+import { MailConnectionError } from "@remit/mailbox-service";
+import { imapFailureKind } from "./failure-kind.js";
+
+describe("imapFailureKind", () => {
+	it("counts an IMAP authentication rejection as auth", () => {
+		assert.equal(
+			imapFailureKind(
+				new MailConnectionError("auth", "IMAP authentication failed"),
+			),
+			"auth",
+		);
+	});
+
+	it("counts a token refresh that cannot mint credentials as auth", () => {
+		assert.equal(
+			imapFailureKind(
+				new RefreshTokenError({
+					kind: "reauth-required",
+					code: "invalid_grant",
+				}),
+			),
+			"auth",
+		);
+	});
+
+	it("keeps a network failure apart from an auth failure", () => {
+		assert.equal(
+			imapFailureKind(
+				new MailConnectionError("network", "IMAP connection failed: ETIMEDOUT"),
+			),
+			"network",
+		);
+	});
+
+	it("classifies anything else as other", () => {
+		assert.equal(imapFailureKind(new Error("bad cursor")), "other");
+		assert.equal(imapFailureKind(undefined), "other");
+	});
+});

package/src/failure-kind.ts

@@ -0,0 +1,17 @@
+import type { MailFailureKind } from "@remit/logger-lambda";
+import { RefreshTokenError } from "@remit/mail-oauth-service";
+import { MailConnectionError } from "@remit/mailbox-service";
+
+/**
+ * Which class of failure ended an IMAP operation, for the exported failure
+ * counter (standalone-observability D3). `auth` is its own kind because it is
+ * the one class that never resolves itself — an expired OAuth grant or a
+ * changed password fails identically forever, and it is the most common way a
+ * self-hosted mailbox goes quiet. A refresh that cannot mint a token is the
+ * same condition arriving one layer earlier.
+ */
+export const imapFailureKind = (error: unknown): MailFailureKind => {
+	if (error instanceof RefreshTokenError) return "auth";
+	if (error instanceof MailConnectionError) return error.kind;
+	return "other";
+};

package/src/handlers/flag-push.ts

@@ -1,6 +1,6 @@
 import { getClient } from "@remit/backend/client";
 import type { Logger } from "@remit/logger-lambda";
-import { MetricUnit, metrics } from "@remit/logger-lambda";
+import { recordImapFailure } from "@remit/logger-lambda";
 import {
 	guardConnectionCursor,
 	isCursorRebuildNeeded,
@@ -222,15 +222,12 @@ export const handleFlagPush = async (
 					);
 
 					if (outcome === "reconciled") {
-						metrics.addMetric(
-							"flagPushStaleRowReconciled",
-							MetricUnit.Count,
-							1,
-						);
 						return;
 					}
 
-					metrics.addMetric("flagPushFailed", MetricUnit.Count, 1);
+					// Terminal and never re-thrown, so the handler-outcome series
+					// records this record as a success. Counted here or it is invisible.
+					recordImapFailure("FLAG_PUSH_EXHAUSTED", "other");
 					log.error(
 						{ error: error instanceof Error ? error.message : String(error) },
 						"Flag push retry exhausted; message still exists at its mailbox",

package/src/handlers/placement-move-push.ts

@@ -1,6 +1,6 @@
 import { getClient } from "@remit/backend/client";
 import type { Logger } from "@remit/logger-lambda";
-import { MetricUnit, metrics } from "@remit/logger-lambda";
+import { recordImapFailure } from "@remit/logger-lambda";
 import {
 	guardConnectionCursor,
 	type IImapConnection,
@@ -428,11 +428,6 @@ export const handlePlacementMovePush = async (
 					);
 
 					if (outcome === "reconciled") {
-						metrics.addMetric(
-							"placementMoveStaleRowReconciled",
-							MetricUnit.Count,
-							1,
-						);
 						await emitMoveResync(emitEvent, {
 							accountId,
 							sourceMailboxId: marker.sourceMailboxId,
@@ -441,7 +436,9 @@ export const handlePlacementMovePush = async (
 						return;
 					}
 
-					metrics.addMetric("placementMoveFailed", MetricUnit.Count, 1);
+					// Terminal and never re-thrown, so the handler-outcome series
+					// records this record as a success. Counted here or it is invisible.
+					recordImapFailure("PLACEMENT_MOVE_EXHAUSTED", "other");
 					log.error(
 						{ error: error instanceof Error ? error.message : String(error) },
 						"Placement move retry exhausted; message still exists at its source",

package/src/handlers/sync-message-body.ts

@@ -1,6 +1,6 @@
 import { getClient } from "@remit/backend/client";
 import type { Logger } from "@remit/logger-lambda";
-import { MetricUnit, metrics } from "@remit/logger-lambda";
+import { recordImapFailure } from "@remit/logger-lambda";
 import {
 	BodySyncService,
 	guardConnectionCursor,
@@ -157,6 +157,7 @@ export const syncMessageBody = async (
 		secrets,
 		mailboxSpecialUse: mailboxSpecialUseRepository,
 		quarantine: quarantineRepository,
+		flagQueue: flagQueueService,
 	} = await getClient();
 
 	const account = await accountService.get(accountId);
@@ -270,6 +271,7 @@ export const syncMessageBody = async (
 					uidValidity: mailbox.uidValidity ?? 0,
 					attempts: receiveCount,
 				},
+				{ flagQueueService },
 			);
 
 			// Guard at the openBox choke point (epic #1281 invariants 3 & 5). The
@@ -320,35 +322,29 @@ export const syncMessageBody = async (
 				// never a steady state (epic #1281 invariant 3). Resolve every
 				// failed id into exactly one of the two terminal outcomes instead of
 				// letting the record dead-letter with no diagnosis.
-				const { reconciledMessageIds, brokenMessageIds } =
-					await resolveExhaustedBodySyncFailures(
-						{
-							messageService,
-							threadMessageService,
-							storageService: storage,
-							log,
-						},
-						{
-							accountId,
-							accountConfigId: account.accountConfigId,
-							mailboxId,
-							mailboxPath: mailbox.fullPath,
-							failedMessageIds: result.failedMessageIds,
-							getConnection: getConnectionChecked,
-						},
-					);
+				const { brokenMessageIds } = await resolveExhaustedBodySyncFailures(
+					{
+						messageService,
+						threadMessageService,
+						storageService: storage,
+						log,
+					},
+					{
+						accountId,
+						accountConfigId: account.accountConfigId,
+						mailboxId,
+						mailboxPath: mailbox.fullPath,
+						failedMessageIds: result.failedMessageIds,
+						getConnection: getConnectionChecked,
+					},
+				);
 
-				if (reconciledMessageIds.length > 0) {
-					metrics.addMetric(
-						"bodySyncStaleRowReconciled",
-						MetricUnit.Count,
-						reconciledMessageIds.length,
-					);
-				}
+				// A broken body is terminal on a record the handler acks, so the
+				// handler-outcome series never sees it.
 				if (brokenMessageIds.length > 0) {
-					metrics.addMetric(
-						"bodySyncMessageBroken",
-						MetricUnit.Count,
+					recordImapFailure(
+						"SYNC_MESSAGE_BODY_BROKEN",
+						"other",
 						brokenMessageIds.length,
 					);
 				}

package/src/handlers/sync-messages.ts

@@ -14,7 +14,7 @@ import type {
 	IUnitOfWork,
 } from "@remit/data-ports";
 import { SyncPhase } from "@remit/domain-enums";
-import { type Logger, MetricUnit, metrics } from "@remit/logger-lambda";
+import { type Logger, recordImapFailure } from "@remit/logger-lambda";
 import { RefreshTokenError } from "@remit/mail-oauth-service";
 import {
 	createManagedConnectionFactory,
@@ -420,22 +420,13 @@ const syncMailboxMessages = async (
 		"Message sync batch complete",
 	);
 
-	if (result.syncedCount > 0) {
-		metrics.addMetric(
-			"imapMessagesSynced",
-			MetricUnit.Count,
-			result.syncedCount,
-		);
-	}
-
 	// A stalled cursor is the one failure on this path that produces no error:
 	// unapplicable messages are caught and held back, so the round returns
 	// normally, the SQS record is deleted, and neither redrive nor the DLQ ever
-	// engages. Without this metric the mailbox stops syncing behind a worker
-	// that looks healthy. It is emitted as a count so a sustained non-zero
-	// value alarms, per-mailbox detail being in the accompanying ERROR log.
+	// engages. Without this counter the mailbox stops syncing behind a worker
+	// that looks healthy. Per-mailbox detail is in the accompanying ERROR log.
 	if (result.cursorStalled) {
-		metrics.addMetric("imapSyncCursorStalled", MetricUnit.Count, 1);
+		recordImapFailure("SYNC_MESSAGES_CURSOR_STALLED", "other");
 	}
 
 	// Emit body sync events for the messages we just synced. Each event carries

package/src/index.ts

@@ -1,11 +1,13 @@
 import {
 	createLogger,
-	MetricUnit,
-	metrics,
+	queueNameFromEventSource,
+	recordImapFailure,
+	recordQueueEvent,
 	withTelemetry,
 } from "@remit/logger-lambda";
 import type { SQSBatchResponse, SQSEvent, SQSHandler } from "aws-lambda";
 import type { WorkerEvent } from "./events.js";
+import { imapFailureKind } from "./failure-kind.js";
 import { processEvent } from "./processor.js";
 
 const log = createLogger();
@@ -39,15 +41,16 @@ export const handler: SQSHandler = withTelemetry(
 				"Processing event",
 			);
 
-			metrics.addDimension("operation", imapEvent.type);
+			const queue = queueNameFromEventSource(record.eventSourceARN);
 			const opStart = Date.now();
 			const failed = await processEvent(imapEvent, log, receiveCount)
 				.then(() => {
-					metrics.addMetric(
-						"imapOperationLatency",
-						MetricUnit.Milliseconds,
-						Date.now() - opStart,
-					);
+					recordQueueEvent({
+						queue,
+						eventType: imapEvent.type,
+						outcome: "success",
+						durationMs: Date.now() - opStart,
+					});
 					return false;
 				})
 				.catch((error) => {
@@ -55,10 +58,15 @@ export const handler: SQSHandler = withTelemetry(
 						{ error, messageId: record.messageId },
 						"Event processing failed",
 					);
-					metrics.addMetric("imapOperationFailures", MetricUnit.Count, 1);
+					recordQueueEvent({
+						queue,
+						eventType: imapEvent.type,
+						outcome: "failure",
+						durationMs: Date.now() - opStart,
+					});
+					recordImapFailure(imapEvent.type, imapFailureKind(error));
 					return true;
 				});
-			metrics.clearDimensions();
 
 			if (failed) {
 				batchItemFailures.push({ itemIdentifier: record.messageId });

package/src/poller.ts

@@ -1,4 +1,4 @@
-import { createLogger } from "@remit/logger-lambda";
+import { createLogger, startMetricsServer } from "@remit/logger-lambda";
 import { runQueuePoller } from "@remit/sqs-client/poller";
 import { env } from "expect-env";
 import { handler } from "./index.js";
@@ -12,6 +12,11 @@ import { handler } from "./index.js";
  */
 const log = createLogger();
 
+// /metrics and nothing else, on the compose network (standalone-observability
+// D2). No health route on it: worker liveness is a heartbeat file, which keeps
+// answering when this server does not.
+startMetricsServer();
+
 await runQueuePoller({
 	log,
 	targets: [