qhttpx 1.9.2 → 1.9.4

package/dist/src/server.js

@@ -0,0 +1,685 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QHTTPX = void 0;
+const http_1 = __importDefault(require("http"));
+const url_1 = require("url");
+const package_json_1 = __importDefault(require("../package.json"));
+const router_1 = require("./router");
+const scheduler_1 = require("./scheduler");
+const tasks_1 = require("./tasks");
+const resources_1 = require("./resources");
+const metrics_1 = require("./metrics");
+const buffer_pool_1 = require("./buffer-pool");
+const types_1 = require("./types");
+const cookies_1 = require("./cookies");
+class QHTTPX {
+    constructor(options = {}) {
+        this.middlewares = [];
+        this.contextPool = [];
+        this.pipelineRunner = null;
+        this.onStartHooks = [];
+        this.onBeforeShutdownHooks = [];
+        this.onShutdownHooks = [];
+        this.nextRequestId = 1;
+        this.upgradeHandlers = [];
+        this.options = options;
+        this.errorHandler = options.errorHandler;
+        this.notFoundHandler = options.notFoundHandler;
+        this.methodNotAllowedHandler = options.methodNotAllowedHandler;
+        this.tracer = options.tracer;
+        this.workerCount = (0, resources_1.calculateWorkerCount)(options.workers ?? 'auto');
+        this.router = new router_1.Router();
+        this.bufferPool = new buffer_pool_1.BufferPool(options.bufferPoolConfig);
+        const maxConcurrency = options.maxConcurrency ?? 1024;
+        this.scheduler = new scheduler_1.Scheduler({
+            maxConcurrency,
+        });
+        this.tasks = new tasks_1.TaskEngine(this.scheduler);
+        this.metrics = new metrics_1.Metrics(this.scheduler, {
+            enabled: 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_1.default.createServer(this.handleRequest.bind(this));
+        if (this.options.keepAliveTimeoutMs !== undefined) {
+            this.server.keepAliveTimeout = this.options.keepAliveTimeoutMs;
+        }
+        if (this.options.headersTimeoutMs !== undefined) {
+            this.server.headersTimeout = this.options.headersTimeoutMs;
+        }
+        this.server.on('upgrade', (req, socket, head) => {
+            void this.handleUpgrade(req, socket, head);
+        });
+    }
+    setErrorHandler(handler) {
+        this.errorHandler = handler;
+    }
+    setNotFoundHandler(handler) {
+        this.notFoundHandler = handler;
+    }
+    setMethodNotAllowedHandler(handler) {
+        this.methodNotAllowedHandler = handler;
+    }
+    set404Handler(handler) {
+        this.setNotFoundHandler(handler);
+    }
+    set405Handler(handler) {
+        this.setMethodNotAllowedHandler(handler);
+    }
+    onStart(hook) {
+        this.onStartHooks.push(hook);
+    }
+    onBeforeShutdown(hook) {
+        this.onBeforeShutdownHooks.push(hook);
+    }
+    onShutdown(hook) {
+        this.onShutdownHooks.push(hook);
+    }
+    upgrade(path, handler) {
+        this.upgradeHandlers.push({ path, handler });
+    }
+    use(middleware) {
+        this.middlewares.push(middleware);
+        // Recompile pipeline after middleware is added
+        this.compileMiddlewarePipeline();
+    }
+    compileMiddlewarePipeline() {
+        const middlewares = this.middlewares;
+        if (middlewares.length === 0) {
+            this.pipelineRunner = async (ctx, handler) => {
+                const result = handler(ctx);
+                if (result && typeof result.then === 'function') {
+                    await result;
+                }
+            };
+            return;
+        }
+        // Precompile a closure that captures the middleware chain
+        this.pipelineRunner = async (ctx, handler) => {
+            let index = -1;
+            const dispatch = async () => {
+                index += 1;
+                if (index < middlewares.length) {
+                    await middlewares[index](ctx, dispatch);
+                    return;
+                }
+                const result = handler(ctx);
+                if (result && typeof result.then === 'function') {
+                    await result;
+                }
+            };
+            await dispatch();
+        };
+    }
+    get(path, handler) {
+        this.router.register('GET', path, handler);
+    }
+    post(path, handler) {
+        this.router.register('POST', path, handler);
+    }
+    put(path, handler) {
+        this.router.register('PUT', path, handler);
+    }
+    delete(path, handler) {
+        this.router.register('DELETE', path, handler);
+    }
+    route(path) {
+        const register = (method, handler) => {
+            this.router.register(method, path, handler);
+        };
+        const builder = {
+            get(handler) {
+                register('GET', handler);
+                return this;
+            },
+            post(handler) {
+                register('POST', handler);
+                return this;
+            },
+            put(handler) {
+                register('PUT', handler);
+                return this;
+            },
+            delete(handler) {
+                register('DELETE', handler);
+                return this;
+            },
+        };
+        return builder;
+    }
+    task(name, handler, options) {
+        this.tasks.register(name, handler, options);
+    }
+    enqueue(name, payload) {
+        return this.tasks.enqueue(name, payload);
+    }
+    registerInternalRoutes() {
+        this.router.register('GET', '/__qhttpx/health', (ctx) => {
+            const version = typeof package_json_1.default.version === 'string' ? package_json_1.default.version : '';
+            const name = typeof package_json_1.default.name === 'string' ? package_json_1.default.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,
+            });
+        });
+    }
+    listen(port, hostname) {
+        return new Promise((resolve, reject) => {
+            const onError = (error) => {
+                this.server.off('error', onError);
+                reject(error);
+            };
+            this.server.once('error', onError);
+            this.server.listen(port, hostname, () => {
+                this.server.off('error', onError);
+                // Freeze router after server starts to prevent further registrations
+                this.router.freeze();
+                void this.runLifecycleHooks(this.onStartHooks);
+                const address = this.server.address();
+                if (address && typeof address === 'object') {
+                    resolve({ port: address.port });
+                }
+                else {
+                    resolve({ port });
+                }
+            });
+        });
+    }
+    close() {
+        return new Promise((resolve, reject) => {
+            this.server.close((err) => {
+                if (err) {
+                    reject(err);
+                    return;
+                }
+                resolve();
+            });
+        });
+    }
+    async shutdown() {
+        await this.runLifecycleHooks(this.onBeforeShutdownHooks);
+        await this.close();
+        await this.runLifecycleHooks(this.onShutdownHooks);
+    }
+    createContext() {
+        const jsonSerializer = this.options.jsonSerializer;
+        const ctx = {
+            req: {},
+            res: {},
+            url: {},
+            params: {},
+            query: {},
+            body: undefined,
+            cookies: {},
+            state: {},
+            bufferPool: this.bufferPool,
+            json(payload, status = 200) {
+                const res = this.res;
+                if (!res.headersSent) {
+                    res.statusCode = status;
+                    res.setHeader('content-type', 'application/json; charset=utf-8');
+                }
+                const serializer = jsonSerializer;
+                const body = serializer !== undefined ? serializer(payload) : JSON.stringify(payload);
+                res.end(body);
+            },
+            send(payload, status = 200) {
+                const res = this.res;
+                if (!res.headersSent) {
+                    res.statusCode = status;
+                }
+                res.end(payload);
+            },
+            html(payload, status = 200) {
+                const res = this.res;
+                if (!res.headersSent) {
+                    res.statusCode = status;
+                    res.setHeader('content-type', 'text/html; charset=utf-8');
+                }
+                res.end(payload);
+            },
+            redirect(url, status = 302) {
+                const res = this.res;
+                if (!res.headersSent) {
+                    res.statusCode = status;
+                    res.setHeader('Location', url);
+                }
+                res.end();
+            },
+            setCookie(name, value, options) {
+                const res = this.res;
+                const serialized = (0, cookies_1.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, serialized]);
+                }
+                else {
+                    res.setHeader('Set-Cookie', serialized);
+                }
+            },
+        };
+        return ctx;
+    }
+    acquireContext(req, res, url, params, query, requestId, body) {
+        const ctx = this.contextPool.pop() ?? this.createContext();
+        ctx.req = req;
+        ctx.res = res;
+        ctx.url = url;
+        ctx.params = params;
+        ctx.query = query;
+        ctx.body = body;
+        ctx.requestId = requestId;
+        return ctx;
+    }
+    releaseContext(ctx) {
+        ctx.req = ctx.req;
+        ctx.res = ctx.res;
+        ctx.url = ctx.url;
+        ctx.params = {};
+        ctx.query = {};
+        ctx.body = undefined;
+        ctx.requestId = undefined;
+        ctx.requestStart = undefined;
+        if (this.contextPool.length < (this.options.maxConcurrency ?? 1024)) {
+            this.contextPool.push(ctx);
+        }
+    }
+    async handleRequest(req, res) {
+        const rawMethod = (req.method || 'GET').toUpperCase();
+        const method = rawMethod;
+        const rawUrl = req.url || '/';
+        const host = req.headers.host || 'localhost';
+        const url = new url_1.URL(rawUrl, `http://${host}`);
+        const incomingRequestIdHeader = req.headers['x-request-id'];
+        let requestId;
+        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: types_1.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 = {};
+        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 = (0, resources_1.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;
+        try {
+            body = await this.readBody(req);
+        }
+        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);
+        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;
+        this.metrics.onRequestStart();
+        if (this.tracer) {
+            const event = {
+                type: 'request_start',
+                method,
+                path: url.pathname,
+                requestId,
+            };
+            const result = this.tracer(event);
+            if (result && typeof result.then === 'function') {
+                void result;
+            }
+        }
+        await this.scheduler.run(async () => {
+            const handler = match.handler;
+            try {
+                if (this.pipelineRunner) {
+                    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.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.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 {
+                        res.end();
+                    }
+                }
+            }
+            catch (err) {
+                await this.handleError(err, ctx);
+            }
+        }, {
+            priority: match.priority,
+            onOverloaded: overloaded,
+            timeoutMs: this.options.requestTimeoutMs,
+            onTimeout,
+        });
+        const duration = Date.now() - start;
+        this.metrics.onRequestEnd(duration, res.statusCode);
+        if (timedOut) {
+            this.metrics.onTimeout();
+        }
+        if (this.tracer) {
+            const event = {
+                type: 'request_end',
+                method,
+                path: url.pathname,
+                statusCode: res.statusCode,
+                durationMs: duration,
+                requestId,
+            };
+            const result = this.tracer(event);
+            if (result && typeof result.then === 'function') {
+                void result;
+            }
+        }
+        this.releaseContext(ctx);
+    }
+    async handleUpgrade(req, socket, head) {
+        const rawUrl = req.url || '/';
+        const host = req.headers.host || 'localhost';
+        const urlObj = new url_1.URL(rawUrl, `http://${host}`);
+        const path = urlObj.pathname;
+        const incomingRequestIdHeader = req.headers['x-request-id'];
+        let requestId;
+        if (typeof incomingRequestIdHeader === 'string') {
+            requestId = incomingRequestIdHeader;
+        }
+        else if (Array.isArray(incomingRequestIdHeader)) {
+            requestId = incomingRequestIdHeader[0];
+        }
+        if (!requestId) {
+            requestId = this.generateRequestId();
+        }
+        const start = Date.now();
+        const handlerEntry = this.upgradeHandlers.find((entry) => entry.path === rawUrl);
+        if (!handlerEntry) {
+            const duration = Date.now() - start;
+            const prefix = requestId ? `${requestId} ` : '';
+            const status = 404;
+            const color = '\x1b[33m';
+            const reset = '\x1b[0m';
+            const line = `${prefix}WS ${path} ${status} ${duration}ms`;
+            console.log(`${color}${line}${reset}`);
+            socket.destroy();
+            return;
+        }
+        try {
+            const result = handlerEntry.handler(req, socket, head);
+            if (result && typeof result.then === 'function') {
+                await result;
+            }
+            const duration = Date.now() - start;
+            const prefix = requestId ? `${requestId} ` : '';
+            const status = 101;
+            const color = '\x1b[36m';
+            const reset = '\x1b[0m';
+            const line = `${prefix}WS ${path} ${status} ${duration}ms`;
+            console.log(`${color}${line}${reset}`);
+        }
+        catch {
+            const duration = Date.now() - start;
+            const prefix = requestId ? `${requestId} ` : '';
+            const status = 500;
+            const color = '\x1b[34m';
+            const reset = '\x1b[0m';
+            const line = `${prefix}WS ${path} ${status} ${duration}ms`;
+            console.log(`${color}${line}${reset}`);
+            socket.destroy();
+        }
+    }
+    async readBody(req) {
+        const method = (req.method || 'GET').toUpperCase();
+        if (method === 'GET' || method === 'HEAD') {
+            return undefined;
+        }
+        const chunks = [];
+        let totalBytes = 0;
+        const maxBodyBytes = this.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 undefined;
+        }
+        const buffer = Buffer.concat(chunks);
+        const contentType = req.headers['content-type'] || '';
+        if (typeof contentType === 'string' &&
+            contentType.includes('application/json')) {
+            const text = buffer.toString('utf8');
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                throw new Error('QHTTPX_INVALID_JSON');
+            }
+        }
+        return buffer;
+    }
+    async runLifecycleHooks(hooks) {
+        if (hooks.length === 0) {
+            return;
+        }
+        for (const hook of hooks) {
+            try {
+                const result = hook();
+                if (result && typeof result.then === 'function') {
+                    await result;
+                }
+            }
+            catch {
+                // Ignore hook errors to avoid impacting core server flow
+            }
+        }
+    }
+    async handleError(err, ctx) {
+        const res = ctx.res;
+        if (res.writableEnded) {
+            return;
+        }
+        if (this.errorHandler) {
+            try {
+                const result = this.errorHandler(err, ctx);
+                if (result && typeof result.then === 'function') {
+                    await result;
+                }
+                if (res.writableEnded) {
+                    return;
+                }
+            }
+            catch {
+                // Fall through to default error handling below
+            }
+        }
+        if (res.writableEnded) {
+            return;
+        }
+        if (err instanceof types_1.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');
+    }
+    generateRequestId() {
+        const id = this.nextRequestId;
+        this.nextRequestId += 1;
+        return `${Date.now().toString(36)}-${id.toString(36)}`;
+    }
+}
+exports.QHTTPX = QHTTPX;