qhttpx 1.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.eslintrc.json +22 -0
- package/.github/workflows/ci.yml +32 -0
- package/.github/workflows/npm-publish.yml +37 -0
- package/.github/workflows/release.yml +21 -0
- package/.prettierrc +7 -0
- package/CHANGELOG.md +145 -0
- package/LICENSE +21 -0
- package/README.md +343 -0
- package/dist/package.json +61 -0
- package/dist/src/benchmarks/compare-frameworks.js +119 -0
- package/dist/src/benchmarks/quantam-users.js +56 -0
- package/dist/src/benchmarks/simple-json.js +58 -0
- package/dist/src/benchmarks/ultra-mode.js +122 -0
- package/dist/src/cli/index.js +200 -0
- package/dist/src/client/index.js +72 -0
- package/dist/src/core/batch.js +97 -0
- package/dist/src/core/body-parser.js +121 -0
- package/dist/src/core/buffer-pool.js +70 -0
- package/dist/src/core/config.js +50 -0
- package/dist/src/core/fusion.js +183 -0
- package/dist/src/core/logger.js +49 -0
- package/dist/src/core/metrics.js +111 -0
- package/dist/src/core/resources.js +25 -0
- package/dist/src/core/scheduler.js +85 -0
- package/dist/src/core/scope.js +68 -0
- package/dist/src/core/serializer.js +44 -0
- package/dist/src/core/server.js +905 -0
- package/dist/src/core/stream.js +71 -0
- package/dist/src/core/tasks.js +87 -0
- package/dist/src/core/types.js +19 -0
- package/dist/src/core/websocket.js +86 -0
- package/dist/src/core/worker-queue.js +73 -0
- package/dist/src/database/adapters/memory.js +90 -0
- package/dist/src/database/adapters/mongo.js +141 -0
- package/dist/src/database/adapters/postgres.js +111 -0
- package/dist/src/database/adapters/sqlite.js +42 -0
- package/dist/src/database/coalescer.js +134 -0
- package/dist/src/database/manager.js +87 -0
- package/dist/src/database/types.js +2 -0
- package/dist/src/index.js +61 -0
- package/dist/src/middleware/compression.js +133 -0
- package/dist/src/middleware/cors.js +66 -0
- package/dist/src/middleware/presets.js +33 -0
- package/dist/src/middleware/rate-limit.js +77 -0
- package/dist/src/middleware/security.js +69 -0
- package/dist/src/middleware/static.js +191 -0
- package/dist/src/openapi/generator.js +149 -0
- package/dist/src/router/radix-router.js +89 -0
- package/dist/src/router/radix-tree.js +81 -0
- package/dist/src/router/router.js +146 -0
- package/dist/src/testing/index.js +84 -0
- package/dist/src/utils/cookies.js +59 -0
- package/dist/src/utils/logger.js +45 -0
- package/dist/src/utils/signals.js +31 -0
- package/dist/src/utils/sse.js +32 -0
- package/dist/src/validation/index.js +19 -0
- package/dist/src/validation/simple.js +102 -0
- package/dist/src/validation/types.js +12 -0
- package/dist/src/validation/zod.js +18 -0
- package/dist/src/views/index.js +17 -0
- package/dist/src/views/types.js +2 -0
- package/dist/tests/adapters.test.js +106 -0
- package/dist/tests/batch.test.js +117 -0
- package/dist/tests/body-parser.test.js +52 -0
- package/dist/tests/compression-sse.test.js +87 -0
- package/dist/tests/cookies.test.js +63 -0
- package/dist/tests/cors.test.js +55 -0
- package/dist/tests/database.test.js +80 -0
- package/dist/tests/dx.test.js +64 -0
- package/dist/tests/ecosystem.test.js +133 -0
- package/dist/tests/features.test.js +47 -0
- package/dist/tests/fusion.test.js +92 -0
- package/dist/tests/http-basic.test.js +124 -0
- package/dist/tests/logger.test.js +33 -0
- package/dist/tests/middleware.test.js +109 -0
- package/dist/tests/observability.test.js +59 -0
- package/dist/tests/openapi.test.js +64 -0
- package/dist/tests/plugin.test.js +65 -0
- package/dist/tests/plugins.test.js +71 -0
- package/dist/tests/rate-limit.test.js +77 -0
- package/dist/tests/resources.test.js +44 -0
- package/dist/tests/scheduler.test.js +46 -0
- package/dist/tests/schema-routes.test.js +77 -0
- package/dist/tests/security.test.js +83 -0
- package/dist/tests/server-db.test.js +72 -0
- package/dist/tests/smoke.test.js +10 -0
- package/dist/tests/sqlite-fusion.test.js +92 -0
- package/dist/tests/static.test.js +102 -0
- package/dist/tests/stream.test.js +44 -0
- package/dist/tests/task-metrics.test.js +53 -0
- package/dist/tests/tasks.test.js +62 -0
- package/dist/tests/testing.test.js +47 -0
- package/dist/tests/validation.test.js +107 -0
- package/dist/tests/websocket.test.js +146 -0
- package/dist/vitest.config.js +9 -0
- package/docs/AEGIS.md +76 -0
- package/docs/BENCHMARKS.md +36 -0
- package/docs/CAPABILITIES.md +70 -0
- package/docs/CLI.md +43 -0
- package/docs/DATABASE.md +142 -0
- package/docs/ECOSYSTEM.md +146 -0
- package/docs/NEXT_STEPS.md +99 -0
- package/docs/OPENAPI.md +99 -0
- package/docs/PLUGINS.md +59 -0
- package/docs/REAL_WORLD_EXAMPLES.md +109 -0
- package/docs/ROADMAP.md +366 -0
- package/docs/VALIDATION.md +136 -0
- package/eslint.config.cjs +26 -0
- package/examples/api-server.ts +254 -0
- package/package.json +61 -0
- package/src/benchmarks/compare-frameworks.ts +149 -0
- package/src/benchmarks/quantam-users.ts +70 -0
- package/src/benchmarks/simple-json.ts +71 -0
- package/src/benchmarks/ultra-mode.ts +159 -0
- package/src/cli/index.ts +214 -0
- package/src/client/index.ts +93 -0
- package/src/core/batch.ts +110 -0
- package/src/core/body-parser.ts +151 -0
- package/src/core/buffer-pool.ts +96 -0
- package/src/core/config.ts +60 -0
- package/src/core/fusion.ts +210 -0
- package/src/core/logger.ts +70 -0
- package/src/core/metrics.ts +166 -0
- package/src/core/resources.ts +38 -0
- package/src/core/scheduler.ts +126 -0
- package/src/core/scope.ts +87 -0
- package/src/core/serializer.ts +41 -0
- package/src/core/server.ts +1113 -0
- package/src/core/stream.ts +111 -0
- package/src/core/tasks.ts +138 -0
- package/src/core/types.ts +178 -0
- package/src/core/websocket.ts +112 -0
- package/src/core/worker-queue.ts +90 -0
- package/src/database/adapters/memory.ts +99 -0
- package/src/database/adapters/mongo.ts +116 -0
- package/src/database/adapters/postgres.ts +86 -0
- package/src/database/adapters/sqlite.ts +44 -0
- package/src/database/coalescer.ts +153 -0
- package/src/database/manager.ts +97 -0
- package/src/database/types.ts +24 -0
- package/src/index.ts +42 -0
- package/src/middleware/compression.ts +147 -0
- package/src/middleware/cors.ts +98 -0
- package/src/middleware/presets.ts +50 -0
- package/src/middleware/rate-limit.ts +106 -0
- package/src/middleware/security.ts +109 -0
- package/src/middleware/static.ts +216 -0
- package/src/openapi/generator.ts +167 -0
- package/src/router/radix-router.ts +119 -0
- package/src/router/radix-tree.ts +106 -0
- package/src/router/router.ts +190 -0
- package/src/testing/index.ts +104 -0
- package/src/utils/cookies.ts +67 -0
- package/src/utils/logger.ts +59 -0
- package/src/utils/signals.ts +45 -0
- package/src/utils/sse.ts +41 -0
- package/src/validation/index.ts +3 -0
- package/src/validation/simple.ts +93 -0
- package/src/validation/types.ts +38 -0
- package/src/validation/zod.ts +14 -0
- package/src/views/index.ts +1 -0
- package/src/views/types.ts +4 -0
- package/tests/adapters.test.ts +120 -0
- package/tests/batch.test.ts +139 -0
- package/tests/body-parser.test.ts +83 -0
- package/tests/compression-sse.test.ts +98 -0
- package/tests/cookies.test.ts +74 -0
- package/tests/cors.test.ts +79 -0
- package/tests/database.test.ts +90 -0
- package/tests/dx.test.ts +78 -0
- package/tests/ecosystem.test.ts +156 -0
- package/tests/features.test.ts +51 -0
- package/tests/fusion.test.ts +121 -0
- package/tests/http-basic.test.ts +161 -0
- package/tests/logger.test.ts +48 -0
- package/tests/middleware.test.ts +137 -0
- package/tests/observability.test.ts +91 -0
- package/tests/openapi.test.ts +74 -0
- package/tests/plugin.test.ts +85 -0
- package/tests/plugins.test.ts +93 -0
- package/tests/rate-limit.test.ts +97 -0
- package/tests/resources.test.ts +64 -0
- package/tests/scheduler.test.ts +71 -0
- package/tests/schema-routes.test.ts +89 -0
- package/tests/security.test.ts +128 -0
- package/tests/server-db.test.ts +72 -0
- package/tests/smoke.test.ts +9 -0
- package/tests/sqlite-fusion.test.ts +106 -0
- package/tests/static.test.ts +111 -0
- package/tests/stream.test.ts +58 -0
- package/tests/task-metrics.test.ts +78 -0
- package/tests/tasks.test.ts +90 -0
- package/tests/testing.test.ts +53 -0
- package/tests/validation.test.ts +126 -0
- package/tests/websocket.test.ts +132 -0
- package/tsconfig.json +16 -0
- package/vitest.config.ts +9 -0
package/.eslintrc.json
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
{
|
|
2
|
+
"root": true,
|
|
3
|
+
"env": {
|
|
4
|
+
"es2020": true,
|
|
5
|
+
"node": true
|
|
6
|
+
},
|
|
7
|
+
"parser": "@typescript-eslint/parser",
|
|
8
|
+
"parserOptions": {
|
|
9
|
+
"project": "./tsconfig.json",
|
|
10
|
+
"sourceType": "module"
|
|
11
|
+
},
|
|
12
|
+
"plugins": ["@typescript-eslint"],
|
|
13
|
+
"extends": [
|
|
14
|
+
"eslint:recommended",
|
|
15
|
+
"plugin:@typescript-eslint/recommended",
|
|
16
|
+
"plugin:prettier/recommended"
|
|
17
|
+
],
|
|
18
|
+
"rules": {
|
|
19
|
+
"@typescript-eslint/no-explicit-any": "off"
|
|
20
|
+
},
|
|
21
|
+
"ignorePatterns": ["dist/**", "node_modules/**"]
|
|
22
|
+
}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches:
|
|
6
|
+
- main
|
|
7
|
+
- master
|
|
8
|
+
pull_request:
|
|
9
|
+
|
|
10
|
+
jobs:
|
|
11
|
+
build-and-test:
|
|
12
|
+
runs-on: ubuntu-latest
|
|
13
|
+
|
|
14
|
+
steps:
|
|
15
|
+
- name: Checkout
|
|
16
|
+
uses: actions/checkout@v4
|
|
17
|
+
|
|
18
|
+
- name: Setup Node.js
|
|
19
|
+
uses: actions/setup-node@v4
|
|
20
|
+
with:
|
|
21
|
+
node-version: 20
|
|
22
|
+
cache: "npm"
|
|
23
|
+
|
|
24
|
+
- name: Install dependencies
|
|
25
|
+
run: npm ci
|
|
26
|
+
|
|
27
|
+
- name: Lint
|
|
28
|
+
run: npm run lint
|
|
29
|
+
|
|
30
|
+
- name: Test
|
|
31
|
+
run: npm test
|
|
32
|
+
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
name: Publish to NPM
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
release:
|
|
5
|
+
types: [published]
|
|
6
|
+
|
|
7
|
+
jobs:
|
|
8
|
+
publish:
|
|
9
|
+
runs-on: ubuntu-latest
|
|
10
|
+
permissions:
|
|
11
|
+
contents: read
|
|
12
|
+
id-token: write
|
|
13
|
+
|
|
14
|
+
steps:
|
|
15
|
+
- name: Checkout
|
|
16
|
+
uses: actions/checkout@v4
|
|
17
|
+
|
|
18
|
+
- name: Setup Node.js
|
|
19
|
+
uses: actions/setup-node@v4
|
|
20
|
+
with:
|
|
21
|
+
node-version: 20
|
|
22
|
+
registry-url: 'https://registry.npmjs.org'
|
|
23
|
+
cache: 'npm'
|
|
24
|
+
|
|
25
|
+
- name: Install dependencies
|
|
26
|
+
run: npm ci
|
|
27
|
+
|
|
28
|
+
- name: Build
|
|
29
|
+
run: npm run build
|
|
30
|
+
|
|
31
|
+
- name: Test
|
|
32
|
+
run: npm test
|
|
33
|
+
|
|
34
|
+
- name: Publish to NPM
|
|
35
|
+
run: npm publish --access public
|
|
36
|
+
env:
|
|
37
|
+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
name: Release
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
tags:
|
|
6
|
+
- "v*"
|
|
7
|
+
|
|
8
|
+
permissions:
|
|
9
|
+
contents: write
|
|
10
|
+
|
|
11
|
+
jobs:
|
|
12
|
+
release:
|
|
13
|
+
runs-on: ubuntu-latest
|
|
14
|
+
steps:
|
|
15
|
+
- name: Checkout
|
|
16
|
+
uses: actions/checkout@v4
|
|
17
|
+
|
|
18
|
+
- name: Create Release
|
|
19
|
+
uses: softprops/action-gh-release@v1
|
|
20
|
+
with:
|
|
21
|
+
generate_release_notes: true
|
package/.prettierrc
ADDED
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
## [1.8.0] - 2026-01-20
|
|
6
|
+
**"The Full-Stack Update"**
|
|
7
|
+
|
|
8
|
+
### Added
|
|
9
|
+
- **Compression Middleware**: Native support for Gzip, Brotli, and Deflate response compression with auto-thresholding (default 1KB) and stream piping.
|
|
10
|
+
- **Server-Sent Events (SSE)**: Built-in `createSSE()` helper for easy real-time event streaming with automatic header management and connection persistence.
|
|
11
|
+
- **Advanced Static Files**: Completely rewritten `static` middleware with support for **Streaming**, **Range Requests** (for video), and **HTTP Caching** (ETag/Last-Modified/304).
|
|
12
|
+
- **Multipart Support**: Integrated `busboy` for high-performance `multipart/form-data` parsing. Files are automatically available in `ctx.files`.
|
|
13
|
+
- **View Engine**: New `ViewEngine` interface and `ctx.render()` method for server-side template rendering (supports EJS, Pug, etc. via adapters).
|
|
14
|
+
- **WebSocket Channels**: Enhanced WebSocket support with a Pub/Sub "Rooms" system for easy broadcasting to specific groups of clients.
|
|
15
|
+
- **Zod Integration**: Official support for Zod schemas in `ctx.validate()`, enabling robust type-safe validation.
|
|
16
|
+
|
|
17
|
+
## [1.7.0] - 2026-01-20
|
|
18
|
+
**"The Developer Experience Update"**
|
|
19
|
+
|
|
20
|
+
### Added
|
|
21
|
+
- **QCLI**: New Command Line Interface (`qhttpx`) for streamlined development and deployment.
|
|
22
|
+
- **Cluster Mode**: `qhttpx start <file>` automatically forks workers across all CPU cores for maximum performance.
|
|
23
|
+
- **Dev Mode**: `qhttpx dev <file>` provides hot-reloading and TypeScript support out of the box.
|
|
24
|
+
- **Resilience**: Built-in worker monitoring and automatic restart on crash in production mode.
|
|
25
|
+
|
|
26
|
+
## [1.6.0] - 2026-01-20
|
|
27
|
+
**"The Extension Update"**
|
|
28
|
+
|
|
29
|
+
### Added
|
|
30
|
+
- **Plugin System**: Full-featured Extension Protocol allowing modular architecture via `app.register()`.
|
|
31
|
+
- **Scoped Routing**: Plugins run in isolated scopes with automatic path prefixing (e.g., `app.register(api, { prefix: '/api' })`).
|
|
32
|
+
- **Async Initialization**: Plugins can be async (e.g., for database connections), and the server waits for them.
|
|
33
|
+
- **Nested Plugins**: Plugins can register other plugins, inheriting and concatenating prefixes automatically.
|
|
34
|
+
- **Encapsulation**: `QHTTPXScope` ensures plugins don't accidentally pollute the global namespace.
|
|
35
|
+
|
|
36
|
+
## [1.5.0] - 2026-01-20
|
|
37
|
+
**"The Aegis Update"**
|
|
38
|
+
|
|
39
|
+
### Added
|
|
40
|
+
- **Aegis Rate Limiter**: High-performance, Token Bucket-based rate limiting middleware to protect against DDoS and abuse.
|
|
41
|
+
- **Dual-Layer Storage**: Default in-memory storage with automatic cleanup, designed to be swappable with Redis/KV stores.
|
|
42
|
+
- **Smart Headers**: Automatic `X-RateLimit-*` and `Retry-After` header injection for standard compliance.
|
|
43
|
+
- **Flexible Keys**: Support for custom key generators (IP, API Key, User ID) to enable tiered rate limiting.
|
|
44
|
+
|
|
45
|
+
## [1.4.0] - 2026-01-20
|
|
46
|
+
**"The Quantum Collapse Update"**
|
|
47
|
+
|
|
48
|
+
### Added
|
|
49
|
+
- **Request Fusion Engine**: A revolutionary request-level coalescing system (Layer 2) that collapses simultaneous requests to the same endpoint into a single execution.
|
|
50
|
+
- **In-Flight Deduplication**: Simultaneous requests for the same resource (based on semantic key) are merged into a "Leader-Follower" model where only one handler runs.
|
|
51
|
+
- **Micro-TTL Caching**: Optional short-lived cache (5-20ms) to coalesce burst traffic that arrives slightly out of sync.
|
|
52
|
+
- **Semantic Hashing**: Intelligent request key generation based on Method + Route + Query + Body + Vary Headers.
|
|
53
|
+
- **Vary Header Support**: Automatic isolation of authenticated requests (Authorization, Cookie) to prevent cross-user data leaks.
|
|
54
|
+
|
|
55
|
+
## [1.3.0] - 2026-01-20
|
|
56
|
+
**"The Documentation Update"**
|
|
57
|
+
|
|
58
|
+
### Added
|
|
59
|
+
- **OpenAPI Generator**: New `app.getOpenAPI()` method automatically generates OpenAPI 3.0 specs from your routes and schemas.
|
|
60
|
+
- **Schema Mapping**: `SimpleValidator` schemas are automatically converted to Swagger-compatible JSON schemas.
|
|
61
|
+
- **Auto-Discovery**: Automatically infers path parameters (e.g., `/{id}`) and query parameters from your code.
|
|
62
|
+
|
|
63
|
+
## [1.2.0] - 2026-01-20
|
|
64
|
+
**"The Guardrails Update"**
|
|
65
|
+
|
|
66
|
+
### Added
|
|
67
|
+
- **Input Validation**: Built-in, zero-dependency `SimpleValidator` for Request Body, Query Parameters, and URL Params.
|
|
68
|
+
- **Automatic Coercion**: Query parameters (e.g., `?page=1`) are automatically converted to numbers/booleans if defined in the schema.
|
|
69
|
+
- **Type Safety**: Routes now reject invalid requests with `400 Bad Request` and detailed error messages before they reach your handler.
|
|
70
|
+
- **Extensible Validation**: Support for custom validators (e.g., Zod, Joi) via the `Validator` interface.
|
|
71
|
+
- **Route Schema**: New `schema` structure supporting `{ body, query, params, response }`.
|
|
72
|
+
|
|
73
|
+
## [1.1.0] - 2026-01-20
|
|
74
|
+
**"The Database & Batch Engine Update"**
|
|
75
|
+
|
|
76
|
+
### Added
|
|
77
|
+
- **Multi-Database Engine**: New `DatabaseManager` supporting multiple database backends with connection pooling.
|
|
78
|
+
- **Database Adapters**: Built-in, zero-dependency adapters for:
|
|
79
|
+
- **PostgreSQL**: High-performance pooling via `pg`.
|
|
80
|
+
- **MongoDB**: Native query and aggregation support via `mongodb`.
|
|
81
|
+
- **Memory**: In-memory database for testing and prototyping.
|
|
82
|
+
- **Smart Query Fusion**: `QueryCoalescer` automatically merges identical queries (e.g., `SELECT ... WHERE id = ?`) into single batched queries (e.g., `WHERE id IN (...)`) to reduce network roundtrips.
|
|
83
|
+
- **Batch Execution Engine**: New `BatchExecutor` allows clients to send multiple operations in a single HTTP request, automatically routed to fused database queries.
|
|
84
|
+
- **Dynamic Imports**: Database drivers (`pg`, `mongodb`) are now optional peer dependencies, keeping the core lightweight.
|
|
85
|
+
- **Flexible Registration**: Support for bringing your own pre-initialized database connections via `registerConnection()`.
|
|
86
|
+
|
|
87
|
+
## [1.0.0] - 2026-01-19
|
|
88
|
+
**"The Enterprise Release"**
|
|
89
|
+
|
|
90
|
+
### Added
|
|
91
|
+
- **Simplification**: Introduced `createHttpApp()` for instant, Express-like server setup.
|
|
92
|
+
- **WebSocket Support**: Full WebSocket upgrade handling via `app.websocket()` and `WebSocketManager`.
|
|
93
|
+
- **Cookie Management**: Native cookie parsing and serialization support (`ctx.cookies`, `ctx.setCookie`).
|
|
94
|
+
- **Body Parsing**: Integrated `BodyParser` for automatic JSON and URL-encoded body handling.
|
|
95
|
+
- **Developer Experience**: Enhanced logging with color-coded status and precise timing.
|
|
96
|
+
|
|
97
|
+
### Changed
|
|
98
|
+
- **Architecture**: Complete codebase restructuring into modular domains (`core`, `router`, `middleware`, `utils`).
|
|
99
|
+
- **Refactoring**: Decoupled monolithic `server.ts` into specialized components.
|
|
100
|
+
- **Imports**: Optimized internal imports and fixed circular dependencies.
|
|
101
|
+
|
|
102
|
+
### Fixed
|
|
103
|
+
- **Logging**: Fixed 200 OK logs appearing for 404/500 errors.
|
|
104
|
+
- **Timing**: Corrected request duration metrics (0ms bug).
|
|
105
|
+
- **Stability**: Resolved port conflicts and improved error propagation in async handlers.
|
|
106
|
+
|
|
107
|
+
## [0.9.0] - 2025-12-20
|
|
108
|
+
**"The Performance Update"**
|
|
109
|
+
|
|
110
|
+
### Added
|
|
111
|
+
- **Resource Management**: Added `BufferPool` for efficient memory reuse during high-load I/O.
|
|
112
|
+
- **Context Pooling**: Implemented zero-allocation `QHTTPXContext` reuse to reduce GC pressure.
|
|
113
|
+
- **Adaptive Scaling**: Added automatic worker calculation based on CPU cores (`calculateWorkerCount`).
|
|
114
|
+
- **Overload Protection**: Added `isResourceOverloaded` checks for memory/CPU thresholds.
|
|
115
|
+
|
|
116
|
+
### Changed
|
|
117
|
+
- **Performance**: Optimized request pipeline to minimize closure allocations.
|
|
118
|
+
|
|
119
|
+
## [0.8.0] - 2025-11-15
|
|
120
|
+
**"The Task Engine Update"**
|
|
121
|
+
|
|
122
|
+
### Added
|
|
123
|
+
- **Background Tasks**: Introduced `TaskEngine` and `Scheduler` for async job processing.
|
|
124
|
+
- **API**: Added `app.task()` for registering job handlers and `app.enqueue()` for dispatching jobs.
|
|
125
|
+
- **Observability**: Added `/metrics` endpoint exposing task queue depths and worker status.
|
|
126
|
+
|
|
127
|
+
## [0.5.0] - 2025-10-01
|
|
128
|
+
**"The Middleware Update"**
|
|
129
|
+
|
|
130
|
+
### Added
|
|
131
|
+
- **Middleware Pipeline**: Implemented `app.use()` and the recursive middleware execution model.
|
|
132
|
+
- **Standard Middleware**: Added built-in middleware for:
|
|
133
|
+
- `cors`: Cross-Origin Resource Sharing support.
|
|
134
|
+
- `static`: Efficient static file serving.
|
|
135
|
+
- `security`: Helmet-like security headers.
|
|
136
|
+
- `logger`: Request/Response logging.
|
|
137
|
+
|
|
138
|
+
## [0.1.0] - 2025-09-01
|
|
139
|
+
**"Genesis"**
|
|
140
|
+
|
|
141
|
+
### Added
|
|
142
|
+
- **Core Server**: Initial HTTP server implementation using Node.js native `http` module.
|
|
143
|
+
- **Routing**: High-performance Radix Tree router (O(1) lookup) for dynamic and static routes.
|
|
144
|
+
- **Context API**: Unified `ctx` object wrapping `req` and `res` (inspired by Koa/Fastify).
|
|
145
|
+
- **JSON Support**: Basic `ctx.json()` helper.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Quantam Open Source
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,343 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
<img src="https://placehold.co/200x200?text=QHTTPX" alt="QHTTPX Logo" width="200" height="200" />
|
|
3
|
+
</div>
|
|
4
|
+
|
|
5
|
+
# QHTTPX
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/qhttpx)
|
|
8
|
+
[](https://github.com/Quantam-Open-Source/qhttpx/blob/main/LICENSE)
|
|
9
|
+
[](https://www.npmjs.com/package/qhttpx)
|
|
10
|
+
[](http://makeapullrequest.com)
|
|
11
|
+
|
|
12
|
+
**URL:** https://qhttpx.gridrr.com
|
|
13
|
+
|
|
14
|
+
QHTTPX is a high-performance, concurrency-native hybrid HTTP runtime for Node.js, designed to outperform traditional frameworks like Express and Fastify under real-world load, even on low-resource machines (1GB RAM and small CPUs).
|
|
15
|
+
|
|
16
|
+
It is built from the ground up for:
|
|
17
|
+
- Extreme concurrency
|
|
18
|
+
- Non-blocking execution
|
|
19
|
+
- Adaptive scaling
|
|
20
|
+
- Zero-waste resource usage
|
|
21
|
+
- Async-first, task-aware scheduling
|
|
22
|
+
|
|
23
|
+
QHTTPX is not just a web framework. It is a runtime engine for HTTP, background tasks, and streaming workloads sharing one unified scheduler.
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Vision
|
|
28
|
+
|
|
29
|
+
- One engine.
|
|
30
|
+
- Millions of concurrent connections.
|
|
31
|
+
- No blocking. No stalls. No wasted CPU.
|
|
32
|
+
- From 1GB VPS to multi-core servers — same code, linear scale.
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Key Features
|
|
37
|
+
|
|
38
|
+
### 1. Concurrency-Native Core
|
|
39
|
+
- Cooperative async scheduler
|
|
40
|
+
- Backpressure-aware pipelines
|
|
41
|
+
- No blocking in hot paths
|
|
42
|
+
- Request, stream, and task execution share the same engine
|
|
43
|
+
|
|
44
|
+
### 2. Hybrid Runtime
|
|
45
|
+
QHTTPX runs:
|
|
46
|
+
- HTTP requests
|
|
47
|
+
- Streaming responses
|
|
48
|
+
- Background jobs
|
|
49
|
+
- Long-running async workflows
|
|
50
|
+
|
|
51
|
+
All inside one unified concurrency model.
|
|
52
|
+
|
|
53
|
+
### 3. Ultra-Fast Routing
|
|
54
|
+
- Radix tree based
|
|
55
|
+
- Zero regex
|
|
56
|
+
- O(1) static route resolution
|
|
57
|
+
- Minimal allocations per request
|
|
58
|
+
|
|
59
|
+
### 4. Resource-Aware Scaling
|
|
60
|
+
- Auto worker scaling
|
|
61
|
+
- CPU pressure detection
|
|
62
|
+
- Memory pressure detection
|
|
63
|
+
- Adaptive queue limits
|
|
64
|
+
- Graceful overload handling (no crashes, no OOM)
|
|
65
|
+
|
|
66
|
+
### 5. Zero-Overhead Pipeline
|
|
67
|
+
- Flattened async middleware
|
|
68
|
+
- No deep stacks
|
|
69
|
+
- No promise churn
|
|
70
|
+
- Context reuse and pooling
|
|
71
|
+
|
|
72
|
+
### 7. Full-Stack Ready
|
|
73
|
+
- **Native Ecosystem**: Works with `jose` (JWT), `ioredis`, `Prisma`, `Drizzle`.
|
|
74
|
+
- **Advanced Static Files**: Streaming, Range Requests (Video), and Caching.
|
|
75
|
+
- **Real-Time**: Built-in SSE and WebSocket Rooms.
|
|
76
|
+
- **Multipart**: Native file upload support.
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## Installation (Preview)
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
npm install qhttpx
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## Basic Usage
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
import { createHttpApp } from "qhttpx";
|
|
92
|
+
|
|
93
|
+
// Create an app (Express-style)
|
|
94
|
+
// Automatically includes: CORS, Security Headers, Logging, Body Parsing
|
|
95
|
+
const app = createHttpApp();
|
|
96
|
+
|
|
97
|
+
app.get("/", (ctx) => {
|
|
98
|
+
ctx.json({ message: "Hello from QHTTPX" });
|
|
99
|
+
});
|
|
100
|
+
|
|
101
|
+
// Cookie & Helper Support
|
|
102
|
+
app.get("/hello", (ctx) => {
|
|
103
|
+
ctx.setCookie("name", "QHTTPX");
|
|
104
|
+
ctx.html("<h1>Hello World</h1>");
|
|
105
|
+
});
|
|
106
|
+
|
|
107
|
+
app.listen(3000, "127.0.0.1").then(({ port }) => {
|
|
108
|
+
console.log(`Server running at http://localhost:${port}`);
|
|
109
|
+
});
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
## Features
|
|
113
|
+
|
|
114
|
+
### 🍪 Built-in Cookie Support
|
|
115
|
+
RFC-compliant cookie parsing and serialization out of the box.
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
app.get('/', (ctx) => {
|
|
119
|
+
const token = ctx.cookies['token'];
|
|
120
|
+
ctx.setCookie('visited', 'true', { httpOnly: true, maxAge: 3600 });
|
|
121
|
+
});
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### 🛠️ DX Helpers
|
|
125
|
+
Built-in helpers for common tasks:
|
|
126
|
+
- `ctx.json(data, status)`
|
|
127
|
+
- `ctx.html(content, status)`
|
|
128
|
+
- `ctx.send(body, status)`
|
|
129
|
+
- `ctx.redirect(url, status)`
|
|
130
|
+
|
|
131
|
+
## Advanced Usage
|
|
132
|
+
|
|
133
|
+
For full control over the runtime configuration:
|
|
134
|
+
|
|
135
|
+
```ts
|
|
136
|
+
import { QHTTPX } from "qhttpx";
|
|
137
|
+
|
|
138
|
+
const app = new QHTTPX({
|
|
139
|
+
workers: "auto",
|
|
140
|
+
maxConcurrency: 1000,
|
|
141
|
+
requestTimeoutMs: 2_000,
|
|
142
|
+
maxMemoryBytes: 512 * 1024 * 1024,
|
|
143
|
+
});
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
## Core API
|
|
149
|
+
|
|
150
|
+
### Server
|
|
151
|
+
|
|
152
|
+
```ts
|
|
153
|
+
new QHTTPX(options);
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
**Options**
|
|
157
|
+
|
|
158
|
+
| Option | Description |
|
|
159
|
+
| ----------------- | ------------------------------------------------ |
|
|
160
|
+
| `workers` | Number of workers or `"auto"` |
|
|
161
|
+
| `maxConcurrency` | Hard limit for in-flight scheduled tasks |
|
|
162
|
+
| `requestTimeoutMs`| Per-request timeout in milliseconds |
|
|
163
|
+
| `maxMemoryBytes` | RSS threshold for returning 503 overload |
|
|
164
|
+
|
|
165
|
+
### Routing
|
|
166
|
+
|
|
167
|
+
```ts
|
|
168
|
+
app.get(path, handler);
|
|
169
|
+
app.post(path, handler);
|
|
170
|
+
app.put(path, handler);
|
|
171
|
+
app.delete(path, handler);
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
**Example**
|
|
175
|
+
|
|
176
|
+
```ts
|
|
177
|
+
app.get("/users/:id", ctx => {
|
|
178
|
+
return ctx.json({ id: ctx.params.id });
|
|
179
|
+
});
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
---
|
|
183
|
+
|
|
184
|
+
## Middleware
|
|
185
|
+
|
|
186
|
+
```ts
|
|
187
|
+
app.use(async (ctx, next) => {
|
|
188
|
+
const start = Date.now();
|
|
189
|
+
await next();
|
|
190
|
+
const duration = Date.now() - start;
|
|
191
|
+
ctx.res.setHeader("x-response-time", `${duration}ms`);
|
|
192
|
+
});
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
### Built-in helpers
|
|
196
|
+
|
|
197
|
+
```ts
|
|
198
|
+
import {
|
|
199
|
+
createCorsMiddleware,
|
|
200
|
+
createSecurityHeadersMiddleware,
|
|
201
|
+
createStaticMiddleware,
|
|
202
|
+
createLoggerMiddleware,
|
|
203
|
+
} from "qhttpx";
|
|
204
|
+
|
|
205
|
+
app.use(createCorsMiddleware());
|
|
206
|
+
app.use(createSecurityHeadersMiddleware());
|
|
207
|
+
app.use(
|
|
208
|
+
createStaticMiddleware({
|
|
209
|
+
root: "./public",
|
|
210
|
+
index: "index.html",
|
|
211
|
+
fallthrough: true,
|
|
212
|
+
}),
|
|
213
|
+
);
|
|
214
|
+
app.use(createLoggerMiddleware());
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
These helpers provide:
|
|
218
|
+
|
|
219
|
+
- CORS headers and preflight handling
|
|
220
|
+
- Security headers (CSP, referrer policy, X-Frame-Options, etc.)
|
|
221
|
+
- Static file serving from a directory
|
|
222
|
+
- Structured request logging with pluggable sink
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## Context
|
|
227
|
+
|
|
228
|
+
Each request receives a high-performance context:
|
|
229
|
+
|
|
230
|
+
- `ctx.req` – raw Node request
|
|
231
|
+
- `ctx.res` – raw Node response
|
|
232
|
+
- `ctx.body` – parsed body (JSON for application/json, otherwise Buffer)
|
|
233
|
+
- `ctx.query` – parsed query parameters
|
|
234
|
+
- `ctx.params` – route params from the path
|
|
235
|
+
- `ctx.json()` – fast JSON response helper
|
|
236
|
+
- `ctx.send()` – buffer / text response helper
|
|
237
|
+
|
|
238
|
+
### Streaming helpers
|
|
239
|
+
|
|
240
|
+
QHTTPX also exposes helpers for streaming and Server-Sent Events:
|
|
241
|
+
|
|
242
|
+
```ts
|
|
243
|
+
import { createSseStream, sendStream } from "qhttpx";
|
|
244
|
+
|
|
245
|
+
app.get("/events", (ctx) => {
|
|
246
|
+
const sse = createSseStream(ctx, { retryMs: 2000 });
|
|
247
|
+
sse.send({ message: "hello" });
|
|
248
|
+
sse.close();
|
|
249
|
+
});
|
|
250
|
+
|
|
251
|
+
app.get("/download", async (ctx) => {
|
|
252
|
+
const fileStream = fs.createReadStream("big-file.dat");
|
|
253
|
+
await sendStream(ctx, fileStream, {
|
|
254
|
+
contentType: "application/octet-stream",
|
|
255
|
+
status: 200,
|
|
256
|
+
});
|
|
257
|
+
});
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
---
|
|
261
|
+
|
|
262
|
+
## Hybrid Task Engine (v0.2+)
|
|
263
|
+
|
|
264
|
+
```ts
|
|
265
|
+
app.task("email-worker", async job => {
|
|
266
|
+
// background execution using same scheduler as HTTP
|
|
267
|
+
});
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
The same scheduler that powers HTTP requests also powers background tasks and long-running async workflows.
|
|
271
|
+
|
|
272
|
+
---
|
|
273
|
+
|
|
274
|
+
## Built-in Observability
|
|
275
|
+
|
|
276
|
+
**Endpoints**
|
|
277
|
+
- `/__qhttpx/health`
|
|
278
|
+
- `/__qhttpx/metrics`
|
|
279
|
+
|
|
280
|
+
**Metrics include**
|
|
281
|
+
- Requests per second
|
|
282
|
+
- Active workers
|
|
283
|
+
- Event loop lag
|
|
284
|
+
- Memory usage
|
|
285
|
+
- Queue depth
|
|
286
|
+
- P50 / P95 / P99 latency
|
|
287
|
+
|
|
288
|
+
---
|
|
289
|
+
|
|
290
|
+
## Performance Goals
|
|
291
|
+
|
|
292
|
+
QHTTPX v1.0 targets:
|
|
293
|
+
|
|
294
|
+
| Metric | Goal |
|
|
295
|
+
| ------------- | ------------------------------------- |
|
|
296
|
+
| Throughput | Faster than Fastify by 15–30% |
|
|
297
|
+
| Latency | Lower P99 than Fastify |
|
|
298
|
+
| Memory | Lower per-connection footprint |
|
|
299
|
+
| Cold start | < 30ms |
|
|
300
|
+
| 1GB RAM | No OOM under 100k concurrent connections |
|
|
301
|
+
|
|
302
|
+
---
|
|
303
|
+
|
|
304
|
+
## Philosophy
|
|
305
|
+
|
|
306
|
+
- Fastify optimizes HTTP.
|
|
307
|
+
- Express simplifies developer experience.
|
|
308
|
+
- QHTTPX optimizes execution itself.
|
|
309
|
+
|
|
310
|
+
It treats HTTP as just one workload type inside a high-performance concurrency engine.
|
|
311
|
+
|
|
312
|
+
---
|
|
313
|
+
|
|
314
|
+
## Roadmap
|
|
315
|
+
|
|
316
|
+
### v0.1.0
|
|
317
|
+
- Core runtime
|
|
318
|
+
- Scheduler
|
|
319
|
+
- Radix router
|
|
320
|
+
- HTTP/1.1
|
|
321
|
+
- Worker scaling
|
|
322
|
+
- Metrics
|
|
323
|
+
- Graceful shutdown
|
|
324
|
+
|
|
325
|
+
### v0.5.0
|
|
326
|
+
- HTTP/2
|
|
327
|
+
- Zero-copy serializers
|
|
328
|
+
- C++ / WASM hot path
|
|
329
|
+
- Kernel socket tuning
|
|
330
|
+
|
|
331
|
+
### v1.0.0
|
|
332
|
+
- Outperform Fastify in real benchmarks
|
|
333
|
+
- Hybrid task + HTTP engine
|
|
334
|
+
- Distributed mesh mode
|
|
335
|
+
- Quantam workflow native integration
|
|
336
|
+
|
|
337
|
+
---
|
|
338
|
+
|
|
339
|
+
## Positioning Statement
|
|
340
|
+
|
|
341
|
+
**QHTTPX**
|
|
342
|
+
A concurrency-native hybrid HTTP runtime built to extract maximum throughput from minimal hardware, designed to outperform Fastify and Express under extreme load while serving as the execution core for next-generation async systems.
|
|
343
|
+
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "qhttpx",
|
|
3
|
+
"version": "1.8.0",
|
|
4
|
+
"description": "**URL:** https://qhttpx.gridrr.com",
|
|
5
|
+
"main": "index.js",
|
|
6
|
+
"bin": {
|
|
7
|
+
"qhttpx": "./dist/src/cli/index.js"
|
|
8
|
+
},
|
|
9
|
+
"directories": {
|
|
10
|
+
"doc": "docs"
|
|
11
|
+
},
|
|
12
|
+
"scripts": {
|
|
13
|
+
"build": "tsc -p tsconfig.json",
|
|
14
|
+
"lint": "eslint src tests --ext .ts",
|
|
15
|
+
"test": "vitest run",
|
|
16
|
+
"example": "npx tsx examples/api-server.ts",
|
|
17
|
+
"bench": "npm run build && node dist/src/benchmarks/simple-json.js",
|
|
18
|
+
"bench:quantam": "npm run build && node dist/src/benchmarks/quantam-users.js",
|
|
19
|
+
"bench:compare": "npm run build && node dist/src/benchmarks/compare-frameworks.js",
|
|
20
|
+
"bench:ultra": "npm run build && node dist/src/benchmarks/ultra-mode.js"
|
|
21
|
+
},
|
|
22
|
+
"keywords": [],
|
|
23
|
+
"author": "",
|
|
24
|
+
"license": "ISC",
|
|
25
|
+
"type": "commonjs",
|
|
26
|
+
"devDependencies": {
|
|
27
|
+
"@types/autocannon": "^7.12.7",
|
|
28
|
+
"@types/better-sqlite3": "^7.6.13",
|
|
29
|
+
"@types/busboy": "^1.5.4",
|
|
30
|
+
"@types/express": "^5.0.6",
|
|
31
|
+
"@types/ioredis": "^4.28.10",
|
|
32
|
+
"@types/mongodb": "^4.0.6",
|
|
33
|
+
"@types/node": "^25.0.9",
|
|
34
|
+
"@types/pg": "^8.16.0",
|
|
35
|
+
"@types/ws": "^8.18.1",
|
|
36
|
+
"@typescript-eslint/eslint-plugin": "^8.53.0",
|
|
37
|
+
"@typescript-eslint/parser": "^8.53.0",
|
|
38
|
+
"autocannon": "^8.0.0",
|
|
39
|
+
"eslint": "^9.39.2",
|
|
40
|
+
"eslint-config-prettier": "^10.1.8",
|
|
41
|
+
"eslint-plugin-prettier": "^5.5.5",
|
|
42
|
+
"mongodb": "^7.0.0",
|
|
43
|
+
"pg": "^8.17.1",
|
|
44
|
+
"prettier": "^3.8.0",
|
|
45
|
+
"tsx": "^4.21.0",
|
|
46
|
+
"typescript": "^5.9.3",
|
|
47
|
+
"vitest": "^4.0.17"
|
|
48
|
+
},
|
|
49
|
+
"dependencies": {
|
|
50
|
+
"better-sqlite3": "^12.6.2",
|
|
51
|
+
"busboy": "^1.6.0",
|
|
52
|
+
"express": "^5.2.1",
|
|
53
|
+
"fast-json-stringify": "^5.15.1",
|
|
54
|
+
"fastify": "^5.7.1",
|
|
55
|
+
"pino": "^10.2.0",
|
|
56
|
+
"pino-pretty": "^13.1.3",
|
|
57
|
+
"quantam-async": "^0.1.1",
|
|
58
|
+
"ws": "^8.19.0",
|
|
59
|
+
"zod": "^4.3.5"
|
|
60
|
+
}
|
|
61
|
+
}
|