@c15t/backend 1.8.0 → 2.0.0-rc.0

package/src/core.ts

@@ -1,20 +1,29 @@
 import { createLogger } from '@c15t/logger';
-import { OpenAPIHandler } from '@orpc/openapi/fetch';
-import { CORSPlugin } from '@orpc/server/plugins';
-import defu from 'defu';
-import { DoubleTieError, ERROR_CODES } from '~/pkgs/results';
-import type { DeepPartial } from '~/pkgs/types/helper';
-import type { C15TContext, C15TOptions, C15TPlugin } from '~/types';
+import { SpanStatusCode } from '@opentelemetry/api';
+import { apiReference } from '@scalar/hono-api-reference';
+import { Hono } from 'hono';
+import { cors } from 'hono/cors';
+import { HTTPException } from 'hono/http-exception';
+import { openAPIRouteHandler } from 'hono-openapi';
+import { validateRequestAuth } from '~/middleware/auth';
+import { createCORSOptions } from '~/middleware/cors';
+import { createOpenAPIConfig } from '~/middleware/openapi';
+import { getIpAddress } from '~/middleware/process-ip';
+import type { C15TContext, C15TOptions } from '~/types';
 import { init } from './init';
-import { createCORSOptions, processCors } from './middleware/cors';
+import { createConsentRoutes } from './routes/consent';
+// Import route handlers
+import { createInitRoute } from './routes/init';
+import { createStatusRoute } from './routes/status';
+import { createSubjectRoutes } from './routes/subject';
 import {
-	createDocsUI,
-	createOpenAPIConfig,
-	createOpenAPISpec,
-} from './middleware/openapi';
-import { withRequestSpan } from './pkgs/api-router/telemetry';
-import { getIp } from './pkgs/api-router/utils/ip';
-import { router } from './router';
+	createRequestSpan,
+	handleSpanError,
+	withSpanContext,
+} from './utils/create-telemetry-options';
+import { extractErrorMessage } from './utils/extract-error-message';
+import { getMetrics } from './utils/metrics';
+import { version } from './version';
 
 /**
  * Type representing an API route
@@ -25,33 +34,20 @@ export type Route = {
 	description?: string;
 };
 
+/**
+ * Hono app type with c15t context
+ */
+export type C15TApp = Hono<{ Variables: { c15tContext: C15TContext } }>;
+
 /**
  * Interface representing a configured c15t consent management instance.
  *
- * @typeParam PluginTypes - Array of plugin types used in this instance
- *
  * @remarks
  * The C15TInstance provides the main interface for interacting with the consent
  * management system. It includes methods for handling requests, accessing API
  * endpoints, and managing the system's configuration.
- *
- * All asynchronous operations return Promises for consistent error handling.
- *
- * @example
- * ```typescript
- * const instance: C15TInstance = c15tInstance({
- *   secret: 'your-secret',
- *   storage: memoryAdapter()
- * });
- *
- * // Handle an incoming request
- * const response = await instance.handler(request);
- * ```
- *
- * @deprecated Will be removed in the next major version. Update to `@c15t/backend/v2`, view migration guide for more details.
- * @see https://c15t.com/docs/self-host/migrate-from-v1
  */
