Struct BatchingPersist 

pub struct BatchingPersist<'a> { /* private fields */ }

Wraps any handler for a bulk-sync drain loop: every callback delegates to the inner handler, but committed messages BUFFER here instead of saving one transaction each — the loop calls BatchingPersist::flush periodically and at stream end to land them in batched transactions (save_messages_batch_multi).

Deferral is recoverable because the wrapper ledger (the negentropy fingerprint set) rides the flush transaction: a message lost to a crash, a stale-session drop, or a failed flush leaves its wrapper unledgered, so the next reconciliation re-delivers it.

Implementations

impl<'a> BatchingPersist<'a>

pub fn new(inner: &'a dyn InboundEventHandler) -> Self

pub fn buffered(&self) -> usize

How many messages are waiting — the loop’s flush-threshold probe.

pub async fn flush(&self, session: &SessionGuard) -> usize

Drain the buffer into batched transactions (grouped by chat, arrival order kept). On a stale session the drained messages are DROPPED, never written into the next account’s DB — their wrappers stay unledgered, so negentropy re-delivers them when the original account returns.

pub async fn try_flush(&self, session: &SessionGuard) -> Result<usize, String>

Self::flush, but a persist failure is distinguishable from “nothing to write” — callers that gate follow-on effects on the ledger actually holding the batch (reconcile-cursor births) need the difference: an advance over an unledgered batch skips those events forever.

Trait Implementations

impl InboundEventHandler for BatchingPersist<'_>

fn buffer_persist( &self, chat_id: &str, msg: &Message, wrapper: Option<([u8; 32], u64)>, ) -> bool

Bulk-sync persist intercept: return true to take ownership of persisting a committed DM/file message — the commit then SKIPS its per-message save AND its wrapper-ledger write (wrapper = the gift-wrap’s (id_bytes, created_at); the owner MUST commit it in the same transaction as the message row, or the message loses crash/drop recoverability). Streaming sync loops (see BatchingPersist) buffer here and drain many messages into one transaction. Default false keeps the per-message save.

fn on_dm_received(&self, chat_id: &str, msg: &Message, is_new: bool)

A DM text message was received and committed to STATE + DB.

fn on_file_received(&self, chat_id: &str, msg: &Message, is_new: bool)

A DM file attachment was received and committed to STATE + DB.

fn on_reaction_received(&self, chat_id: &str, msg: &Message)

A reaction was received and applied to a message.

fn on_message_deleted(&self, chat_id: &str, message_id: &str)

A previously-stored message was deleted by its sender (Layer 2 cooperative hide via NIP-09 over NIP-17). Frontend drops the row.

fn on_community_invite(&self, community_id: &str)

A Community invite was received over a gift wrap and the local user was joined (member-view Community persisted). Platform refreshes the Community subscription so messages start flowing, and surfaces the new Community in the UI.

fn on_community_message(&self, chat_id: &str, msg: &Message, is_new: bool)

A new Community channel message was received, ingested into STATE, and persisted.

fn on_community_update(&self, chat_id: &str, target_id: &str, msg: &Message)

A reaction or edit was applied to an existing Community message. target_id is the affected message; msg is the live-updated view.

fn on_community_removed(&self, chat_id: &str, target_id: &str)

A Community message was removed (cooperative delete / moderation tombstone).

fn on_community_presence( &self, chat_id: &str, npub: &str, joined: bool, event_id: &str, created_at: u64, invited_by: Option<&str>, invited_label: Option<&str>, )

A join/leave presence announcement. created_at is the authenticated inner timestamp; invited_by/invited_label carry invite attribution when present.

fn on_community_typing(&self, chat_id: &str, npub: &str, until: u64)

A Community typing indicator (ephemeral). until is the unix-secs the typer stops being active.

fn on_community_webxdc( &self, chat_id: &str, npub: &str, topic_id: &str, node_addr: Option<&str>, event_id: &str, created_at: u64, )

A WebXDC realtime peer signal. node_addr = Some advertises an Iroh node, None = peer-left.

fn on_community_self_removed(&self, community_id: &str)

The local user was removed from a Community (kick / ban / a leave authored on another device). Local data is torn down (epoch keys retained); the platform surfaces it + refreshes subs.

fn on_community_refreshed(&self, community_id: &str)

A Community’s control plane was refreshed in realtime (banlist/roles/metadata/mode change, or a re-founding followed). The platform re-reads display state.

fn on_community_dissolved(&self, community_id: &str)

A Community was DISSOLVED by its owner (CORD-02 §9): sealed read-only, held keys still open history but nothing new is honored. The platform surfaces the grave.

fn on_channel_keyed( &self, _community_id: &str, _channel_id: &str, _backfilled: usize, )

A Private channel is now readable — its key arrived, by rekey delivery or by a grant’s key vend. channel_id is the 32-byte hex id.

fn on_subscription_ready(&self, _communities: usize)

The realtime Community subscription REGISTERED: healthy relays deliver live channel events from this moment (AUTH-gating relays join as their stream auth completes in the background). Fires once per listen, after the startup refresh commits — even when communities is 0, so “subscribed to nothing” and “still connecting” are distinguishable. Before this, messages are only recoverable by a later sync, not live.