qhttpx 1.8.0

package/src/core/metrics.ts

@@ -0,0 +1,166 @@
+import type { TaskEngine, TaskMetrics } from './tasks';
+import { Scheduler } from './scheduler';
+
+export type LatencySnapshot = {
+  p50: number | null;
+  p95: number | null;
+  p99: number | null;
+};
+
+export type MetricsSnapshot = {
+  totalRequests: number;
+  inFlightRequests: number;
+  totalErrors: number;
+  totalTimeouts: number;
+  requestsPerSecond: number;
+  latency: LatencySnapshot;
+  scheduler: {
+    inFlight: number;
+  };
+  tasks?: TaskMetrics;
+  memory: {
+    rssBytes: number;
+    heapUsedBytes: number;
+  };
+};
+
+export class Metrics {
+  private readonly scheduler: Scheduler;
+
+  private readonly taskEngine?: TaskEngine;
+
+  private readonly latencies: number[] = [];
+
+  private readonly maxLatencies: number;
+
+  private readonly enabled: boolean;
+
+  private totalRequests = 0;
+
+  private inFlightRequests = 0;
+
+  private totalErrors = 0;
+
+  private totalTimeouts = 0;
+
+  constructor(
+    scheduler: Scheduler,
+    options: { maxLatencies?: number; enabled?: boolean } = {},
+    taskEngine?: TaskEngine,
+  ) {
+    this.scheduler = scheduler;
+    this.taskEngine = taskEngine;
+    this.maxLatencies = options.maxLatencies ?? 1000;
+    this.enabled = options.enabled ?? true;
+  }
+
+  onRequestStart(): void {
+    if (!this.enabled) {
+      return;
+    }
+    this.inFlightRequests += 1;
+  }
+
+  onRequestEnd(durationMs: number, statusCode: number): void {
+    if (!this.enabled) {
+      return;
+    }
+    this.totalRequests += 1;
+    if (this.inFlightRequests > 0) {
+      this.inFlightRequests -= 1;
+    }
+    if (statusCode >= 500) {
+      this.totalErrors += 1;
+    }
+    this.recordLatency(durationMs);
+  }
+
+  onTimeout(): void {
+    if (!this.enabled) {
+      return;
+    }
+    this.totalTimeouts += 1;
+  }
+
+  snapshot(): MetricsSnapshot {
+    const uptime = process.uptime();
+    const requestsPerSecond =
+      uptime > 0 ? this.totalRequests / uptime : this.totalRequests;
+
+    const latency = this.latencySnapshot();
+
+    const memoryUsage = process.memoryUsage();
+
+    let tasks: TaskMetrics | undefined;
+    if (this.taskEngine) {
+      tasks = this.taskEngine.getMetrics();
+    }
+
+    return {
+      totalRequests: this.totalRequests,
+      inFlightRequests: this.inFlightRequests,
+      totalErrors: this.totalErrors,
+      totalTimeouts: this.totalTimeouts,
+      requestsPerSecond,
+      latency,
+      scheduler: {
+        inFlight: this.scheduler.getCurrentInFlight(),
+      },
+      tasks,
+      memory: {
+        rssBytes: memoryUsage.rss,
+        heapUsedBytes: memoryUsage.heapUsed,
+      },
+    };
+  }
+
+  private recordLatency(durationMs: number): void {
+    if (!this.enabled) {
+      return;
+    }
+    if (!Number.isFinite(durationMs) || durationMs < 0) {
+      return;
+    }
+    this.latencies.push(durationMs);
+    if (this.latencies.length > this.maxLatencies) {
+      this.latencies.shift();
+    }
+  }
+
+  private latencySnapshot(): LatencySnapshot {
+    if (this.latencies.length === 0) {
+      return {
+        p50: null,
+        p95: null,
+        p99: null,
+      };
+    }
+
+    const sorted = [...this.latencies].sort((a, b) => a - b);
+
+    const p50 = this.percentile(sorted, 0.5);
+    const p95 = this.percentile(sorted, 0.95);
+    const p99 = this.percentile(sorted, 0.99);
+
+    return {
+      p50,
+      p95,
+      p99,
+    };
+  }
+
+  private percentile(sorted: number[], p: number): number {
+    if (sorted.length === 0) {
+      return 0;
+    }
+    if (p <= 0) {
+      return sorted[0];
+    }
+    if (p >= 1) {
+      return sorted[sorted.length - 1];
+    }
+    const index = Math.floor(p * (sorted.length - 1));
+    return sorted[index];
+  }
+}
+

package/src/core/resources.ts

