qhttpx 1.8.0

package/tests/task-metrics.test.ts

@@ -0,0 +1,78 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { QHTTPX } from '../src/index';
+
+type TaskMetricsJson = {
+  tasks: {
+    registeredTasks: number;
+    totalEnqueued: number;
+    totalCompleted: number;
+    totalFailed: number;
+    totalOverloaded: number;
+    totalRetried?: number;
+  };
+};
+
+describe('Task Metrics', () => {
+  let app: QHTTPX | undefined;
+
+  afterEach(async () => {
+    if (app) {
+      await app.close();
+      app = undefined;
+    }
+  });
+
+  it('exposes task metrics in /__qhttpx/metrics', async () => {
+    app = new QHTTPX();
+    
+    // Register a simple task
+    app.task('simple-task', async () => {
+      // do nothing
+    });
+
+    const { port } = await app.listen(0, '127.0.0.1');
+
+    // Enqueue the task a few times
+    await app.enqueue('simple-task', {});
+    await app.enqueue('simple-task', {});
+
+    // Allow some time for async tasks to complete
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    const response = await fetch(`http://127.0.0.1:${port}/__qhttpx/metrics`);
+    expect(response.status).toBe(200);
+
+    const json = (await response.json()) as TaskMetricsJson;
+
+    expect(json.tasks).toBeDefined();
+    expect(json.tasks.registeredTasks).toBe(1);
+    expect(json.tasks.totalEnqueued).toBe(2);
+    expect(json.tasks.totalCompleted).toBe(2);
+    expect(json.tasks.totalFailed).toBe(0);
+    expect(json.tasks.totalOverloaded).toBe(0);
+  });
+
+  it('counts failed tasks', async () => {
+    app = new QHTTPX();
+    
+    app.task('failing-task', async () => {
+      throw new Error('Task failed');
+    }, { maxRetries: 1 }); // 1 retry
+
+    const { port } = await app.listen(0, '127.0.0.1');
+
+    try {
+      await app.enqueue('failing-task', {});
+    } catch {
+    }
+
+    // Allow time for retry and failure
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    const response = await fetch(`http://127.0.0.1:${port}/__qhttpx/metrics`);
+    const json = (await response.json()) as TaskMetricsJson;
+
+    expect(json.tasks.totalFailed).toBe(1);
+    expect(json.tasks.totalRetried).toBe(1); // 1 retry attempt
+  });
+});

package/tests/tasks.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it, vi } from 'vitest';
+import { QHTTPX } from '../src/index';
+
+describe('Task engine', () => {
+  it('registers and executes a task', async () => {
+    const app = new QHTTPX();
+
+    const seen: unknown[] = [];
+
+    app.task('echo', async (payload) => {
+      seen.push(payload);
+    });
+
+    await app.enqueue('echo', { hello: 'world' });
+
+    expect(seen).toHaveLength(1);
+    expect(seen[0]).toEqual({ hello: 'world' });
+  });
+
+  it('retries failing tasks according to maxRetries', async () => {
+    const app = new QHTTPX();
+
+    const spy = vi.fn();
+    let attempts = 0;
+
+    app.task(
+      'sometimes-fails',
+      () => {
+        spy();
+        attempts += 1;
+        if (attempts < 3) {
+          throw new Error('fail');
+        }
+      },
+      { maxRetries: 5 },
+    );
+
+    await app.enqueue('sometimes-fails', null);
+
+    expect(spy).toHaveBeenCalledTimes(3);
+  });
+
+  it('propagates errors after exceeding retries', async () => {
+    const app = new QHTTPX();
+
+    app.task(
+      'always-fails',
+      () => {
+        throw new Error('boom');
+      },
+      { maxRetries: 1 },
+    );
+
+    await expect(app.enqueue('always-fails', null)).rejects.toThrow('boom');
+  });
+
+  it('integrates with HTTP route that enqueues a job', async () => {
+    const app = new QHTTPX();
+    const seen: string[] = [];
+
+    app.task('job', async (payload) => {
+      seen.push(payload as string);
+    });
+
+    app.post('/enqueue', async (ctx) => {
+      const body = ctx.body as { value: string };
+      await app.enqueue('job', body.value);
+      ctx.json({ ok: true });
+    });
+
+    const { port } = await app.listen(0, '127.0.0.1');
+
+    const response = await fetch(`http://127.0.0.1:${port}/enqueue`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({ value: 'hello' }),
+    });
+
+    expect(response.status).toBe(200);
+    const json = (await response.json()) as { ok: boolean };
+    expect(json.ok).toBe(true);
+
+    expect(seen).toEqual(['hello']);
+
+    await app.close();
+  });
+});
+

