@remit/drizzle-service 0.0.15 → 0.0.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/drizzle-service",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "Drizzle ORM service parameterized by dialect (Postgres / SQLite)",
   "type": "module",
   "main": "src/index.ts",

package/src/pagination.test.ts

@@ -0,0 +1,41 @@
+import assert from "node:assert/strict";
+import { describe, test } from "node:test";
+import { decodeToken, encodeToken, resultList } from "./pagination.js";
+
+describe("continuation token decoding", () => {
+	test("round-trips a minted token", () => {
+		const token = encodeToken({ createdAt: 42, accountId: "a-1" });
+		assert.deepEqual(decodeToken(token), { createdAt: 42, accountId: "a-1" });
+	});
+
+	test("decodes a standard base64 token when asked", () => {
+		const token = Buffer.from(JSON.stringify({ id: "x" })).toString("base64");
+		assert.deepEqual(decodeToken(token, "base64"), { id: "x" });
+	});
+
+	for (const [label, token] of [
+		["unparseable", "not-a-cursor"],
+		["a bare number", Buffer.from("123").toString("base64url")],
+		["a JSON array", Buffer.from("[1,2]").toString("base64url")],
+		["JSON null", Buffer.from("null").toString("base64url")],
+	] as const) {
+		test(`rejects ${label}`, () => {
+			assert.throws(
+				() => decodeToken(token),
+				(error: unknown) => {
+					assert.equal((error as { statusCode?: number }).statusCode, 400);
+					assert.equal((error as Error).name, "BadRequestError");
+					return true;
+				},
+			);
+		});
+	}
+
+	test("a full page yields a token and a short page does not", () => {
+		assert.ok(resultList([1, 2], 2, { createdAt: 1 }).continuationToken);
+		assert.equal(
+			resultList([1], 2, { createdAt: 1 }).continuationToken,
+			undefined,
+		);
+	});
+});

package/src/pagination.ts

@@ -1,19 +1,31 @@
 import type { ResultList } from "@remit/data-ports";
+import { BadRequestError } from "@remit/data-ports/errors";
 
 export function encodeToken(data: Record<string, unknown>): string {
 	return Buffer.from(JSON.stringify(data)).toString("base64url");
 }
 