-export interface C15TInstance<PluginTypes extends C15TPlugin[] = C15TPlugin[]> {
+export interface C15TInstance {
 	/**
 	 * Processes incoming HTTP requests and routes them to appropriate handlers.
 	 *
@@ -73,17 +69,17 @@ export interface C15TInstance<PluginTypes extends C15TPlugin[] = C15TPlugin[]> {
 	/**
 	 * The configuration options used for this instance.
 	 */
-	options: C15TOptions<PluginTypes>;
+	options: C15TOptions;
 
 	/**
 	 * Access to the underlying context.
 	 */
-	$context: Promise<C15TContext>;
+	$context: C15TContext;
 
 	/**
-	 * Access to the router for direct usage.
+	 * Access to the Hono app for direct usage.
 	 */
-	router: typeof router;
+	app: C15TApp;
 
 	/**
 	 * Generates and returns the OpenAPI specification as a JSON object.
@@ -103,364 +99,270 @@ export interface C15TInstance<PluginTypes extends C15TPlugin[] = C15TPlugin[]> {
 /**
  * Creates a new c15t consent management instance.
  *
- * This version provides a unified handler that works with oRPC to handle requests.
- *
- * @deprecated Will be removed in the next major version. Update to `@c15t/backend/v2`, view migration guide for more details.
- * @see https://c15t.com/docs/self-host/migrate-from-v1
+ * This version uses Hono as the HTTP framework with OpenAPI support.
  */
-export const c15tInstance = <PluginTypes extends C15TPlugin[] = C15TPlugin[]>(
-	options: C15TOptions<PluginTypes>
-) => {
-	// Initialize context
-	const contextPromise = init(options);
+export const c15tInstance = (options: C15TOptions): C15TInstance => {
+	const context = init(options);
+	const logger = createLogger(options.logger);
 
-	// Replace the inline corsOptions with the imported one
-	const corsOptions = createCORSOptions(options.trustedOrigins);
-
-	// Create the oRPC handler with plugins
-	const rpcHandler = new OpenAPIHandler(router, {
-		plugins: [new CORSPlugin(corsOptions)],
-	});
+	// Create the Hono app
+	const app = new Hono<{ Variables: { c15tContext: C15TContext } }>();
 
 	// Set up OpenAPI configuration
 	const openApiConfig = createOpenAPIConfig(options);
-	const getDocsUI = () => createDocsUI(options);
+	const basePath = options.basePath || '/';
 
-	/**
-	 * Process IP tracking and add it to the context
-	 */
-	const processIp = (request: Request, context: C15TContext) => {
-		const ip = getIp(request, options);
-		if (ip) {
-			context.ipAddress = ip;
-		}
-		return context;
-	};
+	// CORS middleware
+	const corsOptions = createCORSOptions(options.trustedOrigins);
+	app.use('*', cors(corsOptions));
 
-	/**
-	 * Add telemetry tracking to the context
-	 */
-	const processTelemetry = (request: Request, context: C15TContext) => {
-		const url = new URL(request.url);
-		const path = url.pathname;
-		const method = request.method;
-
-		// Add a span to the context that can be accessed by handlers
-		withRequestSpan(
-			method,
-			path,
-			async () => {
-				// This callback is intentionally empty - we're only creating the span
-				// The span automatically tracks the current execution context and
-				// will be associated with the request processing that follows
-			},
-			options
+	// Note: Compression disabled - causes issues with response passthrough in wrapper scenarios
+	// app.use('*', compress());
+
+	// Get metrics instance (null if telemetry is disabled)
+	const metrics = getMetrics(options);
+
+	// Context middleware - enriches each request with c15t context
+	app.use('*', async (c, next) => {
+		const request = c.req.raw;
+		const startTime = Date.now();
+
+		// Check API key authentication
+		const apiKeyAuthenticated = validateRequestAuth(
+			request.headers,
+			options.advanced?.apiKeys
 		);
 
-		// Add path and method to context for easier access
-		context.path = path;
-		context.method = method;
-		context.headers = request.headers;
-		context.userAgent = request.headers.get('user-agent') || undefined;
+		const enrichedContext: C15TContext = {
+			...context,
+			ipAddress: getIpAddress(request, options),
+			userAgent: request.headers.get('user-agent') || undefined,
+			apiKeyAuthenticated,
+			path: c.req.path,
+			method: c.req.method,
+			headers: request.headers,
+		};
 
-		return context;
-	};
+		c.set('c15tContext', enrichedContext);
 
-	/**
-	 * Handle OpenAPI spec requests
-	 */
-	const handleOpenApiSpecRequest = async (
-		url: URL
-	): Promise<Response | null> => {
-		if (openApiConfig.enabled && url.pathname === openApiConfig.specPath) {
-			const ctxResult = await contextPromise;
-			if (!ctxResult.isOk()) {
-				throw ctxResult.error;
+		// Create a telemetry span for the request (if enabled)
+		const span = createRequestSpan(c.req.method, c.req.path, options);
+
+		const runNext = async () => {
+			await next();
+		};
+
+		try {
+			if (span) {
+				await withSpanContext(span, runNext);
+				// After routing, update span name with matched route pattern
+				const matchedRoutes = c.req.matchedRoutes;
+				const routePattern =
+					matchedRoutes
+						.map((r) => r.path)
+						.filter((p) => p !== '/*')
+						.pop() ?? c.req.path;
+				span.updateName(`${c.req.method} ${routePattern}`);
+				span.setAttribute('http.route', routePattern);
+				span.setStatus({ code: SpanStatusCode.OK });
+			} else {
+				await runNext();
+			}
+		} catch (error) {
+			if (span) {
+				handleSpanError(span, error);
 			}
-			const ctx = ctxResult.value;
-			const orpcContext = {
-				adapter: ctx.adapter,
-				registry: ctx.registry,
-				logger: ctx.logger,
-				generateId: ctx.generateId,
-				headers: new Headers(),
-				appName: options.appName || 'c15t',
-				options,
-				trustedOrigins: options.trustedOrigins || [],
-				baseURL: options.baseURL || '/',
-				tables: ctx.tables,
-			};
-			const getOpenAPISpec = createOpenAPISpec(orpcContext, options);
-			const spec = await getOpenAPISpec();
-			return new Response(JSON.stringify(spec), {
-				status: 200,
-				headers: { 'Content-Type': 'application/json' },
-			});
+			throw error;
+		} finally {
+			span?.end();
 		}
-		return null;
-	};
 
-	/**
-	 * Handle API docs UI requests
-	 */
-	const handleDocsUiRequest = (url: URL): Response | null => {
-		if (openApiConfig.enabled && url.pathname === openApiConfig.docsPath) {
-			const html = getDocsUI();
-			return new Response(html, {
-				status: 200,
-				headers: {
-					'Content-Type': 'text/html',
-					'Content-Security-Policy':
-						"default-src 'self'; script-src 'self' https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net;",
+		// Record HTTP metrics after request completes
+		if (metrics) {
+			const durationMs = Date.now() - startTime;
+			// Use route pattern instead of raw path to avoid high cardinality
+			const matchedRoutes = c.req.matchedRoutes;
+			const routePattern =
+				matchedRoutes
+					.map((r) => r.path)
+					.filter((p) => p !== '/*')
+					.pop() ?? c.req.path;
+			metrics.recordHttpRequest(
+				{
+					method: c.req.method,
+					route: routePattern,
+					status: c.res.status,
 				},
-			});
+				durationMs
+			);
 		}
-		return null;
-	};
+	});
 
-	/**
-	 * Create error response for DoubleTieError
-	 */
-	const createDoubleTieErrorResponse = (error: DoubleTieError): Response => {
-		// Sanitize error message to prevent sensitive information disclosure
-		const sanitizedMessage = error.message.replace(
-			/[^\w\s.,;:!?()[\]{}'"+-]/g,
-			''
-		);
-		return new Response(
-			JSON.stringify({
-				code: error.code,
-				message: sanitizedMessage,
-				data: error.meta,
-				status: error.statusCode,
-				defined: true,
-			}),
-			{
-				status: error.statusCode,
-				headers: { 'Content-Type': 'application/json' },
-			}
+	// OpenAPI spec endpoint
+	if (openApiConfig.enabled) {
+		app.get(
+			openApiConfig.specPath,
+			openAPIRouteHandler(app, {
+				documentation: {
+					openapi: '3.1.0',
+					info: {
+						title: options.appName || 'c15t API',
+						version,
+						description: 'API for consent management',
+					},
+					servers: [{ url: basePath }],
+					components: {
+						securitySchemes: {
+							bearerAuth: {
+								type: 'http',
+								scheme: 'bearer',
+							},
+						},
+					},
+				},
+			})
 		);
-	};
 
-	/**
-	 * Create error response for unknown errors
-	 */
-	const createUnknownErrorResponse = (error: unknown): Response => {
-		const message = error instanceof Error ? error.message : String(error);
-		// More safely determine the status code with proper type checks
-		let status = 500;
-		if (error instanceof Error && 'status' in error) {
-			const statusValue = (error as { status: unknown }).status;
-			if (
-				typeof statusValue === 'number' &&
-				statusValue >= 100 &&
-				statusValue < 600
-			) {
-				status = statusValue;
-			}
+		// Docs UI endpoint
+		// The spec URL needs to include the basePath since it's used by the browser
+		const publicSpecUrl = `${basePath}${openApiConfig.specPath}`.replace(
+			/\/+/g,
+			'/'
+		);
+		app.get(
+			openApiConfig.docsPath,
+			apiReference({
+				spec: {
+					url: publicSpecUrl,
+				},
+				pageTitle: `${options.appName || 'c15t API'} Documentation`,
+			})
+		);
+	}
+
+	// Mount routes - using plural nouns for REST conventions
+	app.route('/init', createInitRoute(options));
+	app.route('/subjects', createSubjectRoutes());
+	app.route('/consents', createConsentRoutes());
+	app.route('/status', createStatusRoute());
+
+	// Global error handler
+	app.onError((err, c) => {
+		const ctx = c.get('c15tContext');
+		const log = ctx?.logger || logger;
+
+		log.error('Request handling error:', extractErrorMessage(err));
+
+		if (err instanceof HTTPException) {
+			const cause = err.cause as
+				| { code?: string; message?: string; [key: string]: unknown }
+				| undefined;
+			return c.json(
+				{
+					code: cause?.code || 'HTTP_ERROR',
+					message: err.message,
+					status: err.status,
+					defined: true,
+					data: {},
+				},
+				err.status
+			);
 		}
 
-		return new Response(
-			JSON.stringify({
-				code: ERROR_CODES.INTERNAL_SERVER_ERROR,
-				message,
-				status,
+		return c.json(
+			{
+				code: 'INTERNAL_SERVER_ERROR',
+				message: 'Internal server error',
+				status: 500,
 				defined: true,
 				data: {},
-			}),
-			{
-				status,
-				headers: { 'Content-Type': 'application/json' },
-			}
+			},
+			500
 		);
-	};
-
-	/**
-	 * Handle API requests via oRPC
-	 */
-	const handleApiRequest = async (
-		request: Request,
-		ctx: C15TContext
-	): Promise<Response> => {
-		// Create context for the handler with c15t specifics
-		const orpcContext = {
-			adapter: ctx.adapter,
-			registry: ctx.registry,
-			logger: ctx.logger,
-			generateId: ctx.generateId,
-			headers: request.headers,
-			userAgent: request.headers.get('user-agent') || undefined,
-			appName: options.appName || 'c15t',
-			options: ctx.options,
-			trustedOrigins: options.trustedOrigins || [],
-			baseURL: options.baseURL || '/',
-			tables: ctx.tables,
-		};
-
-		// Apply middleware processing to enrich the context
-		processIp(request, orpcContext);
-		processCors(request, orpcContext, options.trustedOrigins);
-		processTelemetry(request, orpcContext);
-
-		// Use oRPC handler to handle the request with our enhanced context
-		const handlerContext = orpcContext as Record<string, unknown>;
-
-		orpcContext.logger.debug?.('Handling prefix', {
-			prefix: (options.basePath as `/${string}`) || '/',
-		});
-
-		const { matched, response } = await rpcHandler.handle(request, {
-			prefix: (options.basePath as `/${string}`) || '/',
-			context: handlerContext,
-		});
+	});
 
-		// Return the response if handler matched
-		if (matched && response) {
-			orpcContext.logger.debug('Handler matched', {
-				request,
-				matched,
-				response,
-			});
-			return response;
-		}
+	// 404 handler
+	app.notFound((c) => {
+		return c.json(
+			{
+				code: 'NOT_FOUND',
+				message: 'Not Found',
+				status: 404,
+				defined: true,
+				data: {},
+			},
+			404
+		);
+	});
 
-		orpcContext.logger.debug('No handler matched', {
-			request,
-			matched,
-			response,
+	// Create the handler function
+	const handler = async (request: Request): Promise<Response> => {
+		logger?.debug?.('Incoming request', {
+			method: request.method,
+			url: request.url,
 		});
-		// If no handler matched, return 404
-		return new Response('Not Found', { status: 404 });
-	};
 
-	/**
-	 * Handle an incoming request using oRPC
-	 */
-	const handler = async (
-		request: Request,
-		ctxOverride?: DeepPartial<C15TContext>
-	): Promise<Response> => {
-		try {
+		// Strip the basePath from the URL if present
+		// This allows Hono routes to be defined without the basePath prefix
+		let modifiedRequest = request;
+		if (basePath && basePath !== '/') {
 			const url = new URL(request.url);
-
-			// Add this debug log:
-			createLogger(options.logger)?.debug?.('Incoming request', {
-				method: request.method,
-				pathname: url.pathname,
-			});
-
-			// Check for OpenAPI spec or docs UI requests
-			const openApiResponse = await handleOpenApiSpecRequest(url);
-			if (openApiResponse) {
-				return openApiResponse;
-			}
-
-			const docsResponse = handleDocsUiRequest(url);
-			if (docsResponse) {
-				return docsResponse;
-			}
-
-			// Get context, handling Result type properly
-			const ctxResult = await contextPromise;
-			if (!ctxResult.isOk()) {
-				throw ctxResult.error;
+			const normalizedBasePath = basePath.replace(/\/$/, ''); // Remove trailing slash
+			if (url.pathname.startsWith(normalizedBasePath)) {
+				const newPath = url.pathname.slice(normalizedBasePath.length) || '/';
+				url.pathname = newPath;
+				modifiedRequest = new Request(url.toString(), {
+					method: request.method,
+					headers: request.headers,
+					body: request.body,
+					duplex: 'half',
+				} as RequestInit);
 			}
-
-			const ctx = defu(ctxOverride || {}, ctxResult.value) as C15TContext;
-
-			// After options/baseURL/basePath is set/used
-			const basePath = options.basePath || options.baseURL || '/';
-			createLogger(options.logger)?.debug?.('[c15t] Using basePath/baseURL', {
-				basePath,
-			});
-
-			// Add this debug log:
-			createLogger(options.logger)?.debug?.('[c15t] Routing request', {
-				method: request.method,
-				url: request.url,
-				prefix: basePath,
-			});
-
-			// Handle API request
-			return await handleApiRequest(request, ctx);
-		} catch (error) {
-			// Log the error
-			const logger = options.logger ? createLogger(options.logger) : console;
-			logger.error('Request handling error:', error);
-
-			// Handle different error types
-			if (error instanceof DoubleTieError) {
-				return createDoubleTieErrorResponse(error);
-			}
-
-			return createUnknownErrorResponse(error);
 		}
-	};
 
-	// Create Next.js-compatible route handlers
-	const createNextHandlers = () => {
-		const nextHandler = async (request: Request) => {
-			return await handler(request);
-		};
+		return app.fetch(modifiedRequest);
+	};
 
-		return {
-			GET: nextHandler,
-			POST: nextHandler,
-			PUT: nextHandler,
-			PATCH: nextHandler,
-			DELETE: nextHandler,
-			OPTIONS: nextHandler,
-			HEAD: nextHandler,
-		};
+	// Create docs UI helper
+	const getDocsUI = () => {
+		const specUrl = `${basePath}${openApiConfig.specPath}`.replace(/\/+/g, '/');
+		return `
+<!doctype html> 
+<html>
+  <head>
+    <title>${options.appName || 'c15t API'} Documentation</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="icon" type="image/svg+xml" href="https://c15t.com/icon.svg" />
+  </head>
+  <body>
+    <script
+      id="api-reference"
+      data-url="${encodeURI(specUrl)}">
+    </script>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+  </body>
+</html>
+`;
 	};
 
 	// Return the instance
 	return {
 		options,
-
-		// Unwrap the Result when exposing the context
-		$context: contextPromise.then((result) => {
-			if (!result.isOk()) {
-				throw result.error;
-			}
-			return result.value;
-		}),
-
-		// Export router for direct access
-		router,
-
-		// Request handler for standard environments
+		$context: context,
+		app,
 		handler,
-
-		// Next.js route handlers
-		...createNextHandlers(),
-
-		// OpenAPI functionality
 		getOpenAPISpec: async () => {
-			const ctxResult = await contextPromise;
-			if (!ctxResult.isOk()) {
-				throw ctxResult.error;
-			}
-			const ctx = ctxResult.value;
-			const orpcContext = {
-				adapter: ctx.adapter,
-				registry: ctx.registry,
-				logger: ctx.logger,
-				generateId: ctx.generateId,
-				headers: new Headers(),
-				appName: options.appName || 'c15t',
-				options,
-				trustedOrigins: options.trustedOrigins || [],
-				baseURL: options.baseURL || '/',
-				tables: ctx.tables,
-			};
-			const getOpenAPISpec = createOpenAPISpec(orpcContext, options);
-			return getOpenAPISpec();
+			// Generate OpenAPI spec by fetching from our own endpoint
+			const specResponse = await app.fetch(
+				new Request(`http://localhost${openApiConfig.specPath}`)
+			);
+			return specResponse.json() as Promise<Record<string, unknown>>;
 		},
 		getDocsUI,
 	};
 };
 
-export type { C15TPlugin, C15TOptions, C15TContext };
-export type { ContractsInputs, ContractsOutputs } from './contracts';
+export { defineConfig } from './define-config';
+export type { C15TContext, C15TOptions } from './types';
 export { version } from './version';