@@ -0,0 +1,38 @@
+import os from 'os';
+
+export type WorkerSetting = 'auto' | number;
+
+export function calculateWorkerCount(setting: WorkerSetting): number {
+  if (typeof setting === 'number') {
+    if (!Number.isFinite(setting) || setting <= 0) {
+      return 1;
+    }
+    return Math.floor(setting);
+  }
+
+  const cpuCount = os.cpus().length || 1;
+  return Math.max(1, cpuCount);
+}
+
+export type ResourceThresholds = {
+  maxRssBytes?: number;
+};
+
+export type ResourceSample = {
+  rssBytes: number;
+};
+
+export function isResourceOverloaded(
+  sample: ResourceSample,
+  thresholds: ResourceThresholds,
+): boolean {
+  if (
+    thresholds.maxRssBytes !== undefined &&
+    sample.rssBytes > thresholds.maxRssBytes
+  ) {
+    return true;
+  }
+
+  return false;
+}
+

package/src/core/scheduler.ts

@@ -0,0 +1,126 @@
+import { WorkerQueue } from './worker-queue';
+import { RoutePriority } from './types';
+
+export type SchedulerOptions = {
+  maxConcurrency?: number;
+  workers?: number;
+};
+
+export type RunOptions = {
+  priority?: RoutePriority;
+  onOverloaded?: () => void;
+  timeoutMs?: number;
+  onTimeout?: () => void;
+};
+
+export type SchedulerStats = {
+  inFlight: number;
+  maxConcurrency: number;
+  workers: number;
+  perWorkerStats: {
+    workerId: number;
+    queued: number;
+  }[];
+};
+
+export class Scheduler {
+  private inFlight = 0;
+
+  private readonly maxConcurrency: number;
+
+  private readonly workerCount: number;
+
+  private readonly perWorkerQueues: WorkerQueue<() => void>[];
+
+  private nextWorkerIndex = 0;
+
+  constructor(options: SchedulerOptions = {}) {
+    const max = options.maxConcurrency ?? Infinity;
+    this.maxConcurrency = max > 0 ? max : Infinity;
+
+    // Initialize per-worker queues
+    this.workerCount = options.workers ?? 1;
+    this.perWorkerQueues = [];
+    for (let i = 0; i < this.workerCount; i += 1) {
+      this.perWorkerQueues.push(new WorkerQueue(1024));
+    }
+  }
+
+  getCurrentInFlight(): number {
+    return this.inFlight;
+  }
+
+  /**
+   * Get scheduler statistics (queued tasks per worker, etc.)
+   */
+  getStats(): SchedulerStats {
+    return {
+      inFlight: this.inFlight,
+      maxConcurrency: this.maxConcurrency,
+      workers: this.workerCount,
+      perWorkerStats: this.perWorkerQueues.map((q, i) => ({
+        workerId: i,
+        queued: q.getSize(),
+      })),
+    };
+  }
+
+  async run(
+    task: () => void | Promise<void>,
+    options: RunOptions,
+  ): Promise<void> {
+    const priority = options.priority ?? RoutePriority.STANDARD;
+
+    let threshold = this.maxConcurrency;
+    if (priority === RoutePriority.BEST_EFFORT) {
+      // Shed best-effort requests if we are above 80% capacity
+      threshold = Math.max(1, Math.floor(this.maxConcurrency * 0.8));
+    } else if (priority === RoutePriority.STANDARD) {
+      // Shed standard requests if we are above 95% capacity
+      threshold = Math.max(1, Math.floor(this.maxConcurrency * 0.95));
+    }
+    // CRITICAL allows up to 100%
+
+    if (this.inFlight >= threshold) {
+      if (options.onOverloaded) {
+        options.onOverloaded();
+      }
+      return;
+    }
+
+    this.inFlight += 1;
+
+    let timeoutId: NodeJS.Timeout | undefined;
+
+    try {
+      if (!options.timeoutMs || options.timeoutMs <= 0) {
+        const result = task();
+        if (result && typeof (result as Promise<void>).then === 'function') {
+          await result;
+        }
+        return;
+      }
+
+      const taskPromise = Promise.resolve(task()).then(() => 'ok' as const);
+
+      const timeoutPromise = new Promise<'timeout'>((resolve) => {
+        timeoutId = setTimeout(() => {
+          resolve('timeout');
+        }, options.timeoutMs);
+      });
+
+      const result = await Promise.race([taskPromise, timeoutPromise]);
+
+      if (result === 'timeout') {
+        if (options.onTimeout) {
+          options.onTimeout();
+        }
+      }
+    } finally {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      this.inFlight -= 1;
+    }
+  }
+}

