@buenojs/bueno 0.8.4 → 0.8.6

package/src/observability/index.ts

@@ -0,0 +1,136 @@
+/**
+ * Observability Module
+ *
+ * Provides structured error tracking and observability integration for Bueno.
+ * Implement ErrorReporter to send events to Sentry, Bugsnag, Datadog, or any
+ * custom backend — zero SDK dependencies shipped by the framework.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { createApp } from '@buenojs/bueno';
+ * import { ObservabilityModule } from '@buenojs/bueno/observability';
+ *
+ * const app = createApp(AppModule);
+ *
+ * // Wire everything with a single call
+ * const obs = ObservabilityModule.setup(app, {
+ *   reporter: new MyReporter(),
+ *   breadcrumbsSize: 20,
+ *   ignoreStatusCodes: [404, 401],
+ *   tags: { environment: 'production' },
+ * });
+ *
+ * await app.listen(3000);
+ * ```
+ *
+ * ## Writing a reporter (Sentry example)
+ *
+ * ```typescript
+ * import * as Sentry from '@sentry/node';
+ * import type { ErrorReporter, ErrorEvent } from '@buenojs/bueno/observability';
+ *
+ * class SentryReporter implements ErrorReporter {
+ *   constructor(dsn: string) { Sentry.init({ dsn }); }
+ *
+ *   captureError(event: ErrorEvent) {
+ *     Sentry.withScope(scope => {
+ *       if (event.user)    scope.setUser(event.user);
+ *       if (event.traceId) scope.setTag('traceId', event.traceId);
+ *       event.breadcrumbs.forEach(b => scope.addBreadcrumb(b));
+ *       Sentry.captureException(event.error);
+ *     });
+ *   }
+ *
+ *   async flush() { await Sentry.flush(2000); }
+ * }
+ *
+ * ObservabilityModule.setup(app, {
+ *   reporter: new SentryReporter(process.env.SENTRY_DSN),
+ * });
+ * ```
+ */
+
+import type { Application } from "../modules";
+import { ObservabilityService } from "./service";
+import { ObservabilityInterceptor } from "./interceptor";
+import type { ObservabilityOptions } from "./types";
+
+/**
+ * Static module class for configuring observability.
+ * Use `ObservabilityModule.setup(app, options)` for the simplest setup.
+ */
+export class ObservabilityModule {
+	/**
+	 * One-call setup: creates the ObservabilityService, registers the global
+	 * interceptor for trace ID injection and breadcrumb tracking, and wires
+	 * process-level shutdown flush.
+	 *
+	 * Call this before `app.listen()`.
+	 *
+	 * @param app - The Bueno Application instance (from `createApp()`)
+	 * @param options - Observability configuration including the reporter
+	 * @returns The ObservabilityService — use for manual captureError / addBreadcrumb
+	 *
+	 * @example
+	 * ```typescript
+	 * const obs = ObservabilityModule.setup(app, {
+	 *   reporter: new SentryReporter(process.env.SENTRY_DSN),
+	 *   ignoreStatusCodes: [404, 401],
+	 *   tags: { environment: 'production', version: '1.2.3' },
+	 * });
+	 *
+	 * // Later, in a background job:
+	 * obs.captureError(new Error('Job failed'));
+	 *
+	 * // Add a manual breadcrumb:
+	 * obs.addBreadcrumb({ type: 'custom', level: 'info', message: 'Checkout started' });
+	 * ```
+	 */
+	static setup(
+		app: Application,
+		options: ObservabilityOptions,
+	): ObservabilityService {
+		const service = new ObservabilityService(options);
+		const interceptor = new ObservabilityInterceptor(service);
+
+		// Register global interceptor for trace ID injection + breadcrumbs + error capture
+		app.useGlobalInterceptors(interceptor);
+
+		// Register flush on process exit
+		service.registerShutdown();
+
+		return service;
+	}
+}
+
+// ============= Public Exports =============
+
+// Types
+export type {
+	BreadcrumbEntry,
+	ErrorEvent,
+	ErrorRequestContext,
+	ErrorUserContext,
+	MessageEvent,
+	ErrorReporter,
+	ObservabilityOptions,
+	ObservabilityConfig,
+} from "./types";
+
+// Service & helpers
+export { ObservabilityService } from "./service";
+export { extractTraceContext } from "./service";
+
+// Interceptor
+export { ObservabilityInterceptor } from "./interceptor";
+
+// Breadcrumb utilities
+export {
+	BreadcrumbCollector,
+	httpBreadcrumb,
+	logBreadcrumb,
+} from "./breadcrumbs";
+
+// Trace helpers
+export { generateTraceId, generateSpanId, buildTraceparent } from "./trace";

