qhttpx 1.8.0

package/dist/src/core/batch.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BatchExecutor = void 0;
+const coalescer_1 = require("../database/coalescer");
+class BatchExecutor {
+    constructor(dbManager) {
+        this.ops = new Map();
+        this.coalescers = new Map();
+        this.dbManager = dbManager;
+    }
+    register(name, handler) {
+        this.ops.set(name, handler);
+    }
+    async handleBatch(ctx, batch) {
+        if (!Array.isArray(batch)) {
+            throw new Error('Batch must be an array');
+        }
+        // If we have a DB manager, we want to intercept queries for fusion
+        // We create a proxy for the DB manager attached to the context
+        let batchCtx = ctx;
+        if (this.dbManager && ctx.db) {
+            // Create a localized context that intercepts DB calls
+            // We need to ensure that when `ctx.db.get()` is called, it returns a wrapped adapter
+            // But `ctx.db` is the manager itself.
+            // We can't easily wrap the manager instance shared across requests.
+            // Instead, we can wrap the `ctx.db` property for this request scope.
+            const originalDb = ctx.db;
+            // Create a proxy for the database manager
+            const dbProxy = new Proxy(originalDb, {
+                get: (target, prop, receiver) => {
+                    if (prop === 'get' || prop === 'connect') {
+                        return (name) => {
+                            const adapter = target.get(name);
+                            // Check if we have a coalescer for this connection
+                            const connName = name || 'default'; // Simplify for now
+                            let coalescer = this.coalescers.get(connName);
+                            // In a real per-request batch scope, we should create a new Coalescer 
+                            // OR reset the existing one?
+                            // Actually, the Coalescer uses a short timeout (next tick). 
+                            // So it is safe to share across concurrent requests IF we want global batching.
+                            // BUT "auto transaction scope" implies per-request isolation.
+                            // For "Query Fusion", global batching is even better (cross-request fusion).
+                            // However, for this task, let's stick to per-request or global safely.
+                            // Since Coalescer flushes on next tick, sharing it is fine and efficient.
+                            if (!coalescer) {
+                                coalescer = new coalescer_1.QueryCoalescer(adapter);
+                                this.coalescers.set(connName, coalescer);
+                            }
+                            // Return a proxy to the adapter that uses the coalescer
+                            return {
+                                ...adapter,
+                                query: (query, params) => coalescer.query(query, params),
+                                isConnected: () => adapter.isConnected(),
+                                connect: () => adapter.connect(),
+                                disconnect: () => adapter.disconnect()
+                            };
+                        };
+                    }
+                    return Reflect.get(target, prop, receiver);
+                }
+            });
+            // Create a new context object that inherits from original but overrides db
+            // We use Object.create to prototype inherit, but ctx is a flat object in QHTTPX.
+            // We must shallow copy.
+            batchCtx = { ...ctx, db: dbProxy };
+        }
+        // Helper for internal calls
+        // "ctx.call" implementation
+        // The user wants: `ctx.call("getUser", { id: 5 })`
+        // We attach this to the context
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        batchCtx.call = async (op, params) => {
+            const handler = this.ops.get(op);
+            if (!handler) {
+                throw new Error(`Unknown operation: ${op}`);
+            }
+            return handler(params, batchCtx);
+        };
+        // Execute all ops
+        // We can run them in parallel since we want to fuse queries
+        const results = await Promise.all(batch.map(async (item) => {
+            try {
+                const handler = this.ops.get(item.op);
+                if (!handler) {
+                    return { error: `Unknown operation: ${item.op}`, id: item.id };
+                }
+                const result = await handler(item.params, batchCtx);
+                return { result, id: item.id };
+            }
+            catch (err) {
+                return { error: (err instanceof Error ? err.message : String(err)), id: item.id };
+            }
+        }));
+        return { results };
+    }
+}
+exports.BatchExecutor = BatchExecutor;

package/dist/src/core/body-parser.js

