qhttpx 1.8.0

package/tests/middleware.test.ts

@@ -0,0 +1,137 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { QHTTPX } from '../src/index';
+
+describe('QHTTPX middleware pipeline', () => {
+  let app: QHTTPX | undefined;
+
+  afterEach(async () => {
+    if (app) {
+      await app.close();
+      app = undefined;
+    }
+  });
+
+  it('runs middleware in order with await next()', async () => {
+    app = new QHTTPX();
+
+    const calls: string[] = [];
+
+    app.use(async (ctx, next) => {
+      calls.push('m1-before');
+      await next();
+      calls.push('m1-after');
+    });
+
+    app.use(async (ctx, next) => {
+      calls.push('m2-before');
+      await next();
+      calls.push('m2-after');
+    });
+
+    app.get('/', (ctx) => {
+      calls.push('handler');
+      ctx.send('ok');
+    });
+
+    const { port } = await app.listen(0, '127.0.0.1');
+
+    const response = await fetch(`http://127.0.0.1:${port}/`);
+    expect(response.status).toBe(200);
+
+    expect(calls).toEqual([
+      'm1-before',
+      'm2-before',
+      'handler',
+      'm2-after',
+      'm1-after',
+    ]);
+  });
+
+  it('allows middleware to modify response headers', async () => {
+    app = new QHTTPX();
+
+    app.use((ctx, next) => {
+      ctx.res.setHeader('x-powered-by', 'qhttpx');
+      return next();
+    });
+
+    app.get('/', (ctx) => {
+      ctx.send('ok');
+    });
+
+    const { port } = await app.listen(0, '127.0.0.1');
+
+    const response = await fetch(`http://127.0.0.1:${port}/`);
+    expect(response.status).toBe(200);
+    const header = response.headers.get('x-powered-by');
+    expect(header).toBe('qhttpx');
+  });
+
+  it('supports auth middleware that short-circuits unauthorized requests', async () => {
+    app = new QHTTPX();
+
+    app.use((ctx, next) => {
+      const auth = ctx.req.headers['authorization'];
+      if (auth !== 'Bearer secret') {
+        ctx.res.statusCode = 401;
+        ctx.res.end('Unauthorized');
+        return;
+      }
+      return next();
+    });
+
+    app.get('/secure', (ctx) => {
+      ctx.send('ok');
+    });
+
+    const { port } = await app.listen(0, '127.0.0.1');
+
+    const unauthorized = await fetch(`http://127.0.0.1:${port}/secure`);
+    expect(unauthorized.status).toBe(401);
+    const unauthorizedText = await unauthorized.text();
+    expect(unauthorizedText).toBe('Unauthorized');
+
+    const authorized = await fetch(`http://127.0.0.1:${port}/secure`, {
+      headers: {
+        authorization: 'Bearer secret',
+      },
+    });
+    expect(authorized.status).toBe(200);
+    const body = await authorized.text();
+    expect(body).toBe('ok');
+  });
+
+  it('supports error-handling middleware that converts errors to JSON', async () => {
+    app = new QHTTPX();
+
+    app.use(async (ctx, next) => {
+      try {
+        await next();
+      } catch (err) {
+        ctx.res.statusCode = 500;
+        ctx.res.setHeader('content-type', 'application/json; charset=utf-8');
+        ctx.res.end(
+          JSON.stringify({
+            error: 'internal',
+            message: err instanceof Error ? err.message : 'unknown',
+          }),
+        );
+      }
+    });
+
+    app.get('/boom', () => {
+      throw new Error('boom');
+    });
+
+    const { port } = await app.listen(0, '127.0.0.1');
+
+    const response = await fetch(`http://127.0.0.1:${port}/boom`);
+    expect(response.status).toBe(500);
+    const json = (await response.json()) as {
+      error: string;
+      message: string;
+    };
+    expect(json.error).toBe('internal');
+    expect(json.message).toBe('boom');
+  });
+});

package/tests/observability.test.ts

