portok 1.0.0

package/test/helpers/mock-server.mjs

@@ -0,0 +1,305 @@
+/**
+ * Mock HTTP/WebSocket server for testing portokd
+ * Provides configurable responses, delays, and health status
+ */
+
+import http from 'node:http';
+
+// Dynamically import ws to handle when not available
+let WebSocketServer;
+try {
+  const ws = await import('ws');
+  WebSocketServer = ws.WebSocketServer;
+} catch {
+  WebSocketServer = null;
+}
+
+/**
+ * Create a mock server with configurable behavior
+ * @param {Object} options
+ * @param {number} options.port - Port to listen on (0 for random)
+ * @param {number} options.healthStatus - HTTP status for /health endpoint (default: 200)
+ * @param {number} options.responseDelay - Delay in ms before responding (default: 0)
+ * @param {string} options.responseBody - Body to return for requests (default: 'OK')
+ * @param {boolean} options.enableWebSocket - Enable WebSocket support (default: true)
+ * @returns {Promise<MockServer>}
+ */
+export async function createMockServer(options = {}) {
+  const config = {
+    port: options.port || 0,
+    healthStatus: options.healthStatus ?? 200,
+    responseDelay: options.responseDelay || 0,
+    responseBody: options.responseBody || 'OK',
+    enableWebSocket: options.enableWebSocket !== false,
+  };
+
+  const requests = [];
+  let healthy = config.healthStatus >= 200 && config.healthStatus < 300;
+  let currentHealthStatus = config.healthStatus;
+
+  const server = http.createServer(async (req, res) => {
+    // Record request
+    requests.push({
+      method: req.method,
+      url: req.url,
+      headers: { ...req.headers },
+      timestamp: Date.now(),
+    });
+
+    // Apply delay if configured
+    if (config.responseDelay > 0) {
+      await new Promise(resolve => setTimeout(resolve, config.responseDelay));
+    }
+
+    // Health endpoint
+    if (req.url === '/health' || req.url.startsWith('/health?')) {
+      res.writeHead(currentHealthStatus, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ status: healthy ? 'healthy' : 'unhealthy' }));
+      return;
+    }
+
+    // Echo endpoint - returns request info
+    if (req.url === '/echo') {
+      let body = '';
+      for await (const chunk of req) {
+        body += chunk;
+      }
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        method: req.method,
+        url: req.url,
+        headers: req.headers,
+        body,
+      }));
+      return;
+    }
+
+    // Slow endpoint - takes longer to respond
+    if (req.url === '/slow') {
+      await new Promise(resolve => setTimeout(resolve, 2000));
+      res.writeHead(200, { 'Content-Type': 'text/plain' });
+      res.end('Slow response');
+      return;
+    }
+
+    // Error endpoint - returns 500
+    if (req.url === '/error') {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Internal Server Error' }));
+      return;
+    }
+
+    // Stream endpoint - sends chunked data
+    if (req.url === '/stream') {
+      res.writeHead(200, {
+        'Content-Type': 'text/plain',
+        'Transfer-Encoding': 'chunked',
+      });
+      for (let i = 0; i < 5; i++) {
+        res.write(`chunk ${i}\n`);
+        await new Promise(resolve => setTimeout(resolve, 100));
+      }
+      res.end();
+      return;
+    }
+
+    // Default response
+    res.writeHead(200, { 'Content-Type': 'text/plain' });
+    res.end(config.responseBody);
+  });
+
+  // WebSocket support
+  let wss = null;
+  const wsConnections = [];
+
+  if (config.enableWebSocket && WebSocketServer) {
+    wss = new WebSocketServer({ server });
+
+    wss.on('connection', (ws) => {
+      wsConnections.push(ws);
+
+      ws.on('message', (message) => {
+        // Echo messages back
+        ws.send(`echo: ${message}`);
+      });
+
+      ws.on('close', () => {
+        const idx = wsConnections.indexOf(ws);
+        if (idx !== -1) wsConnections.splice(idx, 1);
+      });
+
+      ws.send('connected');
+    });
+  }
+
+  // Start server
+  await new Promise((resolve, reject) => {
+    server.listen(config.port, '127.0.0.1', () => resolve());
+    server.on('error', reject);
+  });
+
+  const actualPort = server.address().port;
+
+  return {
+    port: actualPort,
+    url: `http://127.0.0.1:${actualPort}`,
+    server,
+    wss,
+
+    // Get recorded requests
+    getRequests() {
+      return [...requests];
+    },
+
+    // Clear recorded requests
+    clearRequests() {
+      requests.length = 0;
+    },
+
+    // Set health status dynamically
+    setHealthy(isHealthy) {
+      healthy = isHealthy;
+      currentHealthStatus = isHealthy ? 200 : 503;
+    },
+
+    // Set specific health status code
+    setHealthStatus(statusCode) {
+      currentHealthStatus = statusCode;
+      healthy = statusCode >= 200 && statusCode < 300;
+    },
+
+    // Get WebSocket connections
+    getWebSocketConnections() {
+      return [...wsConnections];
+    },
+
+    // Broadcast to all WebSocket clients
+    broadcast(message) {
+      wsConnections.forEach(ws => {
+        if (ws.readyState === 1) { // OPEN
+          ws.send(message);
+        }
+      });
+    },
+
+    // Close server
+    async close() {
+      // Close WebSocket connections
+      wsConnections.forEach(ws => ws.close());
+
+      // Close WebSocket server
+      if (wss) {
+        await new Promise(resolve => wss.close(resolve));
+      }
+
+      // Close HTTP server
+      await new Promise(resolve => server.close(resolve));
+    },
+  };
+}
+
+/**
+ * Create the portokd server for testing
+ * Sets up environment and spawns the daemon
+ */
+export async function createTestDaemon(options = {}) {
+  const {
+    listenPort = 0,
+    targetPort,
+    adminToken = 'test-token-12345',
+    healthPath = '/health',
+    drainMs = 1000,
+    rollbackWindowMs = 5000,
+    rollbackCheckEveryMs = 500,
+    rollbackFailThreshold = 2,
+  } = options;
+
+  // Set environment
+  process.env.LISTEN_PORT = String(listenPort);
+  process.env.INITIAL_TARGET_PORT = String(targetPort);
+  process.env.ADMIN_TOKEN = adminToken;
+  process.env.HEALTH_PATH = healthPath;
+  process.env.DRAIN_MS = String(drainMs);
+  process.env.ROLLBACK_WINDOW_MS = String(rollbackWindowMs);
+  process.env.ROLLBACK_CHECK_EVERY_MS = String(rollbackCheckEveryMs);
+  process.env.ROLLBACK_FAIL_THRESHOLD = String(rollbackFailThreshold);
+  process.env.STATE_FILE = `/tmp/portok-test-${Date.now()}.json`;
+
+  // Import the daemon (will start based on env vars)
+  const daemon = await import('../../portokd.mjs');
+
+  // Wait for server to be ready
+  await new Promise(resolve => setTimeout(resolve, 100));
+
+  const actualPort = daemon.server.address()?.port || listenPort;
+
+  return {
+    port: actualPort,
+    url: `http://127.0.0.1:${actualPort}`,
+    adminToken,
+    daemon,
+
+    async close() {
+      daemon.server.close();
+    },
+  };
+}
+
+/**
+ * Helper to make admin requests
+ */
+export async function adminRequest(baseUrl, endpoint, options = {}) {
+  const { method = 'GET', token = 'test-token-12345', body } = options;
+
+  const fetchOptions = {
+    method,
+    headers: {
+      'x-admin-token': token,
+      'Content-Type': 'application/json',
+    },
+  };
+
+  if (body) {
+    fetchOptions.body = JSON.stringify(body);
+  }
+
+  const response = await fetch(`${baseUrl}${endpoint}`, fetchOptions);
+  const data = await response.json().catch(() => ({}));
+
+  return {
+    ok: response.ok,
+    status: response.status,
+    data,
+  };
+}
+
+/**
+ * Helper to wait for a condition
+ */
+export async function waitFor(condition, timeout = 5000, interval = 100) {
+  const startTime = Date.now();
+
+  while (Date.now() - startTime < timeout) {
+    if (await condition()) {
+      return true;
+    }
+    await new Promise(resolve => setTimeout(resolve, interval));
+  }
+
+  throw new Error(`Condition not met within ${timeout}ms`);
+}
+
+/**
+ * Helper to get a free port
+ */
+export async function getFreePort() {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer();
+    server.listen(0, '127.0.0.1', () => {
+      const port = server.address().port;
+      server.close(() => resolve(port));
+    });
+    server.on('error', reject);
+  });
+}
+

