Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.5 KB
Raw Blame
/**
 * `search.keyword_statement_timeout_ms` (#6495): the per-statement bound the
 * Postgres engine sets (`statement_timeout`, transaction-local) around every
 * keyword, keyword-page, keyword-count, title and CJK search statement.
 * Integer milliseconds, default 8000, range 1000..60000; `config set` refuses
 * other values and a stored value outside the range reads as the default.
 *
 * The bound is an operator mitigation, never a request parameter: a remote
 * caller cannot widen it, and the cap keeps a broad keyword query from
 * holding a backend for minutes. It is resolved once per engine connection,
 * by the first keyword statement after connect (the file plane the engine
 * connected with, then the DB plane's `config` row), never by a request
 * parameter; connect itself issues no statement for it, so a borrower of an
 * in-flight pool still connects at once and a read-only command that never
 * searches reads nothing. `gbrain config set` therefore takes effect on the
 * next connection: the next CLI command, or a restart of the serving process. It
 * mitigates #6495 (a brain whose commonest terms cannot be ranked within the
 * bound) by letting the operator trade latency for coverage; ranking cost
 * stays proportional to the matching corpus, so a longer bound buys time,
 * not a faster statement. `countKeywordPages` keeps its own narrower
 * `timeoutMs` when a caller passes one.
 *
 * Postgres only: PGLite runs these statements with no statement timeout.
 */
import { requestConfigValue, type BulkConfigReader } from '../config-snapshot.ts';

export const KEYWORD_STATEMENT_TIMEOUT_KEY = 'search.keyword_statement_timeout_ms';
export const KEYWORD_STATEMENT_TIMEOUT_DEFAULT_MS = 8000;
export const KEYWORD_STATEMENT_TIMEOUT_MIN_MS = 1000;
export const KEYWORD_STATEMENT_TIMEOUT_MAX_MS = 60_000;

/** The configured milliseconds when `raw` is an integer in range, else undefined. */
export function keywordStatementTimeoutMs(raw: unknown): number | undefined {
  if (raw === undefined || raw === null || raw === '') return undefined;
  const n = typeof raw === 'string' ? Number(raw.trim()) : Number(raw);
  return Number.isInteger(n) && n >= KEYWORD_STATEMENT_TIMEOUT_MIN_MS && n <= KEYWORD_STATEMENT_TIMEOUT_MAX_MS ? n : undefined;
}

/** File plane, then DB plane, then the default. */
export function resolveKeywordStatementTimeoutMs(fileValue: unknown, dbValue: unknown): number {
  return keywordStatementTimeoutMs(fileValue) ?? keywordStatementTimeoutMs(dbValue) ?? KEYWORD_STATEMENT_TIMEOUT_DEFAULT_MS;
}

/** `config set` refusal text, or null when the value is valid. */
export function keywordStatementTimeoutValueProblem(value: string): string | null {
  return keywordStatementTimeoutMs(value) !== undefined
    ? null
    : `${KEYWORD_STATEMENT_TIMEOUT_KEY} must be an integer number of milliseconds from ${KEYWORD_STATEMENT_TIMEOUT_MIN_MS} to ${KEYWORD_STATEMENT_TIMEOUT_MAX_MS} (got '${value}'). Nothing was written.`;
}

/**
 * The DB-plane read, with the key inlined instead of bound: a bound parameter
 * makes the driver describe the statement and record its type in the shared
 * pg-types cache, which is then written under `~/.gbrain/cache/pg-types/` at
 * exit, and read-only commands such as `gbrain graduate --plan` must not
 * write a byte (test/e2e/graduation-cli-zero-mutation-*.test.ts).
 */
// engine-sql-ok: one Postgres-only config-row read with the key inlined so the driver describes no parameter (pg-types cache); PGLite sets no statement timeout
export const KEYWORD_STATEMENT_TIMEOUT_CONFIG_SQL = `SELECT value FROM config WHERE key = '${KEYWORD_STATEMENT_TIMEOUT_KEY}'`;

/**
 * The `statement_timeout` setting value (`<ms>ms`) for one engine connection:
 * the file plane's value when set, else the DB plane's (from the request's
 * config snapshot when one is open, #7147). A config table that cannot be read
 * yet (a fresh brain before its schema) yields the default.
 */
export async function loadKeywordStatementTimeout(
  reader: { executeRaw<T>(sql: string): Promise<T[]> } & BulkConfigReader,
  fileValue: unknown,
): Promise<string> {
  const fileMs = keywordStatementTimeoutMs(fileValue);
  if (fileMs !== undefined) return `${fileMs}ms`;
  const snapshotValue = await requestConfigValue(reader, KEYWORD_STATEMENT_TIMEOUT_KEY);
  const dbValue = snapshotValue !== undefined
    ? snapshotValue
    : (await reader.executeRaw<{ value: string }>(KEYWORD_STATEMENT_TIMEOUT_CONFIG_SQL).catch(() => []))[0]?.value;
  return `${resolveKeywordStatementTimeoutMs(undefined, dbValue)}ms`;
}