qhttpx 1.8.0

package/src/core/body-parser.ts

@@ -0,0 +1,151 @@
+import { IncomingMessage } from 'http';
+import { parse as parseQueryString } from 'querystring';
+import busboy from 'busboy';
+
+export type BodyParserOptions = {
+  maxBodyBytes?: number;
+};
+
+export type ParsedBody = {
+  body: unknown;
+  files?: Record<string, unknown>;
+};
+
+export interface IBodyParser {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  parse(req: IncomingMessage, options?: BodyParserOptions): Promise<any>;
+}
+
+export class BodyParser {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  static async parse(req: IncomingMessage, options: BodyParserOptions = {}): Promise<any> {
+    const method = (req.method || 'GET').toUpperCase();
+    if (method === 'GET' || method === 'HEAD') {
+      return { body: undefined };
+    }
+
+    const contentType = req.headers['content-type'] || '';
+
+    if (contentType.includes('multipart/form-data')) {
+      return this.parseMultipart(req, options);
+    }
+
+    const chunks: Buffer[] = [];
+    let totalBytes = 0;
+    const maxBodyBytes = options.maxBodyBytes;
+
+    for await (const chunk of req) {
+      const bufferChunk =
+        typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+      chunks.push(bufferChunk);
+      totalBytes += bufferChunk.length;
+      if (maxBodyBytes !== undefined && totalBytes > maxBodyBytes) {
+        throw new Error('QHTTPX_BODY_TOO_LARGE');
+      }
+    }
+
+    if (chunks.length === 0) {
+      return { body: undefined };
+    }
+
+    const buffer = Buffer.concat(chunks);
+
+    if (
+      typeof contentType === 'string' &&
+      contentType.includes('application/json')
+    ) {
+      const text = buffer.toString('utf8');
+      try {
+        return { body: JSON.parse(text) };
+      } catch {
+        throw new Error('QHTTPX_INVALID_JSON');
+      }
+    }
+
+    if (
+      typeof contentType === 'string' &&
+      contentType.includes('application/x-www-form-urlencoded')
+    ) {
+      const text = buffer.toString('utf8');
+      return { body: parseQueryString(text) };
+    }
+
+    return { body: buffer };
+  }
+
+  private static parseMultipart(
+    req: IncomingMessage,
+    options: BodyParserOptions,
+  ): Promise<ParsedBody> {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return new Promise<any>((resolve, reject) => {
+      let bb;
+      try {
+        bb = busboy({ headers: req.headers, limits: { fileSize: options.maxBodyBytes } });
+      } catch (err) {
+        return reject(err);
+      }
+
+      const body: Record<string, unknown> = {};
+      const files: Record<string, unknown> = {};
+
+      bb.on('field', (name, val) => {
+        if (Object.prototype.hasOwnProperty.call(body, name)) {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          if (Array.isArray((body as any)[name])) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (body as any)[name].push(val);
+          } else {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (body as any)[name] = [(body as any)[name], val];
+          }
+        } else {
+          body[name] = val;
+        }
+      });
+
+      bb.on('file', (name, file, info) => {
+        const { filename, encoding, mimeType } = info;
+        const chunks: Buffer[] = [];
+
+        file.on('data', (chunk) => {
+          chunks.push(chunk);
+        });
+
+        file.on('end', () => {
+          const buffer = Buffer.concat(chunks);
+          const fileData = {
+            filename,
+            encoding,
+            mimeType,
+            data: buffer,
+            size: buffer.length,
+          };
+
+          if (Object.prototype.hasOwnProperty.call(files, name)) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            if (Array.isArray((files as any)[name])) {
+              // eslint-disable-next-line @typescript-eslint/no-explicit-any
+              (files as any)[name].push(fileData);
+            } else {
+              // eslint-disable-next-line @typescript-eslint/no-explicit-any
+              (files as any)[name] = [(files as any)[name], fileData];
+            }
+          } else {
+            files[name] = fileData;
+          }
+        });
+      });
+
+      bb.on('close', () => {
+        resolve({ body, files });
+      });
+
+      bb.on('error', (err) => {
+        reject(err);
+      });
+
+      req.pipe(bb);
+    });
+  }
+}

package/src/core/buffer-pool.ts