@@ -0,0 +1,91 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { QHTTPX } from '../src/index';
+
+describe('QHTTPX observability and health', () => {
+  let app: QHTTPX | undefined;
+
+  afterEach(async () => {
+    if (app) {
+      await app.close();
+      app = undefined;
+    }
+  });
+
+  it('exposes a health endpoint with basic info', async () => {
+    app = new QHTTPX();
+
+    const { port } = await app.listen(0, '127.0.0.1');
+
+    const response = await fetch(
+      `http://127.0.0.1:${port}/__qhttpx/health`,
+    );
+
+    expect(response.status).toBe(200);
+    const json = (await response.json()) as {
+      status: string;
+      name: string;
+      version: string;
+      workers: number;
+    };
+
+    expect(json.status).toBe('ok');
+    expect(typeof json.name).toBe('string');
+    expect(typeof json.version).toBe('string');
+    expect(json.workers).toBeGreaterThan(0);
+  });
+
+  it('exposes metrics for handled requests', async () => {
+    app = new QHTTPX();
+
+    app.get('/ping', (ctx) => {
+      ctx.send('pong');
+    });
+
+    const { port } = await app.listen(0, '127.0.0.1');
+
+    await fetch(`http://127.0.0.1:${port}/ping`);
+    await fetch(`http://127.0.0.1:${port}/ping`);
+
+    const response = await fetch(
+      `http://127.0.0.1:${port}/__qhttpx/metrics`,
+    );
+
+    expect(response.status).toBe(200);
+    const json = (await response.json()) as {
+      totalRequests: number;
+      inFlightRequests: number;
+      latency: { p50: number | null };
+      memory: { rssBytes: number; heapUsedBytes: number };
+      workers: number;
+    };
+
+    expect(json.totalRequests).toBeGreaterThanOrEqual(2);
+    expect(json.inFlightRequests).toBeGreaterThanOrEqual(0);
+    expect(json.latency.p50 === null || json.latency.p50 >= 0).toBe(true);
+    expect(json.memory.rssBytes).toBeGreaterThan(0);
+    expect(json.memory.heapUsedBytes).toBeGreaterThan(0);
+    expect(json.workers).toBeGreaterThan(0);
+  });
+
+  it('propagates and generates x-request-id headers', async () => {
+    app = new QHTTPX();
+
+    app.get('/ping', (ctx) => {
+      ctx.send('pong');
+    });
+
+    const { port } = await app.listen(0, '127.0.0.1');
+
+    const first = await fetch(`http://127.0.0.1:${port}/ping`);
+    const firstId = first.headers.get('x-request-id');
+    expect(firstId === null || firstId.length > 0).toBe(true);
+
+    const second = await fetch(`http://127.0.0.1:${port}/ping`, {
+      headers: {
+        'x-request-id': 'custom-id-123',
+      },
+    });
+    const secondId = second.headers.get('x-request-id');
+    expect(secondId).toBe('custom-id-123');
+  });
+});