package/src/observability/interceptor.ts

@@ -0,0 +1,85 @@
+/**
+ * ObservabilityInterceptor
+ *
+ * Global interceptor that enriches every request with:
+ * 1. Trace/span IDs — extracted from W3C `traceparent` header or generated fresh
+ * 2. Breadcrumbs — records request entry and exit (with status + duration)
+ * 3. Error capture — calls ObservabilityService when a route handler throws
+ *
+ * Register via ObservabilityModule.setup() (done automatically).
+ */
+
+import type { Context } from "../context";
+import type { CallHandler, NestInterceptor } from "../modules";
+import { generateSpanId, generateTraceId } from "./trace";
+import { httpBreadcrumb } from "./breadcrumbs";
+import type { ObservabilityService } from "./service";
+import { extractTraceContext } from "./service";
+
+/**
+ * Resolves trace context from the incoming request.
+ * Uses the W3C `traceparent` header if present, otherwise generates new IDs.
+ */
+function resolveTraceIds(context: Context): {
+	traceId: string;
+	spanId: string;
+} {
+	const existing = extractTraceContext(context);
+	if (existing.traceId && existing.spanId) {
+		return { traceId: existing.traceId, spanId: existing.spanId };
+	}
+	return { traceId: generateTraceId(), spanId: generateSpanId() };
+}
+
+export class ObservabilityInterceptor implements NestInterceptor {
+	constructor(private readonly service: ObservabilityService) {}
+
+	async intercept(context: Context, next: CallHandler): Promise<unknown> {
+		const startMs = Date.now();
+
+		// 1. Inject trace IDs into context for downstream use
+		const { traceId, spanId } = resolveTraceIds(context);
+		context.set("traceId", traceId);
+		context.set("spanId", spanId);
+
+		// 2. Record request entry breadcrumb
+		this.service.addBreadcrumb({
+			type: "navigation",
+			level: "info",
+			message: `${context.method} ${context.path}`,
+			data: { traceId, spanId },
+		});
+
+		try {
+			const result = await next.handle();
+
+			// 3a. Record successful request exit
+			const durationMs = Date.now() - startMs;
+			const response = result as Response | null;
+			const statusCode =
+				response instanceof Response ? response.status : undefined;
+
+			this.service
+				.getBreadcrumbCollector()
+				.add(
+					httpBreadcrumb(context.method, context.path, statusCode, durationMs),
+				);
+
+			return result;
+		} catch (error) {
+			// 3b. Capture the error with full request context (non-blocking)
+			this.service.captureFromContext(context, error as Error);
+
+			// 4. Record failed request breadcrumb
+			const durationMs = Date.now() - startMs;
+			this.service
+				.getBreadcrumbCollector()
+				.add(
+					httpBreadcrumb(context.method, context.path, undefined, durationMs),
+				);
+
+			// 5. Rethrow so the framework's exception filters still fire
+			throw error;
+		}
+	}
+}

package/src/observability/service.ts