+// A continuation token is opaque and server-minted: absent means "first page",
+// present means "resume here". A token that does not decode is neither, so it
+// is a malformed parameter. Reading it as "first page" answered the request
+// with page one under a fresh token, so a client that kept paging kept
+// appending the same rows with nothing signalling the failure (#136).
 export function decodeToken(
 	token: string,
-): Record<string, unknown> | undefined {
+	encoding: "base64" | "base64url" = "base64url",
+): Record<string, unknown> {
+	let parsed: unknown;
 	try {
-		return JSON.parse(
-			Buffer.from(token, "base64url").toString("utf8"),
-		) as Record<string, unknown>;
+		parsed = JSON.parse(Buffer.from(token, encoding).toString("utf8"));
 	} catch {
-		return undefined;
+		throw new BadRequestError("Invalid continuationToken");
 	}
+
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+		throw new BadRequestError("Invalid continuationToken");
+	}
+
+	return parsed as Record<string, unknown>;
 }
 
 export function resultList<T>(

package/src/repos/cascade-delete.test.ts

@@ -242,7 +242,7 @@ describe("runDrizzleCascadeDelete", () => {
 			quarantinedAt: NOW,
 			attempts: 3,
 			failureStage: "BodyParse",
-			failureCode: "UnterminatedMultipartBoundary",
+			failureCode: "UnreadableBody",
 			failureMessage: "multipart boundary was never closed",
 			workerVersion: "worker 1.0.0",
 			structure: [{ depth: 0, contentType: "multipart/mixed" }],

package/src/repos/quarantine.test.ts

@@ -1,5 +1,6 @@
 import assert from "node:assert";
 import { after, before, describe, test } from "node:test";
+import { deriveQuarantineId } from "@remit/data-ports/id";
 import { quarantineTable } from "../schema/quarantine.js";
 import { createTestDb, randomId, type TestDb } from "../test-db.js";
 import { QuarantineRepo } from "./quarantine.js";
@@ -26,7 +27,7 @@ describe("QuarantineRepo", () => {
 			quarantinedAt: now,
 			attempts: 3,
 			failureStage: "BodyParse",
-			failureCode: "UnterminatedMultipartBoundary",
+			failureCode: "UnreadableBody",
 			failureMessage: "multipart boundary was never closed",
 			workerVersion: "worker 1.0.0",
 			structure: [{ depth: 0, contentType: "multipart/mixed" }],
@@ -109,4 +110,83 @@ describe("QuarantineRepo", () => {
 		assert.equal(entry.sizeBytes, undefined);
 		assert.equal(entry.messageIdHash, undefined);
 	});
+
+	test("re-quarantining the same message rewrites one row, never adds another", async () => {
+		const accountConfigId = randomId();
+		const identity = {
+			accountConfigId,
+			accountId: randomId(),
+			mailboxId: randomId(),
+			uidValidity: 1_712_000_000,
+			uid: 40217,
+			mailboxPath: "INBOX",
+			attempts: 1,
+			failureStage: "BodyParse" as const,
+			failureCode: "UnreadableBody" as const,
+			failureMessage: "the parser said no",
+			workerVersion: "sha-abc",
+		};
+
+		await repo.upsert({ ...identity, quarantinedAt: 1_000 });
+		await repo.upsert({ ...identity, quarantinedAt: 2_000, attempts: 4 });
+
+		const entries = await repo.listByAccountConfigId(accountConfigId);
+
+		assert.equal(entries.length, 1);
+		assert.equal(entries[0].attempts, 4);
+		assert.equal(entries[0].quarantinedAt, 2_000);
+	});
+
+	test("keeps the id derived from the message, not the random column default", async () => {
+		const accountConfigId = randomId();
+		const identity = {
+			accountConfigId,
+			accountId: randomId(),
+			mailboxId: randomId(),
+			uidValidity: 1_712_000_000,
+			uid: 40217,
+			mailboxPath: "INBOX",
+			quarantinedAt: 1_000,
+			attempts: 1,
+			failureStage: "BodyParse" as const,
+			failureCode: "UnreadableBody" as const,
+			failureMessage: "the parser said no",
+			workerVersion: "sha-abc",
+		};
+
+		await repo.upsert(identity);
+		const [entry] = await repo.listByAccountConfigId(accountConfigId);
+
+		assert.equal(
+			entry.quarantineId,
+			deriveQuarantineId(
+				identity.accountId,
+				identity.mailboxId,
+				identity.uidValidity,
+				identity.uid,
+			),
+		);
+	});
+
+	test("defaults the MIME tree to empty when the message failed before its shape was read", async () => {
+		const accountConfigId = randomId();
+		await repo.upsert({
+			accountConfigId,
+			accountId: randomId(),
+			mailboxId: randomId(),
+			uidValidity: 1_712_000_000,
+			uid: 1,
+			mailboxPath: "INBOX",
+			quarantinedAt: 1_000,
+			attempts: 1,
+			failureStage: "BodyParse",
+			failureCode: "UnreadableBody",
+			failureMessage: "the parser said no",
+			workerVersion: "sha-abc",
+		});
+
+		const [entry] = await repo.listByAccountConfigId(accountConfigId);
+
+		assert.deepEqual(entry.structure, []);
+	});
 });

package/src/repos/quarantine.ts

@@ -2,7 +2,9 @@ import type {
 	IQuarantineRepository,
 	QuarantineItem,
 	QuarantineMimeNodeItem,
+	QuarantineUpsertInput,
 } from "@remit/data-ports";
+import { deriveQuarantineId } from "@remit/data-ports/id";
 import { desc, eq } from "drizzle-orm";
 import type { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { quarantineTable } from "../schema/quarantine.js";
@@ -38,8 +40,8 @@ function rowToItem(row: typeof quarantineTable.$inferSelect): QuarantineItem {
 }
 
 /**
- * Read side of the message quarantine (issue #72). The rows are written by the
- * sync worker; nothing in the API process creates or clears one.
+ * The message quarantine (issue #72). Written by the sync worker, read by the
+ * settings surface; nothing in the API process creates or clears a row.
  */
 export class QuarantineRepo implements IQuarantineRepository {
 	constructor(private db: DB) {}
@@ -54,4 +56,48 @@ export class QuarantineRepo implements IQuarantineRepository {
 			.orderBy(desc(quarantineTable.quarantinedAt));
 		return rows.map(rowToItem);
 	};
+
+	upsert = async (input: QuarantineUpsertInput): Promise<void> => {
+		const quarantineId = deriveQuarantineId(
+			input.accountId,
+			input.mailboxId,
+			input.uidValidity,
+			input.uid,
+		);
+		const now = Date.now();
+		const columns = {
+			accountConfigId: input.accountConfigId,
+			accountId: input.accountId,
+			mailboxId: input.mailboxId,
+			uidValidity: input.uidValidity,
+			uid: input.uid,
+			mailboxRole: input.mailboxRole ?? null,
+			mailboxPath: input.mailboxPath,
+			quarantinedAt: input.quarantinedAt,
+			attempts: input.attempts,
+			failureStage: input.failureStage,
+			failureCode: input.failureCode,
+			failureMessage: input.failureMessage,
+			failurePartPath: input.failurePartPath ?? null,
+			workerVersion: input.workerVersion,
+			contentType: input.contentType ?? null,
+			transferEncoding: input.transferEncoding ?? null,
+			charset: input.charset ?? null,
+			sizeBytes: input.sizeBytes ?? null,
+			structure: input.structure ?? [],
+			messageIdHash: input.messageIdHash ?? null,
+		};
+
+		// `quarantinedAt` is deliberately part of the update set: a re-quarantine
+		// is the message being set aside again, and the list is ordered by it.
+		// `createdAt` is not, so the row keeps saying when the message first
+		// failed.
+		await this.db
+			.insert(quarantineTable)
+			.values({ quarantineId, ...columns, createdAt: now, updatedAt: now })
+			.onConflictDoUpdate({
+				target: quarantineTable.quarantineId,
+				set: { ...columns, updatedAt: now },
+			});
+	};
 }

package/src/repos/thread-message.sqlite.test.ts

@@ -520,4 +520,92 @@ describe("DrizzleThreadMessageRepository (sqlite)", () => {
 			"pages do not overlap",
 		);
 	});
+
+	describe("search continuation token", () => {
+		const acct = "acct-search-cursor";
+
+		before(async () => {
+			const base = Date.now();
+			for (let i = 0; i < 4; i++) {
+				await repo.create(
+					makeInput({
+						accountConfigId: acct,
+						subject: `cursor probe ${i}`,
+						sentDate: base - i,
+						internalDate: base - i,
+					}),
+				);
+			}
+		});
+
+		test("an absent token returns the first page", async () => {
+			const page = await repo.searchByMailboxWindow(
+				acct,
+				MAILBOX,
+				{ subject: "cursor probe" },
+				{ limit: 2, order: "desc" },
+			);
+			assert.equal(page.items.length, 2);
+			assert.equal(page.items[0]?.subject, "cursor probe 0");
+			assert.ok(page.continuationToken);
+		});
+
+		test("a server-minted token returns the next page", async () => {
+			const first = await repo.searchByMailboxWindow(
+				acct,
+				MAILBOX,
+				{ subject: "cursor probe" },
+				{ limit: 2, order: "desc" },
+			);
+			const second = await repo.searchByMailboxWindow(
+				acct,
+				MAILBOX,
+				{ subject: "cursor probe" },
+				{
+					limit: 2,
+					order: "desc",
+					continuationToken: first.continuationToken,
+				},
+			);
+			assert.equal(second.items.length, 2);
+			const firstIds = new Set(first.items.map((i) => i.threadMessageId));
+			assert.ok(
+				second.items.every((i) => !firstIds.has(i.threadMessageId)),
+				"pages do not overlap",
+			);
+		});
+
+		for (const [label, token] of [
+			["an unparseable", "not-a-cursor"],
+			["a non-object", Buffer.from("123").toString("base64")],
+			["an incomplete", Buffer.from('{"s":1}').toString("base64")],
+		] as const) {
+			test(`${label} token is a validation failure`, async () => {
+				await assert.rejects(
+					() =>
+						repo.searchByMailboxWindow(
+							acct,
+							MAILBOX,
+							{ subject: "cursor probe" },
+							{ limit: 2, continuationToken: token },
+						),
+					(error: unknown) => {
+						assert.equal((error as { statusCode?: number }).statusCode, 400);
+						assert.equal((error as Error).name, "BadRequestError");
+						return true;
+					},
+				);
+			});
+		}
+
+		test("an undecodable account cursor is a validation failure", async () => {
+			await assert.rejects(
+				() => repo.listByAccount(acct, { continuationToken: "not-a-cursor" }),
+				(error: unknown) => {
+					assert.equal((error as { statusCode?: number }).statusCode, 400);
+					return true;
+				},
+			);
+		});
+	});
 });

package/src/repos/thread-message.ts

@@ -6,6 +6,7 @@ import type {
 	ThreadMessageItem,
 	UpdateThreadMessageInput,
 } from "@remit/data-ports";
+import { BadRequestError } from "@remit/data-ports/errors";
 import {
 	and,
 	asc,
@@ -23,6 +24,7 @@ import shortUuid from "short-uuid";
 import { v5 as uuidv5 } from "uuid";
 import type { Db } from "../db.js";
 import { NotFoundError } from "../error.js";
+import { decodeToken } from "../pagination.js";
 import { threadMessageTable } from "../schema/thread-message.js";
 import { fromMatch, subjectMatch } from "./thread-search-predicates.js";
 
@@ -64,12 +66,12 @@ function encodeDateCursor(sentDate: number, threadMessageId: string): string {
 	).toString("base64");
 }
 
-function decodeDateCursor(token: string): DateCursor | null {
-	try {
-		return JSON.parse(Buffer.from(token, "base64").toString()) as DateCursor;
-	} catch {
-		return null;
+function decodeDateCursor(token: string): DateCursor {
+	const decoded = decodeToken(token, "base64");
+	if (typeof decoded.s !== "number" || typeof decoded.id !== "string") {
+		throw new BadRequestError("Invalid continuationToken");
 	}
+	return { s: decoded.s, id: decoded.id };
 }
 
 function encodeAccountCursor(threadMessageId: string): string {
@@ -78,12 +80,12 @@ function encodeAccountCursor(threadMessageId: string): string {
 	);
 }
 
-function decodeAccountCursor(token: string): AccountCursor | null {
-	try {
-		return JSON.parse(Buffer.from(token, "base64").toString()) as AccountCursor;
-	} catch {
-		return null;
+function decodeAccountCursor(token: string): AccountCursor {
+	const decoded = decodeToken(token, "base64");
+	if (typeof decoded.id !== "string") {
+		throw new BadRequestError("Invalid continuationToken");
 	}
+	return { id: decoded.id };
 }
 
 // ─── Schema ──────────────────────────────────────────────────────────────────