qhttpx 1.9.2 → 1.9.3

package/dist/src/openapi/generator.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAPIGenerator = void 0;
+class OpenAPIGenerator {
+    constructor(router, options) {
+        this.router = router;
+        this.options = options;
+    }
+    generate() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const paths = {};
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const schemas = {};
+        const methodMap = this.router.getRoutes();
+        for (const [method, routes] of methodMap.entries()) {
+            for (const route of routes) {
+                // Convert /users/:id to /users/{id}
+                const pathKey = route.path.replace(/:([a-zA-Z0-9_]+)/g, '{$1}');
+                if (!paths[pathKey]) {
+                    paths[pathKey] = {};
+                }
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const operation = {
+                    responses: {}
+                };
+                const schema = route.schema;
+                if (schema) {
+                    // Parameters (Query & Path)
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const parameters = [];
+                    // Path Params
+                    // We can infer path params from the URL segments
+                    const pathParams = route.path.match(/:([a-zA-Z0-9_]+)/g);
+                    if (pathParams) {
+                        pathParams.forEach(p => {
+                            const name = p.substring(1);
+                            // Check if we have specific schema for this param
+                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                            const paramSchema = schema.params?.properties?.[name];
+                            parameters.push({
+                                name,
+                                in: 'path',
+                                required: true,
+                                schema: paramSchema ? this.convertSchema(paramSchema) : { type: 'string' }
+                            });
+                        });
+                    }
+                    // Query Params
+                    if (schema.query) {
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        const queryProps = schema.query.properties || {};
+                        for (const [key, prop] of Object.entries(queryProps)) {
+                            parameters.push({
+                                name: key,
+                                in: 'query',
+                                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                                required: schema.query.required !== false && prop.required !== false, // simplified
+                                schema: this.convertSchema(prop)
+                            });
+                        }
+                    }
+                    if (parameters.length > 0) {
+                        operation.parameters = parameters;
+                    }
+                    // Request Body
+                    if (schema.body) {
+                        operation.requestBody = {
+                            content: {
+                                'application/json': {
+                                    schema: this.convertSchema(schema.body)
+                                }
+                            }
+                        };
+                    }
+                    // Responses
+                    // For now, default to 200 OK
+                    operation.responses['200'] = {
+                        description: 'Successful response',
+                        content: {
+                            'application/json': {
+                                schema: schema.response ? this.convertSchema(schema.response) : {}
+                            }
+                        }
+                    };
+                    // 400 Bad Request if validation exists
+                    if (schema.body || schema.query || schema.params) {
+                        operation.responses['400'] = {
+                            description: 'Validation Error'
+                        };
+                    }
+                }
+                else {
+                    // No schema, generic response
+                    operation.responses['200'] = {
+                        description: 'Successful response'
+                    };
+                }
+                paths[pathKey][method.toLowerCase()] = operation;
+            }
+        }
+        return {
+            openapi: '3.0.0',
+            info: this.options.info,
+            servers: this.options.servers,
+            paths,
+            components: {
+                schemas
+            }
+        };
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    convertSchema(schema) {
+        if (!schema)
+            return {};
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const res = { type: schema.type };
+        if (schema.properties) {
+            res.properties = {};
+            for (const [key, prop] of Object.entries(schema.properties)) {
+                res.properties[key] = this.convertSchema(prop);
+            }
+        }
+        if (schema.items) {
+            res.items = this.convertSchema(schema.items);
+        }
+        if (schema.min !== undefined) {
+            if (schema.type === 'string')
+                res.minLength = schema.min;
+            if (schema.type === 'number')
+                res.minimum = schema.min;
+            if (schema.type === 'array')
+                res.minItems = schema.min;
+        }
+        if (schema.max !== undefined) {
+            if (schema.type === 'string')
+                res.maxLength = schema.max;
+            if (schema.type === 'number')
+                res.maximum = schema.max;
+            if (schema.type === 'array')
+                res.maxItems = schema.max;
+        }
+        if (schema.pattern)
+            res.pattern = schema.pattern;
+        if (schema.enum)
+            res.enum = schema.enum;
+        return res;
+    }
+}
+exports.OpenAPIGenerator = OpenAPIGenerator;