@@ -0,0 +1,303 @@
+/**
+ * ObservabilityService
+ *
+ * Central service that assembles ErrorEvents and dispatches them to the
+ * configured ErrorReporter. Error capture happens through the
+ * ObservabilityInterceptor which calls captureFromContext() directly.
+ *
+ * Exposes addBreadcrumb() and captureError() for manual instrumentation
+ * throughout the application.
+ */
+
+import type { Context } from "../context";
+import { BreadcrumbCollector, httpBreadcrumb } from "./breadcrumbs";
+import type {
+	BreadcrumbEntry,
+	ErrorEvent,
+	ErrorReporter,
+	ErrorUserContext,
+	MessageEvent,
+	ObservabilityOptions,
+} from "./types";
+
+// ============= Helpers =============
+
+function generateId(): string {
+	const bytes = new Uint8Array(16);
+	crypto.getRandomValues(bytes);
+	return Array.from(bytes)
+		.map((b) => b.toString(16).padStart(2, "0"))
+		.join("");
+}
+
+function extractSafeHeaders(req: Request): Record<string, string> {
+	const safe: Record<string, string> = {};
+	const sensitiveHeaders = new Set([
+		"authorization",
+		"cookie",
+		"x-api-key",
+		"x-auth-token",
+		"proxy-authorization",
+	]);
+	req.headers.forEach((value, key) => {
+		if (!sensitiveHeaders.has(key.toLowerCase())) {
+			safe[key] = value;
+		}
+	});
+	return safe;
+}
+
+function getStatusCode(error: Error): number | undefined {
+	const e = error as Error & { statusCode?: number; status?: number };
+	return e.statusCode ?? e.status;
+}
+
+// ============= Service =============
+
+/**
+ * ObservabilityService manages error reporting and breadcrumb tracking.
+ *
+ * Use ObservabilityModule.setup(app, options) to wire it to the application,
+ * or instantiate directly for contexts where the full module isn't needed.
+ *
+ * @example
+ * ```typescript
+ * // Via ObservabilityModule (recommended):
+ * const obs = ObservabilityModule.setup(app, {
+ *   reporter: new SentryReporter(),
+ * });
+ *
+ * // Manual breadcrumb:
+ * obs.addBreadcrumb({
+ *   type: 'custom',
+ *   level: 'info',
+ *   message: 'User completed checkout',
+ *   data: { orderId: '123' }
+ * });
+ * ```
+ */
+export class ObservabilityService {
+	private readonly reporter: ErrorReporter;
+	private readonly breadcrumbs: BreadcrumbCollector;
+	private readonly options: {
+		breadcrumbsSize: number;
+		ignoreErrors: Array<new (...args: unknown[]) => Error>;
+		ignoreStatusCodes: number[];
+		tags: Record<string, string>;
+		captureUnhandled: boolean;
+	};
+
+	constructor(options: ObservabilityOptions) {
+		this.reporter = options.reporter;
+		this.options = {
+			breadcrumbsSize: options.breadcrumbsSize ?? 20,
+			ignoreErrors: options.ignoreErrors ?? [],
+			ignoreStatusCodes: options.ignoreStatusCodes ?? [],
+			tags: options.tags ?? {},
+			captureUnhandled: options.captureUnhandled ?? false,
+		};
+		this.breadcrumbs = new BreadcrumbCollector(this.options.breadcrumbsSize);
+
+		if (this.options.captureUnhandled) {
+			this.setupUnhandledCapture();
+		}
+	}
+
+	// ============= Framework Integration =============
+
+	/**
+	 * Called by ObservabilityInterceptor when an HTTP route throws.
+	 * Assembles a full ErrorEvent with request context and dispatches it.
+	 * Non-blocking — never delays the HTTP response.
+	 */
+	captureFromContext(context: Context, error: Error): void {
+		if (this.shouldIgnore(error)) return;
+
+		// Add a breadcrumb for the failed request entry
+		this.breadcrumbs.add(
+			httpBreadcrumb(context.method, context.path, undefined),
+		);
+
+		const event = this.assembleEvent(error, "error", context);
+		this.dispatchAsync(event);
+	}
+
+	/**
+	 * Register flush on process shutdown.
+	 * Called automatically by ObservabilityModule.setup().
+	 */
+	registerShutdown(): void {
+		const flush = async () => {
+			if (this.reporter.flush) {
+				try {
+					await this.reporter.flush();
+				} catch (err) {
+					console.error("[ObservabilityService] Reporter flush failed:", err);
+				}
+			}
+		};
+
+		process.once("beforeExit", () => {
+			flush().catch(console.error);
+		});
+	}
+
+	// ============= Public API =============
+
+	/**
+	 * Manually capture an error outside the HTTP pipeline.
+	 * Useful inside background jobs, event listeners, scheduled tasks.
+	 *
+	 * @example
+	 * obs.captureError(new Error('Payment failed'), 'error');
+	 */
+	captureError(error: Error, level: ErrorEvent["level"] = "error"): void {
+		if (this.shouldIgnore(error)) return;
+		const event = this.assembleEvent(error, level);
+		this.dispatchAsync(event);
+	}
+
+	/**
+	 * Manually capture a non-error message.
+	 *
+	 * @example
+	 * obs.captureMessage('Deployment completed', 'info', { version: '2.0.0' });
+	 */
+	captureMessage(
+		message: string,
+		level: MessageEvent["level"] = "info",
+		extra?: Record<string, unknown>,
+	): void {
+		if (!this.reporter.captureMessage) return;
+		const event: MessageEvent = {
+			id: generateId(),
+			timestamp: new Date(),
+			message,
+			level,
+			extra,
+		};
+		this.dispatchMessageAsync(event);
+	}
+
+	/**
+	 * Add a breadcrumb to the ring buffer.
+	 * Breadcrumbs recorded here are included in the next error event.
+	 *
+	 * @example
+	 * obs.addBreadcrumb({
+	 *   type: 'custom',
+	 *   level: 'info',
+	 *   message: 'Fetched user from database',
+	 *   data: { userId: 42 }
+	 * });
+	 */
+	addBreadcrumb(
+		entry: Omit<BreadcrumbEntry, "timestamp"> & { timestamp?: Date },
+	): void {
+		this.breadcrumbs.add({
+			...entry,
+			timestamp: entry.timestamp ?? new Date(),
+		});
+	}
+
+	/**
+	 * Access the underlying BreadcrumbCollector.
+	 * Used internally by ObservabilityInterceptor.
+	 */
+	getBreadcrumbCollector(): BreadcrumbCollector {
+		return this.breadcrumbs;
+	}
+
+	// ============= Private =============
+
+	private assembleEvent(
+		error: Error,
+		level: ErrorEvent["level"],
+		context?: Context,
+	): ErrorEvent {
+		const user = context?.get<ErrorUserContext>("user");
+		const traceId = context?.get<string>("traceId") ?? undefined;
+		const spanId = context?.get<string>("spanId") ?? undefined;
+
+		return {
+			id: generateId(),
+			timestamp: new Date(),
+			error,
+			level,
+			request: context
+				? {
+						method: context.method,
+						path: context.path,
+						headers: extractSafeHeaders(context.req),
+						ip: context.ip ?? "",
+						userAgent: context.getHeader("user-agent"),
+					}
+				: undefined,
+			traceId,
+			spanId,
+			user: user ?? undefined,
+			breadcrumbs: this.breadcrumbs.getAll(),
+			tags: { ...this.options.tags },
+		};
+	}
+
+	private shouldIgnore(error: Error): boolean {
+		for (const ErrorClass of this.options.ignoreErrors) {
+			if (error instanceof ErrorClass) return true;
+		}
+		if (this.options.ignoreStatusCodes.length > 0) {
+			const code = getStatusCode(error);
+			if (code !== undefined && this.options.ignoreStatusCodes.includes(code)) {
+				return true;
+			}
+		}
+		return false;
+	}
+
+	private dispatchAsync(event: ErrorEvent): void {
+		// Fire-and-forget — never blocks the HTTP response
+		Promise.resolve(this.reporter.captureError(event)).catch((err) => {
+			console.error("[ObservabilityService] Reporter.captureError failed:", err);
+		});
+	}
+
+	private dispatchMessageAsync(event: MessageEvent): void {
+		if (!this.reporter.captureMessage) return;
+		Promise.resolve(this.reporter.captureMessage(event)).catch((err) => {
+			console.error(
+				"[ObservabilityService] Reporter.captureMessage failed:",
+				err,
+			);
+		});
+	}
+
+	private setupUnhandledCapture(): void {
+		process.on("unhandledRejection", (reason: unknown) => {
+			const error =
+				reason instanceof Error
+					? reason
+					: new Error(String(reason ?? "Unhandled rejection"));
+			this.captureError(error, "error");
+		});
+
+		process.on("uncaughtException", (error: Error) => {
+			this.captureError(error, "fatal");
+		});
+	}
+}
+
+// ============= Trace Context Extraction =============
+
+/**
+ * Extract traceId and spanId from the W3C traceparent header.
+ * Format: 00-<traceId>-<spanId>-<flags>
+ */
+export function extractTraceContext(
+	context: Context,
+): { traceId?: string; spanId?: string } {
+	const traceparent = context.getHeader("traceparent");
+	if (!traceparent) return {};
+	const parts = traceparent.split("-");
+	if (parts.length < 4) return {};
+	return { traceId: parts[1], spanId: parts[2] };
+}

