@obsunified/collector 2.0.1

package/src/lib/store.ts

@@ -0,0 +1,96 @@
+import type {
+	StoredSpan,
+	TelemetryInstrumentationGapsResponse,
+	TelemetryIssueDetailResponse,
+	TelemetryIssueOptions,
+	TelemetryIssueOverviewResponse,
+	TelemetryOverviewOptions,
+	TelemetryOverviewResponse,
+	TelemetryTraceDetailResponse,
+} from "@obsunified/types";
+import type { SqlDb } from "./sql-db";
+import { getTelemetryExportRows } from "./store/export";
+import { ingestTelemetrySpans } from "./store/ingest";
+import {
+	getTelemetryIssueDetail,
+	getTelemetryIssueOverview,
+} from "./store/issues";
+import { getTelemetryOverview } from "./store/overview";
+import { purgeExpiredTelemetry } from "./store/retention";
+import {
+	getTelemetryServiceMap,
+	getTelemetryServiceOperations,
+	type ServiceMapOptions,
+	type ServiceOperationsOptions,
+} from "./store/service-map";
+import {
+	calibrateTelemetryInstrumentationGaps,
+	getTelemetryTraceDetail,
+	getTelemetryTraceGaps,
+	type TelemetryInstrumentationGapCalibrationOptions,
+} from "./store/trace-detail";
+
+export class TelemetryStore {
+	constructor(private readonly db: SqlDb) {}
+
+	async ingest(
+		spans: StoredSpan[],
+	): Promise<{ inserted: number; traceCount: number }> {
+		return ingestTelemetrySpans(this.db, spans);
+	}
+
+	async getOverview(
+		options: TelemetryOverviewOptions,
+	): Promise<TelemetryOverviewResponse> {
+		return getTelemetryOverview(this.db, options);
+	}
+
+	async getTraceDetail(
+		traceId: string,
+		projectId: string,
+	): Promise<TelemetryTraceDetailResponse | null> {
+		return getTelemetryTraceDetail(this.db, traceId, projectId);
+	}
+
+	async getTraceGaps(
+		traceId: string,
+		projectId: string,
+	): Promise<TelemetryInstrumentationGapsResponse | null> {
+		return getTelemetryTraceGaps(this.db, traceId, projectId);
+	}
+
+	async calibrateTraceGaps(
+		options: TelemetryInstrumentationGapCalibrationOptions,
+	) {
+		return calibrateTelemetryInstrumentationGaps(this.db, options);
+	}
+
+	async getIssueOverview(
+		options: TelemetryIssueOptions,
+	): Promise<TelemetryIssueOverviewResponse> {
+		return getTelemetryIssueOverview(this.db, options);
+	}
+
+	async getIssueDetail(
+		issueId: string,
+		options: TelemetryIssueOptions,
+	): Promise<TelemetryIssueDetailResponse | null> {
+		return getTelemetryIssueDetail(this.db, issueId, options);
+	}
+
+	async getExportRows(options: TelemetryOverviewOptions): Promise<string> {
+		return getTelemetryExportRows(this.db, options);
+	}
+
+	async getServiceMap(options: ServiceMapOptions) {
+		return getTelemetryServiceMap(this.db, options);
+	}
+
+	async getServiceOperations(options: ServiceOperationsOptions) {
+		return getTelemetryServiceOperations(this.db, options);
+	}
+
+	async purgeExpired(): Promise<number> {
+		return purgeExpiredTelemetry(this.db);
+	}
+}

package/src/lib/tail-publisher.ts

