qhttpx 1.9.1 → 1.9.3

package/dist/src/middleware/presets.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApiPreset = createApiPreset;
+exports.createStaticAppPreset = createStaticAppPreset;
+const security_1 = require("./security");
+const cors_1 = require("./cors");
+const compression_1 = require("./compression");
+const logger_1 = require("../utils/logger");
+const static_1 = require("./static");
+const rate_limit_1 = require("./rate-limit");
+function createApiPreset(options = {}) {
+    const middlewares = [];
+    // 1. CORS
+    // Default to true (enabled) if not specified, to match createSecureDefaults behavior
+    const corsOpts = options.cors ?? options.security?.cors ?? true;
+    if (corsOpts !== false) {
+        const opts = corsOpts === true ? {} : corsOpts;
+        middlewares.push((0, cors_1.createCorsMiddleware)(opts));
+    }
+    // 2. Security Headers
+    middlewares.push((0, security_1.createSecurityHeadersMiddleware)(options.security?.securityHeaders));
+    // 3. Compression
+    if (options.compression) {
+        const opts = options.compression === true ? {} : options.compression;
+        middlewares.push((0, compression_1.createCompressionMiddleware)(opts));
+    }
+    // 4. Logging
+    if (options.logging !== false) {
+        const loggerOptions = typeof options.logging === 'object' ? options.logging : {};
+        middlewares.push((0, logger_1.createLoggerMiddleware)(loggerOptions));
+    }
+    // 5. Rate Limit
+    if (options.rateLimit) {
+        middlewares.push((0, rate_limit_1.rateLimit)(options.rateLimit));
+    }
+    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/middleware/rate-limit.d.ts

@@ -0,0 +1,14 @@
+import type { QHTTPXMiddleware, RateLimitOptions, RateLimitStore } from '../core/types';
+export declare class MemoryStore implements RateLimitStore {
+    private hits;
+    private interval?;
+    constructor(clearPeriodMs?: number);
+    increment(key: string, windowMs: number): Promise<{
+        total: number;
+        resetTime: number;
+    }>;
+    decrement(key: string): Promise<void>;
+    reset(key: string): Promise<void>;
+    private cleanup;
+}
+export declare const rateLimit: (options?: RateLimitOptions) => QHTTPXMiddleware;

package/dist/src/middleware/rate-limit.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rateLimit = exports.MemoryStore = void 0;
+class MemoryStore {
+    constructor(clearPeriodMs = 60000) {
+        this.hits = new Map();
+        // Cleanup expired entries periodically
+        if (clearPeriodMs > 0) {
+            this.interval = setInterval(() => this.cleanup(), clearPeriodMs);
+            this.interval.unref(); // Don't hold process open
+        }
+    }
+    async increment(key, windowMs) {
+        const now = Date.now();
+        let record = this.hits.get(key);
+        if (!record || now > record.resetTime) {
+            record = { count: 1, resetTime: now + windowMs };
+            this.hits.set(key, record);
+        }
+        else {
+            record.count++;
+        }
+        return { total: record.count, resetTime: record.resetTime };
+    }
+    async decrement(key) {
+        const record = this.hits.get(key);
+        if (record && record.count > 0) {
+            record.count--;
+        }
+    }
+    async reset(key) {
+        this.hits.delete(key);
+    }
+    cleanup() {
+        const now = Date.now();
+        for (const [key, record] of this.hits.entries()) {
+            if (now > record.resetTime) {
+                this.hits.delete(key);
+            }
+        }
+    }
+}
+exports.MemoryStore = MemoryStore;
+const rateLimit = (options = {}) => {
+    const windowMs = options.windowMs ?? 60000; // 1 minute default
+    const max = options.max ?? 100; // 100 requests default
+    const message = options.message ?? 'Too many requests, please try again later.';
+    const statusCode = options.statusCode ?? 429;
+    const headers = options.headers ?? true;
+    const store = options.store ?? new MemoryStore();
+    const keyGenerator = options.keyGenerator ?? ((ctx) => {
+        if (options.trustProxy) {
+            const forwarded = ctx.req.headers['x-forwarded-for'];
+            if (forwarded) {
+                return Array.isArray(forwarded) ? forwarded[0] : forwarded.split(',')[0].trim();
+            }
+        }
+        return ctx.req.socket.remoteAddress || 'unknown';
+    });
+    return async (ctx, next) => {
+        if (options.skip?.(ctx)) {
+            return next();
+        }
+        const key = keyGenerator(ctx);
+        const { total, resetTime } = await store.increment(key, windowMs);
+        const remaining = Math.max(0, max - total);
+        const resetSeconds = Math.ceil((resetTime - Date.now()) / 1000);
+        if (headers) {
+            ctx.res.setHeader('X-RateLimit-Limit', max);
+            ctx.res.setHeader('X-RateLimit-Remaining', remaining);
+            ctx.res.setHeader('X-RateLimit-Reset', resetSeconds);
+        }
+        if (total > max) {
+            if (headers) {
+                ctx.res.setHeader('Retry-After', resetSeconds);
+            }
+            ctx.json(typeof message === 'string' ? { error: message } : message, statusCode);
+            return;
+        }
+        await next();
+    };
+};
+exports.rateLimit = rateLimit;

package/dist/src/middleware/security.d.ts

@@ -0,0 +1,21 @@
+import { QHTTPXContext, QHTTPXMiddleware, CorsOptions } from '../core/types';
+export type SecurityHeadersOptions = {
+    contentSecurityPolicy?: string | null;
+    referrerPolicy?: string | null;
+    xFrameOptions?: 'DENY' | 'SAMEORIGIN' | null;
+    xContentTypeOptions?: 'nosniff' | null;
+    xXssProtection?: '0' | '1; mode=block' | null;
+    strictTransportSecurity?: string | null;
+};
+export declare function createSecurityHeadersMiddleware(options?: SecurityHeadersOptions): QHTTPXMiddleware;
+export type SecureDefaultsOptions = {
+    cors?: CorsOptions;
+    securityHeaders?: SecurityHeadersOptions;
+};
+export declare function createSecureDefaults(options?: SecureDefaultsOptions): QHTTPXMiddleware[];
+export type RateLimitOptions = {
+    maxRequests: number;
+    windowMs: number;
+    keyGenerator?: (ctx: QHTTPXContext) => string;
+};
+export declare function createRateLimitMiddleware(options: RateLimitOptions): QHTTPXMiddleware;

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.d.ts

@@ -0,0 +1,11 @@
+import { QHTTPXMiddleware } from '../core/types';
+export type StaticOptions = {
+    root: string;
+    index?: string;
+    fallthrough?: boolean;
+    etag?: boolean;
+    lastModified?: boolean;
+    maxAge?: number;
+    immutable?: boolean;
+};
+export declare function createStaticMiddleware(options: StaticOptions): QHTTPXMiddleware;

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/native/index.d.ts

@@ -0,0 +1,32 @@
+export interface NativeServerBinding {
+    parse(buffer: Buffer): {
+        method: string;
+        path: string;
+        version: number;
+        headers: Record<string, string>;
+        bodyOffset: number;
+    } | null;
+    createResponse(statusCode: number, headers: Record<string, string>, body?: string | Buffer): Buffer;
+    createJSONResponse(obj: unknown): Buffer;
+    writeResponse(fd: number, chunks: (Buffer | string)[]): void;
+    setCPUAffinity(cpuId: number): boolean;
+}
+export declare class NativeServer {
+    private binding;
+    constructor();
+    get isAvailable(): boolean;
+    parse(buffer: Buffer): {
+        method: string;
+        path: string;
+        version: number;
+        headers: Record<string, string>;
+        bodyOffset: number;
+    } | null;
+    createResponse(statusCode: number, headers: Record<string, string>, body?: string | Buffer): Buffer<ArrayBufferLike>;
+    createJSONResponse(obj: unknown): Buffer<ArrayBufferLike>;
+    writeResponse(fd: number, chunks: (Buffer | string)[]): void;
+    setCPUAffinity(cpuId: number): boolean;
+    private disableNative;
+    private jsCreateResponse;
+    private jsCreateJSONResponse;
+}

package/dist/src/native/index.js

@@ -0,0 +1,141 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NativeServer = void 0;
+const path_1 = __importDefault(require("path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const loadBinding = require('node-gyp-build');
+// EXPECTED ABI VERSION
+const EXPECTED_ABI = 1;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let nativeBinding = null;
+try {
+    // Look for prebuilds or built binary in root
+    const rootDir = __dirname.includes('dist')
+        ? path_1.default.join(__dirname, '..', '..', '..')
+        : path_1.default.join(__dirname, '..', '..');
+    const binding = loadBinding(rootDir);
+    // 5. Version lock the ABI
+    if (binding && binding.abi === EXPECTED_ABI) {
+        nativeBinding = binding;
+    }
+    else if (binding) {
+        // Version mismatch - disable native
+        // console.warn(`QHTTPX: Native ABI mismatch (Expected: ${EXPECTED_ABI}, Got: ${binding.abi}). Falling back to JS.`);
+        nativeBinding = null;
+    }
+}
+catch {
+    // Graceful fallback to JS implementation
+}
+class NativeServer {
+    constructor() {
+        if (nativeBinding && nativeBinding.NativeServer) {
+            try {
+                this.binding = new nativeBinding.NativeServer();
+            }
+            catch {
+                this.binding = null;
+            }
+        }
+        else {
+            this.binding = null;
+        }
+    }
+    get isAvailable() {
+        return this.binding !== null;
+    }
+    // 4. Guard every native call
+    parse(buffer) {
+        if (this.binding) {
+            try {
+                return this.binding.parse(buffer);
+            }
+            catch {
+                this.disableNative();
+            }
+        }
+        // Fallback: If native parse fails, we return null.
+        // The NativeAdapter will see null and might close the connection or handle error.
+        // We cannot easily implement a full HTTP parser in JS here without adding dependencies.
+        // But since NativeAdapter falls back to http.Server if !isAvailable, 
+        // disabling native here ensures subsequent requests use the safe path.
+        return null;
+    }
+    createResponse(statusCode, headers, body) {
+        if (this.binding) {
+            try {
+                return this.binding.createResponse(statusCode, headers, body);
+            }
+            catch {
+                this.disableNative();
+            }
+        }
+        return this.jsCreateResponse(statusCode, headers, body);
+    }
+    createJSONResponse(obj) {
+        if (this.binding) {
+            try {
+                return this.binding.createJSONResponse(obj);
+            }
+            catch {
+                this.disableNative();
+            }
+        }
+        // Fallback: Use JSON.stringify + Buffer
+        return this.jsCreateJSONResponse(obj);
+    }
+    writeResponse(fd, chunks) {
+        if (this.binding) {
+            try {
+                return this.binding.writeResponse(fd, chunks);
+            }
+            catch {
+                this.disableNative();
+            }
+        }
+        // No JS fallback for raw FD writes (requires net.Socket usually)
+        // The caller (NativeAdapter) should handle this by using socket.write()
+        // We throw here so caller knows to use fallback
+        throw new Error('Native writeResponse not available');
+    }
+    setCPUAffinity(cpuId) {
+        if (this.binding) {
+            try {
+                return this.binding.setCPUAffinity(cpuId);
+            }
+            catch {
+                this.disableNative();
+            }
+        }
+        return false;
+    }
+    disableNative() {
+        this.binding = null;
+        // console.warn('QHTTPX: Native module disabled due to error. Falling back to JS.');
+    }
+    // --- JS Fallbacks ---
+    jsCreateResponse(statusCode, headers, body) {
+        const statusMessage = statusCode === 200 ? 'OK' : 'Unknown'; // Simplified
+        let head = `HTTP/1.1 ${statusCode} ${statusMessage}\r\n`;
+        for (const [key, value] of Object.entries(headers)) {
+            head += `${key}: ${value}\r\n`;
+        }
+        head += '\r\n';
+        const headBuf = Buffer.from(head);
+        if (body) {
+            const bodyBuf = Buffer.isBuffer(body) ? body : Buffer.from(body);
+            return Buffer.concat([headBuf, bodyBuf]);
+        }
+        return headBuf;
+    }
+    jsCreateJSONResponse(obj) {
+        const json = JSON.stringify(obj);
+        const contentLen = Buffer.byteLength(json);
+        const head = `HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: ${contentLen}\r\n\r\n`;
+        return Buffer.concat([Buffer.from(head), Buffer.from(json)]);
+    }
+}
+exports.NativeServer = NativeServer;

package/dist/src/openapi/generator.d.ts

@@ -0,0 +1,19 @@
+import { Router } from '../router/router';
+export type OpenAPIOptions = {
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+    servers?: {
+        url: string;
+        description?: string;
+    }[];
+};
+export declare class OpenAPIGenerator {
+    private router;
+    private options;
+    constructor(router: Router, options: OpenAPIOptions);
+    generate(): object;
+    private convertSchema;
+}