@remit/data-ports 0.0.64 → 0.0.65

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/data-ports",
-  "version": "0.0.64",
+  "version": "0.0.65",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/errors.ts

@@ -99,11 +99,14 @@ export class MailboxNotSettledError extends ConflictError {
 }
 
 /**
- * Why the row's folder and uid do not name the same message. `in_flight` clears
- * on its own, so the client words a wait; `unverified` does not, so it words a
- * resync instead.
+ * Why the row's folder and uid do not name the same message. One value, because
+ * one state produces it: a mutation is still in flight and the pair clears on
+ * its own, so the client words a wait rather than a repair. A mutation that
+ * gave up does not reach here — it hands the row back to a placement the server
+ * confirmed first (docs/architecture/imap-mutations.md R3), which is a pair
+ * every dependent mutation can act on.
  */
-export type MessagePlacementUnsettledReason = "in_flight" | "unverified";
+export type MessagePlacementUnsettledReason = "in_flight";
 
 export class MessagePlacementUnsettledError extends ConflictError {
 	name = "MessagePlacementUnsettledError";
@@ -185,3 +188,21 @@ export class InternalServerError extends UnhandledError {
 	name = "InternalServerError";
 	public statusCode = 500;
 }
+
+/**
+ * A repository lookup or write for a row that no longer exists rejects with a
+ * `NotFoundError`, name-matched rather than by `instanceof`: the class crosses
+ * the adapter boundary and an adapter may throw its own.
+ *
+ * A worker event that references a deliberately-deleted mailbox is completed or
+ * moot work, never a transient fault: every redelivery re-throws the same
+ * `NotFoundError`, and because the sync queues carry `MessageGroupId=accountId`
+ * that permanently-failing head message stalls the whole account's per-group
+ * FIFO. Handlers use this predicate to resolve such an event terminally (ack
+ * with a WARN) instead of retrying forever (issues #287, #289, #290).
+ *
+ * The guard is narrow on purpose: only a genuine not-found terminates. Real
+ * IMAP/infra failures carry other errors and must still propagate to be retried.
+ */
+export const isNotFoundError = (error: unknown): boolean =>
+	(error as { name?: string })?.name === "NotFoundError";

package/src/index.ts

@@ -52,7 +52,11 @@ export type {
 	UnitOfWorkRepositories,
 } from "./interfaces/unit-of-work.js";
 export type { MessageSettlementFields } from "./message-settlement.js";
-export { hasAbandonedDelete } from "./message-settlement.js";
+export {
+	abandonedMutationOf,
+	hasAbandonedDelete,
+	hasAbandonedMove,
+} from "./message-settlement.js";
 export {
 	FILTER_NO_ACTION,
 	isSenderMuted,
@@ -126,6 +130,8 @@ export type {
 	OrganizeJobRequestItem,
 	OutboxAttachmentItem,
 	OutboxMessageItem,
+	PlacementPredicate,
+	PlacementTransitionInput,
 	PutCalendarFeedTokenInput,
 	PutCalendarObjectInput,
 	PutCalendarSuggestionInput,
@@ -151,7 +157,6 @@ export type {
 	UpdateLabelInput,
 	UpdateMailboxInput,
 	UpdateMessageInput,
-	UpdateMessageMoveInput,
 	UpdateOrganizeJobRequestInput,
 	UpdateOutboxMessageInput,
 	UpdateThreadMessageInput,

package/src/interfaces/message.ts

@@ -3,9 +3,10 @@ import type {
 	MessageDescription,
 	MessageIdSource,
 	MessageItem,
+	PlacementPredicate,
+	PlacementTransitionInput,
 	ResultList,
 	UpdateMessageInput,
-	UpdateMessageMoveInput,
 } from "../types.js";
 
 export interface IMessageRepository {
@@ -19,7 +20,6 @@ export interface IMessageRepository {
 	update(messageId: string, input: UpdateMessageInput): Promise<MessageItem>;
 	clearBodyStorageKey(messageId: string): Promise<MessageItem>;
 	clearSpamReport(messageId: string): Promise<MessageItem>;
-	clearOriginalMailboxId(messageId: string): Promise<MessageItem>;
 	delete(messageId: string): Promise<void>;
 	deleteMany(messageIds: string[]): Promise<void>;
 	listByMailbox(
@@ -28,15 +28,29 @@ export interface IMessageRepository {
 	): Promise<ResultList<MessageItem>>;
 	listAllByMailbox(mailboxId: string): Promise<MessageItem[]>;
 	describe(messageId: string): Promise<MessageDescription>;
-	updateForMove(
-		messageId: string,
-		input: UpdateMessageMoveInput,
-	): Promise<MessageItem>;
 	updateUid(
 		messageId: string,
 		newUid: number,
 		newMailboxId: string,
 	): Promise<MessageItem>;
+	/**
+	 * Move the row's placement from the state the caller read to the state it
+	 * decided on, as one conditional write (imap-mutations R3). The only writer
+	 * of `mailboxId`, `status`, `syncStatus`, `abandonedMutation`,
+	 * `originalMailboxId` and `originalUid`, apart from the settle in
+	 * {@link updateUid} — so a placement written without a predicate is a type
+	 * error rather than a convention.
+	 *
+	 * Resolves with the written row when the predicate matched, and with
+	 * `undefined` when it did not — someone else won, or the row is gone. The
+	 * loser re-reads and re-decides; it never blind-retries and never writes
+	 * anyway.
+	 */
+	transitionPlacement(
+		messageId: string,
+		expected: PlacementPredicate,
+		next: PlacementTransitionInput,
+	): Promise<MessageItem | undefined>;
 }
 
 export type { MessageIdSource };

package/src/message-placement-doors.test.ts

@@ -0,0 +1,100 @@
+/**
+ * The two doors, proved by the compiler.
+ *
+ * `docs/architecture/imap-mutations.md` R3 says a placement is written only as
+ * a conditional write. A rule like that is worth exactly as much as the thing
+ * enforcing it, and a convention enforces nothing: the first four writers on
+ * this branch each reached for the general-purpose `update()` and nobody
+ * noticed, because nothing stopped them.
+ *
+ * So the placement fields are gone from every input type but the two that are
+ * allowed to carry them — `transitionPlacement`, which takes a predicate, and
+ * the settle in `updateUid`, which takes no input object at all and writes what
+ * the mail server confirmed. Every `@ts-expect-error` below is a door that is
+ * shut: delete the omission from `UpdateMessageInput` and these stop erroring,
+ * which fails the build.
+ *
+ * `@ts-expect-error` is the assertion here, so this file is checked rather than
+ * run. The one runtime case exists to keep the suite honest about having loaded
+ * it.
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import type {
+	PlacementPredicate,
+	PlacementTransitionInput,
+	UpdateMessageInput,
+} from "./types.js";
+
+// --- The general-purpose writer refuses every placement field ---------------
+
+// @ts-expect-error `status` is a placement field: write it through a transition
+const status: UpdateMessageInput = { status: "moving" };
+
+// @ts-expect-error `syncStatus` is a placement field
+const syncStatus: UpdateMessageInput = { syncStatus: "failed" };
+
+// @ts-expect-error `abandonedMutation` is a placement field
+const abandonedMutation: UpdateMessageInput = { abandonedMutation: "delete" };
+
+// @ts-expect-error `mailboxId` is a placement field
+const mailboxId: UpdateMessageInput = { mailboxId: "mbx-1" };
+
+// @ts-expect-error `uid` is a placement field
+const uid: UpdateMessageInput = { uid: 42 };
+
+// @ts-expect-error `originalMailboxId` is a placement field
+const originalMailboxId: UpdateMessageInput = { originalMailboxId: "mbx-1" };
+
+// @ts-expect-error `originalUid` is a placement field
+const originalUid: UpdateMessageInput = { originalUid: 42 };
+
+// Everything else about a message still goes through it, unchanged.
+const ordinary: UpdateMessageInput = {
+	bodyStorageKey: "s3://body",
+	category: "personal",
+	spamReport: { reportedAt: 0 },
+};
+
+// --- The transition is the door, and it takes a predicate -------------------
+
+const transition: {
+	expected: PlacementPredicate;
+	next: PlacementTransitionInput;
+} = {
+	expected: { status: ["moving", "deleting"], mailboxId: "mbx-1", uid: 42 },
+	next: {
+		status: "active",
+		syncStatus: "abandoned",
+		abandonedMutation: "delete",
+		mailboxId: "mbx-1",
+		uid: 42,
+		originalMailboxId: null,
+		originalUid: null,
+	},
+};
+
+// The predicate names states, never a free-form column: a caller cannot smuggle
+// an unrelated field into the WHERE clause and call it a lock.
+// @ts-expect-error `category` is not part of a placement
+const notAPlacement: PlacementPredicate = { category: "personal" };
+
+test("the placement doors are the transition and the settle", () => {
+	assert.equal(transition.next.status, "active");
+	assert.equal(ordinary.category, "personal");
+	assert.deepEqual(
+		[
+			status,
+			syncStatus,
+			abandonedMutation,
+			mailboxId,
+			uid,
+			originalMailboxId,
+			originalUid,
+			notAPlacement,
+		].length,
+		8,
+		"each of the seven fields, and the predicate's own shape, is pinned above",
+	);
+});

package/src/message-settlement.test.ts

@@ -1,72 +1,132 @@
 import assert from "node:assert/strict";
 import { describe, test } from "node:test";
-import { MessageStatus, MessageSyncStatus } from "@remit/domain-enums";
-import { hasAbandonedDelete } from "./message-settlement.js";
+import {
+	MessageMutation,
+	MessageStatus,
+	MessageSyncStatus,
+} from "@remit/domain-enums";
+import {
+	abandonedMutationOf,
+	hasAbandonedDelete,
+	hasAbandonedMove,
+	type MessageSettlementFields,
+} from "./message-settlement.js";
 
-describe("hasAbandonedDelete", () => {
-	test("the pair abandonDelete writes, its only writer", () => {
+const row = (over: Partial<MessageSettlementFields>): MessageSettlementFields =>
+	({
+		status: MessageStatus.active,
+		syncStatus: MessageSyncStatus.synced,
+		abandonedMutation: MessageMutation.none,
+		...over,
+	}) as MessageSettlementFields;
+
+describe("abandonedMutationOf", () => {
+	test("names the delete `abandonDelete` gave up on", () => {
 		assert.equal(
-			hasAbandonedDelete({
-				status: MessageStatus.active,
-				syncStatus: MessageSyncStatus.failed,
-			}),
-			true,
+			abandonedMutationOf(
+				row({
+					syncStatus: MessageSyncStatus.abandoned,
+					abandonedMutation: MessageMutation.delete,
+				}),
+			),
+			MessageMutation.delete,
 		);
 	});
 
-	test("a move mid-retry is not a give-up, whatever `failed` suggests", () => {
+	/**
+	 * Issue #1229: the two used to be one state on the wire, so a move that
+	 * handed back rendered the delete copy under a button that deleted the
+	 * message. The row has to say which, because the hand-back is what erased
+	 * the `status` that said it.
+	 */
+	test("names the move a hand-back gave up on, distinctly", () => {
 		assert.equal(
-			hasAbandonedDelete({
-				status: MessageStatus.moving,
-				syncStatus: MessageSyncStatus.failed,
-			}),
-			false,
+			abandonedMutationOf(
+				row({
+					syncStatus: MessageSyncStatus.abandoned,
+					abandonedMutation: MessageMutation.move,
+				}),
+			),
+			MessageMutation.move,
 		);
 	});
 
-	test("a delete mid-retry keeps `deleting`, so it is not a give-up", () => {
+	test("`syncStatus` is the gate: a settled row's stale marker says nothing", () => {
 		assert.equal(
-			hasAbandonedDelete({
-				status: MessageStatus.deleting,
-				syncStatus: MessageSyncStatus.failed,
-			}),
-			false,
+			abandonedMutationOf(
+				row({
+					syncStatus: MessageSyncStatus.synced,
+					abandonedMutation: MessageMutation.delete,
+				}),
+			),
+			MessageMutation.none,
 		);
 	});
 
-	test("a copy that gave up hides its row as `deleted` rather than claiming this", () => {
+	/**
+	 * `failed` is the transient attempt marker — every handler writes it and
+	 * re-throws for redelivery (imap-mutations R3) — so it can never mean a
+	 * give-up, whatever `status` sits beside it. This is issue #1153: before the
+	 * give-up had a value of its own, these three were the same row.
+	 */
+	for (const status of [
+		MessageStatus.active,
+		MessageStatus.moving,
+		MessageStatus.deleting,
+	]) {
+		test(`a ${status} row mid-retry is not a give-up`, () => {
+			assert.equal(
+				abandonedMutationOf(
+					row({ status, syncStatus: MessageSyncStatus.failed }),
+				),
+				MessageMutation.none,
+			);
+		});
+	}
+
+	test("an ordinary inbound row, `pending` forever, says nothing", () => {
 		assert.equal(
-			hasAbandonedDelete({
-				status: MessageStatus.deleted,
-				syncStatus: MessageSyncStatus.failed,
-			}),
-			false,
+			abandonedMutationOf(row({ syncStatus: MessageSyncStatus.pending })),
+			MessageMutation.none,
 		);
 	});
 
 	/**
-	 * Both a settled move (`updateUid`) and a delete that exhausted its retries
-	 * (#1143 repairs the row to where the message actually is) land on this pair.
-	 * The second is a give-up this predicate deliberately cannot see — pinned so
-	 * the gap is a decision on record, not an oversight.
+	 * A move or delete that exhausted its retries is repaired against IMAP and
+	 * now carries the give-up (#1098, #1005). What still lands on `synced` is a
+	 * hand-back that refused nothing — the server never heard the command — and
+	 * that is settled, not abandoned.
 	 */
-	test("`active` + `synced` is never a give-up, however it was reached", () => {
+	test("`synced` is never a give-up, however it was reached", () => {
 		assert.equal(
-			hasAbandonedDelete({
-				status: MessageStatus.active,
-				syncStatus: MessageSyncStatus.synced,
-			}),
-			false,
+			abandonedMutationOf(row({ syncStatus: MessageSyncStatus.synced })),
+			MessageMutation.none,
 		);
 	});
+});
+
+describe("the per-operation predicates", () => {
+	const abandoned = (
+		mutation: MessageSettlementFields["abandonedMutation"],
+	): MessageSettlementFields =>
+		row({
+			syncStatus: MessageSyncStatus.abandoned,
+			abandonedMutation: mutation,
+		});
+
+	test("a delete that gave up is a delete and not a move", () => {
+		assert.equal(hasAbandonedDelete(abandoned(MessageMutation.delete)), true);
+		assert.equal(hasAbandonedMove(abandoned(MessageMutation.delete)), false);
+	});
 
-	test("an ordinary inbound row, `pending` forever, says nothing", () => {
-		assert.equal(
-			hasAbandonedDelete({
-				status: MessageStatus.active,
-				syncStatus: MessageSyncStatus.pending,
-			}),
-			false,
-		);
+	test("a move that gave up is a move and not a delete", () => {
+		assert.equal(hasAbandonedMove(abandoned(MessageMutation.move)), true);
+		assert.equal(hasAbandonedDelete(abandoned(MessageMutation.move)), false);
+	});
+
+	test("a copy that gave up claims neither", () => {
+		const copy = abandoned(MessageMutation.copy);
+		assert.equal(hasAbandonedDelete(copy), false);
+		assert.equal(hasAbandonedMove(copy), false);
 	});
 });

package/src/message-settlement.ts

@@ -1,47 +1,50 @@
-import { MessageStatus, MessageSyncStatus } from "@remit/domain-enums";
+import { MessageMutation, MessageSyncStatus } from "@remit/domain-enums";
 import type { MessageItem } from "./types.js";
 
 export type MessageSettlementFields = Pick<
 	MessageItem,
-	"status" | "syncStatus"
+	"status" | "syncStatus" | "abandonedMutation"
 >;
 
 /**
- * A delete Remit refused to run, having already removed the message locally.
- * `abandonDelete` reaches this from four checks, all of them made before any
- * expunge: the Trash folder the event names is not on the server (TRYCREATE),
- * the event carries no destination, it names an operation this build does not
- * recognise, or it was minted under an unknown contract. The row is handed back
- * to the folder the server still holds the message in.
+ * Which mutation gave up on this row, and `none` where none did.
  *
- * `status: active` alongside `syncStatus: failed` is the whole signal, and
- * `abandonDelete` (`imap-worker/src/handlers/message-delete.ts`) is its ONLY
- * writer. Every other writer of either value writes the other along with it:
+ * `syncStatus: abandoned` is the gate and the only gate: it is the give-up
+ * value of the placement state model (docs/architecture/imap-mutations.md R3),
+ * written only after the row has been put back on a placement the mail server
+ * confirmed. Every settle overwrites it, and the settle in `updateUid` clears
+ * `abandonedMutation` alongside it. A transient attempt writes
+ * `failed` and re-throws for redelivery, so `failed` never reaches here.
  *
- * - `updateUid` (`drizzle-service/src/repos/message.ts`) settles a confirmed
- *   move by writing `active` and `synced` in the same statement, so a move that
- *   worked after a failed attempt cannot leave `failed` behind.
- * - `empty-trash` and `message-copy`'s `settleCopied` both hand a row back as
- *   `active` + `synced`.
- * - `upsertWithStatus` leaves an existing row alone, so no inbound sync writes
- *   either value onto a row that already has them.
+ * `abandonedMutation` behind that gate says WHICH mutation, which the row
+ * otherwise cannot say: the hand-back sets `status` back to `active`, and
+ * `status` was the field naming the mutation that was outstanding. Reading the
+ * pair without it is how a move that handed back came to be reported to the
+ * user as a failed delete, under a "Delete again" button (issue #1229).
  *
- * `syncStatus: failed` ON ITS OWN is NOT a give-up marker, whatever
- * `placement-settled.ts`'s docstring says. `message-move.ts`, `message-delete.ts`
- * and `message-copy.ts` each write it on an ORDINARY TRANSIENT attempt and then
- * re-throw for queue redelivery — the row is mid-retry and about to succeed. In
- * those handlers `status` stays at its in-flight value (`moving`, `deleting`),
- * which is what separates them from the pair above.
+ * Outside the gate the field is `none` and says nothing, exactly as
+ * `originalUid` says nothing once a placement has settled. Reading it
+ * unconditionally would resurrect a give-up a later mutation has settled.
  *
- * Two give-ups this cannot see, and must not pretend to:
- *
- * - A MOVE or a DELETE that exhausted its retries settles `active` + `synced`
- *   (`resolveExhaustedMessageMoveFailure` and
- *   `resolveExhaustedMessageDeleteFailure` repair the row to where the message
- *   actually is — #1098, #1005), so both read as fully settled here.
- * - `flag-push` and `placement-move-push` never write either field at all.
- *   Their give-up state lives on their own marker rows.
+ * Two give-ups this deliberately does not name. `flag-push` never writes a
+ * placement at all — its give-up lives on its own marker row and in an
+ * operator alert. `placement-move-push` does restore the row when its push is
+ * exhausted, and drops its marker with it, but leaves this field at `none`:
+ * Remit's own classification move is not a mutation the user asked for, so a
+ * per-message treatment for it would report a failure against an intent nobody
+ * formed.
  */
+export const abandonedMutationOf = (
+	message: MessageSettlementFields,
+): MessageItem["abandonedMutation"] =>
+	message.syncStatus === MessageSyncStatus.abandoned
+		? message.abandonedMutation
+		: MessageMutation.none;
+
+/** A delete Remit refused to run or gave up on, having removed it locally first. */
 export const hasAbandonedDelete = (message: MessageSettlementFields): boolean =>
-	message.status === MessageStatus.active &&
-	message.syncStatus === MessageSyncStatus.failed;
+	abandonedMutationOf(message) === MessageMutation.delete;
+
+/** A move Remit gave up on, having already pointed the row at the destination. */
+export const hasAbandonedMove = (message: MessageSettlementFields): boolean =>
+	abandonedMutationOf(message) === MessageMutation.move;

package/src/types.ts

@@ -384,6 +384,7 @@ export type CreateMessageInput = Omit<
 	| "updatedAt"
 	| "status"
 	| "syncStatus"
+	| "abandonedMutation"
 	| "category"
 	| "classificationState"
 	| "authenticityVerdict"
@@ -393,6 +394,7 @@ export type CreateMessageInput = Omit<
 	messageId: string;
 	status?: MessageItem["status"];
 	syncStatus?: MessageItem["syncStatus"];
+	abandonedMutation?: MessageItem["abandonedMutation"];
 	category?: MessageItem["category"];
 	classificationState?: MessageItem["classificationState"];
 	authenticityVerdict?: MessageItem["authenticityVerdict"];
@@ -400,22 +402,56 @@ export type CreateMessageInput = Omit<
 	movedByRemit?: MessageItem["movedByRemit"];
 };
 
+/**
+ * Everything about a message that is not its placement.
+ *
+ * The six placement fields are omitted rather than merely discouraged
+ * (docs/architecture/imap-mutations.md R3): where they are gone from the only
+ * general-purpose writer, a placement written without a predicate is a type
+ * error rather than a convention someone has to remember. `transitionPlacement`
+ * and the settle in `updateUid` are the two doors, and they are the whole set.
+ */
 export type UpdateMessageInput = Partial<
-	Omit<CreateMessageInput, "mailboxId" | "uid">
->;
-
-export type UpdateMessageMoveInput = Partial<
-	Pick<
+	Omit<
 		CreateMessageInput,
 		| "mailboxId"
 		| "uid"
 		| "status"
 		| "syncStatus"
+		| "abandonedMutation"
 		| "originalMailboxId"
 		| "originalUid"
 	>
 >;
 
+/**
+ * The placement a transition expects to find, as the caller read it
+ * (docs/architecture/imap-mutations.md R3). Every field named here becomes a
+ * term of the UPDATE's WHERE clause; what the caller did not read, it does not
+ * supply. `syncStatus` takes a set because several of the six placement states
+ * share one `status`.
+ */
+export type PlacementPredicate = {
+	status?: MessageItem["status"] | readonly MessageItem["status"][];
+	syncStatus?: MessageItem["syncStatus"] | readonly MessageItem["syncStatus"][];
+	mailboxId?: string;
+	uid?: number;
+};
+
+/**
+ * What a winning transition writes. `originalMailboxId` and `originalUid` take
+ * `null` to clear, which is how a settle spells a dropped pre-move pair.
+ */
+export type PlacementTransitionInput = {
+	status?: MessageItem["status"];
+	syncStatus?: MessageItem["syncStatus"];
+	abandonedMutation?: MessageItem["abandonedMutation"];
+	mailboxId?: string;
+	uid?: number;
+	originalMailboxId?: string | null;
+	originalUid?: number | null;
+};
+
 export type MessageIdSource = {
 	messageId?: string;
 	uid: number;