@@ -0,0 +1,64 @@
+import type { LogRecord, StoredSpan } from "@obsunified/types";
+import type { TailEvent } from "../durable-objects/tail-hub";
+import type { CollectorEnv } from "../framework/env";
+
+/**
+ * Fire-and-forget publish to the TailHub DO. Swallows errors — tail is a
+ * best-effort UX feature; a broadcast failure must never break ingest.
+ */
+export async function publishTail(
+	env: CollectorEnv,
+	events: TailEvent[],
+): Promise<void> {
+	if (!env.TAIL_HUB || events.length === 0) return;
+	try {
+		const id = env.TAIL_HUB.idFromName("singleton");
+		const stub = env.TAIL_HUB.get(id);
+		await stub.fetch("https://hub/publish", {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify(events),
+		});
+	} catch (err) {
+		console.error("[tail-publisher] publish failed:", err);
+	}
+}
+
+export function spanToTailEvent(span: StoredSpan): TailEvent {
+	return {
+		kind: "span",
+		projectId: span.projectId,
+		row: {
+			traceId: span.traceId,
+			spanId: span.spanId,
+			parentSpanId: span.parentSpanId,
+			serviceName: span.serviceName,
+			spanName: span.spanName,
+			spanKind: span.spanKind,
+			statusCode: span.statusCode,
+			statusMessage: span.statusMessage,
+			startTime: span.startTime,
+			endTime: span.endTime,
+			durationMs: span.durationMs,
+		},
+		t: span.receivedAt,
+	};
+}
+
+export function logToTailEvent(log: LogRecord): TailEvent {
+	return {
+		kind: "log",
+		projectId: log.projectId,
+		row: {
+			logId: log.logId,
+			traceId: log.traceId,
+			spanId: log.spanId,
+			serviceName: log.serviceName,
+			severity: log.severity,
+			loggerName: log.loggerName,
+			message: log.message,
+			occurredAt: log.occurredAt,
+		},
+		t: log.receivedAt,
+	};
+}

package/src/lib/test-utils/mem-sql-db.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Self-test for the `MemSqlDb` test double — RFC 0008 Phase 0.4.
+ *
+ * The point is to validate the double behaves as the `SqlDb` contract
+ * promises (prepare → bind → first/all/run, with binds carried forward
+ * through `bind`), so anything that uses it for store-level testing in
+ * later phases can trust the seam.
+ */
+
+import { describe, expect, it } from "vitest";
+import type { SqlDb } from "../sql-db";
+import { MemSqlDb } from "./mem-sql-db";
+
+const useDb = (db: SqlDb) => db; // type-witness — fails to compile if MemSqlDb drifts from SqlDb.
+
+describe("MemSqlDb", () => {
+	it("conforms to SqlDb structurally", () => {
+		const db = new MemSqlDb();
+		// Compiles only because MemSqlDb implements SqlDb.
+		expect(useDb(db)).toBe(db);
+	});
+
+	it("records prepare / bind / first calls with the bound args", async () => {
+		const db = new MemSqlDb({
+			first: (sql, binds) =>
+				sql.startsWith("SELECT count") && binds[0] === "p1" ? { c: 7 } : null,
+		});
+
+		const row = await db
+			.prepare("SELECT count(*) as c FROM x WHERE project_id = ?")
+			.bind("p1")
+			.first<{ c: number }>();
+
+		expect(row).toEqual({ c: 7 });
+		expect(db.calls).toHaveLength(1);
+		expect(db.calls[0]).toEqual({
+			sql: "SELECT count(*) as c FROM x WHERE project_id = ?",
+			binds: ["p1"],
+			op: "first",
+		});
+	});
+
+	it("returns wrapped results for all()", async () => {
+		const db = new MemSqlDb({
+			all: () => [{ id: "a" }, { id: "b" }],
+		});
+
+		const out = await db.prepare("SELECT id FROM x").all<{ id: string }>();
+		expect(out).toEqual({ results: [{ id: "a" }, { id: "b" }] });
+	});
+
+	it("returns empty results when no all() handler is configured", async () => {
+		const db = new MemSqlDb();
+		const out = await db.prepare("SELECT 1").all();
+		expect(out).toEqual({ results: [] });
+	});
+
+	it("returns changes=1 by default for run()", async () => {
+		const db = new MemSqlDb();
+		const out = await db.prepare("INSERT INTO x DEFAULT VALUES").run();
+		expect(out).toEqual({ meta: { changes: 1 } });
+	});
+
+	it("honors a configurable run() handler", async () => {
+		const db = new MemSqlDb({ run: () => ({ changes: 3 }) });
+		const out = await db.prepare("UPDATE x SET y=1").run();
+		expect(out).toEqual({ meta: { changes: 3 } });
+	});
+
+	it("each bind() returns a new statement (binds don't leak across statements)", async () => {
+		const db = new MemSqlDb({
+			first: (_sql, binds) => ({ bind0: binds[0] }),
+		});
+		const stmt = db.prepare("SELECT ? AS x");
+
+		const a = await stmt.bind("a").first<{ bind0: string }>();
+		const b = await stmt.bind("b").first<{ bind0: string }>();
+
+		expect(a).toEqual({ bind0: "a" });
+		expect(b).toEqual({ bind0: "b" });
+	});
+
+	it("callsMatching filters by SQL substring", async () => {
+		const db = new MemSqlDb();
+		await db.prepare("INSERT INTO foo VALUES (?)").bind(1).run();
+		await db.prepare("INSERT INTO bar VALUES (?)").bind(2).run();
+		await db.prepare("SELECT * FROM foo").all();
+
+		expect(db.callsMatching("foo")).toHaveLength(2);
+		expect(db.callsMatching("bar")).toHaveLength(1);
+		expect(db.callsMatching("baz")).toHaveLength(0);
+	});
+});

