qhttpx 1.9.2 → 1.9.3

package/dist/src/core/stream.d.ts

@@ -0,0 +1,15 @@
+import { Readable } from 'stream';
+import { QHTTPXContext } from './types';
+export type SseOptions = {
+    retryMs?: number;
+};
+export type SseStream = {
+    send: (data: unknown, event?: string) => void;
+    close: () => void;
+};
+export declare function createSseStream(ctx: QHTTPXContext, options?: SseOptions): SseStream;
+export type StreamOptions = {
+    contentType?: string;
+    status?: number;
+};
+export declare function sendStream(ctx: QHTTPXContext, stream: Readable, options?: StreamOptions): Promise<void>;

package/dist/src/core/stream.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSseStream = createSseStream;
+exports.sendStream = sendStream;
+function createSseStream(ctx, options = {}) {
+    const res = ctx.res;
+    if (!res.headersSent) {
+        res.statusCode = 200;
+        res.setHeader('content-type', 'text/event-stream; charset=utf-8');
+        res.setHeader('cache-control', 'no-cache');
+        res.setHeader('connection', 'keep-alive');
+    }
+    const anyRes = res;
+    if (anyRes.flushHeaders) {
+        anyRes.flushHeaders();
+    }
+    if (typeof options.retryMs === 'number') {
+        res.write(`retry: ${options.retryMs}\n\n`);
+    }
+    const send = (data, event) => {
+        if (res.writableEnded) {
+            return;
+        }
+        const payload = typeof data === 'string' ? data : JSON.stringify(data);
+        let chunk = '';
+        if (event) {
+            chunk += `event: ${event}\n`;
+        }
+        chunk += `data: ${payload}\n\n`;
+        res.write(chunk);
+        if (anyRes.flush) {
+            anyRes.flush();
+        }
+    };
+    const close = () => {
+        if (!res.writableEnded) {
+            res.end();
+        }
+    };
+    return { send, close };
+}
+function sendStream(ctx, stream, options = {}) {
+    const res = ctx.res;
+    if (!res.headersSent) {
+        if (options.status !== undefined) {
+            res.statusCode = options.status;
+        }
+        if (options.contentType) {
+            res.setHeader('content-type', options.contentType);
+        }
+    }
+    return new Promise((resolve, reject) => {
+        stream.on('error', (err) => {
+            if (!res.headersSent) {
+                res.statusCode = 500;
+                res.setHeader('content-type', 'text/plain; charset=utf-8');
+            }
+            if (!res.writableEnded) {
+                res.end('Internal Server Error');
+            }
+            reject(err);
+        });
+        stream.on('end', () => {
+            if (!res.writableEnded) {
+                res.end();
+            }
+            resolve();
+        });
+        stream.pipe(res, { end: false });
+    });
+}

package/dist/src/core/tasks.d.ts

@@ -0,0 +1,29 @@
+import { Scheduler } from './scheduler';
+export type QHTTPXTaskHandler = (payload: unknown) => void | Promise<void>;
+export type QHTTPXTaskOptions = {
+    maxRetries?: number;
+    backoffMs?: number;
+};
+export type TaskMetrics = {
+    registeredTasks: number;
+    totalEnqueued: number;
+    totalCompleted: number;
+    totalFailed: number;
+    totalOverloaded: number;
+    totalRetried: number;
+};
+export declare class TaskEngine {
+    private readonly scheduler;
+    private readonly tasks;
+    private registeredTasksCount;
+    private totalEnqueued;
+    private totalCompleted;
+    private totalFailed;
+    private totalOverloaded;
+    private totalRetried;
+    constructor(scheduler: Scheduler);
+    register(name: string, handler: QHTTPXTaskHandler, options?: QHTTPXTaskOptions): void;
+    enqueue(name: string, payload: unknown): Promise<void>;
+    getMetrics(): TaskMetrics;
+    private executeWithRetry;
+}