package/dist/src/presets.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApiPreset = createApiPreset;
+exports.createStaticAppPreset = createStaticAppPreset;
+const security_1 = require("./security");
+const logger_1 = require("./logger");
+const static_1 = require("./static");
+function createApiPreset(options = {}) {
+    const middlewares = [];
+    // 1. Security (CORS, Headers)
+    middlewares.push(...(0, security_1.createSecureDefaults)(options.security));
+    // 2. Logging
+    if (options.logging !== false) {
+        const loggerOptions = typeof options.logging === 'object' ? options.logging : {};
+        middlewares.push((0, logger_1.createLoggerMiddleware)(loggerOptions));
+    }
+    return middlewares;
+}
+function createStaticAppPreset(options) {
+    const middlewares = [];
+    // 1. Security
+    middlewares.push(...(0, security_1.createSecureDefaults)(options.security));
+    // 2. Logging
+    if (options.logging !== false) {
+        const loggerOptions = typeof options.logging === 'object' ? options.logging : {};
+        middlewares.push((0, logger_1.createLoggerMiddleware)(loggerOptions));
+    }
+    // 3. Static Files
+    // We force fallthrough to true so API routes can handle non-static requests
+    const staticOptions = { ...options.static, fallthrough: true };
+    middlewares.push((0, static_1.createStaticMiddleware)(staticOptions));
+    return middlewares;
+}

package/dist/src/radix-router.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Radix tree router compiled into a flat array structure for zero-allocation matching.
+ * Built once at server startup (frozen).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RadixRouter = void 0;
+class RadixRouter {
+    constructor() {
+        this.roots = new Map();
+        this.isFrozen = false;
+    }
+    register(method, path, handler) {
+        if (this.isFrozen) {
+            console.warn(`Radix router is frozen. Late route registration (${method} ${path}) may not be optimized.`);
+        }
+        if (!this.roots.has(method)) {
+            this.roots.set(method, {});
+        }
+        const root = this.roots.get(method);
+        const segments = this.normalize(path);
+        let node = root;
+        for (const segment of segments) {
+            if (!node.children) {
+                node.children = new Map();
+            }
+            const isParam = segment.startsWith(':');
+            const key = isParam ? segment.slice(1) : segment;
+            if (!node.children.has(key)) {
+                node.children.set(key, {
+                    paramKey: isParam ? key : undefined,
+                });
+            }
+            node = node.children.get(key);
+        }
+        node.handler = handler;
+    }
+    match(method, path) {
+        const root = this.roots.get(method);
+        if (!root) {
+            return undefined;
+        }
+        const segments = this.normalize(path);
+        const params = {};
+        let node = root;
+        for (const segment of segments) {
+            if (!node.children) {
+                return undefined;
+            }
+            // Try exact match first
+            let child = node.children.get(segment);
+            // If no exact match, try param match
+            if (!child) {
+                for (const [key, candidate] of node.children.entries()) {
+                    if (candidate.paramKey && typeof key === 'string') {
+                        params[key] = segment;
+                        child = candidate;
+                        break;
+                    }
+                }
+            }
+            if (!child) {
+                return undefined;
+            }
+            node = child;
+        }
+        if (!node.handler) {
+            return undefined;
+        }
+        return { handler: node.handler, params };
+    }
+    freeze() {
+        if (this.isFrozen) {
+            return;
+        }
+        this.isFrozen = true;
+        // Future: compile to flat array structure here
+    }
+    isFrozenRouter() {
+        return this.isFrozen;
+    }
+    normalize(path) {
+        if (!path || path === '/') {
+            return [];
+        }
+        return path.split('/').filter((segment) => segment.length > 0);
+    }
+}
+exports.RadixRouter = RadixRouter;