package/test/metrics.test.mjs

@@ -0,0 +1,328 @@
+/**
+ * Metrics Tests
+ * Tests metrics collection: counters, RPS, inflight tracking
+ */
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert';
+import { spawn } from 'node:child_process';
+import { createMockServer, getFreePort, waitFor } from './helpers/mock-server.mjs';
+
+describe('Metrics', () => {
+  let mockServer;
+  let proxyPort;
+  let daemonProcess;
+  const adminToken = 'test-token-metrics';
+
+  before(async () => {
+    mockServer = await createMockServer({ port: 0 });
+    proxyPort = await getFreePort();
+
+    daemonProcess = spawn('node', ['portokd.mjs'], {
+      env: {
+        ...process.env,
+        LISTEN_PORT: String(proxyPort),
+        INITIAL_TARGET_PORT: String(mockServer.port),
+        ADMIN_TOKEN: adminToken,
+        STATE_FILE: `/tmp/portok-metrics-test-${Date.now()}.json`,
+        DRAIN_MS: '1000',
+        ROLLBACK_WINDOW_MS: '60000',
+        ROLLBACK_CHECK_EVERY_MS: '5000',
+        ROLLBACK_FAIL_THRESHOLD: '3',
+        ADMIN_RATE_LIMIT: '1000',
+      },
+      stdio: 'pipe',
+    });
+
+    await waitFor(async () => {
+      try {
+        const res = await fetch(`http://127.0.0.1:${proxyPort}/__status`, {
+          headers: { 'x-admin-token': adminToken },
+        });
+        return res.ok;
+      } catch {
+        return false;
+      }
+    }, 5000);
+  });
+
+  after(async () => {
+    if (daemonProcess) {
+      daemonProcess.kill('SIGTERM');
+    }
+    if (mockServer) await mockServer.close();
+  });
+
+  describe('Metrics Endpoint', () => {
+    it('should return all required metrics fields', async () => {
+      const response = await fetch(`http://127.0.0.1:${proxyPort}/__metrics`, {
+        headers: { 'x-admin-token': adminToken },
+      });
+
+      assert.strictEqual(response.status, 200);
+
+      const metrics = await response.json();
+
+      // Check all required fields exist
+      assert.ok('startedAt' in metrics);
+      assert.ok('inflight' in metrics);
+      assert.ok('inflightMax' in metrics);
+      assert.ok('totalRequests' in metrics);
+      assert.ok('totalProxyErrors' in metrics);
+      assert.ok('statusCounters' in metrics);
+      assert.ok('rollingRps60' in metrics);
+      assert.ok('health' in metrics);
+      assert.ok('lastProxyError' in metrics);
+    });
+
+    it('should have valid startedAt timestamp', async () => {
+      const response = await fetch(`http://127.0.0.1:${proxyPort}/__metrics`, {
+        headers: { 'x-admin-token': adminToken },
+      });
+      const metrics = await response.json();
+
+      const startedAt = new Date(metrics.startedAt);
+      assert.ok(!isNaN(startedAt.getTime()));
+      assert.ok(startedAt <= new Date());
+    });
+  });
+
+  describe('Request Counting', () => {
+    it('should count total requests', async () => {
+      // Get initial count
+      const beforeRes = await fetch(`http://127.0.0.1:${proxyPort}/__metrics`, {
+        headers: { 'x-admin-token': adminToken },
+      });
+      const before = await beforeRes.json();
+
+      // Make some proxied requests
+      for (let i = 0; i < 5; i++) {
+        await fetch(`http://127.0.0.1:${proxyPort}/`);
+      }
+
+      // Get new count
+      const afterRes = await fetch(`http://127.0.0.1:${proxyPort}/__metrics`, {
+        headers: { 'x-admin-token': adminToken },
+      });
+      const after = await afterRes.json();
+
+      // Should have increased by at least 5 (proxied requests, not admin)
+      assert.ok(after.totalRequests >= before.totalRequests + 5);
+    });
+  });
+
+  describe('Status Counters', () => {
+    it('should count 2xx responses', async () => {
+      const beforeRes = await fetch(`http://127.0.0.1:${proxyPort}/__metrics`, {
+        headers: { 'x-admin-token': adminToken },
+      });
+      const before = await beforeRes.json();
+
+      // Make successful requests
+      for (let i = 0; i < 3; i++) {
+        await fetch(`http://127.0.0.1:${proxyPort}/`);
+      }
+
+      const afterRes = await fetch(`http://127.0.0.1:${proxyPort}/__metrics`, {
+        headers: { 'x-admin-token': adminToken },
+      });
+      const after = await afterRes.json();
+
+      assert.ok(after.statusCounters['2xx'] >= before.statusCounters['2xx'] + 3);
+    });
+
+    it('should count 5xx responses', async () => {
+      const beforeRes = await fetch(`http://127.0.0.1:${proxyPort}/__metrics`, {
+        headers: { 'x-admin-token': adminToken },
+      });
+      const before = await beforeRes.json();
+
+      // Make requests that return 500
+      for (let i = 0; i < 2; i++) {
+        await fetch(`http://127.0.0.1:${proxyPort}/error`);
+      }
+
+      const afterRes = await fetch(`http://127.0.0.1:${proxyPort}/__metrics`, {
+        headers: { 'x-admin-token': adminToken },
+      });
+      const after = await afterRes.json();
+
+      assert.ok(after.statusCounters['5xx'] >= before.statusCounters['5xx'] + 2);
+    });
+
+    it('should have all status counter categories', async () => {
+      const response = await fetch(`http://127.0.0.1:${proxyPort}/__metrics`, {
+        headers: { 'x-admin-token': adminToken },
+      });
+      const metrics = await response.json();
+
+      assert.ok('2xx' in metrics.statusCounters);
+      assert.ok('3xx' in metrics.statusCounters);
+      assert.ok('4xx' in metrics.statusCounters);
+      assert.ok('5xx' in metrics.statusCounters);
+    });
+  });
+
+  describe('Inflight Tracking', () => {
+    it('should track inflight requests', async () => {
+      // Make requests to slow endpoint
+      const promises = [];
+      for (let i = 0; i < 3; i++) {
+        promises.push(fetch(`http://127.0.0.1:${proxyPort}/slow`));
+      }
+
+      // Check inflight while requests are in progress
+      await new Promise(resolve => setTimeout(resolve, 500));
+
+      const metricsRes = await fetch(`http://127.0.0.1:${proxyPort}/__metrics`, {
+        headers: { 'x-admin-token': adminToken },
+      });
+      const metrics = await metricsRes.json();
+
+      // Should have some inflight requests
+      // Note: timing-dependent, so just check inflightMax was tracked
+      assert.ok(metrics.inflightMax >= 0);
+
+      // Wait for slow requests to complete
+      await Promise.all(promises);
+    });
+
+    it('should track inflightMax', async () => {
+      const metricsRes = await fetch(`http://127.0.0.1:${proxyPort}/__metrics`, {
+        headers: { 'x-admin-token': adminToken },
+      });
+      const metrics = await metricsRes.json();
+
+      // inflightMax should be >= current inflight
+      assert.ok(metrics.inflightMax >= metrics.inflight);
+    });
+  });
+
+  describe('Rolling RPS', () => {
+    it('should calculate rolling RPS over 60 seconds', async () => {
+      // Make some requests
+      for (let i = 0; i < 10; i++) {
+        await fetch(`http://127.0.0.1:${proxyPort}/`);
+      }
+
+      const metricsRes = await fetch(`http://127.0.0.1:${proxyPort}/__metrics`, {
+        headers: { 'x-admin-token': adminToken },
+      });
+      const metrics = await metricsRes.json();
+
+      // RPS should be a number >= 0
+      assert.ok(typeof metrics.rollingRps60 === 'number');
+      assert.ok(metrics.rollingRps60 >= 0);
+    });
+
+    it('should update RPS as requests come in', async () => {
+      const beforeRes = await fetch(`http://127.0.0.1:${proxyPort}/__metrics`, {
+        headers: { 'x-admin-token': adminToken },
+      });
+      const before = await beforeRes.json();
+
+      // Make burst of requests
+      const promises = [];
+      for (let i = 0; i < 20; i++) {
+        promises.push(fetch(`http://127.0.0.1:${proxyPort}/`));
+      }
+      await Promise.all(promises);
+
+      const afterRes = await fetch(`http://127.0.0.1:${proxyPort}/__metrics`, {
+        headers: { 'x-admin-token': adminToken },
+      });
+      const after = await afterRes.json();
+
+      // RPS should have increased
+      assert.ok(after.rollingRps60 >= before.rollingRps60);
+    });
+  });
+
+  describe('Health Metrics', () => {
+    it('should track health status', async () => {
+      const metricsRes = await fetch(`http://127.0.0.1:${proxyPort}/__metrics`, {
+        headers: { 'x-admin-token': adminToken },
+      });
+      const metrics = await metricsRes.json();
+
+      assert.ok('activePortOk' in metrics.health);
+      assert.ok('lastCheckedAt' in metrics.health);
+      assert.ok('consecutiveFails' in metrics.health);
+    });
+
+    it('should update health after health check', async () => {
+      // Trigger a health check via /__health endpoint
+      await fetch(`http://127.0.0.1:${proxyPort}/__health`, {
+        headers: { 'x-admin-token': adminToken },
+      });
+
+      const metricsRes = await fetch(`http://127.0.0.1:${proxyPort}/__metrics`, {
+        headers: { 'x-admin-token': adminToken },
+      });
+      const metrics = await metricsRes.json();
+
+      // lastCheckedAt should be set
+      assert.ok(metrics.health.lastCheckedAt);
+    });
+  });
+
+  describe('Error Tracking', () => {
+    it('should track proxy errors', async () => {
+      const metricsRes = await fetch(`http://127.0.0.1:${proxyPort}/__metrics`, {
+        headers: { 'x-admin-token': adminToken },
+      });
+      const metrics = await metricsRes.json();
+
+      assert.ok(typeof metrics.totalProxyErrors === 'number');
+    });
+
+    it('should record last proxy error details', async () => {
+      // Create a daemon with invalid target port
+      const badPort = await getFreePort();
+      const badDaemon = spawn('node', ['portokd.mjs'], {
+        env: {
+          ...process.env,
+          LISTEN_PORT: String(badPort),
+          INITIAL_TARGET_PORT: '1', // Invalid/closed port
+          ADMIN_TOKEN: adminToken,
+          STATE_FILE: `/tmp/portok-error-test-${Date.now()}.json`,
+          DRAIN_MS: '1000',
+          ROLLBACK_WINDOW_MS: '60000',
+          ROLLBACK_CHECK_EVERY_MS: '5000',
+          ROLLBACK_FAIL_THRESHOLD: '3',
+        ADMIN_RATE_LIMIT: '1000',
+        },
+        stdio: 'pipe',
+      });
+
+      await new Promise(resolve => setTimeout(resolve, 1000));
+
+      // Make a request that will fail
+      await fetch(`http://127.0.0.1:${badPort}/`).catch(() => {});
+
+      // Wait a bit for error to be recorded
+      await new Promise(resolve => setTimeout(resolve, 200));
+
+      try {
+        const metricsRes = await fetch(`http://127.0.0.1:${badPort}/__metrics`, {
+          headers: { 'x-admin-token': adminToken },
+        });
+
+        if (metricsRes.ok) {
+          const metrics = await metricsRes.json();
+
+          if (metrics.lastProxyError) {
+            assert.ok(metrics.lastProxyError.message);
+            assert.ok(metrics.lastProxyError.timestamp);
+            assert.ok(metrics.lastProxyError.targetPort);
+          }
+        }
+      } catch {
+        // Daemon might not be fully up, which is fine
+      }
+
+      badDaemon.kill('SIGTERM');
+    });
+  });
+});
+