@remit/drizzle-service 0.0.1

package/src/repos/i4-mailbox-lock.test.ts

@@ -0,0 +1,368 @@
+import assert from "node:assert";
+import { after, before, describe, test } from "node:test";
+import { mailboxLockTable } from "../schema/i4-mailbox-lock.js";
+import { createTestDb, randomId, type TestDb } from "../test-db.js";
+import { MailboxLockRepo } from "./i4-mailbox-lock.js";
+
+describe("MailboxLockRepo", () => {
+	let db: TestDb;
+	let close: () => Promise<void>;
+	let repo: MailboxLockRepo;
+
+	async function seedExpiredLock(input: {
+		mailboxId: string;
+		eventName: string;
+		accountId: string;
+		lockId: string;
+	}): Promise<void> {
+		await db.insert(mailboxLockTable).values({
+			...input,
+			lockedBy: input.eventName,
+			acquiredAt: Date.now() - 3_600_000,
+			ttl: Math.floor(Date.now() / 1000) - 60,
+		});
+	}
+
+	before(async () => {
+		({ db, close } = await createTestDb());
+		repo = new MailboxLockRepo(db as never);
+	});
+
+	after(async () => {
+		await close();
+	});
+
+	test("tryAcquireLock acquires lock when none exists", async () => {
+		const mailboxId = randomId();
+		const accountId = randomId();
+		const lockId = randomId();
+		const eventName = "SYNC_MESSAGES";
+
+		const acquired = await repo.tryAcquireLock(
+			mailboxId,
+			eventName,
+			accountId,
+			lockId,
+		);
+		assert.equal(acquired, true, "should acquire lock");
+
+		const lock = await repo.get(accountId, mailboxId, eventName);
+		assert.ok(lock, "lock should exist");
+		assert.equal(lock.mailboxId, mailboxId);
+		assert.equal(lock.eventName, eventName);
+		assert.equal(lock.accountId, accountId);
+		assert.equal(lock.lockId, lockId);
+		assert.ok(lock.acquiredAt > 0);
+		assert.ok(lock.ttl > 0);
+
+		// cleanup
+		await repo.releaseLock(accountId, mailboxId, eventName, lockId);
+	});
+
+	test("tryAcquireLock fails (returns false) when lock already held", async () => {
+		const mailboxId = randomId();
+		const accountId = randomId();
+		const lockId1 = randomId();
+		const lockId2 = randomId();
+		const eventName = "SYNC_MESSAGES";
+
+		const first = await repo.tryAcquireLock(
+			mailboxId,
+			eventName,
+			accountId,
+			lockId1,
+		);
+		assert.equal(first, true, "first acquire should succeed");
+
+		const second = await repo.tryAcquireLock(
+			mailboxId,
+			eventName,
+			accountId,
+			lockId2,
+		);
+		assert.equal(second, false, "second acquire should fail");
+
+		await repo.releaseLock(accountId, mailboxId, eventName, lockId1);
+	});
+
+	test("tryAcquireLock steals an expired lock", async () => {
+		const mailboxId = randomId();
+		const accountId = randomId();
+		const staleLockId = randomId();
+		const freshLockId = randomId();
+		const eventName = "SYNC_MESSAGES";
+
+		await seedExpiredLock({
+			mailboxId,
+			eventName,
+			accountId,
+			lockId: staleLockId,
+		});
+
+		const acquired = await repo.tryAcquireLock(
+			mailboxId,
+			eventName,
+			accountId,
+			freshLockId,
+		);
+		assert.equal(acquired, true, "should steal the expired lock");
+
+		const lock = await repo.get(accountId, mailboxId, eventName);
+		assert.ok(lock, "lock should exist");
+		assert.equal(
+			lock.lockId,
+			freshLockId,
+			"lock should be owned by new holder",
+		);
+		assert.ok(
+			lock.ttl > Math.floor(Date.now() / 1000),
+			"ttl should be renewed",
+		);
+
+		await repo.releaseLock(accountId, mailboxId, eventName, freshLockId);
+	});
+
+	test("tryAcquireLock refuses to steal a live lock", async () => {
+		const mailboxId = randomId();
+		const accountId = randomId();
+		const liveLockId = randomId();
+		const contenderLockId = randomId();
+		const eventName = "SYNC_MESSAGES";
+
+		await repo.tryAcquireLock(mailboxId, eventName, accountId, liveLockId);
+
+		const acquired = await repo.tryAcquireLock(
+			mailboxId,
+			eventName,
+			accountId,
+			contenderLockId,
+		);
+		assert.equal(acquired, false, "should not steal a live lock");
+
+		const lock = await repo.get(accountId, mailboxId, eventName);
+		assert.ok(lock, "lock should still exist");
+		assert.equal(
+			lock.lockId,
+			liveLockId,
+			"live lock owner should be unchanged",
+		);
+
+		await repo.releaseLock(accountId, mailboxId, eventName, liveLockId);
+	});
+
+	test("only one contender wins when stealing the same expired lock", async () => {
+		const mailboxId = randomId();
+		const accountId = randomId();
+		const staleLockId = randomId();
+		const contenderA = randomId();
+		const contenderB = randomId();
+		const eventName = "SYNC_MESSAGES";
+
+		await seedExpiredLock({
+			mailboxId,
+			eventName,
+			accountId,
+			lockId: staleLockId,
+		});
+
+		const results = await Promise.all([
+			repo.tryAcquireLock(mailboxId, eventName, accountId, contenderA),
+			repo.tryAcquireLock(mailboxId, eventName, accountId, contenderB),
+		]);
+
+		assert.equal(
+			results.filter(Boolean).length,
+			1,
+			"exactly one contender should win",
+		);
+
+		const lock = await repo.get(accountId, mailboxId, eventName);
+		assert.ok(lock);
+		await repo.releaseLock(accountId, mailboxId, eventName, lock.lockId);
+	});
+
+	test("releaseLock removes the lock when lockId matches", async () => {
+		const mailboxId = randomId();
+		const accountId = randomId();
+		const lockId = randomId();
+		const eventName = "SYNC_MESSAGES";
+
+		await repo.tryAcquireLock(mailboxId, eventName, accountId, lockId);
+		await repo.releaseLock(accountId, mailboxId, eventName, lockId);
+
+		const lock = await repo.get(accountId, mailboxId, eventName);
+		assert.equal(lock, null, "lock should be released");
+	});
+
+	test("releaseLock is a no-op when lockId does not match", async () => {
+		const mailboxId = randomId();
+		const accountId = randomId();
+		const lockId1 = randomId();
+		const lockId2 = randomId();
+		const eventName = "SYNC_MESSAGES";
+
+		await repo.tryAcquireLock(mailboxId, eventName, accountId, lockId1);
+		await repo.releaseLock(accountId, mailboxId, eventName, lockId2); // wrong lockId
+
+		const lock = await repo.get(accountId, mailboxId, eventName);
+		assert.ok(lock, "lock should still exist");
+		assert.equal(lock.lockId, lockId1);
+
+		await repo.releaseLock(accountId, mailboxId, eventName, lockId1);
+	});
+
+	test("withMailboxLock executes and releases", async () => {
+		const mailboxId = randomId();
+		const accountId = randomId();
+		const eventName = "SYNC_MESSAGES";
+
+		let ran = false;
+		const result = await repo.withMailboxLock(
+			mailboxId,
+			eventName,
+			accountId,
+			async () => {
+				ran = true;
+				return "done";
+			},
+		);
+
+		assert.equal(result.executed, true);
+		assert.equal(result.result, "done");
+		assert.equal(ran, true);
+
+		const lock = await repo.get(accountId, mailboxId, eventName);
+		assert.equal(lock, null, "lock released after operation");
+	});
+
+	test("withMailboxLock skips when lock already held", async () => {
+		const mailboxId = randomId();
+		const accountId = randomId();
+		const lockId = randomId();
+		const eventName = "SYNC_MESSAGES";
+
+		await repo.tryAcquireLock(mailboxId, eventName, accountId, lockId);
+
+		const result = await repo.withMailboxLock(
+			mailboxId,
+			eventName,
+			accountId,
+			async () => "should not run",
+		);
+
+		assert.equal(result.executed, false);
+
+		await repo.releaseLock(accountId, mailboxId, eventName, lockId);
+	});
+
+	test("withMailboxLock releases even if operation throws", async () => {
+		const mailboxId = randomId();
+		const accountId = randomId();
+		const eventName = "SYNC_MESSAGES";
+
+		await assert.rejects(
+			repo.withMailboxLock(mailboxId, eventName, accountId, async () => {
+				throw new Error("boom");
+			}),
+			/boom/,
+		);
+
+		const lock = await repo.get(accountId, mailboxId, eventName);
+		assert.equal(lock, null, "lock released after throw");
+	});
+
+	test("get returns null when no lock exists", async () => {
+		const lock = await repo.get(randomId(), randomId(), "SYNC_MESSAGES");
+		assert.equal(lock, null);
+	});
+
+	test("different eventNames create separate locks", async () => {
+		const mailboxId = randomId();
+		const accountId = randomId();
+		const lockId1 = randomId();
+		const lockId2 = randomId();
+
+		const a1 = await repo.tryAcquireLock(
+			mailboxId,
+			"SYNC_MESSAGES",
+			accountId,
+			lockId1,
+		);
+		const a2 = await repo.tryAcquireLock(
+			mailboxId,
+			"SYNC_FLAGS",
+			accountId,
+			lockId2,
+		);
+
+		assert.equal(a1, true);
+		assert.equal(a2, true);
+
+		await repo.releaseLock(accountId, mailboxId, "SYNC_MESSAGES", lockId1);
+		await repo.releaseLock(accountId, mailboxId, "SYNC_FLAGS", lockId2);
+	});
+
+	test("listByAccount returns locks for that account only", async () => {
+		const mailboxId1 = randomId();
+		const mailboxId2 = randomId();
+		const accountId1 = randomId();
+		const accountId2 = randomId();
+		const lockId1 = randomId();
+		const lockId2 = randomId();
+		const eventName = "SYNC_MESSAGES";
+
+		await repo.tryAcquireLock(mailboxId1, eventName, accountId1, lockId1);
+		await repo.tryAcquireLock(mailboxId2, eventName, accountId2, lockId2);
+
+		const locks = await repo.listByAccount(accountId1);
+		assert.equal(locks.filter((l) => l.lockId === lockId1).length, 1);
+		assert.equal(locks.filter((l) => l.lockId === lockId2).length, 0);
+
+		await repo.releaseLock(accountId1, mailboxId1, eventName, lockId1);
+		await repo.releaseLock(accountId2, mailboxId2, eventName, lockId2);
+	});
+
+	test("deleteByAccount removes all locks for that account", async () => {
+		const accountId = randomId();
+		const lockId1 = randomId();
+		const lockId2 = randomId();
+		const mb1 = randomId();
+		const mb2 = randomId();
+
+		await repo.tryAcquireLock(mb1, "SYNC_MESSAGES", accountId, lockId1);
+		await repo.tryAcquireLock(mb2, "SYNC_FLAGS", accountId, lockId2);
+
+		await repo.deleteByAccount(accountId);
+
+		const locks = await repo.listByAccount(accountId);
+		assert.equal(locks.length, 0);
+	});
+
+	test("get is scoped to accountId (foreign account sees nothing)", async () => {
+		const accountId = randomId();
+		const other = randomId();
+		const mailboxId = randomId();
+		const lockId = randomId();
+		await repo.tryAcquireLock(mailboxId, "SYNC_MESSAGES", accountId, lockId);
+
+		assert.ok(await repo.get(accountId, mailboxId, "SYNC_MESSAGES"));
+		assert.equal(await repo.get(other, mailboxId, "SYNC_MESSAGES"), null);
+
+		await repo.releaseLock(accountId, mailboxId, "SYNC_MESSAGES", lockId);
+	});
+
+	test("releaseLock does not release another account's lock", async () => {
+		const accountId = randomId();
+		const other = randomId();
+		const mailboxId = randomId();
+		const lockId = randomId();
+		await repo.tryAcquireLock(mailboxId, "SYNC_MESSAGES", accountId, lockId);
+
+		// Foreign account with the (leaked) lockId still cannot release it.
+		await repo.releaseLock(other, mailboxId, "SYNC_MESSAGES", lockId);
+		assert.ok(await repo.get(accountId, mailboxId, "SYNC_MESSAGES"));
+
+		await repo.releaseLock(accountId, mailboxId, "SYNC_MESSAGES", lockId);
+		assert.equal(await repo.get(accountId, mailboxId, "SYNC_MESSAGES"), null);
+	});
+});

