Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.5 KB
Raw Blame
/**
 * /metrics surface for `gbrain serve --http` (#3893, reimplemented from
 * @y2688's PR).
 *
 * Two properties the original community PR got wrong are pinned here:
 *
 *   1. The tracking middleware must be registered BEFORE every route —
 *      Express only applies `app.use` middleware to routes registered after
 *      it, and the PR mounted the tracker after most routes, so they were
 *      never counted (structural test below).
 *   2. GET /metrics must sit behind requireAdmin — request/error/latency
 *      series profile a personal brain's usage, so the exposition is not a
 *      public surface (the PR served it unauthenticated).
 *
 * The helpers are exercised against a bare Express app wired in the SAME
 * order as serve-http.ts (precedent: the mountOAuthCorsGate tests in
 * test/serve-http-cors.test.ts).
 */
import { describe, expect, test } from 'bun:test';
import express from 'express';
import type { Server } from 'http';
import {
  createMetricsCounters,
  metricsTrackingMiddleware,
  recordCompletedRequest,
  renderPrometheusMetrics,
  type MetricsCounters,
} from '../src/commands/serve-http-metrics.ts';
import { surfaceFileSource, surfaceSource } from './helpers/source-surface.ts';

describe('recordCompletedRequest', () => {
  test('classifies status >= 400 as errors and records latency samples', () => {
    const c = createMetricsCounters(1_000);
    recordCompletedRequest(c, 200, 12);
    recordCompletedRequest(c, 404, 5);
    recordCompletedRequest(c, 500, 30);
    expect(c.errors).toBe(2);
    expect(c.latencySamples).toEqual([12, 5, 30]);
  });

  test('caps the latency buffer, keeping the newest samples (memory bound)', () => {
    const c = createMetricsCounters();
    for (let i = 0; i <= 10_000; i++) recordCompletedRequest(c, 200, i);
    expect(c.latencySamples.length).toBe(5_000);
    expect(c.latencySamples[c.latencySamples.length - 1]).toBe(10_000);
    expect(c.latencySamples[0]).toBe(5_001);
  });
});

describe('renderPrometheusMetrics', () => {
  test('renders counters, ratio, percentiles, and uptime in exposition format', () => {
    const c = createMetricsCounters(0);
    c.requests = 10;
    c.errors = 2;
    c.latencySamples = Array.from({ length: 100 }, (_, i) => i + 1); // 1..100
    const text = renderPrometheusMetrics(c, 5_000);
    expect(text).toContain('# TYPE gbrain_requests_total counter');
    expect(text).toContain('gbrain_requests_total 10');
    expect(text).toContain('gbrain_errors_total 2');
    expect(text).toContain('gbrain_error_ratio 0.2000');
    expect(text).toContain('gbrain_latency_ms_p50 51');
    expect(text).toContain('gbrain_latency_ms_p99 100');
    expect(text).toContain('gbrain_uptime_seconds 5.0');
  });

  test('zero-state renders without dividing by zero', () => {
    const c = createMetricsCounters(0);
    const text = renderPrometheusMetrics(c, 0);
    expect(text).toContain('gbrain_requests_total 0');
    expect(text).toContain('gbrain_error_ratio 0');
    expect(text).toContain('gbrain_latency_ms_p50 0');
    expect(text).toContain('gbrain_latency_ms_p99 0');
  });
});

