qhttpx 1.8.5 → 1.8.11

package/src/core/server.ts

@@ -1,1234 +0,0 @@
-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);
-  }
-
-  /**
-   * Alias for setErrorHandler
-   */
-  onError(handler: QHTTPXErrorHandler): void {
-    this.setErrorHandler(handler);
-  }
-
-  /**
-   * Alias for setNotFoundHandler
-   */
-  notFound(handler: QHTTPXNotFoundHandler): void {
-    this.setNotFoundHandler(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) => {
-        const nextFn = async () => {
-          const result = next(ctx);
-          if (result && typeof (result as Promise<void>).then === 'function') {
-            await result;
-          }
-        };
-        // Attach next to ctx for destructuring support
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        (ctx as any).next = nextFn;
-
-        return middleware(ctx, nextFn);
-      };
-    }
-
-    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
-      | import('./types').QHTTPXRouteConfig,
-    handlerIfOptions?: QHTTPXHandler,
-  ): void {
-    let handler: QHTTPXHandler;
-    let schema: RouteSchema | Record<string, unknown> | undefined;
-    const options: { priority?: RoutePriority } = {};
-
-    if (typeof handlerOrOptions === 'function') {
-      handler = handlerOrOptions;
-    } else if (handlerIfOptions) {
-      handler = handlerIfOptions;
-      schema = handlerOrOptions.schema;
-      options.priority = handlerOrOptions.priority;
-    } else {
-      const opts = handlerOrOptions as QHTTPXRouteOptions;
-      handler = opts.handler;
-      schema = opts.schema;
-      options.priority = opts.priority;
-    }
-
-    const compiled = this.compileRoutePipeline(handler, schema);
-    this.router.register(method, path, compiled, { ...options, schema });
-  }
-
-  get(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void;
-  get(
-    path: string,
-    config: import('./types').QHTTPXRouteConfig,
-    handler: QHTTPXHandler,
-  ): void;
-  get(
-    path: string,
-    handlerOrOptions:
-      | QHTTPXHandler
-      | QHTTPXRouteOptions
-      | import('./types').QHTTPXRouteConfig,
-    handler?: QHTTPXHandler,
-  ): void {
-    this.registerRoute('GET', path, handlerOrOptions, handler);
-  }
-
-  post(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void;
-  post(
-    path: string,
-    config: import('./types').QHTTPXRouteConfig,
-    handler: QHTTPXHandler,
-  ): void;
-  post(
-    path: string,
-    handlerOrOptions:
-      | QHTTPXHandler
-      | QHTTPXRouteOptions
-      | import('./types').QHTTPXRouteConfig,
-    handler?: QHTTPXHandler,
-  ): void {
-    this.registerRoute('POST', path, handlerOrOptions, handler);
-  }
-
-  put(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void;
-  put(
-    path: string,
-    config: import('./types').QHTTPXRouteConfig,
-    handler: QHTTPXHandler,
-  ): void;
-  put(
-    path: string,
-    handlerOrOptions:
-      | QHTTPXHandler
-      | QHTTPXRouteOptions
-      | import('./types').QHTTPXRouteConfig,
-    handler?: QHTTPXHandler,
-  ): void {
-    this.registerRoute('PUT', path, handlerOrOptions, handler);
-  }
-
-  delete(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void;
-  delete(
-    path: string,
-    config: import('./types').QHTTPXRouteConfig,
-    handler: QHTTPXHandler,
-  ): void;
-  delete(
-    path: string,
-    handlerOrOptions:
-      | QHTTPXHandler
-      | QHTTPXRouteOptions
-      | import('./types').QHTTPXRouteConfig,
-    handler?: QHTTPXHandler,
-  ): void {
-    this.registerRoute('DELETE', path, handlerOrOptions, 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,
-    hostnameOrCallback?: string | (() => void),
-    callback?: () => void,
-  ): Promise<{ port: number }> {
-    let hostname: string | undefined;
-    let cb: (() => void) | undefined;
-
-    if (typeof hostnameOrCallback === 'function') {
-      cb = hostnameOrCallback;
-      hostname = undefined;
-    } else {
-      hostname = hostnameOrCallback;
-      cb = callback;
-    }
-
-    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 (cb) cb();
-
-        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,
-      headers: null,
-      url: null,
-      params: null,
-      query: null,
-      body: undefined,
-      cookies: null,
-      state: null,
-      bufferPool: this.bufferPool,
-      requestId: '',
-      requestStart: 0,
-      serializer: null,
-      path: '',
-      error: undefined,
-      db: this.options.database,
-    };
-
-    // Helper to get response object from closure-captured ctx
-    // We use arrow functions to ensure they don't depend on 'this' context at call site
-    // enabling destructuring like: ({ json }) => json(...)
-
-    ctx.json = (payload: unknown, status = 200) => {
-      const res = ctx.res;
-      if (!res.headersSent) {
-        res.statusCode = status;
-        res.setHeader('content-type', 'application/json; charset=utf-8');
-      }
-      let body: string | Buffer;
-      if (ctx.serializer) {
-        body = ctx.serializer(payload);
-      } else if (useFastStringify) {
-        body = fastJsonStringify(payload);
-      } else if (jsonSerializer) {
-        body = jsonSerializer(payload);
-      } else {
-        body = JSON.stringify(payload);
-      }
-      res.end(body);
-    };
-
-    ctx.send = (payload: string | Buffer, status = 200) => {
-      const res = ctx.res;
-      if (!res.headersSent) {
-        res.statusCode = status;
-      }
-      res.end(payload);
-    };
-
-    ctx.html = (payload: string, status = 200) => {
-      const res = ctx.res;
-      if (!res.headersSent) {
-        res.statusCode = status;
-        res.setHeader('content-type', 'text/html; charset=utf-8');
-      }
-      res.end(payload);
-    };
-
-    ctx.redirect = (url: string, status = 302) => {
-      const res = ctx.res;
-      if (!res.headersSent) {
-        res.statusCode = status;
-        res.setHeader('Location', url);
-      }
-      res.end();
-    };
-
-    ctx.setCookie = (name: string, value: string, options: CookieOptions | undefined) => {
-      const res = ctx.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);
-      }
-    };
-
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    ctx.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 || {});
-      
-      const res = ctx.res;
-      if (!res.headersSent) {
-        res.statusCode = 200;
-        res.setHeader('content-type', 'text/html; charset=utf-8');
-      }
-      res.end(html);
-    };
-
-    ctx.validate = async <T>(schema: unknown, data?: unknown): Promise<T> => {
-      const target = data ?? ctx.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.headers = req.headers;
-    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;
-    mutableCtx.path = url.pathname;
-    
-    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.headers = 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;
-    mutableCtx.path = '';
-    mutableCtx.error = undefined;
-    // 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 handleError(err: unknown, ctx: QHTTPXContext): Promise<void> | void {
-    const res = ctx.res;
-    if (res.writableEnded) {
-      return;
-    }
-
-    if (this.errorHandler) {
-      try {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const errorContext = ctx as any;
-        errorContext.error = err;
-        const result = this.errorHandler(errorContext);
-        if (result && typeof (result as Promise<void>).then === 'function') {
-          return (result as Promise<void>).then(() => {
-             // Ensure response is sent if handler didn't
-          });
-        }
-        if (res.writableEnded) {
-          return;
-        }
-      } catch (handlerErr) {
-        // Fall through to default error handling below
-        console.error('Error in error handler:', handlerErr);
-      }
-    }
-
-    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)}`;
-  }
-}