@c15t/backend 2.0.0-rc.0 → 2.0.0-rc.10

package/src/utils/create-telemetry-options.ts

@@ -1,229 +0,0 @@
-import {
-	context,
-	type Meter,
-	metrics,
-	type Span,
-	SpanStatusCode,
-	trace,
-} from '@opentelemetry/api';
-import type { C15TOptions } from '../types';
-import { version } from '../version';
-import { extractErrorMessage } from './extract-error-message';
-
-type TelemetryConfig = NonNullable<C15TOptions['advanced']>['telemetry'];
-
-// ── Cached config (set once during init) ──────────────────────────────
-let cachedConfig: TelemetryConfig | null = null;
-let cachedDefaultAttributes: Record<string, string | number | boolean> = {};
-
-/**
- * Creates telemetry configuration from provided options
- *
- * This function merges user-provided telemetry options with sensible defaults,
- * ensuring that service name and version are always properly set.
- *
- * Telemetry is opt-in by default - users must explicitly set enabled: true.
- *
- * @param appName - The application name to use for service.name attribute
- * @param telemetryConfig - Optional user-provided telemetry configuration
- * @param tenantId - Optional tenant ID for multi-tenant deployments
- * @returns Properly structured telemetry options for the OpenTelemetry SDK
- */
-export function createTelemetryOptions(
-	appName = 'c15t',
-	telemetryConfig?: TelemetryConfig,
-	tenantId?: string
-): TelemetryConfig {
-	const defaultAttributes: Record<string, string | number | boolean> = {
-		...(telemetryConfig?.defaultAttributes || {}),
-
-		// Always ensure these core attributes are set
-		'service.name': String(appName),
-		'service.version': version,
-	};
-
-	if (tenantId) {
-		defaultAttributes['tenant.id'] = tenantId;
-	}
-
-	const config: TelemetryConfig = {
-		// Opt-in: disabled by default, must be explicitly enabled
-		enabled: telemetryConfig?.enabled ?? false,
-		tracer: telemetryConfig?.tracer,
-		meter: telemetryConfig?.meter,
-		defaultAttributes,
-	};
-
-	// Cache for use without explicit options
-	cachedConfig = config;
-	cachedDefaultAttributes = defaultAttributes;
-
-	return config;
-}
-
-/**
- * Checks if telemetry is enabled.
- * When called without options, uses the cached config from init.
- */
-export function isTelemetryEnabled(options?: C15TOptions): boolean {
-	if (options) {
-		return options.advanced?.telemetry?.enabled === true;
-	}
-	return cachedConfig?.enabled === true;
-}
-
-/**
- * Gets the tracer for the c15t backend.
- * When called without options, uses the cached config from init.
- */
-export const getTracer = (options?: C15TOptions) => {
-	if (!isTelemetryEnabled(options)) {
-		// Return a no-op tracer when telemetry is disabled
-		return trace.getTracer('c15t-noop');
-	}
-	const tracer = options?.advanced?.telemetry?.tracer ?? cachedConfig?.tracer;
-	if (tracer) {
-		return tracer;
-	}
-	return trace.getTracer(options?.appName ?? 'c15t');
-};
-
-/**
- * Gets the meter for the c15t backend.
- * When called without options, uses the cached config from init.
- */
-export const getMeter = (options?: C15TOptions): Meter => {
-	if (!isTelemetryEnabled(options)) {
-		// Return a no-op meter when telemetry is disabled
-		return metrics.getMeter('c15t-noop');
-	}
-	const meter = options?.advanced?.telemetry?.meter ?? cachedConfig?.meter;
-	if (meter) {
-		return meter;
-	}
-	return metrics.getMeter(options?.appName ?? 'c15t');
-};
-
-/**
- * Gets the cached default attributes.
- * Used by span wrappers when no explicit options are provided.
- */
-export function getDefaultAttributes(): Record<
-	string,
-	string | number | boolean
-> {
-	return cachedDefaultAttributes;
-}
-
-/**
- * Resets the cached telemetry config (for testing).
- */
-export function resetTelemetryConfig(): void {
-	cachedConfig = null;
-	cachedDefaultAttributes = {};
-}
-
-/**
- * Creates a span for an API request
- */
-export const createRequestSpan = (
-	method: string,
-	path: string,
-	options?: C15TOptions
-) => {
-	if (!isTelemetryEnabled(options)) {
-		return null;
-	}
-
-	const tracer = getTracer(options);
-	const defaultAttrs =
-		options?.advanced?.telemetry?.defaultAttributes || getDefaultAttributes();
-
-	const span = tracer.startSpan(`${method} ${path}`, {
-		attributes: {
-			'http.method': method,
-			...defaultAttrs,
-		},
-	});
-
-	return span;
-};
-
-/**
- * Wraps an API request handler in a span.
- * The span is set as active context so child spans nest correctly.
- */
-export const withRequestSpan = async <T>(
-	method: string,
-	path: string,
-	operation: () => Promise<T>,
-	options?: C15TOptions
-): Promise<T> => {
-	const span = createRequestSpan(method, path, options);
-
-	if (!span) {
-		return operation();
-	}
-
-	try {
-		const result = await withSpanContext(span, operation);
-		span.setStatus({ code: SpanStatusCode.OK });
-		return result;
-	} catch (error) {
-		handleSpanError(span, error);
-		throw error;
-	} finally {
-		span.end();
-	}
-};
-
-/**
- * Handles errors in spans
- */
-export const handleSpanError = (span: Span, error: unknown) => {
-	span.setStatus({
-		code: SpanStatusCode.ERROR,
-		message: extractErrorMessage(error),
-	});
-
-	if (error instanceof Error) {
-		span.setAttribute('error.type', error.name);
-	}
-};
-
-/**
- * Gets the current trace context for log correlation.
- * Returns trace and span IDs from the active span.
- *
- * @returns Object with traceId and spanId, or null if no active span
- */
-export function getTraceContext(): {
-	traceId: string;
-	spanId: string;
-} | null {
-	const activeSpan = trace.getActiveSpan();
-	if (!activeSpan) {
-		return null;
-	}
-
-	const spanContext = activeSpan.spanContext();
-	if (!spanContext) {
-		return null;
-	}
-
-	return {
-		traceId: spanContext.traceId,
-		spanId: spanContext.spanId,
-	};
-}
-
-/**
- * Runs a function within a span context, making the span active.
- * This allows nested operations to access the parent span via trace.getActiveSpan().
- */
-export const withSpanContext = async <T>(
-	span: Span,
-	operation: () => Promise<T>
-): Promise<T> => {
-	return context.with(trace.setSpan(context.active(), span), operation);
-};

