qhttpx 1.8.0

package/src/middleware/static.ts

@@ -0,0 +1,216 @@
+import fs from 'fs';
+import path from 'path';
+// import crypto from 'crypto';
+import { QHTTPXMiddleware } from '../core/types';
+
+export type StaticOptions = {
+  root: string;
+  index?: string;
+  fallthrough?: boolean;
+  etag?: boolean;
+  lastModified?: boolean;
+  maxAge?: number; // in seconds
+  immutable?: boolean;
+};
+
+function guessContentType(filePath: string): string {
+  const ext = path.extname(filePath).toLowerCase();
+  const types: Record<string, string> = {
+    '.html': 'text/html; charset=utf-8',
+    '.htm': 'text/html; charset=utf-8',
+    '.js': 'application/javascript; charset=utf-8',
+    '.mjs': 'application/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+    '.txt': 'text/plain; charset=utf-8',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav',
+    '.pdf': 'application/pdf',
+    '.zip': 'application/zip',
+  };
+  return types[ext] || 'application/octet-stream';
+}
+
+function generateETag(stat: fs.Stats): string {
+  const mtime = stat.mtimeMs.toString(16);
+  const size = stat.size.toString(16);
+  return `W/"${size}-${mtime}"`;
+}
+
+export function createStaticMiddleware(options: StaticOptions): QHTTPXMiddleware {
+  const root = path.resolve(options.root);
+  const indexFile = options.index ?? 'index.html';
+  const fallthrough = options.fallthrough ?? false;
+  const etag = options.etag ?? true;
+  const lastModified = options.lastModified ?? true;
+  const maxAge = options.maxAge ?? 0;
+  const immutable = options.immutable ?? 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('Allow', 'GET, HEAD');
+      ctx.res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+      ctx.res.end('Method Not Allowed');
+      return;
+    }
+
+    let requestPath = ctx.url.pathname || '/';
+    // Prevent directory traversal
+    requestPath = requestPath.replace(/^(\.\.(\/|\\|$))+/, '');
+    
+    // Normalize path
+    let safePath = path.normalize(requestPath);
+    if (safePath.startsWith('..')) safePath = '/'; // Extra safety
+    
+    // Handle root/directory requests
+    let filePath = path.join(root, safePath);
+
+    let stat: fs.Stats;
+    try {
+      stat = await fs.promises.stat(filePath);
+      if (stat.isDirectory()) {
+        filePath = path.join(filePath, indexFile);
+        stat = await fs.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;
+    }
+
+    // Caching Headers
+    if (maxAge > 0 || immutable) {
+      let cacheControl = `public, max-age=${maxAge}`;
+      if (immutable) cacheControl += ', immutable';
+      ctx.res.setHeader('Cache-Control', cacheControl);
+    }
+
+    if (lastModified) {
+      ctx.res.setHeader('Last-Modified', stat.mtime.toUTCString());
+    }
+
+    if (etag) {
+      const tag = generateETag(stat);
+      ctx.res.setHeader('ETag', tag);
+
+      // ETag Freshness Check
+      const ifNoneMatch = ctx.req.headers['if-none-match'];
+      if (ifNoneMatch === tag) {
+        ctx.res.statusCode = 304;
+        ctx.res.end();
+        return;
+      }
+    }
+
+    // Last-Modified Freshness Check
+    const ifModifiedSince = ctx.req.headers['if-modified-since'];
+    if (ifModifiedSince) {
+      const since = new Date(ifModifiedSince).getTime();
+      // Round down mtime to seconds for comparison
+      const mtime = Math.floor(stat.mtimeMs / 1000) * 1000;
+      if (mtime <= since) {
+        ctx.res.statusCode = 304;
+        ctx.res.end();
+        return;
+      }
+    }
+
+    const contentType = guessContentType(filePath);
+    ctx.res.setHeader('Content-Type', contentType);
+    ctx.res.setHeader('Accept-Ranges', 'bytes');
+
+    // Range Support
+    const range = ctx.req.headers['range'];
+            let start = 0;
+            let end = stat.size - 1;
+            // let isRange = false;
+
+            if (range) {
+      const parts = range.replace(/bytes=/, '').split('-');
+      const partialStart = parts[0];
+      const partialEnd = parts[1];
+
+      const parsedStart = parseInt(partialStart, 10);
+      const parsedEnd = partialEnd ? parseInt(partialEnd, 10) : end;
+
+      if (!isNaN(parsedStart) && !isNaN(parsedEnd) && parsedStart <= parsedEnd && parsedEnd < stat.size) {
+        start = parsedStart;
+                end = parsedEnd;
+                // isRange = true;
+                ctx.res.statusCode = 206;
+                ctx.res.setHeader('Content-Range', `bytes ${start}-${end}/${stat.size}`);
+        ctx.res.setHeader('Content-Length', end - start + 1);
+      } else {
+        // Invalid range
+        ctx.res.statusCode = 416;
+        ctx.res.setHeader('Content-Range', `bytes */${stat.size}`);
+        ctx.res.end();
+        return;
+      }
+    } else {
+      ctx.res.statusCode = 200;
+      ctx.res.setHeader('Content-Length', stat.size);
+    }
+
+    if (method === 'HEAD') {
+      ctx.res.end();
+      return;
+    }
+
+    const stream = fs.createReadStream(filePath, { start, end });
+    
+    // Disable auto-end if we are streaming?
+    // Actually, we can just pipe. But we need to make sure the server doesn't call res.end()
+    // The middleware architecture awaits next(), then server calls end().
+    // If we handle the response here, we should probably set a flag or just return without calling next() (which we do).
+    // But the server might still try to end it if we don't tell it we are done.
+    // In QHTTPX, if a handler returns, server checks `res.writableEnded`.
+    // Pipe calls end() by default.
+    
+    // We need to wait for the stream to finish before returning from middleware
+    // so that the server doesn't race.
+    
+    await new Promise<void>((resolve, reject) => {
+      stream.pipe(ctx.res);
+      stream.on('end', resolve);
+      stream.on('error', (err) => {
+        stream.destroy();
+        reject(err);
+      });
+      ctx.res.on('close', () => {
+        stream.destroy();
+        resolve();
+      });
+    });
+  };
+}

