qhttpx 1.8.0

package/src/router/router.ts

@@ -0,0 +1,190 @@
+import { RadixTree } from './radix-tree';
+import { HTTPMethod, QHTTPXHandler, RouteOptions, RoutePriority } from '../core/types';
+import { RouteSchema } from '../validation/types';
+
+type RouteDefinition = {
+  path: string;
+  segments: string[];
+  handler: QHTTPXHandler;
+  priority: RoutePriority;
+  schema?: RouteSchema | Record<string, unknown>;
+};
+
+export type RouteMatch = {
+  handler: QHTTPXHandler;
+  params: Record<string, string>;
+  priority: RoutePriority;
+};
+
+export class Router {
+  // Per-method route buckets
+  private readonly methodBuckets: Map<HTTPMethod, RouteDefinition[]> = new Map([
+    ['GET', []],
+    ['POST', []],
+    ['PUT', []],
+    ['DELETE', []],
+    ['PATCH', []],
+    ['HEAD', []],
+    ['OPTIONS', []],
+  ]);
+
+  // Derived structures (built at freeze time)
+  private readonly radixTrees: Map<HTTPMethod, RadixTree> = new Map();
+
+  // Freeze state
+  private isFrozen = false;
+
+  register(
+    method: HTTPMethod,
+    path: string,
+    handler: QHTTPXHandler,
+    options?: RouteOptions & { schema?: RouteSchema | Record<string, unknown> },
+  ): void {
+    if (this.isFrozen) {
+      console.warn(
+        `Router is frozen. Late route registration (${method} ${path}) may not be optimized.`,
+      );
+    }
+
+    const segments = this.normalize(path);
+    const bucket = this.methodBuckets.get(method);
+    if (bucket) {
+      bucket.push({
+        path,
+        segments,
+        handler,
+        priority: options?.priority ?? RoutePriority.STANDARD,
+        schema: options?.schema,
+      });
+    }
+  }
+
+  getRoutes(): Map<HTTPMethod, RouteDefinition[]> {
+    return this.methodBuckets;
+  }
+
+  match(method: HTTPMethod, path: string): RouteMatch | undefined {
+    // Fast path for frozen router
+    if (this.isFrozen) {
+      const tree = this.radixTrees.get(method);
+      if (tree) {
+        const segments = this.normalize(path);
+        const match = tree.lookup(segments);
+        if (match) {
+          return match;
+        }
+      }
+      return undefined;
+    }
+
+    // Slow path for unfrozen router (legacy behavior)
+    const segments = this.normalize(path);
+    const bucket = this.methodBuckets.get(method);
+
+    if (!bucket || bucket.length === 0) {
+      return undefined;
+    }
+
+    // Try to match against routes
+    for (const route of bucket) {
+      if (route.segments.length !== segments.length) {
+        continue;
+      }
+
+      const params: Record<string, string> = {};
+      let matched = true;
+
+      for (let i = 0; i < route.segments.length; i += 1) {
+        const pattern = route.segments[i];
+        const value = segments[i];
+
+        if (pattern.startsWith(':')) {
+          const key = pattern.slice(1);
+          params[key] = value;
+        } else if (pattern !== value) {
+          matched = false;
+          break;
+        }
+      }
+
+      if (matched) {
+        return {
+          handler: route.handler,
+          params,
+          priority: route.priority,
+        };
+      }
+    }
+
+    return undefined;
+  }
+
+  getAllowedMethods(path: string): HTTPMethod[] {
+    const segments = this.normalize(path);
+    const methods: HTTPMethod[] = [];
+
+    for (const [method, routes] of this.methodBuckets.entries()) {
+      for (const route of routes) {
+        if (route.segments.length !== segments.length) {
+          continue;
+        }
+
+        let matched = true;
+        for (let i = 0; i < route.segments.length; i += 1) {
+          const pattern = route.segments[i];
+          const value = segments[i];
+
+          if (pattern.startsWith(':')) {
+            continue;
+          }
+
+          if (pattern !== value) {
+            matched = false;
+            break;
+          }
+        }
+
+        if (matched) {
+          methods.push(method);
+          break;
+        }
+      }
+    }
+
+    return methods;
+  }
+
+  /**
+   * Freeze the router after server starts.
+   * Prevents further route registration and builds derived structures for optimized matching.
+   */
+  freeze(): void {
+    if (this.isFrozen) {
+      return;
+    }
+
+    this.isFrozen = true;
+
+    // Build derived structures for faster matching
+    for (const [method, routes] of this.methodBuckets.entries()) {
+      const tree = new RadixTree();
+
+      for (const route of routes) {
+        tree.insert(route.segments, route.handler, route.priority);
+      }
+
+      this.radixTrees.set(method, tree);
+    }
+  }
+
+  isFrozenRouter(): boolean {
+    return this.isFrozen;
+  }
+
+  private normalize(path: string): string[] {
+    if (!path || path === '/') {
+      return [];
+    }
+    return path.split('/').filter((segment) => segment.length > 0);
+  }
+}

