Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* #6278: `executeRaw` with `timeoutMs` on Postgres. The session's
* `statement_timeout` is a startup parameter a transaction-mode pooler drops,
* so a preparation read outside the publication transaction had no
* server-side bound and a relation lock held elsewhere pinned its connection
* for as long as the lock lasted. A reserved connection runs `BEGIN; SET LOCAL
* statement_timeout` (`BEGIN READ WRITE`, #7183), the statement and `COMMIT` as one pipelined round trip:
* the pooler pins the transaction to one server connection, `SET LOCAL` ends
* with it, and a statement past the bound ends server-side with 57014 (a lock
* wait counts toward it). `COMMIT` after a failed statement is a rollback,
* never an error of its own. `signal` covers the wait for a free
* connection (a saturated pool must not hold the bound off); the statement
* itself ends at the bound or, when `signal` aborts after the connection was
* reserved, by a cancel request: the call then rejects at once with an
* `AbortError` and the connection is discarded, so a socket or pooler that
* stopped answering never keeps it reserved (#8155). A write ended this way may
* have committed: its outcome is unknown. With `deadlineAt` the
* bound is the time left after the connection was reserved (#6696 B1).
*
* `jitOff` adds `SET LOCAL jit = off` to the same envelope (see
* jit-off-statement.ts). Without `timeoutMs` there is no bound, and a
* signalled statement runs through `run` (the engine's `runUnsafe`), so
* `signal` still cancels it in flight as it would a plain `executeRaw`; its
* `COMMIT` follows the statement instead of riding in the same round trip.
*/
import type postgres from '#postgres';
import { reserveWithCancellation } from './cancellation.ts';
import { READ_WRITE_BEGIN } from './read-write-transactions.ts';
import type { CheckoutGauge } from '../pool-gauge.ts';
import { ReadDeadlineError } from '../read-deadline.ts';
type Sql = ReturnType<typeof postgres>;
export type RunStatement = <T>(conn: Sql, sql: string, params: unknown[] | undefined, opts: { signal?: AbortSignal; prepare?: boolean }) => Promise<T[]>;
// engine-sql-ok: transaction control around a caller's statement (BEGIN / SET LOCAL statement_timeout / SET LOCAL jit / COMMIT), no storage-domain SQL
export async function runBoundedStatement<T>(conn: Sql, sql: string, params: unknown[] | undefined,
opts: { timeoutMs?: number; deadlineAt?: number; signal?: AbortSignal; jitOff?: boolean; prepare?: boolean }, onReserved: () => void, run?: RunStatement): Promise<T[]> {
const reserved = opts.signal ? await reserveWithCancellation(reserve => conn.reserve(reserve), opts.signal) : await conn.reserve();
onReserved();
const settings = opts.jitOff ? ['SET LOCAL jit = off'] : [];
if (opts.timeoutMs !== undefined) {
// #6696 B1: an absolute deadline is re-read after the pool wait, so time spent waiting for a connection is not granted again.
const ms = Math.max(1, Math.ceil(opts.deadlineAt !== undefined ? Math.min(opts.timeoutMs, opts.deadlineAt - Date.now()) : opts.timeoutMs));
settings.push(`SET LOCAL statement_timeout = ${ms}`);
}
let discarded = false;
let onAbort: (() => void) | undefined;
try {
const open = reserved.unsafe([READ_WRITE_BEGIN, ...settings].join('; ')).simple().execute();
// A cancellable statement is issued through `run`, which awaits the query and so enqueues it a microtask
// later than `execute()` would: COMMIT then waits for it to settle instead of being pipelined ahead of it.
const cancellable = opts.timeoutMs === undefined && opts.signal && run;
const read = cancellable
? (async () => run<T>(reserved as unknown as Sql, sql, params, { signal: opts.signal, prepare: opts.prepare }))()
: reserved.unsafe(sql, params as Parameters<typeof reserved.unsafe>[1], { prepare: opts.prepare ?? true }).execute();
const commit = () => reserved.unsafe('COMMIT').execute();
const close = cancellable ? read.then(commit, commit) : commit();
const statement = Promise.allSettled([open, read, close]);
const settled = opts.signal && !cancellable
? await Promise.race([statement, new Promise<never>((_, reject) => {
onAbort = () => {
discarded = true;
try { void Promise.resolve((read as { cancel?: () => unknown }).cancel?.()).catch(() => {}); } catch { /* the discard below still retires it */ }
reserved.discard();
reject(new DOMException('aborted', 'AbortError'));
};
if (opts.signal!.aborted) onAbort();
else opts.signal!.addEventListener('abort', onAbort, { once: true });
})])
: await statement;
for (const outcome of settled) if (outcome.status === 'rejected') throw outcome.reason;
return (settled[1] as PromiseFulfilledResult<unknown>).value as T[];
} finally {
if (onAbort) opts.signal?.removeEventListener('abort', onAbort);
if (!discarded) reserved.release();
}
}
/**
* #6318: an engine read issued for a bounded preparation (read-deadline.ts) that would otherwise run on the shared pool
* in autocommit. It runs on one reserved connection as `BEGIN READ ONLY; SET LOCAL statement_timeout = <time left>`
* (one simple statement), the read's own statements and `COMMIT`, pipelined: the server ends a read still waiting on
* a lock at the deadline (57014), through a transaction-mode pooler, and the answer returns without waiting for
* COMMIT's round trip. A failed read leaves the transaction aborted, and COMMIT then rolls it back.
* #8651: the deadline also ends the wait for a free connection; a read whose deadline passed before it had one is
* never sent (`ReadDeadlineError`). A COMMIT still unsettled at the deadline, and at least `settleMs` after it was
* sent, has its connection discarded so the connection and its gauge slot come back.
*/
// engine-sql-ok: transaction control around a caller's read (BEGIN READ ONLY / SET LOCAL statement_timeout / COMMIT), no storage-domain SQL
export async function runDeadlineRead<T>(conn: Sql, deadlineAt: number, run: (tx: Sql) => Promise<T>, gauge: CheckoutGauge, settleMs: number): Promise<T> {
if (Date.now() >= deadlineAt) throw new ReadDeadlineError();
gauge.acquire('reserved');
const expiry = new AbortController();
const timer = setTimeout(() => expiry.abort(), deadlineAt - Date.now());
let reserved: postgres.ReservedSql;
try {
reserved = await reserveWithCancellation(reserve => conn.reserve(reserve), expiry.signal);
} catch (error) {
gauge.release('reserved');
throw expiry.signal.aborted ? new ReadDeadlineError() : error;
} finally { clearTimeout(timer); }
if (Date.now() >= deadlineAt) {
reserved.release();
gauge.release('reserved');
throw new ReadDeadlineError();
}
gauge.checkedOut();
const ms = Math.max(1, Math.ceil(deadlineAt - Date.now()));
const opened = reserved.unsafe(`BEGIN READ ONLY; SET LOCAL statement_timeout = ${ms}`).simple().execute().then(() => undefined, (error: unknown) => error);
try {
const result = await run(reserved as unknown as Sql);
const failed = await opened;
if (failed) throw failed;
return result;
} finally {
let settled = false;
const settle = () => {
if (settled) return;
settled = true;
clearTimeout(stuck);
reserved.release();
gauge.release('reserved');
};
const stuck = setTimeout(() => { reserved.discard(); settle(); }, Math.max(deadlineAt - Date.now(), settleMs));
stuck.unref?.();
void reserved.unsafe('COMMIT').execute().then(settle, settle);
}
}