package/src/observability/trace.ts

@@ -0,0 +1,37 @@
+/**
+ * Trace ID generation helpers
+ *
+ * Generates W3C TraceContext-compatible IDs using the Web Crypto API.
+ * These are intentionally kept separate from src/telemetry to avoid
+ * coupling the observability module to the OTLP tracing module.
+ */
+
+/**
+ * Generate a W3C-compatible trace ID (32 hex characters / 16 bytes)
+ */
+export function generateTraceId(): string {
+	const bytes = new Uint8Array(16);
+	crypto.getRandomValues(bytes);
+	return Array.from(bytes)
+		.map((b) => b.toString(16).padStart(2, "0"))
+		.join("");
+}
+
+/**
+ * Generate a W3C-compatible span ID (16 hex characters / 8 bytes)
+ */
+export function generateSpanId(): string {
+	const bytes = new Uint8Array(8);
+	crypto.getRandomValues(bytes);
+	return Array.from(bytes)
+		.map((b) => b.toString(16).padStart(2, "0"))
+		.join("");
+}
+
+/**
+ * Build a W3C `traceparent` header value from traceId + spanId.
+ * Format: 00-<traceId>-<spanId>-01
+ */
+export function buildTraceparent(traceId: string, spanId: string): string {
+	return `00-${traceId}-${spanId}-01`;
+}