describe('metricsTrackingMiddleware — Express wiring (serve-http.ts order)', () => {
  function buildApp(counters: MetricsCounters, opts: { authed: boolean }): express.Express {
    const app = express();
    // Mirrors serve-http.ts: tracker first, then routes.
    app.use(metricsTrackingMiddleware(counters));
    const adminGate = (_req: express.Request, res: express.Response, next: express.NextFunction) => {
      if (opts.authed) { next(); return; }
      res.status(401).json({ error: 'Admin authentication required' });
    };
    app.get('/metrics', adminGate, (_req, res) => {
      res.set('Content-Type', 'text/plain; version=0.0.4');
      res.send(renderPrometheusMetrics(counters));
    });
    app.get('/ok', (_req, res) => res.json({ ok: true }));
    app.get('/boom', (_req, res) => res.status(500).json({ boom: true }));
    return app;
  }

  async function withServer<T>(
    app: express.Express,
    fn: (base: string) => Promise<T>,
  ): Promise<T> {
    const server: Server = app.listen(0);
    await new Promise<void>(resolve => server.once('listening', () => resolve()));
    const addr = server.address();
    const port = typeof addr === 'object' && addr ? addr.port : 0;
    try {
      return await fn(`http://127.0.0.1:${port}`);
    } finally {
      await new Promise<void>(resolve => server.close(() => resolve()));
    }
  }

  test('counts requests on routes registered after it; 5xx lands as an error', async () => {
    const counters = createMetricsCounters();
    await withServer(buildApp(counters, { authed: true }), async base => {
      await fetch(`${base}/ok`);
      await fetch(`${base}/boom`);
      expect(counters.requests).toBe(2);
      expect(counters.errors).toBe(1);
      expect(counters.latencySamples.length).toBe(2);
    });
  });

  test('/metrics scrapes are excluded from the counters they report', async () => {
    const counters = createMetricsCounters();
    await withServer(buildApp(counters, { authed: true }), async base => {
      const res = await fetch(`${base}/metrics`);
      expect(res.status).toBe(200);
      expect(await res.text()).toContain('gbrain_requests_total 0');
      expect(counters.requests).toBe(0);
    });
  });

  test('an unauthenticated scrape gets 401, not the exposition', async () => {
    const counters = createMetricsCounters();
    await withServer(buildApp(counters, { authed: false }), async base => {
      const res = await fetch(`${base}/metrics`);
      expect(res.status).toBe(401);
      expect(await res.text()).not.toContain('gbrain_requests_total');
    });
  });
});

describe('serve-http.ts wiring (structural — the two defects of the original PR)', () => {
  // test-reads-source-ok[trust-boundary]: mount ORDER (middleware before first route) and the requireAdmin
  // gate are wiring properties of the real serve-http.ts; the behavioral tests above run a
  // rebuilt harness app, so only a source scan pins the real module without booting it.
  // Refactor wave 1 split: buildServeHttpApp (serve-http.ts) installs the
  // tracker, then mountOAuth(app, ctx) registers /token + /revoke and the SDK
  // auth router from serve-http-oauth.ts. Order is positional in the façade;
  // both registrations are pinned inside mountOAuth's body.
  const src = surfaceFileSource('serve-http', 'src/commands/serve-http.ts');
  const oauthSrc = surfaceFileSource('serve-http', 'src/commands/serve-http-oauth.ts');
  const mountOAuthStart = oauthSrc.indexOf('export function mountOAuth(app: Express, ctx: ServeHttpContext)');
  const mountOAuthBody = oauthSrc.slice(mountOAuthStart, oauthSrc.indexOf('\n}\n', mountOAuthStart));

  test('tracking middleware is mounted before the first route registration', () => {
    const mw = src.indexOf('metricsTrackingMiddleware(');
    const oauthMount = src.indexOf('mountOAuth(app, ctx);');
    const firstTokenRoute = mountOAuthBody.indexOf('mountConfidentialOAuth(app,');
    const authRouterMount = mountOAuthBody.indexOf('app.use(authRouter)');
    expect(mw).toBeGreaterThan(-1);
    expect(mountOAuthStart).toBeGreaterThan(-1);
    expect(firstTokenRoute).toBeGreaterThan(-1);
    expect(authRouterMount).toBeGreaterThan(-1);
    expect(oauthMount).toBeGreaterThan(-1);
    expect(mw).toBeLessThan(oauthMount);
    expect(src.indexOf('mountConfidentialOAuth(')).toBe(-1);
    expect(src.indexOf('app.use(authRouter)')).toBe(-1);
  });

  test('GET /metrics is gated behind requireAdmin', () => {
    expect(surfaceSource('serve-http')).toMatch(/app\.get\(\s*'\/metrics',\s*requireAdmin/);
  });
});