qhttpx 1.8.0

package/dist/src/middleware/security.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSecurityHeadersMiddleware = createSecurityHeadersMiddleware;
+exports.createSecureDefaults = createSecureDefaults;
+exports.createRateLimitMiddleware = createRateLimitMiddleware;
+const cors_1 = require("./cors");
+function createSecurityHeadersMiddleware(options = {}) {
+    const { contentSecurityPolicy = "default-src 'self'", referrerPolicy = 'no-referrer', xFrameOptions = 'SAMEORIGIN', xContentTypeOptions = 'nosniff', xXssProtection = '1; mode=block', strictTransportSecurity, } = options;
+    return async (ctx, next) => {
+        if (contentSecurityPolicy) {
+            ctx.res.setHeader('content-security-policy', contentSecurityPolicy);
+        }
+        if (referrerPolicy) {
+            ctx.res.setHeader('referrer-policy', referrerPolicy);
+        }
+        if (xFrameOptions) {
+            ctx.res.setHeader('x-frame-options', xFrameOptions);
+        }
+        if (xContentTypeOptions) {
+            ctx.res.setHeader('x-content-type-options', xContentTypeOptions);
+        }
+        if (xXssProtection) {
+            ctx.res.setHeader('x-xss-protection', xXssProtection);
+        }
+        if (strictTransportSecurity) {
+            ctx.res.setHeader('strict-transport-security', strictTransportSecurity);
+        }
+        await next();
+    };
+}
+function createSecureDefaults(options = {}) {
+    const middlewares = [];
+    middlewares.push((0, cors_1.createCorsMiddleware)(options.cors));
+    middlewares.push(createSecurityHeadersMiddleware(options.securityHeaders));
+    return middlewares;
+}
+function createRateLimitMiddleware(options) {
+    const maxRequests = options.maxRequests;
+    const windowMs = options.windowMs;
+    const keyGenerator = options.keyGenerator ??
+        ((ctx) => {
+            const addr = ctx.req.socket.remoteAddress;
+            return addr || 'anonymous';
+        });
+    const buckets = new Map();
+    return async (ctx, next) => {
+        const now = Date.now();
+        const key = keyGenerator(ctx);
+        const existing = buckets.get(key);
+        let bucket = existing;
+        if (!bucket || bucket.resetAt <= now) {
+            bucket = {
+                count: 0,
+                resetAt: now + windowMs,
+            };
+            buckets.set(key, bucket);
+        }
+        bucket.count += 1;
+        if (bucket.count > maxRequests) {
+            if (!ctx.res.headersSent) {
+                ctx.res.statusCode = 429;
+                ctx.res.setHeader('content-type', 'text/plain; charset=utf-8');
+            }
+            ctx.res.end('Too Many Requests');
+            return;
+        }
+        await next();
+    };
+}

package/dist/src/middleware/static.js