package/src/utils/env.ts

@@ -1,84 +0,0 @@
-/**
- * Environment variables object
- *
- * Provides access to environment variables in a way that works in both
- * browser and Node.js environments. In Node.js, this will be process.env,
- * and in browsers, it will be an empty object.
- *
- * @returns An object containing environment variables accessible in the current runtime
- *
- * @example
- * ```ts
- * // Access an environment variable
- * const apiKey = env.API_KEY;
- * ```
- */
-export const env = typeof process !== 'undefined' ? process.env : {};
-
-/**
- * Determines if the application is running in production mode
- *
- * Checks if NODE_ENV is set to 'production'. This is useful for
- * conditionally enabling or disabling features based on the environment.
- *
- * @returns Boolean indicating whether the application is running in production mode
- *
- * @example
- * ```ts
- * // Conditionally execute code based on environment
- * if (isProduction) {
- *   // Production-only code
- * }
- * ```
- */
-export const isProduction =
-	typeof process !== 'undefined' && process.env.NODE_ENV === 'production';
-
-/**
- * Converts a string or boolean value to a boolean
- *
- * @param val - The value to convert to boolean
- * @returns `false` if the value is falsy or the string 'false', otherwise `true`
- *
- * @example
- * ```ts
- * toBoolean('true'); // true
- * toBoolean('false'); // false
- * toBoolean(undefined); // false
- * toBoolean(true); // true
- * ```
- *
- * @internal Used for environment variable parsing
- */
-function toBoolean(val: boolean | string | undefined) {
-	return val ? val !== 'false' : false;
-}
-
-/**
- * The current Node.js environment value
- *
- * Retrieves the NODE_ENV environment variable value if available,
- * otherwise returns an empty string.
- *
- * @returns The current NODE_ENV value or empty string if not set
- */
-export const nodeENV =
-	(typeof process !== 'undefined' && process.env && process.env.NODE_ENV) || '';
-
-/**
- * Determines if the application is running in test mode
- *
- * Checks if NODE_ENV is set to 'test' or if the TEST environment
- * variable is truthy and not 'false'.
- *
- * @returns Boolean indicating whether the application is running in test mode
- *
- * @example
- * ```ts
- * // Skip expensive operations in tests
- * if (!isTest) {
- *   runExpensiveOperation();
- * }
- * ```
- */
-export const isTest = nodeENV === 'test' || toBoolean(env.TEST);