package/src/lib/test-utils/mem-sql-db.ts

@@ -0,0 +1,86 @@
+/**
+ * In-memory `SqlDb` test double — RFC 0008.
+ *
+ * Replaces hand-rolled `FakeDb` patterns scattered across tests (e.g. the
+ * one in `stage6.test.ts` that motivated this). Tests configure `first` /
+ * `all` / `run` matchers; the double records every prepare/bind so tests
+ * can assert *which* SQL was issued, not just that something ran.
+ *
+ * Not a real SQLite — there is no execution. The point is decision
+ * coverage (which query did the store choose, which value did it return),
+ * not SQL grammar coverage.
+ */
+
+import type { SqlDb, SqlStatement } from "../sql-db";
+
+export interface MemSqlDbOptions {
+	/** Return value for `first()`. Receives the SQL + binds at call time. */
+	first?: (sql: string, binds: unknown[]) => Record<string, unknown> | null;
+	/** Rows returned for `all()`. The double wraps in `{ results }`. */
+	all?: (sql: string, binds: unknown[]) => Record<string, unknown>[];
+	/** Changes count for `run()`. Defaults to `1`. */
+	run?: (sql: string, binds: unknown[]) => { changes: number };
+}
+
+export interface MemSqlDbCall {
+	sql: string;
+	binds: unknown[];
+	op: "first" | "all" | "run";
+}
+
+export class MemSqlDb implements SqlDb {
+	readonly calls: MemSqlDbCall[] = [];
+	constructor(private readonly opts: MemSqlDbOptions = {}) {}
+
+	prepare(sql: string): SqlStatement {
+		return new MemSqlStatement(sql, [], this.calls, this.opts);
+	}
+
+	async batch(
+		statements: SqlStatement[],
+	): Promise<Array<{ meta: { changes: number } }>> {
+		const results: Array<{ meta: { changes: number } }> = [];
+		for (const stmt of statements) {
+			results.push(await stmt.run());
+		}
+		return results;
+	}
+
+	/** Filter recorded calls by a substring of the SQL — convenient in tests. */
+	callsMatching(needle: string): MemSqlDbCall[] {
+		return this.calls.filter((c) => c.sql.includes(needle));
+	}
+}
+
+class MemSqlStatement implements SqlStatement {
+	constructor(
+		private readonly sql: string,
+		private readonly binds: unknown[],
+		private readonly calls: MemSqlDbCall[],
+		private readonly opts: MemSqlDbOptions,
+	) {}
+
+	bind(...args: unknown[]): SqlStatement {
+		return new MemSqlStatement(this.sql, args, this.calls, this.opts);
+	}
+
+	async first<T = Record<string, unknown>>(): Promise<T | null> {
+		this.calls.push({ sql: this.sql, binds: this.binds, op: "first" });
+		const row = this.opts.first ? this.opts.first(this.sql, this.binds) : null;
+		return (row ?? null) as T | null;
+	}
+
+	async all<T = Record<string, unknown>>(): Promise<{ results: T[] }> {
+		this.calls.push({ sql: this.sql, binds: this.binds, op: "all" });
+		const rows = this.opts.all ? this.opts.all(this.sql, this.binds) : [];
+		return { results: rows as T[] };
+	}
+
+	async run(): Promise<{ meta: { changes: number } }> {
+		this.calls.push({ sql: this.sql, binds: this.binds, op: "run" });
+		const r = this.opts.run
+			? this.opts.run(this.sql, this.binds)
+			: { changes: 1 };
+		return { meta: { changes: r.changes } };
+	}
+}

