@remit/backend 0.0.143 → 0.0.145

package/src/handlers/system-update.ts

@@ -1,230 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { readFileSync, renameSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import type {
-	SystemUpdateResponse,
-	SystemUpdateRun,
-} from "@remit/api-openapi-types";
-import { ConflictError, HTTPError } from "@remit/data-ports/errors";
-import type { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";
-import type { Context } from "openapi-backend";
-import { getSubFromEvent } from "../auth.js";
-import { defaultErrorCode } from "../error.js";
-import type { OperationHandler, SystemOperationIds } from "../types.js";
-
-class TargetVersionMismatchError extends HTTPError {
-	name = "TargetVersionMismatchError";
-	statusCode = 422;
-}
-
-const DEFAULT_CONTROL_DIR = "/data/control";
-
-const controlDir = (): string =>
-	process.env.REMIT_UPDATE_CONTROL_DIR ?? DEFAULT_CONTROL_DIR;
-
-const manifestUrl = (): string | undefined =>
-	process.env.REMIT_UPDATE_MANIFEST_URL;
-
-/**
- * The running version is a fact the updater owns: it reads the tag from `.env`
- * and writes it into `state.json`, which is the only honest source across an
- * update that rewrites that tag underneath a long-lived backend process. When no
- * state file exists yet the backend has nothing authoritative to report, so it
- * reports the version as unknown rather than fabricating one from its own
- * process environment — a value captured at container start that drifts from the
- * real running tag the moment an update lands. The first updater check writes a
- * real `currentVersion` within seconds of the stack coming up.
- */
-const UNKNOWN_VERSION = "unknown";
-
-/**
- * A refusal in the shape `formatResponse` unwraps: the status, and the body as
- * an object it serializes. Handing it an already-serialized `body` string
- * instead publishes the whole envelope — `{"statusCode":…,"headers":…}` with
- * the real body escaped inside it — which is not an `ApiError` at all.
- */
-const refuse = (statusCode: number, message: string): APIGatewayProxyResult =>
-	({
-		statusCode,
-		body: { code: defaultErrorCode(statusCode), message },
-	}) as unknown as APIGatewayProxyResult;
-
-const notFound = (): APIGatewayProxyResult => refuse(404, "Not found");
-
-const unauthorized = (): APIGatewayProxyResult => refuse(401, "Unauthorized");
-
-/**
- * The self-update seam is off unless a manifest URL is configured (RFC 037 D8),
- * which the hosted deployment leaves unset. Both endpoints answer 404 in that
- * case. Where it is on, any authenticated caller may use it — the account list
- * is the trust boundary of a self-hosted instance.
- */
-const guardManifestConfigured = (): APIGatewayProxyResult | null =>
-	manifestUrl() ? null : notFound();
-
-/**
- * Read `state.json` off the control volume. A missing file is an instance that
- * has never checked or updated (RFC 037 D8), not an error, so it reads as
- * `null`; the caller renders the disabled/empty resource. Any other read or
- * parse failure propagates.
- */
-const readState = (): SystemUpdateResponse | null => {
-	let raw: string;
-	try {
-		raw = readFileSync(join(controlDir(), "state.json"), "utf8");
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
-		throw error;
-	}
-	return JSON.parse(raw) as SystemUpdateResponse;
-};
-
-const emptyResource = (): SystemUpdateResponse => ({
-	currentVersion: UNKNOWN_VERSION,
-	check: { status: "disabled" },
-	run: null,
-});
-
-const isRunInFlight = (run: SystemUpdateRun | null | undefined): boolean =>
-	run != null && run.outcome === null;
-
-/**
- * The version the caller may install is the one the last check reported. It
- * exists only on a successful check; a disabled or failed check offers nothing
- * to match, so any target is a mismatch.
- */
-const checkedVersion = (
-	state: SystemUpdateResponse | null,
-): string | undefined =>
-	state?.check.status === "ok" ? state.check.latestVersion : undefined;
-
-/**
- * Write `request.json` atomically with exactly the four fields the seam accepts
- * (#133). The updater resolves the registry and every image reference from the
- * manifest it fetches itself; a request naming any of those is rejected whole,
- * so the backend never writes one. The temp file sits in the same directory as
- * the target for the rename to be atomic on one filesystem.
- */
-const writeRequest = (request: {
-	runId: string;
-	targetVersion: string;
-	requestedAt: string;
-	requestedBy: string;
-}): void => {
-	const dir = controlDir();
-	const tmp = join(dir, `.request.json.${request.runId}.tmp`);
-	writeFileSync(tmp, JSON.stringify(request), { mode: 0o644 });
-	renameSync(tmp, join(dir, "request.json"));
-};
-
-/**
- * Record a check request on the control seam (#599). The updater consumes it on
- * its watch loop and runs a manifest check immediately, so a press of check in
- * the panel — not just the updater's own cadence — moves `lastCheckedAt`. Like
- * request.json it is written atomically and carries no authority: its presence
- * is the whole message, so it is empty.
- */
-const writeCheckRequest = (): void => {
-	const dir = controlDir();
-	const tmp = join(dir, `.check-request.json.tmp`);
-	writeFileSync(tmp, JSON.stringify({}), { mode: 0o644 });
-	renameSync(tmp, join(dir, "check-request.json"));
-};
-
-/**
- * The resource returned by the POST. The updater has not yet written the
- * authoritative run — it polls the seam — so this bootstraps the run block with
- * the id just requested and the first phase, giving the client a `runId` to poll
- * for (RFC 037 D9). The updater's own `state.json` supersedes it on the next
- * read.
- */
-const requestedResource = (
-	state: SystemUpdateResponse | null,
-	runId: string,
-	targetVersion: string,
-	requestedAt: string,
-): SystemUpdateResponse => {
-	const from = state?.currentVersion ?? UNKNOWN_VERSION;
-	return {
-		currentVersion: from,
-		check: state?.check ?? { status: "disabled" },
-		run: {
-			runId,
-			fromVersion: from,
-			targetVersion,
-			phase: "checking",
-			outcome: null,
-			startedAt: requestedAt,
-			updatedAt: requestedAt,
-			message: "The update has been requested.",
-			logCommand: "remit logs updater",
-		},
-	};
-};
-
-export const SystemOperations: Record<
-	SystemOperationIds,
-	OperationHandler<SystemOperationIds>
-> = {
-	SystemOperations_getSystemUpdate: async (
-		context: Context,
-		...args: unknown[]
-	): Promise<SystemUpdateResponse | APIGatewayProxyResult> => {
-		const offSurface = guardManifestConfigured();
-		if (offSurface) return offSurface;
-
-		const event = args[0] as APIGatewayProxyEvent;
-		if (!getSubFromEvent(event)) return unauthorized();
-
-		// A refresh asks for a fresh answer, and only the updater can fetch one, so
-		// the request goes on the control seam for its watch loop to pick up (#599).
-		// The answer is the stored state as it stands, `lastCheckedAt` included: the
-		// caller holds its own press and watches that timestamp move, so the
-		// response never has to claim a verdict the updater has not reached.
-		const { refresh } = context.request.query as { refresh?: boolean };
-		if (refresh === true) writeCheckRequest();
-
-		return readState() ?? emptyResource();
-	},
-
-	SystemOperations_applySystemUpdate: async (
-		context: Context,
-		...args: unknown[]
-	): Promise<SystemUpdateResponse | APIGatewayProxyResult> => {
-		const offSurface = guardManifestConfigured();
-		if (offSurface) return offSurface;
-
-		const event = args[0] as APIGatewayProxyEvent;
-		const sub = getSubFromEvent(event);
-		if (!sub) return unauthorized();
-
-		const { targetVersion } = context.request.requestBody as {
-			targetVersion: string;
-		};
-		const state = readState();
-
-		if (isRunInFlight(state?.run)) {
-			throw new ConflictError("An update is already in progress.");
-		}
-
-		if (targetVersion !== checkedVersion(state)) {
-			throw new TargetVersionMismatchError(
-				"targetVersion does not match the latest checked release.",
-			);
-		}
-
-		const runId = randomUUID();
-		const requestedAt = new Date().toISOString();
-		writeRequest({
-			runId,
-			targetVersion,
-			requestedAt,
-			requestedBy: sub,
-		});
-
-		return {
-			statusCode: 202,
-			body: requestedResource(state, runId, targetVersion, requestedAt),
-		} as unknown as APIGatewayProxyResult;
-	},
-};

package/src/handlers/thread.test.ts

@@ -1,396 +0,0 @@
-import assert from "node:assert/strict";
-import { describe, it } from "node:test";
-import type { ThreadMessageItem } from "@remit/data-ports";
-import { MessageCategory, SenderTrust, StarColor } from "@remit/domain-enums";
-import {
-	buildListThreadMessagesOptions,
-	buildListThreadsOptions,
-	buildSearchThreadsOptions,
-	dedupeThreadMessages,
-	executeThreadSearch,
-	type ThreadSearchClient,
-} from "./thread.js";
-
-const ACCOUNT = "cfg-1";
-const MAILBOX = "mbx-inbox";
-
-type Row = {
-	threadMessageId: string;
-	messageIdHeader?: string;
-	createdAt: number;
-};
-
-const row = (
-	threadMessageId: string,
-	messageIdHeader: string | undefined,
-	createdAt: number,
-): Row => ({ threadMessageId, messageIdHeader, createdAt });
-
-describe("buildListThreadMessagesOptions", () => {
-	it("defaults to oldest-first and hides soft-deleted messages", () => {
-		assert.deepEqual(buildListThreadMessagesOptions({}), {
-			order: "asc",
-			excludeDeleted: true,
-		});
-	});
-
-	it("honours an explicit order", () => {
-		assert.equal(
-			buildListThreadMessagesOptions({ order: "desc" }).order,
-			"desc",
-		);
-	});
-
-	it("carries no mailbox filter, so sent messages stay in the conversation", () => {
-		assert.ok(!("mailboxId" in buildListThreadMessagesOptions({})));
-	});
-});
-
-describe("dedupeThreadMessages", () => {
-	it("keeps a thread whose messages are all distinct", () => {
-		const rows = [
-			row("tm-1", "<a@example.test>", 10),
-			row("tm-2", "<b@example.test>", 20),
-		];
-		assert.deepEqual(dedupeThreadMessages(rows), rows);
-	});
-
-	it("collapses a copied message to the original", () => {
-		const original = row("tm-1", "<a@example.test>", 10);
-		const copy = row("tm-2", "<a@example.test>", 50);
-		assert.deepEqual(dedupeThreadMessages([original, copy]), [original]);
-	});
-
-	it("keeps the same row whichever order the rows arrive in", () => {
-		const original = row("tm-1", "<a@example.test>", 10);
-		const copy = row("tm-2", "<a@example.test>", 50);
-		assert.deepEqual(dedupeThreadMessages([copy, original]), [original]);
-	});
-
-	it("breaks a createdAt tie on threadMessageId", () => {
-		const first = row("tm-a", "<a@example.test>", 10);
-		const second = row("tm-b", "<a@example.test>", 10);
-		assert.deepEqual(dedupeThreadMessages([second, first]), [first]);
-	});
-
-	it("treats headers that differ only by surrounding space as one message", () => {
-		const original = row("tm-1", "<a@example.test>", 10);
-		const copy = row("tm-2", " <a@example.test> ", 50);
-		assert.deepEqual(dedupeThreadMessages([original, copy]), [original]);
-	});
-
-	it("never merges rows without a usable header", () => {
-		const rows = [
-			row("tm-1", undefined, 10),
-			row("tm-2", undefined, 20),
-			row("tm-3", "<>", 30),
-			row("tm-4", "", 40),
-		];
-		assert.deepEqual(dedupeThreadMessages(rows), rows);
-	});
-
-	it("leaves an empty thread empty", () => {
-		assert.deepEqual(dedupeThreadMessages([]), []);
-	});
-});
-
-// #304: `category` is a column on the thread_message row, so it is a SQL
-// predicate the port applies inside its window — not a criterion resolved by
-// enriching whatever the window happened to return. These assertions are on the
-// routing, because that is what a later refactor can silently undo: the SQL
-// clause goes dead and the filter falls back to a window-sized filter with no
-// test failing.
-describe("executeThreadSearch", () => {
-	type Category = ThreadMessageItem["category"];
-
-	const threadRow = (
-		threadMessageId: string,
-		category: Category,
-	): ThreadMessageItem => ({
-		threadMessageId,
-		threadId: `t-${threadMessageId}`,
-		messageId: `m-${threadMessageId}`,
-		accountConfigId: ACCOUNT,
-		mailboxId: MAILBOX,
-		uid: 1,
-		referenceOrder: 0,
-		internalDate: 0,
-		sentDate: 0,
-		isRead: false,
-		hasAttachment: false,
-		star: StarColor.None,
-		hasStars: false,
-		isDeleted: false,
-		category,
-		createdAt: 0,
-		updatedAt: 0,
-	});
-
-	type RecordedCall = {
-		search: { category?: Category[] };
-		continuationToken?: string;
-		limit?: number;
-	};
-
-	const fakeClient = (rows: ThreadMessageItem[]) => {
-		const windowCalls: RecordedCall[] = [];
-		const countCalls: RecordedCall[] = [];
-
-		// The fake applies the category predicate itself, the way a port does, so
-		// a request that never reaches `search` cannot answer correctly by
-		// accident. The window also honours `limit`, so a handler deriving a count
-		// from the rows it got back cannot pass for one that asked the port.
-		const matching = (categories?: Category[]) =>
-			categories?.length
-				? rows.filter((row) => categories.includes(row.category))
-				: rows;
-
-		const client: ThreadSearchClient = {
-			threadMessage: {
-				async searchByMailboxWindow(_account, _mailbox, search, options) {
-					windowCalls.push({
-						search,
-						continuationToken: options?.continuationToken,
-						limit: options?.limit,
-					});
-					return {
-						items: matching(search.category).slice(0, options?.limit),
-						continuationToken: undefined,
-					};
-				},
-				async countByMailbox(_account, _mailbox, search) {
-					countCalls.push({ search });
-					return matching(search.category).length;
-				},
-			},
-			message: { get: async () => [] },
-			address: { getAddress: async () => [] },
-			messageLabel: { listByMessageIds: async () => [] },
-			label: { listByAccountConfig: async () => [] },
-		};
-
-		return { client, windowCalls, countCalls };
-	};
-
-	const ACCOUNT_ROWS = [
-		threadRow("tm-1", MessageCategory.personal),
-		threadRow("tm-2", MessageCategory.marketing),
-		threadRow("tm-3", MessageCategory.uncategorized),
-	];
-
-	it("passes category to the port's search, not to the off-row filter", async () => {
-		const { client, windowCalls } = fakeClient(ACCOUNT_ROWS);
-
-		const response = await executeThreadSearch(client, ACCOUNT, MAILBOX, {
-			category: [MessageCategory.personal],
-		});
-
-		assert.deepEqual(windowCalls.length, 1);
-		assert.deepEqual(windowCalls[0].search.category, [
-			MessageCategory.personal,
-		]);
-		assert.deepEqual(
-			response.items?.map((item) => item.threadMessageId),
-			["tm-1"],
-		);
-	});
-
-	it("takes the count-only path for a category-only query", async () => {
-		const { client, windowCalls, countCalls } = fakeClient(ACCOUNT_ROWS);
-
-		const response = await executeThreadSearch(client, ACCOUNT, MAILBOX, {
-			category: [MessageCategory.personal, MessageCategory.marketing],
-			count: true,
-			results: false,
-		});
-
-		assert.equal(windowCalls.length, 0, "no window read in count-only mode");
-		assert.equal(countCalls.length, 1);
-		assert.deepEqual(countCalls[0].search.category, [
-			MessageCategory.personal,
-			MessageCategory.marketing,
-		]);
-		assert.equal(response.count, 2);
-		assert.equal(response.items, undefined);
-	});
-
-	// The one request shape that still takes the off-row branch. `category` must
-	// reach `search` anyway, so the window is category-filtered before the
-	// enrichment the off-row criterion needs.
-	it("keeps category in search when an off-row criterion is also set", async () => {
-		const { client, windowCalls } = fakeClient(ACCOUNT_ROWS);
-
-		const response = await executeThreadSearch(client, ACCOUNT, MAILBOX, {
-			category: [MessageCategory.personal],
-			senderTrust: [SenderTrust.Unknown],
-		});
-
-		assert.equal(windowCalls.length, 1);
-		assert.deepEqual(windowCalls[0].search.category, [
-			MessageCategory.personal,
-		]);
-		assert.deepEqual(
-			response.items?.map((item) => item.threadMessageId),
-			["tm-1"],
-		);
-	});
-
-	it("serves category from the row, so it survives an absent message row", async () => {
-		const { client } = fakeClient(ACCOUNT_ROWS);
-
-		const response = await executeThreadSearch(client, ACCOUNT, MAILBOX, {});
-
-		assert.deepEqual(
-			response.items?.map((item) => item.category),
-			[
-				MessageCategory.personal,
-				MessageCategory.marketing,
-				MessageCategory.uncategorized,
-			],
-		);
-	});
-
-	// #509: `limit` is a page size. A response that carries a page of rows and a
-	// count has to state how many messages match, not how many it handed back.
-	it("counts the whole match when rows are asked for as well", async () => {
-		const pageSize = 2;
-		const matches = 4753;
-		const windowCalls: number[] = [];
-		const client: ThreadSearchClient = {
-			threadMessage: {
-				async searchByMailboxWindow(_account, _mailbox, _search, options) {
-					windowCalls.push(options?.limit ?? 0);
-					return {
-						items: ACCOUNT_ROWS.slice(0, pageSize),
-						continuationToken: "next",
-					};
-				},
-				async countByMailbox() {
-					return matches;
-				},
-			},
-			message: { get: async () => [] },
-			address: { getAddress: async () => [] },
-			messageLabel: { listByMessageIds: async () => [] },
-			label: { listByAccountConfig: async () => [] },
-		};
-
-		const response = await executeThreadSearch(client, ACCOUNT, MAILBOX, {
-			count: true,
-			limit: pageSize,
-		});
-
-		assert.deepEqual(windowCalls, [pageSize]);
-		assert.equal(response.items?.length, pageSize);
-		assert.equal(response.count, matches);
-	});
-
-	// #305: `senderTrust` and `dkimMismatch` are resolved by enriching rows, so
-	// the only number the handler could put in `count` is this page's post-filter
-	// length — a page length wearing the name of a total. Absent instead.
-	it("omits count under senderTrust rather than counting the page", async () => {
-		const { client, countCalls } = fakeClient(ACCOUNT_ROWS);
-
-		const response = await executeThreadSearch(client, ACCOUNT, MAILBOX, {
-			senderTrust: [SenderTrust.Unknown],
-			count: true,
-		});
-
-		assert.equal(response.count, undefined);
-		assert.equal(countCalls.length, 0, "nothing to count off the row");
-		assert.equal(response.items?.length, ACCOUNT_ROWS.length);
-	});
-
-	it("omits count under dkimMismatch rather than counting the page", async () => {
-		const { client } = fakeClient(ACCOUNT_ROWS);
-
-		const response = await executeThreadSearch(client, ACCOUNT, MAILBOX, {
-			dkimMismatch: true,
-			count: true,
-		});
-
-		assert.equal(response.count, undefined);
-	});
-
-	// The count it asked for cannot be answered and the rows it declined are not
-	// wanted, so there is nothing left to read.
-	it("reads nothing for a count-only request under an off-row criterion", async () => {
-		const { client, windowCalls, countCalls } = fakeClient(ACCOUNT_ROWS);
-
-		const response = await executeThreadSearch(client, ACCOUNT, MAILBOX, {
-			dkimMismatch: true,
-			count: true,
-			results: false,
-		});
-
-		assert.deepEqual(response, {});
-		assert.equal(windowCalls.length, 0);
-		assert.equal(countCalls.length, 0);
-	});
-
-	it("answers the same count whether or not rows were asked for", async () => {
-		const criteria = {
-			category: [MessageCategory.personal, MessageCategory.marketing],
-			count: true,
-		};
-		const withRows = await executeThreadSearch(
-			fakeClient(ACCOUNT_ROWS).client,
-			ACCOUNT,
-			MAILBOX,
-			criteria,
-		);
-		const countOnly = await executeThreadSearch(
-			fakeClient(ACCOUNT_ROWS).client,
-			ACCOUNT,
-			MAILBOX,
-			{ ...criteria, results: false },
-		);
-
-		assert.equal(withRows.count, 2);
-		assert.equal(countOnly.count, withRows.count);
-	});
-
-	// The page size bounds the rows; it has no say in how many messages match.
-	it("holds the count still while the page size moves", async () => {
-		const responses = [];
-		for (const limit of [1, 500]) {
-			const { client } = fakeClient(ACCOUNT_ROWS);
-			responses.push(
-				await executeThreadSearch(client, ACCOUNT, MAILBOX, {
-					count: true,
-					limit,
-				}),
-			);
-		}
-
-		assert.deepEqual(
-			responses.map((response) => response.items?.length),
-			[1, ACCOUNT_ROWS.length],
-			"the page did move",
-		);
-		assert.deepEqual(
-			responses.map((response) => response.count),
-			[ACCOUNT_ROWS.length, ACCOUNT_ROWS.length],
-		);
-	});
-
-	// The cursor never reaches the count query, so the number does not shrink as
-	// the user pages: page three claims the same total page one did.
-	it("holds the count still while the caller pages", async () => {
-		const { client, windowCalls, countCalls } = fakeClient(ACCOUNT_ROWS);
-
-		const response = await executeThreadSearch(client, ACCOUNT, MAILBOX, {
-			count: true,
-			continuationToken: "page-three",
-		});
-
-		assert.equal(windowCalls[0].continuationToken, "page-three");
-		assert.equal(countCalls.length, 1);
-		assert.equal(response.count, ACCOUNT_ROWS.length);
-	});
-
-	it("projects category, so the DynamoDB port reads it with the row", () => {
-		assert.ok(buildSearchThreadsOptions({}).attributes.includes("category"));
-		assert.ok(buildListThreadsOptions({}).attributes.includes("category"));
-	});
-});