@useavalon/avalon 0.1.0

package/src/middleware/executor.ts

@@ -0,0 +1,315 @@
+/**
+ * Simplified Middleware Executor
+ *
+ * This module provides a streamlined middleware execution system that aligns
+ * with Nitro's conventions while supporting Avalon's route-scoped middleware.
+ *
+ * Key features:
+ * - Nitro-style handler signature: return void to continue, return Response to terminate
+ * - Middleware caching for performance
+
+ * - Error propagation to Nitro's error handling
+ * - Context preservation: event.context modifications persist through the chain
+ * - Development logging for context changes
+ *
+ * Requirements: 1.2, 1.3, 1.4, 2.1, 2.2
+ */
+
+import type { H3Event } from 'h3';
+import type { MiddlewareHandler, MiddlewareRoute, MiddlewareFileExport, MiddlewareExecutorOptions } from './types.ts';
+import { getMatchingMiddleware } from './discovery.ts';
+
+/**
+ * Captures a snapshot of the event context for comparison
+ * Used in development mode to log context changes
+ */
+function captureContextSnapshot(context: Record<string, unknown>): Map<string, unknown> {
+	const snapshot = new Map<string, unknown>();
+	for (const key of Object.keys(context)) {
+		snapshot.set(key, context[key]);
+	}
+	return snapshot;
+}
+
+/**
+ * Compares two context snapshots and returns the changes
+ * Used in development mode to log context modifications
+ */
+function getContextChanges(
+	before: Map<string, unknown>,
+	after: Record<string, unknown>,
+): { added: string[]; modified: string[]; removed: string[] } {
+	const added: string[] = [];
+	const modified: string[] = [];
+	const removed: string[] = [];
+
+	for (const key of Object.keys(after)) {
+		if (!before.has(key)) {
+			added.push(key);
+		} else if (before.get(key) !== after[key]) {
+			modified.push(key);
+		}
+	}
+
+	for (const key of before.keys()) {
+		if (!(key in after)) {
+			removed.push(key);
+		}
+	}
+
+	return { added, modified, removed };
+}
+
+/**
+ * Logs context changes in development mode
+ * Requirements: 2.1, 2.2
+ *
+ * Note: Intentionally minimal to reduce log noise.
+ * Uncomment the body for debugging middleware context issues.
+ */
+function logContextChanges(
+	_filePath: string,
+	_changes: { added: string[]; modified: string[]; removed: string[] },
+): void {
+	// Uncomment for debugging middleware context issues:
+	// const hasChanges = _changes.added.length > 0 || _changes.modified.length > 0 || _changes.removed.length > 0;
+	// if (!hasChanges) return;
+	// console.log(`[middleware] Context changes in ${_filePath}: ...`);
+}
+
+/** Default executor options */
+const DEFAULT_OPTIONS: Required<MiddlewareExecutorOptions> = {
+	devMode: false,
+	timeout: 30000,
+};
+
+/** Middleware cache: maps file paths to loaded handlers */
+const middlewareCache = new Map<string, MiddlewareHandler>();
+
+/**
+ * Executes a single middleware route handler with context tracking.
+ * Returns the Response if the chain should terminate, undefined to continue.
+ */
+async function executeMiddlewareRoute(
+	event: H3Event,
+	route: MiddlewareRoute,
+	devMode: boolean,
+	timeout: number,
+): Promise<Response | undefined> {
+	const handler = await loadMiddleware(route.filePath, devMode);
+	if (!handler) return undefined;
+
+	const contextBefore = devMode ? captureContextSnapshot(event.context) : null;
+
+	const result = await executeWithTimeout(() => handler(event), timeout, route.filePath);
+
+	if (devMode && contextBefore) {
+		const changes = getContextChanges(contextBefore, event.context);
+		logContextChanges(route.filePath, changes);
+	}
+
+	const response = handleMiddlewareResult(result, route.filePath, devMode);
+	if (response && devMode) {
+		console.log(`[middleware] Chain terminated by ${route.filePath}`);
+	}
+	return response;
+}
+
+/**
+ * Executes route-scoped middleware chain for a request
+ *
+ * 1. Finds middleware that matches the request URL
+ * 2. Executes them in priority order (parent before child)
+ * 3. Handles void return (continue) and Response return (terminate)
+ * 4. Propagates errors to Nitro's error handling
+ * 5. Preserves event.context modifications across the chain
+ * 6. Logs context changes in development mode
+ *
+ * @param event - H3 event object from Nitro
+ * @param routes - Discovered middleware routes from discoverScopedMiddleware
+ * @param options - Execution options
+ * @returns Response if middleware terminated the chain, undefined otherwise
+ */
+export async function executeScopedMiddleware(
+	event: H3Event,
+	routes: MiddlewareRoute[],
+	options: MiddlewareExecutorOptions = {},
+): Promise<Response | undefined> {
+	const { devMode, timeout } = { ...DEFAULT_OPTIONS, ...options };
+
+	const url = buildUrlFromEvent(event);
+	const matchingRoutes = getMatchingMiddleware(routes, url);
+
+	if (matchingRoutes.length === 0) {
+		return undefined;
+	}
+
+	for (const route of matchingRoutes) {
+		try {
+			const response = await executeMiddlewareRoute(event, route, devMode, timeout);
+			if (response) return response;
+		} catch (error) {
+			if (devMode) {
+				console.error(`[middleware] Error in ${route.filePath}:`, error);
+			}
+			throw error;
+		}
+	}
+
+	return undefined;
+}
+
+/**
+ * Builds a URL object from an H3 event.
+ * Supports both h3 v2 (event.url / event.req.url) and the dev-mode mock shape (event.path).
+ */
+function buildUrlFromEvent(event: H3Event): URL {
+	const base = 'http://localhost';
+
+	// h3 v2: event.url is a string
+	if (typeof (event as any).url === 'string') {
+		return new URL((event as any).url, base);
+	}
+
+	// h3 v2: event.req is a Web Request
+	if ((event as any).req?.url) {
+		return new URL((event as any).req.url, base);
+	}
+
+	// Dev-mode mock: event.path
+	if ((event as any).path) {
+		return new URL((event as any).path, base);
+	}
+
+	// Legacy h3 v1: event.node.req.url
+	if ((event as any).node?.req?.url) {
+		return new URL((event as any).node.req.url, base);
+	}
+
+	return new URL('/', base);
+}
+
+/**
+ * Converts an absolute file path to a valid ESM import specifier.
+ * Windows absolute paths (C:\...) are converted to file:// URLs.
+ * On Unix, the path is returned as-is (no-op).
+ */
+export function toImportSpecifier(filePath: string): string {
+	if (/^[A-Za-z]:[\\/]/.test(filePath)) {
+		return `file:///${filePath.replaceAll('\\', '/')}`;
+	}
+	return filePath;
+}
+
+/**
+ * Loads a middleware handler via Vite's ssrLoadModule (dev) or dynamic import (prod/worker).
+ */
+async function loadMiddleware(filePath: string, devMode: boolean): Promise<MiddlewareHandler | null> {
+	if (!devMode && middlewareCache.has(filePath)) {
+		return middlewareCache.get(filePath)!;
+	}
+
+	try {
+		let module: MiddlewareFileExport;
+
+		const viteServer = globalThis.__viteDevServer;
+		if (devMode && viteServer) {
+			const viteRoot = viteServer.config.root || '';
+			const vitePath = filePath.startsWith(viteRoot) ? '/' + filePath.slice(viteRoot.length + 1) : filePath;
+			module = (await viteServer.ssrLoadModule(vitePath)) as MiddlewareFileExport;
+		} else {
+			const importPath = toImportSpecifier(filePath);
+			module = (await import(/* @vite-ignore */ importPath)) as MiddlewareFileExport;
+		}
+
+		if (!module.default || typeof module.default !== 'function') {
+			if (devMode) {
+				console.warn(`[middleware] ${filePath} does not export a default function`);
+			}
+			return null;
+		}
+
+		if (!devMode) {
+			middlewareCache.set(filePath, module.default);
+		}
+
+		return module.default;
+	} catch (error) {
+		if (devMode) {
+			console.error(`[middleware] Failed to load ${filePath}:`, error);
+		}
+		return null;
+	}
+}
+
+/**
+ * Executes a middleware handler with a timeout
+ */
+async function executeWithTimeout<T>(fn: () => T | Promise<T>, timeout: number, filePath: string): Promise<T> {
+	return Promise.race([
+		Promise.resolve(fn()),
+		new Promise<never>((_, reject) => {
+			setTimeout(() => {
+				reject(new Error(`Middleware timeout after ${timeout}ms: ${filePath}`));
+			}, timeout);
+		}),
+	]);
+}
+
+/**
+ * Handles the result of a middleware execution.
+ * Supports Nitro-style (void/Response) format.
+ */
+function handleMiddlewareResult(result: unknown, filePath: string, devMode: boolean): Response | undefined {
+	if (result === undefined || result === null) {
+		return undefined;
+	}
+
+	if (result instanceof Response) {
+		return result;
+	}
+
+	if (devMode) {
+		console.warn(
+			`[middleware] ${filePath} returned unexpected value: ${typeof result}. ` +
+				`Expected void or Response.`,
+		);
+	}
+
+	return undefined;
+}
+
+/** Clears the middleware cache (e.g. during hot reload) */
+export function clearMiddlewareCache(): void {
+	middlewareCache.clear();
+}
+
+/** Removes a specific middleware from the cache */
+export function invalidateMiddleware(filePath: string): boolean {
+	return middlewareCache.delete(filePath);
+}
+
+/** Gets the current size of the middleware cache */
+export function getMiddlewareCacheSize(): number {
+	return middlewareCache.size;
+}
+
+/** Checks if a key exists in event.context */
+export function hasContextValue(event: H3Event, key: string): boolean {
+	return key in event.context;
+}
+
+/** Gets a typed value from event.context */
+export function getContextValue<T>(event: H3Event, key: string): T | undefined {
+	return event.context[key] as T | undefined;
+}
+
+/** Sets a value in event.context with optional development logging */
+export function setContextValue<T>(event: H3Event, key: string, value: T, devMode: boolean = false): void {
+	const isNew = !(key in event.context);
+	event.context[key] = value;
+
+	if (devMode) {
+		console.log(`[middleware] Context ${isNew ? 'set' : 'updated'}: ${key}`);
+	}
+}

