@obsunified/collector 2.3.0 → 2.4.4

package/dist/{ingest-auth-BmP5-f96.d.ts → ingest-auth-BTowieER.d.ts}

@@ -1,4 +1,62 @@
 import { Hono, Context, MiddlewareHandler } from 'hono';
+import { AlertState } from '@obsunified/types';
+
+/**
+ * Email alert channel: the runtime-neutral half.
+ *
+ * The collector package runs on Cloudflare Workers as well as Node, and a
+ * Worker cannot open an SMTP connection. So the package only defines what an
+ * email transport must do (`AlertEmailTransport`) and how an alert reads as
+ * mail (`formatAlertEmail`); a host that can speak SMTP binds a transport as
+ * `env.ALERT_EMAIL` (the Node collector does, from `ALERT_SMTP_*`, see
+ * apps/collector-node/src/alert-email.ts). Without that binding, rules with
+ * an email channel are refused at create/update time and an email channel on
+ * an existing rule counts as a failed delivery at fire time.
+ */
+
+interface AlertEmailMessage {
+    to: string[];
+    subject: string;
+    text: string;
+}
+interface AlertEmailTransport {
+    /**
+     * Sends one message. Resolves only when the SMTP server accepted it for
+     * every recipient; rejects otherwise.
+     */
+    send(message: AlertEmailMessage): Promise<void>;
+}
+/** What every channel is told about a transition (the webhook JSON body). */
+interface AlertNotificationPayload {
+    rule: {
+        id: string;
+        name: string;
+        signal: string;
+    };
+    value: number;
+    threshold: number;
+    comparison: string;
+    state: AlertState;
+    evaluatedAt: string;
+    projectId: string;
+    /**
+     * RFC 0002 Stage 6 — populated when the rule is bound to an Analysis
+     * (`rule.analysisId` set). The narrative is the gated, LLM-generated
+     * sentence the dashboard panel was last showing — what's actually
+     * happening, in plain English. Webhooks consuming this can put the
+     * narrative in the Slack/PagerDuty body directly.
+     */
+    analysis?: {
+        id: string;
+        narrative: string | null;
+        status: string | null;
+    };
+}
+declare const isValidEmailAddress: (addr: string) => boolean;
+declare function formatAlertEmail(payload: AlertNotificationPayload): {
+    subject: string;
+    text: string;
+};
 
 /**
  * Pluggable logger interface for the collector framework.
@@ -69,6 +127,12 @@ interface CollectorEnv {
     /** Durable Object namespace for live-tail SSE pub/sub. Optional — when
      *  unbound the /internal/telemetry/tail endpoint returns 503. */
     TAIL_HUB?: DurableObjectNamespace;
+    /**
+     * SMTP transport for email alert channels. Bound by hosts that can send
+     * mail (the Node collector, from `ALERT_SMTP_*`); never set on Cloudflare
+     * Workers. Without it, rules with an email channel are refused.
+     */
+    ALERT_EMAIL?: AlertEmailTransport;
     /** Write-only API key for SDK ingest endpoints (/v1/*) */
     INGEST_KEY?: string;
     /** Password for dashboard login */
