qhttpx 1.8.0

package/src/core/stream.ts

@@ -0,0 +1,111 @@
+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 function createSseStream(
+  ctx: QHTTPXContext,
+  options: SseOptions = {},
+): SseStream {
+  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 as unknown as {
+    flushHeaders?: () => void;
+    flush?: () => void;
+  };
+  if (anyRes.flushHeaders) {
+    anyRes.flushHeaders();
+  }
+
+  if (typeof options.retryMs === 'number') {
+    res.write(`retry: ${options.retryMs}\n\n`);
+  }
+
+  const send = (data: unknown, event?: string) => {
+    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 };
+}
+
+export type StreamOptions = {
+  contentType?: string;
+  status?: number;
+};
+
+export function sendStream(
+  ctx: QHTTPXContext,
+  stream: Readable,
+  options: StreamOptions = {},
+): Promise<void> {
+  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/src/core/tasks.ts

@@ -0,0 +1,138 @@
+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;
+};
+
+type TaskDefinition = {
+  name: string;
+  handler: QHTTPXTaskHandler;
+  options: QHTTPXTaskOptions;
+};
+
+export class TaskEngine {
+  private readonly scheduler: Scheduler;
+
+  private readonly tasks = new Map<string, TaskDefinition>();
+
+  private registeredTasksCount = 0;
+
+  private totalEnqueued = 0;
+
+  private totalCompleted = 0;
+
+  private totalFailed = 0;
+
+  private totalOverloaded = 0;
+
+  private totalRetried = 0;
+
+  constructor(scheduler: Scheduler) {
+    this.scheduler = scheduler;
+  }
+
+  register(
+    name: string,
+    handler: QHTTPXTaskHandler,
+    options: QHTTPXTaskOptions = {},
+  ): void {
+    if (!this.tasks.has(name)) {
+      this.registeredTasksCount += 1;
+    }
+    this.tasks.set(name, {
+      name,
+      handler,
+      options,
+    });
+  }
+
+  async enqueue(name: string, payload: unknown): Promise<void> {
+    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(): TaskMetrics {
+    return {
+      registeredTasks: this.registeredTasksCount,
+      totalEnqueued: this.totalEnqueued,
+      totalCompleted: this.totalCompleted,
+      totalFailed: this.totalFailed,
+      totalOverloaded: this.totalOverloaded,
+      totalRetried: this.totalRetried,
+    };
+  }
+
+  private async executeWithRetry(
+    def: TaskDefinition,
+    payload: unknown,
+  ): Promise<void> {
+    const maxRetries = def.options.maxRetries ?? 0;
+    const backoffMs = def.options.backoffMs ?? 0;
+
+    let attempt = 0;
+
+    for (;;) {
+      let overloaded = false;
+      let error: unknown;
+
+      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<void>((resolve) => {
+          setTimeout(resolve, backoffMs);
+        });
+      }
+    }
+  }
+}
+

package/src/core/types.ts