package/dist/src/core/tasks.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskEngine = void 0;
+class TaskEngine {
+    constructor(scheduler) {
+        this.tasks = new Map();
+        this.registeredTasksCount = 0;
+        this.totalEnqueued = 0;
+        this.totalCompleted = 0;
+        this.totalFailed = 0;
+        this.totalOverloaded = 0;
+        this.totalRetried = 0;
+        this.scheduler = scheduler;
+    }
+    register(name, handler, options = {}) {
+        if (!this.tasks.has(name)) {
+            this.registeredTasksCount += 1;
+        }
+        this.tasks.set(name, {
+            name,
+            handler,
+            options,
+        });
+    }
+    async enqueue(name, payload) {
+        const def = this.tasks.get(name);
+        if (!def) {
+            throw new Error(`Task "${name}" is not registered`);
+        }
+        this.totalEnqueued += 1;
+        await this.executeWithRetry(def, payload);
+    }
+    getMetrics() {
+        return {
+            registeredTasks: this.registeredTasksCount,
+            totalEnqueued: this.totalEnqueued,
+            totalCompleted: this.totalCompleted,
+            totalFailed: this.totalFailed,
+            totalOverloaded: this.totalOverloaded,
+            totalRetried: this.totalRetried,
+        };
+    }
+    async executeWithRetry(def, payload) {
+        const maxRetries = def.options.maxRetries ?? 0;
+        const backoffMs = def.options.backoffMs ?? 0;
+        let attempt = 0;
+        for (;;) {
+            let overloaded = false;
+            let error;
+            await this.scheduler.run(async () => {
+                try {
+                    await def.handler(payload);
+                }
+                catch (err) {
+                    error = err;
+                }
+            }, {
+                onOverloaded: () => {
+                    overloaded = true;
+                },
+            });
+            if (!overloaded && !error) {
+                this.totalCompleted += 1;
+                return;
+            }
+            if (attempt >= maxRetries) {
+                if (error) {
+                    this.totalFailed += 1;
+                    throw error;
+                }
+                if (overloaded) {
+                    this.totalOverloaded += 1;
+                    throw new Error(`Task "${def.name}" overloaded`);
+                }
+                return;
+            }
+            attempt += 1;
+            this.totalRetried += 1;
+            if (backoffMs > 0) {
+                await new Promise((resolve) => {
+                    setTimeout(resolve, backoffMs);
+                });
+            }
+        }
+    }
+}
+exports.TaskEngine = TaskEngine;

package/dist/src/core/types.d.ts

