Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.0 KB
Raw Blame
/**
 * issue #6 — CheckoutGauge (pure) + the PostgresEngine gauge seams.
 *
 * The leak guard matters most: a counter that isn't released on a THROWING
 * query drifts upward forever and turns the diagnostics into fiction. The
 * engine seams use the Object.create(PostgresEngine.prototype) + fake-pool
 * pattern (no real DB).
 */

import { describe, expect, test } from 'bun:test';
import { CheckoutGauge } from '../src/core/pool-gauge.ts';
import { PostgresEngine } from '../src/core/postgres-engine.ts';

describe('CheckoutGauge (pure)', () => {
  test('acquire/release round-trip per kind', () => {
    const g = new CheckoutGauge();
    g.acquire('raw');
    g.acquire('raw');
    g.acquire('direct');
    g.acquire('reserved');
    g.acquire('tx');
    expect(g.snapshot()).toEqual({ raw: 2, direct: 1, reserved: 1, tx: 1 });
    g.release('raw');
    g.release('direct');
    g.release('reserved');
    g.release('tx');
    expect(g.snapshot()).toEqual({ raw: 1, direct: 0, reserved: 0, tx: 0 });
  });

  test('release clamps at zero (a missed acquire never underflows)', () => {
    const g = new CheckoutGauge();
    g.release('raw');
    g.release('tx');
    expect(g.snapshot()).toEqual({ raw: 0, direct: 0, reserved: 0, tx: 0 });
  });

  test('snapshot is a copy, not a live reference', () => {
    const g = new CheckoutGauge();
    const snap = g.snapshot();
    g.acquire('raw');
    expect(snap.raw).toBe(0);
  });
});

// --- engine seams (fake pool, no DB) ---------------------------------------

interface FakePoolBehavior {
  /** What conn.unsafe returns per call. */
  unsafe: (sql: string, params?: unknown[]) => unknown;
}

function makeEngine(behavior: FakePoolBehavior): {
  engine: PostgresEngine;
  diagnostics: () => { tracked: Record<string, number>; poolMax: number | null } | null;
} {
  const fakePool = {
    unsafe: behavior.unsafe,
    options: { max: 10 },
  };
  const engine = Object.create(PostgresEngine.prototype) as PostgresEngine;
  Object.defineProperty(engine, 'sql', { get: () => fakePool });
  Object.defineProperty(engine, '_sql', { value: fakePool, writable: true });
  // Fresh gauge per fake engine (the real field initializer doesn't run for
  // Object.create instances).
  Object.defineProperty(engine, 'checkoutGauge', {
    value: new CheckoutGauge(),
    writable: true,
  });
  return {
    engine,
    diagnostics: () =>
      (engine as unknown as {
        getPoolDiagnostics: () => { tracked: Record<string, number>; poolMax: number | null } | null;
      }).getPoolDiagnostics(),
  };
}

describe('PostgresEngine gauge seams (fake pool)', () => {
  test('executeRaw: counted while in flight, released on resolve', async () => {
    let resolveQuery: (rows: unknown[]) => void = () => {};
    const { engine, diagnostics } = makeEngine({
      unsafe: () => new Promise((r) => { resolveQuery = r; }),
    });

    const p = engine.executeRaw('SELECT 42');
    expect(diagnostics()?.tracked.raw).toBe(1);
    expect(diagnostics()?.poolMax).toBe(10);
    resolveQuery([]);
    await p;
    expect(diagnostics()?.tracked.raw).toBe(0);
  });

  test('executeRaw: released on REJECTED query (leak guard)', async () => {
    const { engine, diagnostics } = makeEngine({
      unsafe: () => Promise.reject(new Error('query was cancelled')),
    });
    await expect(engine.executeRaw('SELECT 42')).rejects.toThrow('query was cancelled');
    expect(diagnostics()?.tracked.raw).toBe(0);
  });

  test('executeRaw: released on SYNCHRONOUS throw (pre-aborted signal)', async () => {
    const { engine, diagnostics } = makeEngine({
      unsafe: () => Promise.resolve([]),
    });
    const ac = new AbortController();
    ac.abort();
    await expect(
      engine.executeRaw('SELECT 42', undefined, { signal: ac.signal }),
    ).rejects.toThrow();
    expect(diagnostics()?.tracked.raw).toBe(0);
  });

  test('getPoolDiagnostics is fail-open (no pool → null, no throw)', () => {
    const engine = Object.create(PostgresEngine.prototype) as PostgresEngine;
    // No sql defined — the getter on the prototype will throw internally.
    const diag = (engine as unknown as {
      getPoolDiagnostics: () => unknown;
    }).getPoolDiagnostics();
    expect(diag).toBeNull();
  });
});

describe('PostgresEngine gauge seams: direct + tx (coverage-audit gaps)', () => {
  test('executeRawDirect: counted as direct while in flight, released on resolve and reject', async () => {
    let resolveQuery: (rows: unknown[]) => void = () => {};
    const { engine, diagnostics } = makeEngine({
      unsafe: () => new Promise((r) => { resolveQuery = r; }),
    });
    // No connectionManager on the fake -> executeRawDirect falls through to this.sql.
    const p = engine.executeRawDirect('SELECT 1');
    expect(diagnostics()?.tracked.direct).toBe(1);
    resolveQuery([]);
    await p;
    expect(diagnostics()?.tracked.direct).toBe(0);

    const { engine: rejEngine, diagnostics: rejDiag } = makeEngine({
      unsafe: () => Promise.reject(new Error('boom')),
    });
    await expect(rejEngine.executeRawDirect('SELECT 1')).rejects.toThrow('boom');
    expect(rejDiag()?.tracked.direct).toBe(0);
  });

  test('transaction: tx counter released on SYNCHRONOUS begin() throw (nested-tx clone class)', async () => {
    const { engine, diagnostics } = makeEngine({ unsafe: () => Promise.resolve([]) });
    // Fake pool has no .begin -> conn.begin(...) throws synchronously, the
    // exact shape a nested transaction on a tx clone produces.
    await expect(
      (engine as unknown as { transaction: (fn: unknown) => Promise<unknown> }).transaction(async () => 'x'),
    ).rejects.toThrow();
    expect(diagnostics()?.tracked.tx).toBe(0);
  });

  test('withReservedConnection: ddl() throw falls back to the READ pool and releases the permit', async () => {
    const log: string[] = [];
    const readPool = {
      unsafe: async () => [],
      options: { max: 10 },
      reserve: async () => {
        log.push('reserve:read');
        return { unsafe: async () => [], release: () => log.push('release:read') };
      },
    };
    const engine = Object.create(PostgresEngine.prototype) as PostgresEngine;
    Object.defineProperty(engine, 'sql', { get: () => readPool });
    Object.defineProperty(engine, '_sql', { value: readPool, writable: true });
    Object.defineProperty(engine, 'checkoutGauge', { value: new CheckoutGauge(), writable: true });
    Object.defineProperty(engine, '_reservedDirectInFlight', { value: 0, writable: true });
    Object.defineProperty(engine, 'connectionManager', {
      value: {
        peekReadPool: () => readPool,
        isDualPoolActive: () => true,
        describeMode: () => ({ direct_pool_size: 3 }),
        ddl: async () => { throw new Error('EMAXCONNSESSION'); },
      },
      writable: true,
    });
    const out = await engine.withReservedConnection(async () => 'ok');
    expect(out).toBe('ok');
    expect(log).toEqual(['reserve:read', 'release:read']); // fell back, did not fail the caller
    expect((engine as unknown as { _reservedDirectInFlight: number })._reservedDirectInFlight).toBe(0);
  });
});