qhttpx 1.9.2 → 1.9.3

package/dist/src/core/buffer-pool.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Buffer pool for response bodies (small, medium, large).
+ * Reuses allocated buffers to reduce GC pressure.
+ */
+export type BufferPoolConfig = {
+    smallSize?: number;
+    mediumSize?: number;
+    largeSize?: number;
+    smallPoolSize?: number;
+    mediumPoolSize?: number;
+    largePoolSize?: number;
+};
+export declare class BufferPool {
+    private readonly smallSize;
+    private readonly mediumSize;
+    private readonly largeSize;
+    private readonly smallBuffers;
+    private readonly mediumBuffers;
+    private readonly largeBuffers;
+    private readonly smallPoolSize;
+    private readonly mediumPoolSize;
+    private readonly largePoolSize;
+    constructor(config?: BufferPoolConfig);
+    /**
+     * Acquire a buffer suitable for the given size.
+     * Returns a buffer from the appropriate pool.
+     */
+    acquire(size: number): Buffer;
+    /**
+     * Release a buffer back to the appropriate pool.
+     */
+    release(buffer: Buffer): void;
+    /**
+     * Get the number of available buffers in each pool.
+     */
+    getPoolStatus(): {
+        small: number;
+        medium: number;
+        large: number;
+    };
+}