package/tests/testing.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import { QHTTPX, createTestClient } from '../src';
+
+describe('Testing utilities', () => {
+  it('creates a test client and handles requests', async () => {
+    const app = new QHTTPX();
+
+    app.get('/hello', (ctx) => {
+      ctx.json({ message: 'world' });
+    });
+
+    app.post('/echo', (ctx) => {
+      ctx.json(ctx.body);
+    });
+
+    const client = createTestClient(app);
+
+    try {
+      const res1 = await client.get('/hello');
+      expect(res1.status).toBe(200);
+      expect(await res1.json()).toEqual({ message: 'world' });
+
+      const res2 = await client.post('/echo', { foo: 'bar' });
+      expect(res2.status).toBe(200);
+      expect(await res2.json()).toEqual({ foo: 'bar' });
+    } finally {
+      await client.stop();
+    }
+  });
+
+  it('handles custom headers and raw body', async () => {
+    const app = new QHTTPX();
+
+    app.post('/raw', (ctx) => {
+      ctx.send(ctx.req.headers['x-custom'] as string);
+    });
+
+    const client = createTestClient(app);
+
+    try {
+      const res = await client.post('/raw', 'raw-body', {
+        headers: {
+          'x-custom': 'custom-value',
+          'content-type': 'text/plain',
+        },
+      });
+      expect(res.status).toBe(200);
+      expect(await res.text()).toBe('custom-value');
+    } finally {
+      await client.stop();
+    }
+  });
+});

package/tests/validation.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { QHTTPX } from '../src/core/server';
+import { RouteSchema } from '../src/validation/types';
+
+describe('Validation System', () => {
+  let app: QHTTPX;
+
+  afterEach(async () => {
+    if (app) await app.close();
+  });
+
+  it('should validate request body and return 400 on failure', async () => {
+    app = new QHTTPX();
+
+    const schema: RouteSchema = {
+      body: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', min: 3 },
+          age: { type: 'number', min: 18 }
+        }
+      }
+    };
+
+    app.post('/user', {
+      schema,
+      handler: (ctx: import('../src/core/types').QHTTPXContext) => {
+        ctx.json({ status: 'ok', body: ctx.body });
+      }
+    });
+
+    const { port } = await app.listen(0);
+
+    // Invalid request (age too low)
+    const res1 = await fetch(`http://localhost:${port}/user`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name: 'Alice', age: 10 })
+    });
+
+    expect(res1.status).toBe(400);
+    const data1 = await res1.json();
+    expect(data1.error).toBe('Validation Error');
+    expect(data1.details).toContain('age');
+
+    // Valid request
+    const res2 = await fetch(`http://localhost:${port}/user`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name: 'Alice', age: 20 })
+    });
+
+    expect(res2.status).toBe(200);
+    const data2 = await res2.json();
+    expect(data2.body).toEqual({ name: 'Alice', age: 20 });
+  });
+
+  it('should validate and coerce query parameters', async () => {
+    app = new QHTTPX();
+
+    const schema: RouteSchema = {
+      query: {
+        type: 'object',
+        properties: {
+          page: { type: 'number', min: 1 },
+          sort: { type: 'string', enum: ['asc', 'desc'] }
+        }
+      }
+    };
+
+    app.get('/items', {
+      schema,
+      handler: (ctx: import('../src/core/types').QHTTPXContext) => {
+        // ctx.query should have numbers now
+        ctx.json({ 
+          page: ctx.query.page, 
+          pageType: typeof ctx.query.page,
+          sort: ctx.query.sort 
+        });
+      }
+    });
+
+    const { port } = await app.listen(0);
+
+    // Valid query
+    const res1 = await fetch(`http://localhost:${port}/items?page=5&sort=desc`);
+    expect(res1.status).toBe(200);
+    const data1 = await res1.json();
+    expect(data1.page).toBe(5);
+    expect(data1.pageType).toBe('number'); // Coercion worked
+    expect(data1.sort).toBe('desc');
+
+    // Invalid query
+    const res2 = await fetch(`http://localhost:${port}/items?page=0&sort=foo`);
+    expect(res2.status).toBe(400);
+  });
+
+  it('should support legacy response schema (no validation)', async () => {
+    app = new QHTTPX();
+
+    // Legacy schema: just a JSON schema at root
+    const schema = {
+      type: 'object',
+      properties: {
+        hello: { type: 'string' }
+      }
+    };
+
+    app.get('/legacy', {
+      schema,
+      handler: (ctx: import('../src/core/types').QHTTPXContext) => {
+        // If validation ran, it might fail because ctx.body is undefined or not matching
+        // But here we check if it IGNORES validation and uses it for serialization
+        ctx.json({ hello: 'world', extra: 'hidden' });
+      }
+    });
+
+    const { port } = await app.listen(0);
+
+    const res = await fetch(`http://localhost:${port}/legacy`);
+    expect(res.status).toBe(200);
+    const data = await res.json();
+    expect(data.hello).toBe('world');
+    expect(data.extra).toBeUndefined(); // fast-json-stringify filters extra fields
+  });
+});