@@ -0,0 +1,96 @@
+/**
+ * Buffer pool for response bodies (small, medium, large).
+ * Reuses allocated buffers to reduce GC pressure.
+ */
+
+export type BufferPoolConfig = {
+  smallSize?: number; // Default: 4KB
+  mediumSize?: number; // Default: 64KB
+  largeSize?: number; // Default: 256KB
+  smallPoolSize?: number; // Number of small buffers to maintain
+  mediumPoolSize?: number; // Number of medium buffers to maintain
+  largePoolSize?: number; // Number of large buffers to maintain
+};
+
+export class BufferPool {
+  private readonly smallSize: number;
+  private readonly mediumSize: number;
+  private readonly largeSize: number;
+
+  private readonly smallBuffers: Buffer[] = [];
+  private readonly mediumBuffers: Buffer[] = [];
+  private readonly largeBuffers: Buffer[] = [];
+
+  private readonly smallPoolSize: number;
+  private readonly mediumPoolSize: number;
+  private readonly largePoolSize: number;
+
+  constructor(config: BufferPoolConfig = {}) {
+    this.smallSize = config.smallSize ?? 4096; // 4KB
+    this.mediumSize = config.mediumSize ?? 65536; // 64KB
+    this.largeSize = config.largeSize ?? 262144; // 256KB
+
+    this.smallPoolSize = config.smallPoolSize ?? 32;
+    this.mediumPoolSize = config.mediumPoolSize ?? 8;
+    this.largePoolSize = config.largePoolSize ?? 2;
+
+    // Preallocate buffers
+    for (let i = 0; i < this.smallPoolSize; i += 1) {
+      this.smallBuffers.push(Buffer.allocUnsafe(this.smallSize));
+    }
+    for (let i = 0; i < this.mediumPoolSize; i += 1) {
+      this.mediumBuffers.push(Buffer.allocUnsafe(this.mediumSize));
+    }
+    for (let i = 0; i < this.largePoolSize; i += 1) {
+      this.largeBuffers.push(Buffer.allocUnsafe(this.largeSize));
+    }
+  }
+
+  /**
+   * Acquire a buffer suitable for the given size.
+   * Returns a buffer from the appropriate pool.
+   */
+  acquire(size: number): Buffer {
+    if (size <= this.smallSize) {
+      return this.smallBuffers.pop() || Buffer.allocUnsafe(this.smallSize);
+    }
+    if (size <= this.mediumSize) {
+      return this.mediumBuffers.pop() || Buffer.allocUnsafe(this.mediumSize);
+    }
+    return this.largeBuffers.pop() || Buffer.allocUnsafe(this.largeSize);
+  }
+
+  /**
+   * Release a buffer back to the appropriate pool.
+   */
+  release(buffer: Buffer): void {
+    if (buffer.length === this.smallSize && this.smallBuffers.length < this.smallPoolSize) {
+      this.smallBuffers.push(buffer);
+    } else if (
+      buffer.length === this.mediumSize &&
+      this.mediumBuffers.length < this.mediumPoolSize
+    ) {
+      this.mediumBuffers.push(buffer);
+    } else if (
+      buffer.length === this.largeSize &&
+      this.largeBuffers.length < this.largePoolSize
+    ) {
+      this.largeBuffers.push(buffer);
+    }
+  }
+
+  /**
+   * Get the number of available buffers in each pool.
+   */
+  getPoolStatus(): {
+    small: number;
+    medium: number;
+    large: number;
+  } {
+    return {
+      small: this.smallBuffers.length,
+      medium: this.mediumBuffers.length,
+      large: this.largeBuffers.length,
+    };
+  }
+}

package/src/core/config.ts

@@ -0,0 +1,60 @@
+import type { QHTTPXOptions } from './types';
+
+export type LoadConfigOptions = {
+  env?: NodeJS.ProcessEnv;
+  defaults?: QHTTPXOptions;
+  prefix?: string;
+};
+
+export function loadConfig(options: LoadConfigOptions = {}): QHTTPXOptions {
+  const env = options.env ?? process.env;
+  const defaults = options.defaults ?? {};
+  const prefix = options.prefix ?? 'QHTTPX_';
+
+  const getNumber = (key: string): number | undefined => {
+    const value = env[prefix + key];
+    if (!value) {
+      return undefined;
+    }
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0) {
+      return undefined;
+    }
+    return n;
+  };
+
+  const getBoolean = (key: string): boolean | undefined => {
+    const value = env[prefix + key];
+    if (!value) {
+      return undefined;
+    }
+    const lower = value.toLowerCase();
+    if (lower === 'true' || lower === '1') {
+      return true;
+    }
+    if (lower === 'false' || lower === '0') {
+      return false;
+    }
+    return undefined;
+  };
+
+  const maxConcurrency = getNumber('MAX_CONCURRENCY');
+  const requestTimeoutMs = getNumber('REQUEST_TIMEOUT_MS');
+  const maxMemoryBytes = getNumber('MAX_MEMORY_BYTES');
+  const maxBodyBytes = getNumber('MAX_BODY_BYTES');
+  const keepAliveTimeoutMs = getNumber('KEEP_ALIVE_TIMEOUT_MS');
+  const headersTimeoutMs = getNumber('HEADERS_TIMEOUT_MS');
+  const metricsEnabled = getBoolean('METRICS_ENABLED');
+
+  return {
+    ...defaults,
+    maxConcurrency: maxConcurrency ?? defaults.maxConcurrency,
+    requestTimeoutMs: requestTimeoutMs ?? defaults.requestTimeoutMs,
+    maxMemoryBytes: maxMemoryBytes ?? defaults.maxMemoryBytes,
+    maxBodyBytes: maxBodyBytes ?? defaults.maxBodyBytes,
+    keepAliveTimeoutMs: keepAliveTimeoutMs ?? defaults.keepAliveTimeoutMs,
+    headersTimeoutMs: headersTimeoutMs ?? defaults.headersTimeoutMs,
+    metricsEnabled: metricsEnabled ?? defaults.metricsEnabled,
+  };
+}
+

