qhttpx 1.8.4 → 1.8.11

package/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.8.11] - 2026-01-20
+**"The Workflow Fix"**
+
+### Fixed
+- **CI/CD**: Changed NPM publish trigger from `release: published` to `push: tags` to bypass GITHUB_TOKEN recursion limits.
+
+## [1.8.10] - 2026-01-20
+**"The Debug Update"**
+
+### Changed
+- **CI/CD**: Enabled verbose logging for NPM publish workflow to diagnose registry errors.
+
+## [1.8.9] - 2026-01-20
+**"The Publishing Fix"**
+
+### Fixed
+- **NPM Publishing**: Fixed `npm publish` failure ("Hard link is not allowed") by explicitly whitelisting package files in `package.json`.
+
+## [1.8.8] - 2026-01-20
+**"The Documentation & Stability Update"**
+
+### Added
+- **Comprehensive Documentation**: Added detailed guides in `docs/` for Routing, Middleware, Errors, Request Fusion, Aegis Rate Limiting, WebSockets, and Static Files.
+- **Documentation Index**: Added a central documentation index to `README.md`.
+- **Feature Comparison**: Expanded `README.md` comparison table to highlight Hybrid Architecture, Request Fusion, and DDoS Protection.
+
+### Fixed
+- **Native Compilation**: Resolved `npm ci` failures on Windows/Linux by fixing macro usage in `picohttpparser.c` and `writev` return handling in `server.cc`.
+- **TypeScript Types**: Fixed `ctx.next` readonly assignment error that prevented middleware destructuring in some environments.
+- **Tests**: Fixed test suite failures in `dx.test.ts` and `resources.test.ts`.
+
+## [1.8.6] - 2026-01-20
+**"The Zero-Boilerplate Update"**
+
+### Added
+- **Zero-Config App Creation**: `createHttpApp` now accepts options for `rateLimit`, `cors`, and `compression` to enable them instantly without manual middleware setup.
+- **CLI Scaffolding**: Added `npm create qhttpx` support via the `create-qhttpx` package. Generates a modern, type-safe project with all best practices enabled.
+- **Standardized Errors**: Added `StandardHttpException` hierarchy (e.g., `NotFoundException`, `TooManyRequestsException`) for consistent error handling.
+- **Rate Limit Improvements**: Added `trustProxy` option to `RateLimitOptions` for correct IP detection behind proxies/load balancers.
+- **Context Utilities**: Added `ctx.ip` (remote address) and `ctx.method` (HTTP method) for easier access.
+- **Native Layer Architecture**: Significant C++ and architectural optimizations for high-throughput scaling:
+    - **ABI Lock**: Stabilized C++ interface with `WriteResponse` and `CreateJSONResponse` to prevent future breaking changes.
+    - **Zero-Copy JSON**: Implemented `createJSONResponse` fast path in C++ for serialization and HTTP framing without V8 transition overhead.
+    - **Object Pooling**: Added `MockResponsePool` to recycle request/response objects, reducing Garbage Collection pressure.
+    - **CPU Affinity**: Added `setCPUAffinity` to bind processes/threads to specific CPU cores for linear multi-core scaling.
+- **Ultra Performance**: Optimized Ultra Mode with lazy URL parsing and reduced overhead, achieving >50% reduction in p99 latency (1.4s -> ~0.7s) under heavy load.
+
+### Changed
+- **Simplified CLI**: `qhttpx new` now uses the same template as `create-qhttpx`, ensuring consistency.
+- **Dependency Management**: Scaffolding now uses explicit versioning (`^x.y.z`) for stability instead of `latest`.
+- **Benchmarks**: Updated performance comparisons against Fastify, Hono, and Express in `README.md` and `docs/BENCHMARKS.md`.
+
+## [1.8.5] - 2026-01-20
+**"The Usability IV Update"**
+
+### Added
+- **Context Headers**: Added `ctx.headers` (alias for `req.headers`) for direct access to request headers.
+- **Environment**: Added `dotenv` and updated `@types/node` dependencies.
+
 ## [1.8.4] - 2026-01-20
 **"The Usability III Update"**
 

package/README.md

@@ -2,7 +2,6 @@
   <img src="https://raw.githubusercontent.com/Quantam-Open-Source/qhttpx/main/assets/logo.svg" alt="QHTTPX Logo" width="200" height="200" />
 </div>
 
