@lithia-js/core 1.0.0-canary.0

package/dist/server/request-processor.d.ts

@@ -0,0 +1,400 @@
+/**
+ * Request processor module for HTTP request handling.
+ *
+ * This module is the core of Lithia's request processing pipeline. It handles:
+ * - Route matching and parameter extraction
+ * - Static file serving
+ * - CORS preflight and headers
+ * - Middleware execution chain
+ * - Route handler invocation
+ * - Error handling and logging
+ *
+ * @module server/request-processor
+ */
+import type { Lithia } from "../lithia";
+import type { HttpServer } from "./http-server";
+import type { LithiaRequest } from "./request";
+import type { LithiaResponse } from "./response";
+/**
+ * Route handler function signature.
+ *
+ * The primary function exported from route files to handle requests.
+ *
+ * @param req - The incoming HTTP request
+ * @param res - The HTTP response object
+ */
+export type LithiaHandler = (req: LithiaRequest, res: LithiaResponse) => Promise<void>;
+/**
+ * Middleware function signature.
+ *
+ * Middlewares run before the route handler and can modify the request/response,
+ * perform authentication, logging, or other cross-cutting concerns.
+ *
+ * @param req - The incoming HTTP request
+ * @param res - The HTTP response object
+ * @param next - Function to call to proceed to the next middleware or handler
+ *
+ * @remarks
+ * Middlewares must call `next()` to continue the chain. Not calling `next()`
+ * will stop execution and prevent the route handler from running.
+ *
+ * @example
+ * ```typescript
+ * export const middlewares = [
+ *   async (req, res, next) => {
+ *     console.log('Before handler');
+ *     await next();
+ *     console.log('After handler');
+ *   }
+ * ];
+ * ```
+ */
+export type LithiaMiddleware = (req: LithiaRequest, res: LithiaResponse, next: () => void) => Promise<void>;
+/**
+ * Structure of a route module loaded from the file system.
+ *
+ * Route files can export a default handler and optionally an array of
+ * middlewares to run before the handler.
+ */
+export interface RouteModule {
+    /**
+     * The default route handler function.
+     *
+     * This is the main function that processes the request and sends a response.
+     */
+    default?: LithiaHandler;
+    /**
+     * Optional array of middlewares executed before the handler.
+     *
+     * Middlewares run in order and must call `next()` to continue.
+     */
+    middlewares?: Array<LithiaMiddleware>;
+}
+/**
+ * Standardized error response format.
+ *
+ * All errors are formatted consistently as JSON with this structure.
+ *
+ * @internal
+ */
+export interface RequestErrorInfo {
+    /** Error details object. */
+    error: {
+        /** Human-readable error message. */
+        message: string;
+        /** HTTP status code. */
+        statusCode: number;
+        /** ISO timestamp of when the error occurred. */
+        timestamp: string;
+        /** Request path that caused the error. */
+        path: string;
+        /** HTTP method of the request. */
+        method: string;
+        /** Short error digest for correlation with logs. */
+        digest?: string;
+        /** Validation error details (for 400 errors). */
+        issues?: any[];
+    };
+}
+/**
+ * Request processor for the Lithia HTTP pipeline.
+ *
+ * This class orchestrates the entire request processing flow from receiving
+ * an HTTP request to sending a response. It manages:
+ *
+ * - **CORS handling**: Preflight requests and CORS headers
+ * - **Static files**: Serving files from configured static directories
+ * - **Route matching**: Finding the route that matches the request path
+ * - **Parameter extraction**: Extracting dynamic route parameters
+ * - **Middleware execution**: Running global and route-specific middlewares
+ * - **Handler invocation**: Executing the route handler function
+ * - **Error handling**: Converting exceptions to structured JSON responses
+ * - **Request logging**: Logging all requests with timing and status codes
+ *
+ * @remarks
+ * The processor uses AsyncLocalStorage to provide request context to hooks,
+ * allowing route handlers to access request/response without explicit parameters.
+ *
+ * In development mode, route modules are reloaded on each request (cache busting).
+ * In production, modules are cached for better performance.
+ */
+export declare class RequestProcessor {
+    private lithia;
+    private httpServer;
+    /**
+     * Creates a new request processor.
+     *
+     * @param lithia - The Lithia application instance
+     */
+    constructor(lithia: Lithia, httpServer: HttpServer);
+    /**
+     * Processes an incoming HTTP request through the complete pipeline.
+     *
+     * This is the main entry point for request processing. The method executes
+     * the following steps in order:
+     *
+     * 1. Initialize request context for hooks
+     * 2. Handle CORS preflight (OPTIONS) requests
+     * 3. Add standard response headers
+     * 4. Attempt to serve static files
+     * 5. Match request to a route
+     * 6. Extract dynamic route parameters
+     * 7. Load the route module
+     * 8. Execute global middlewares
+     * 9. Execute route-specific middlewares
+     * 10. Execute the route handler
+     * 11. Log the request with timing
+     *
+     * Any errors thrown during this process are caught and handled by
+     * {@link handleError}, which sends a structured error response.
+     *
+     * @param req - The incoming HTTP request
+     * @param res - The HTTP response object
+     *
+     * @example
+     * ```typescript
+     * const processor = new RequestProcessor(lithia);
+     * await processor.processRequest(req, res);
+     * ```
+     */
+    processRequest(req: LithiaRequest, res: LithiaResponse): Promise<void>;
+    /**
+     * Executes an array of middlewares sequentially.
+     *
+     * Middlewares are executed in order. Each middleware must call `next()`
+     * to continue to the next middleware in the chain. If a middleware does
+     * not call `next()`, the chain stops and subsequent middlewares are not
+     * executed.
+     *
+     * If any middleware throws an error, execution stops immediately and the
+     * error is returned.
+     *
+     * @param middlewares - Array of middleware functions to execute
+     * @param req - The HTTP request object
+     * @param res - The HTTP response object
+     * @returns null if successful, or an Error if a middleware threw
+     *
+     * @private
+     *
+     * @example
+     * ```typescript
+     * const error = await this.executeMiddlewares(middlewares, req, res);
+     * if (error) {
+     *   throw error;
+     * }
+     * ```
+     */
+    private executeMiddlewares;
+    /**
+     * Sends a structured 404 JSON response for unmatched routes.
+     *
+     * This method is called when no route matches the requested path.
+     * It sends a standardized error response with status 404.
+     *
+     * @param req - The HTTP request that didn't match any route
+     * @param res - The HTTP response object
+     *
+     * @private
+     */
+    private sendNotFound;
+    /**
+     * Centralized error handler for the request pipeline.
+     *
+     * This method handles all errors thrown during request processing:
+     *
+     * **Development mode:**
+     * - Returns detailed error messages
+     * - Includes full error stacks
+     * - Shows validation issues if present
+     *
+     * **Production mode:**
+     * - Returns generic error messages
+     * - Includes error digest for log correlation
+     * - Hides sensitive error details
+     *
+     * All server errors (5xx) are logged with the error digest for correlation
+     * between client responses and server logs.
+     *
+     * @param err - The error that was thrown
+     * @param req - The HTTP request that caused the error
+     * @param res - The HTTP response object
+     * @param start - High-resolution timestamp when request processing started
+     *
+     * @private
+     */
+    private handleError;
+    /**
+     * Logs a completed request with color-coded status and timing.
+     *
+     * The log includes:
+     * - HTTP status code (color-coded by range)
+     * - HTTP method (GET, POST, etc.)
+     * - Request pathname
+     * - Processing duration in milliseconds
+     *
+     * Status colors:
+     * - 2xx: Green (success)
+     * - 3xx: Cyan (redirect)
+     * - 4xx: Yellow (client error)
+     * - 5xx: Red (server error)
+     *
+     * @param req - The HTTP request that was processed
+     * @param res - The HTTP response that was sent
+     * @param start - High-resolution timestamp when processing started
+     *
+     * @private
+     */
+    /**
+     * Logs a completed request with color-coded status and timing.
+     *
+     * The log includes:
+     * - HTTP status code (color-coded by range)
+     * - HTTP method (GET, POST, etc.)
+     * - Request pathname
+     * - Processing duration in milliseconds
+     *
+     * Status colors:
+     * - 2xx: Green (success)
+     * - 3xx: Cyan (redirect)
+     * - 4xx: Yellow (client error)
+     * - 5xx: Red (server error)
+     *
+     * Respects the `logging.requests` configuration flag. Critical errors
+     * (5xx) are always logged regardless of the flag.
+     *
+     * @param req - The HTTP request that was processed
+     * @param res - The HTTP response that was sent
+     * @param start - High-resolution timestamp when processing started
+     *
+     * @private
+     */
+    private logRequest;
+    /**
+     * Generates a short hexadecimal digest for error correlation.
+     *
+     * The digest is used to correlate server-side error logs with client-facing
+     * error responses. This allows developers to find the detailed error in logs
+     * using the digest shown to the client.
+     *
+     * The digest is generated from:
+     * - Error message and stack
+     * - Current timestamp
+     * - Random factor for uniqueness
+     *
+     * @param err - The error to generate a digest for
+     * @returns An 8-character hexadecimal digest
+     *
+     * @private
+     */
+    private generateErrorDigest;
+    /**
+     * Handles CORS preflight requests and applies CORS headers.
+     *
+     * This method:
+     * 1. Checks if the request origin is allowed based on CORS configuration
+     * 2. Adds appropriate CORS headers to the response
+     * 3. Handles OPTIONS preflight requests
+     *
+     * **CORS Headers Applied:**
+     * - `Access-Control-Allow-Origin`: Allowed origin
+     * - `Access-Control-Allow-Credentials`: If credentials are enabled
+     * - `Access-Control-Allow-Methods`: Allowed HTTP methods
+     * - `Access-Control-Allow-Headers`: Allowed request headers
+     * - `Access-Control-Max-Age`: Preflight cache duration
+     * - `Access-Control-Expose-Headers`: Headers exposed to client
+     *
+     * @param req - The HTTP request
+     * @param res - The HTTP response
+     * @returns true if the request was an OPTIONS preflight that was handled, false otherwise
+     *
+     * @private
+     */
+    private handleCors;
+    /**
+     * Attempts to serve a static file from the configured static directory.
+     *
+     * This method:
+     * 1. Checks if static file serving is enabled
+     * 2. Only serves for GET and HEAD requests
+     * 3. Strips configured prefix from the path
+     * 4. Prevents directory traversal attacks
+     * 5. Determines MIME type from file extension
+     * 6. Sends the file with appropriate Content-Type header
+     *
+     * @param req - The HTTP request
+     * @param res - The HTTP response
+     * @returns true if a static file was served, false otherwise
+     * @throws {StaticFileMimeMissingError} If file extension has no configured MIME type
+     *
+     * @private
+     */
+    private serveStaticFile;
+    /**
+     * Finds a route matching the given pathname and HTTP method.
+     *
+     * Routes are matched in the order they were registered. The first route
+     * that matches both the path pattern (via regex) and HTTP method is returned.
+     *
+     * @param pathname - The request pathname to match
+     * @param method - The HTTP method (GET, POST, etc.)
+     * @returns The matched Route, or undefined if no match found
+     *
+     * @private
+     */
+    private findMatchingRoute;
+    /**
+     * Tests whether a pathname matches a route's regex pattern.
+     *
+     * @param pathname - The pathname to test
+     * @param route - The route with the regex pattern
+     * @returns true if the pathname matches the route's regex, false otherwise
+     *
+     * @private
+     */
+    private matchesPath;
+    /**
+     * Imports a route module from the file system.
+     *
+     * In **development mode**, uses cache-busting to reload the module on each
+     * request, enabling hot reloading without server restart.
+     *
+     * In **production mode**, uses standard dynamic imports with caching for
+     * better performance.
+     *
+     * The method also validates the module structure:
+     * - Must have a default export
+     * - Default export must be a function
+     * - Default export must be async
+     *
+     * @param route - The route whose module should be imported
+     * @returns The loaded and validated route module
+     * @throws {InvalidRouteModuleError} If the module structure is invalid
+     * @throws {Error} If the module fails to load
+     *
+     * @private
+     */
+    private importRouteModule;
+    /**
+     * Extracts named route parameters from the pathname.
+     *
+     * For dynamic routes like `/users/:id/posts/:postId`, this method:
+     * 1. Matches the pathname against the route's regex
+     * 2. Extracts parameter names from the route path (e.g., "id", "postId")
+     * 3. Maps regex capture groups to parameter names
+     * 4. URL-decodes parameter values
+     *
+     * @param pathname - The request pathname
+     * @param route - The matched route with dynamic segments
+     * @returns Object mapping parameter names to their values
+     *
+     * @private
+     *
+     * @example
+     * ```typescript
+     * // Route: /users/:id/posts/:postId
+     * // Pathname: /users/123/posts/456
+     * // Returns: { id: '123', postId: '456' }
+     * ```
+     */
+    private extractParams;
+}