package/src/core/scope.ts

@@ -0,0 +1,87 @@
+import { QHTTPX } from './server';
+import {
+  QHTTPXHandler,
+  QHTTPXRouteOptions,
+  QHTTPXMiddleware,
+  QHTTPXPlugin,
+  QHTTPXPluginOptions,
+} from './types';
+
+/**
+ * A Scope represents a prefixed or isolated context for plugins.
+ * It proxies methods to the main QHTTPX instance but handles prefixing.
+ */
+export class QHTTPXScope {
+  constructor(
+    private readonly app: QHTTPX,
+    private readonly prefix: string = ''
+  ) {}
+
+  /**
+   * Registers a sub-plugin within this scope.
+   * Prefixes are concatenated (e.g. /v1 + /users = /v1/users).
+   */
+  public async register<Options extends QHTTPXPluginOptions>(
+    plugin: QHTTPXPlugin<Options>,
+    options?: Options
+  ): Promise<void> {
+    const newPrefix = this.joinPaths(this.prefix, options?.prefix || '');
+    const scope = new QHTTPXScope(this.app, newPrefix);
+    await plugin(scope, options as Options);
+  }
+
+  public use(middleware: QHTTPXMiddleware): void {
+    // Middleware in scopes is currently global (TODO: Encapsulated middleware)
+    this.app.use(middleware);
+  }
+
+  public get(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void {
+    this.app._registerRoute('GET', this.joinPaths(this.prefix, path), handler);
+  }
+
+  public post(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void {
+    this.app._registerRoute('POST', this.joinPaths(this.prefix, path), handler);
+  }
+
+  public put(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void {
+    this.app._registerRoute('PUT', this.joinPaths(this.prefix, path), handler);
+  }
+
+  public delete(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void {
+    this.app._registerRoute('DELETE', this.joinPaths(this.prefix, path), handler);
+  }
+
+  public patch(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void {
+    this.app._registerRoute('PATCH', this.joinPaths(this.prefix, path), handler);
+  }
+
+  public options(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void {
+    this.app._registerRoute('OPTIONS', this.joinPaths(this.prefix, path), handler);
+  }
+
+  public head(path: string, handler: QHTTPXHandler | QHTTPXRouteOptions): void {
+    this.app._registerRoute('HEAD', this.joinPaths(this.prefix, path), handler);
+  }
+
+  // Helper to access the main app if needed
+  public getApp(): QHTTPX {
+    return this.app;
+  }
+
+  private joinPaths(head: string, tail: string): string {
+    if (!head) return tail;
+    if (!tail) return head;
+    
+    // Ensure clean slash joining
+    const headSlash = head.endsWith('/');
+    const tailSlash = tail.startsWith('/');
+
+    if (headSlash && tailSlash) {
+      return head + tail.slice(1);
+    }
+    if (!headSlash && !tailSlash) {
+      return head + '/' + tail;
+    }
+    return head + tail;
+  }
+}

package/src/core/serializer.ts

@@ -0,0 +1,41 @@
+import stringify from 'fast-json-stringify';
+
+// Cache of compiled stringifiers per schema
+const stringifierCache = new Map<string, (value: unknown) => string>();
+
+// Default fast JSON stringifier for generic objects
+const defaultStringifier = stringify({
+  type: 'object',
+  additionalProperties: true,
+} as Parameters<typeof stringify>[0]);
+
+/**
+ * Fast JSON serializer using fast-json-stringify
+ * For best performance, use schema-based stringifiers per route
+ */
+export function fastJsonStringify(value: unknown, schema?: unknown): string {
+  if (schema) {
+    const schemaKey = JSON.stringify(schema);
+    let stringifier = stringifierCache.get(schemaKey);
+    if (!stringifier) {
+      stringifier = stringify(schema as Parameters<typeof stringify>[0]);
+      stringifierCache.set(schemaKey, stringifier);
+    }
+    return stringifier(value);
+  }
+  return defaultStringifier(value as object);
+}
+
+/**
+ * Get a pre-compiled stringifier for a specific schema
+ * Use this in route handlers for maximum performance
+ */
+export function getStringifier(schema: unknown) {
+  const schemaKey = JSON.stringify(schema);
+  let stringifier = stringifierCache.get(schemaKey);
+  if (!stringifier) {
+    stringifier = stringify(schema as Parameters<typeof stringify>[0]);
+    stringifierCache.set(schemaKey, stringifier);
+  }
+  return stringifier;
+}