-<h1 align="center">QHTTPX</h1>
 
 <div align="center">
   <strong>The High-Performance Hybrid HTTP Runtime for Node.js</strong>
@@ -41,6 +40,22 @@ Most Node.js frameworks rely on the event loop blindly. QHTTPX introduces a **Co
 | **Routing** | Regex / Linear Scan | **Radix Tree** (O(1) lookup) |
 | **Streaming** | Basic Pipe | **Smart Streams** (Backpressure-aware) |
 
+### 🏆 Feature Comparison
+
+| Feature | **QHTTPX** | Fastify | Express | Hono |
+| :--- | :---: | :---: | :---: | :---: |
+| **Core Runtime** | **⚡ Hybrid (C++ / JS)** | JS | JS | JS |
+| **Request Fusion** | **✅ Native** | ❌ | ❌ | ❌ |
+| **DDoS Protection** | **✅ Built-in (Aegis)** | ❌ | ❌ | ❌ |
+| **JSON Serialization** | **✅ Zero-Copy (C++)** | Schema-based | Slow | Slow |
+| **Concurrency Model** | **✅ Async Scheduler** | Event Loop | Event Loop | Event Loop |
+| **Rate Limiting** | **✅ Zero-Overhead** | Plugin | Middleware | Middleware |
+| **Routing Algorithm** | **✅ Optimized Radix** | Radix Tree | Linear/Regex | RegExp/Trie |
+| **WebSocket** | **✅ Built-in Pub/Sub** | Plugin | Plugin | Helper |
+| **Multipart Uploads** | **✅ Native** | Plugin | Middleware | Plugin |
+| **Static Assets** | **✅ Smart Streaming** | Standard | Standard | Standard |
+| **Type Safety** | **✅ First-class** | Good | Partial | First-class |
+
 ---
 
 ## ✨ Key Features
@@ -77,7 +92,16 @@ npm install qhttpx
 
 ## ⚡ Quick Start
 
-### 1. The Rapid Way (Recommended)
+### 1. Create a Project (Recommended)
+
+Scaffold a production-ready QHTTPX application instantly using our CLI tool:
+
+```bash
+npm create qhttpx@latest
+```
+This will set up a project with TypeScript, Request Fusion, and best practices pre-configured.
+
+### 2. The Rapid Way (Singleton)
 Get up and running instantly with the singleton instance and destructuring support.
 
 ```typescript
@@ -95,7 +119,7 @@ app.onError(({ error, json }) => {
 app.listen(3000, () => console.log("Server running on http://localhost:3000"));
 ```
 
-### 2. The Custom Way
+### 3. The Custom Way (Advanced)
 When you need specific configuration options or multiple instances.
 
 ```typescript
@@ -115,65 +139,36 @@ app.get("/users", async ({ json, query }) => {
 app.listen(3000);
 ```
 
-### 2. The Scalable Way (Cluster Mode)
-For production workloads utilizing all CPU cores.
-
-```bash
-# Start your app in cluster mode
-npx qhttpx start dist/index.js
-```
-
 ---
 
-## 🛠️ Advanced Usage
-
-### Request Fusion (The "Magic")
-Enable `enableRequestFusion` to automatically deduplicate traffic.
-
-```typescript
-const app = new QHTTPX({ 
-  enableRequestFusion: true 
-});
-
-// If 50 users hit this endpoint simultaneously, 
-// the database query runs only ONCE.
-app.get("/heavy-query", async (ctx) => {
-  const data = await db.expensiveQuery();
-  return ctx.json(data);
-});
-```
-
-### Real-Time (SSE & WebSockets)
+## 📚 Documentation
 
