@remit/backend 0.0.40 → 0.0.41

package/dev-server/server.ts

@@ -1,5 +1,12 @@
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import { logger } from "@remit/logger-lambda";
+import {
+	metricsContentType,
+	onScrape,
+	renderMetrics,
+	setAccountSyncAges,
+} from "@remit/logger-lambda/metrics";
 import { isStorageNotFoundError } from "@remit/storage-service";
 import type { APIGatewayProxyResult } from "aws-lambda";
 import { env } from "expect-env";
@@ -17,6 +24,7 @@ import { resolveContentPath } from "./content-path.js";
 import { parseAllowedOrigins, resolveAllowOrigin } from "./cors.js";
 import { createLambdaContext, createLambdaEvent } from "./lambda-helpers.js";
 import { checkRelationalStore } from "./relational-health.js";
+import { collectAccountSyncAges } from "./sync-age.js";
 
 const app = express();
 
@@ -137,6 +145,35 @@ app.get("/health", async (_req: Request, res: Response) => {
 	});
 });
 
+// The scrape endpoint (standalone-observability D2), on the port this server
+// already serves on and never routed through Caddy — deploy/vps/caddy/routes.caddy
+// proxies /api/*, /content/* and /health, and everything else goes to the static
+// web server, so there is no path from the public origin to this route.
+//
+// The per-account sync age is a database read, so it is collected when a scrape
+// arrives rather than tracked as syncs complete. A read that fails fails the
+// scrape: a signal that could not be evaluated must not render as a healthy
+// number. Only the self-host backends have a store to read here — the
+// AWS-local dev path composes its client from outside this module.
+if (isSelfHostBackend) {
+	onScrape(async () => {
+		const client = await getClient();
+		setAccountSyncAges(await collectAccountSyncAges(client, Date.now()));
+	});
+}
+
+app.get("/metrics", async (_req: Request, res: Response) => {
+	const body = await renderMetrics().catch((error: unknown) => {
+		logger.error({ error: String(error) }, "Metrics collection failed");
+		return null;
+	});
+	if (body === null) {
+		res.status(500).type("text/plain").send("metrics collection failed\n");
+		return;
+	}
+	res.setHeader("content-type", metricsContentType).send(body);
+});
+
 // Swagger UI exposes the full API schema, so it must never be on the public
 // surface. On the self-host backends this server is the deployed backend
 // container; gate the docs to the AWS-local dev path only. The generated

package/dev-server/sync-age.test.ts

@@ -0,0 +1,91 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { AccountItem, MailboxItem } from "@remit/data-ports";
+import { collectAccountSyncAges, type SyncAgeSource } from "./sync-age.js";
+
+const NOW = 1_700_000_000_000;
+
+const account = (overrides: Partial<AccountItem>): AccountItem =>
+	({
+		accountId: "acct-1",
+		createdAt: NOW - 600_000,
+		lastSyncAt: NOW,
+		...overrides,
+	}) as AccountItem;
+
+const mailbox = (lastMessageSyncAt: number): MailboxItem =>
+	({ mailboxId: `mbx-${lastMessageSyncAt}`, lastMessageSyncAt }) as MailboxItem;
+
+const source = (
+	accounts: AccountItem[],
+	mailboxes: Record<string, MailboxItem[]>,
+): SyncAgeSource => ({
+	account: { listAll: async () => accounts },
+	mailbox: {
+		listAllByAccount: async (accountId: string) => mailboxes[accountId] ?? [],
+	},
+});
+
+describe("collectAccountSyncAges", () => {
+	it("measures from the newest mailbox message-sync stamp", async () => {
+		const ages = await collectAccountSyncAges(
+			source([account({})], {
+				"acct-1": [mailbox(NOW - 300_000), mailbox(NOW - 60_000)],
+			}),
+			NOW,
+		);
+		assert.deepEqual(ages, [{ accountId: "acct-1", ageSeconds: 60 }]);
+	});
+
+	it("ignores account.lastSyncAt, which is stamped before the message fan-out", async () => {
+		// lastSyncAt is fresh and every message handler has been failing for an
+		// hour. The exported age must report the hour.
+		const ages = await collectAccountSyncAges(
+			source([account({ lastSyncAt: NOW })], {
+				"acct-1": [mailbox(NOW - 3_600_000)],
+			}),
+			NOW,
+		);
+		assert.deepEqual(ages, [{ accountId: "acct-1", ageSeconds: 3600 }]);
+	});
+
+	it("treats an unstamped mailbox as never synced", async () => {
+		const ages = await collectAccountSyncAges(
+			source([account({ createdAt: NOW - 900_000 })], {
+				"acct-1": [mailbox(0)],
+			}),
+			NOW,
+		);
+		assert.deepEqual(ages, [{ accountId: "acct-1", ageSeconds: 900 }]);
+	});
+
+	it("reports an account with no mailboxes at all rather than omitting it", async () => {
+		const ages = await collectAccountSyncAges(
+			source([account({ createdAt: NOW - 120_000 })], {}),
+			NOW,
+		);
+		assert.deepEqual(ages, [{ accountId: "acct-1", ageSeconds: 120 }]);
+	});
+
+	it("skips a deleted account", async () => {
+		const ages = await collectAccountSyncAges(
+			source(
+				[
+					account({ accountId: "gone", deletedAt: NOW - 1000 }),
+					account({ accountId: "live" }),
+				],
+				{ live: [mailbox(NOW - 30_000)] },
+			),
+			NOW,
+		);
+		assert.deepEqual(ages, [{ accountId: "live", ageSeconds: 30 }]);
+	});
+
+	it("never reports a negative age when a stamp is ahead of the clock", async () => {
+		const ages = await collectAccountSyncAges(
+			source([account({})], { "acct-1": [mailbox(NOW + 5_000)] }),
+			NOW,
+		);
+		assert.deepEqual(ages, [{ accountId: "acct-1", ageSeconds: 0 }]);
+	});
+});