package/src/utils/extract-error-message.ts

@@ -1,21 +0,0 @@
-/**
- * Extracts a useful error message from any error type.
- *
- * Handles `AggregateError` (e.g. from Node.js `net.connect` failing on both
- * IPv4/IPv6) where `error.message` is empty but `error.errors[]` contains the
- * real messages.
- */
-export function extractErrorMessage(error: unknown): string {
-	if (error instanceof AggregateError && error.errors?.length > 0) {
-		const inner = error.errors
-			.map((e: unknown) => (e instanceof Error ? e.message : String(e)))
-			.join('; ');
-		return `AggregateError: ${inner}`;
-	}
-
-	if (error instanceof Error) {
-		return error.message || error.name;
-	}
-
-	return String(error);
-}

package/src/utils/instrumentation.test.ts

@@ -1,185 +0,0 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import type { C15TOptions } from '../types';
-import {
-	withCacheSpan,
-	withDatabaseSpan,
-	withExternalSpan,
-} from './instrumentation';
-
-// Mock create-telemetry-options
-vi.mock('./create-telemetry-options', () => {
-	const { SpanStatusCode } = require('@opentelemetry/api');
-
-	const mockSpan = () => ({
-		setStatus: vi.fn(),
-		setAttribute: vi.fn(),
-		updateName: vi.fn(),
-		end: vi.fn(),
-	});
-
-	return {
-		isTelemetryEnabled: vi.fn(
-			(options) => options?.advanced?.telemetry?.enabled === true
-		),
-		getTracer: vi.fn(() => ({
-			startSpan: vi.fn(() => mockSpan()),
-		})),
-		getDefaultAttributes: vi.fn(() => ({
-			'service.name': 'test',
-			'service.version': '1.0.0',
-		})),
-		withSpanContext: vi.fn((_span, operation) => operation()),
-		handleSpanError: vi.fn((span, error) => {
-			span.setStatus({
-				code: SpanStatusCode.ERROR,
-				message: error instanceof Error ? error.message : String(error),
-			});
-			if (error instanceof Error) {
-				span.setAttribute('error.type', error.name);
-			}
-		}),
-	};
-});
-
-afterEach(() => {
-	vi.clearAllMocks();
-});
-
-const enabledOptions: C15TOptions = {
-	trustedOrigins: [],
-	adapter: {} as C15TOptions['adapter'],
-	advanced: {
-		telemetry: {
-			enabled: true,
-		},
-	},
-};
-
-describe('withDatabaseSpan', () => {
-	it('returns operation result when telemetry is disabled', async () => {
-		const result = await withDatabaseSpan(
-			{ operation: 'find', entity: 'subject' },
-			async () => ({ id: '123', name: 'test' })
-		);
-
-		expect(result).toEqual({ id: '123', name: 'test' });
-	});
-
-	it('returns operation result when telemetry is enabled', async () => {
-		const result = await withDatabaseSpan(
-			{ operation: 'find', entity: 'subject' },
-			async () => ({ id: '123', name: 'test' }),
-			enabledOptions
-		);
-
-		expect(result).toEqual({ id: '123', name: 'test' });
-	});
-
-	it('propagates errors from operation', async () => {
-		const error = new Error('DB connection failed');
-
-		await expect(
-			withDatabaseSpan(
-				{ operation: 'find', entity: 'subject' },
-				async () => {
-					throw error;
-				},
-				enabledOptions
-			)
-		).rejects.toThrow('DB connection failed');
-	});
-
-	it('executes operation without span when telemetry is disabled', async () => {
-		const operation = vi.fn().mockResolvedValue('result');
-
-		const result = await withDatabaseSpan(
-			{ operation: 'create', entity: 'consent' },
-			operation
-		);
-
-		expect(result).toBe('result');
-		expect(operation).toHaveBeenCalledTimes(1);
-	});
-});
-
-describe('withExternalSpan', () => {
-	it('returns operation result when telemetry is disabled', async () => {
-		const result = await withExternalSpan(
-			{ url: 'https://example.com/api', method: 'GET' },
-			async () => ({ status: 200 })
-		);
-
-		expect(result).toEqual({ status: 200 });
-	});
-
-	it('returns operation result when telemetry is enabled', async () => {
-		const result = await withExternalSpan(
-			{ url: 'https://example.com/api', method: 'GET' },
-			async () => ({ status: 200 }),
-			enabledOptions
-		);
-
-		expect(result).toEqual({ status: 200 });
-	});
-
-	it('propagates errors from operation', async () => {
-		const error = new Error('Network error');
-
-		await expect(
-			withExternalSpan(
-				{ url: 'https://example.com/api', method: 'POST' },
-				async () => {
-					throw error;
-				},
-				enabledOptions
-			)
-		).rejects.toThrow('Network error');
-	});
-});
-
-describe('withCacheSpan', () => {
-	it('returns operation result when telemetry is disabled', async () => {
-		const result = await withCacheSpan('get', 'memory', async () => ({
-			data: 'cached',
-		}));
-
-		expect(result).toEqual({ data: 'cached' });
-	});
-
-	it('returns operation result when telemetry is enabled', async () => {
-		const result = await withCacheSpan(
-			'get',
-			'external',
-			async () => ({ data: 'cached' }),
-			enabledOptions
-		);
-
-		expect(result).toEqual({ data: 'cached' });
-	});
-
-	it('returns null for cache miss', async () => {
-		const result = await withCacheSpan(
-			'get',
-			'memory',
-			async () => null,
-			enabledOptions
-		);
-
-		expect(result).toBeNull();
-	});
-
-	it('propagates errors from operation', async () => {
-		const error = new Error('Cache connection failed');
-
-		await expect(
-			withCacheSpan(
-				'get',
-				'external',
-				async () => {
-					throw error;
-				},
-				enabledOptions
-			)
-		).rejects.toThrow('Cache connection failed');
-	});
-});