@@ -0,0 +1,121 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BodyParser = void 0;
+const querystring_1 = require("querystring");
+const busboy_1 = __importDefault(require("busboy"));
+class BodyParser {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static async parse(req, options = {}) {
+        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 = [];
+        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: (0, querystring_1.parse)(text) };
+        }
+        return { body: buffer };
+    }
+    static parseMultipart(req, options) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return new Promise((resolve, reject) => {
+            let bb;
+            try {
+                bb = (0, busboy_1.default)({ headers: req.headers, limits: { fileSize: options.maxBodyBytes } });
+            }
+            catch (err) {
+                return reject(err);
+            }
+            const body = {};
+            const files = {};
+            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[name])) {
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        body[name].push(val);
+                    }
+                    else {
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        body[name] = [body[name], val];
+                    }
+                }
+                else {
+                    body[name] = val;
+                }
+            });
+            bb.on('file', (name, file, info) => {
+                const { filename, encoding, mimeType } = info;
+                const chunks = [];
+                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[name])) {
+                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                            files[name].push(fileData);
+                        }
+                        else {
+                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                            files[name] = [files[name], fileData];
+                        }
+                    }
+                    else {
+                        files[name] = fileData;
+                    }
+                });
+            });
+            bb.on('close', () => {
+                resolve({ body, files });
+            });
+            bb.on('error', (err) => {
+                reject(err);
+            });
+            req.pipe(bb);
+        });
+    }
+}
+exports.BodyParser = BodyParser;

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.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/fusion.js

@@ -0,0 +1,183 @@
+"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.options = typeof options === 'boolean' ? {} : options;
+        if (!this.options.vary) {
+            this.options.vary = ['authorization', 'cookie'];
+        }
+    }
+    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.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;
+        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.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.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Metrics = void 0;
+class Metrics {
+    constructor(scheduler, options = {}, taskEngine) {
+        this.latencies = [];
+        this.totalRequests = 0;
+        this.inFlightRequests = 0;
+        this.totalErrors = 0;
+        this.totalTimeouts = 0;
+        this.scheduler = scheduler;
+        this.taskEngine = taskEngine;
+        this.maxLatencies = options.maxLatencies ?? 1000;
+        this.enabled = options.enabled ?? true;
+    }
+    onRequestStart() {
+        if (!this.enabled) {
+            return;
+        }
+        this.inFlightRequests += 1;
+    }
+    onRequestEnd(durationMs, statusCode) {
+        if (!this.enabled) {
+            return;
+        }
+        this.totalRequests += 1;
+        if (this.inFlightRequests > 0) {
+            this.inFlightRequests -= 1;
+        }
+        if (statusCode >= 500) {
+            this.totalErrors += 1;
+        }
+        this.recordLatency(durationMs);
+    }
+    onTimeout() {
+        if (!this.enabled) {
+            return;
+        }
+        this.totalTimeouts += 1;
+    }
+    snapshot() {
+        const uptime = process.uptime();
+        const requestsPerSecond = uptime > 0 ? this.totalRequests / uptime : this.totalRequests;
+        const latency = this.latencySnapshot();
+        const memoryUsage = process.memoryUsage();
+        let tasks;
+        if (this.taskEngine) {
+            tasks = this.taskEngine.getMetrics();
+        }
+        return {
+            totalRequests: this.totalRequests,
+            inFlightRequests: this.inFlightRequests,
+            totalErrors: this.totalErrors,
+            totalTimeouts: this.totalTimeouts,
+            requestsPerSecond,
+            latency,
+            scheduler: {
+                inFlight: this.scheduler.getCurrentInFlight(),
+            },
+            tasks,
+            memory: {
+                rssBytes: memoryUsage.rss,
+                heapUsedBytes: memoryUsage.heapUsed,
+            },
+        };
+    }
+    recordLatency(durationMs) {
+        if (!this.enabled) {
+            return;
+        }
+        if (!Number.isFinite(durationMs) || durationMs < 0) {
+            return;
+        }
+        this.latencies.push(durationMs);
+        if (this.latencies.length > this.maxLatencies) {
+            this.latencies.shift();
+        }
+    }
+    latencySnapshot() {
+        if (this.latencies.length === 0) {
+            return {
+                p50: null,
+                p95: null,
+                p99: null,
+            };
+        }
+        const sorted = [...this.latencies].sort((a, b) => a - b);
+        const p50 = this.percentile(sorted, 0.5);
+        const p95 = this.percentile(sorted, 0.95);
+        const p99 = this.percentile(sorted, 0.99);
+        return {
+            p50,
+            p95,
+            p99,
+        };
+    }
+    percentile(sorted, p) {
+        if (sorted.length === 0) {
+            return 0;
+        }
+        if (p <= 0) {
+            return sorted[0];
+        }
+        if (p >= 1) {
+            return sorted[sorted.length - 1];
+        }
+        const index = Math.floor(p * (sorted.length - 1));
+        return sorted[index];
+    }
+}
+exports.Metrics = Metrics;