@@ -0,0 +1,191 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStaticMiddleware = createStaticMiddleware;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function guessContentType(filePath) {
+    const ext = path_1.default.extname(filePath).toLowerCase();
+    const types = {
+        '.html': 'text/html; charset=utf-8',
+        '.htm': 'text/html; charset=utf-8',
+        '.js': 'application/javascript; charset=utf-8',
+        '.mjs': 'application/javascript; charset=utf-8',
+        '.css': 'text/css; charset=utf-8',
+        '.json': 'application/json; charset=utf-8',
+        '.png': 'image/png',
+        '.jpg': 'image/jpeg',
+        '.jpeg': 'image/jpeg',
+        '.gif': 'image/gif',
+        '.svg': 'image/svg+xml',
+        '.ico': 'image/x-icon',
+        '.txt': 'text/plain; charset=utf-8',
+        '.mp4': 'video/mp4',
+        '.webm': 'video/webm',
+        '.mp3': 'audio/mpeg',
+        '.wav': 'audio/wav',
+        '.pdf': 'application/pdf',
+        '.zip': 'application/zip',
+    };
+    return types[ext] || 'application/octet-stream';
+}
+function generateETag(stat) {
+    const mtime = stat.mtimeMs.toString(16);
+    const size = stat.size.toString(16);
+    return `W/"${size}-${mtime}"`;
+}
+function createStaticMiddleware(options) {
+    const root = path_1.default.resolve(options.root);
+    const indexFile = options.index ?? 'index.html';
+    const fallthrough = options.fallthrough ?? false;
+    const etag = options.etag ?? true;
+    const lastModified = options.lastModified ?? true;
+    const maxAge = options.maxAge ?? 0;
+    const immutable = options.immutable ?? false;
+    return async (ctx, next) => {
+        const method = ctx.req.method || 'GET';
+        if (method !== 'GET' && method !== 'HEAD') {
+            if (fallthrough) {
+                await next();
+                return;
+            }
+            ctx.res.statusCode = 405;
+            ctx.res.setHeader('Allow', 'GET, HEAD');
+            ctx.res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+            ctx.res.end('Method Not Allowed');
+            return;
+        }
+        let requestPath = ctx.url.pathname || '/';
+        // Prevent directory traversal
+        requestPath = requestPath.replace(/^(\.\.(\/|\\|$))+/, '');
+        // Normalize path
+        let safePath = path_1.default.normalize(requestPath);
+        if (safePath.startsWith('..'))
+            safePath = '/'; // Extra safety
+        // Handle root/directory requests
+        let filePath = path_1.default.join(root, safePath);
+        let stat;
+        try {
+            stat = await fs_1.default.promises.stat(filePath);
+            if (stat.isDirectory()) {
+                filePath = path_1.default.join(filePath, indexFile);
+                stat = await fs_1.default.promises.stat(filePath);
+            }
+        }
+        catch {
+            if (fallthrough) {
+                await next();
+                return;
+            }
+            ctx.res.statusCode = 404;
+            ctx.res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+            ctx.res.end('Not Found');
+            return;
+        }
+        if (!stat.isFile()) {
+            if (fallthrough) {
+                await next();
+                return;
+            }
+            ctx.res.statusCode = 404;
+            ctx.res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+            ctx.res.end('Not Found');
+            return;
+        }
+        // Caching Headers
+        if (maxAge > 0 || immutable) {
+            let cacheControl = `public, max-age=${maxAge}`;
+            if (immutable)
+                cacheControl += ', immutable';
+            ctx.res.setHeader('Cache-Control', cacheControl);
+        }
+        if (lastModified) {
+            ctx.res.setHeader('Last-Modified', stat.mtime.toUTCString());
+        }
+        if (etag) {
+            const tag = generateETag(stat);
+            ctx.res.setHeader('ETag', tag);
+            // ETag Freshness Check
+            const ifNoneMatch = ctx.req.headers['if-none-match'];
+            if (ifNoneMatch === tag) {
+                ctx.res.statusCode = 304;
+                ctx.res.end();
+                return;
+            }
+        }
+        // Last-Modified Freshness Check
+        const ifModifiedSince = ctx.req.headers['if-modified-since'];
+        if (ifModifiedSince) {
+            const since = new Date(ifModifiedSince).getTime();
+            // Round down mtime to seconds for comparison
+            const mtime = Math.floor(stat.mtimeMs / 1000) * 1000;
+            if (mtime <= since) {
+                ctx.res.statusCode = 304;
+                ctx.res.end();
+                return;
+            }
+        }
+        const contentType = guessContentType(filePath);
+        ctx.res.setHeader('Content-Type', contentType);
+        ctx.res.setHeader('Accept-Ranges', 'bytes');
+        // Range Support
+        const range = ctx.req.headers['range'];
+        let start = 0;
+        let end = stat.size - 1;
+        // let isRange = false;
+        if (range) {
+            const parts = range.replace(/bytes=/, '').split('-');
+            const partialStart = parts[0];
+            const partialEnd = parts[1];
+            const parsedStart = parseInt(partialStart, 10);
+            const parsedEnd = partialEnd ? parseInt(partialEnd, 10) : end;
+            if (!isNaN(parsedStart) && !isNaN(parsedEnd) && parsedStart <= parsedEnd && parsedEnd < stat.size) {
+                start = parsedStart;
+                end = parsedEnd;
+                // isRange = true;
+                ctx.res.statusCode = 206;
+                ctx.res.setHeader('Content-Range', `bytes ${start}-${end}/${stat.size}`);
+                ctx.res.setHeader('Content-Length', end - start + 1);
+            }
+            else {
+                // Invalid range
+                ctx.res.statusCode = 416;
+                ctx.res.setHeader('Content-Range', `bytes */${stat.size}`);
+                ctx.res.end();
+                return;
+            }
+        }
+        else {
+            ctx.res.statusCode = 200;
+            ctx.res.setHeader('Content-Length', stat.size);
+        }
+        if (method === 'HEAD') {
+            ctx.res.end();
+            return;
+        }
+        const stream = fs_1.default.createReadStream(filePath, { start, end });
+        // Disable auto-end if we are streaming?
+        // Actually, we can just pipe. But we need to make sure the server doesn't call res.end()
+        // The middleware architecture awaits next(), then server calls end().
+        // If we handle the response here, we should probably set a flag or just return without calling next() (which we do).
+        // But the server might still try to end it if we don't tell it we are done.
+        // In QHTTPX, if a handler returns, server checks `res.writableEnded`.
+        // Pipe calls end() by default.
+        // We need to wait for the stream to finish before returning from middleware
+        // so that the server doesn't race.
+        await new Promise((resolve, reject) => {
+            stream.pipe(ctx.res);
+            stream.on('end', resolve);
+            stream.on('error', (err) => {
+                stream.destroy();
+                reject(err);
+            });
+            ctx.res.on('close', () => {
+                stream.destroy();
+                resolve();
+            });
+        });
+    };
+}

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/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.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;