package/dist/src/radix-tree.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RadixTree = void 0;
+class Node {
+    constructor() {
+        // Map segment -> Node
+        this.children = new Map();
+        // Parameter child node (only one allowed per level for simplicity)
+        this.paramChild = null;
+        this.paramName = null;
+        // Data if this node is a route end
+        this.data = null;
+    }
+}
+class RadixTree {
+    constructor() {
+        this.root = new Node();
+    }
+    insert(segments, handler, priority) {
+        let node = this.root;
+        for (const segment of segments) {
+            if (segment.startsWith(':')) {
+                const paramName = segment.slice(1);
+                if (!node.paramChild) {
+                    node.paramChild = new Node();
+                    node.paramChild.paramName = paramName;
+                }
+                else if (node.paramChild.paramName !== paramName) {
+                    throw new Error(`Cannot have two different parameter names at the same level: "${node.paramChild.paramName}" and "${paramName}"`);
+                }
+                node = node.paramChild;
+            }
+            else {
+                if (!node.children.has(segment)) {
+                    node.children.set(segment, new Node());
+                }
+                node = node.children.get(segment);
+            }
+        }
+        node.data = { handler, priority };
+    }
+    lookup(segments) {
+        // Use a stack-based approach or recursion. 
+        // For simplicity and correctness with backtracking, we'll use recursion.
+        // To minimize allocations, we pass the same params object and only copy on success?
+        // Actually, creating a params object is inevitable for the result.
+        return this.find(this.root, segments, 0);
+    }
+    find(node, segments, index) {
+        if (index === segments.length) {
+            if (node.data) {
+                return {
+                    handler: node.data.handler,
+                    priority: node.data.priority,
+                    params: {},
+                };
+            }
+            return null;
+        }
+        const segment = segments[index];
+        // 1. Try exact match
+        const child = node.children.get(segment);
+        if (child) {
+            const result = this.find(child, segments, index + 1);
+            if (result) {
+                return result;
+            }
+        }
+        // 2. Try param match
+        if (node.paramChild) {
+            const result = this.find(node.paramChild, segments, index + 1);
+            if (result) {
+                // If match found down this path, add current param to it
+                result.params[node.paramChild.paramName] = segment;
+                return result;
+            }
+        }
+        return null;
+    }
+}
+exports.RadixTree = RadixTree;

package/dist/src/resources.js

@@ -0,0 +1,25 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateWorkerCount = calculateWorkerCount;
+exports.isResourceOverloaded = isResourceOverloaded;
+const os_1 = __importDefault(require("os"));
+function calculateWorkerCount(setting) {
+    if (typeof setting === 'number') {
+        if (!Number.isFinite(setting) || setting <= 0) {
+            return 1;
+        }
+        return Math.floor(setting);
+    }
+    const cpuCount = os_1.default.cpus().length || 1;
+    return Math.max(1, cpuCount);
+}
+function isResourceOverloaded(sample, thresholds) {
+    if (thresholds.maxRssBytes !== undefined &&
+        sample.rssBytes > thresholds.maxRssBytes) {
+        return true;
+    }
+    return false;
+}

package/dist/src/router/radix-router.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Radix tree router compiled into a flat array structure for zero-allocation matching.
+ * Built once at server startup (frozen).
+ */
+import { HTTPMethod, QHTTPXHandler } from '../core/types';
+export type CompiledRadixMatch = {
+    handler: QHTTPXHandler;
+    params: Record<string, string>;
+};
+export declare class RadixRouter {
+    private roots;
+    private isFrozen;
+    register(method: HTTPMethod, path: string, handler: QHTTPXHandler): void;
+    match(method: HTTPMethod, path: string): CompiledRadixMatch | undefined;
+    freeze(): void;
+    isFrozenRouter(): boolean;
+    private normalize;
+}