@@ -155,7 +219,7 @@ declare const COLLECTOR_STRING_ENV_MANIFEST: {
 type CollectorOptionalStringEnvKey = (typeof COLLECTOR_OPTIONAL_STRING_ENV_KEYS)[number];
 type CollectorHostManagedEnvKey = (typeof COLLECTOR_HOST_MANAGED_ENV_KEYS)[number];
 type CollectorManifestStringEnvKey = CollectorOptionalStringEnvKey | CollectorHostManagedEnvKey;
-type CollectorObjectBindingKey = "DB" | "REPLAYS_BUCKET" | "PROFILES_BUCKET" | "TAIL_HUB";
+type CollectorObjectBindingKey = "DB" | "REPLAYS_BUCKET" | "PROFILES_BUCKET" | "TAIL_HUB" | "ALERT_EMAIL";
 type CollectorStringEnvKey = Exclude<keyof CollectorEnv, CollectorObjectBindingKey>;
 /**
  * Verifies that every string key in `declaredKeys` is categorized in either
@@ -202,4 +266,4 @@ declare function createIngestAuth(config?: {
     };
 }>;
 
-export { COLLECTOR_HOST_MANAGED_ENV_KEYS as C, type Logger as L, COLLECTOR_OPTIONAL_STRING_ENV_KEYS as a, COLLECTOR_STRING_ENV_MANIFEST as b, type ChildSpanRunner as c, type CollectorApp as d, type CollectorEnv as e, type CollectorHostManagedEnvKey as f, type CollectorManifestStringEnvKey as g, type CollectorObjectBindingKey as h, type CollectorOptionalStringEnvKey as i, type CollectorRouteContext as j, type CollectorStringEnvKey as k, assertCollectorEnvManifestCompleteness as l, consoleLogger as m, createIngestAuth as n, resetIngestAuthCache as r };
+export { type AlertEmailMessage as A, COLLECTOR_HOST_MANAGED_ENV_KEYS as C, type Logger as L, type AlertEmailTransport as a, type AlertNotificationPayload as b, COLLECTOR_OPTIONAL_STRING_ENV_KEYS as c, COLLECTOR_STRING_ENV_MANIFEST as d, type ChildSpanRunner as e, type CollectorApp as f, type CollectorEnv as g, type CollectorHostManagedEnvKey as h, type CollectorManifestStringEnvKey as i, type CollectorObjectBindingKey as j, type CollectorOptionalStringEnvKey as k, type CollectorRouteContext as l, type CollectorStringEnvKey as m, assertCollectorEnvManifestCompleteness as n, consoleLogger as o, createIngestAuth as p, formatAlertEmail as q, isValidEmailAddress as r, resetIngestAuthCache as s };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@obsunified/collector",
-  "version": "2.3.0",
+  "version": "2.4.4",
   "description": "Plugin-based observability collector runtime with pluggable SQL/blob storage.",
   "license": "MIT",
   "repository": {
@@ -37,8 +37,8 @@
   "sideEffects": false,
   "dependencies": {
     "@bufbuild/protobuf": "^2.11.0",
-    "@obsunified/pprof-decoder": "2.0.2",
-    "@obsunified/types": "2.3.0"
+    "@obsunified/pprof-decoder": "2.0.3",
+    "@obsunified/types": "2.4.1"
   },
   "peerDependencies": {
     "hono": "^4.7.0",

package/src/framework/collector.ts

@@ -129,6 +129,13 @@ export interface CollectorConfig {
 	 * client can never make the host buffer an ingest-sized body.
 	 */
 	maxAuthBodyBytes?: number;
+	/**
+	 * Acknowledge that this app runs without `auth` on `/v1/*` (e.g. a local
+	 * sandbox behind a trusted proxy). It changes nothing about request
+	 * handling; it only silences the one-time warning logged when the first
+	 * ingest request reaches an app that has no ingest auth configured.
+	 */
+	allowUnauthenticatedIngest?: boolean;
 }
 
 export class CollectorRuntime implements CollectorPluginContext {
@@ -350,6 +357,21 @@ export const createTelemetryCollectorApp = (
 	} else if (config.auth?.ingest) {
 		// Legacy: explicit ingest-only middleware
 		app.use("/v1/*", config.auth.ingest);
+	} else if (!config.allowUnauthenticatedIngest) {
+		// No ingest auth: /v1/* accepts anonymous writes. Behaviour is kept
+		// for compatibility, but say so loudly — once, on the first ingest
+		// request, so merely importing the package (whose default export
+		// builds an auth-less app) never logs.
+		let warned = false;
+		app.use("/v1/*", async (_c, next) => {
+			if (!warned) {
+				warned = true;
+				runtime.logger.warn(
+					"[collector] WARNING: /v1/* ingest is UNAUTHENTICATED — this app was built without `auth`, so anyone who can reach it can write telemetry. Pass `auth: { middleware: createIngestAuth() }` (and set INGEST_KEY or create a key in the dashboard), or set `allowUnauthenticatedIngest: true` to acknowledge and silence this warning.",
+				);
+			}
+			await next();
+		});
 	}
 
 	// Dashboard auth (session cookie or programmatic bearer token) — owns /internal/* and /dashboard/* when configured.

package/src/framework/env.ts

@@ -1,4 +1,5 @@
 import type { Context, Hono } from "hono";
+import type { AlertEmailTransport } from "../lib/alert-email";
 import type { Logger } from "./logger";
 
 /**
@@ -22,6 +23,12 @@ export interface CollectorEnv {
 	/** Durable Object namespace for live-tail SSE pub/sub. Optional — when
 	 *  unbound the /internal/telemetry/tail endpoint returns 503. */
 	TAIL_HUB?: DurableObjectNamespace;
+	/**
+	 * SMTP transport for email alert channels. Bound by hosts that can send
+	 * mail (the Node collector, from `ALERT_SMTP_*`); never set on Cloudflare
+	 * Workers. Without it, rules with an email channel are refused.
+	 */
+	ALERT_EMAIL?: AlertEmailTransport;
 	/** Write-only API key for SDK ingest endpoints (/v1/*) */
 	INGEST_KEY?: string;
 	/** Password for dashboard login */
@@ -146,7 +153,8 @@ export type CollectorObjectBindingKey =
 	| "DB"
 	| "REPLAYS_BUCKET"
 	| "PROFILES_BUCKET"
-	| "TAIL_HUB";
+	| "TAIL_HUB"
+	| "ALERT_EMAIL";
 
 export type CollectorStringEnvKey = Exclude<
 	keyof CollectorEnv,

package/src/framework/ingest-auth-warning.test.ts

@@ -0,0 +1,71 @@
+/**
+ * An app built without ingest auth keeps accepting anonymous `/v1/*` writes
+ * (back-compat), but logs one loud warning on the first ingest request.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import type { CollectorPlugin } from "./collector";
+import { createTelemetryCollectorApp } from "./collector";
+import type { CollectorEnv } from "./env";
+import type { Logger } from "./logger";
+
+const okPlugin: CollectorPlugin = {
+	name: "ok",
+	register(app) {
+		app.post("/v1/traces", (c) => c.json({ ok: true }));
+	},
+};
+
+const spyLogger = () => {
+	const warn = vi.fn<Logger["warn"]>();
+	const logger: Logger = {
+		debug: vi.fn(),
+		info: vi.fn(),
+		warn,
+		error: vi.fn(),
+	};
+	return { logger, warn };
+};
+
+const ingest = (app: ReturnType<typeof createTelemetryCollectorApp>) =>
+	app.request("/v1/traces", { method: "POST", body: "{}" }, {} as CollectorEnv);
+
+const unauthWarnings = ({ warn }: ReturnType<typeof spyLogger>) =>
+	warn.mock.calls.filter(([m]) => String(m).includes("UNAUTHENTICATED"));
+
+describe("unauthenticated ingest warning", () => {
+	it("warns exactly once and still accepts the request", async () => {
+		const spy = spyLogger();
+		const { logger } = spy;
+		const app = createTelemetryCollectorApp({ plugins: [okPlugin], logger });
+		expect(unauthWarnings(spy)).toHaveLength(0); // not at build time
+		for (let i = 0; i < 3; i++) {
+			expect((await ingest(app)).status).toBe(200);
+		}
+		expect(unauthWarnings(spy)).toHaveLength(1);
+	});
+
+	it("stays silent when ingest auth is configured", async () => {
+		const spy = spyLogger();
+		const { logger } = spy;
+		const app = createTelemetryCollectorApp({
+			plugins: [okPlugin],
+			logger,
+			auth: { middleware: async (_c, next) => next() },
+		});
+		expect((await ingest(app)).status).toBe(200);
+		expect(unauthWarnings(spy)).toHaveLength(0);
+	});
+
+	it("stays silent with the explicit allowUnauthenticatedIngest opt-in", async () => {
+		const spy = spyLogger();
+		const { logger } = spy;
+		const app = createTelemetryCollectorApp({
+			plugins: [okPlugin],
+			logger,
+			allowUnauthenticatedIngest: true,
+		});
+		expect((await ingest(app)).status).toBe(200);
+		expect(unauthWarnings(spy)).toHaveLength(0);
+	});
+});

package/src/index.ts

@@ -9,6 +9,7 @@ import { aiSpanPayloadsProcessorPlugin } from "./plugins/ai-span-payloads-proces
 import {
 	createAlertEvaluatorHandler,
 	evaluateAllRules,
+	evaluateRuleBatch,
 } from "./plugins/alerts-evaluator";
 import { alertsRoutesPlugin } from "./plugins/alerts-routes";
 import { analysesRoutesPlugin } from "./plugins/analyses-routes";
@@ -100,6 +101,13 @@ export {
 	type RetrievalEventRecord,
 	type ToolCallRecord,
 } from "./lib/actions-store";
+export {
+	type AlertEmailMessage,
+	type AlertEmailTransport,
+	type AlertNotificationPayload,
+	formatAlertEmail,
+	isValidEmailAddress,
+} from "./lib/alert-email";
 export { AlertsStore, compareValue } from "./lib/alerts-store";
 export {
 	computeChangeBlastRadius,
@@ -168,6 +176,11 @@ export {
 	isEvalCaseSourceType,
 	isEvalRunStatus,
 } from "./lib/eval-cases-store";
+export {
+	evaluateMetricQuery,
+	reduceSeries,
+	validateMetricQuery,
+} from "./lib/metric-alerts";
 export { MetricsStore } from "./lib/metrics-store";
 export { ProjectsStore } from "./lib/projects-store";
 export { D1Adapter, type SqlDb, type SqlStatement } from "./lib/sql-db";
@@ -192,6 +205,7 @@ export {
 	defaultSpanEnrichmentPlugin,
 	evalCasesRoutesPlugin,
 	evaluateAllRules,
+	evaluateRuleBatch,
 	evidenceRetrievalRoutesPlugin,
 	genAiNormalizerPlugin,
 	identityReceiverPlugin,
@@ -272,6 +286,7 @@ export const createDefaultCollectorApp = (config?: Partial<CollectorConfig>) =>
 		logger: config?.logger,
 		withChildSpan: config?.withChildSpan,
 		sqlDb: config?.sqlDb,
+		allowUnauthenticatedIngest: config?.allowUnauthenticatedIngest,
 	});
 
 export default createTelemetryCollectorApp(allPlugins);

package/src/lib/alert-email.ts

@@ -0,0 +1,104 @@
+/**
+ * Email alert channel: the runtime-neutral half.
+ *
+ * The collector package runs on Cloudflare Workers as well as Node, and a
+ * Worker cannot open an SMTP connection. So the package only defines what an
+ * email transport must do (`AlertEmailTransport`) and how an alert reads as
+ * mail (`formatAlertEmail`); a host that can speak SMTP binds a transport as
+ * `env.ALERT_EMAIL` (the Node collector does, from `ALERT_SMTP_*`, see
+ * apps/collector-node/src/alert-email.ts). Without that binding, rules with
+ * an email channel are refused at create/update time and an email channel on
+ * an existing rule counts as a failed delivery at fire time.
+ */
+
+import type { AlertState } from "@obsunified/types";
+
+export interface AlertEmailMessage {
+	to: string[];
+	subject: string;
+	text: string;
+}
+
+export interface AlertEmailTransport {
+	/**
+	 * Sends one message. Resolves only when the SMTP server accepted it for
+	 * every recipient; rejects otherwise.
+	 */
+	send(message: AlertEmailMessage): Promise<void>;
+}
+
+/** What every channel is told about a transition (the webhook JSON body). */
+export interface AlertNotificationPayload {
+	rule: {
+		id: string;
+		name: string;
+		signal: string;
+	};
+	value: number;
+	threshold: number;
+	comparison: string;
+	state: AlertState;
+	evaluatedAt: string;
+	projectId: string;
+	/**
+	 * RFC 0002 Stage 6 — populated when the rule is bound to an Analysis
+	 * (`rule.analysisId` set). The narrative is the gated, LLM-generated
+	 * sentence the dashboard panel was last showing — what's actually
+	 * happening, in plain English. Webhooks consuming this can put the
+	 * narrative in the Slack/PagerDuty body directly.
+	 */
+	analysis?: {
+		id: string;
+		narrative: string | null;
+		status: string | null;
+	};
+}
+
+export const MAX_EMAIL_RECIPIENTS = 20;
+
+// Deliberately strict: one plain address, no display name, no whitespace,
+// commas, angle brackets or quotes (nothing that could add a header or a
+// second recipient).
+const EMAIL_RE =
+	/^[^\s@<>,;:"()[\]\\]+@[^\s@<>,;:"()[\]\\]+\.[^\s@<>,;:"()[\]\\]+$/;
+
+export const isValidEmailAddress = (addr: string): boolean =>
+	addr.length <= 254 && EMAIL_RE.test(addr);
+
+const oneLine = (s: string): string => s.replace(/[\r\n]+/g, " ").trim();
+
+export function formatAlertEmail(payload: AlertNotificationPayload): {
+	subject: string;
+	text: string;
+} {
+	const label = payload.state === "firing" ? "FIRING" : "RESOLVED";
+	const name = oneLine(payload.rule.name);
+	const lines = [
+		payload.state === "firing"
+			? `Alert rule "${name}" is firing.`
+			: `Alert rule "${name}" has resolved.`,
+		"",
+		`Rule:        ${name} (${payload.rule.id})`,
+		`Signal:      ${payload.rule.signal}`,
+		`State:       ${payload.state}`,
+		`Value:       ${payload.value}`,
+		`Condition:   value ${payload.comparison} ${payload.threshold}`,
+		`Threshold:   ${payload.threshold}`,
+		`Comparison:  ${payload.comparison}`,
+		`Evaluated:   ${payload.evaluatedAt}`,
+		`Project:     ${payload.projectId}`,
+	];
+	if (payload.analysis) {
+		lines.push(
+			`Analysis:    ${payload.analysis.id}${payload.analysis.status ? ` (${payload.analysis.status})` : ""}`,
+		);
+		if (payload.analysis.narrative) {
+			lines.push("", payload.analysis.narrative);
+		}
+	}
+	lines.push("", "Sent by obs-unified.");
+	return {
+		subject: `[obs-unified] ${label}: ${name}`,
+		text: `${lines.join("\n")}\n`,
+	};
+}

package/src/lib/alerts-store.test.ts

@@ -4,8 +4,8 @@
  */
 
 import type { AlertRuleInput } from "@obsunified/types";
-import { describe, expect, it } from "vitest";
-import { AlertsStore } from "./alerts-store";
+import { describe, expect, it, vi } from "vitest";
+import { AlertsStore, sanitizeEvaluationError } from "./alerts-store";
 import { ProjectsStore } from "./projects-store";
 import { createMigratedSqliteDb } from "./test-utils/node-sqlite-db";
 
@@ -66,6 +66,37 @@ describe("AlertsStore.deleteRule", () => {
 	});
 });
 
