silgi 0.1.0-beta.13 → 0.1.0-beta.15

package/dist/plugins/analytics-query.mjs

@@ -0,0 +1,164 @@
+//#region src/plugins/analytics-query.ts
+function parseQueryParams(params) {
+	const q = {};
+	const cursor = params.get("cursor");
+	if (cursor) q.cursor = Number(cursor);
+	const before = params.get("before");
+	if (before) q.before = Number(before);
+	const limit = params.get("limit");
+	q.limit = limit ? Math.max(1, Number(limit)) : 50;
+	q.sort = params.get("sort") ?? void 0;
+	q.order = params.get("order") ?? void 0;
+	q.status = params.get("status") ?? void 0;
+	q.path = params.get("path") ?? void 0;
+	q.search = params.get("search") ?? void 0;
+	q.procedure = params.get("procedure") ?? void 0;
+	q.session = params.get("session") ?? void 0;
+	const minDuration = params.get("minDuration");
+	if (minDuration) q.minDuration = Number(minDuration);
+	const maxDuration = params.get("maxDuration");
+	if (maxDuration) q.maxDuration = Number(maxDuration);
+	return q;
+}
+function matchesStatus(entryStatus, filter) {
+	const exact = Number(filter);
+	if (Number.isFinite(exact)) return entryStatus === exact;
+	if (/^[1-5]xx$/i.test(filter)) {
+		const cls = Number(filter[0]);
+		return Math.floor(entryStatus / 100) === cls;
+	}
+	const rangeMatch = filter.match(/^([<>]=?)(\d+)$/);
+	if (rangeMatch) {
+		const [, op, val] = rangeMatch;
+		const n = Number(val);
+		switch (op) {
+			case ">": return entryStatus > n;
+			case ">=": return entryStatus >= n;
+			case "<": return entryStatus < n;
+			case "<=": return entryStatus <= n;
+		}
+	}
+	return true;
+}
+function queryRequests(entries, params) {
+	let filtered = entries;
+	if (params.status) {
+		const status = params.status;
+		filtered = filtered.filter((r) => matchesStatus(r.status, status));
+	}
+	if (params.path) {
+		const prefix = params.path.toLowerCase();
+		filtered = filtered.filter((r) => r.path.toLowerCase().includes(prefix));
+	}
+	if (params.procedure) {
+		const proc = params.procedure.toLowerCase();
+		filtered = filtered.filter((r) => r.procedures.some((p) => p.procedure.toLowerCase().includes(proc)));
+	}
+	if (params.session) {
+		const session = params.session;
+		filtered = filtered.filter((r) => r.sessionId === session);
+	}
+	if (params.minDuration != null) {
+		const min = params.minDuration;
+		filtered = filtered.filter((r) => r.durationMs >= min);
+	}
+	if (params.maxDuration != null) {
+		const max = params.maxDuration;
+		filtered = filtered.filter((r) => r.durationMs <= max);
+	}
+	if (params.search) {
+		const term = params.search.toLowerCase();
+		filtered = filtered.filter((r) => r.path?.toLowerCase().includes(term) || r.procedures?.some((p) => p.procedure.toLowerCase().includes(term)) || r.method?.toLowerCase().includes(term) || r.requestId?.includes(term));
+	}
+	const sortField = params.sort ?? "timestamp";
+	const desc = (params.order ?? "desc") === "desc";
+	filtered = sortEntries(filtered, sortField, desc);
+	return paginate(filtered, params);
+}
+function queryErrors(entries, params) {
+	let filtered = entries;
+	if (params.status) {
+		const status = params.status;
+		filtered = filtered.filter((e) => matchesStatus(e.status, status));
+	}
+	if (params.procedure) {
+		const proc = params.procedure.toLowerCase();
+		filtered = filtered.filter((e) => e.procedure.toLowerCase().includes(proc));
+	}
+	if (params.path) {
+		const path = params.path.toLowerCase();
+		filtered = filtered.filter((e) => e.procedure.toLowerCase().includes(path));
+	}
+	if (params.minDuration != null) {
+		const min = params.minDuration;
+		filtered = filtered.filter((e) => e.durationMs >= min);
+	}
+	if (params.maxDuration != null) {
+		const max = params.maxDuration;
+		filtered = filtered.filter((e) => e.durationMs <= max);
+	}
+	if (params.search) {
+		const term = params.search.toLowerCase();
+		filtered = filtered.filter((e) => e.procedure.toLowerCase().includes(term) || e.error.toLowerCase().includes(term) || e.code.toLowerCase().includes(term) || e.requestId.includes(term));
+	}
+	const sortField = params.sort ?? "timestamp";
+	const desc = (params.order ?? "desc") === "desc";
+	filtered = sortEntries(filtered, sortField, desc);
+	return paginate(filtered, params);
+}
+function queryTasks(entries, params) {
+	let filtered = entries;
+	if (params.status) {
+		const status = params.status;
+		filtered = filtered.filter((t) => status === "error" ? t.status === "error" : t.status === "success");
+	}
+	if (params.search) {
+		const term = params.search.toLowerCase();
+		filtered = filtered.filter((t) => t.taskName.toLowerCase().includes(term) || (t.error?.toLowerCase().includes(term) ?? false));
+	}
+	if (params.minDuration != null) {
+		const min = params.minDuration;
+		filtered = filtered.filter((t) => t.durationMs >= min);
+	}
+	const sortField = params.sort ?? "timestamp";
+	const desc = (params.order ?? "desc") === "desc";
+	filtered = sortEntries(filtered, sortField, desc);
+	return paginate(filtered, params);
+}
+function sortEntries(entries, field, desc) {
+	const sorted = [...entries];
+	sorted.sort((a, b) => {
+		const va = a[field];
+		const vb = b[field];
+		if (va == null && vb == null) return 0;
+		if (va == null) return 1;
+		if (vb == null) return -1;
+		if (typeof va === "number" && typeof vb === "number") return desc ? vb - va : va - vb;
+		if (typeof va === "string" && typeof vb === "string") return desc ? vb.localeCompare(va) : va.localeCompare(vb);
+		return 0;
+	});
+	return sorted;
+}
+function paginate(entries, params) {
+	const limit = params.limit ?? 50;
+	const total = entries.length;
+	let start = 0;
+	if (params.cursor != null) {
+		const idx = entries.findIndex((e) => e.id === params.cursor);
+		start = idx === -1 ? 0 : idx + 1;
+	} else if (params.before != null) {
+		const idx = entries.findIndex((e) => e.id === params.before);
+		start = idx === -1 ? 0 : Math.max(0, idx - limit);
+	}
+	const data = entries.slice(start, start + limit);
+	const hasMore = start + limit < total;
+	return {
+		data,
+		total,
+		hasMore,
+		nextCursor: hasMore && data.length > 0 ? data[data.length - 1].id : null,
+		prevCursor: start > 0 && data.length > 0 ? data[0].id : null
+	};
+}
+//#endregion
+export { parseQueryParams, queryErrors, queryRequests, queryTasks };

