qhttpx 1.8.5 → 1.8.11

package/docs/AEGIS.md

@@ -12,7 +12,25 @@
 
 ## Usage
 
-Import `rateLimit` from the middleware package:
+### Zero-Config (Recommended)
+
+The easiest way to enable Aegis is via the `createHttpApp` factory:
+
+```typescript
+import { createHttpApp } from 'qhttpx';
+
+const app = createHttpApp({
+  rateLimit: {
+    windowMs: 60 * 1000, // 1 minute
+    max: 100,            // Limit each IP to 100 requests per window
+    trustProxy: true     // Enable if behind Nginx/Cloudflare
+  }
+});
+```
+
+### Manual Middleware
+
+For more control, import `rateLimit` from the middleware package:
 
 ```typescript
 import { QHTTPX } from 'qhttpx';
@@ -26,17 +44,24 @@ app.use(rateLimit({
   max: 100, // Limit each IP to 100 requests per window
   message: { error: 'Too many requests, slow down!' }
 }));
+```
 
-// 2. API Key Limits (Tiered)
-app.use(rateLimit({
-  windowMs: 60 * 60 * 1000, // 1 hour
-  max: 5000,
-  keyGenerator: (ctx) => ctx.req.headers['x-api-key'] || ctx.req.socket.remoteAddress
-}));
+## Proxy Support
+
+If your app sits behind a reverse proxy (Nginx, AWS ALB, Cloudflare), you must configure **Proxy Trust** so Aegis sees the real user IP instead of the load balancer's IP.
 
-app.get('/', (ctx) => ctx.json({ message: 'Welcome!' }));
+```typescript
+// In createHttpApp
+const app = createHttpApp({
+  rateLimit: {
+    trustProxy: true // Trusts X-Forwarded-For header
+  }
+});
 
-app.listen(3000);
+// Or manually
+app.use(rateLimit({
+  trustProxy: true
+}));
 ```
 
 ## Options

package/docs/BENCHMARKS.md

@@ -23,14 +23,15 @@ This will:
 - Run an `autocannon` benchmark against `GET /json`
 - Shut down the server when the run completes
 
-## Scenario
+## Latest Results (Local Windows Environment)
 
-The current scenario measures:
+Configuration: 100 connections, 10 pipelining, 40s duration (Average of 2 runs, taking the second result)
 
-- Simple JSON endpoint: `GET /json`
-- Connections: 100
-- Pipelining: 10
-- Duration: 10 seconds
+| Framework | Req/Sec | Latency (Avg) | Throughput |
+| :--- | :--- | :--- | :--- |
+| **Fastify** | 16,050 | 256.78 ms | 3.00 Mb/s |
+| **QHTTPX** | **14,179** | **291.13 ms** | **3.02 Mb/s** |
+| **Hono** | 14,176 | 294.09 ms | 2.43 Mb/s |
+| **Express** | 10,450 | 407.12 ms | 1.94 Mb/s |
 
-You can adjust these parameters in `src/benchmarks/simple-json.ts`.
 

package/docs/ERRORS.md