package/src/middleware/index.ts

@@ -0,0 +1,76 @@
+/**
+ * Avalon Middleware Module
+ *
+ * This module provides a Nitro-aligned middleware system for Avalon that supports
+ * both global middleware (via Nitro's middleware/ directory) and route-scoped
+ * middleware (via _middleware.ts files in page/API directories).
+ *
+ * Key features:
+ * - Nitro-compatible handler signature: return void to continue, return Response to terminate
+ * - Route-scoped middleware discovery in src/pages/ and src/api/
+ * - Priority-based execution order (parent before child)
+ * - Type-safe context augmentation for H3 events
+ *
+ * @example
+ * ```ts
+ * // Define middleware with proper typing
+ * import { defineMiddleware } from 'avalon/middleware';
+ * import { getHeader, createError } from 'h3';
+ *
+ * export default defineMiddleware(async (event) => {
+ *   const token = getHeader(event, 'Authorization');
+ *   if (!token) {
+ *     throw createError({ statusCode: 401, message: 'Unauthorized' });
+ *   }
+ *   event.context.user = await validateToken(token);
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Discover and execute middleware in your server
+ * import { discoverScopedMiddleware, executeScopedMiddleware } from 'avalon/middleware';
+ *
+ * const routes = await discoverScopedMiddleware({ baseDir: 'src', devMode: true });
+ * const response = await executeScopedMiddleware(event, routes);
+ * if (response) return response;
+ * ```
+ *
+ * Requirements: 4.3
+ */
+
+// =============================================================================
+// Type Exports
+// =============================================================================
+
+export type {
+	MiddlewareHandler,
+	MiddlewareFileExport,
+	MiddlewareRoute,
+	MiddlewareDiscoveryOptions,
+	MiddlewareExecutorOptions,
+} from './types.ts';
+
+// =============================================================================
+// Helper Functions (defineMiddleware removed — use defineHandler from 'nitro/h3')
+// =============================================================================
+
+// =============================================================================
+// Discovery Functions
+// =============================================================================
+
+export { discoverScopedMiddleware, getMatchingMiddleware, clearDiscoveryCache } from './discovery.ts';
+
+// =============================================================================
+// Executor Functions
+// =============================================================================
+
+export {
+	executeScopedMiddleware,
+	clearMiddlewareCache,
+	invalidateMiddleware,
+	getMiddlewareCacheSize,
+	hasContextValue,
+	getContextValue,
+	setContextValue,
+} from './executor.ts';

