qhttpx 1.9.1 → 1.9.3

package/dist/src/signals.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachSignalHandlers = attachSignalHandlers;
+function attachSignalHandlers(app, options = {}) {
+    const signals = options.signals ?? ['SIGINT', 'SIGTERM'];
+    const timeoutMs = options.timeoutMs ?? 10000;
+    let shuttingDown = false;
+    const handler = async (signal) => {
+        if (shuttingDown) {
+            return;
+        }
+        shuttingDown = true;
+        console.log(`Received ${signal}, shutting down...`);
+        const timer = setTimeout(() => {
+            console.error('Shutdown timed out, forcing exit. (some connections might be lost)');
+            process.exit(1);
+        }, timeoutMs);
+        try {
+            await app.shutdown();
+            clearTimeout(timer);
+            process.exit(0);
+        }
+        catch (err) {
+            console.error('Error during shutdown:', err);
+            process.exit(1);
+        }
+    };
+    for (const signal of signals) {
+        process.on(signal, handler);
+    }
+}

package/dist/src/static.js

@@ -0,0 +1,107 @@
+"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();
+    if (ext === '.html' || ext === '.htm') {
+        return 'text/html; charset=utf-8';
+    }
+    if (ext === '.js') {
+        return 'application/javascript; charset=utf-8';
+    }
+    if (ext === '.css') {
+        return 'text/css; charset=utf-8';
+    }
+    if (ext === '.json') {
+        return 'application/json; charset=utf-8';
+    }
+    if (ext === '.png') {
+        return 'image/png';
+    }
+    if (ext === '.jpg' || ext === '.jpeg') {
+        return 'image/jpeg';
+    }
+    if (ext === '.gif') {
+        return 'image/gif';
+    }
+    if (ext === '.svg') {
+        return 'image/svg+xml';
+    }
+    return 'application/octet-stream';
+}
+function createStaticMiddleware(options) {
+    const root = path_1.default.resolve(options.root);
+    const indexFile = options.index ?? 'index.html';
+    const fallthrough = options.fallthrough ?? 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('content-type', 'text/plain; charset=utf-8');
+            ctx.res.end('Method Not Allowed');
+            return;
+        }
+        let requestPath = ctx.url.pathname || '/';
+        requestPath = requestPath.replace(/^[/\\]+/, '');
+        if (requestPath === '') {
+            requestPath = indexFile;
+        }
+        else if (requestPath.endsWith('/')) {
+            requestPath = requestPath + indexFile;
+        }
+        let safePath = path_1.default.normalize(requestPath);
+        safePath = safePath.replace(/^(\.\.(\/|\\|$))+/, '');
+        const filePath = path_1.default.join(root, safePath);
+        let stat;
+        try {
+            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;
+        }
+        const contentType = guessContentType(filePath);
+        ctx.res.setHeader('content-type', contentType);
+        ctx.res.statusCode = 200;
+        if (method === 'HEAD') {
+            ctx.res.end();
+            return;
+        }
+        try {
+            const data = await fs_1.default.promises.readFile(filePath);
+            ctx.res.end(data);
+        }
+        catch {
+            if (!ctx.res.headersSent) {
+                ctx.res.statusCode = 500;
+                ctx.res.setHeader('content-type', 'text/plain; charset=utf-8');
+            }
+            ctx.res.end('Internal Server Error');
+        }
+    };
+}

package/dist/src/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/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/testing/index.d.ts

@@ -0,0 +1,25 @@
+import { QHTTPX } from '../core/server';
+import { HTTPMethod } from '../core/types';
+export declare class TestClient {
+    private app;
+    private server;
+    private baseURL;
+    constructor(app: QHTTPX);
+    /**
+     * Starts the server on a random port.
+     * Automatically called by request methods if not started.
+     */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    request(method: HTTPMethod, path: string, options?: {
+        headers?: Record<string, string>;
+        body?: any;
+        query?: Record<string, string | number | boolean>;
+    }): Promise<Response>;
+    get(path: string, options?: Omit<Parameters<TestClient['request']>[2], 'body'>): Promise<Response>;
+    post(path: string, body?: any, options?: Omit<Parameters<TestClient['request']>[2], 'body'>): Promise<Response>;
+    put(path: string, body?: any, options?: Omit<Parameters<TestClient['request']>[2], 'body'>): Promise<Response>;
+    delete(path: string, options?: Omit<Parameters<TestClient['request']>[2], 'body'>): Promise<Response>;
+    patch(path: string, body?: any, options?: Omit<Parameters<TestClient['request']>[2], 'body'>): Promise<Response>;
+}
+export declare function createTestClient(app: QHTTPX): TestClient;