+describe("AlertsStore.listEvaluations project scoping", () => {
+	it("does not return another project's evaluation history for a known rule id", async () => {
+		const db = createMigratedSqliteDb();
+		const projects = new ProjectsStore(db);
+		const alphaProject = await projects.createProject({ name: "A", slug: "a" });
+		const betaProject = await projects.createProject({ name: "B", slug: "b" });
+		const store = new AlertsStore(db);
+		const beta = await store.createRule(
+			betaProject.id,
+			input({ name: "beta" }),
+		);
+		await store.recordEvaluation(beta.id, beta.projectId, 5, "firing", true);
+
+		const own = await store.listEvaluations({
+			ruleId: beta.id,
+			projectId: betaProject.id,
+			hours: 24,
+		});
+		expect(own.evaluations).toHaveLength(1);
+
+		const foreign = await store.listEvaluations({
+			ruleId: beta.id,
+			projectId: alphaProject.id,
+			hours: 24,
+		});
+		expect(foreign.evaluations).toEqual([]);
+		expect(foreign.evidenceReferences).toBeUndefined();
+		db.close();
+	});
+});
+
 describe("AlertsStore.validateInput webhook targets", () => {
 	const store = new AlertsStore(createMigratedSqliteDb());
 
@@ -151,3 +182,117 @@ describe("AlertsStore alert_state.notified (migration 049)", () => {
 		});
 	});
 });
