Struct UsageAggregator 

pub struct UsageAggregator { /* private fields */ }

Thread-safe, in-memory usage counter store with optional persistence backend.

Cheaply cloneable via Arc — all clones share the same underlying map.

Persistence

By default, the aggregator uses NoopBackend and counters are lost on restart. Pass a [RedisBackend] (or any UsageBackend impl) to UsageAggregator::new_with_backend to enable durable storage.

let agg = UsageAggregator::new_with_backend(Arc::new(NoopBackend));

Example

use std::sync::Arc;
use fraiseql_server::usage::aggregator::UsageAggregator;
use fraiseql_server::usage::events::MutationAuditEvent;

let agg = Arc::new(UsageAggregator::new());
let event = MutationAuditEvent::new("create_user", "User", "create", "acme", "2026-05");
agg.record(&event);
let summary = agg.query("acme", "2026-05");
assert_eq!(summary.mutations["User"], 1);

Implementations

impl UsageAggregator

pub fn new() -> Self

Create an empty aggregator with no persistence (in-memory only).

pub fn new_with_backend(backend: Arc<dyn UsageBackend>) -> Self

Create an empty aggregator backed by the given persistence backend.

pub fn set_backend(&self, backend: Arc<dyn UsageBackend>)

Replace the persistence backend at runtime.

Called during server startup to upgrade from the default NoopBackend to a durable backend (e.g. PostgresBackend) once the database pool is available. Any in-flight in-memory counters are preserved.

Panics

Panics if the backend RwLock is poisoned (unrecoverable state).

pub fn record(&self, event: &MutationAuditEvent)

Record one mutation audit event, incrementing the appropriate counter.

This method is lock-free on the hot path: it uses AtomicU64::fetch_add after the initial shard lock in DashMap::entry.

pub fn query(&self, tenant_id: &str, period: &str) -> UsageSummary

Return the usage summary for a tenant and period.

Returns UsageSummary { mutations: {} } (never an error) when no events have been recorded for the given (tenant_id, period) pair.

pub fn entry_count(&self) -> usize

Return the total number of distinct counter entries (for monitoring).

pub async fn flush_to_backend(&self) -> Result<(), String>

Flush all current counters to the persistence backend.

A no-op when using the default NoopBackend.

Errors

Propagates errors from the underlying UsageBackend::flush.

Panics

Panics if the backend RwLock is poisoned (unrecoverable state).

pub async fn load_from_backend(&self) -> Result<(), String>

Load persisted counters from the backend into the in-memory map.

Existing in-memory counters are merged (not replaced): the loaded value is added to any in-flight in-memory count so that events recorded between the last flush and this load are not lost.

Errors

Propagates errors from the underlying UsageBackend::load.

Panics

Panics if the backend RwLock is poisoned (unrecoverable state).

Trait Implementations

impl Debug for UsageAggregator

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

Formats the value using the given formatter.

impl Default for UsageAggregator

fn default() -> Self

Returns the “default value” for a type.