@@ -0,0 +1,112 @@
+# Error Handling
+
+QHTTPX provides a robust and unified error handling system designed to make building reliable APIs simple and consistent.
+
+## Standard Exceptions
+
+Gone are the days of manually setting status codes and message strings. QHTTPX exports a set of **Standard HTTP Exceptions** that cover most common API scenarios.
+
+These exceptions automatically set the correct HTTP status code and structure the JSON response.
+
+### Available Exceptions
+
+Import them directly from `qhttpx`:
+
+```typescript
+import { 
+  BadRequestException, 
+  UnauthorizedException, 
+  ForbiddenException, 
+  NotFoundException, 
+  MethodNotAllowedException, 
+  ConflictException, 
+  PayloadTooLargeException, 
+  UnsupportedMediaTypeException, 
+  TooManyRequestsException, 
+  InternalServerErrorException, 
+  ServiceUnavailableException 
+} from 'qhttpx';
+```
+
+### Usage in Routes
+
+Simply `throw` an exception within your handler. QHTTPX will catch it and format the response.
+
+```typescript
+app.get('/users/:id', ({ params }) => {
+  const user = findUser(params.id);
+  
+  if (!user) {
+    throw new NotFoundException(`User with ID ${params.id} not found`);
+  }
+  
+  if (user.isLocked) {
+    throw new ForbiddenException('This account is locked');
+  }
+  
+  return user;
+});
+```
+
+**Response Example (`NotFoundException`):**
+```json
+{
+  "error": "Not Found",
+  "code": "NOT_FOUND",
+  "details": "User with ID 123 not found",
+  "statusCode": 404
+}
+```
+
+## Global Error Handler
+
+You can define a global error handler to intercept all errors (both standard exceptions and unexpected runtime errors) to customize logging or response formatting.
+
+Use `app.onError()`:
+
+```typescript
+app.onError(({ error, json }) => {
+  console.error('Captured Error:', error);
+
+  // Check if it's a known HTTP error
+  if (error instanceof HttpError) {
+    return json({
+      status: 'error',
+      message: error.message,
+      code: error.code
+    }, error.statusCode);
+  }
+
+  // Handle unknown/unexpected errors
+  return json({
+    status: 'critical',
+    message: 'Internal Server Error'
+  }, 500);
+});
+```
+
+## Async Error Handling
+
+QHTTPX handles `async` errors automatically. You don't need `try/catch` blocks for every route unless you want specific local handling. If an async function rejects, the Global Error Handler will catch it.
+
+```typescript
+// This works automatically!
+app.get('/db-query', async () => {
+  const data = await db.query('SELECT * FROM users'); // If this throws, it's caught.
+  return data;
+});
+```
+
+## Validation Errors
+
+When using the built-in validation system, validation failures automatically throw a `BadRequestException` containing detailed error messages about which fields failed.
+
+```json
+{
+  "error": "Bad Request",
+  "code": "BAD_REQUEST",
+  "details": [
+    { "field": "email", "message": "Invalid email format" }
+  ]
+}
+```

package/docs/FUSION.md

@@ -0,0 +1,68 @@
+# Request Fusion Engine (Layer 2 Coalescing)
+
+**Request Fusion** is QHTTPX's flagship performance feature. It is a "Layer 2 Coalescing" engine designed to protect your database and downstream services from the "Thundering Herd" problem.
+
+## The Problem: The Thundering Herd
+
+Imagine your API serves a popular resource, like "Trending News" (`GET /api/trending`).
+During a viral event, you might receive **10,000 requests per second** for this *exact same resource*.
+
+In traditional frameworks (Express/Fastify):
+1. Node.js accepts 10,000 requests.
+2. The handler runs 10,000 times.
+3. Your database receives 10,000 identical queries.
+4. **Result**: Database CPU spikes to 100%, latency skyrockets, and the site crashes.
+
+## The Solution: Request Fusion
+
+With Request Fusion enabled, QHTTPX acts intelligently:
+
+1. **Request 1** arrives: QHTTPX marks it as the **Leader** and starts processing (querying the DB).
+2. **Requests 2 through 10,000** arrive *while Request 1 is still processing*.
+3. QHTTPX identifies them as **Followers** (identical semantic fingerprint).
+4. These requests **wait** for the Leader. They do *not* execute the handler.
+5. **Leader finishes**: The result is broadcast to all 9,999 Followers instantly.
+
+**Result**: 
+- **1** Database Query.
+- **10,000** Happy Users.
+- **Zero** Database Load.
+
+## Enabling Fusion
+
+Request Fusion is optional but recommended for read-heavy public APIs.
+
+### Using `createHttpApp` (Zero-Config)
+
+```typescript
+const app = createHttpApp({
+  enableRequestFusion: true
+});
+```
+
+### Manual Configuration
+
+```typescript
+const app = new QHTTPX({
+  enableRequestFusion: true
+});
+```
+
+## Semantic Hashing
+
+How does QHTTPX know requests are identical? It generates a **Semantic Key** based on:
+
+1. **HTTP Method** (e.g., `GET`)
+2. **URL Path** (e.g., `/api/trending`)
+3. **Query Parameters** (sorted) (e.g., `?category=tech&page=1`)
+4. **Request Body** (if JSON)
+5. **Vary Headers** (Configurable, e.g., `Accept-Language`)
+
+## Micro-TTL
+
+For even higher performance, Fusion includes a "Micro-TTL" mechanism. Even after a request finishes, the result can be held for a tiny window (e.g., 100ms) to satisfy immediately subsequent requests, acting as an ultra-short-term cache for burst traffic.
+
+## Best Practices
+
+- **Idempotency**: Fusion is safest for `GET` requests. QHTTPX automatically disables Fusion for `POST`, `PUT`, `DELETE`, and `PATCH` by default to prevent side-effect duplication issues, though this can be overridden if you know what you are doing.
+- **Personalized Content**: Be careful with endpoints that return user-specific data (like "My Profile"). If the response depends on the `Authorization` header, ensure that header is part of the Fusion Key (or disable Fusion for that route).