package/dist/src/core/buffer-pool.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Buffer pool for response bodies (small, medium, large).
+ * Reuses allocated buffers to reduce GC pressure.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BufferPool = void 0;
+class BufferPool {
+    constructor(config = {}) {
+        this.smallBuffers = [];
+        this.mediumBuffers = [];
+        this.largeBuffers = [];
+        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) {
+        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) {
+        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() {
+        return {
+            small: this.smallBuffers.length,
+            medium: this.mediumBuffers.length,
+            large: this.largeBuffers.length,
+        };
+    }
+}
+exports.BufferPool = BufferPool;

package/dist/src/core/config.d.ts

@@ -0,0 +1,7 @@
+import type { QHTTPXOptions } from './types';
+export type LoadConfigOptions = {
+    env?: NodeJS.ProcessEnv;
+    defaults?: QHTTPXOptions;
+    prefix?: string;
+};
+export declare function loadConfig(options?: LoadConfigOptions): QHTTPXOptions;

package/dist/src/core/config.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+function loadConfig(options = {}) {
+    const env = options.env ?? process.env;
+    const defaults = options.defaults ?? {};
+    const prefix = options.prefix ?? 'QHTTPX_';
+    const getNumber = (key) => {
+        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) => {
+        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/dist/src/core/errors.d.ts

@@ -0,0 +1,34 @@
+import { HttpError } from './types';
+export declare class BadRequestException extends HttpError {
+    constructor(message?: string, details?: unknown);
+}
+export declare class UnauthorizedException extends HttpError {
+    constructor(message?: string, details?: unknown);
+}
+export declare class ForbiddenException extends HttpError {
+    constructor(message?: string, details?: unknown);
+}
+export declare class NotFoundException extends HttpError {
+    constructor(message?: string, details?: unknown);
+}
+export declare class MethodNotAllowedException extends HttpError {
+    constructor(message?: string, details?: unknown);
+}
+export declare class ConflictException extends HttpError {
+    constructor(message?: string, details?: unknown);
+}
+export declare class PayloadTooLargeException extends HttpError {
+    constructor(message?: string, details?: unknown);
+}
+export declare class UnsupportedMediaTypeException extends HttpError {
+    constructor(message?: string, details?: unknown);
+}
+export declare class TooManyRequestsException extends HttpError {
+    constructor(message?: string, details?: unknown);
+}
+export declare class InternalServerErrorException extends HttpError {
+    constructor(message?: string, details?: unknown);
+}
+export declare class ServiceUnavailableException extends HttpError {
+    constructor(message?: string, details?: unknown);
+}

package/dist/src/core/errors.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceUnavailableException = exports.InternalServerErrorException = exports.TooManyRequestsException = exports.UnsupportedMediaTypeException = exports.PayloadTooLargeException = exports.ConflictException = exports.MethodNotAllowedException = exports.NotFoundException = exports.ForbiddenException = exports.UnauthorizedException = exports.BadRequestException = void 0;
+const types_1 = require("./types");
+class BadRequestException extends types_1.HttpError {
+    constructor(message = 'Bad Request', details) {
+        super(400, message, { code: 'BAD_REQUEST', details });
+    }
+}
+exports.BadRequestException = BadRequestException;
+class UnauthorizedException extends types_1.HttpError {
+    constructor(message = 'Unauthorized', details) {
+        super(401, message, { code: 'UNAUTHORIZED', details });
+    }
+}
+exports.UnauthorizedException = UnauthorizedException;
+class ForbiddenException extends types_1.HttpError {
+    constructor(message = 'Forbidden', details) {
+        super(403, message, { code: 'FORBIDDEN', details });
+    }
+}
+exports.ForbiddenException = ForbiddenException;
+class NotFoundException extends types_1.HttpError {
+    constructor(message = 'Not Found', details) {
+        super(404, message, { code: 'NOT_FOUND', details });
+    }
+}
+exports.NotFoundException = NotFoundException;
+class MethodNotAllowedException extends types_1.HttpError {
+    constructor(message = 'Method Not Allowed', details) {
+        super(405, message, { code: 'METHOD_NOT_ALLOWED', details });
+    }
+}
+exports.MethodNotAllowedException = MethodNotAllowedException;
+class ConflictException extends types_1.HttpError {
+    constructor(message = 'Conflict', details) {
+        super(409, message, { code: 'CONFLICT', details });
+    }
+}
+exports.ConflictException = ConflictException;
+class PayloadTooLargeException extends types_1.HttpError {
+    constructor(message = 'Payload Too Large', details) {
+        super(413, message, { code: 'PAYLOAD_TOO_LARGE', details });
+    }
+}
+exports.PayloadTooLargeException = PayloadTooLargeException;
+class UnsupportedMediaTypeException extends types_1.HttpError {
+    constructor(message = 'Unsupported Media Type', details) {
+        super(415, message, { code: 'UNSUPPORTED_MEDIA_TYPE', details });
+    }
+}
+exports.UnsupportedMediaTypeException = UnsupportedMediaTypeException;
+class TooManyRequestsException extends types_1.HttpError {
+    constructor(message = 'Too Many Requests', details) {
+        super(429, message, { code: 'TOO_MANY_REQUESTS', details });
+    }
+}
+exports.TooManyRequestsException = TooManyRequestsException;
+class InternalServerErrorException extends types_1.HttpError {
+    constructor(message = 'Internal Server Error', details) {
+        super(500, message, { code: 'INTERNAL_SERVER_ERROR', details });
+    }
+}
+exports.InternalServerErrorException = InternalServerErrorException;
+class ServiceUnavailableException extends types_1.HttpError {
+    constructor(message = 'Service Unavailable', details) {
+        super(503, message, { code: 'SERVICE_UNAVAILABLE', details });
+    }
+}
+exports.ServiceUnavailableException = ServiceUnavailableException;

package/dist/src/core/fusion.d.ts

@@ -0,0 +1,20 @@
+import type { QHTTPXContext } from './types';
+export interface RequestFusionOptions {
+    windowMs?: number;
+    vary?: string[];
+}
+export interface RequestFusionMetrics {
+    totalFused: number;
+    totalProcessed: number;
+}
+export declare class RequestFusion {
+    private inflight;
+    private cache;
+    private options;
+    private metrics;
+    constructor(options?: boolean | RequestFusionOptions);
+    getMetrics(): RequestFusionMetrics;
+    coalesce(ctx: QHTTPXContext, next: (ctx: QHTTPXContext) => Promise<void> | void): Promise<void>;
+    private applyResult;
+    private getKey;
+}

package/dist/src/core/fusion.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestFusion = void 0;
+const crypto_1 = require("crypto");
+class RequestFusion {
+    constructor(options = {}) {
+        this.inflight = new Map();
+        this.cache = new Map();
+        this.metrics = {
+            totalFused: 0,
+            totalProcessed: 0
+        };
+        this.options = typeof options === 'boolean' ? {} : options;
+        if (!this.options.vary) {
+            this.options.vary = ['authorization', 'cookie'];
+        }
+    }
+    getMetrics() {
+        return { ...this.metrics };
+    }
+    async coalesce(ctx, next) {
+        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.metrics.totalFused++;
+                    this.applyResult(ctx, cached.result);
+                    return;
+                }
+                else {
+                    this.cache.delete(key);
+                }
+            }
+        }
+        // 2. Check In-Flight
+        if (this.inflight.has(key)) {
+            try {
+                this.metrics.totalFused++;
+                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
+        this.metrics.totalProcessed++;
+        let resolve;
+        let reject;
+        const promise = new Promise((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;
+        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) => {
+            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, status = 200) => {
+            finish({ type: 'json', payload, status });
+            return originalJson.call(ctx, payload, status);
+        };
+        mutableCtx.send = (payload, status = 200) => {
+            finish({ type: 'send', payload, status });
+            return originalSend.call(ctx, payload, status);
+        };
+        mutableCtx.html = (payload, status = 200) => {
+            finish({ type: 'html', payload, status });
+            return originalHtml.call(ctx, payload, status);
+        };
+        mutableCtx.redirect = (url, 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;
+        }
+    }
+    applyResult(ctx, result) {
+        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, result.status);
+                }
+                else {
+                    ctx.send(String(result.payload), result.status);
+                }
+                break;
+            }
+            case 'html': {
+                if (typeof result.payload === 'string') {
+                    ctx.html(result.payload, result.status);
+                }
+                else {
+                    ctx.html(String(result.payload), result.status);
+                }
+                break;
+            }
+            case 'redirect': {
+                if (typeof result.payload === 'string') {
+                    ctx.redirect(result.payload, result.status);
+                }
+                else {
+                    ctx.redirect(String(result.payload), result.status);
+                }
+                break;
+            }
+        }
+    }
+    getKey(ctx) {
+        // 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 (0, crypto_1.createHash)('sha1').update(data).digest('hex');
+    }
+}
+exports.RequestFusion = RequestFusion;