package/src/core/fusion.ts

@@ -0,0 +1,210 @@
+import type { QHTTPXContext } from './types';
+import { createHash } from 'crypto';
+
+export interface RequestFusionOptions {
+  windowMs?: number;
+  vary?: string[];
+}
+
+interface FusionResult {
+  type: 'json' | 'send' | 'html' | 'redirect';
+  payload: unknown;
+  status: number;
+  contentType?: string;
+}
+
+export class RequestFusion {
+  private inflight: Map<string, Promise<FusionResult>> = new Map();
+  private cache: Map<string, { result: FusionResult; expires: number }> = new Map();
+  private options: RequestFusionOptions;
+
+  constructor(options: boolean | RequestFusionOptions = {}) {
+    this.options = typeof options === 'boolean' ? {} : options;
+    if (!this.options.vary) {
+      this.options.vary = ['authorization', 'cookie'];
+    }
+  }
+
+  public async coalesce(ctx: QHTTPXContext, next: (ctx: QHTTPXContext) => Promise<void> | void): Promise<void> {
+    const key = this.getKey(ctx);
+
+    // 1. Check Cache (Short-lived "Micro-TTL")
+    if (this.options.windowMs && this.options.windowMs > 0) {
+      const cached = this.cache.get(key);
+      if (cached) {
+        if (Date.now() < cached.expires) {
+          this.applyResult(ctx, cached.result);
+          return;
+        } else {
+          this.cache.delete(key);
+        }
+      }
+    }
+
+    // 2. Check In-Flight
+    if (this.inflight.has(key)) {
+      try {
+        const result = await this.inflight.get(key)!;
+        this.applyResult(ctx, result);
+        return;
+      } catch (err) {
+        // If leader failed, we should probably fail too or retry?
+        // For now, let's propagate the error.
+        throw err;
+      }
+    }
+
+    // 3. Be the Leader
+    let resolve: (value: FusionResult) => void;
+    let reject: (reason?: unknown) => void;
+    const promise = new Promise<FusionResult>((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+
+    this.inflight.set(key, promise);
+
+    // Hijack context methods to capture result
+    // Cast to any to allow overwriting readonly methods
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const mutableCtx = ctx as any;
+    
+    const originalJson = mutableCtx.json;
+    const originalSend = mutableCtx.send;
+    const originalHtml = mutableCtx.html;
+    const originalRedirect = mutableCtx.redirect;
+
+    let captured = false;
+
+    // Helper to cleanup and resolve
+    const finish = (result: FusionResult) => {
+      if (captured) return;
+      captured = true;
+      resolve(result);
+
+      // Cache if needed
+      if (this.options.windowMs && this.options.windowMs > 0) {
+        this.cache.set(key, {
+          result,
+          expires: Date.now() + this.options.windowMs
+        });
+        // Cleanup cache later
+        setTimeout(() => this.cache.delete(key), this.options.windowMs);
+      }
+
+      // Remove from inflight immediately (unless we rely on cache for window)
+      // Actually, if we have windowMs, we rely on cache.
+      // If windowMs=0, we remove immediately.
+      this.inflight.delete(key);
+    };
+
+    mutableCtx.json = (payload: unknown, status = 200) => {
+      finish({ type: 'json', payload, status });
+      return originalJson.call(ctx, payload, status);
+    };
+
+    mutableCtx.send = (payload: string | Buffer, status = 200) => {
+      finish({ type: 'send', payload, status });
+      return originalSend.call(ctx, payload, status);
+    };
+
+    mutableCtx.html = (payload: string, status = 200) => {
+      finish({ type: 'html', payload, status });
+      return originalHtml.call(ctx, payload, status);
+    };
+
+    mutableCtx.redirect = (url: string, status = 302) => {
+      finish({ type: 'redirect', payload: url, status });
+      return originalRedirect.call(ctx, url, status);
+    };
+
+    try {
+      await next(ctx);
+      // If next() completes but no response method was called, 
+      // it implies the handler might be async and forgot to await, 
+      // or it's a 404/middleware issue.
+      // If not captured yet, we can't resolve the followers properly.
+      // They will hang unless we reject or resolve with something.
+      // However, typical QHTTPX usage implies ctx.json/send is called.
+    } catch (err) {
+      reject!(err);
+      this.inflight.delete(key);
+      // Restore methods
+      mutableCtx.json = originalJson;
+      mutableCtx.send = originalSend;
+      mutableCtx.html = originalHtml;
+      mutableCtx.redirect = originalRedirect;
+      throw err;
+    }
+  }
+
+  private applyResult(ctx: QHTTPXContext, result: FusionResult) {
+    switch (result.type) {
+      case 'json':
+        ctx.json(result.payload, result.status);
+        break;
+      case 'send': {
+        if (typeof result.payload === 'string' || Buffer.isBuffer(result.payload)) {
+          ctx.send(result.payload as string | Buffer, result.status);
+        } else {
+          ctx.send(String(result.payload), result.status);
+        }
+        break;
+      }
+      case 'html': {
+        if (typeof result.payload === 'string') {
+          ctx.html(result.payload as string, result.status);
+        } else {
+          ctx.html(String(result.payload), result.status);
+        }
+        break;
+      }
+      case 'redirect': {
+        if (typeof result.payload === 'string') {
+          ctx.redirect(result.payload as string, result.status);
+        } else {
+          ctx.redirect(String(result.payload), result.status);
+        }
+        break;
+      }
+    }
+  }
+
+  private getKey(ctx: QHTTPXContext): string {
+    // Base: Method + Path
+    let data = `${ctx.req.method}|${ctx.url?.pathname}|`;
+
+    // Query
+    if (ctx.query) {
+      // Deterministic sort
+      const keys = Object.keys(ctx.query).sort();
+      for (const k of keys) {
+        data += `${k}=${ctx.query[k]}|`;
+      }
+    }
+
+    // Body (if parsed)
+    if (ctx.body) {
+      // We assume body is simple JSON.
+      // For objects, order matters for hashing.
+      // fast-json-stringify or JSON.stringify isn't always deterministic key order.
+      // But for performance, JSON.stringify is often "good enough" if keys aren't shuffled.
+      // For strict correctness, we should use a canonical stringify, but that's slow.
+      // Let's use JSON.stringify for now.
+      data += JSON.stringify(ctx.body);
+    }
+
+    // Vary Headers
+    if (this.options.vary) {
+      for (const header of this.options.vary) {
+        const val = ctx.req.headers[header.toLowerCase()];
+        if (val) {
+          data += `|${header}:${val}`;
+        }
+      }
+    }
+
+    // We hash it to keep the key size manageable
+    return createHash('sha1').update(data).digest('hex');
+  }
+}

package/src/core/logger.ts

@@ -0,0 +1,70 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import pino from 'pino';
+
+export type LogLevel = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
+
+export interface LoggerOptions {
+  level?: LogLevel;
+  pretty?: boolean;
+  name?: string;
+}
+
+export class Logger {
+  private pino: pino.Logger;
+
+  constructor(options: LoggerOptions = {}) {
+    const isDev = process.env.NODE_ENV !== 'production';
+    const pretty = options.pretty ?? isDev;
+
+    this.pino = pino({
+      name: options.name || 'qhttpx',
+      level: options.level || 'info',
+      transport: pretty
+        ? {
+            target: 'pino-pretty',
+            options: {
+              colorize: true,
+              translateTime: 'HH:MM:ss Z',
+              ignore: 'pid,hostname',
+            },
+          }
+        : undefined,
+    });
+  }
+
+  info(msg: string, ...args: any[]): void;
+  info(obj: object, msg?: string, ...args: any[]): void;
+  info(arg1: string | object, ...args: any[]): void {
+    this.pino.info(arg1 as any, ...args);
+  }
+
+  error(msg: string, ...args: any[]): void;
+  error(obj: object, msg?: string, ...args: any[]): void;
+  error(arg1: string | object, ...args: any[]): void {
+    this.pino.error(arg1 as any, ...args);
+  }
+
+  warn(msg: string, ...args: any[]): void;
+  warn(obj: object, msg?: string, ...args: any[]): void;
+  warn(arg1: string | object, ...args: any[]): void {
+    this.pino.warn(arg1 as any, ...args);
+  }
+
+  debug(msg: string, ...args: any[]): void;
+  debug(obj: object, msg?: string, ...args: any[]): void;
+  debug(arg1: string | object, ...args: any[]): void {
+    this.pino.debug(arg1 as any, ...args);
+  }
+
+  fatal(msg: string, ...args: any[]): void;
+  fatal(obj: object, msg?: string, ...args: any[]): void;
+  fatal(arg1: string | object, ...args: any[]): void {
+    this.pino.fatal(arg1 as any, ...args);
+  }
+
+  child(bindings: pino.Bindings): Logger {
+    const child = new Logger();
+    child.pino = this.pino.child(bindings);
+    return child;
+  }
+}