+
+describe("AlertsStore.listRules evaluation status", () => {
+	it("reports the last evaluation, its error and whether the state was delivered", async () => {
+		vi.useFakeTimers({ toFake: ["Date"] });
+		try {
+			const db = createMigratedSqliteDb();
+			const project = await new ProjectsStore(db).createProject({
+				name: "S",
+				slug: "s",
+			});
+			const store = new AlertsStore(db);
+			const erroring = await store.createRule(
+				project.id,
+				input({ name: "erroring" }),
+			);
+			const undelivered = await store.createRule(
+				project.id,
+				input({ name: "undelivered" }),
+			);
+			const fresh = await store.createRule(
+				project.id,
+				input({ name: "fresh" }),
+			);
+
+			vi.setSystemTime(Date.parse("2026-10-31T10:00:00.000Z"));
+			await store.recordEvaluation(erroring.id, project.id, 3, "ok", false);
+			vi.setSystemTime(Date.parse("2026-10-31T10:05:00.000Z"));
+			await store.recordEvaluation(
+				erroring.id,
+				project.id,
+				0,
+				"ok",
+				false,
+				"error",
+				"connect ECONNREFUSED postgres://obs:hunter2@db:5432/obs\nat pool",
+			);
+			await store.transitionState(
+				undelivered.id,
+				project.id,
+				"firing",
+				"2026-10-31T10:05:00.000Z",
+			);
+			await store.recordEvaluation(
+				undelivered.id,
+				project.id,
+				7,
+				"firing",
+				false,
+			);
+
+			const byName = new Map(
+				(await store.listRules(project.id)).map((r) => [r.name, r]),
+			);
+			expect(byName.get("erroring")).toMatchObject({
+				currentState: undefined,
+				notificationDelivered: null,
+				lastEvaluation: {
+					evaluatedAt: "2026-10-31T10:05:00.000Z",
+					outcome: "error",
+					value: 0,
+					error: "connect ECONNREFUSED <url> at pool",
+				},
+			});
+			expect(JSON.stringify(byName.get("erroring"))).not.toContain("hunter2");
+			expect(byName.get("undelivered")).toMatchObject({
+				currentState: "firing",
+				notificationDelivered: false,
+				lastEvaluation: { outcome: "value", value: 7, error: null },
+			});
+			expect(byName.get("fresh")).toMatchObject({
+				notificationDelivered: null,
+				lastEvaluation: null,
+			});
+			// Existing fields are unchanged.
+			expect(byName.get("fresh")).toMatchObject({
+				id: fresh.id,
+				signal: "spans",
+				enabled: true,
+			});
+
+			await store.markNotified(
+				undelivered.id,
+				project.id,
+				"firing",
+				"2026-10-31T10:05:00.000Z",
+			);
+			expect(
+				(await store.listRules(project.id)).find(
+					(r) => r.name === "undelivered",
+				)?.notificationDelivered,
+			).toBe(true);
+
+			const evaluations = await store.listEvaluations({
+				ruleId: erroring.id,
+				projectId: project.id,
+				hours: 24 * 365,
+			});
+			expect(evaluations.evaluations[0]).toMatchObject({
+				outcome: "error",
+				error: "connect ECONNREFUSED <url> at pool",
+			});
+			db.close();
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it("truncates long error messages", () => {
+		expect(sanitizeEvaluationError("x".repeat(800))).toHaveLength(500);
+		expect(sanitizeEvaluationError("see https://hooks.slack.com/T/B/s")).toBe(
+			"see <url>",
+		);
+	});
+});