Struct Usage 

pub struct Usage { /* private fields */ }

A usage-meter table over the Database port: durable per (subject, meter, period) counters. Construct it with the table the module declares (e.g. "<module>_usage") and ship create_table_sql as its migration. subject is who the allowance belongs to; meter is which resource is counted, so one table holds every meter.

Implementations

impl Usage

pub fn new(table: impl Into<String>) -> Self

pub fn create_table_sql(&self) -> String

The portable DDL for the usage table. used is BIGINT, a signed 64-bit counter on both SQLite and Postgres (ADR 0004).

pub fn consume_statement( &self, subject: &str, meter: &str, period: Period, now: OffsetDateTime, amount: u64, limit: Option<u64>, ) -> Statement

The guarded upsert as a Statement for the module’s own db.batch_atomic(..), beside the work it pays for. With a limit it fails (a NOT NULL violation on used) when the allowance cannot carry amount, so the batch rolls back; read the meter back for the 429 (read). With limit None, counting only.

pub async fn consume( &self, db: &dyn Database, subject: &str, meter: &str, period: Period, now: OffsetDateTime, amount: u64, limit: Option<u64>, ) -> Result<Consumption, DbError>

Spends amount against the allowance for (subject, meter) in the period containing now, atomically. Admission and the increment are one statement, so concurrent callers cannot overspend: the row lock serialises them and the guard is re-evaluated against the committed row. On admission the caller does the work; on refusal it must not. An amount above limit is refused as exhausted even on an empty meter (used 0).

Errors

Returns DbError if the write or the read-back fails.

pub async fn refund( &self, db: &dyn Database, subject: &str, meter: &str, period: Period, now: OffsetDateTime, amount: u64, ) -> Result<(), DbError>

Returns amount to the allowance, never below zero. A single guarded UPDATE, so it cannot race an increment into a lost update.

Errors

Returns DbError if the update fails.

pub async fn read( &self, db: &dyn Database, subject: &str, meter: &str, period: Period, now: OffsetDateTime, ) -> Result<u64, DbError>

How much (subject, meter) has spent in the period containing now; 0 when no row exists.

Errors

Returns DbError if the read fails.

pub async fn history( &self, db: &dyn Database, subject: &str, meter: &str, period: Period, now: OffsetDateTime, last_n_periods: u32, ) -> Result<Vec<(PeriodWindow, u64)>, DbError>

The last last_n_periods windows and their spend, most recent first (the period containing now first), with periods that have no row reported as 0. One SELECT over the span, zero-filled in Rust.

Errors

Returns DbError if the read fails.

pub async fn purge( &self, db: &dyn Database, period: Period, now: OffsetDateTime, keep_periods: u32, ) -> Result<u64, DbError>

Deletes every counter older than the keep_periods most recent windows, the one containing now included — the retention half of the meter. keep_periods of 0 deletes every row. Returns the rows removed.

Core schedules nothing: the owning module calls this from its Module::scheduled tick, the way module-waitlist calls SendCooldown::prune.

Errors

Returns DbError if the delete fails.

Trait Implementations

impl Clone for Usage

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Usage

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.