package/tests/openapi.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from 'vitest';
+import { QHTTPX } from '../src/core/server';
+import { RouteSchema } from '../src/validation/types';
+
+describe('OpenAPI Generator', () => {
+  it('should generate valid OpenAPI spec from routes', () => {
+    const app = new QHTTPX();
+
+    const userSchema: RouteSchema = {
+      params: {
+        type: 'object',
+        properties: {
+          id: { type: 'string' }
+        }
+      },
+      body: {
+        type: 'object',
+        properties: {
+          name: { type: 'string' },
+          age: { type: 'number', min: 18 }
+        }
+      },
+      response: {
+        type: 'object',
+        properties: {
+          success: { type: 'boolean' }
+        }
+      }
+    };
+
+    app.post('/users/:id', {
+      schema: userSchema,
+      handler: (ctx) => { ctx.json({ success: true }) }
+    });
+
+    app.get('/health', (ctx) => { ctx.send('ok') });
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const spec: any = app.getOpenAPI({
+      info: {
+        title: 'Test API',
+        version: '1.0.0'
+      }
+    });
+
+    // Check basic structure
+    expect(spec.openapi).toBe('3.0.0');
+    expect(spec.info.title).toBe('Test API');
+
+    // Check Path normalization
+    expect(spec.paths['/users/{id}']).toBeDefined();
+    expect(spec.paths['/health']).toBeDefined();
+
+    // Check Operation
+    const postUser = spec.paths['/users/{id}'].post;
+    expect(postUser).toBeDefined();
+
+    // Check Params
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const pathParam = postUser.parameters.find((p: any) => p.name === 'id');
+    expect(pathParam).toBeDefined();
+    expect(pathParam.in).toBe('path');
+    expect(pathParam.required).toBe(true);
+
+    // Check Request Body
+    const bodySchema = postUser.requestBody.content['application/json'].schema;
+    expect(bodySchema.properties.name.type).toBe('string');
+    expect(bodySchema.properties.age.minimum).toBe(18);
+
+    // Check Response
+    const responseSchema = postUser.responses['200'].content['application/json'].schema;
+    expect(responseSchema.properties.success.type).toBe('boolean');
+  });
+});

package/tests/plugin.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from 'vitest';
+import { QHTTPX } from '../src/core/server';
+import { QHTTPXPlugin } from '../src/core/types';
+
+describe('Plugin System', () => {
+  it('should register a simple plugin', async () => {
+    const app = new QHTTPX();
+    let pluginRun = false;
+
+    const myPlugin: QHTTPXPlugin = async (scope) => {
+       pluginRun = true;
+       // eslint-disable-next-line @typescript-eslint/no-explicit-any
+       scope.get('/ping', (ctx: any) => ctx.json({ pong: true }));
+     };
+
+    await app.register(myPlugin);
+
+    expect(pluginRun).toBe(true);
+
+    const { port } = await app.listen(0);
+    const res = await fetch(`http://localhost:${port}/ping`);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ pong: true });
+  });
+
+  it('should handle prefixes', async () => {
+     const app = new QHTTPX();
+
+     const apiPlugin: QHTTPXPlugin = async (scope) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        scope.get('/users', (ctx: any) => ctx.json({ users: [] }));
+     };
+
+    // Register with prefix /v1
+    await app.register(apiPlugin, { prefix: '/v1' });
+
+    const { port } = await app.listen(0);
+    
+    // /v1/users should exist
+    const res = await fetch(`http://localhost:${port}/v1/users`);
+    expect(res.status).toBe(200);
+
+    // /users should NOT exist
+    const res404 = await fetch(`http://localhost:${port}/users`);
+    expect(res404.status).toBe(404);
+  });
+
+  it('should handle nested plugins with concatenated prefixes', async () => {
+    const app = new QHTTPX();
+
+    const usersPlugin: QHTTPXPlugin = async (scope) => {
+       // eslint-disable-next-line @typescript-eslint/no-explicit-any
+       scope.get('/list', (ctx: any) => ctx.json({ list: true }));
+     };
+
+     const v1Plugin: QHTTPXPlugin = async (scope) => {
+       // Register nested plugin under /users
+       await scope.register(usersPlugin, { prefix: '/users' });
+     };
+
+    // Register v1 under /api
+    await app.register(v1Plugin, { prefix: '/api' });
+
+    const { port } = await app.listen(0);
+    
+    // Result should be /api/users/list
+    const res = await fetch(`http://localhost:${port}/api/users/list`);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ list: true });
+  });
+
+  it('should pass options to plugins', async () => {
+     const app = new QHTTPX();
+     // eslint-disable-next-line @typescript-eslint/no-explicit-any
+     let receivedOpts: any;
+
+     const configPlugin: QHTTPXPlugin = async (scope, opts) => {
+        receivedOpts = opts;
+     };
+
+    await app.register(configPlugin, { prefix: '/a', secret: '123' });
+
+    expect(receivedOpts).toEqual({ prefix: '/a', secret: '123' });
+  });
+});

