Rulvar API reference

---

Rulvar API reference / @rulvar/store-postgres / PostgresQuotaLimiter

Class: PostgresQuotaLimiter

Defined in: packages/store-postgres/src/quota.ts:275

The multi-host reference implementation of the core QuotaLimiter SPI: engine processes pointing instances at ONE database and schema (a PostgresStore's database or their own) enforce one global provider quota. Admission consumes the window counters inside a single transaction serialized on a schema-wide advisory transaction lock, so two processes or HOSTS can never both take the last slot; reservations are rows, so reconcile settles a grant from any host; both tables are lazily pruned to the current and previous accounting window. The rule model, the fixed epoch-aligned one-minute windows, and the admission decision are the core's own exported functions, so this limiter, memoryQuotaLimiter, and SqliteQuotaLimiter agree on every verdict. The rules MUST be identical across coordinating processes (buckets key on rule content), and since RV506 that is enforced: boot records quotaRulesFingerprint(rules) in the schema's rulvar_quota_meta row and refuses a drifted instance with a typed ConfigError naming both hashes (acceptRulesUpdate: true rotates the record). Runtime contention queues on the advisory lock (a hot limiter is EXPECTED to serialize; note the lock serializes reserve AND reconcile, so it sees admission attempts plus grants); a call still waiting past QUOTA_LOCK_TIMEOUT_MS throws, and the whole admission path (bootstrap, checkout, transaction) is bounded by admissionDeadlineMs, whose expiry throws a typed QuotaDeadlineError and destroys the held connection. Both throws land in the engine's onLimiterError policy, which decides what they mean. Call close() when done.

Implements

• QuotaLimiter

Constructors

Constructor

new PostgresQuotaLimiter(options): PostgresQuotaLimiter;

Defined in: packages/store-postgres/src/quota.ts:298

Parameters

Parameter	Type
options	PostgresQuotaLimiterOptions

Returns

PostgresQuotaLimiter

Methods

close()

close(): Promise<void>;

Defined in: packages/store-postgres/src/quota.ts:870

Returns

Promise<void>

---

reconcile()

reconcile(
   reservationId, 
   usage, 
actual?): Promise<void>;

Defined in: packages/store-postgres/src/quota.ts:748

Settles a reservation against the attempt's actual usage. The optional actual.requests is the TRUE number of wire requests the reservation ended up covering (RV905: an adapter absorbing provider-side continuations makes several wire calls inside one reserved dispatch); implementations add the difference over the single request the reservation admitted into the same window, so the request cap reflects what the provider actually metered. A settlement never denies retroactively: the wire calls already happened. Implementations written against the two-argument form remain valid; they merely keep the historical undercount.

Parameters

Parameter	Type
reservationId	string
usage	Usage
actual?	{ requests?: number; }
actual.requests?	number

Returns

Promise<void>

Implementation of

QuotaLimiter.reconcile

---

release()

release(reservationId): Promise<void>;

Defined in: packages/store-postgres/src/quota.ts:804

Cancels an UNUSED admission (RV1104, the optional SPI method from RV1013): exactly what admission consumed, the admitted requests and the token estimate, returns to the window, from any host sharing the schema. Unknown ids, a double release, and a release after reconcile are no-ops (the row is gone); a rolled-over window already aged the estimate out, so only the row is deleted; a released id settles nothing afterwards. Runs under the same advisory lock and generation fence as every admission, so a rotated-away host returns nothing under retired bucket keys. Mirrors memoryQuotaLimiter.release verdict for verdict.

Parameters

Parameter	Type
reservationId	string

Returns

Promise<void>

Implementation of

QuotaLimiter.release

---

reserve()

reserve(request): Promise<QuotaDecision>;

Defined in: packages/store-postgres/src/quota.ts:684

Parameters

Parameter	Type
request	QuotaReservationRequest

Returns

Promise<QuotaDecision>

Implementation of

QuotaLimiter.reserve

---

snapshot()

snapshot(): Promise<{
  requests: number;
  rule: QuotaRule;
  tokens: number;
  windowStart: number;
}[]>;

Defined in: packages/store-postgres/src/quota.ts:843

Current-window counters per rule, for telemetry and referees.

Returns

Promise<{ requests: number; rule: QuotaRule; tokens: number; windowStart: number; }[]>