-```typescript
-// Server-Sent Events
-app.get('/events', (ctx) => {
-  const stream = createSSE(ctx);
-  setInterval(() => {
-    stream.send({ time: Date.now() }, 'tick');
-  }, 1000);
-});
+Detailed guides for every feature of QHTTPX:
 
-// WebSockets with Rooms
-app.upgrade('/chat', (ws) => {
-  ws.join('general');
-  ws.on('message', (msg) => {
-    // Broadcast to 'general' room
-    app.websocket.to('general').emit(`Echo: ${msg}`);
-  });
-});
-```
+- **[Routing](./docs/ROUTING.md)**: Radix tree, parameters, and groups.
+- **[Middleware](./docs/MIDDLEWARE.md)**: Global and route-level hooks.
+- **[Error Handling](./docs/ERRORS.md)**: Standard exceptions and global handlers.
+- **[Aegis Rate Limiter](./docs/AEGIS.md)**: DDoS protection and traffic shaping.
+- **[Request Fusion](./docs/FUSION.md)**: "Thundering Herd" protection engine.
+- **[WebSockets](./docs/WEBSOCKETS.md)**: Real-time Pub/Sub and Rooms.
+- **[Static Files](./docs/STATIC.md)**: Streaming, Range requests, and Caching.
+- **[Ecosystem Integration](./docs/ECOSYSTEM.md)**: Auth, Database, and Validation patterns.
 
 ---
 
 ## 📊 Benchmarks
 
-In **Ultra Mode**, QHTTPX is designed to saturate 10Gbps links with minimal CPU usage.
+Benchmarks comparing **QHTTPX v1.8.6** against popular Node.js frameworks.
+*(Run on local environment: Windows, 100 connections, 10 pipelining, 40s duration. Average of 2 runs, taking the second result.)*
 
-*(Benchmarks run on AWS c5.large)*
-- **QHTTPX (Fusion Enabled)**: ~85,000 req/sec (0% DB Load increase on burst)
-- **Fastify**: ~72,000 req/sec
-- **Express**: ~14,000 req/sec
+| 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 |
+
+> **Note**: QHTTPX achieves comparable throughput to Fastify while offering advanced features like **Request Fusion** (deduplication) which can significantly reduce database load in real-world scenarios.
 
 ---
 
@@ -187,6 +182,31 @@ QHTTPX is an **Open Runtime**. It works seamlessly with standard tools:
 
 ---
 