package/docs/MIDDLEWARE.md

@@ -0,0 +1,65 @@
+# Middleware
+
+Middleware in QHTTPX functions similarly to Express or Koa but is optimized for the async scheduler. It allows you to execute code before or after the route handler.
+
+## Global Middleware
+
+Register middleware using `app.use()`. It applies to all routes registered *after* it.
+
+```typescript
+app.use(async (ctx, next) => {
+  const start = Date.now();
+  
+  await next(); // Wait for downstream middleware/handler
+  
+  const ms = Date.now() - start;
+  ctx.res.setHeader('X-Response-Time', `${ms}ms`);
+});
+```
+
+## Destructuring Syntax
+
+You can destructure the context arguments for cleaner code:
+
+```typescript
+app.use(async ({ req, res }, next) => {
+  console.log(`${req.method} ${req.url}`);
+  await next();
+});
+```
+
+## Built-in Middleware
+
+QHTTPX comes with essential middleware optimized for its core.
+
+### Rate Limiting (Aegis)
+
+See [Aegis Documentation](./AEGIS.md).
+
+### CORS
+
+Enabled via `createHttpApp` or manually.
+
+```typescript
+const app = createHttpApp({ cors: true });
+```
+
+### Compression
+
+Automatically compresses responses using Gzip/Brotli.
+
+```typescript
+const app = createHttpApp({ compression: true });
+```
+
+### Body Parser
+
+The body parser is **built-in** and lazy-loaded. You do not need to `app.use(bodyParser())`.
+Just access `ctx.body` and it will be parsed on demand.
+
+```typescript
+app.post('/data', ({ body }) => {
+  // body is already parsed (JSON/URL-encoded)
+  return { received: body };
+});
+```

package/docs/ROUTING.md

@@ -0,0 +1,70 @@
+# Routing
+
+QHTTPX employs a high-performance **Radix Tree** (prefix tree) router. This data structure allows for `O(k)` route lookup time (where `k` is the length of the URL), making it significantly faster than the linear regex matching used by Express or Koa.
+
+## Basic Routing
+
+Supported methods: `get`, `post`, `put`, `delete`, `patch`, `options`, `head`.
+
+```typescript
+app.get('/', (ctx) => {
+  return ctx.json({ hello: 'world' });
+});
+
+app.post('/items', (ctx) => {
+  // ...
+});
+```
+
+## Route Parameters
+
+Capture dynamic segments of the URL using colons (`:`).
+
+```typescript
+app.get('/users/:id', (ctx) => {
+  const { id } = ctx.params;
+  return ctx.json({ userId: id });
+});
+
+// Multiple parameters
+app.get('/posts/:year/:month/:slug', (ctx) => {
+  const { year, month, slug } = ctx.params;
+  // ...
+});
+```
+
+## Wildcards
+
+Match everything following a path using `*`.
+
+```typescript
+// Matches /files/image.png, /files/docs/report.pdf, etc.
+app.get('/files/*', (ctx) => {
+  const path = ctx.params['*']; // "image.png"
+  // ...
+});
+```
+
+## Route Destructuring
+
+The handler context can be destructured for cleaner code:
+
+```typescript
+app.get('/search', ({ query, json }) => {
+  const { q } = query;
+  return json({ results: performSearch(q) });
+});
+```
+
+## Scoped Routes (Groups)
+
+Use plugins to create route groups with prefixes (similar to `express.Router` or Fastify encapsulation).
+
+```typescript
+const apiV1 = async (app: QHTTPX, opts: any) => {
+  app.get('/users', () => { ... }); // Becomes /api/v1/users
+  app.get('/posts', () => { ... }); // Becomes /api/v1/posts
+};
+
+app.register(apiV1, { prefix: '/api/v1' });
+```

package/docs/STATIC.md