package/dist/plugins/analytics-sse.d.mts

@@ -0,0 +1,31 @@
+import { ErrorEntry, RequestEntry, TaskExecution } from "./analytics.mjs";
+
+//#region src/plugins/analytics-sse.d.ts
+type AnalyticsEvent = {
+  type: 'request';
+  data: RequestEntry;
+} | {
+  type: 'error';
+  data: ErrorEntry;
+} | {
+  type: 'task';
+  data: TaskExecution;
+} | {
+  type: 'stats';
+  data: unknown;
+};
+declare class AnalyticsSSEHub {
+  #private;
+  constructor();
+  /** Start periodic stats broadcast. */
+  startStatsBroadcast(getStats: () => unknown, intervalMs?: number): void;
+  /** Broadcast an event to all connected clients. */
+  broadcast(event: AnalyticsEvent): void;
+  /** Create an SSE ReadableStream for a new client connection. */
+  createStream(): ReadableStream<Uint8Array>;
+  /** Number of connected clients. */
+  get clientCount(): number;
+  dispose(): void;
+}
+//#endregion
+export { AnalyticsSSEHub };

package/dist/plugins/analytics-sse.mjs

@@ -0,0 +1,74 @@
+import { encodeEventMessage } from "../core/sse.mjs";
+//#region src/plugins/analytics-sse.ts
+/**
+* Analytics SSE — real-time event streaming for the analytics dashboard.
+*/
+var AnalyticsSSEHub = class {
+	#clients = /* @__PURE__ */ new Set();
+	#statsInterval = null;
+	#getStats = null;
+	constructor() {}
+	/** Start periodic stats broadcast. */
+	startStatsBroadcast(getStats, intervalMs = 5e3) {
+		this.#getStats = getStats;
+		this.#statsInterval = setInterval(() => {
+			if (this.#clients.size > 0 && this.#getStats) this.broadcast({
+				type: "stats",
+				data: this.#getStats()
+			});
+		}, intervalMs);
+		if (typeof this.#statsInterval === "object" && "unref" in this.#statsInterval) this.#statsInterval.unref();
+	}
+	/** Broadcast an event to all connected clients. */
+	broadcast(event) {
+		if (this.#clients.size === 0) return;
+		const message = encodeEventMessage({
+			event: event.type,
+			data: JSON.stringify(event.data)
+		});
+		for (const controller of this.#clients) try {
+			controller.enqueue(message);
+		} catch {
+			this.#clients.delete(controller);
+		}
+	}
+	/** Create an SSE ReadableStream for a new client connection. */
+	createStream() {
+		let controller;
+		let keepAliveTimer;
+		return new ReadableStream({
+			start: (ctrl) => {
+				controller = ctrl;
+				this.#clients.add(controller);
+				controller.enqueue(encodeEventMessage({ comment: "connected" }));
+				keepAliveTimer = setInterval(() => {
+					try {
+						controller.enqueue(encodeEventMessage({ comment: "keepalive" }));
+					} catch {
+						clearInterval(keepAliveTimer);
+						this.#clients.delete(controller);
+					}
+				}, 15e3);
+				if (typeof keepAliveTimer === "object" && "unref" in keepAliveTimer) keepAliveTimer.unref();
+			},
+			cancel: () => {
+				clearInterval(keepAliveTimer);
+				this.#clients.delete(controller);
+			}
+		}).pipeThrough(new TextEncoderStream());
+	}
+	/** Number of connected clients. */
+	get clientCount() {
+		return this.#clients.size;
+	}
+	dispose() {
+		if (this.#statsInterval) clearInterval(this.#statsInterval);
+		this.#statsInterval = null;
+		for (const controller of this.#clients) try {
+			controller.close();
+		} catch {}
+		this.#clients.clear();
+	}
+};
+//#endregion
+export { AnalyticsSSEHub };

package/dist/plugins/analytics-timeseries.d.mts

@@ -0,0 +1,50 @@
+//#region src/plugins/analytics-timeseries.d.ts
+/**
+ * Analytics Time-Series — multi-tier bucketed aggregation with automatic downsampling.
+ *
+ * Three tiers:
+ * - minute: 1-minute buckets, last 60 minutes
+ * - hour: 1-hour buckets, last 24 hours
+ * - day: 1-day buckets, last 30 days
+ */
+interface TimeSeriesBucket {
+  time: number;
+  count: number;
+  errors: number;
+  totalLatency: number;
+  minLatency: number;
+  maxLatency: number;
+}
+interface TimeSeriesSnapshot {
+  time: number;
+  count: number;
+  errors: number;
+  errorRate: number;
+  avgLatency: number;
+  minLatency: number;
+  maxLatency: number;
+}
+type TimeRange = '1h' | '6h' | '24h' | '7d' | '30d';
+declare class TimeSeriesAggregator {
+  #private;
+  constructor();
+  /** Record a request. */
+  record(durationMs: number, isError: boolean): void;
+  /** Get time-series for a given range. */
+  query(range: TimeRange): TimeSeriesSnapshot[];
+  /** Export state for persistence. */
+  toJSON(): {
+    minutes: TimeSeriesBucket[];
+    hours: TimeSeriesBucket[];
+    days: TimeSeriesBucket[];
+  };
+  /** Restore from persisted state. */
+  hydrate(data: {
+    minutes?: TimeSeriesBucket[];
+    hours?: TimeSeriesBucket[];
+    days?: TimeSeriesBucket[];
+  }): void;
+  dispose(): void;
+}
+//#endregion
+export { TimeSeriesAggregator };

package/dist/plugins/analytics-timeseries.mjs

@@ -0,0 +1,169 @@
+//#region src/plugins/analytics-timeseries.ts
+const MINUTE_MS = 6e4;
+const HOUR_MS = 36e5;
+const DAY_MS = 864e5;
+const MAX_MINUTE_BUCKETS = 60;
+const MAX_HOUR_BUCKETS = 24;
+const MAX_DAY_BUCKETS = 30;
+var TimeSeriesAggregator = class {
+	#minutes = [];
+	#hours = [];
+	#days = [];
+	#currentMinute = null;
+	#rollupTimer = null;
+	constructor() {
+		this.#rollupTimer = setInterval(() => this.#rollup(), MINUTE_MS);
+		if (typeof this.#rollupTimer === "object" && "unref" in this.#rollupTimer) this.#rollupTimer.unref();
+	}
+	/** Record a request. */
+	record(durationMs, isError) {
+		const now = Date.now();
+		const minuteStart = now - now % MINUTE_MS;
+		if (!this.#currentMinute || this.#currentMinute.time !== minuteStart) {
+			if (this.#currentMinute) {
+				this.#minutes.push(this.#currentMinute);
+				if (this.#minutes.length > MAX_MINUTE_BUCKETS) this.#minutes.shift();
+			}
+			this.#currentMinute = createBucket(minuteStart);
+		}
+		this.#currentMinute.count++;
+		if (isError) this.#currentMinute.errors++;
+		this.#currentMinute.totalLatency += durationMs;
+		if (durationMs < this.#currentMinute.minLatency) this.#currentMinute.minLatency = durationMs;
+		if (durationMs > this.#currentMinute.maxLatency) this.#currentMinute.maxLatency = durationMs;
+	}
+	/** Get time-series for a given range. */
+	query(range) {
+		this.#flushCurrentMinute();
+		switch (range) {
+			case "1h": return this.#minutes.map(toSnapshot);
+			case "6h": {
+				const cutoff = Date.now() - 6 * HOUR_MS;
+				const hourData = this.#hours.filter((b) => b.time >= cutoff).map(toSnapshot);
+				const minuteData = this.#minutes.map(toSnapshot);
+				return [...hourData, ...minuteData];
+			}
+			case "24h": return this.#hours.map(toSnapshot);
+			case "7d": {
+				const cutoff = Date.now() - 7 * DAY_MS;
+				return this.#days.filter((b) => b.time >= cutoff).map(toSnapshot);
+			}
+			case "30d": return this.#days.map(toSnapshot);
+		}
+	}
+	/** Export state for persistence. */
+	toJSON() {
+		this.#flushCurrentMinute();
+		return {
+			minutes: this.#minutes,
+			hours: this.#hours,
+			days: this.#days
+		};
+	}
+	/** Restore from persisted state. */
+	hydrate(data) {
+		if (Array.isArray(data.minutes)) this.#minutes = data.minutes;
+		if (Array.isArray(data.hours)) this.#hours = data.hours;
+		if (Array.isArray(data.days)) this.#days = data.days;
+	}
+	#flushCurrentMinute() {
+		if (this.#currentMinute && this.#currentMinute.count > 0) {
+			const minuteStart = Date.now() - Date.now() % MINUTE_MS;
+			if (this.#currentMinute.time !== minuteStart) {
+				this.#minutes.push(this.#currentMinute);
+				if (this.#minutes.length > MAX_MINUTE_BUCKETS) this.#minutes.shift();
+				this.#currentMinute = null;
+			}
+		}
+	}
+	#rollup() {
+		const now = Date.now();
+		const hourStart = now - now % HOUR_MS;
+		const completedMinutes = this.#minutes.filter((b) => b.time < hourStart);
+		if (completedMinutes.length > 0) {
+			const byHour = /* @__PURE__ */ new Map();
+			for (const b of completedMinutes) {
+				const hStart = b.time - b.time % HOUR_MS;
+				const arr = byHour.get(hStart);
+				if (arr) arr.push(b);
+				else byHour.set(hStart, [b]);
+			}
+			for (const [hStart, buckets] of byHour) {
+				const existing = this.#hours.find((h) => h.time === hStart);
+				if (existing) mergeBucketInto(existing, buckets);
+				else {
+					this.#hours.push(mergeBuckets(hStart, buckets));
+					if (this.#hours.length > MAX_HOUR_BUCKETS) this.#hours.shift();
+				}
+			}
+			this.#minutes = this.#minutes.filter((b) => b.time >= hourStart);
+		}
+		const dayStart = now - now % DAY_MS;
+		const completedHours = this.#hours.filter((b) => b.time < dayStart);
+		if (completedHours.length > 0) {
+			const byDay = /* @__PURE__ */ new Map();
+			for (const b of completedHours) {
+				const dStart = b.time - b.time % DAY_MS;
+				const arr = byDay.get(dStart);
+				if (arr) arr.push(b);
+				else byDay.set(dStart, [b]);
+			}
+			for (const [dStart, buckets] of byDay) {
+				const existing = this.#days.find((d) => d.time === dStart);
+				if (existing) mergeBucketInto(existing, buckets);
+				else {
+					this.#days.push(mergeBuckets(dStart, buckets));
+					if (this.#days.length > MAX_DAY_BUCKETS) this.#days.shift();
+				}
+			}
+			this.#hours = this.#hours.filter((b) => b.time >= dayStart);
+		}
+	}
+	dispose() {
+		if (this.#rollupTimer) clearInterval(this.#rollupTimer);
+		this.#rollupTimer = null;
+	}
+};
+function createBucket(time) {
+	return {
+		time,
+		count: 0,
+		errors: 0,
+		totalLatency: 0,
+		minLatency: Infinity,
+		maxLatency: 0
+	};
+}
+function mergeBuckets(time, buckets) {
+	const merged = createBucket(time);
+	for (const b of buckets) {
+		merged.count += b.count;
+		merged.errors += b.errors;
+		merged.totalLatency += b.totalLatency;
+		if (b.minLatency < merged.minLatency) merged.minLatency = b.minLatency;
+		if (b.maxLatency > merged.maxLatency) merged.maxLatency = b.maxLatency;
+	}
+	return merged;
+}
+function mergeBucketInto(target, buckets) {
+	for (const b of buckets) {
+		target.count += b.count;
+		target.errors += b.errors;
+		target.totalLatency += b.totalLatency;
+		if (b.minLatency < target.minLatency) target.minLatency = b.minLatency;
+		if (b.maxLatency > target.maxLatency) target.maxLatency = b.maxLatency;
+	}
+}
+function toSnapshot(b) {
+	return {
+		time: b.time,
+		count: b.count,
+		errors: b.errors,
+		errorRate: b.count > 0 ? b.errors / b.count * 100 : 0,
+		avgLatency: b.count > 0 ? b.totalLatency / b.count : 0,
+		minLatency: b.minLatency === Infinity ? 0 : b.minLatency,
+		maxLatency: b.maxLatency
+	};
+}
+//#endregion
+export { TimeSeriesAggregator };

package/dist/plugins/analytics.d.mts

@@ -1,18 +1,10 @@
+import { BudgetRule, CostTracker, SpanCost } from "./analytics-cost.mjs";
+import { AlertEngine, AlertRule } from "./analytics-alerts.mjs";
+import { AnalyticsSSEHub } from "./analytics-sse.mjs";
+import { TimeSeriesAggregator } from "./analytics-timeseries.mjs";
 import { FetchHandler } from "../core/handler.mjs";
 
 //#region src/plugins/analytics.d.ts
-/**
- * Built-in analytics plugin — zero-dependency monitoring with deep error tracing.
- *
- * - Per-procedure metrics (count, errors, latency percentiles) via ring buffers
- * - Full error log with input, headers, stack trace, custom spans
- * - `trace()` helper for measuring DB queries, API calls, etc.
- * - "Copy for AI" — one-click markdown export of any error
- * - HTTP-level request tracking with procedure grouping (batch support)
- * - Unique request IDs via `x-request-id` response header
- *
- * Dashboard at /api/analytics, JSON API at /api/analytics/stats, errors at /api/analytics/errors.
- */
 interface TimeWindow {
   time: number;
   count: number;
@@ -30,6 +22,8 @@ interface TraceSpan {
   error?: string;
   /** Structured key-value attributes (db.name, auth.operation, user.id, etc.) */
   attributes?: Record<string, string | number | boolean>;
+  /** Cost metadata for this span (tokens, price, provider). */
+  cost?: SpanCost;
 }
 interface ErrorEntry {
   id: number;
@@ -66,6 +60,7 @@ interface RequestEntry {
   timestamp: number;
   durationMs: number;
   method: string;
+  url: string;
   path: string;
   ip: string;
   headers: Record<string, string>;
@@ -74,6 +69,10 @@ interface RequestEntry {
   status: number;
   procedures: ProcedureCall[];
   isBatch: boolean;
+  /** Trace ID for correlating related requests across services. */
+  traceId?: string;
+  /** Parent request ID — links child requests to the originating request. */
+  parentRequestId?: string;
 }
 /** A background task execution record. */
 interface TaskExecution {
@@ -93,12 +92,6 @@ interface AnalyticsOptions {
   bufferSize?: number;
   /** Time-series history in seconds (default: 120) */
   historySeconds?: number;
-  /** Max error entries to keep (default: 100) */
-  maxErrors?: number;
-  /** Max recent request entries to keep (default: 200) */
-  maxRequests?: number;
-  /** Max task execution entries to keep (default: 200) */
-  maxTasks?: number;
   /**
    * Protect dashboard access.
    * - `string` — secret token checked against `Authorization: Bearer <token>` header or `?token=` query param
@@ -108,6 +101,14 @@ interface AnalyticsOptions {
   auth?: string | ((req: Request) => boolean | Promise<boolean>);
   /** Interval in ms between storage flushes (default: 5000) */
   flushInterval?: number;
+  /** Days to retain entries in storage (default: 30). Entries older than this are pruned on flush. */
+  retentionDays?: number;
+  /** Path prefixes to exclude from tracking. Can also be managed at runtime via the dashboard or API. */
+  ignorePaths?: string[];
+  /** Alert rules — fire actions when conditions are met within a sliding window. */
+  alerts?: AlertRule[];
+  /** Budget rules for cost tracking. */
+  budgets?: BudgetRule[];
 }
 interface ProcedureSnapshot {
   count: number;
@@ -188,7 +189,22 @@ declare function trace<T>(ctx: Record<string, unknown>, name: string, fn: () =>
 }): Promise<T>;
 declare class AnalyticsCollector {
   #private;
+  /** SSE hub for real-time streaming */
+  sseHub: AnalyticsSSEHub;
+  /** Multi-tier time-series aggregation */
+  timeseries: TimeSeriesAggregator;
+  /** Alert engine */
+  alertEngine: AlertEngine | null;
+  /** Cost tracker */
+  costTracker: CostTracker;
   constructor(options?: AnalyticsOptions);
+  /** Check if a path is server-side ignored (from config). */
+  isIgnored(pathname: string): boolean;
+  /** Check if a path is hidden in the dashboard (from runtime API). */
+  isHidden(pathname: string): boolean;
+  addHiddenPath(path: string): void;
+  removeHiddenPath(path: string): void;
+  getHiddenPaths(): string[];
   record(path: string, durationMs: number): void;
   recordError(path: string, durationMs: number, errorMsg: string): void;
   recordDetailedError(entry: Omit<ErrorEntry, 'id'>): void;
@@ -204,10 +220,12 @@ declare class RequestAccumulator {
   #private;
   readonly requestId: string;
   readonly sessionId: string;
+  readonly traceId: string;
+  readonly parentRequestId?: string;
   /** True if a new session cookie needs to be set. */
   readonly isNewSession: boolean;
   t0: number;
-  constructor(request: Request, collector: AnalyticsCollector);
+  constructor(request: Request, collector: AnalyticsCollector, traceId?: string, parentRequestId?: string);
   addProcedure(call: ProcedureCall): void;
   /** Get Set-Cookie header value (only if new session). */
   getSessionCookie(): string | null;
@@ -224,7 +242,7 @@ declare function sanitizeHeaders(headers: Headers): Record<string, string>;
 /** Return auth-failure response for analytics routes. */
 declare function analyticsAuthResponse(pathname: string): Response;
 /** Serve analytics dashboard and API routes. */
-declare function serveAnalyticsRoute(pathname: string, collector: AnalyticsCollector, dashboardHtml: string | undefined): Promise<Response>;
+declare function serveAnalyticsRoute(pathname: string, request: Request, collector: AnalyticsCollector, dashboardHtml: string | undefined): Promise<Response>;
 /**
  * Wrap a fetch handler with analytics collection.
  * Intercepts analytics dashboard routes and instruments every request.