package/dist/src/testing/index.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestClient = void 0;
+exports.createTestClient = createTestClient;
+class TestClient {
+    constructor(app) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.server = null;
+        this.baseURL = '';
+        this.app = app;
+    }
+    /**
+     * Starts the server on a random port.
+     * Automatically called by request methods if not started.
+     */
+    async start() {
+        if (this.server)
+            return;
+        const { port } = await this.app.listen(0);
+        this.server = this.app.serverInstance;
+        this.baseURL = `http://127.0.0.1:${port}`;
+    }
+    async stop() {
+        if (this.server) {
+            await this.app.close();
+            this.server = null;
+        }
+    }
+    async request(method, path, options = {}) {
+        if (!this.server) {
+            await this.start();
+        }
+        const url = new URL(path, this.baseURL);
+        if (options.query) {
+            Object.entries(options.query).forEach(([k, v]) => {
+                url.searchParams.append(k, String(v));
+            });
+        }
+        const headers = options.headers || {};
+        let bodyPayload;
+        if (options.body) {
+            if (typeof options.body === 'object' &&
+                !(options.body instanceof Uint8Array) &&
+                !(options.body instanceof ArrayBuffer) &&
+                !(options.body instanceof FormData) &&
+                !(options.body instanceof URLSearchParams)) {
+                bodyPayload = JSON.stringify(options.body);
+                if (!headers['content-type']) {
+                    headers['content-type'] = 'application/json';
+                }
+            }
+            else {
+                bodyPayload = options.body;
+            }
+        }
+        return fetch(url, {
+            method,
+            headers,
+            body: bodyPayload,
+        });
+    }
+    get(path, options) {
+        return this.request('GET', path, options);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    post(path, body, options) {
+        return this.request('POST', path, { ...options, body });
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    put(path, body, options) {
+        return this.request('PUT', path, { ...options, body });
+    }
+    delete(path, options) {
+        return this.request('DELETE', path, options);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    patch(path, body, options) {
+        return this.request('PATCH', path, { ...options, body });
+    }
+}
+exports.TestClient = TestClient;
+function createTestClient(app) {
+    return new TestClient(app);
+}

package/dist/src/testing.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTestClient = createTestClient;
+async function createTestClient(app) {
+    const { port } = await app.listen(0, '127.0.0.1');
+    const baseUrl = `http://127.0.0.1:${port}`;
+    const request = async (method, path, body, extraHeaders = {}) => {
+        const headers = { ...extraHeaders };
+        const init = {
+            method,
+            headers,
+        };
+        if (body !== undefined) {
+            if (typeof body === 'string') {
+                init.body = body;
+            }
+            else if (body instanceof Uint8Array || Buffer.isBuffer(body)) {
+                init.body = body;
+            }
+            else {
+                init.body = JSON.stringify(body);
+                if (!('content-type' in headers)) {
+                    headers['content-type'] = 'application/json';
+                }
+            }
+        }
+        return fetch(`${baseUrl}${path}`, init);
+    };
+    return {
+        get: (path, headers) => request('GET', path, undefined, headers),
+        post: (path, body, headers) => request('POST', path, body, headers),
+        put: (path, body, headers) => request('PUT', path, body, headers),
+        delete: (path, headers) => request('DELETE', path, undefined, headers),
+        close: async () => {
+            await app.close();
+        },
+        app,
+        url: baseUrl,
+    };
+}

package/dist/src/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/utils/cookies.d.ts

@@ -0,0 +1,3 @@
+import { CookieOptions } from '../core/types';
+export declare function parseCookies(header: string | undefined): Record<string, string>;
+export declare function serializeCookie(name: string, value: string, options?: CookieOptions): string;

package/dist/src/utils/cookies.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCookies = parseCookies;
+exports.serializeCookie = serializeCookie;
+function parseCookies(header) {
+    const list = {};
+    if (!header) {
+        return list;
+    }
+    header.split(';').forEach((cookie) => {
+        const parts = cookie.split('=');
+        const name = parts.shift()?.trim();
+        if (name) {
+            const value = parts.join('=');
+            list[name] = decodeURIComponent(value);
+        }
+    });
+    return list;
+}
+function serializeCookie(name, value, options = {}) {
+    let str = `${name}=${encodeURIComponent(value)}`;
+    if (options.maxAge) {
+        str += `; Max-Age=${Math.floor(options.maxAge)}`;
+    }
+    if (options.domain) {
+        str += `; Domain=${options.domain}`;
+    }
+    if (options.path) {
+        str += `; Path=${options.path}`;
+    }
+    else {
+        str += '; Path=/';
+    }
+    if (options.expires) {
+        str += `; Expires=${options.expires.toUTCString()}`;
+    }
+    if (options.httpOnly) {
+        str += '; HttpOnly';
+    }
+    if (options.secure) {
+        str += '; Secure';
+    }
+    if (options.sameSite) {
+        switch (options.sameSite) {
+            case 'lax':
+                str += '; SameSite=Lax';
+                break;
+            case 'strict':
+                str += '; SameSite=Strict';
+                break;
+            case 'none':
+                str += '; SameSite=None';
+                break;
+            default:
+                break;
+        }
+    }
+    return str;
+}

package/dist/src/utils/logger.d.ts

@@ -0,0 +1,12 @@
+import { QHTTPXContext, QHTTPXMiddleware } from '../core/types';
+export type LogEntry = {
+    method: string;
+    path: string;
+    status: number;
+    durationMs: number;
+    requestId?: string;
+};
+export type LoggerOptions = {
+    sink?: (entry: LogEntry, ctx: QHTTPXContext) => void;
+};
+export declare function createLoggerMiddleware(options?: LoggerOptions): QHTTPXMiddleware;

package/dist/src/utils/logger.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLoggerMiddleware = createLoggerMiddleware;
+function createLoggerMiddleware(options = {}) {
+    const sink = options.sink ??
+        ((entry) => {
+            const status = entry.status;
+            let color = '\x1b[37m';
+            if (status >= 200 && status < 300) {
+                color = '\x1b[32m';
+            }
+            else if (status === 404) {
+                color = '\x1b[33m';
+            }
+            else if (status >= 500) {
+                color = '\x1b[34m';
+            }
+            else if (status >= 400) {
+                color = '\x1b[35m';
+            }
+            const reset = '\x1b[0m';
+            const prefix = entry.requestId ? `${entry.requestId} ` : '';
+            const line = `${prefix}${entry.method} ${entry.path} ${status} ${entry.durationMs}ms`;
+            console.log(`${color}${line}${reset}`);
+        });
+    return async (ctx, next) => {
+        const start = ctx.requestStart ?? Date.now();
+        try {
+            await next();
+        }
+        finally {
+            const durationMs = Math.max(1, Date.now() - start);
+            const method = ctx.req.method || 'GET';
+            const path = ctx.url.pathname;
+            const status = ctx.res.statusCode || 200;
+            sink({
+                method,
+                path,
+                status,
+                durationMs,
+                requestId: ctx.requestId,
+            }, ctx);
+        }
+    };
+}

package/dist/src/utils/signals.d.ts

@@ -0,0 +1,6 @@
+import { QHTTPX } from '../core/server';
+export type SignalHandlerOptions = {
+    signals?: NodeJS.Signals[];
+    timeoutMs?: number;
+};
+export declare function attachSignalHandlers(app: QHTTPX, options?: SignalHandlerOptions): void;

package/dist/src/utils/signals.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachSignalHandlers = attachSignalHandlers;
+function attachSignalHandlers(app, options = {}) {
+    const signals = options.signals ?? ['SIGINT', 'SIGTERM'];
+    const timeoutMs = options.timeoutMs ?? 10000;
+    let shuttingDown = false;
+    const handler = async (signal) => {
+        if (shuttingDown) {
+            return;
+        }
+        shuttingDown = true;
+        console.log(`Received ${signal}, shutting down...`);
+        const timer = setTimeout(() => {
+            console.error('Shutdown timed out, forcing exit. (some connections might be lost)');
+            process.exit(1);
+        }, timeoutMs);
+        try {
+            await app.shutdown();
+            clearTimeout(timer);
+            process.exit(0);
+        }
+        catch (err) {
+            console.error('Error during shutdown:', err);
+            process.exit(1);
+        }
+    };
+    for (const signal of signals) {
+        process.on(signal, handler);
+    }
+}

package/dist/src/utils/sse.d.ts

@@ -0,0 +1,6 @@
+import { QHTTPXContext } from '../core/types';
+export interface SSEStream {
+    send(data: unknown, event?: string, id?: string): void;
+    close(): void;
+}
+export declare function createSSE(ctx: QHTTPXContext): SSEStream;

package/dist/src/utils/sse.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSSE = createSSE;
+function createSSE(ctx) {
+    const res = ctx.res;
+    // Disable auto-end so we can keep the connection open
+    ctx.disableAutoEnd = true;
+    // Only write headers if not already sent
+    if (!res.headersSent) {
+        res.setHeader('Content-Type', 'text/event-stream');
+        res.setHeader('Cache-Control', 'no-cache');
+        res.setHeader('Connection', 'keep-alive');
+        res.setHeader('X-Accel-Buffering', 'no'); // For Nginx
+        // Send initial ping/comment to flush headers and establish connection
+        res.write(': connected\n\n');
+    }
+    const send = (data, event, id) => {
+        if (id)
+            res.write(`id: ${id}\n`);
+        if (event)
+            res.write(`event: ${event}\n`);
+        const payload = typeof data === 'string' ? data : JSON.stringify(data);
+        res.write(`data: ${payload}\n\n`);
+    };
+    const close = () => {
+        res.end();
+    };
+    ctx.req.on('close', () => {
+        // console.log('SSE client disconnected');
+    });
+    return { send, close };
+}