package/tests/plugins.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect } from 'vitest';
+import { QHTTPX } from '../src/core/server';
+import { QHTTPXPlugin, QHTTPXContext } from '../src/core/types';
+import { QHTTPXScope } from '../src/core/scope';
+import { createTestClient } from '../src/testing';
+
+describe('Plugin System', () => {
+  it('should register a simple plugin', async () => {
+    const app = new QHTTPX();
+    
+    const myPlugin: QHTTPXPlugin = (s) => {
+      const scope = s as QHTTPXScope;
+      scope.get('/plugin', (ctx: QHTTPXContext) => {
+        ctx.json({ message: 'Hello from Plugin' });
+      });
+    };
+
+    await app.register(myPlugin);
+
+    const client = createTestClient(app);
+    const res = await client.get('/plugin');
+    
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ message: 'Hello from Plugin' });
+    await client.stop();
+  });
+
+  it('should support scoped prefixes', async () => {
+    const app = new QHTTPX();
+
+    const v1Plugin: QHTTPXPlugin = (s) => {
+      const scope = s as QHTTPXScope;
+      scope.get('/users', (ctx: QHTTPXContext) => {
+        ctx.json({ version: 'v1' });
+      });
+    };
+
+    await app.register(v1Plugin, { prefix: '/v1' });
+
+    const client = createTestClient(app);
+    const res = await client.get('/v1/users');
+    
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ version: 'v1' });
+    await client.stop();
+  });
+
+  it('should support nested plugins', async () => {
+    const app = new QHTTPX();
+
+    const usersPlugin: QHTTPXPlugin = (s) => {
+      const scope = s as QHTTPXScope;
+      scope.get('/list', (ctx: QHTTPXContext) => {
+        ctx.json({ users: [] });
+      });
+    };
+
+    const apiPlugin: QHTTPXPlugin = async (s) => {
+      const scope = s as QHTTPXScope;
+      await scope.register(usersPlugin, { prefix: '/users' });
+    };
+
+    await app.register(apiPlugin, { prefix: '/api' });
+
+    const client = createTestClient(app);
+    const res = await client.get('/api/users/list');
+    
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ users: [] });
+    await client.stop();
+  });
+
+  it('should support plugin options', async () => {
+    const app = new QHTTPX();
+
+    type MyOptions = { secret: string };
+    const authPlugin: QHTTPXPlugin<MyOptions> = (s, options) => {
+      const scope = s as QHTTPXScope;
+      scope.get('/secret', (ctx: QHTTPXContext) => {
+        ctx.json({ secret: options.secret });
+      });
+    };
+
+    await app.register(authPlugin, { secret: 'super-secret' });
+
+    const client = createTestClient(app);
+    const res = await client.get('/secret');
+    
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ secret: 'super-secret' });
+    await client.stop();
+  });
+});