package/src/lib/ua-parser.ts

@@ -0,0 +1,61 @@
+const BOT_PATTERN =
+	/(?:^|[^\p{L}\p{N}])(?:bot|crawler|spider|slurp|facebookexternalhit|headless|monitoring|uptime|curl|wget|python-requests|go-http-client)(?:$|[^\p{L}\p{N}])/iu;
+
+export interface ParsedUserAgent {
+	browser: string | null;
+	os: string | null;
+	deviceType: string | null;
+}
+
+export const isBot = (userAgent: string | null | undefined): boolean =>
+	Boolean(userAgent && BOT_PATTERN.test(userAgent));
+
+const detectBrowser = (userAgent: string): string | null => {
+	if (/edg\//i.test(userAgent)) return "Edge";
+	if (/opr\//i.test(userAgent) || /opera/i.test(userAgent)) return "Opera";
+	if (/samsungbrowser\//i.test(userAgent)) return "Samsung Internet";
+	if (/chrome\//i.test(userAgent) || /crios\//i.test(userAgent))
+		return "Chrome";
+	if (/firefox\//i.test(userAgent) || /fxios\//i.test(userAgent))
+		return "Firefox";
+	if (/safari\//i.test(userAgent)) return "Safari";
+	return null;
+};
+
+const detectOs = (userAgent: string): string | null => {
+	if (/windows nt/i.test(userAgent)) return "Windows";
+	if (/(iphone|ipad|ipod)/i.test(userAgent)) return "iOS";
+	if (/android/i.test(userAgent)) return "Android";
+	if (/mac os x/i.test(userAgent) || /macintosh/i.test(userAgent))
+		return "macOS";
+	if (/linux/i.test(userAgent)) return "Linux";
+	return null;
+};
+
+const detectDeviceType = (userAgent: string): string | null => {
+	if (/ipad|tablet/i.test(userAgent)) return "tablet";
+	if (/mobile|iphone|ipod|android/i.test(userAgent)) return "mobile";
+	return "desktop";
+};
+
+export const parseUserAgent = (
+	userAgent: string | null | undefined,
+): ParsedUserAgent => {
+	if (!userAgent) {
+		return { browser: null, os: null, deviceType: null };
+	}
+
+	if (isBot(userAgent)) {
+		return {
+			browser: detectBrowser(userAgent),
+			os: detectOs(userAgent),
+			deviceType: "bot",
+		};
+	}
+
+	return {
+		browser: detectBrowser(userAgent),
+		os: detectOs(userAgent),
+		deviceType: detectDeviceType(userAgent),
+	};
+};