package/dist/src/core/logger.d.ts

@@ -0,0 +1,22 @@
+import pino from 'pino';
+export type LogLevel = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
+export interface LoggerOptions {
+    level?: LogLevel;
+    pretty?: boolean;
+    name?: string;
+}
+export declare class Logger {
+    private pino;
+    constructor(options?: LoggerOptions);
+    info(msg: string, ...args: any[]): void;
+    info(obj: object, msg?: string, ...args: any[]): void;
+    error(msg: string, ...args: any[]): void;
+    error(obj: object, msg?: string, ...args: any[]): void;
+    warn(msg: string, ...args: any[]): void;
+    warn(obj: object, msg?: string, ...args: any[]): void;
+    debug(msg: string, ...args: any[]): void;
+    debug(obj: object, msg?: string, ...args: any[]): void;
+    fatal(msg: string, ...args: any[]): void;
+    fatal(obj: object, msg?: string, ...args: any[]): void;
+    child(bindings: pino.Bindings): Logger;
+}

package/dist/src/core/logger.js

@@ -0,0 +1,49 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const pino_1 = __importDefault(require("pino"));
+class Logger {
+    constructor(options = {}) {
+        const isDev = process.env.NODE_ENV !== 'production';
+        const pretty = options.pretty ?? isDev;
+        this.pino = (0, pino_1.default)({
+            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(arg1, ...args) {
+        this.pino.info(arg1, ...args);
+    }
+    error(arg1, ...args) {
+        this.pino.error(arg1, ...args);
+    }
+    warn(arg1, ...args) {
+        this.pino.warn(arg1, ...args);
+    }
+    debug(arg1, ...args) {
+        this.pino.debug(arg1, ...args);
+    }
+    fatal(arg1, ...args) {
+        this.pino.fatal(arg1, ...args);
+    }
+    child(bindings) {
+        const child = new Logger();
+        child.pino = this.pino.child(bindings);
+        return child;
+    }
+}
+exports.Logger = Logger;

package/dist/src/core/metrics.d.ts

@@ -0,0 +1,48 @@
+import type { TaskEngine, TaskMetrics } from './tasks';
+import { Scheduler } from './scheduler';
+import type { RequestFusion, RequestFusionMetrics } from './fusion';
+export type LatencySnapshot = {
+    p50: number | null;
+    p95: number | null;
+    p99: number | null;
+};
+export type MetricsSnapshot = {
+    totalRequests: number;
+    inFlightRequests: number;
+    totalErrors: number;
+    totalTimeouts: number;
+    requestsPerSecond: number;
+    latency: LatencySnapshot;
+    scheduler: {
+        inFlight: number;
+    };
+    tasks?: TaskMetrics;
+    fusion?: RequestFusionMetrics;
+    memory: {
+        rssBytes: number;
+        heapUsedBytes: number;
+    };
+};
+export declare class Metrics {
+    private readonly scheduler;
+    private readonly taskEngine?;
+    private readonly fusion?;
+    private readonly latencies;
+    private readonly maxLatencies;
+    private readonly enabled;
+    private totalRequests;
+    private inFlightRequests;
+    private totalErrors;
+    private totalTimeouts;
+    constructor(scheduler: Scheduler, options?: {
+        maxLatencies?: number;
+        enabled?: boolean;
+    }, taskEngine?: TaskEngine, fusion?: RequestFusion);
+    onRequestStart(): void;
+    onRequestEnd(durationMs: number, statusCode: number): void;
+    onTimeout(): void;
+    snapshot(): MetricsSnapshot;
+    private recordLatency;
+    private latencySnapshot;
+    private percentile;
+}