package/src/repos/i4-mailbox-lock.ts

@@ -0,0 +1,140 @@
+import type {
+	IMailboxLockRepository,
+	MailboxLockItem,
+	WithMailboxLockResult,
+} from "@remit/data-ports";
+import { and, eq, lt } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { randomId } from "../id.js";
+import { mailboxLockTable } from "../schema/i4-mailbox-lock.js";
+
+type DB = NodePgDatabase<Record<string, unknown>>;
+
+const TTL_SECONDS = 3600;
+
+function rowToItem(row: typeof mailboxLockTable.$inferSelect): MailboxLockItem {
+	return {
+		mailboxId: row.mailboxId,
+		eventName: row.eventName,
+		accountId: row.accountId,
+		lockId: row.lockId,
+		acquiredAt: row.acquiredAt,
+		lockedBy: row.lockedBy,
+		ttl: row.ttl,
+	};
+}
+
+export class MailboxLockRepo implements IMailboxLockRepository {
+	constructor(private db: DB) {}
+
+	async tryAcquireLock(
+		mailboxId: string,
+		eventName: string,
+		accountId: string,
+		lockId: string,
+	): Promise<boolean> {
+		const now = Date.now();
+		const nowSeconds = Math.floor(now / 1000);
+		const ttl = nowSeconds + TTL_SECONDS;
+
+		const rows = await this.db
+			.insert(mailboxLockTable)
+			.values({
+				mailboxId,
+				eventName,
+				accountId,
+				lockId,
+				acquiredAt: now,
+				lockedBy: eventName,
+				ttl,
+			})
+			.onConflictDoUpdate({
+				target: [mailboxLockTable.mailboxId, mailboxLockTable.eventName],
+				set: { accountId, lockId, acquiredAt: now, lockedBy: eventName, ttl },
+				setWhere: lt(mailboxLockTable.ttl, nowSeconds),
+			})
+			.returning();
+
+		return rows.length > 0;
+	}
+
+	async releaseLock(
+		accountId: string,
+		mailboxId: string,
+		eventName: string,
+		lockId: string,
+	): Promise<void> {
+		await this.db
+			.delete(mailboxLockTable)
+			.where(
+				and(
+					eq(mailboxLockTable.accountId, accountId),
+					eq(mailboxLockTable.mailboxId, mailboxId),
+					eq(mailboxLockTable.eventName, eventName),
+					eq(mailboxLockTable.lockId, lockId),
+				),
+			);
+	}
+
+	async withMailboxLock<T>(
+		mailboxId: string,
+		eventName: string,
+		accountId: string,
+		operation: () => Promise<T>,
+		options?: { lockId?: string },
+	): Promise<WithMailboxLockResult<T>> {
+		const lockId = options?.lockId ?? randomId();
+
+		const acquired = await this.tryAcquireLock(
+			mailboxId,
+			eventName,
+			accountId,
+			lockId,
+		);
+		if (!acquired) return { executed: false };
+
+		return operation()
+			.then((result) => ({ executed: true as const, result }))
+			.finally(() => this.releaseLock(accountId, mailboxId, eventName, lockId));
+	}
+
+	async get(
+		accountId: string,
+		mailboxId: string,
+		eventName: string,
+	): Promise<MailboxLockItem | null> {
+		const [row] = await this.db
+			.select()
+			.from(mailboxLockTable)
+			.where(
+				and(
+					eq(mailboxLockTable.accountId, accountId),
+					eq(mailboxLockTable.mailboxId, mailboxId),
+					eq(mailboxLockTable.eventName, eventName),
+				),
+			);
+		return row ? rowToItem(row) : null;
+	}
+
+	async listAllLocks(): Promise<MailboxLockItem[]> {
+		const rows = await this.db
+			.select()
+			.from(mailboxLockTable)
+			.orderBy(mailboxLockTable.acquiredAt);
+		return rows.map(rowToItem);
+	}
+
+	async listByAccount(accountId: string): Promise<MailboxLockItem[]> {
+		const rows = await this.db
+			.select()
+			.from(mailboxLockTable)
+			.where(eq(mailboxLockTable.accountId, accountId));
+		return rows.map(rowToItem);
+	}
+
+	async deleteByAccount(accountId: string): Promise<void> {
+		await this.db
+			.delete(mailboxLockTable)
+			.where(eq(mailboxLockTable.accountId, accountId));
+	}
+}

