Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
3.9 KB
Raw Blame
/**
 * #6317 (C1): the ordinary pool's real numbers, read from the vendored
 * driver's own queues (`sql.pool`, a GBrain addition to postgres.js: the
 * `open`, `busy`, `full`, `reserved`, `connecting` connection queues and the
 * queries waiting for any connection). This is the figure `pool-gauge.ts`
 * refuses to invent: a connection is checked out when it is executing
 * (`busy`, `full`), owned by a reservation or transaction (`reserved`) or
 * being opened for a waiting query (`connecting`); `waiters` is the driver's
 * query queue, which a transaction-mode pooler cannot see. Every reader
 * duck-types the engine and gets null when the engine is not Postgres or the
 * driver predates the accessor, never a guess.
 */

export interface DriverPoolStats {
  checked_out: number;
  max: number;
  waiters: number;
  /** #6383: age of the oldest statement still waiting for the server, 0 when nothing is in flight. */
  inflight_oldest_ms: number;
  /** #6383: statements the pool has settled since it opened; a pool that is checked out but never advances this is stalled. */
  completed: number;
  /**
   * #6543 (A4): age of the oldest statement past its own budget (the pool's, raised for an operation that declared a longer
   * statement_timeout, none for a declared 0), 0 when none is; absent when the driver predates per-statement budgets.
   */
  inflight_over_budget_ms?: number;
}

interface DriverQueues { max: number; open: number; busy: number; full: number; reserved: number; connecting: number; closed: number; ended: number; queued: number; inflight_oldest_ms?: number; completed?: number;
  inflight_over_budget_ms?: number }

/** The pool numbers of one driver instance, or null when it exposes none. */
export function driverPoolStats(sql: unknown): DriverPoolStats | null {
  const pool = (sql as { pool?: DriverQueues } | null)?.pool;
  if (!pool || typeof pool.max !== 'number') return null;
  return {
    checked_out: pool.busy + pool.full + pool.reserved + pool.connecting,
    max: pool.max,
    waiters: pool.queued,
    inflight_oldest_ms: pool.inflight_oldest_ms ?? 0,
    completed: pool.completed ?? 0,
    ...(typeof pool.inflight_over_budget_ms === 'number' ? { inflight_over_budget_ms: pool.inflight_over_budget_ms } : {}),
  };
}

/** The ordinary pool of an engine that reports one (`getPoolDiagnostics().pool`), else null. */
export function enginePoolStats(engine: unknown): DriverPoolStats | null {
  try {
    const diagnostics = (engine as { getPoolDiagnostics?: () => { pool?: DriverPoolStats | null } | null } | null)?.getPoolDiagnostics?.();
    return diagnostics?.pool ?? null;
  } catch {
    return null;
  }
}

/** #6383: the ordinary pool's numbers plus the engine's incident counters, the block `/health?deep=1` and the stall watch report. */
export interface PoolHealthSnapshot extends DriverPoolStats {
  poisoned_discards: number;
  stuck_discards: number;
  build_failures: number;
  desync_discards: number;
  /** #6543 (A6): connections retired by an incident (stuck, desync, closed under statements) that reconnected, and reconnects that failed. */
  recovered: number;
  recovery_failed: number;
}

export function poolHealthSnapshot(engine: unknown): PoolHealthSnapshot | null {
  try {
    const diagnostics = (engine as { getPoolDiagnostics?: () => { pool?: DriverPoolStats | null; poisonedDiscards?: number; stuckDiscards?: number; buildFailures?: number; desyncDiscards?: number;
      recovered?: number; recoveryFailed?: number } | null } | null)?.getPoolDiagnostics?.();
    if (!diagnostics?.pool) return null;
    return {
      ...diagnostics.pool,
      poisoned_discards: diagnostics.poisonedDiscards ?? 0,
      stuck_discards: diagnostics.stuckDiscards ?? 0,
      build_failures: diagnostics.buildFailures ?? 0,
      desync_discards: diagnostics.desyncDiscards ?? 0,
      recovered: diagnostics.recovered ?? 0,
      recovery_failed: diagnostics.recoveryFailed ?? 0,
    };
  } catch {
    return null;
  }
}