package/tests/websocket.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from 'vitest';
+import * as net from 'net';
+import WebSocket from 'ws';
+import { QHTTPX } from '../src';
+
+describe('WebSocket upgrade', () => {
+  it('handles websocket upgrade for registered path', async () => {
+    const app = new QHTTPX();
+    let upgraded = false;
+
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    app.upgrade('/ws', (ws, req) => {
+      upgraded = true;
+      ws.close();
+    });
+
+    const { port } = await app.listen(0, '127.0.0.1');
+
+    const ws = new WebSocket(`ws://127.0.0.1:${port}/ws`);
+    
+    await new Promise<void>((resolve, reject) => {
+      ws.on('open', () => {
+        resolve();
+      });
+      ws.on('error', (err) => {
+        reject(err);
+      });
+    });
+
+    expect(upgraded).toBe(true);
+    ws.close();
+    await app.close();
+  });
+
+  it('destroys socket when no upgrade handler is registered for path', async () => {
+    const app = new QHTTPX();
+    const { port } = await app.listen(0, '127.0.0.1');
+
+    const socket = net.createConnection({ port, host: '127.0.0.1' });
+
+    const done = new Promise<void>((resolve) => {
+      let finished = false;
+      const finish = () => {
+        if (!finished) {
+          finished = true;
+          resolve();
+        }
+      };
+      socket.on('end', finish);
+      socket.on('close', finish);
+      socket.on('error', () => {
+        finish();
+      });
+      setTimeout(finish, 500);
+    });
+
+    const requestLines = [
+      'GET /no-ws HTTP/1.1',
+      'Host: 127.0.0.1',
+      'Upgrade: websocket',
+      'Connection: Upgrade',
+      '',
+      '',
+    ];
+
+    socket.write(requestLines.join('\r\n'));
+
+    await done;
+    await app.close();
+  });
+
+  it('supports rooms and broadcasting', async () => {
+    const app = new QHTTPX();
+    
+    app.upgrade('/chat', (ws, req) => {
+      const url = new URL(req.url || '', 'http://localhost');
+      const room = url.searchParams.get('room');
+      if (room) {
+        ws.join(room);
+      }
+    });
+
+    app.post('/broadcast', (ctx) => {
+      const { room, message } = ctx.body as { room: string; message: string };
+      app.websocket.to(room).emit(message);
+      ctx.json({ success: true });
+    });
+
+    const { port } = await app.listen(0, '127.0.0.1');
+    const baseUrl = `ws://127.0.0.1:${port}/chat`;
+
+    // Client A in room1
+    const wsA = new WebSocket(`${baseUrl}?room=room1`);
+    const msgsA: string[] = [];
+    wsA.on('message', (data) => msgsA.push(data.toString()));
+
+    // Client B in room1
+    const wsB = new WebSocket(`${baseUrl}?room=room1`);
+    const msgsB: string[] = [];
+    wsB.on('message', (data) => msgsB.push(data.toString()));
+
+    // Client C in room2
+    const wsC = new WebSocket(`${baseUrl}?room=room2`);
+    const msgsC: string[] = [];
+    wsC.on('message', (data) => msgsC.push(data.toString()));
+
+    await Promise.all([
+      new Promise<void>((resolve) => wsA.on('open', () => resolve())),
+      new Promise<void>((resolve) => wsB.on('open', () => resolve())),
+      new Promise<void>((resolve) => wsC.on('open', () => resolve())),
+    ]);
+
+    // Broadcast to room1
+    // We need to make a POST request.
+    // Since we are inside test, we can use fetch or http.request.
+    // Or just use app.websocket directly if we can access it?
+    // We can access app.websocket directly here since we have app instance.
+    app.websocket.to('room1').emit('hello room1');
+
+    // Wait a bit for messages
+    await new Promise((resolve) => setTimeout(resolve, 100));
+
+    expect(msgsA).toContain('hello room1');
+    expect(msgsB).toContain('hello room1');
+    expect(msgsC).not.toContain('hello room1');
+
+    wsA.close();
+    wsB.close();
+    wsC.close();
+    await app.close();
+  });
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "rootDir": ".",
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "types": ["node", "vitest"]
+  },
+  "include": ["src", "tests", "vitest.config.*"]
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['tests/**/*.test.ts'],
+    exclude: ['dist/**', 'node_modules/**'],
+  },
+});
+