@@ -0,0 +1,61 @@
+# Static Files & Streaming
+
+QHTTPX includes a high-performance static file server capable of handling media streaming (video/audio) and partial content requests out of the box.
+
+## Basic Usage
+
+To serve static files (like images, CSS, JS) from a directory:
+
+```typescript
+import path from 'path';
+
+// Serve files from the 'public' folder at the root URL
+app.static('/', path.join(__dirname, 'public'));
+
+// Serve files from 'assets' under the '/static' prefix
+app.static('/static', path.join(__dirname, 'assets'));
+```
+
+## Features
+
+### 1. Range Requests (Video Streaming)
+
+The static handler automatically supports `Range` headers (HTTP 206 Partial Content). This means you can serve video files directly to browsers, and users can seek (jump) to different parts of the video without downloading the whole file.
+
+### 2. Smart Caching
+
+It automatically handles:
+- `Last-Modified` headers.
+- `ETag` generation.
+- `304 Not Modified` responses to save bandwidth.
+
+### 3. Streaming (Low Memory)
+
+Files are streamed to the response using Node.js streams. This ensures that serving a large file (e.g., 1GB video) does not spike your server's RAM usage.
+
+## Configuration Options
+
+You can customize the static handler:
+
+```typescript
+app.static('/public', './public', {
+  maxAge: 86400, // Cache-Control max-age in seconds (default: 0)
+  index: 'index.html', // Default file for directories (default: index.html)
+  hidden: false // Serve hidden files starting with . (default: false)
+});
+```
+
+## Manual Streaming
+
+If you need to stream generated content or files manually within a route:
+
+```typescript
+import fs from 'fs';
+
+app.get('/download', ({ res }) => {
+  const stream = fs.createReadStream('./large-file.zip');
+  
+  res.setHeader('Content-Type', 'application/zip');
+  stream.pipe(res);
+});
+```

package/docs/WEBSOCKETS.md

@@ -0,0 +1,76 @@
+# WebSockets
+
+QHTTPX includes a first-class, high-performance WebSocket implementation with built-in Pub/Sub capabilities. It handles protocol upgrades automatically within the same HTTP server instance.
+
+## Usage
+
+### 1. Enable WebSockets
+
+No special configuration is needed. The WebSocket server is attached to the HTTP server automatically.
+
+### 2. Handle Upgrades
+
+Use the `app.upgrade` method to handle the initial handshake.
+
+```typescript
+app.upgrade('/ws', (req, socket, head) => {
+  // Perform authentication here if needed
+  // ...
+  
+  // Accept the upgrade
+  app.websocket.handleUpgrade(req, socket, head, (ws) => {
+    app.websocket.emit('connection', ws, req);
+  });
+});
+```
+
+### 3. Handle Connections
+
+Listen for the `connection` event on the `app.websocket` instance.
+
+```typescript
+app.websocket.on('connection', (ws, req) => {
+  console.log('New client connected!');
+
+  ws.on('message', (msg) => {
+    console.log('Received:', msg.toString());
+    ws.send(`Echo: ${msg}`);
+  });
+
+  ws.on('close', () => {
+    console.log('Client disconnected');
+  });
+});
+```
+
+## Pub/Sub (Rooms)
+
+QHTTPX allows you to broadcast messages to specific "rooms" or groups of clients.
+
+### Joining a Room
+
+```typescript
+app.websocket.on('connection', (ws) => {
+  // Client joins 'chat-room-1'
+  ws.subscribe('chat-room-1');
+});
+```
+
+### Broadcasting to a Room
+
+You can broadcast from anywhere in your application (even outside the socket handler).
+
+```typescript
+// Send to everyone in 'chat-room-1'
+app.websocket.to('chat-room-1').emit('New Message!');
+```
+
+### Leaving a Room
+
+```typescript
+ws.unsubscribe('chat-room-1');
+```
+
+## Performance Note
+
+The WebSocket implementation shares the same efficient async scheduler as the HTTP layer, allowing thousands of concurrent connections with minimal overhead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qhttpx",
-  "version": "1.8.5",
+  "version": "1.8.11",
   "description": "The High-Performance Hybrid HTTP Runtime for Node.js. Built for extreme concurrency, request fusion, and zero-overhead scaling.",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -14,6 +14,15 @@
   "bin": {
     "qhttpx": "./dist/src/cli/index.js"
   },
+  "files": [
+    "dist",
+    "src/native",
+    "binding.gyp",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "docs"
+  ],
   "directories": {
     "doc": "docs"
   },
