Trait InboundEventHandler 

pub trait InboundEventHandler: Send + Sync {
    // Provided methods
    fn on_dm_received(&self, _chat_id: &str, _msg: &Message, _is_new: bool) { ... }
    fn on_file_received(&self, _chat_id: &str, _msg: &Message, _is_new: bool) { ... }
    fn on_reaction_received(&self, _chat_id: &str, _msg: &Message) { ... }
    fn on_message_deleted(&self, _chat_id: &str, _message_id: &str) { ... }
    fn on_community_invite(&self, _community_id: &str) { ... }
    fn on_community_message(
        &self,
        _chat_id: &str,
        _msg: &Message,
        _is_new: bool,
    ) { ... }
    fn on_community_update(
        &self,
        _chat_id: &str,
        _target_id: &str,
        _msg: &Message,
    ) { ... }
    fn on_community_removed(&self, _chat_id: &str, _target_id: &str) { ... }
    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>,
    ) { ... }
    fn on_community_typing(&self, _chat_id: &str, _npub: &str, _until: u64) { ... }
    fn on_community_webxdc(
        &self,
        _chat_id: &str,
        _npub: &str,
        _topic_id: &str,
        _node_addr: Option<&str>,
        _event_id: &str,
        _created_at: u64,
    ) { ... }
    fn on_community_self_removed(&self, _community_id: &str) { ... }
    fn on_channel_keyed(
        &self,
        _community_id: &str,
        _channel_id: &str,
        _backfilled: usize,
    ) { ... }
    fn on_subscription_ready(&self, _communities: usize) { ... }
    fn on_community_refreshed(&self, _community_id: &str) { ... }
    fn on_community_dissolved(&self, _community_id: &str) { ... }
    fn buffer_persist(
        &self,
        _chat_id: &str,
        _msg: &Message,
        _wrapper: Option<([u8; 32], u64)>,
    ) -> bool { ... }
}

Platform-specific callbacks for inbound event processing.

Same pattern as SendCallback/ProfileSyncHandler — trait with default no-ops. Platforms implement only the hooks they need.

Provided Methods

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_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.

The inverse of the silent-mute failure: a bot granted access can act the moment it can actually read, rather than polling for a channel it has no way to know it is waiting on.

backfilled counts the messages that predate the grant and were pulled into LOCAL STATE before this fired. They are history, not delivery: none of them reach on_message — read them explicitly (get_messages_before) and decide what deserves acting on.

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.

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 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.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl InboundEventHandler for BatchingPersist<'_>

impl InboundEventHandler for NoOpEventHandler