package/src/testing/index.ts

@@ -0,0 +1,104 @@
+import { QHTTPX } from '../core/server';
+import { HTTPMethod } from '../core/types';
+
+export class TestClient {
+  private app: QHTTPX;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private server: any = null;
+  private baseURL: string = '';
+
+  constructor(app: QHTTPX) {
+    this.app = app;
+  }
+
+  /**
+   * Starts the server on a random port.
+   * Automatically called by request methods if not started.
+   */
+  async start(): Promise<void> {
+    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(): Promise<void> {
+    if (this.server) {
+      await this.app.close();
+      this.server = null;
+    }
+  }
+
+  async request(
+    method: HTTPMethod,
+    path: string,
+    options: {
+      headers?: Record<string, string>;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      body?: any;
+      query?: Record<string, string | number | boolean>;
+    } = {}
+  ): Promise<Response> {
+    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: Record<string, string> = options.headers || {};
+    let bodyPayload: BodyInit | undefined;
+
+    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 as BodyInit;
+      }
+    }
+
+    return fetch(url, {
+      method,
+      headers,
+      body: bodyPayload,
+    });
+  }
+
+  get(path: string, options?: Omit<Parameters<TestClient['request']>[2], 'body'>) {
+    return this.request('GET', path, options);
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  post(path: string, body?: any, options?: Omit<Parameters<TestClient['request']>[2], 'body'>) {
+    return this.request('POST', path, { ...options, body });
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  put(path: string, body?: any, options?: Omit<Parameters<TestClient['request']>[2], 'body'>) {
+    return this.request('PUT', path, { ...options, body });
+  }
+
+  delete(path: string, options?: Omit<Parameters<TestClient['request']>[2], 'body'>) {
+    return this.request('DELETE', path, options);
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  patch(path: string, body?: any, options?: Omit<Parameters<TestClient['request']>[2], 'body'>) {
+    return this.request('PATCH', path, { ...options, body });
+  }
+}
+
+export function createTestClient(app: QHTTPX) {
+  return new TestClient(app);
+}

package/src/utils/cookies.ts

@@ -0,0 +1,67 @@
+import { CookieOptions } from '../core/types';
+
+export function parseCookies(header: string | undefined): Record<string, string> {
+  const list: Record<string, string> = {};
+  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;
+}
+
+export function serializeCookie(name: string, value: string, options: CookieOptions = {}): string {
+  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/src/utils/logger.ts

@@ -0,0 +1,59 @@
+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 function createLoggerMiddleware(
+  options: LoggerOptions = {},
+): QHTTPXMiddleware {
+  const sink =
+    options.sink ??
+    ((entry: LogEntry) => {
+      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/src/utils/signals.ts

@@ -0,0 +1,45 @@
+import { QHTTPX } from '../core/server';
+
+export type SignalHandlerOptions = {
+  signals?: NodeJS.Signals[];
+  timeoutMs?: number;
+};
+
+export function attachSignalHandlers(
+  app: QHTTPX,
+  options: SignalHandlerOptions = {},
+): void {
+  const signals = options.signals ?? ['SIGINT', 'SIGTERM'];
+  const timeoutMs = options.timeoutMs ?? 10000;
+
+  let shuttingDown = false;
+
+  const handler = async (signal: NodeJS.Signals) => {
+    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/src/utils/sse.ts

@@ -0,0 +1,41 @@
+import { QHTTPXContext } from '../core/types';
+
+export interface SSEStream {
+  send(data: unknown, event?: string, id?: string): void;
+  close(): void;
+}
+
+export function createSSE(ctx: QHTTPXContext): SSEStream {
+  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: unknown, event?: string, id?: string) => {
+    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 };
+}

package/src/validation/index.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './simple';
+export * from './zod';

package/src/validation/simple.ts

@@ -0,0 +1,93 @@
+import { SimpleSchema, Validator, ValidationResult, ValidationError } from './types';
+
+export class SimpleValidator implements Validator {
+  validate(schema: unknown, data: unknown): ValidationResult {
+     try {
+       // If schema is not a SimpleSchema object, we can't validate it with this validator
+       // But for simplicity, we assume the user passes a valid SimpleSchema if they use this validator.
+       const validData = this.check(schema as SimpleSchema, data);
+       return { success: true, data: validData };
+     } catch (err) {
+       return { 
+         success: false, 
+         // eslint-disable-next-line @typescript-eslint/no-explicit-any
+         error: new ValidationError((err as any).message || 'Validation failed') 
+       };
+     }
+   }
+
+   // eslint-disable-next-line @typescript-eslint/no-explicit-any
+   private check(schema: SimpleSchema, data: unknown, path: string = ''): any {
+    if (schema.required !== false && (data === undefined || data === null)) {
+      throw new Error(`Field '${path}' is required`);
+    }
+
+    if (data === undefined || data === null) {
+      return data;
+    }
+
+    switch (schema.type) {
+      case 'string':
+        if (typeof data !== 'string') throw new Error(`Field '${path}' must be a string`);
+        if (schema.min !== undefined && data.length < schema.min) throw new Error(`Field '${path}' too short (min ${schema.min})`);
+        if (schema.max !== undefined && data.length > schema.max) throw new Error(`Field '${path}' too long (max ${schema.max})`);
+        if (schema.pattern && !new RegExp(schema.pattern).test(data)) throw new Error(`Field '${path}' format invalid`);
+        if (schema.enum && !schema.enum.includes(data)) throw new Error(`Field '${path}' must be one of [${schema.enum.join(', ')}]`);
+        return data;
+
+      case 'number':
+        // Try to coerce if it's a string looking like a number (useful for query params)
+        let num = data;
+        if (typeof data === 'string' && !isNaN(Number(data))) {
+          num = Number(data);
+        }
+        
+        if (typeof num !== 'number' || isNaN(num as number)) throw new Error(`Field '${path}' must be a number`);
+        if (schema.min !== undefined && (num as number) < schema.min) throw new Error(`Field '${path}' too small (min ${schema.min})`);
+        if (schema.max !== undefined && (num as number) > schema.max) throw new Error(`Field '${path}' too large (max ${schema.max})`);
+        if (schema.enum && !schema.enum.includes(num as number)) throw new Error(`Field '${path}' must be one of [${schema.enum.join(', ')}]`);
+        return num;
+
+      case 'boolean':
+        if (typeof data === 'boolean') return data;
+        if (data === 'true') return true;
+        if (data === 'false') return false;
+        throw new Error(`Field '${path}' must be a boolean`);
+
+      case 'array':
+        if (!Array.isArray(data)) throw new Error(`Field '${path}' must be an array`);
+        if (schema.min !== undefined && data.length < schema.min) throw new Error(`Field '${path}' too few items (min ${schema.min})`);
+        if (schema.max !== undefined && data.length > schema.max) throw new Error(`Field '${path}' too many items (max ${schema.max})`);
+        if (schema.items) {
+          return data.map((item, i) => this.check(schema.items!, item, `${path}[${i}]`));
+        }
+        return data;
+
+      case 'object':
+        if (typeof data !== 'object' || Array.isArray(data)) throw new Error(`Field '${path}' must be an object`);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const result: any = {};
+        const props = schema.properties || {};
+        
+        // Check known properties
+        for (const key in props) {
+          const propSchema = props[key];
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const propValue = (data as any)[key];
+          result[key] = this.check(propSchema, propValue, path ? `${path}.${key}` : key);
+        }
+
+        // Pass through unknown properties? 
+        // For strictness, maybe we should strip them?
+        // Let's keep unknown properties for now to be safe, or make it configurable.
+        // For now: Only keep validated properties if properties are defined.
+        if (Object.keys(props).length > 0) {
+           return result;
+        }
+        return data;
+        
+      default:
+        return data;
+    }
+  }
+}

package/src/validation/types.ts

@@ -0,0 +1,38 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ValidationResult<T = any> = 
+   | { success: true; data: T }
+   | { success: false; error: ValidationError };
+
+export class ValidationError extends Error {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  constructor(public details: any) {
+    super('Validation Error');
+    this.name = 'ValidationError';
+  }
+}
+
+export interface Validator {
+  validate(schema: unknown, data: unknown): Promise<ValidationResult> | ValidationResult;
+}
+
+export type RouteSchema = {
+  body?: unknown;
+  query?: unknown;
+  params?: unknown;
+  headers?: unknown;
+  response?: unknown;
+};
+
+// Simple Schema Types for the built-in validator
+export type SimpleType = 'string' | 'number' | 'boolean' | 'object' | 'array';
+
+export interface SimpleSchema {
+  type: SimpleType;
+  required?: boolean; // default true
+  properties?: Record<string, SimpleSchema>; // for object
+  items?: SimpleSchema; // for array
+  min?: number; // min length or value
+  max?: number; // max length or value
+  pattern?: string; // regex for string
+  enum?: (string | number)[];
+}

package/src/validation/zod.ts

@@ -0,0 +1,14 @@
+import { Validator, ValidationResult, ValidationError } from './types';
+
+export class ZodValidator implements Validator {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async validate<T = any>(schema: unknown, data: unknown): Promise<ValidationResult<T>> {
+    try {
+      const zodSchema = schema as { parseAsync: (data: unknown) => Promise<T> };
+      const result = await zodSchema.parseAsync(data);
+      return { success: true, data: result };
+    } catch (error) {
+      return { success: false, error: new ValidationError(error) };
+    }
+  }
+}

package/src/views/index.ts

@@ -0,0 +1 @@
+export * from './types';

package/src/views/types.ts

@@ -0,0 +1,4 @@
+export interface ViewEngine {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  render(path: string, locals: Record<string, any>): Promise<string> | string;
+}