qhttpx 1.8.0

package/src/core/server.ts

@@ -0,0 +1,1113 @@
+import http, { IncomingMessage, ServerResponse } from 'http';
+import path from 'path';
+import type { Duplex } from 'stream';
+import { URL } from 'url';
+import pkgJson from '../../package.json';
+import { Router } from '../router/router';
+import { Scheduler } from './scheduler';
+import { TaskEngine } from './tasks';
+import { calculateWorkerCount, isResourceOverloaded } from './resources';
+import { Metrics } from './metrics';
+import { BodyParser } from './body-parser';
+import { BufferPool } from './buffer-pool';
+import { WebSocketManager } from './websocket';
+import { fastJsonStringify, getStringifier } from './serializer';
+import { BatchExecutor } from './batch';
+import { RequestFusion } from './fusion';
+import { SimpleValidator } from '../validation/simple';
+import { RouteSchema, Validator } from '../validation/types';
+import { OpenAPIGenerator, OpenAPIOptions } from '../openapi/generator';
+import {
+  HTTPMethod,
+  HttpError,
+  QHTTPXContext,
+  QHTTPXErrorHandler,
+  QHTTPXHandler,
+  QHTTPXMethodNotAllowedHandler,
+  QHTTPXMiddleware,
+  QHTTPXNotFoundHandler,
+  QHTTPXOptions,
+  QHTTPXRouteOptions,
+  QHTTPXTracer,
+  RoutePriority,
+  QHTTPXPlugin,
+  QHTTPXPluginOptions,
+  CookieOptions,
+} from './types';
+
+import { parseCookies, serializeCookie } from '../utils/cookies';
+import { QHTTPXScope } from './scope';
+import { Logger } from './logger';
+
+export class QHTTPX {
+  private readonly options: QHTTPXOptions;
+
+  private readonly server: http.Server;
+  
+  public readonly logger: Logger;
+
+  private readonly router: Router;
+
+  private readonly scheduler: Scheduler;
+
+  private readonly middlewares: QHTTPXMiddleware[] = [];
+
+  private readonly workerCount: number;
+
+  private readonly tasks: TaskEngine;
+
+  private readonly metrics: Metrics;
+
+  private readonly contextPool: QHTTPXContext[] = [];
+
+  private readonly bufferPool: BufferPool;
+
+  private pipelineRunner: ((ctx: QHTTPXContext, handler: QHTTPXHandler) => Promise<void>) | null = null;
+
+  private errorHandler?: QHTTPXErrorHandler;
+
+  private notFoundHandler?: QHTTPXNotFoundHandler;
+
+  private methodNotAllowedHandler?: QHTTPXMethodNotAllowedHandler;
+
+  private readonly tracer?: QHTTPXTracer;
+
+  private readonly onStartHooks: Array<() => void | Promise<void>> = [];
+
+  private readonly onBeforeShutdownHooks: Array<() => void | Promise<void>> = [];
+
+  private readonly onShutdownHooks: Array<() => void | Promise<void>> = [];
+
+  private nextRequestId = 1;
+
+  private readonly wsManager: WebSocketManager;
+
+  private readonly ultraMode: boolean;
+
+  private readonly batchExecutor?: BatchExecutor;
+
+  private readonly fusion?: RequestFusion;
+
+  private readonly validator: Validator;
+
+  constructor(options: QHTTPXOptions = {}) {
+    this.options = options;
+    this.logger = new Logger({
+      name: options.name,
+      level: options.performanceMode === 'ultra' ? 'error' : 'info'
+    });
+    this.ultraMode = options.performanceMode === 'ultra';
+    this.errorHandler = this.ultraMode ? undefined : options.errorHandler;
+    this.notFoundHandler = this.ultraMode ? undefined : options.notFoundHandler;
+    this.methodNotAllowedHandler = this.ultraMode ? undefined : options.methodNotAllowedHandler;
+    this.tracer = this.ultraMode ? undefined : options.tracer;
+    this.workerCount = calculateWorkerCount(options.workers ?? 'auto');
+    this.router = new Router();
+    this.wsManager = new WebSocketManager(this.generateRequestId.bind(this));
+    this.bufferPool = new BufferPool(options.bufferPoolConfig);
+    const maxConcurrency = options.maxConcurrency ?? 1024;
+    this.scheduler = new Scheduler({
+      maxConcurrency,
+    });
+    this.tasks = new TaskEngine(this.scheduler);
+    
+    if (options.enableBatching) {
+      this.batchExecutor = new BatchExecutor(options.database);
+    }
+
+    if (options.enableRequestFusion) {
+      this.fusion = new RequestFusion(options.enableRequestFusion);
+    }
+
+    this.validator = options.validator ?? new SimpleValidator();
+
+    this.metrics = new Metrics(
+      this.scheduler,
+      {
+        enabled: !this.ultraMode && (this.options.metricsEnabled ?? true),
+      },
+      this.tasks,
+    );
+    for (let i = 0; i < maxConcurrency; i += 1) {
+      this.contextPool.push(this.createContext());
+    }
+    this.registerInternalRoutes();
+    this.compileMiddlewarePipeline();
+    this.server = http.createServer(this.handleRequest.bind(this));
+    if (this.options.keepAliveTimeoutMs !== undefined) {
+      this.server.keepAliveTimeout = this.options.keepAliveTimeoutMs;
+    } else if (this.ultraMode) {
+      this.server.keepAliveTimeout = 0;
+    }
+    if (this.options.headersTimeoutMs !== undefined) {
+      this.server.headersTimeout = this.options.headersTimeoutMs;
+    } else if (this.ultraMode) {
+      this.server.headersTimeout = 0;
+    }
+    if (this.ultraMode) {
+      this.server.requestTimeout = 0;
+      this.server.maxHeadersCount = 0;
+      this.server.timeout = 0;
+    }
+    this.server.on('upgrade', (req, socket, head) => {
+      void this.handleUpgrade(req, socket, head);
+    });
+  }
+
+  get serverInstance(): http.Server {
+    return this.server;
+  }
+
+  get websocket(): WebSocketManager {
+    return this.wsManager;
+  }
+
+  setErrorHandler(handler: QHTTPXErrorHandler): void {
+    this.errorHandler = handler;
+  }
+
+  setNotFoundHandler(handler: QHTTPXNotFoundHandler): void {
+    this.notFoundHandler = handler;
+  }
+
+  setMethodNotAllowedHandler(handler: QHTTPXMethodNotAllowedHandler): void {
+    this.methodNotAllowedHandler = handler;
+  }
+
+  set404Handler(handler: QHTTPXNotFoundHandler): void {
+    this.setNotFoundHandler(handler);
+  }
+
+  set405Handler(handler: QHTTPXMethodNotAllowedHandler): void {
+    this.setMethodNotAllowedHandler(handler);
+  }
+
+  onStart(hook: () => void | Promise<void>): void {
+    this.onStartHooks.push(hook);
+  }
+
+  onBeforeShutdown(hook: () => void | Promise<void>): void {
+    this.onBeforeShutdownHooks.push(hook);
+  }
+
+  onShutdown(hook: () => void | Promise<void>): void {
+    this.onShutdownHooks.push(hook);
+  }
+
+  upgrade(
+    path: string,
+    handler: import('./websocket').WSHandler,
+  ): void {
+    this.wsManager.register(path, handler);
+  }
+
+  use(middleware: QHTTPXMiddleware): void {
+    this.middlewares.push(middleware);
+    // Recompile pipeline after middleware is added
+    this.compileMiddlewarePipeline();
+  }
+
+  private compileMiddlewarePipeline(): void {
+    const middlewares = this.middlewares;
+
+    if (middlewares.length === 0) {
+      this.pipelineRunner = async (ctx, handler) => {
+        const result = handler(ctx);
+        if (result && typeof (result as Promise<void>).then === 'function') {
+          await result;
+        }
+      };
+      return;
+    }
+
+    // Flatten middleware pipeline into a single function chain
+    // This eliminates Promise nesting, recursive dispatch overhead, and microtask backlogs
+    // Each middleware executes directly without closure allocation overhead
+    this.pipelineRunner = async (ctx, handler) => {
+      let index = 0;
+      
+      const executeNext = async (): Promise<void> => {
+        if (index >= middlewares.length) {
+          // All middlewares done, execute handler
+          const result = handler(ctx);
+          if (result && typeof (result as unknown as Record<string, unknown>).then === 'function') {
+            await (result as Promise<void>);
+          }
+          return;
+        }
+        
+        const currentIndex = index;
+        index += 1;
+        
+        const result = middlewares[currentIndex](ctx, executeNext);
+        if (result && typeof (result as unknown as Record<string, unknown>).then === 'function') {
+          await (result as Promise<void>);
+        }
+      };
+
+      await executeNext();
+    };
+  }
+
+  private compileRoutePipeline(
+    handler: QHTTPXHandler,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    schema?: RouteSchema | Record<string, any>,
+  ): QHTTPXHandler {
+    const middlewares = this.middlewares;
+    
+    // Heuristic: Is it a structured RouteSchema or a legacy ResponseSchema?
+    let responseSchema: unknown | undefined;
+    let requestSchema: RouteSchema | undefined;
+
+    if (schema) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const s = schema as any;
+      if (s.body || s.query || s.params || s.headers || s.response) {
+        // It is a RouteSchema
+        requestSchema = s;
+        responseSchema = s.response;
+      } else {
+        // It is a legacy ResponseSchema
+        responseSchema = s;
+      }
+    }
+
+    const stringifier = responseSchema ? getStringifier(responseSchema) : undefined;
+
+    // Build middleware chain
+    let pipeline = handler;
+
+    // Wrap with validation if needed (before handler, after global middleware)
+    if (requestSchema) {
+      const inner = pipeline;
+      pipeline = async (ctx) => {
+        // Validate Body
+        if (requestSchema!.body) {
+          const result = await this.validator.validate(requestSchema!.body, ctx.body);
+          if (!result.success) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const err = result.error as any;
+            ctx.json({ error: 'Validation Error', details: err.details || err.message || err }, 400);
+            return;
+          }
+          ctx.body = result.data;
+        }
+
+        // Validate Query
+        if (requestSchema!.query) {
+          const result = await this.validator.validate(requestSchema!.query, ctx.query);
+          if (!result.success) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const err = result.error as any;
+            ctx.json({ error: 'Validation Error', details: err.details || err.message || err }, 400);
+            return;
+          }
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          (ctx as any).query = result.data;
+        }
+
+        // Validate Params
+        if (requestSchema!.params) {
+          const result = await this.validator.validate(requestSchema!.params, ctx.params);
+          if (!result.success) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const err = result.error as any;
+            ctx.json({ error: 'Validation Error', details: err.details || err.message || err }, 400);
+            return;
+          }
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          (ctx as any).params = result.data;
+        }
+
+        return inner(ctx);
+      };
+    }
+
+    // Wrap with Request Fusion if enabled
+    if (this.fusion) {
+      const inner = pipeline;
+      pipeline = (ctx) => this.fusion!.coalesce(ctx, inner);
+    }
+
+    // We iterate backwards to wrap the handler
+    // pipeline = m[last](ctx, () => pipeline(ctx))
+    for (let i = middlewares.length - 1; i >= 0; i -= 1) {
+      const middleware = middlewares[i];
+      const next = pipeline;
+      pipeline = (ctx) => {
+        return middleware(ctx, async () => {
+          const result = next(ctx);
+          if (result && typeof (result as Promise<void>).then === 'function') {
+            await result;
+          }
+        });
+      };
+    }
+
+    if (stringifier) {
+      const inner = pipeline;
+      return (ctx) => {
+        ctx.serializer = stringifier;
+        return inner(ctx);
+      };
+    }
+
+    return pipeline;
+  }
+
+  // Internal registration to be accessed by Scopes
+  public _registerRoute(
+    method: HTTPMethod,
+    path: string,
+    handlerOrOptions: QHTTPXHandler | QHTTPXRouteOptions,
+  ): void {
+    this.registerRoute(method, path, handlerOrOptions);
+  }
+
+  public async register<Options extends QHTTPXPluginOptions>(
+    plugin: QHTTPXPlugin<Options>,
+    options?: Options
+  ): Promise<void> {
+    const scope = new QHTTPXScope(this, options?.prefix);
+    await plugin(scope, options as Options);
+  }
+
+  private registerRoute(
+    method: HTTPMethod,
+    path: string,
+    handlerOrOptions: QHTTPXHandler | QHTTPXRouteOptions,
+  ): void {
+    let handler: QHTTPXHandler;
+    let schema: RouteSchema | Record<string, unknown> | undefined;
+    const options: { priority?: RoutePriority } = {};
+
+    if (typeof handlerOrOptions === 'function') {
+      handler = handlerOrOptions;
+    } else {
+      handler = handlerOrOptions.handler;
+      schema = handlerOrOptions.schema;
+      options.priority = handlerOrOptions.priority;
+    }
+
+    const compiled = this.compileRoutePipeline(handler, schema);
+    this.router.register(method, path, compiled, { ...options, schema });
+  }
+
+  get(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void {
+    this.registerRoute('GET', path, handler);
+  }
+
+  post(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void {
+    this.registerRoute('POST', path, handler);
+  }
+
+  put(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void {
+    this.registerRoute('PUT', path, handler);
+  }
+
+  delete(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void {
+    this.registerRoute('DELETE', path, handler);
+  }
+
+  route(path: string) {
+    const register = (method: HTTPMethod, handler: QHTTPXHandler | QHTTPXRouteOptions) => {
+      this.registerRoute(method, path, handler);
+    };
+
+    const builder = {
+      get(handler: QHTTPXHandler | QHTTPXRouteOptions) {
+        register('GET', handler);
+        return this;
+      },
+      post(handler: QHTTPXHandler | QHTTPXRouteOptions) {
+        register('POST', handler);
+        return this;
+      },
+      put(handler: QHTTPXHandler | QHTTPXRouteOptions) {
+        register('PUT', handler);
+        return this;
+      },
+      delete(handler: QHTTPXHandler | QHTTPXRouteOptions) {
+        register('DELETE', handler);
+        return this;
+      },
+    };
+
+    return builder;
+  }
+
+  task(
+    name: string,
+    handler: import('./types').QHTTPXTaskHandler,
+    options?: import('./types').QHTTPXTaskOptions,
+  ): void {
+    this.tasks.register(name, handler, options);
+  }
+
+  enqueue(name: string, payload: unknown): Promise<void> {
+    return this.tasks.enqueue(name, payload);
+  }
+
+  op(name: string, handler: import('./types').QHTTPXOpHandler): void {
+    if (!this.batchExecutor) {
+      // Auto-enable batch executor if op is called?
+      // Or throw?
+      // Better to throw or warn if not enabled.
+      // But for ease of use, let's create it if missing (but we miss DB context if done this way without options)
+      // The constructor handles options. If enableBatching is false, we shouldn't be here.
+      throw new Error('Batching is not enabled. Pass enableBatching: true to QHTTPX options.');
+    }
+    this.batchExecutor.register(name, handler);
+  }
+
+  private registerInternalRoutes(): void {
+    this.router.register('GET', '/__qhttpx/health', (ctx) => {
+      const version = typeof pkgJson.version === 'string' ? pkgJson.version : '';
+      const name = typeof pkgJson.name === 'string' ? pkgJson.name : '';
+
+      ctx.json({
+        status: 'ok',
+        name,
+        version,
+        workers: this.workerCount,
+      });
+    });
+
+    this.router.register('GET', '/__qhttpx/metrics', (ctx) => {
+      const snapshot = this.metrics.snapshot();
+      ctx.json({
+        ...snapshot,
+        workers: this.workerCount,
+      });
+    });
+
+    this.router.register('GET', '/__qhttpx/runtime', (ctx) => {
+      const schedulerStats = this.scheduler.getStats();
+      ctx.json({
+        workers: this.workerCount,
+        router: {
+          frozen: this.router.isFrozenRouter(),
+        },
+        scheduler: schedulerStats,
+      });
+    });
+
+    if (this.options.enableBatching && this.batchExecutor) {
+      const endpoint = typeof this.options.enableBatching === 'object' 
+        ? this.options.enableBatching.endpoint 
+        : '/qhttpx';
+        
+      this.router.register('POST', endpoint, async (ctx) => {
+         // eslint-disable-next-line @typescript-eslint/no-explicit-any
+         const body = ctx.body as any;
+         if (!body || !Array.isArray(body.batch)) {
+           ctx.json({ error: 'Invalid batch format' }, 400);
+           return;
+         }
+         
+         try {
+           const result = await this.batchExecutor!.handleBatch(ctx, body.batch);
+           ctx.json(result);
+         } catch (err) {
+           // eslint-disable-next-line @typescript-eslint/no-explicit-any
+           ctx.json({ error: (err as any).message }, 500);
+         }
+       });
+    }
+  }
+
+  getOpenAPI(options: OpenAPIOptions): object {
+    const generator = new OpenAPIGenerator(this.router, options);
+    return generator.generate();
+  }
+
+  public async listen(port: number, hostname?: string): Promise<{ port: number }> {
+    if (this.options.database) {
+      await this.options.database.connect();
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    if ((this.options as any).plugins) {
+      // Plugins are registered synchronously in constructor, but their async init happens now?
+      // Actually, plugins are registered via app.register() which is async.
+      // So they should be ready.
+    }
+
+    return new Promise((resolve, reject) => {
+      const onError = (error: unknown) => {
+        this.server.off('error', onError);
+        reject(error);
+      };
+
+      this.server.once('error', onError);
+
+      this.server.listen(port, hostname, () => {
+        this.server.off('error', onError);
+        // Freeze router after server starts to prevent further registrations
+        this.router.freeze();
+        void this.runLifecycleHooks(this.onStartHooks);
+        const address = this.server.address();
+        if (address && typeof address === 'object') {
+          resolve({ port: address.port });
+        } else {
+          resolve({ port });
+        }
+      });
+    });
+  }
+
+  close(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.server.close((err) => {
+        if (err) {
+          reject(err);
+          return;
+        }
+        resolve();
+      });
+    });
+  }
+
+  async shutdown(): Promise<void> {
+    await this.runLifecycleHooks(this.onBeforeShutdownHooks);
+    await this.close();
+    await this.runLifecycleHooks(this.onShutdownHooks);
+  }
+
+  private createContext(): QHTTPXContext {
+    const jsonSerializer = this.options.jsonSerializer;
+    const useFastStringify = jsonSerializer === undefined;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const ctx: any = {
+      req: null,
+      res: null,
+      url: null,
+      params: null,
+      query: null,
+      body: undefined,
+      cookies: null,
+      state: null,
+      bufferPool: this.bufferPool,
+      requestId: '',
+      requestStart: 0,
+      serializer: null,
+      json(payload: unknown, status = 200) {
+        const res = this.res;
+        if (!res.headersSent) {
+          res.statusCode = status;
+          res.setHeader('content-type', 'application/json; charset=utf-8');
+        }
+        let body: string | Buffer;
+        if (this.serializer) {
+          body = this.serializer(payload);
+        } else if (useFastStringify) {
+          body = fastJsonStringify(payload);
+        } else if (jsonSerializer) {
+          body = jsonSerializer(payload);
+        } else {
+          body = JSON.stringify(payload);
+        }
+        res.end(body);
+      },
+      send(payload: string | Buffer, status = 200) {
+        const res = this.res;
+        if (!res.headersSent) {
+          res.statusCode = status;
+        }
+        res.end(payload);
+      },
+      html(payload: string, status = 200) {
+        const res = this.res;
+        if (!res.headersSent) {
+          res.statusCode = status;
+          res.setHeader('content-type', 'text/html; charset=utf-8');
+        }
+        res.end(payload);
+      },
+      redirect(url: string, status = 302) {
+        const res = this.res;
+        if (!res.headersSent) {
+          res.statusCode = status;
+          res.setHeader('Location', url);
+        }
+        res.end();
+      },
+      setCookie(name: string, value: string, options: CookieOptions | undefined) {
+         const res = this.res;
+         const serialized = serializeCookie(name, value, options);
+        let existing = res.getHeader('Set-Cookie');
+        if (Array.isArray(existing)) {
+          existing.push(serialized);
+          res.setHeader('Set-Cookie', existing);
+        } else if (existing) {
+          res.setHeader('Set-Cookie', [existing as string, serialized]);
+        } else {
+          res.setHeader('Set-Cookie', serialized);
+        }
+      },
+      db: this.options.database,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      render: async (view: string, locals?: Record<string, any>) => {
+        const engine = this.options.viewEngine;
+        if (!engine) {
+          throw new Error('No view engine registered');
+        }
+        const viewsPath = this.options.viewsPath || process.cwd();
+        const fullPath = path.resolve(viewsPath, view);
+
+        const html = await engine.render(fullPath, locals || {});
+        
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const res = (ctx as any).res;
+        if (!res.headersSent) {
+          res.statusCode = 200;
+          res.setHeader('content-type', 'text/html; charset=utf-8');
+        }
+        res.end(html);
+      },
+      validate: async <T>(schema: unknown, data?: unknown): Promise<T> => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const target = data ?? (ctx as any).body;
+        const result = await this.validator.validate(schema, target);
+        if (result.success) {
+          return result.data as T;
+        }
+        throw new HttpError(400, 'Validation Error', {
+          code: 'VALIDATION_ERROR',
+          details: result.error,
+        });
+      },
+    };
+    return ctx;
+  }
+
+  private acquireContext(
+    req: IncomingMessage,
+    res: ServerResponse,
+    url: URL,
+    params: Record<string, string>,
+    query: Record<string, string | string[]>,
+    requestId: string | undefined,
+    body: unknown,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    files?: Record<string, any>,
+  ): QHTTPXContext {
+    const ctx = this.contextPool.pop() ?? this.createContext();
+    // Reset and populate properties
+    // We use type assertions to write to readonly/managed properties for performance
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const mutableCtx = ctx as any;
+    mutableCtx.req = req;
+    mutableCtx.res = res;
+    mutableCtx.url = url;
+    mutableCtx.params = params;
+    mutableCtx.query = query;
+    mutableCtx.body = body;
+    mutableCtx.files = files;
+    mutableCtx.requestId = requestId;
+    mutableCtx.serializer = undefined;
+    // In ultra mode, skip cookie parsing to save overhead
+    if (!this.ultraMode) {
+      mutableCtx.cookies = parseCookies(req.headers.cookie);
+    }
+    mutableCtx.state = {};
+    mutableCtx.disableAutoEnd = false;
+    
+    return ctx;
+  }
+
+  private releaseContext(ctx: QHTTPXContext) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const mutableCtx = ctx as any;
+    mutableCtx.req = null;
+    mutableCtx.res = null;
+    mutableCtx.url = null;
+    mutableCtx.params = null;
+    mutableCtx.query = null;
+    mutableCtx.body = undefined;
+    mutableCtx.files = undefined;
+    mutableCtx.requestId = '';
+    mutableCtx.requestStart = 0;
+    mutableCtx.serializer = null;
+    mutableCtx.cookies = null;
+    mutableCtx.state = null;
+    // render method is static per context instance creation (closure over options), 
+    // but good to keep it consistent.
+    // Wait, 'render' is defined in 'createContext' and depends on 'this.options'.
+    // It doesn't hold request-specific state other than 'res' which is updated in 'acquireContext'.
+    // So we don't need to null it out.
+    
+    if (this.contextPool.length < (this.options.maxConcurrency ?? 1024)) {
+      this.contextPool.push(ctx);
+    }
+  }
+
+  private async handleRequest(req: IncomingMessage, res: ServerResponse) {
+    const rawMethod = (req.method || 'GET').toUpperCase();
+    const method = rawMethod as HTTPMethod;
+    const rawUrl = req.url || '/';
+    const host = req.headers.host || 'localhost';
+    const url = new URL(rawUrl, `http://${host}`);
+
+    const incomingRequestIdHeader = req.headers['x-request-id'];
+    let requestId: string | undefined;
+    if (typeof incomingRequestIdHeader === 'string') {
+      requestId = incomingRequestIdHeader;
+    } else if (Array.isArray(incomingRequestIdHeader)) {
+      requestId = incomingRequestIdHeader[0];
+    }
+    if (!requestId) {
+      requestId = this.generateRequestId();
+    }
+    if (!res.headersSent && requestId) {
+      res.setHeader('x-request-id', requestId);
+    }
+
+    let match = this.router.match(method, url.pathname);
+    const hasRoute = !!match;
+
+    if (!match) {
+      match = {
+        handler: () => {},
+        params: {},
+        priority: RoutePriority.STANDARD,
+      };
+    }
+
+    const allowedMethods = this.router.getAllowedMethods(url.pathname);
+
+    if (!hasRoute && !res.headersSent) {
+      const hasAnyMethod = allowedMethods.length > 0;
+      res.statusCode = hasAnyMethod ? 405 : 404;
+    }
+
+    const query: Record<string, string | string[]> = {};
+    url.searchParams.forEach((value, key) => {
+      if (Object.prototype.hasOwnProperty.call(query, key)) {
+        const existing = query[key];
+        if (Array.isArray(existing)) {
+          existing.push(value);
+        } else {
+          query[key] = [existing, value];
+        }
+      } else {
+        query[key] = value;
+      }
+    });
+
+    if (this.options.maxMemoryBytes !== undefined) {
+      const sampleRss = process.memoryUsage().rss;
+      const overloadedByMemory = isResourceOverloaded(
+        { rssBytes: sampleRss },
+        { maxRssBytes: this.options.maxMemoryBytes },
+      );
+      if (overloadedByMemory) {
+        const overloaded = () => {
+          if (res.writableEnded) {
+            return;
+          }
+          if (!res.headersSent) {
+            res.statusCode = 503;
+            res.setHeader('content-type', 'text/plain; charset=utf-8');
+          }
+          res.end('Server overloaded');
+        };
+        overloaded();
+        return;
+      }
+    }
+
+    let body: unknown;
+    let files: Record<string, unknown> | undefined;
+
+    if (method !== 'GET' && method !== 'HEAD') {
+      try {
+        const parsed = await BodyParser.parse(req, {
+          maxBodyBytes: this.options.maxBodyBytes,
+        });
+        body = parsed.body;
+        files = parsed.files;
+      } catch (err) {
+        if (err instanceof Error && err.message === 'QHTTPX_INVALID_JSON') {
+          if (!res.headersSent) {
+            res.statusCode = 400;
+            res.setHeader('content-type', 'text/plain; charset=utf-8');
+          }
+          res.end('Invalid JSON');
+          return;
+        }
+        if (err instanceof Error && err.message === 'QHTTPX_BODY_TOO_LARGE') {
+          if (!res.headersSent) {
+            res.statusCode = 413;
+            res.setHeader('content-type', 'text/plain; charset=utf-8');
+          }
+          res.end('Payload Too Large');
+          return;
+        }
+
+        if (!res.headersSent) {
+          res.statusCode = 500;
+          res.setHeader('content-type', 'text/plain; charset=utf-8');
+        }
+        res.end('Internal Server Error');
+        return;
+      }
+    }
+
+    const ctx = this.acquireContext(
+      req,
+      res,
+      url,
+      match.params,
+      query,
+      requestId,
+      body,
+      files,
+    );
+
+    const overloaded = () => {
+      if (res.writableEnded) {
+        return;
+      }
+      if (!res.headersSent) {
+        res.statusCode = 503;
+        res.setHeader('content-type', 'text/plain; charset=utf-8');
+      }
+      res.end('Server overloaded');
+    };
+
+    let timedOut = false;
+
+    const onTimeout = () => {
+      timedOut = true;
+      if (res.writableEnded) {
+        return;
+      }
+      if (!res.headersSent) {
+        res.statusCode = 504;
+        res.setHeader('content-type', 'text/plain; charset=utf-8');
+      }
+      res.end('Request timed out');
+    };
+
+    const start = Date.now();
+    ctx.requestStart = start;
+    if (!this.ultraMode) {
+      this.metrics.onRequestStart();
+    }
+
+    if (this.tracer) {
+      const event = {
+        type: 'request_start' as const,
+        method,
+        path: url.pathname,
+        requestId,
+      };
+      const result = this.tracer(event);
+      if (result && typeof (result as Promise<void>).then === 'function') {
+        void result;
+      }
+    }
+
+    const handle = async () => {
+      const handler = match.handler;
+
+      try {
+        if (hasRoute) {
+          // Optimized path: Route handler is already compiled with middlewares
+          const result = handler(ctx);
+          if (result && typeof (result as Promise<void>).then === 'function') {
+            await result;
+          }
+        } else if (this.pipelineRunner) {
+          // Slow path: Run global middleware pipeline for 404/405
+          await this.pipelineRunner(ctx, handler);
+        }
+
+        if (!res.writableEnded) {
+          if (!hasRoute) {
+            const hasAnyMethod = allowedMethods.length > 0;
+            if (hasAnyMethod && this.methodNotAllowedHandler) {
+              const result = this.methodNotAllowedHandler(
+                ctx,
+                allowedMethods,
+              );
+              if (
+                result &&
+                typeof (result as Promise<void>).then === 'function'
+              ) {
+                await result;
+              }
+              if (!res.writableEnded && !res.headersSent) {
+                res.statusCode = 405;
+                res.setHeader(
+                  'content-type',
+                  'text/plain; charset=utf-8',
+                );
+                res.end('Method Not Allowed');
+              }
+            } else if (!hasAnyMethod && this.notFoundHandler) {
+              const result = this.notFoundHandler(ctx);
+              if (
+                result &&
+                typeof (result as Promise<void>).then === 'function'
+              ) {
+                await result;
+              }
+              if (!res.writableEnded && !res.headersSent) {
+                res.statusCode = 404;
+                res.setHeader(
+                  'content-type',
+                  'text/plain; charset=utf-8',
+                );
+                res.end('Not Found');
+              }
+            } else if (hasAnyMethod) {
+              if (!res.headersSent) {
+                res.statusCode = 405;
+                res.setHeader(
+                  'content-type',
+                  'text/plain; charset=utf-8',
+                );
+              }
+              res.end('Method Not Allowed');
+            } else {
+              if (!res.headersSent) {
+                res.statusCode = 404;
+                res.setHeader(
+                  'content-type',
+                  'text/plain; charset=utf-8',
+                );
+              }
+              res.end('Not Found');
+            }
+          } else if (!ctx.disableAutoEnd) {
+            res.end();
+          }
+        }
+      } catch (err) {
+        await this.handleError(err, ctx);
+      }
+    };
+
+    if (this.ultraMode) {
+      await handle();
+    } else {
+      await this.scheduler.run(handle, {
+        priority: match.priority,
+        onOverloaded: overloaded,
+        timeoutMs: this.options.requestTimeoutMs,
+        onTimeout,
+      });
+    }
+
+    const duration = Date.now() - start;
+    if (!this.ultraMode) {
+      this.metrics.onRequestEnd(duration, res.statusCode);
+      if (timedOut) {
+        this.metrics.onTimeout();
+      }
+    }
+
+    if (this.tracer) {
+      const event = {
+        type: 'request_end' as const,
+        method,
+        path: url.pathname,
+        statusCode: res.statusCode,
+        durationMs: duration,
+        requestId,
+      };
+      const result = this.tracer(event);
+      if (result && typeof (result as Promise<void>).then === 'function') {
+        void result;
+      }
+    }
+
+    this.releaseContext(ctx);
+  }
+
+  private async handleUpgrade(
+    req: IncomingMessage,
+    socket: Duplex,
+    head: Buffer,
+  ): Promise<void> {
+    await this.wsManager.handleUpgrade(req, socket, head);
+  }
+
+  private async runLifecycleHooks(
+    hooks: Array<() => void | Promise<void>>,
+  ): Promise<void> {
+    if (hooks.length === 0) {
+      return;
+    }
+    for (const hook of hooks) {
+      try {
+        const result = hook();
+        if (result && typeof (result as Promise<void>).then === 'function') {
+          await result;
+        }
+      } catch {
+        // Ignore hook errors to avoid impacting core server flow
+      }
+    }
+  }
+
+  private async handleError(err: unknown, ctx: QHTTPXContext): Promise<void> {
+    const res = ctx.res;
+
+    if (res.writableEnded) {
+      return;
+    }
+
+    if (this.errorHandler) {
+      try {
+        const result = this.errorHandler(err, ctx);
+        if (result && typeof (result as Promise<void>).then === 'function') {
+          await result;
+        }
+        if (res.writableEnded) {
+          return;
+        }
+      } catch {
+        // Fall through to default error handling below
+      }
+    }
+
+    if (res.writableEnded) {
+      return;
+    }
+
+    if (err instanceof HttpError) {
+      if (!res.headersSent) {
+        res.statusCode = err.status;
+        res.setHeader('content-type', 'application/json; charset=utf-8');
+      }
+      const payload = {
+        error: {
+          message: err.message,
+          code: err.code ?? 'HTTP_ERROR',
+          details: err.details,
+        },
+      };
+      const serializer = this.options.jsonSerializer;
+      const body =
+        serializer !== undefined ? serializer(payload) : JSON.stringify(payload);
+      res.end(body);
+      return;
+    }
+
+    if (!res.headersSent) {
+      res.statusCode = 500;
+      res.setHeader('content-type', 'text/plain; charset=utf-8');
+    }
+    res.end('Internal Server Error');
+  }
+
+  private generateRequestId(): string {
+    const id = this.nextRequestId;
+    this.nextRequestId += 1;
+    return `${Date.now().toString(36)}-${id.toString(36)}`;
+  }
+}