+## 👥 Team
+
+QHTTPX is developed and maintained by **Quantam Open Source**.
+
+### Lead Developer
+**Byron Kennedy Pfukwa**  
+*Creator & Core Maintainer*  
+[![GitHub](https://img.shields.io/badge/GitHub-BYRON--lang-181717?style=flat&logo=github)](https://github.com/BYRON-lang)
+[![NPM](https://img.shields.io/badge/NPM-~brnxdev-CB3837?style=flat&logo=npm)](https://www.npmjs.com/~brnxdev)
+[![X](https://img.shields.io/badge/X-@byronpfukwa-000000?style=flat&logo=x)](https://x.com/byronpfukwa)
+
+### Socials
+Follow us for updates:
+- **QHTTPX (X)**: [@qhttpx](https://x.com/qhttpx)
+- **Open Quantam (X)**: [@openquantam](https://x.com/openquantam)
+
+---
+
 ## 📜 License
 
 MIT © [Quantam Open Source](https://github.com/Quantam-Open-Source)
+
+<br />
+
+<div align="center">
+  <p>Project Part of</p>
+  <img src="assets/open%20quantam.png" alt="Open Quantam" width="150" />
+</div>

package/binding.gyp

@@ -0,0 +1,18 @@
+{
+  "targets": [
+    {
+      "target_name": "qhttpx_native",
+      "cflags!": [ "-fno-exceptions" ],
+      "cflags_cc!": [ "-fno-exceptions" ],
+      "sources": [
+        "src/native/addon.cc",
+        "src/native/server.cc",
+        "src/native/picohttpparser.c"
+      ],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")"
+      ],
+      "defines": [ "NAPI_DISABLE_CPP_EXCEPTIONS" ]
+    }
+  ]
+}

package/dist/examples/api-server.js

@@ -1,17 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const index_1 = require("../src/index");
+const dotenv_1 = require("dotenv");
+// Load .env
+(0, dotenv_1.config)();
 // 1. Initialize App (Fusion + Aegis enabled)
 const app = (0, index_1.createHttpApp)({
     enableRequestFusion: true, // ⚡ Auto-coalesce duplicate requests
-    metricsEnabled: true // 📊 Expose /__qhttpx/metrics
-});
-// 2. Global Middleware (Logging & Rate Limit)
-app.use(async ({ req, next }) => {
-    console.log(`[${req.method}] ${req.url}`);
-    if (next)
-        await next();
+    metricsEnabled: true, // 📊 Expose /__qhttpx/metrics
+    rateLimit: {
+        windowMs: 15 * 60 * 1000,
+        max: 100,
+        trustProxy: true
+    },
+    cors: true, // 🛡️ Built-in CORS
+    compression: true // 🗜️ Built-in Compression (Gzip/Brotli)
 });
+// 2. Global Middleware (Logging is built-in by default)
+// No manual app.use(rateLimit(...)) needed!
 // 3. Validation Schema
 const UserSchema = {
     body: {
@@ -32,7 +38,15 @@ app.post('/users', { schema: UserSchema }, async ({ body, json }) => {
     // Body is already validated and typed here
     json({ created: true, user: body }, 201);
 });
-// 📂 File Uploads (Typed)
+// � Header Auth Example
+app.post('/auth/verify', async ({ headers, json }) => {
+    const token = headers.authorization?.replace('Bearer ', '');
+    if (!token)
+        return json({ error: 'No token provided' }, 401);
+    // Verify token...
+    json({ valid: true, token });
+});
+// �📂 File Uploads (Typed)
 app.post('/upload', ({ files, json }) => {
     if (!files?.doc)
         return json({ error: 'No file' }, 400);
@@ -49,6 +63,13 @@ app.upgrade('/chat', (ws) => {
 });
 // 5. Unified Error Handling
 app.onError(({ error, json }) => {
+    if (error instanceof index_1.HttpError) {
+        return json({
+            error: error.message,
+            code: error.code,
+            details: error.details
+        }, error.status);
+    }
     console.error(error); // Log internal error
     json({ error: 'Internal Server Error', handled: true }, 500);
 });

package/dist/examples/basic.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/basic.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../src/index");
+const app = (0, index_1.createHttpApp)();
+app.get('/', ({ json }) => {
+    json({ message: 'Hello from QHTTPX!' });
+});
+app.listen(3000, () => {
+    console.log('Server running on http://localhost:3000');
+});

package/dist/examples/compression.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/compression.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../src/index");
+const app = (0, index_1.createHttpApp)({
+    // Enable Gzip/Brotli compression
+    compression: true
+    // Or with options:
+    // compression: { threshold: 2048 } // Only compress responses > 2KB
+});
+app.get('/large', ({ json }) => {
+    // Generate a large response to trigger compression
+    const data = Array(1000).fill('some repeated data to compress');
+    json({ data });
+});
+app.listen(3000, () => {
+    console.log('Compression-enabled server running on http://localhost:3000');
+});

package/dist/examples/cors.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/cors.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../src/index");
+const app = (0, index_1.createHttpApp)({
+    // Simple: Enable CORS for all origins
+    // cors: true 
+    // Advanced: Configure specific origins
+    cors: {
+        origin: ['http://localhost:5173', 'https://myapp.com'],
+        methods: ['GET', 'POST'],
+        credentials: true
+    }
+});
+app.get('/api/data', ({ json }) => {
+    json({ data: 'This data is accessible via CORS' });
+});
+app.listen(3000, () => {
+    console.log('CORS-enabled server running on http://localhost:3000');
+});

package/dist/examples/errors.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/errors.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../src/index");
+const app = (0, index_1.createHttpApp)();
+app.get('/missing', () => {
+    throw new index_1.NotFoundException('Resource not found');
+});
+app.get('/private', () => {
+    throw new index_1.ForbiddenException('You do not have access');
+});
+// Custom global error handler
+app.onError(({ error, json }) => {
+    if (error instanceof index_1.HttpError) {
+        return json({
+            status: 'error',
+            code: error.code,
+            message: error.message
+        }, error.status);
+    }
+    console.error('Unexpected error:', error);
+    json({ status: 'error', message: 'Internal Server Error' }, 500);
+});
+app.listen(3000, () => {
+    console.log('Error handling demo running on http://localhost:3000');
+});

package/dist/examples/file-upload.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/file-upload.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../src/index");
+const app = (0, index_1.createHttpApp)({
+    // Limits for uploads
+    maxBodyBytes: 10 * 1024 * 1024 // 10MB
+});
+app.post('/upload', ({ files, json }) => {
+    if (!files || !files.document) {
+        return json({ error: 'No file uploaded' }, 400);
+    }
+    const doc = Array.isArray(files.document) ? files.document[0] : files.document;
+    console.log(`Received file: ${doc.filename} (${doc.size} bytes)`);
+    json({
+        uploaded: true,
+        filename: doc.filename,
+        mimetype: doc.mimeType,
+        size: doc.size
+    });
+});
+app.listen(3000, () => {
+    console.log('Upload server running on http://localhost:3000');
+    console.log('Send POST to /upload with form-data field "document"');
+});

package/dist/examples/fusion.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/fusion.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../src/index");
+const app = (0, index_1.createHttpApp)({
+    // Enable Request Fusion (Request Coalescing)
+    enableRequestFusion: true
+});
+// Simulate a slow database call
+const heavyTask = async () => {
+    await new Promise(resolve => setTimeout(resolve, 500));
+    return { data: 'Expensive Result', timestamp: Date.now() };
+};
+// If 1000 users hit this endpoint simultaneously, 
+// the handler runs ONLY ONCE, and the result is shared.
+app.get('/heavy', async ({ json }) => {
+    const result = await heavyTask();
+    json(result);
+});
+app.listen(3000, () => {
+    console.log('Fusion-enabled server running on http://localhost:3000');
+});

package/dist/examples/rate-limiting.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/rate-limiting.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../src/index");
+const app = (0, index_1.createHttpApp)({
+    rateLimit: {
+        windowMs: 15 * 60 * 1000, // 15 minutes
+        max: 100, // Limit each IP to 100 requests per window
+        message: 'Too many requests, please try again later.',
+        trustProxy: true // Trust X-Forwarded-For header (useful behind proxies like Nginx)
+    }
+});
+app.get('/', ({ json }) => {
+    json({ status: 'OK', message: 'Request accepted' });
+});
+app.listen(3000, () => {
+    console.log('Rate-limited server running on http://localhost:3000');
+});

package/dist/examples/validation.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/validation.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../src/index");
+const app = (0, index_1.createHttpApp)();
+// Define a simple schema (or use Zod if configured)
+const UserSchema = {
+    body: {
+        type: 'object',
+        required: ['username', 'email'],
+        properties: {
+            username: { type: 'string' },
+            email: { type: 'string' }
+        }
+    }
+};
+// Apply schema to route
+app.post('/register', { schema: UserSchema }, ({ body, json }) => {
+    // 'body' is already validated and typed here (if using TS with inferred types)
+    json({ success: true, user: body });
+});
+app.listen(3000, () => {
+    console.log('Validation server running on http://localhost:3000');
+});

package/dist/examples/websockets.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/examples/websockets.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../src/index");
+const app = (0, index_1.createHttpApp)();
+app.upgrade('/chat', (ws) => {
+    console.log('Client connected');
+    ws.join('general');
+    ws.on('message', (msg) => {
+        console.log(`Received: ${msg}`);
+        // Broadcast to everyone in 'general' room
+        app.websocket.to('general').emit(`Echo: ${msg}`);
+    });
+    ws.on('close', () => {
+        console.log('Client disconnected');
+    });
+});
+app.listen(3000, () => {
+    console.log('WebSocket Server running on http://localhost:3000');
+    console.log('Test with a WebSocket client at ws://localhost:3000/chat');
+});

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "qhttpx",
-    "version": "1.8.4",
+    "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"
     },
@@ -67,6 +76,7 @@
         "@typescript-eslint/eslint-plugin": "^8.53.0",
         "@typescript-eslint/parser": "^8.53.0",
         "autocannon": "^8.0.0",
+        "dotenv": "^17.2.3",
         "eslint": "^9.39.2",
         "eslint-config-prettier": "^10.1.8",
         "eslint-plugin-prettier": "^5.5.5",
@@ -81,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/dist/src/benchmarks/simple-json.js

@@ -9,10 +9,9 @@ function runAutocannon(url) {
     return new Promise((resolve, reject) => {
         const instance = (0, autocannon_1.default)({
             url,
-            amount: 10000,
-            connections: 10000,
-            pipelining: 1,
-            duration: 10,
+            connections: 100,
+            pipelining: 10,
+            duration: 40,
         }, (err, result) => {
             if (err) {
                 reject(err);
@@ -37,6 +36,9 @@ async function run() {
     });
     const { port } = await app.listen(0, '127.0.0.1');
     const url = `http://127.0.0.1:${port}/json`;
+    console.log('Running warmup (1/2)...');
+    await runAutocannon(url);
+    console.log('Running benchmark (2/2)...');
     const result = await runAutocannon(url);
     autocannon_1.default.printResult(result);
     const totalRequests = result.requests.total;