@remit/drizzle-service 0.0.82 → 0.0.84

package/src/repos/i4-mailbox.ts

@@ -3,16 +3,32 @@ import type {
 	CreateMailboxInput,
 	IMailboxRepository,
 	MailboxItem,
+	MailboxStatePredicate,
+	MailboxSubtreeTransitionIntent,
+	MailboxTransitionIntent,
+	MailboxTransitionWrite,
 	ResultList,
 	UpdateMailboxInput,
 } from "@remit/data-ports";
-import { MailboxCursorState, MailboxSyncStatus } from "@remit/domain-enums";
-import { and, asc, eq, gt, inArray, or } from "drizzle-orm";
+import { MailboxCursorState } from "@remit/domain-enums";
+import { and, asc, eq, gt, inArray, isNull, or, type SQL } from "drizzle-orm";
 import shortUuid from "short-uuid";
 import type { Db } from "../db.js";
 import { NotFoundError } from "../error.js";
 import { decodeToken, resultList } from "../pagination.js";
-import { mailboxTable } from "../schema/i4-mailbox.js";
+import {
+	mailboxAttributeTable,
+	mailboxFlagTable,
+	mailboxSpecialUseTable,
+	mailboxTable,
+} from "../schema/i4-mailbox.js";
+import { mailboxLockTable } from "../schema/i4-mailbox-lock.js";
+import { messageFlagPushTable } from "../schema/i4-message-flag-push.js";
+import { messagePlacementMoveTable } from "../schema/i4-message-placement-move.js";
+import { messageTable } from "../schema/message-data.js";
+import { threadMessageTable } from "../schema/thread-message.js";
+import { runInTransaction } from "../tx.js";
+import { deleteMessageSubtree } from "./message.js";
 
 const base36Translator = shortUuid.createTranslator(
 	shortUuid.constants.uuid25Base36,
@@ -21,6 +37,63 @@ const generateMailboxId = () => base36Translator.fromUUID(randomUUID());
 
 type DB = Db<Record<string, unknown>>;
 
+/**
+ * Message subtrees removed per transaction by {@link MailboxRepo.deleteMailboxWithMail},
+ * matching `SUBTREE_BATCH_SIZE` in the account purge. On SQLite each batch holds
+ * the process's only write slot, so the bound is what keeps a large folder's
+ * delete from parking every other writer behind it (D8).
+ */
+const MAIL_DELETE_BATCH_SIZE = 100;
+
+/** Refuses a subtree intent from inside the transaction, so the throw is the rollback. */
+class SubtreeContested extends Error {
+	constructor() {
+		super("mailbox subtree transition contested");
+		this.name = "SubtreeContested";
+	}
+}
+
+/** The WHERE terms of a folder-state transition (folder-rename-and-delete.md D3). */
+const stateTerms = (expected: MailboxStatePredicate): SQL[] => {
+	const terms: SQL[] = [
+		inArray(mailboxTable.syncStatus, [...expected.from]),
+	] as SQL[];
+	if (expected.wherePendingPath === undefined) return terms;
+	terms.push(
+		expected.wherePendingPath === null
+			? isNull(mailboxTable.pendingPath)
+			: eq(mailboxTable.pendingPath, expected.wherePendingPath),
+	);
+	return terms;
+};
+
+/**
+ * A rename target only means something while a rename is outstanding or has
+ * just failed, so the two states that cannot carry one drop it here rather than
+ * relying on every caller to remember. That is what makes the invariant — a
+ * non-null `pendingPath` only under `pending` or `failed` — hold by
+ * construction: this is the only writer of either field, and `synced` with a
+ * target on it is the seventh combination the design calls unreachable.
+ */
+const KEEPS_A_RENAME_TARGET: readonly MailboxItem["syncStatus"][] = [
+	"pending",
+	"failed",
+];
+
+const transitionSet = (
+	to: MailboxItem["syncStatus"],
+	write: MailboxTransitionWrite | undefined,
+): Partial<typeof mailboxTable.$inferInsert> => ({
+	syncStatus: to,
+	...(write?.fullPath !== undefined ? { fullPath: write.fullPath } : {}),
+	...(KEEPS_A_RENAME_TARGET.includes(to)
+		? write?.pendingPath !== undefined
+			? { pendingPath: write.pendingPath }
+			: {}
+		: { pendingPath: null }),
+	updatedAt: Date.now(),
+});
+
 export function rowToMailbox(
 	row: typeof mailboxTable.$inferSelect,
 ): MailboxItem {
@@ -43,9 +116,9 @@ export function rowToMailbox(
 		lastMessageSyncAt: row.lastMessageSyncAt,
 		initialSyncCompletedAt: row.initialSyncCompletedAt ?? undefined,
 		parentMailboxId: row.parentMailboxId,
-		syncStatus: (row.syncStatus as MailboxItem["syncStatus"]) ?? undefined,
+		syncStatus: row.syncStatus as MailboxItem["syncStatus"],
+		...(row.pendingPath !== null ? { pendingPath: row.pendingPath } : {}),
 		cursorState: (row.cursorState as MailboxItem["cursorState"]) ?? undefined,
-		oldPath: row.oldPath ?? undefined,
 		specialUse: (row.specialUse as MailboxItem["specialUse"]) ?? undefined,
 		createdAt: row.createdAt,
 		updatedAt: row.updatedAt,
@@ -78,9 +151,11 @@ export class MailboxRepo implements IMailboxRepository {
 				lastMessageSyncAt: input.lastMessageSyncAt,
 				initialSyncCompletedAt: input.initialSyncCompletedAt,
 				parentMailboxId: input.parentMailboxId ?? "",
-				syncStatus: input.syncStatus,
+				// Total per D1: an insert that names no state is a folder the
+				// server just told us about, and a folder the server told us
+				// about is confirmed.
+				syncStatus: input.syncStatus ?? "synced",
 				cursorState: input.cursorState ?? MailboxCursorState.normal,
-				oldPath: input.oldPath,
 				specialUse: input.specialUse ?? null,
 				createdAt: now,
 				updatedAt: now,
@@ -161,16 +236,12 @@ export class MailboxRepo implements IMailboxRepository {
 			updates.initialSyncCompletedAt = input.initialSyncCompletedAt;
 		if (input.parentMailboxId !== undefined)
 			updates.parentMailboxId = input.parentMailboxId;
-		if (input.syncStatus !== undefined) updates.syncStatus = input.syncStatus;
 		if (input.cursorState !== undefined)
 			updates.cursorState = input.cursorState;
-		if (input.oldPath !== undefined) updates.oldPath = input.oldPath;
 		if (input.specialUse !== undefined) updates.specialUse = input.specialUse;
 
 		if (remove) {
 			for (const field of remove) {
-				if (field === "syncStatus") updates.syncStatus = null;
-				if (field === "oldPath") updates.oldPath = null;
 				if (field === "specialUse") updates.specialUse = null;
 			}
 		}
@@ -189,6 +260,81 @@ export class MailboxRepo implements IMailboxRepository {
 		return rowToMailbox(row);
 	}
 
+	async transition(
+		accountId: string,
+		mailboxId: string,
+		intent: MailboxTransitionIntent,
+	): Promise<MailboxItem | null> {
+		const [row] = await this.db
+			.update(mailboxTable)
+			.set(transitionSet(intent.to, intent.set))
+			.where(
+				and(
+					eq(mailboxTable.accountId, accountId),
+					eq(mailboxTable.mailboxId, mailboxId),
+					...stateTerms(intent),
+				),
+			)
+			.returning();
+		return row ? rowToMailbox(row) : null;
+	}
+
+	async transitionSubtree(
+		accountId: string,
+		mailboxId: string,
+		intent: MailboxSubtreeTransitionIntent,
+	): Promise<MailboxItem[] | null> {
+		return runInTransaction(this.db, async (tx) => {
+			const repo = new MailboxRepo(tx);
+			const root = await repo
+				.get(accountId, mailboxId)
+				.catch((error: unknown) => {
+					if (error instanceof NotFoundError) return null;
+					throw error;
+				});
+			if (!root) return null;
+
+			const subtree = [
+				root,
+				...(await repo.findByPathPrefix(
+					accountId,
+					root.fullPath,
+					root.hierarchyDelimiter,
+				)),
+			];
+
+			const written: MailboxItem[] = [];
+			for (const row of subtree) {
+				// The from-state predicate rides each UPDATE rather than a read
+				// taken before them (D3). Read-then-check-then-write is safe on
+				// SQLite only because `runInTransaction` serializes top-level
+				// writes; under Postgres READ COMMITTED a single-row transition
+				// committing in between is missed entirely.
+				const [updated] = await tx
+					.update(mailboxTable)
+					.set(transitionSet(intent.to, intent.rowSet(row)))
+					.where(
+						and(
+							eq(mailboxTable.accountId, accountId),
+							eq(mailboxTable.mailboxId, row.mailboxId),
+							inArray(mailboxTable.syncStatus, [...intent.from]),
+						),
+					)
+					.returning();
+				if (updated) written.push(rowToMailbox(updated));
+			}
+
+			// A subtree cannot be half-renamed: one row that moved out from under
+			// this call refuses the whole intent, and the throw is what rolls the
+			// rest back.
+			if (written.length !== subtree.length) throw new SubtreeContested();
+			return written;
+		}).catch((error: unknown) => {
+			if (error instanceof SubtreeContested) return null;
+			throw error;
+		});
+	}
+
 	async resolveAccountId(mailboxId: string): Promise<string | null> {
 		const [row] = await this.db
 			.select({ accountId: mailboxTable.accountId })
@@ -335,22 +481,78 @@ export class MailboxRepo implements IMailboxRepository {
 		return rows.map(rowToMailbox);
 	}
 
-	async renameChildPaths(
+	async deleteMailboxWithMail(
 		accountId: string,
-		oldPath: string,
-		newPath: string,
-		delimiter = "/",
+		mailboxId: string,
 	): Promise<void> {
-		const children = await this.findByPathPrefix(accountId, oldPath, delimiter);
-		for (const child of children) {
-			const newChildPath = child.fullPath.replace(oldPath, newPath);
-			// Mark the child pending, like the renamed parent: its new path is not
-			// on the server until MAILBOX_RENAME lands, so a reconcile running in
-			// that window must not reap it as server-deleted (#290).
-			await this.update(accountId, child.mailboxId, {
-				fullPath: newChildPath,
-				syncStatus: MailboxSyncStatus.pending,
+		// Tenant scope, and the re-entry guard in the same read: a redelivery that
+		// arrives after the final commit finds no row and has nothing left to do,
+		// exactly as `delete` no-ops. Every removal below keys on `mailboxId`
+		// alone, so this is what stops a foreign accountId reaching them.
+		const [owned] = await this.db
+			.select({ mailboxId: mailboxTable.mailboxId })
+			.from(mailboxTable)
+			.where(
+				and(
+					eq(mailboxTable.accountId, accountId),
+					eq(mailboxTable.mailboxId, mailboxId),
+				),
+			);
+		if (!owned) return;
+
+		// Ordered, batched and resumable rather than one transaction (D8). The
+		// caller keeps the row `deleting` until the last commit, so an interrupted
+		// run re-enters here and continues against whatever is left.
+		for (;;) {
+			const rows = await this.db
+				.select({ messageId: messageTable.messageId })
+				.from(messageTable)
+				.where(eq(messageTable.mailboxId, mailboxId))
+				.limit(MAIL_DELETE_BATCH_SIZE);
+			if (rows.length === 0) break;
+			const messageIds = rows.map((row) => row.messageId);
+
+			await runInTransaction(this.db, async (tx) => {
+				// The primitive the rest of the codebase deletes mail with: nine
+				// per-message child tables plus one `message.removed` outbox row
+				// each, which is what clears the search index. A bespoke table
+				// list would orphan those nine and leave deleted mail searchable.
+				await deleteMessageSubtree(tx, messageIds);
+				await tx
+					.delete(threadMessageTable)
+					.where(inArray(threadMessageTable.messageId, messageIds));
 			});
 		}
+
+		await this.db
+			.delete(mailboxSpecialUseTable)
+			.where(eq(mailboxSpecialUseTable.mailboxId, mailboxId));
+		await this.db
+			.delete(mailboxAttributeTable)
+			.where(eq(mailboxAttributeTable.mailboxId, mailboxId));
+		await this.db
+			.delete(mailboxFlagTable)
+			.where(eq(mailboxFlagTable.mailboxId, mailboxId));
+		await this.db
+			.delete(mailboxLockTable)
+			.where(eq(mailboxLockTable.mailboxId, mailboxId));
+		await this.db
+			.delete(messageFlagPushTable)
+			.where(eq(messageFlagPushTable.mailboxId, mailboxId));
+		await this.db
+			.delete(messagePlacementMoveTable)
+			.where(
+				or(
+					eq(messagePlacementMoveTable.sourceMailboxId, mailboxId),
+					eq(messagePlacementMoveTable.destinationMailboxId, mailboxId),
+				),
+			);
+
+		// `filter` also carries a mailboxId and is deliberately not in that list:
+		// D16 refuses the delete while any filter or role appointment is bound, so
+		// there is nothing to unbind, and deleting a user's filters as a side
+		// effect of a folder delete is the outcome the design rules out.
+
+		await this.delete(accountId, mailboxId);
 	}
 }

package/src/repos/search-index-shape.test.ts

@@ -0,0 +1,82 @@
+/**
+ * The guard that keeps an instance installed by an earlier build from running a
+ * predicate its index cannot answer.
+ *
+ * `CREATE VIRTUAL TABLE IF NOT EXISTS` is a no-op against an existing table, so
+ * adding an indexed column changes nothing on a database that already has the
+ * old one — and a MATCH naming that column raises rather than missing. The
+ * migrator compares the shipped shape with the installed one and rebuilds.
+ */
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { describe, test } from "node:test";
+import {
+	searchIndexColumns,
+	searchIndexShapeIsCurrent,
+} from "./search-index-shape.js";
+
+const shipped = readFileSync(
+	new URL("../../../../npm-scripts/sqlite-search-index.sql", import.meta.url),
+	"utf8",
+);
+
+const installed = (columns: string[]): string =>
+	`CREATE VIRTUAL TABLE thread_message_fts USING fts5(${columns.join(", ")}, content='thread_message', content_rowid='rowid', tokenize='trigram remove_diacritics 1')`;
+
+describe("searchIndexColumns", () => {
+	test("reads the indexed columns and leaves the options out", () => {
+		assert.deepEqual(searchIndexColumns(installed(["subject", "sender"])), [
+			"subject",
+			"sender",
+		]);
+	});
+
+	test("reads the shipped index, triggers and all", () => {
+		assert.deepEqual(searchIndexColumns(shipped), [
+			"subject",
+			"sender",
+			"body",
+		]);
+	});
+
+	test("a table that is not an fts5 index has no columns", () => {
+		assert.deepEqual(searchIndexColumns("CREATE TABLE t (a, b)"), []);
+	});
+});
+
+describe("searchIndexShapeIsCurrent", () => {
+	test("the shipped index matches itself", () => {
+		assert.equal(searchIndexShapeIsCurrent(shipped, shipped), true);
+	});
+
+	// The upgrade this exists for: an instance carrying the two-column index the
+	// previous build installed must be rebuilt, or every search raises.
+	test("an index missing an indexed column is stale", () => {
+		assert.equal(
+			searchIndexShapeIsCurrent(installed(["subject", "sender"]), shipped),
+			false,
+		);
+	});
+
+	test("an index carrying every shipped column is current", () => {
+		assert.equal(
+			searchIndexShapeIsCurrent(
+				installed(["subject", "sender", "body"]),
+				shipped,
+			),
+			true,
+		);
+	});
+
+	// An extra column indexes text nothing reads. It costs space and matches
+	// nothing wrong, so it is not a reason to drop and re-tokenize the table.
+	test("an index carrying more than the shipped columns is current", () => {
+		assert.equal(
+			searchIndexShapeIsCurrent(
+				installed(["subject", "sender", "body", "labels"]),
+				shipped,
+			),
+			true,
+		);
+	});
+});

package/src/repos/search-index-shape.ts

@@ -0,0 +1,56 @@
+/**
+ * Whether an installed FTS5 search index carries the columns the shipped one
+ * declares.
+ *
+ * `CREATE VIRTUAL TABLE IF NOT EXISTS` is a no-op against a table that already
+ * exists, so a database installed by an earlier build keeps that build's
+ * columns for good. A predicate naming a column that build never indexed does
+ * not degrade — SQLite raises, and every search on that instance fails — so the
+ * migrator compares the two shapes and rebuilds where they differ.
+ *
+ * Both sides are read from DDL rather than from a hand-kept list: the shipped
+ * side is the committed `.sql`, the installed side is what `sqlite_master`
+ * holds, and neither can drift from what is actually there.
+ */
+
+/** The text between the parentheses of a `USING fts5(...)` clause. */
+const fts5Arguments = (ddl: string): string => {
+	const clause = ddl.search(/using\s+fts5\s*\(/i);
+	if (clause === -1) return "";
+	const open = ddl.indexOf("(", clause);
+	let depth = 0;
+	for (let index = open; index < ddl.length; index++) {
+		const char = ddl[index];
+		if (char === "(") depth++;
+		if (char !== ")") continue;
+		depth--;
+		if (depth === 0) return ddl.slice(open + 1, index);
+	}
+	return "";
+};
+
+/**
+ * The indexed column names an FTS5 table declares. An argument carrying an `=`
+ * is an option (`content=`, `tokenize=`), not a column, and anything quoted or
+ * otherwise unusual is left out rather than guessed at — a name this cannot
+ * read is a name the comparison must not claim is missing.
+ */
+export const searchIndexColumns = (ddl: string): string[] =>
+	fts5Arguments(ddl)
+		.split(",")
+		.map((argument) => argument.trim())
+		.filter((argument) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(argument));
+
+/**
+ * Whether `installed` indexes every column `shipped` does. A superset passes:
+ * an extra column indexes text no predicate reads, which costs space and
+ * matches nothing wrong.
+ */
+export const searchIndexShapeIsCurrent = (
+	installed: string,
+	shipped: string,
+): boolean => {
+	const columns = new Set(searchIndexColumns(installed));
+	const expected = searchIndexColumns(shipped);
+	return expected.length > 0 && expected.every((column) => columns.has(column));
+};