package/src/utils/instrumentation.ts

@@ -1,196 +0,0 @@
-import type { Span } from '@opentelemetry/api';
-import { SpanKind, SpanStatusCode } from '@opentelemetry/api';
-import type { C15TOptions } from '../types';
-import {
-	getDefaultAttributes,
-	getTracer,
-	handleSpanError,
-	isTelemetryEnabled,
-	withSpanContext,
-} from './create-telemetry-options';
-
-/**
- * Span attributes for database operations
- */
-export interface DatabaseSpanAttributes {
-	/** The database operation type (find, create, update, delete) */
-	operation: 'find' | 'create' | 'update' | 'delete' | 'findOrCreate';
-	/** The entity type being operated on */
-	entity: string;
-	/** Optional additional attributes */
-	[key: string]: string | number | boolean | undefined;
-}
-
-/**
- * Span attributes for external API calls
- */
-export interface ExternalSpanAttributes {
-	/** The URL being called */
-	url: string;
-	/** The HTTP method */
-	method: string;
-	/** Optional additional attributes */
-	[key: string]: string | number | boolean | undefined;
-}
-
-/**
- * Execute an async operation within a span, handling status and error recording.
- *
- * Sets SpanStatusCode.OK on success, records error attributes and sets
- * SpanStatusCode.ERROR on failure, and always ends the span.
- */
-async function executeWithSpan<T>(
-	span: Span,
-	operation: () => Promise<T>
-): Promise<T> {
-	try {
-		const result = await withSpanContext(span, operation);
-		span.setStatus({ code: SpanStatusCode.OK });
-		return result;
-	} catch (error) {
-		handleSpanError(span, error);
-		throw error;
-	} finally {
-		span.end();
-	}
-}
-
-/**
- * Resolves default attributes from explicit options or the cached config.
- */
-function resolveDefaultAttributes(
-	options?: C15TOptions
-): Record<string, string | number | boolean> {
-	return (
-		options?.advanced?.telemetry?.defaultAttributes || getDefaultAttributes()
-	);
-}
-
-/**
- * Wraps a database operation in a span for tracing.
- *
- * @param attributes - Span attributes describing the operation
- * @param operation - The async operation to wrap
- * @param options - C15T options for telemetry configuration
- * @returns The result of the operation
- *
- * @example
- * ```typescript
- * const subject = await withDatabaseSpan(
- *   { operation: 'find', entity: 'subject' },
- *   async () => db.subject.findUnique({ where: { id } }),
- *   options
- * );
- * ```
- */
-export async function withDatabaseSpan<T>(
-	attributes: DatabaseSpanAttributes,
-	operation: () => Promise<T>,
-	options?: C15TOptions
-): Promise<T> {
-	if (!isTelemetryEnabled(options)) {
-		return operation();
-	}
-
-	const tracer = getTracer(options);
-	const spanName = `db.${attributes.entity}.${attributes.operation}`;
-
-	const span = tracer.startSpan(spanName, {
-		kind: SpanKind.CLIENT,
-		attributes: {
-			'db.system': 'c15t',
-			'db.operation': attributes.operation,
-			'db.entity': attributes.entity,
-			...resolveDefaultAttributes(options),
-			...Object.fromEntries(
-				Object.entries(attributes).filter(
-					([key]) => !['operation', 'entity'].includes(key)
-				)
-			),
-		},
-	});
-
-	return executeWithSpan(span, operation);
-}
-
-/**
- * Wraps an external API call in a span for tracing.
- *
- * @param attributes - Span attributes describing the external call
- * @param operation - The async operation to wrap
- * @param options - C15T options for telemetry configuration
- * @returns The result of the operation
- *
- * @example
- * ```typescript
- * const response = await withExternalSpan(
- *   { url: 'https://api.example.com/data', method: 'GET' },
- *   async () => fetch('https://api.example.com/data'),
- *   options
- * );
- * ```
- */
-export async function withExternalSpan<T>(
-	attributes: ExternalSpanAttributes,
-	operation: () => Promise<T>,
-	options?: C15TOptions
-): Promise<T> {
-	if (!isTelemetryEnabled(options)) {
-		return operation();
-	}
-
-	const tracer = getTracer(options);
-	const url = new URL(attributes.url);
-	const spanName = `HTTP ${attributes.method} ${url.hostname}`;
-
-	const span = tracer.startSpan(spanName, {
-		kind: SpanKind.CLIENT,
-		attributes: {
-			'http.method': attributes.method,
-			'http.url': `${url.origin}${url.pathname}`,
-			'http.host': url.hostname,
-			...resolveDefaultAttributes(options),
-			...Object.fromEntries(
-				Object.entries(attributes).filter(
-					([key]) => !['url', 'method'].includes(key)
-				)
-			),
-		},
-	});
-
-	return executeWithSpan(span, operation);
-}
-
-/**
- * Wraps a cache operation in a span for tracing.
- *
- * @param operation - The cache operation type
- * @param layer - The cache layer (bundled, memory, external)
- * @param fn - The async operation to wrap
- * @param options - C15T options for telemetry configuration
- * @returns The result of the operation
- */
-export async function withCacheSpan<T>(
-	operation: 'get' | 'set' | 'delete',
-	layer: 'bundled' | 'memory' | 'external',
-	fn: () => Promise<T>,
-	options?: C15TOptions
-): Promise<T> {
-	if (!isTelemetryEnabled(options)) {
-		return fn();
-	}
-
-	const tracer = getTracer(options);
-	const spanName = `cache.${layer}.${operation}`;
-
-	const span = tracer.startSpan(spanName, {
-		kind: SpanKind.CLIENT,
-		attributes: {
-			'cache.operation': operation,
-			'cache.layer': layer,
-			...resolveDefaultAttributes(options),
-		},
-	});
-
-	return executeWithSpan(span, fn);
-}