package/src/middleware/types.ts

@@ -0,0 +1,99 @@
+/**
+ * Nitro-Aligned Middleware Types
+ *
+ * This module defines types for Avalon's middleware system that align with
+ * Nitro's conventions while preserving route-scoped middleware features.
+ *
+ * Key differences from old middleware system:
+ * - Handler signature: (event: H3Event) => void | Response | Promise<void | Response>
+ * - Return void to continue, return Response to terminate
+ * - Uses event.context for data passing instead of custom state/locals
+ *
+ * Requirements: 1.1
+ */
+
+import type { H3Event } from 'h3';
+
+/**
+ * Nitro-aligned middleware handler signature
+ *
+ * This signature matches Nitro's middleware conventions:
+ * - Return nothing (void/undefined) to continue to next middleware
+ * - Return a Response to terminate the chain and send that response
+ * - Throw an error to trigger Nitro's error handling
+ *
+ * @example
+ * ```ts
+ * const handler: MiddlewareHandler = async (event) => {
+ *   // Check auth
+ *   if (!event.context.user) {
+ *     return new Response('Unauthorized', { status: 401 });
+ *   }
+ *   // Continue to next middleware
+ * };
+ * ```
+ */
+export type MiddlewareHandler = (
+  event: H3Event
+) => void | Response | Promise<void | Response>;
+
+/**
+ * Route-scoped middleware file export interface
+ *
+ * Middleware files should export a default function matching the MiddlewareHandler signature.
+ *
+ * @example
+ * ```ts
+ * // src/pages/admin/_middleware.ts
+ * export default async (event) => {
+ *   // middleware logic
+ * };
+ * ```
+ */
+export interface MiddlewareFileExport {
+  /** Default export must be a MiddlewareHandler function */
+  default: MiddlewareHandler;
+}
+
+/**
+ * Discovered middleware route configuration
+ *
+ * Represents a middleware file discovered during scanning, with its
+ * URL pattern, file path, execution priority, and type.
+ */
+export interface MiddlewareRoute {
+  /** URL pattern for matching requests */
+  pattern: URLPattern;
+  /** Absolute path to the middleware file */
+  filePath: string;
+  /** Execution priority (lower numbers execute first) */
+  priority: number;
+  /** Middleware type - determines which routes it applies to */
+  type: 'global' | 'pages';
+}
+
+/**
+ * Middleware discovery options
+ */
+export interface MiddlewareDiscoveryOptions {
+  /** Base directory to scan (e.g., 'src') */
+  baseDir: string;
+  /** File pattern to match (default: '_middleware.ts') */
+  filePattern?: string;
+  /** Directories to exclude from scanning */
+  excludeDirs?: string[];
+  /** Enable development mode logging */
+  devMode?: boolean;
+}
+
+/**
+ * Middleware execution options
+ */
+export interface MiddlewareExecutorOptions {
+  /** Enable development mode logging */
+  devMode?: boolean;
+  /** Timeout for middleware execution in milliseconds */
+  timeout?: number;
+}
+
+