package/dist/src/router/radix-router.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Radix tree router compiled into a flat array structure for zero-allocation matching.
+ * Built once at server startup (frozen).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RadixRouter = void 0;
+class RadixRouter {
+    constructor() {
+        this.roots = new Map();
+        this.isFrozen = false;
+    }
+    register(method, path, handler) {
+        if (this.isFrozen) {
+            console.warn(`Radix router is frozen. Late route registration (${method} ${path}) may not be optimized.`);
+        }
+        if (!this.roots.has(method)) {
+            this.roots.set(method, {});
+        }
+        const root = this.roots.get(method);
+        const segments = this.normalize(path);
+        let node = root;
+        for (const segment of segments) {
+            if (!node.children) {
+                node.children = new Map();
+            }
+            const isParam = segment.startsWith(':');
+            const key = isParam ? segment.slice(1) : segment;
+            if (!node.children.has(key)) {
+                node.children.set(key, {
+                    paramKey: isParam ? key : undefined,
+                });
+            }
+            node = node.children.get(key);
+        }
+        node.handler = handler;
+    }
+    match(method, path) {
+        const root = this.roots.get(method);
+        if (!root) {
+            return undefined;
+        }
+        const segments = this.normalize(path);
+        const params = {};
+        let node = root;
+        for (const segment of segments) {
+            if (!node.children) {
+                return undefined;
+            }
+            // Try exact match first
+            let child = node.children.get(segment);
+            // If no exact match, try param match
+            if (!child) {
+                for (const [key, candidate] of node.children.entries()) {
+                    if (candidate.paramKey && typeof key === 'string') {
+                        params[key] = segment;
+                        child = candidate;
+                        break;
+                    }
+                }
+            }
+            if (!child) {
+                return undefined;
+            }
+            node = child;
+        }
+        if (!node.handler) {
+            return undefined;
+        }
+        return { handler: node.handler, params };
+    }
+    freeze() {
+        if (this.isFrozen) {
+            return;
+        }
+        this.isFrozen = true;
+        // Future: compile to flat array structure here
+    }
+    isFrozenRouter() {
+        return this.isFrozen;
+    }
+    normalize(path) {
+        if (!path || path === '/') {
+            return [];
+        }
+        return path.split('/').filter((segment) => segment.length > 0);
+    }
+}
+exports.RadixRouter = RadixRouter;

package/dist/src/router/radix-tree.d.ts

@@ -0,0 +1,18 @@
+import { QHTTPXHandler, RoutePriority } from '../core/types';
+export type RouteData = {
+    handler: QHTTPXHandler;
+    priority: RoutePriority;
+};
+export type MatchResult = {
+    handler: QHTTPXHandler;
+    priority: RoutePriority;
+    params: Record<string, string>;
+};
+export declare class RadixTree {
+    private root;
+    insert(segments: string[], handler: QHTTPXHandler, priority: RoutePriority): void;
+    lookup(segments: string[]): MatchResult | null;
+    lookupPath(path: string): MatchResult | null;
+    private findPath;
+    private find;
+}