package/dev-server/sync-age.ts

@@ -0,0 +1,55 @@
+import type { IAccountRepository, IMailboxRepository } from "@remit/data-ports";
+
+export interface SyncAgeSource {
+	readonly account: Pick<IAccountRepository, "listAll">;
+	readonly mailbox: Pick<IMailboxRepository, "listAllByAccount">;
+}
+
+export interface AccountSyncAge {
+	readonly accountId: string;
+	readonly ageSeconds: number;
+}
+
+/**
+ * Seconds since each account last completed a message-sync round
+ * (standalone-observability D3).
+ *
+ * Measured from `mailbox.lastMessageSyncAt`, not `account.lastSyncAt`.
+ * `account.lastSyncAt` is stamped after the mailbox *list* sync and before the
+ * per-mailbox fan-out that fetches messages, so a deployment whose message
+ * handlers all throw keeps it fresh forever while no mail arrives.
+ * `lastMessageSyncAt` is stamped at the end of a message-sync round, after the
+ * fetch and the writes.
+ *
+ * The value is the age of the newest such stamp across the account's mailboxes:
+ * seconds since this account last completed a round trip that would have found
+ * new mail if there were any. An account with no stamped mailbox has never
+ * completed one, and reports the age of the account row instead of being
+ * omitted — "never synced" is the condition most worth seeing, not a gap in the
+ * series.
+ *
+ * Labelled by account id, never by address: a scraped label travels wherever
+ * the scrape goes.
+ */
+export const collectAccountSyncAges = async (
+	source: SyncAgeSource,
+	now: number,
+): Promise<AccountSyncAge[]> => {
+	const accounts = await source.account.listAll();
+	const ages: AccountSyncAge[] = [];
+	for (const account of accounts) {
+		if (account.deletedAt) continue;
+		const mailboxes = await source.mailbox.listAllByAccount(account.accountId);
+		const stamps = mailboxes
+			.map((mailbox) => mailbox.lastMessageSyncAt)
+			.filter(
+				(stamp): stamp is number => typeof stamp === "number" && stamp > 0,
+			);
+		const newest = stamps.length > 0 ? Math.max(...stamps) : account.createdAt;
+		ages.push({
+			accountId: account.accountId,
+			ageSeconds: Math.max(0, Math.round((now - newest) / 1000)),
+		});
+	}
+	return ages;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/backend",
-  "version": "0.0.40",
+  "version": "0.0.41",
   "description": "Remit Mail Inspector API backend",
   "license": "MIT",
   "author": "",