@@ -0,0 +1,178 @@
+import { IncomingMessage, ServerResponse } 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 enum RoutePriority {
+  CRITICAL = 'critical',
+  STANDARD = 'standard',
+  BEST_EFFORT = 'best-effort',
+}
+
+export type RouteOptions = {
+  priority?: RoutePriority;
+};
+
+export class HttpError extends Error {
+  status: number;
+
+  code?: string;
+
+  details?: unknown;
+
+  constructor(
+    status: number,
+    message?: string,
+    options: { code?: string; details?: unknown } = {},
+  ) {
+    super(message ?? 'HTTP Error');
+    this.status = status;
+    this.code = options.code;
+    this.details = options.details;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export type CookieOptions = {
+  domain?: string;
+  path?: string;
+  expires?: Date;
+  maxAge?: number;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: 'lax' | 'strict' | 'none';
+};
+
+export type QHTTPXContext = {
+  readonly req: IncomingMessage;
+  readonly res: ServerResponse;
+  readonly url: URL;
+  readonly params: Record<string, string>;
+  readonly query: Record<string, string | string[]>;
+  body: unknown;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  files?: Record<string, any>;
+  readonly cookies: Record<string, string>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  state: Record<string, any>;
+  readonly bufferPool: BufferPool;
+  requestId: string | undefined;
+  requestStart: number | undefined;
+  // Serializer for the current route
+  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;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  readonly call?: (op: string, params: any) => Promise<any>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  readonly render: (view: string, locals?: Record<string, any>) => Promise<void>;
+  readonly validate: <T = unknown>(schema: unknown, data?: unknown) => Promise<T>;
+  disableAutoEnd?: boolean;
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type QHTTPXOpHandler = (params: any, ctx: QHTTPXContext) => any | Promise<any>;
+
+export type QHTTPXHandler = (ctx: QHTTPXContext) => void | Promise<void>;
+
+export type QHTTPXRouteOptions = {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  schema?: RouteSchema | Record<string, any>;
+  handler: QHTTPXHandler;
+  priority?: RoutePriority;
+};
+
+export type QHTTPXMiddleware = (
+  ctx: QHTTPXContext,
+  next: () => Promise<void>,
+) => void | Promise<void>;
+
+export type QHTTPXErrorHandler = (
+  err: unknown,
+  ctx: QHTTPXContext,
+) => 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 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;
+};
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type QHTTPXPlugin<Options = any> = (
+  // eslint-disable-next-line @typescript-eslint/no-explicit-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;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [key: string]: any;
+};

package/src/core/websocket.ts

@@ -0,0 +1,112 @@
+import { IncomingMessage } from 'http';
+import { Duplex } from 'stream';
+import { URL } from 'url';
+import { WebSocket, WebSocketServer } 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 class WebSocketManager {
+  private readonly wss: WebSocketServer;
+  private readonly handlers: { path: string; handler: WSHandler }[] = [];
+  private readonly rooms: Map<string, Set<QHTTPXWebSocket>> = new Map();
+
+  constructor(private readonly requestIdGenerator: () => string) {
+    this.wss = new WebSocketServer({ noServer: true });
+  }
+
+  register(path: string, handler: WSHandler): void {
+    this.handlers.push({ path, handler });
+  }
+
+  async handleUpgrade(
+    req: IncomingMessage,
+    socket: Duplex,
+    head: Buffer,
+  ): Promise<void> {
+    const rawUrl = req.url || '/';
+    const host = req.headers.host || 'localhost';
+    const urlObj = new 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 as QHTTPXWebSocket;
+      qws.id = this.requestIdGenerator();
+
+      qws.join = (room: string) => this.join(room, qws);
+      qws.leave = (room: string) => this.leave(room, qws);
+
+      qws.on('close', () => {
+        this.leaveAll(qws);
+      });
+
+      handlerEntry.handler(qws, req);
+    });
+  }
+
+  private join(room: string, ws: QHTTPXWebSocket) {
+    if (!this.rooms.has(room)) {
+      this.rooms.set(room, new Set());
+    }
+    this.rooms.get(room)!.add(ws);
+  }
+
+  private leave(room: string, ws: QHTTPXWebSocket) {
+    const set = this.rooms.get(room);
+    if (set) {
+      set.delete(ws);
+      if (set.size === 0) {
+        this.rooms.delete(room);
+      }
+    }
+  }
+
+  private leaveAll(ws: QHTTPXWebSocket) {
+    for (const [room, set] of this.rooms) {
+      if (set.has(ws)) {
+        set.delete(ws);
+        if (set.size === 0) {
+          this.rooms.delete(room);
+        }
+      }
+    }
+  }
+
+  public to(room: string) {
+    return {
+      emit: (data: unknown) => {
+        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 === WebSocket.OPEN) {
+              client.send(payload);
+            }
+          }
+        }
+      },
+    };
+  }
+
+  public broadcast(data: unknown) {
+    const payload = typeof data === 'string' ? data : JSON.stringify(data);
+    for (const client of this.wss.clients) {
+      if (client.readyState === WebSocket.OPEN) {
+        client.send(payload);
+      }
+    }
+  }
+}

package/src/core/worker-queue.ts

@@ -0,0 +1,90 @@
+/**
+ * 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 class WorkerQueue<T> {
+  private readonly capacity: number;
+  private readonly buffer: (WorkItem<T> | undefined)[];
+
+  private writeIndex = 0;
+  private readIndex = 0;
+  private size = 0;
+
+  constructor(capacity: number = 1024) {
+    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: WorkItem<T>): boolean {
+    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(): WorkItem<T> | undefined {
+    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(): WorkItem<T> | undefined {
+    if (this.size <= 0) {
+      return undefined;
+    }
+    return this.buffer[this.readIndex];
+  }
+
+  /**
+   * Check if the queue is empty.
+   */
+  isEmpty(): boolean {
+    return this.size === 0;
+  }
+
+  /**
+   * Get the current size of the queue.
+   */
+  getSize(): number {
+    return this.size;
+  }
+
+  /**
+   * Get the capacity of the queue.
+   */
+  getCapacity(): number {
+    return this.capacity;
+  }
+}