@@ -0,0 +1,173 @@
+import { IncomingMessage, ServerResponse, IncomingHttpHeaders } from 'http';
+import { URL } from 'url';
+import type { BufferPool, BufferPoolConfig } from './buffer-pool';
+import type { DatabaseManager } from '../database/manager';
+import type { RouteSchema, Validator } from '../validation/types';
+import type { ViewEngine } from '../views/types';
+import type { RequestFusionOptions } from './fusion';
+export type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+export declare enum RoutePriority {
+    CRITICAL = "critical",
+    STANDARD = "standard",
+    BEST_EFFORT = "best-effort"
+}
+export type RouteOptions = {
+    priority?: RoutePriority;
+};
+export declare class HttpError extends Error {
+    status: number;
+    code?: string;
+    details?: unknown;
+    constructor(status: number, message?: string, options?: {
+        code?: string;
+        details?: unknown;
+    });
+}
+export type CookieOptions = {
+    domain?: string;
+    path?: string;
+    expires?: Date;
+    maxAge?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'lax' | 'strict' | 'none';
+};
+export type QHTTPXFile = {
+    filename: string;
+    encoding: string;
+    mimeType: string;
+    data: Buffer;
+    size: number;
+};
+export type QHTTPXContext = {
+    readonly req: IncomingMessage;
+    readonly res: ServerResponse;
+    readonly headers: IncomingHttpHeaders;
+    readonly url: URL;
+    readonly method: HTTPMethod;
+    readonly ip: string;
+    readonly params: Record<string, string>;
+    readonly query: Record<string, string | string[]>;
+    body: unknown;
+    files?: Record<string, QHTTPXFile | QHTTPXFile[]>;
+    readonly cookies: Record<string, string>;
+    state: Record<string, any>;
+    readonly bufferPool: BufferPool;
+    requestId: string | undefined;
+    requestStart: number | undefined;
+    serializer?: (value: unknown) => string;
+    readonly json: (body: unknown, status?: number) => void;
+    readonly send: (body: string | Buffer, status?: number) => void;
+    readonly html: (html: string, status?: number) => void;
+    readonly redirect: (url: string, status?: number) => void;
+    readonly setCookie: (name: string, value: string, options?: CookieOptions) => void;
+    readonly db?: DatabaseManager;
+    readonly call?: (op: string, params: any) => Promise<any>;
+    readonly render: (view: string, locals?: Record<string, any>) => Promise<void>;
+    readonly validate: <T = unknown>(schema: unknown, data?: unknown) => Promise<T>;
+    disableAutoEnd?: boolean;
+    readonly path: string;
+    readonly next?: () => Promise<void>;
+};
+export type QHTTPXOpHandler = (params: any, ctx: QHTTPXContext) => any | Promise<any>;
+export type QHTTPXHandler = (ctx: QHTTPXContext) => void | Promise<void>;
+export type QHTTPXRouteOptions = {
+    schema?: RouteSchema | Record<string, any>;
+    handler: QHTTPXHandler;
+    priority?: RoutePriority;
+};
+export type QHTTPXRouteConfig = Omit<QHTTPXRouteOptions, 'handler'>;
+export type QHTTPXMiddleware = (ctx: QHTTPXContext, next: () => Promise<void>) => void | Promise<void>;
+export type QHTTPXErrorContext = QHTTPXContext & {
+    error: unknown;
+};
+export type QHTTPXErrorHandler = (ctx: QHTTPXErrorContext) => void | Promise<void>;
+export type QHTTPXNotFoundHandler = (ctx: QHTTPXContext) => void | Promise<void>;
+export type QHTTPXMethodNotAllowedHandler = (ctx: QHTTPXContext, allowedMethods: HTTPMethod[]) => void | Promise<void>;
+export type QHTTPXTraceEvent = {
+    type: 'request_start';
+    method: string;
+    path: string;
+    requestId?: string;
+} | {
+    type: 'request_end';
+    method: string;
+    path: string;
+    statusCode: number;
+    durationMs: number;
+    requestId?: string;
+};
+export type QHTTPXTracer = (event: QHTTPXTraceEvent) => void | Promise<void>;
+export type QHTTPXTaskHandler = (payload: unknown) => void | Promise<void>;
+export type QHTTPXTaskOptions = {
+    maxRetries?: number;
+    backoffMs?: number;
+};
+export type PerformanceMode = 'balanced' | 'ultra';
+export interface RateLimitStore {
+    increment(key: string, windowMs: number): Promise<{
+        total: number;
+        resetTime: number;
+    }>;
+    decrement(key: string): Promise<void>;
+    reset(key: string): Promise<void>;
+}
+export interface RateLimitOptions {
+    windowMs?: number;
+    max?: number;
+    message?: string | object;
+    statusCode?: number;
+    headers?: boolean;
+    keyGenerator?: (ctx: QHTTPXContext) => string;
+    skip?: (ctx: QHTTPXContext) => boolean;
+    store?: RateLimitStore;
+    trustProxy?: boolean;
+}
+export type QHTTPXOptions = {
+    name?: string;
+    workers?: 'auto' | number;
+    maxConcurrency?: number;
+    requestTimeoutMs?: number;
+    maxMemoryBytes?: number;
+    maxBodyBytes?: number;
+    keepAliveTimeoutMs?: number;
+    headersTimeoutMs?: number;
+    metricsEnabled?: boolean;
+    jsonSerializer?: (value: unknown) => string | Buffer;
+    bufferPoolConfig?: BufferPoolConfig;
+    errorHandler?: QHTTPXErrorHandler;
+    notFoundHandler?: QHTTPXNotFoundHandler;
+    methodNotAllowedHandler?: QHTTPXMethodNotAllowedHandler;
+    tracer?: QHTTPXTracer;
+    performanceMode?: PerformanceMode;
+    database?: DatabaseManager;
+    enableBatching?: boolean | {
+        endpoint: string;
+    };
+    validator?: Validator;
+    enableRequestFusion?: boolean | RequestFusionOptions;
+    viewEngine?: ViewEngine;
+    viewsPath?: string;
+    rateLimit?: RateLimitOptions;
+    cors?: CorsOptions | boolean;
+    compression?: CompressionOptions | boolean;
+};
+export type CorsOrigin = string | string[] | ((origin: string | undefined) => string | null | undefined);
+export type CorsOptions = {
+    origin?: CorsOrigin;
+    methods?: string[];
+    allowedHeaders?: string[];
+    exposedHeaders?: string[];
+    credentials?: boolean;
+    maxAgeSeconds?: number;
+};
+export type CompressionOptions = {
+    threshold?: number;
+    level?: number;
+};
+export type QHTTPXPlugin<Options = any> = (app: any, // We use 'any' here to avoid circular dependency with QHTTPX class, or we could use an interface
+options: Options) => void | Promise<void>;
+export type QHTTPXPluginOptions = {
+    prefix?: string;
+    [key: string]: any;
+};