package/src/repos/i4-mailbox-special-use.ts

@@ -0,0 +1,165 @@
+import type {
+	IMailboxSpecialUseRepository,
+	MailboxSpecialUseItem,
+	MailboxSpecialUseValue,
+} from "@remit/data-ports";
+import { eq } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { randomId } from "../id.js";
+import { mailboxSpecialUseTable, mailboxTable } from "../schema/i4-mailbox.js";
+
+type DB = NodePgDatabase<Record<string, unknown>>;
+
+function rowToSpecialUse(
+	row: typeof mailboxSpecialUseTable.$inferSelect,
+): MailboxSpecialUseItem {
+	return {
+		mailboxSpecialUseId: row.mailboxSpecialUseId,
+		mailboxId: row.mailboxId,
+		specialUse: row.specialUse as MailboxSpecialUseValue,
+	};
+}
+
+export class MailboxSpecialUseRepo implements IMailboxSpecialUseRepository {
+	constructor(private db: DB) {}
+
+	async create(
+		mailboxId: string,
+		specialUse: MailboxSpecialUseValue,
+	): Promise<MailboxSpecialUseItem> {
+		const [row] = await this.db
+			.insert(mailboxSpecialUseTable)
+			.values({
+				mailboxSpecialUseId: randomId(),
+				mailboxId,
+				specialUse,
+			})
+			.returning();
+		return rowToSpecialUse(row);
+	}
+
+	async createMany(
+		mailboxId: string,
+		specialUses: MailboxSpecialUseValue[],
+	): Promise<MailboxSpecialUseItem[]> {
+		if (specialUses.length === 0) return [];
+		const values = specialUses.map((specialUse) => ({
+			mailboxSpecialUseId: randomId(),
+			mailboxId,
+			specialUse,
+		}));
+		const rows = await this.db
+			.insert(mailboxSpecialUseTable)
+			.values(values)
+			.returning();
+		return rows.map(rowToSpecialUse);
+	}
+
+	async listByMailboxId(mailboxId: string): Promise<MailboxSpecialUseItem[]> {
+		const rows = await this.db
+			.select()
+			.from(mailboxSpecialUseTable)
+			.where(eq(mailboxSpecialUseTable.mailboxId, mailboxId));
+		return rows.map(rowToSpecialUse);
+	}
+
+	async deleteByMailboxId(mailboxId: string): Promise<number> {
+		const existing = await this.listByMailboxId(mailboxId);
+		if (existing.length === 0) return 0;
+		await this.db
+			.delete(mailboxSpecialUseTable)
+			.where(eq(mailboxSpecialUseTable.mailboxId, mailboxId));
+		return existing.length;
+	}
+
+	async findBySpecialUse(
+		accountId: string,
+		specialUse: MailboxSpecialUseValue,
+	): Promise<{ mailboxId: string; fullPath: string } | null> {
+		const mailboxes = await this.db
+			.select()
+			.from(mailboxTable)
+			.where(eq(mailboxTable.accountId, accountId));
+
+		for (const mailbox of mailboxes) {
+			const entries = await this.listByMailboxId(mailbox.mailboxId);
+			if (entries.some((e) => e.specialUse === specialUse)) {
+				return { mailboxId: mailbox.mailboxId, fullPath: mailbox.fullPath };
+			}
+		}
+		return null;
+	}
+
+	async findInboxMailbox(
+		accountId: string,
+	): Promise<{ mailboxId: string; fullPath: string } | null> {
+		const rows = await this.db
+			.select()
+			.from(mailboxTable)
+			.where(eq(mailboxTable.accountId, accountId));
+		const found = rows.find((r) => r.fullPath.toUpperCase() === "INBOX");
+		return found
+			? { mailboxId: found.mailboxId, fullPath: found.fullPath }
+			: null;
+	}
+
+	async findTrashMailbox(
+		accountId: string,
+	): Promise<{ mailboxId: string; fullPath: string } | null> {
+		const bySpecialUse = await this.findBySpecialUse(accountId, "Trash");
+		if (bySpecialUse) return bySpecialUse;
+
+		const rows = await this.db
+			.select()
+			.from(mailboxTable)
+			.where(eq(mailboxTable.accountId, accountId));
+
+		const names = [
+			"trash",
+			"deleted items",
+			"deleted",
+			"[gmail]/trash",
+			"[gmail]/bin",
+		];
+		const found = rows.find((r) => names.includes(r.fullPath.toLowerCase()));
+		return found
+			? { mailboxId: found.mailboxId, fullPath: found.fullPath }
+			: null;
+	}
+
+	async findArchiveMailbox(
+		accountId: string,
+	): Promise<{ mailboxId: string; fullPath: string } | null> {
+		const bySpecialUse = await this.findBySpecialUse(accountId, "Archive");
+		if (bySpecialUse) return bySpecialUse;
+
+		const rows = await this.db
+			.select()
+			.from(mailboxTable)
+			.where(eq(mailboxTable.accountId, accountId));
+
+		const names = ["archive", "archives", "[gmail]/all mail"];
+		const found = rows.find((r) => names.includes(r.fullPath.toLowerCase()));
+		return found
+			? { mailboxId: found.mailboxId, fullPath: found.fullPath }
+			: null;
+	}
+
+	async findJunkMailbox(
+		accountId: string,
+	): Promise<{ mailboxId: string; fullPath: string } | null> {
+		const bySpecialUse = await this.findBySpecialUse(accountId, "Junk");
+		if (bySpecialUse) return bySpecialUse;
+
+		const rows = await this.db
+			.select()
+			.from(mailboxTable)
+			.where(eq(mailboxTable.accountId, accountId));
+
+		const names = ["junk", "spam", "bulk mail", "junk e-mail", "[gmail]/spam"];
+		const found = rows.find((r) => names.includes(r.fullPath.toLowerCase()));
+		return found
+			? { mailboxId: found.mailboxId, fullPath: found.fullPath }
+			: null;
+	}
+}