package/dist/src/router/radix-tree.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RadixTree = void 0;
+class Node {
+    constructor() {
+        // Map segment -> Node
+        this.children = new Map();
+        // Parameter child node (only one allowed per level for simplicity)
+        this.paramChild = null;
+        this.paramName = null;
+        // Data if this node is a route end
+        this.data = null;
+        // Optimization: Pre-allocated match result for static matches
+        this.staticMatch = null;
+    }
+}
+class RadixTree {
+    constructor() {
+        this.root = new Node();
+    }
+    insert(segments, handler, priority) {
+        let node = this.root;
+        for (const segment of segments) {
+            if (segment.startsWith(':')) {
+                const paramName = segment.slice(1);
+                if (!node.paramChild) {
+                    node.paramChild = new Node();
+                    node.paramChild.paramName = paramName;
+                }
+                else if (node.paramChild.paramName !== paramName) {
+                    throw new Error(`Cannot have two different parameter names at the same level: "${node.paramChild.paramName}" and "${paramName}"`);
+                }
+                node = node.paramChild;
+            }
+            else {
+                if (!node.children.has(segment)) {
+                    node.children.set(segment, new Node());
+                }
+                node = node.children.get(segment);
+            }
+        }
+        node.data = { handler, priority };
+        node.staticMatch = { handler, priority, params: {} };
+    }
+    lookup(segments) {
+        return this.find(this.root, segments, 0);
+    }
+    lookupPath(path) {
+        if (path === '/' || path === '') {
+            if (this.root.staticMatch) {
+                return this.root.staticMatch;
+            }
+            return null;
+        }
+        const start = path.charCodeAt(0) === 47 ? 1 : 0;
+        return this.findPath(this.root, path, start);
+    }
+    findPath(node, path, start) {
+        // Handle trailing slash or end of path
+        if (start >= path.length) {
+            if (node.staticMatch) {
+                return node.staticMatch;
+            }
+            return null;
+        }
+        let end = path.indexOf('/', start);
+        if (end === -1) {
+            end = path.length;
+        }
+        const segment = path.substring(start, end);
+        const nextStart = end + 1;
+        // Skip empty segments (e.g. //) to match normalize behavior
+        if (segment.length === 0) {
+            return this.findPath(node, path, nextStart);
+        }
+        // 1. Try exact match
+        const child = node.children.get(segment);
+        if (child) {
+            const result = this.findPath(child, path, nextStart);
+            if (result)
+                return result;
+        }
+        // 2. Try param match
+        if (node.paramChild) {
+            const result = this.findPath(node.paramChild, path, nextStart);
+            if (result) {
+                // Clone params to avoid modifying shared staticMatch
+                const newParams = { ...result.params };
+                newParams[node.paramChild.paramName] = segment;
+                return {
+                    handler: result.handler,
+                    priority: result.priority,
+                    params: newParams
+                };
+            }
+        }
+        return null;
+    }
+    find(node, segments, index) {
+        if (index === segments.length) {
+            if (node.data) {
+                return {
+                    handler: node.data.handler,
+                    priority: node.data.priority,
+                    params: {},
+                };
+            }
+            return null;
+        }
+        const segment = segments[index];
+        // 1. Try exact match
+        const child = node.children.get(segment);
+        if (child) {
+            const result = this.find(child, segments, index + 1);
+            if (result) {
+                return result;
+            }
+        }
+        // 2. Try param match
+        if (node.paramChild) {
+            const result = this.find(node.paramChild, segments, index + 1);
+            if (result) {
+                // If match found down this path, add current param to it
+                result.params[node.paramChild.paramName] = segment;
+                return result;
+            }
+        }
+        return null;
+    }
+}
+exports.RadixTree = RadixTree;

package/dist/src/router/router.d.ts

@@ -0,0 +1,34 @@
+import { HTTPMethod, QHTTPXHandler, RouteOptions, RoutePriority } from '../core/types';
+import { RouteSchema } from '../validation/types';
+type RouteDefinition = {
+    path: string;
+    segments: string[];
+    handler: QHTTPXHandler;
+    priority: RoutePriority;
+    schema?: RouteSchema | Record<string, unknown>;
+};
+export type RouteMatch = {
+    handler: QHTTPXHandler;
+    params: Record<string, string>;
+    priority: RoutePriority;
+};
+export declare class Router {
+    private readonly methodBuckets;
+    private readonly radixTrees;
+    private readonly staticRoutes;
+    private isFrozen;
+    register(method: HTTPMethod, path: string, handler: QHTTPXHandler, options?: RouteOptions & {
+        schema?: RouteSchema | Record<string, unknown>;
+    }): void;
+    getRoutes(): Map<HTTPMethod, RouteDefinition[]>;
+    match(method: HTTPMethod, path: string): RouteMatch | undefined;
+    getAllowedMethods(path: string): HTTPMethod[];
+    /**
+     * Freeze the router after server starts.
+     * Prevents further route registration and builds derived structures for optimized matching.
+     */
+    freeze(): void;
+    isFrozenRouter(): boolean;
+    private normalize;
+}
+export {};