package/dist/src/core/types.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpError = exports.RoutePriority = void 0;
+var RoutePriority;
+(function (RoutePriority) {
+    RoutePriority["CRITICAL"] = "critical";
+    RoutePriority["STANDARD"] = "standard";
+    RoutePriority["BEST_EFFORT"] = "best-effort";
+})(RoutePriority || (exports.RoutePriority = RoutePriority = {}));
+class HttpError extends Error {
+    constructor(status, message, options = {}) {
+        super(message ?? 'HTTP Error');
+        this.status = status;
+        this.code = options.code;
+        this.details = options.details;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.HttpError = HttpError;

package/dist/src/core/websocket.d.ts

@@ -0,0 +1,25 @@
+import { IncomingMessage } from 'http';
+import { Duplex } from 'stream';
+import { WebSocket } from 'ws';
+export interface QHTTPXWebSocket extends WebSocket {
+    join(room: string): void;
+    leave(room: string): void;
+    id: string;
+}
+export type WSHandler = (ws: QHTTPXWebSocket, req: IncomingMessage) => void;
+export declare class WebSocketManager {
+    private readonly requestIdGenerator;
+    private readonly wss;
+    private readonly handlers;
+    private readonly rooms;
+    constructor(requestIdGenerator: () => string);
+    register(path: string, handler: WSHandler): void;
+    handleUpgrade(req: IncomingMessage, socket: Duplex, head: Buffer): Promise<void>;
+    private join;
+    private leave;
+    private leaveAll;
+    to(room: string): {
+        emit: (data: unknown) => void;
+    };
+    broadcast(data: unknown): void;
+}

package/dist/src/core/websocket.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketManager = void 0;
+const url_1 = require("url");
+const ws_1 = require("ws");
+class WebSocketManager {
+    constructor(requestIdGenerator) {
+        this.requestIdGenerator = requestIdGenerator;
+        this.handlers = [];
+        this.rooms = new Map();
+        this.wss = new ws_1.WebSocketServer({ noServer: true });
+    }
+    register(path, handler) {
+        this.handlers.push({ path, handler });
+    }
+    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 handlerEntry = this.handlers.find((entry) => entry.path === path);
+        if (!handlerEntry) {
+            socket.destroy();
+            return;
+        }
+        this.wss.handleUpgrade(req, socket, head, (ws) => {
+            const qws = ws;
+            qws.id = this.requestIdGenerator();
+            qws.join = (room) => this.join(room, qws);
+            qws.leave = (room) => this.leave(room, qws);
+            qws.on('close', () => {
+                this.leaveAll(qws);
+            });
+            handlerEntry.handler(qws, req);
+        });
+    }
+    join(room, ws) {
+        if (!this.rooms.has(room)) {
+            this.rooms.set(room, new Set());
+        }
+        this.rooms.get(room).add(ws);
+    }
+    leave(room, ws) {
+        const set = this.rooms.get(room);
+        if (set) {
+            set.delete(ws);
+            if (set.size === 0) {
+                this.rooms.delete(room);
+            }
+        }
+    }
+    leaveAll(ws) {
+        for (const [room, set] of this.rooms) {
+            if (set.has(ws)) {
+                set.delete(ws);
+                if (set.size === 0) {
+                    this.rooms.delete(room);
+                }
+            }
+        }
+    }
+    to(room) {
+        return {
+            emit: (data) => {
+                const set = this.rooms.get(room);
+                if (set) {
+                    const payload = typeof data === 'string' ? data : JSON.stringify(data);
+                    for (const client of set) {
+                        if (client.readyState === ws_1.WebSocket.OPEN) {
+                            client.send(payload);
+                        }
+                    }
+                }
+            },
+        };
+    }
+    broadcast(data) {
+        const payload = typeof data === 'string' ? data : JSON.stringify(data);
+        for (const client of this.wss.clients) {
+            if (client.readyState === ws_1.WebSocket.OPEN) {
+                client.send(payload);
+            }
+        }
+    }
+}
+exports.WebSocketManager = WebSocketManager;

package/dist/src/core/worker-queue.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Lock-free (or lock-minimal) work queue for per-worker task distribution.
+ * Uses a simple ring buffer for high throughput.
+ */
+export type WorkItem<T> = {
+    id: number;
+    task: T;
+    priority: number;
+};
+export declare class WorkerQueue<T> {
+    private readonly capacity;
+    private readonly buffer;
+    private writeIndex;
+    private readIndex;
+    private size;
+    constructor(capacity?: number);
+    /**
+     * Enqueue a work item. Returns true if successful, false if queue is full.
+     */
+    enqueue(item: WorkItem<T>): boolean;
+    /**
+     * Dequeue a work item. Returns undefined if queue is empty.
+     */
+    dequeue(): WorkItem<T> | undefined;
+    /**
+     * Peek at the next item without removing it.
+     */
+    peek(): WorkItem<T> | undefined;
+    /**
+     * Check if the queue is empty.
+     */
+    isEmpty(): boolean;
+    /**
+     * Get the current size of the queue.
+     */
+    getSize(): number;
+    /**
+     * Get the capacity of the queue.
+     */
+    getCapacity(): number;
+}

package/dist/src/core/worker-queue.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * Lock-free (or lock-minimal) work queue for per-worker task distribution.
+ * Uses a simple ring buffer for high throughput.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkerQueue = void 0;
+class WorkerQueue {
+    constructor(capacity = 1024) {
+        this.writeIndex = 0;
+        this.readIndex = 0;
+        this.size = 0;
+        if (capacity <= 0 || !Number.isInteger(capacity)) {
+            throw new Error('Capacity must be a positive integer');
+        }
+        // Ensure capacity is a power of 2 for efficient modulo with bitmask
+        this.capacity = Math.pow(2, Math.ceil(Math.log2(capacity)));
+        this.buffer = new Array(this.capacity);
+    }
+    /**
+     * Enqueue a work item. Returns true if successful, false if queue is full.
+     */
+    enqueue(item) {
+        if (this.size >= this.capacity) {
+            return false;
+        }
+        this.buffer[this.writeIndex] = item;
+        this.writeIndex = (this.writeIndex + 1) & (this.capacity - 1);
+        this.size += 1;
+        return true;
+    }
+    /**
+     * Dequeue a work item. Returns undefined if queue is empty.
+     */
+    dequeue() {
+        if (this.size <= 0) {
+            return undefined;
+        }
+        const item = this.buffer[this.readIndex];
+        this.buffer[this.readIndex] = undefined;
+        this.readIndex = (this.readIndex + 1) & (this.capacity - 1);
+        this.size -= 1;
+        return item;
+    }
+    /**
+     * Peek at the next item without removing it.
+     */
+    peek() {
+        if (this.size <= 0) {
+            return undefined;
+        }
+        return this.buffer[this.readIndex];
+    }
+    /**
+     * Check if the queue is empty.
+     */
+    isEmpty() {
+        return this.size === 0;
+    }
+    /**
+     * Get the current size of the queue.
+     */
+    getSize() {
+        return this.size;
+    }
+    /**
+     * Get the capacity of the queue.
+     */
+    getCapacity() {
+        return this.capacity;
+    }
+}
+exports.WorkerQueue = WorkerQueue;

package/dist/src/cors.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCorsMiddleware = createCorsMiddleware;
+function resolveOrigin(origin, requestOrigin) {
+    if (!origin) {
+        return '*';
+    }
+    if (typeof origin === 'string') {
+        return origin;
+    }
+    if (Array.isArray(origin)) {
+        if (!requestOrigin) {
+            return null;
+        }
+        if (origin.includes(requestOrigin)) {
+            return requestOrigin;
+        }
+        return null;
+    }
+    return origin(requestOrigin);
+}
+function createCorsMiddleware(options = {}) {
+    const methodsHeader = options.methods && options.methods.length > 0
+        ? options.methods.join(', ')
+        : 'GET,HEAD,PUT,PATCH,POST,DELETE,OPTIONS';
+    const allowedHeadersHeader = options.allowedHeaders && options.allowedHeaders.length > 0
+        ? options.allowedHeaders.join(', ')
+        : undefined;
+    const exposedHeadersHeader = options.exposedHeaders && options.exposedHeaders.length > 0
+        ? options.exposedHeaders.join(', ')
+        : undefined;
+    const maxAgeHeader = typeof options.maxAgeSeconds === 'number'
+        ? String(options.maxAgeSeconds)
+        : undefined;
+    const allowCredentials = options.credentials ?? false;
+    return async (ctx, next) => {
+        const requestOriginHeader = ctx.req.headers.origin;
+        const resolvedOrigin = resolveOrigin(options.origin, requestOriginHeader);
+        if (resolvedOrigin) {
+            ctx.res.setHeader('access-control-allow-origin', resolvedOrigin);
+            if (allowCredentials) {
+                ctx.res.setHeader('access-control-allow-credentials', 'true');
+            }
+            if (exposedHeadersHeader) {
+                ctx.res.setHeader('access-control-expose-headers', exposedHeadersHeader);
+            }
+        }
+        if (ctx.req.method === 'OPTIONS') {
+            ctx.res.statusCode = 204;
+            ctx.res.setHeader('access-control-allow-methods', methodsHeader);
+            const requestHeaders = typeof ctx.req.headers['access-control-request-headers'] === 'string'
+                ? ctx.req.headers['access-control-request-headers']
+                : undefined;
+            const headersValue = allowedHeadersHeader || requestHeaders;
+            if (headersValue) {
+                ctx.res.setHeader('access-control-allow-headers', headersValue);
+            }
+            if (maxAgeHeader) {
+                ctx.res.setHeader('access-control-max-age', maxAgeHeader);
+            }
+            ctx.res.end();
+            return;
+        }
+        await next();
+    };
+}