package/src/openapi/generator.ts

@@ -0,0 +1,167 @@
+import { RouteSchema, SimpleSchema } from '../validation/types';
+import { Router } from '../router/router';
+
+export type OpenAPIOptions = {
+  info: {
+    title: string;
+    version: string;
+    description?: string;
+  };
+  servers?: { url: string; description?: string }[];
+};
+
+export class OpenAPIGenerator {
+  constructor(private router: Router, private options: OpenAPIOptions) {}
+
+  generate(): object {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const paths: Record<string, any> = {};
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const schemas: Record<string, any> = {};
+
+    const methodMap = this.router.getRoutes();
+
+    for (const [method, routes] of methodMap.entries()) {
+      for (const route of routes) {
+        // Convert /users/:id to /users/{id}
+        const pathKey = route.path.replace(/:([a-zA-Z0-9_]+)/g, '{$1}');
+
+        if (!paths[pathKey]) {
+          paths[pathKey] = {};
+        }
+
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const operation: any = {
+          responses: {}
+        };
+
+        const schema = route.schema as RouteSchema | undefined;
+        if (schema) {
+          // Parameters (Query & Path)
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const parameters: any[] = [];
+          
+          // Path Params
+          // We can infer path params from the URL segments
+          const pathParams = route.path.match(/:([a-zA-Z0-9_]+)/g);
+          if (pathParams) {
+             pathParams.forEach(p => {
+                const name = p.substring(1);
+                // Check if we have specific schema for this param
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const paramSchema = (schema.params as any)?.properties?.[name];
+                parameters.push({
+                   name,
+                   in: 'path',
+                   required: true,
+                   schema: paramSchema ? this.convertSchema(paramSchema) : { type: 'string' }
+                });
+             });
+          }
+
+          // Query Params
+          if (schema.query) {
+             // eslint-disable-next-line @typescript-eslint/no-explicit-any
+             const queryProps = (schema.query as any).properties || {};
+             for (const [key, prop] of Object.entries(queryProps)) {
+                parameters.push({
+                   name: key,
+                   in: 'query',
+                   // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                   required: (schema.query as any).required !== false && (prop as any).required !== false, // simplified
+                   schema: this.convertSchema(prop as SimpleSchema)
+                });
+             }
+          }
+
+          if (parameters.length > 0) {
+            operation.parameters = parameters;
+          }
+
+          // Request Body
+          if (schema.body) {
+            operation.requestBody = {
+              content: {
+                'application/json': {
+                  schema: this.convertSchema(schema.body as SimpleSchema)
+                }
+              }
+            };
+          }
+
+          // Responses
+          // For now, default to 200 OK
+          operation.responses['200'] = {
+            description: 'Successful response',
+            content: {
+               'application/json': {
+                  schema: schema.response ? this.convertSchema(schema.response as SimpleSchema) : {}
+               }
+            }
+          };
+          
+          // 400 Bad Request if validation exists
+          if (schema.body || schema.query || schema.params) {
+             operation.responses['400'] = {
+                description: 'Validation Error'
+             };
+          }
+
+        } else {
+           // No schema, generic response
+           operation.responses['200'] = {
+              description: 'Successful response'
+           };
+        }
+
+        paths[pathKey][method.toLowerCase()] = operation;
+      }
+    }
+
+    return {
+      openapi: '3.0.0',
+      info: this.options.info,
+      servers: this.options.servers,
+      paths,
+      components: {
+        schemas
+      }
+    };
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private convertSchema(schema: SimpleSchema): any {
+     if (!schema) return {};
+     
+     // eslint-disable-next-line @typescript-eslint/no-explicit-any
+     const res: any = { type: schema.type };
+     
+     if (schema.properties) {
+        res.properties = {};
+        for (const [key, prop] of Object.entries(schema.properties)) {
+           res.properties[key] = this.convertSchema(prop);
+        }
+     }
+     
+     if (schema.items) {
+        res.items = this.convertSchema(schema.items);
+     }
+     
+     if (schema.min !== undefined) {
+        if (schema.type === 'string') res.minLength = schema.min;
+        if (schema.type === 'number') res.minimum = schema.min;
+        if (schema.type === 'array') res.minItems = schema.min;
+     }
+     
+     if (schema.max !== undefined) {
+        if (schema.type === 'string') res.maxLength = schema.max;
+        if (schema.type === 'number') res.maximum = schema.max;
+        if (schema.type === 'array') res.maxItems = schema.max;
+     }
+     
+     if (schema.pattern) res.pattern = schema.pattern;
+     if (schema.enum) res.enum = schema.enum;
+     
+     return res;
+  }
+}

package/src/router/radix-router.ts

@@ -0,0 +1,119 @@
+/**
+ * Radix tree router compiled into a flat array structure for zero-allocation matching.
+ * Built once at server startup (frozen).
+ */
+
+import { HTTPMethod, QHTTPXHandler } from '../core/types';
+
+type RadixNode = {
+  charCode?: number; // Single char to match
+  prefix?: string; // Static path prefix
+  children?: Map<string | number, RadixNode>; // char/paramKey -> child
+  handler?: QHTTPXHandler;
+  paramKey?: string; // For :param routes
+};
+
+export type CompiledRadixMatch = {
+  handler: QHTTPXHandler;
+  params: Record<string, string>;
+};
+
+export class RadixRouter {
+  private roots: Map<HTTPMethod, RadixNode> = new Map();
+  private isFrozen = false;
+
+  register(method: HTTPMethod, path: string, handler: QHTTPXHandler): void {
+    if (this.isFrozen) {
+      console.warn(`Radix router is frozen. Late route registration (${method} ${path}) may not be optimized.`);
+    }
+
+    if (!this.roots.has(method)) {
+      this.roots.set(method, {});
+    }
+
+    const root = this.roots.get(method)!;
+    const segments = this.normalize(path);
+
+    let node = root;
+    for (const segment of segments) {
+      if (!node.children) {
+        node.children = new Map();
+      }
+
+      const isParam = segment.startsWith(':');
+      const key = isParam ? segment.slice(1) : segment;
+
+      if (!node.children.has(key)) {
+        node.children.set(key, {
+          paramKey: isParam ? key : undefined,
+        });
+      }
+
+      node = node.children.get(key)!;
+    }
+
+    node.handler = handler;
+  }
+
+  match(method: HTTPMethod, path: string): CompiledRadixMatch | undefined {
+    const root = this.roots.get(method);
+    if (!root) {
+      return undefined;
+    }
+
+    const segments = this.normalize(path);
+    const params: Record<string, string> = {};
+
+    let node = root;
+    for (const segment of segments) {
+      if (!node.children) {
+        return undefined;
+      }
+
+      // Try exact match first
+      let child = node.children.get(segment);
+
+      // If no exact match, try param match
+      if (!child) {
+        for (const [key, candidate] of node.children.entries()) {
+          if (candidate.paramKey && typeof key === 'string') {
+            params[key] = segment;
+            child = candidate;
+            break;
+          }
+        }
+      }
+
+      if (!child) {
+        return undefined;
+      }
+
+      node = child;
+    }
+
+    if (!node.handler) {
+      return undefined;
+    }
+
+    return { handler: node.handler, params };
+  }
+
+  freeze(): void {
+    if (this.isFrozen) {
+      return;
+    }
+    this.isFrozen = true;
+    // Future: compile to flat array structure here
+  }
+
+  isFrozenRouter(): boolean {
+    return this.isFrozen;
+  }
+
+  private normalize(path: string): string[] {
+    if (!path || path === '/') {
+      return [];
+    }
+    return path.split('/').filter((segment) => segment.length > 0);
+  }
+}

package/src/router/radix-tree.ts

@@ -0,0 +1,106 @@
+import { QHTTPXHandler, RoutePriority } from '../core/types';
+
+export type RouteData = {
+  handler: QHTTPXHandler;
+  priority: RoutePriority;
+};
+
+class Node {
+  // Map segment -> Node
+  children: Map<string, Node> = new Map();
+  // Parameter child node (only one allowed per level for simplicity)
+  paramChild: Node | null = null;
+  paramName: string | null = null;
+
+  // Data if this node is a route end
+  data: RouteData | null = null;
+}
+
+export type MatchResult = {
+  handler: QHTTPXHandler;
+  priority: RoutePriority;
+  params: Record<string, string>;
+};
+
+export class RadixTree {
+  private root: Node = new Node();
+
+  insert(
+    segments: string[],
+    handler: QHTTPXHandler,
+    priority: RoutePriority,
+  ): void {
+    let node = this.root;
+
+    for (const segment of segments) {
+      if (segment.startsWith(':')) {
+        const paramName = segment.slice(1);
+        if (!node.paramChild) {
+          node.paramChild = new Node();
+          node.paramChild.paramName = paramName;
+        } else if (node.paramChild.paramName !== paramName) {
+          throw new Error(
+            `Cannot have two different parameter names at the same level: "${node.paramChild.paramName}" and "${paramName}"`,
+          );
+        }
+        node = node.paramChild;
+      } else {
+        if (!node.children.has(segment)) {
+          node.children.set(segment, new Node());
+        }
+        node = node.children.get(segment)!;
+      }
+    }
+
+    node.data = { handler, priority };
+  }
+
+  lookup(segments: string[]): MatchResult | null {
+    // Use a stack-based approach or recursion. 
+    // For simplicity and correctness with backtracking, we'll use recursion.
+    // To minimize allocations, we pass the same params object and only copy on success?
+    // Actually, creating a params object is inevitable for the result.
+    
+    return this.find(this.root, segments, 0);
+  }
+
+  private find(
+    node: Node,
+    segments: string[],
+    index: number,
+  ): MatchResult | null {
+    if (index === segments.length) {
+      if (node.data) {
+        return {
+          handler: node.data.handler,
+          priority: node.data.priority,
+          params: {},
+        };
+      }
+      return null;
+    }
+
+    const segment = segments[index];
+
+    // 1. Try exact match
+    const child = node.children.get(segment);
+    if (child) {
+      const result = this.find(child, segments, index + 1);
+      if (result) {
+        return result;
+      }
+    }
+
+    // 2. Try param match
+    if (node.paramChild) {
+      const result = this.find(node.paramChild, segments, index + 1);
+      if (result) {
+        // If match found down this path, add current param to it
+        result.params[node.paramChild.paramName!] = segment;
+        return result;
+      }
+    }
+
+    return null;
+  }
+}