@@ -82,6 +91,7 @@
     "better-sqlite3": "^12.6.2",
     "busboy": "^1.6.0",
     "fast-json-stringify": "^5.15.1",
+    "node-addon-api": "^8.5.0",
     "pino": "^10.2.0",
     "pino-pretty": "^13.1.3",
     "quantam-async": "^0.1.1",

package/src/native/README.md

@@ -0,0 +1,31 @@
+# QHTTPX Native Addon
+
+This directory contains the C++ native addon for QHTTPX to accelerate HTTP parsing and response generation.
+
+## Prerequisites
+
+To build this addon, you need:
+- **Windows**: Visual Studio Build Tools (Desktop development with C++).
+- **Linux/macOS**: Python 3, make, and a C++ compiler (GCC/Clang).
+
+## Building
+
+The build is handled automatically by `npm install` if `node-gyp` and build tools are present.
+
+To manually rebuild:
+```bash
+npx node-gyp rebuild
+```
+
+## Structure
+
+- `addon.cc`: Entry point, registers the module.
+- `server.cc`: `NativeServer` class implementation.
+- `picohttpparser.c/h`: The HTTP parser library (vendored).
+- `index.ts`: TypeScript wrapper and fallback logic.
+
+## Usage
+
+The `NativeAdapter` in `src/core/native-adapter.ts` automatically detects if the native addon is available.
+If available, it uses `net.Server` + `NativeServer` for handling requests.
+If not, it falls back to the standard `http.Server`.

package/src/native/addon.cc

@@ -0,0 +1,8 @@
+#include <napi.h>
+#include "server.h"
+
+Napi::Object InitAll(Napi::Env env, Napi::Object exports) {
+  return NativeServer::Init(env, exports);
+}
+
+NODE_API_MODULE(qhttpx_native, InitAll)

package/src/native/index.ts

@@ -0,0 +1,78 @@
+
+
+export interface NativeServerBinding {
+  parse(buffer: Buffer): {
+    method: string;
+    path: string;
+    version: number;
+    headers: Record<string, string>;
+    bodyOffset: number;
+  } | null;
+  createResponse(statusCode: number, headers: Record<string, string>, body?: string | Buffer): Buffer;
+  createJSONResponse(obj: unknown): Buffer;
+  writeResponse(fd: number, chunks: (Buffer | string)[]): void;
+  setCPUAffinity(cpuId: number): boolean;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let nativeBinding: any = null;
+
+// Use try/catch with module.createRequire if import.meta is not available in some build targets
+// However, since we are in a TS module that might be commonjs or esm
+// We'll use a safer approach for require
+try {
+  const req = require;
+  
+  try {
+    nativeBinding = req('../../build/Release/qhttpx_native.node');
+  } catch {
+    try {
+      nativeBinding = req('../../build/Debug/qhttpx_native.node');
+    } catch {
+      // Ignored
+    }
+  }
+} catch {
+  // Ignored
+}
+
+export class NativeServer {
+  private binding: NativeServerBinding | null;
+
+  constructor() {
+    if (nativeBinding && nativeBinding.NativeServer) {
+      this.binding = new nativeBinding.NativeServer();
+    } else {
+      this.binding = null;
+    }
+  }
+
+  public get isAvailable(): boolean {
+    return this.binding !== null;
+  }
+
+  public parse(buffer: Buffer) {
+    if (!this.binding) throw new Error('Native bindings not available');
+    return this.binding.parse(buffer);
+  }
+
+  public createResponse(statusCode: number, headers: Record<string, string>, body?: string | Buffer) {
+    if (!this.binding) throw new Error('Native bindings not available');
+    return this.binding.createResponse(statusCode, headers, body);
+  }
+
+  public createJSONResponse(obj: unknown) {
+    if (!this.binding) throw new Error('Native bindings not available');
+    return this.binding.createJSONResponse(obj);
+  }
+
+  public writeResponse(fd: number, chunks: (Buffer | string)[]) {
+    if (!this.binding) throw new Error('Native bindings not available');
+    return this.binding.writeResponse(fd, chunks);
+  }
+
+  public setCPUAffinity(cpuId: number) {
+    if (!this.binding) throw new Error('Native bindings not available');
+    return this.binding.setCPUAffinity(cpuId);
+  }
+}