qhttpx 1.8.0

package/examples/api-server.ts

@@ -0,0 +1,254 @@
+import { createHash } from 'crypto';
+import { IncomingMessage } from 'http';
+import { Duplex } from 'stream';
+import { createHttpApp, HttpError } from '../src/index';
+
+// 1. Initialize the application (includes CORS, Security Headers, Logging)
+const app = createHttpApp({
+  metricsEnabled: true,
+  workers: 1,
+});
+
+// 2. Mock Database
+const users = new Map<string, { id: string; name: string; role: string }>();
+
+// Seed some data
+users.set('1', { id: '1', name: 'Alice', role: 'admin' });
+users.set('2', { id: '2', name: 'Bob', role: 'user' });
+
+// 3. Register Background Tasks
+app.task('send-email', async (payload: any) => {
+  // Simulate heavy work
+  await new Promise((resolve) => setTimeout(resolve, 500));
+  console.log(`[Background Job] Sending email to ${payload.email}: "${payload.subject}"`);
+});
+
+// 4. Define Routes
+
+// Root
+app.get('/', (ctx) => {
+  ctx.json({
+    message: 'Welcome to QHTTPX Example API',
+    endpoints: [
+      'GET /api/users',
+      'POST /api/users',
+      'GET /api/users/:id',
+      'POST /api/jobs/email',
+      'WS /ws',
+      'GET /api/cookies',
+      'GET /api/redirect'
+    ],
+    documentation: 'https://github.com/your-repo/qhttpx'
+  });
+});
+
+app.get('/api/cookies', (ctx) => {
+  // Read cookies
+  const visited = parseInt(ctx.cookies['visited'] || '0');
+  
+  // Set cookie
+  ctx.setCookie('visited', (visited + 1).toString(), {
+    path: '/',
+    maxAge: 3600, // 1 hour
+    httpOnly: true,
+  });
+
+  ctx.json({
+    message: 'Cookie demo',
+    visited: visited + 1,
+    allCookies: ctx.cookies
+  });
+});
+
+app.get('/api/redirect', (ctx) => {
+  ctx.redirect('/api/users');
+});
+
+// User Routes using the Chainable Builder
+app.route('/api/users')
+  .get((ctx) => {
+    const userList = Array.from(users.values());
+    ctx.json({ data: userList, count: userList.length });
+  })
+  .post(async (ctx) => {
+    if (!ctx.body || typeof ctx.body !== 'object') {
+       ctx.json({ error: 'Invalid body' }, 400);
+       return;
+    }
+    
+    const body = ctx.body as any;
+    if (!body.name || !body.role) {
+      ctx.json({ error: 'Missing name or role' }, 400);
+      return;
+    }
+
+    const id = (users.size + 1).toString();
+    const newUser = { id, name: body.name, role: body.role };
+    users.set(id, newUser);
+
+    ctx.json({ message: 'User created', user: newUser }, 201);
+  });
+
+app.route('/api/users/:id')
+  .get((ctx) => {
+    const { id } = ctx.params;
+    const user = users.get(id);
+    
+    if (!user) {
+      ctx.json({ error: 'User not found' }, 404);
+      return;
+    }
+
+    ctx.json({ data: user });
+  })
+  .delete((ctx) => {
+    const { id } = ctx.params;
+    if (users.delete(id)) {
+      ctx.json({ message: 'User deleted' });
+    } else {
+      ctx.json({ error: 'User not found' }, 404);
+    }
+  });
+
+// Job Route
+app.post('/api/jobs/email', async (ctx) => {
+  const body = ctx.body as any;
+  if (!body.email) {
+    ctx.json({ error: 'Email required' }, 400);
+    return;
+  }
+
+  await app.enqueue('send-email', { 
+    email: body.email, 
+    subject: 'Welcome to QHTTPX!' 
+  });
+
+  ctx.json({ message: 'Email job queued', status: 'pending' }, 202);
+});
+
+// WebSocket Route
+app.upgrade('/ws', handleWebSocketEcho);
+
+// Error handling demo
+app.get('/error', () => {
+  throw new Error('Something went wrong!');
+});
+
+// Custom Error Handlers (optional, defaults are good)
+app.setNotFoundHandler((ctx) => {
+  ctx.json({ error: 'Not Found', path: ctx.url.pathname }, 404);
+});
+
+app.setErrorHandler((err, ctx) => {
+  if (err instanceof HttpError) {
+    ctx.json({ error: err.message, code: err.code, details: err.details }, err.status);
+    return;
+  }
+  ctx.json({ error: 'Internal Server Error' }, 500);
+});
+
+// 5. Start Server
+const PORT = process.env.PORT ? parseInt(process.env.PORT) : 3000;
+app.listen(PORT, '0.0.0.0').then(({ port }) => {
+  console.log(`\n🚀 Server running at http://localhost:${port}`);
+  console.log(`   Try: curl http://localhost:${port}/api/users`);
+});
+
+// --- Helpers ---
+
+function createWebSocketAccept(key: string): string {
+  return createHash('sha1')
+    .update(key + '258EAFA5-E914-47DA-95CA-C5AB0DC85B11')
+    .digest('base64');
+}
+
+function handleWebSocketEcho(req: IncomingMessage, socket: Duplex, head: Buffer) {
+  void head;
+
+  const rawKeyHeader = req.headers['sec-websocket-key'];
+  let keyHeader: string | undefined;
+  if (typeof rawKeyHeader === 'string') {
+    keyHeader = rawKeyHeader;
+  } else if (Array.isArray(rawKeyHeader)) {
+    const values = rawKeyHeader as string[];
+    if (values.length > 0) {
+      keyHeader = values[0];
+    }
+  }
+
+  const key = keyHeader ?? '';
+  const accept = createWebSocketAccept(key);
+  const responseLines = [
+    'HTTP/1.1 101 Switching Protocols',
+    'Upgrade: websocket',
+    'Connection: Upgrade',
+    `Sec-WebSocket-Accept: ${accept}`,
+    '',
+    '',
+  ];
+  socket.write(responseLines.join('\r\n'));
+
+  socket.on('data', (buffer) => {
+    if (buffer.length < 2) return;
+
+    const opcode = buffer[0] & 0x0f;
+    const masked = (buffer[1] & 0x80) !== 0;
+    let payloadLength = buffer[1] & 0x7f;
+    let offset = 2;
+
+    if (payloadLength === 126) {
+      if (buffer.length < offset + 2) return;
+      payloadLength = buffer.readUInt16BE(offset);
+      offset += 2;
+    } else if (payloadLength === 127) {
+      return; // Too large for this demo
+    }
+
+    if (buffer.length < offset + payloadLength) return;
+
+    let maskingKey: Buffer | undefined;
+    if (masked) {
+      maskingKey = buffer.subarray(offset, offset + 4);
+      offset += 4;
+    }
+
+    const payload = buffer.subarray(offset, offset + payloadLength);
+
+    if (masked && maskingKey) {
+      for (let i = 0; i < payload.length; i += 1) {
+        payload[i] ^= maskingKey[i % 4];
+      }
+    }
+
+    if (opcode === 0x8) { // Close
+      socket.end();
+      return;
+    }
+
+    if (opcode === 0x1) { // Text
+      const message = payload.toString('utf8');
+      const textBytes = Buffer.from(message, 'utf8');
+      const length = textBytes.length;
+
+      let header: Buffer;
+      if (length < 126) {
+        header = Buffer.alloc(2);
+        header[0] = 0x81;
+        header[1] = length;
+      } else if (length < 65536) {
+        header = Buffer.alloc(4);
+        header[0] = 0x81;
+        header[1] = 126;
+        header.writeUInt16BE(length, 2);
+      } else {
+        return; // Too large
+      }
+
+      const frame = Buffer.concat([header, textBytes]);
+      socket.write(frame);
+    }
+  });
+
+  socket.on('end', () => socket.end());
+  socket.on('error', () => socket.destroy());
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "qhttpx",
+  "version": "1.8.0",
+  "description": "**URL:** https://qhttpx.gridrr.com",
+  "main": "index.js",
+  "bin": {
+    "qhttpx": "./dist/src/cli/index.js"
+  },
+  "directories": {
+    "doc": "docs"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src tests --ext .ts",
+    "test": "vitest run",
+    "example": "npx tsx examples/api-server.ts",
+    "bench": "npm run build && node dist/src/benchmarks/simple-json.js",
+    "bench:quantam": "npm run build && node dist/src/benchmarks/quantam-users.js",
+    "bench:compare": "npm run build && node dist/src/benchmarks/compare-frameworks.js",
+    "bench:ultra": "npm run build && node dist/src/benchmarks/ultra-mode.js"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "devDependencies": {
+    "@types/autocannon": "^7.12.7",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/busboy": "^1.5.4",
+    "@types/express": "^5.0.6",
+    "@types/ioredis": "^4.28.10",
+    "@types/mongodb": "^4.0.6",
+    "@types/node": "^25.0.9",
+    "@types/pg": "^8.16.0",
+    "@types/ws": "^8.18.1",
+    "@typescript-eslint/eslint-plugin": "^8.53.0",
+    "@typescript-eslint/parser": "^8.53.0",
+    "autocannon": "^8.0.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "mongodb": "^7.0.0",
+    "pg": "^8.17.1",
+    "prettier": "^3.8.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  },
+  "dependencies": {
+    "better-sqlite3": "^12.6.2",
+    "busboy": "^1.6.0",
+    "express": "^5.2.1",
+    "fast-json-stringify": "^5.15.1",
+    "fastify": "^5.7.1",
+    "pino": "^10.2.0",
+    "pino-pretty": "^13.1.3",
+    "quantam-async": "^0.1.1",
+    "ws": "^8.19.0",
+    "zod": "^4.3.5"
+  }
+}

package/src/benchmarks/compare-frameworks.ts

@@ -0,0 +1,149 @@
+import autocannon from 'autocannon';
+import fastify from 'fastify';
+import express, { Request, Response } from 'express';
+import { QHTTPX } from '../index';
+
+type BenchResult = {
+  name: string;
+  total: number;
+  sent: number;
+  rps: number;
+  p99: number;
+};
+
+async function runAutocannon(name: string, url: string): Promise<BenchResult> {
+  const result = await autocannon({
+    url,
+    connections: 200,
+    pipelining: 10,
+    duration: 10,
+  });
+
+  const total = result.requests.total;
+  const sent = result.requests.sent;
+  const rps = result.requests.average;
+  const p99 = result.latency.p99;
+
+  console.log(
+    `${name} bench: total=${total} (sent=${sent}) req, ` +
+      `${rps.toFixed(0)} req/sec, p99=${p99.toFixed(
+        1,
+      )}ms, connections=${result.connections}, pipelining=${
+        result.pipelining
+      }`,
+  );
+
+  return {
+    name,
+    total,
+    sent,
+    rps,
+    p99,
+  };
+}
+
+async function startQHTTPX() {
+  const payloadBuffer = Buffer.from(
+    JSON.stringify({ message: 'hello from qhttpx' }),
+  );
+  const app = new QHTTPX({
+    maxConcurrency: 1024,
+    metricsEnabled: false,
+    jsonSerializer: () => payloadBuffer,
+  });
+
+  app.get('/json', (ctx) => {
+    ctx.json({ message: 'hello from qhttpx' });
+  });
+
+  const { port } = await app.listen(0, '127.0.0.1');
+  const url = `http://127.0.0.1:${port}/json`;
+  return { app, url };
+}
+
+async function startFastify() {
+  const app = fastify();
+
+  app.get('/json', async () => {
+    return { message: 'hello from fastify' };
+  });
+
+  await app.listen({ port: 0, host: '127.0.0.1' });
+  const address = app.server.address();
+  if (!address || typeof address === 'string') {
+    throw new Error('Fastify address not available');
+  }
+  const url = `http://127.0.0.1:${address.port}/json`;
+  return { app, url };
+}
+
+async function startExpress() {
+  const app = express();
+  app.get('/json', (_req: Request, res: Response) => {
+    res.json({ message: 'hello from express' });
+  });
+
+  const server = await new Promise<import('http').Server>((resolve) => {
+    const s = app.listen(0, '127.0.0.1', () => {
+      resolve(s);
+    });
+  });
+  const address = server.address();
+  if (!address || typeof address === 'string') {
+    throw new Error('Express address not available');
+  }
+  const url = `http://127.0.0.1:${address.port}/json`;
+  return { app, url, server };
+}
+
+async function run() {
+  const results: BenchResult[] = [];
+
+  const qhttpx = await startQHTTPX();
+  try {
+    const r = await runAutocannon('QHTTPX', qhttpx.url);
+    results.push(r);
+  } finally {
+    await qhttpx.app.close();
+  }
+
+  const fast = await startFastify();
+  try {
+    const r = await runAutocannon('Fastify', fast.url);
+    results.push(r);
+  } finally {
+    await fast.app.close();
+  }
+
+  const exp = await startExpress();
+  try {
+    const r = await runAutocannon('Express', exp.url);
+    results.push(r);
+  } finally {
+    await new Promise<void>((resolve, reject) => {
+      exp.server.close((err: unknown) => {
+        if (err) {
+          reject(err);
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+
+  console.log('\nSummary:');
+  for (const r of results) {
+    console.log(
+      `${r.name}: ${r.rps.toFixed(0)} req/sec, p99=${r.p99.toFixed(
+        1,
+      )}ms, total=${r.total}`,
+    );
+  }
+
+  process.exit(0);
+}
+
+run().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/benchmarks/quantam-users.ts

@@ -0,0 +1,70 @@
+import { quantam } from 'quantam-async';
+import { QHTTPX } from '../index';
+
+async function run() {
+  const app = new QHTTPX({
+    maxConcurrency: 512,
+    requestTimeoutMs: 10_000,
+  });
+
+  app.get('/json', (ctx) => {
+    ctx.json({ message: 'hello from qhttpx' });
+  });
+
+  const { port } = await app.listen(0, '127.0.0.1');
+
+  const url = `http://127.0.0.1:${port}/json`;
+
+  const requestsPerUser = 10;
+  const userCount = 10_000;
+  const maxConcurrentUsers = 1_000;
+
+  const flow = quantam<number>()
+    .name('user-flow')
+    .step(async (userId) => {
+      for (let i = 0; i < requestsPerUser; i += 1) {
+        const response = await fetch(url);
+        if (!response.ok) {
+          throw new Error(
+            `user ${userId} request ${i} failed with status ${response.status}`,
+          );
+        }
+        await response.text();
+      }
+      return userId;
+    })
+    .retry(3, 50)
+    .timeout(30_000);
+
+  const inputs: number[] = [];
+  for (let i = 0; i < userCount; i += 1) {
+    inputs.push(i);
+  }
+
+  const start = Date.now();
+  try {
+    await flow.runMany(inputs, {
+      concurrency: maxConcurrentUsers,
+    });
+  } catch (err) {
+    console.error('Quantam runMany error', err);
+  }
+  const durationSec = (Date.now() - start) / 1000;
+  const totalRequests = userCount * requestsPerUser;
+  const rps = totalRequests / durationSec;
+
+  console.log(
+    `Quantam bench: users=${userCount}, requestsPerUser=${requestsPerUser}, ` +
+      `totalRequests=${totalRequests}, duration=${durationSec.toFixed(
+        2,
+      )}s, rps=${rps.toFixed(0)}, concurrency=${maxConcurrentUsers}`,
+  );
+
+  await app.close();
+  process.exit(0);
+}
+
+run().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/benchmarks/simple-json.ts

@@ -0,0 +1,71 @@
+import autocannon from 'autocannon';
+import { QHTTPX } from '../index';
+
+function runAutocannon(url: string): Promise<autocannon.Result> {
+  return new Promise((resolve, reject) => {
+    const instance = autocannon(
+      {
+        url,
+        amount: 10_000,
+        connections: 10_000,
+        pipelining: 1,
+        duration: 10,
+      },
+      (err, result) => {
+        if (err) {
+          reject(err);
+          return;
+        }
+        resolve(result);
+      },
+    );
+
+    instance.on('error', (err) => {
+      reject(err);
+    });
+  });
+}
+
+async function run() {
+  const payloadBuffer = Buffer.from(
+    JSON.stringify({ message: 'hello from qhttpx' }),
+  );
+  const app = new QHTTPX({
+    maxConcurrency: 512,
+    metricsEnabled: false,
+    jsonSerializer: () => payloadBuffer,
+  });
+
+  app.get('/json', (ctx) => {
+    ctx.json({ message: 'hello from qhttpx' });
+  });
+
+  const { port } = await app.listen(0, '127.0.0.1');
+
+  const url = `http://127.0.0.1:${port}/json`;
+
+  const result = await runAutocannon(url);
+
+  autocannon.printResult(result);
+
+  const totalRequests = result.requests.total;
+  const sent = result.requests.sent;
+  const avgRps = result.requests.average.toFixed(0);
+  const p99 = result.latency.p99.toFixed(1);
+  const connections = result.connections;
+  const pipelining = result.pipelining;
+  // Summary line that shows up clearly in CI/dev logs
+  console.log(
+    `QHTTPX bench: total=${totalRequests} (sent=${sent}) req, ` +
+      `${avgRps} req/sec, p99=${p99}ms, connections=${connections}, ` +
+      `pipelining=${pipelining}`,
+  );
+
+  await app.close();
+  process.exit(0);
+}
+
+run().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});