package/tests/rate-limit.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { QHTTPX } from '../src/core/server';
+import { rateLimit } from '../src/middleware/rate-limit';
+
+describe('Aegis Rate Limiter', () => {
+  let app: QHTTPX;
+  let port: number;
+
+  beforeEach(async () => {
+    app = new QHTTPX();
+  });
+
+  afterEach(() => {
+    // Cleanup if needed
+  });
+
+  it('should block requests exceeding the limit', async () => {
+    app.use(rateLimit({
+      windowMs: 1000,
+      max: 2, // Allow 2 requests
+      message: { error: 'Blocked' }
+    }));
+
+    app.get('/', (ctx) => ctx.json({ ok: true }));
+
+    const { port: p } = await app.listen(0);
+    port = p;
+    const url = `http://localhost:${port}`;
+
+    // 1st request (OK)
+    const r1 = await fetch(url);
+    expect(r1.status).toBe(200);
+    expect(r1.headers.get('x-ratelimit-remaining')).toBe('1');
+
+    // 2nd request (OK)
+    const r2 = await fetch(url);
+    expect(r2.status).toBe(200);
+    expect(r2.headers.get('x-ratelimit-remaining')).toBe('0');
+
+    // 3rd request (Blocked)
+    const r3 = await fetch(url);
+    expect(r3.status).toBe(429);
+    expect(await r3.json()).toEqual({ error: 'Blocked' });
+    expect(r3.headers.get('retry-after')).toBeDefined();
+  });
+
+  it('should reset after window expires', async () => {
+    app.use(rateLimit({
+      windowMs: 100, // Short window
+      max: 1
+    }));
+
+    app.get('/', (ctx) => ctx.json({ ok: true }));
+
+    const { port: p } = await app.listen(0);
+    const url = `http://localhost:${p}`;
+
+    // 1st (OK)
+    await fetch(url);
+
+    // 2nd (Blocked)
+    const r2 = await fetch(url);
+    expect(r2.status).toBe(429);
+
+    // Wait for window
+    await new Promise(r => setTimeout(r, 150));
+
+    // 3rd (OK)
+    const r3 = await fetch(url);
+    expect(r3.status).toBe(200);
+  });
+
+  it('should support custom key generators (e.g. per API key)', async () => {
+    app.use(rateLimit({
+      windowMs: 1000,
+      max: 1,
+      keyGenerator: (ctx) => ctx.req.headers['x-api-key'] as string || 'anon'
+    }));
+
+    app.get('/', (ctx) => ctx.json({ ok: true }));
+
+    const { port: p } = await app.listen(0);
+    const url = `http://localhost:${p}`;
+
+    // User A (OK)
+    const r1 = await fetch(url, { headers: { 'x-api-key': 'userA' } });
+    expect(r1.status).toBe(200);
+
+    // User B (OK - different key)
+    const r2 = await fetch(url, { headers: { 'x-api-key': 'userB' } });
+    expect(r2.status).toBe(200);
+
+    // User A Again (Blocked)
+    const r3 = await fetch(url, { headers: { 'x-api-key': 'userA' } });
+    expect(r3.status).toBe(429);
+  });
+});

package/tests/resources.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+  calculateWorkerCount,
+  isResourceOverloaded,
+} from '../src/core/resources';
+import { QHTTPX } from '../src/index';
+
+describe('Resource helpers', () => {
+  it('calculates worker count for fixed numbers', () => {
+    expect(calculateWorkerCount(1)).toBe(1);
+    expect(calculateWorkerCount(4)).toBe(4);
+    expect(calculateWorkerCount(0)).toBe(1);
+    expect(calculateWorkerCount(-5)).toBe(1);
+  });
+
+  it('detects memory overload based on thresholds', () => {
+    expect(
+      isResourceOverloaded(
+        { rssBytes: 2000 },
+        {
+          maxRssBytes: 1000,
+        },
+      ),
+    ).toBe(true);
+
+    expect(
+      isResourceOverloaded(
+        { rssBytes: 500 },
+        {
+          maxRssBytes: 1000,
+        },
+      ),
+    ).toBe(false);
+  });
+});
+
+describe('QHTTPX resource-aware behavior', () => {
+  it('returns 503 when memory usage exceeds maxMemoryBytes', async () => {
+    const originalMemoryUsage = process.memoryUsage;
+    const fakeMemoryUsage = vi.fn(() => ({
+      ...originalMemoryUsage(),
+      rss: 10_000_000_000,
+    }));
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (process as any).memoryUsage = fakeMemoryUsage;
+
+    const app = new QHTTPX({
+      maxMemoryBytes: 1_000_000,
+    });
+    const { port } = await app.listen(0, '127.0.0.1');
+
+    app.get('/', (ctx) => {
+      ctx.send('ok');
+    });
+
+    const response = await fetch(`http://127.0.0.1:${port}/`);
+    expect(response.status).toBe(503);
+
+    await app.close();
+    (process as unknown as { memoryUsage: typeof originalMemoryUsage }).memoryUsage =
+      originalMemoryUsage;
+  });
+});