Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.1 KB
Raw Blame
/**
 * Transaction-local settings for the Postgres search reads (#6039, #6721).
 *
 * JIT off. The search statements (keyword, keyword chunks, CJK, title,
 * vector candidates and the vector `hasMore` witness) are short interactive
 * reads, but their correlated visibility subplans inflate the planner's cost
 * estimate past `jit_above_cost` (100k by default) and, on the vector and
 * common-term statements, past the inlining and optimization thresholds
 * (500k). Postgres then compiles the statement with LLVM on every call, and
 * compilation, not execution, dominates its latency: on a 20k-page brain the
 * remote keyword statement spent 58 of 61 ms compiling and the remote vector
 * candidate statement 990 of 1,394 ms. JIT never pays back on a statement
 * that executes in milliseconds.
 *
 * One statement (#6721). Every setting a search transaction needs (`jit`,
 * the RLS `app.scopes`, `statement_timeout`, the relaxed arms'
 * `enable_seqscan`, the vector scan settings) is applied by a single
 * `SELECT set_config(...), set_config(...)`: each separate statement was a
 * round trip in series with the query, about 30 ms each to a remote pooler.
 * At the top level nothing is read first or restored after: `set_config(...,
 * true)` ends with the transaction, and the read is sent behind the settings
 * statement without waiting for its answer (one round trip for both: the
 * transaction pins its connection, the driver sends in order and budgets the
 * read by the `statement_timeout` it just sent). A failed settings statement
 * aborts the transaction, so the read fails behind it and the settings error
 * is the one raised. Inside a caller's transaction the read
 * runs in a savepoint, and a released savepoint keeps the settings, so one
 * statement reads the caller's values first and one restores them after; a
 * failed read rolls the savepoint back, which reverts them too.
 *
 * Each setting name is a literal in the statement and each value a bound
 * parameter, so the vendored driver reads a `statement_timeout` change from
 * the text and budgets the next statement by it (#6543).
 *
 * Postgres only: PGLite has no JIT provider, no RLS binding and no
 * statement timeout, so its engine never calls this.
 */
import type postgres from '#postgres';

/** Setting name to transaction-local value. */
export type SearchSettings = Readonly<Record<string, string>>;

export const SEARCH_JIT_OFF: SearchSettings = { jit: 'off' };

const SETTING_NAME = /^[a-z_][a-z0-9_]*(\.[a-z_][a-z0-9_]*)?$/;

function names(settings: SearchSettings): string[] {
  const keys = Object.keys(settings);
  for (const name of keys) if (!SETTING_NAME.test(name)) throw new Error(`search setting name not allowed: ${name}`);
  return keys;
}

/** `SELECT set_config('<name>', $1, true), …`: one statement for every setting, values bound. */
export function searchSettingsStatement(settings: SearchSettings): { sql: string; params: string[] } {
  const keys = names(settings);
  return {
    sql: `SELECT ${keys.map((name, i) => `set_config('${name}', $${i + 1}, true)`).join(', ')}`,
    params: keys.map(name => settings[name]!),
  };
}

const SETTINGS_STATEMENT = /^SELECT set_config\('[a-z_][a-z0-9_]*(\.[a-z_][a-z0-9_]*)?', \$\d+, true\)(, set_config\('[a-z_][a-z0-9_]*(\.[a-z_][a-z0-9_]*)?', \$\d+, true\))*$/;
const READ_START = /^\s*(--[^\n]*\n\s*)*(select|with)\b/i;
const NOT_A_PLAIN_READ = /;|\b(insert|update|delete|merge|truncate|copy|lock|call|do|nextval|setval|set_config|pg_notify|pg_advisory\w*|pg_try_advisory\w*|txid_current|pg_current_xact_id|lo_\w+|dblink\w*)\b|\bfor\s+(no\s+key\s+|key\s+)?share\b/i;

/**
 * GBRA-156: what a search read transaction may send behind BEGIN before BEGIN's answer (`TransactionOptions.pipelineEarly`).
 * If BEGIN fails, an accepted statement runs in autocommit, so this accepts the settings statement
 * `searchSettingsStatement` builds (transaction-local, a no-op outside a transaction) and single SELECT or WITH
 * statements (after any leading line comments) that name no write, lock, sequence, notification or session-setting keyword. A refusal costs only the
 * round trip: the statement waits for BEGIN's answer, as every statement did before.
 */
export function isPipelinableSearchRead(statement: string): boolean {
  if (SETTINGS_STATEMENT.test(statement)) return true;
  return READ_START.test(statement) && !NOT_A_PLAIN_READ.test(statement);
}

/** `SELECT current_setting('<name>', true) AS "<name>", …`: the caller's values, one row. */
function currentSettingsStatement(keys: string[]): string {
  return `SELECT ${keys.map(name => `current_setting('${name}', true) AS "${name}"`).join(', ')}`;
}

/**
 * Apply `settings` for `run` on the search transaction `tx`. `nested`: `tx`
 * is a savepoint in a caller's transaction, whose values are restored after
 * `run`; a value the caller never set restores to `fallback[name]`
 * (an extension setting not yet loaded reads as NULL), else ''.
 */
// engine-sql-ok: jit, statement_timeout, enable_seqscan and the hnsw settings are Postgres server settings
export async function withSearchSettings<T>(
  tx: ReturnType<typeof postgres>,
  nested: boolean,
  settings: SearchSettings,
  run: () => Promise<T>,
  fallback: SearchSettings = {},
): Promise<T> {
  const keys = names(settings);
  if (keys.length === 0) return run();
  const previous = nested ? (await tx.unsafe(currentSettingsStatement(keys)))[0] as Record<string, string | null> : undefined;
  const set = searchSettingsStatement(settings);
  const applied = tx.unsafe(set.sql, set.params);
  if (previous) await applied;
  else applied.catch(() => undefined);
  const result = await run().catch(async error => {
    await applied;
    throw error;
  });
  await applied;
  if (previous) {
    const restore = searchSettingsStatement(Object.fromEntries(keys.map(name => [name, previous[name] ?? fallback[name] ?? ''])));
    await tx.unsafe(restore.sql, restore.params);
  }
  return result;
}

/** JIT off for `run` alone (the unscoped jit-off reads). */
export function withSearchJitOff<T>(tx: ReturnType<typeof postgres>, nested: boolean, run: () => Promise<T>): Promise<T> {
  return withSearchSettings(tx, nested, SEARCH_JIT_OFF, run);
}