Struct ProtocolEngine 

pub struct ProtocolEngine {
    pub batch_depth: Cell<u32>,
    pub batch_persist_dirty: Cell<bool>,
    /* private fields */
}

Fields

batch_depth: Cell<u32>

While > 0, persist() only flips batch_persist_dirty instead of serializing+writing. AppCore wraps catch-up bursts and other multi-event entry points so an N-event burst issues one persist instead of N. The exclusive SQLite write under iOS DELETE-mode journaling can keep UI reads blocked on the connection mutex for hundreds of ms each — N of them stacked produced the multi-second foreground freeze.

batch_persist_dirty: Cell<bool>

Implementations

impl ProtocolEngine

pub fn ingest_app_keys_snapshot( &mut self, owner_pubkey: PublicKey, app_keys: AppKeys, created_at: u64, ) -> Result<ProtocolRetryBatch>

pub fn ingest_app_keys_event( &mut self, event: &Event, ) -> Result<ProtocolRetryBatch>

pub fn ingest_app_keys_event_with_outcome( &mut self, event: &Event, ) -> Result<ProtocolMetadataIngestionResult>

impl ProtocolEngine

pub fn load_or_create_for_local_device( storage: Arc<dyn StorageAdapter>, owner_pubkey: PublicKey, device_keys: &Keys, ) -> Result<Self>

pub fn debug_snapshot(&self) -> ProtocolEngineDebugSnapshot

pub fn is_known_local_owner_device(&self, device_pubkey: PublicKey) -> bool

pub fn owner_hint_for_device( &self, device_pubkey: PublicKey, ) -> Option<ProtocolDeviceOwnerHint>

pub fn has_pending_inbound_direct_events(&self) -> bool

pub fn has_pending_retry_work(&self) -> bool

pub fn has_ready_group_sender_key_retry_work(&self) -> bool

Whether another bounded history-recovery pass can make progress now. This excludes unchanged failed ciphertexts and ignores this batch’s spent budget.

pub fn has_pending_inbound_direct_event_id(&self, event_id: &str) -> bool

pub fn queued_owner_claim_targets(&self) -> Vec<String>

pub fn direct_send_readiness( &self, peer_pubkey: PublicKey, ) -> DirectSendReadiness

pub fn authenticate_local_owner_for_sending( &mut self, owner_keys: &Keys, ) -> Result<()>

pub fn local_invite(&self) -> Option<Invite>

pub fn local_invite_response_pubkey(&self) -> Option<PublicKey>

pub fn known_message_author_pubkeys(&self) -> Vec<PublicKey>

pub fn message_author_pubkeys_filtered<F>( &self, accept_owner: F, ) -> Vec<PublicKey>

where F: Fn(PublicKey) -> bool,

Walks every session and returns its expected event-author pubkeys, but only for sessions whose peer owner passes the accept_owner predicate. The owner-aware variant lets the caller drop blocked / non-accepted peers from the subscription filter without losing the device-ephemeral keys that nostr actually filters on.

pub fn has_usable_direct_session_for_owner(&self, owner: PublicKey) -> bool

Whether an authorized, verified peer device has a send-capable session. Shares the message-author projection and its session/roster invalidation.

pub fn is_known_message_author(&self, author: PublicKey) -> bool

pub fn known_group_sender_event_pubkeys(&self) -> Vec<PublicKey>

pub fn group_sender_event_pubkeys_for_owner( &self, owner: PublicKey, ) -> Vec<PublicKey>

pub fn group_sender_event_pubkeys_for_group( &self, group_id: &str, ) -> Vec<PublicKey>

pub fn is_known_group_sender_event_author(&self, author: PublicKey) -> bool

pub fn is_potential_group_sender_key_event(&self, event: &Event) -> bool

pub fn is_group_sender_key_candidate_with_local_group_context( &self, event: &Event, ) -> bool

pub fn header_message_sender_has_verified_owner(&self, event: &Event) -> bool

pub fn header_message_sender_has_tracked_session(&self, event: &Event) -> bool

pub fn known_device_identity_pubkeys_for_owner( &self, owner_pubkey: PublicKey, ) -> Vec<PublicKey>

pub fn known_device_identity_pubkeys_for_owner_with_snapshot( &self, snapshot: &SessionManagerSnapshot, owner_pubkey: PublicKey, ) -> Vec<PublicKey>

pub fn message_author_pubkeys_for_owner( &self, owner_pubkey: PublicKey, ) -> Vec<PublicKey>

pub fn session_manager_snapshot(&self) -> SessionManagerSnapshot

SessionManager::snapshot clones every user record + every device state — the runtime debug builder fans out per known user, so callers that hit multiple owners in one pass must share a single snapshot via the _with_snapshot helpers below instead of paying that clone cost per owner.

pub fn message_session_debug_snapshots_with_snapshot( snapshot: &SessionManagerSnapshot, owner_pubkey: PublicKey, ) -> Vec<ProtocolMessageSessionDebugSnapshot>

pub fn verified_message_session_snapshots_for_owner( &self, owner_pubkey: PublicKey, ) -> Vec<ProtocolMessageSessionDebugSnapshot>

pub fn active_session_count_for_owner_with_snapshot( snapshot: &SessionManagerSnapshot, owner_pubkey: PublicKey, ) -> usize

pub fn active_session_count_for_owner(&self, owner_pubkey: PublicKey) -> usize

pub fn active_roster_session_count_for_owner( &self, owner_pubkey: PublicKey, ) -> usize

pub fn active_roster_session_count_for_owner_with_snapshot( &self, snapshot: &SessionManagerSnapshot, owner_pubkey: PublicKey, ) -> usize

pub fn owner_device_binding_is_verified( &self, owner_pubkey: PublicKey, device_pubkey: PublicKey, ) -> bool

pub fn known_verified_peer_owner_pubkeys(&self) -> Vec<PublicKey>

pub fn has_delivery_blocking_message_work(&self, message_id: &str) -> bool

impl ProtocolEngine

pub fn install_device_sync_group( &mut self, snapshot: GroupSnapshot, ) -> Result<bool>

Install metadata copied from an authenticated sibling device. Signed roster facts can advance this copy, but restoring removed membership requires a newer revision.

pub fn ingest_group_roster_fact_event( &mut self, event: &Event, ) -> Result<Option<ProtocolGroupRosterIngestionResult>>

impl ProtocolEngine

pub fn owns_group_data_stream(&self, chat_id: &str, author: PublicKey) -> bool

pub fn subscribable_group_sender_event_pubkeys(&self) -> Vec<PublicKey>

Authors learned from private distributions for groups this device belongs to.

pub fn pending_group_publish_effects(&self) -> Vec<ProtocolEffect>

Ready group ciphertext remains here until the application’s durable outbox owns it. Reoffering the same signed events never advances ratchets.

pub fn has_pending_group_publish(&self, event_id: &str) -> bool

pub fn ack_group_publish_effects( &mut self, effects: &[ProtocolEffect], ) -> Result<()>

Call only after the complete publication batch is committed to the application outbox (or durably rejected by its block/removal policy).

impl ProtocolEngine

pub fn signed_local_device_authorization(&self) -> Option<bool>

Whether retained, verified identity-signed evidence authorizes this device.

pub fn ingest_invite_response_owner_proof( &mut self, invite: &Invite, response: &Event, claimed_owner: PublicKey, authenticated_device: PublicKey, ) -> Result<ProtocolRetryBatch>

Read the account-signed authorization carried by a successfully decrypted handshake. The caller supplies the owner and device authenticated by that handshake, so unrelated signed records cannot establish its sender.

impl ProtocolEngine

pub fn message_targets_another_device(&self, event: &Event) -> bool

Shared bootstrap authors can expose ciphertext addressed to other devices. Untargeted session messages remain eligible for authenticated decryption.

pub fn has_due_pending_retry_work(&self, now: NdrUnixSeconds) -> bool

pub fn process_direct_message_event( &mut self, event: &Event, ) -> Result<Option<ProtocolDecryptedMessage>>

pub fn process_group_outer_event( &mut self, event: &Event, ) -> Result<ProtocolGroupIncomingResult>

Process a local group ciphertext extracted from an authenticated pairwise wrapper after its sender/group binding was checked. Never pass a raw network event here or use it as a fallback for failed direct decryption.

pub fn process_group_pairwise_payload( &mut self, payload: &[u8], from_owner_pubkey: PublicKey, from_sender_device_pubkey: Option<PublicKey>, ) -> Result<ProtocolGroupIncomingResult>

pub fn process_local_sibling_group_pairwise_payload( &mut self, payload: &[u8], from_owner_pubkey: PublicKey, from_sender_device_pubkey: Option<PublicKey>, ) -> Result<ProtocolGroupIncomingResult>

pub fn pending_group_decrypted_delivery( &self, event_id: &str, ) -> Result<Option<GroupIncomingEvent>>

Resolve a sender-key delivery already authenticated and durably journaled. External pairwise group-message payloads remain unsupported. The caller acknowledges this ID only after its application snapshot is saved.

pub fn retry_pending_protocol( &mut self, now: NdrUnixSeconds, ) -> Result<ProtocolRetryBatch>

pub fn ack_pending_decrypted_deliveries(&mut self) -> Result<()>

pub fn ack_decrypted_delivery_ids( &mut self, event_ids: &HashSet<String>, ) -> Result<()>

Only acknowledge deliveries that the application has durably applied. Other saves must not discard plaintext waiting for its first delivery.

impl ProtocolEngine

pub fn import_private_invite_session_once( &mut self, response_event_id: &str, owner_pubkey: PublicKey, authenticated_device: PublicKey, state: SessionState, now: UnixSeconds, ) -> Result<ProtocolInviteSessionImportOutcome>

pub fn persisted_invite_owner_device_is_authorized( storage: Arc<dyn StorageAdapter>, local_owner_pubkey: PublicKey, local_device_keys: &Keys, invite_owner_pubkey: PublicKey, invite_device_pubkey: PublicKey, ) -> Result<bool>

Reads only existing protocol state and checks exact signed AppKeys evidence. It never creates protocol state or treats a generic cached roster projection as authorization.

pub fn invite_owner_device_is_authorized( &self, invite_owner_pubkey: PublicKey, invite_device_pubkey: PublicKey, ) -> bool

Checks exact signed evidence, including an encrypted proof ingested by a read-only notification preview. Generic roster projections do not count.

impl ProtocolEngine

pub fn message_author_pubkeys_by_priority<F>( &self, accept_owner: F, ) -> Vec<PublicKey>

where F: Fn(PublicKey) -> bool,

Message authors of the accepted owners, most important first: the live ratchet keys of active sessions, then of inactive ones, then keys that only still have missed messages from older ratchet periods. A subscription that reaches a relay limit drops from the end.

impl ProtocolEngine

pub fn hold_pending_direct_sends(&mut self, peer: PublicKey, hold: bool)

Runtime hold while private block state is being applied. The owning app restores it from signed account state before allowing retry work.

pub fn retire_pending_direct_sends( &mut self, peer: PublicKey, through: Option<u64>, ) -> Result<usize>

Durably cancel unsent direct-chat intents after a local block. Group membership/key controls addressed to this peer keep their group chat ID and are retained, as are every other conversation’s pending deliveries.

pub fn retire_pending_local_sibling_events( &mut self, matches: impl Fn(PublicKey, &UnsignedEvent) -> bool, ) -> Result<usize>

Retire matching plaintext sibling intents, including intents waiting for roster discovery. Already sealed events and all other queues are untouched. Callers must durably migrate the source data first and must not expose this engine for sending if retirement fails.

impl ProtocolEngine

pub fn enter_batch(&self)

pub fn exit_batch(&mut self) -> Result<()>

impl ProtocolEngine

pub fn group_id_for_sender_event_author( &self, author: PublicKey, ) -> Option<String>

Resolve an authenticated private carrier without advertising group authors.

pub fn has_pending_group_pairwise_payloads(&self) -> bool

pub fn missing_group_metadata_sources( &self, ) -> Vec<(PublicKey, String, PublicKey)>

A bounded rotating slice of durable, authenticated key distributions still waiting for their group metadata, including after a restart.

pub fn resend_private_group_context( &mut self, group_id: &str, requester: PublicKey, author: Option<PublicKey>, ) -> Result<Vec<ProtocolEffect>>

Resend only to an existing member. Ordinary members’ metadata copies still pass the normal admin admission check; they cannot establish authority.

impl ProtocolEngine

pub fn observe_invite_event( &mut self, event: &Event, ) -> Result<ProtocolRetryBatch>

pub fn observe_invite_event_with_outcome( &mut self, event: &Event, ) -> Result<ProtocolMetadataIngestionResult>

pub fn observe_invite_response_event( &mut self, event: &Event, ) -> Result<ProtocolRetryBatch>

pub fn accept_invite( &mut self, invite: &Invite, owner_pubkey_hint: Option<PublicKey>, ) -> Result<ProtocolAcceptInviteOutcome>

pub fn import_session_state( &mut self, peer_pubkey: PublicKey, device_id: Option<String>, state: SessionState, now: UnixSeconds, ) -> Result<ProtocolRetryBatch>

pub fn create_group( &mut self, name: String, member_owners: Vec<PublicKey>, now: UnixSeconds, ) -> Result<ProtocolGroupSendResult>

pub fn update_group_name( &mut self, group_id: &str, name: String, ) -> Result<ProtocolGroupSendResult>

pub fn update_group_picture( &mut self, group_id: &str, picture: Option<String>, ) -> Result<ProtocolGroupSendResult>

pub fn update_group_about( &mut self, group_id: &str, about: Option<String>, ) -> Result<ProtocolGroupSendResult>

pub fn add_group_members( &mut self, group_id: &str, members: Vec<PublicKey>, ) -> Result<ProtocolGroupSendResult>

pub fn admit_group_invite_member( &mut self, group_id: &str, token: &str, member: PublicKey, max_uses: Option<u32>, ) -> Result<ProtocolGroupSendResult>

Admission and its distinct-owner receipt share one durable checkpoint. Force persistence even in a receive batch: never publish membership before the use limit is durable. Retry after a crash cannot admit an extra owner.

pub fn group_invite_use_count(&self, group_id: &str, token: &str) -> usize

pub fn group_snapshot(&self, group_id: &str) -> Option<GroupSnapshot>

pub fn group_invite_used_by( &self, group_id: &str, token: &str, member: PublicKey, ) -> bool

pub fn remove_group_member( &mut self, group_id: &str, member: PublicKey, ) -> Result<ProtocolGroupSendResult>

pub fn set_group_admin( &mut self, group_id: &str, member: PublicKey, is_admin: bool, ) -> Result<ProtocolGroupSendResult>

pub fn send_group_payload( &mut self, group_id: &str, payload: Vec<u8>, inner_event_id: Option<String>, ) -> Result<ProtocolGroupSendResult>

pub fn send_direct_text( &mut self, peer_pubkey: PublicKey, chat_id: &str, text: &str, expires_at_secs: Option<u64>, now: UnixSeconds, ) -> Result<ProtocolDirectSendResult>

pub fn send_direct_text_created_at( &mut self, peer_pubkey: PublicKey, chat_id: &str, text: &str, expires_at_secs: Option<u64>, created_at: UnixSeconds, now: UnixSeconds, ) -> Result<ProtocolDirectSendResult>

Keep the authored time separate from the transport/retry clock.

pub fn send_direct_unsigned_event( &mut self, peer_pubkey: PublicKey, chat_id: &str, rumor: UnsignedEvent, now: UnixSeconds, ) -> Result<ProtocolDirectSendResult>

pub fn send_direct_unsigned_event_to_peer_only( &mut self, peer_pubkey: PublicKey, chat_id: &str, rumor: UnsignedEvent, now: UnixSeconds, ) -> Result<ProtocolDirectSendResult>

pub fn send_local_sibling_unsigned_event( &mut self, conversation_owner: PublicKey, chat_id: &str, rumor: UnsignedEvent, now: UnixSeconds, ) -> Result<ProtocolDirectSendResult>

impl ProtocolEngine

pub fn authorization_events(&self) -> Vec<Event>

Original signed evidence for authenticated own-device reconciliation.

impl ProtocolEngine

pub fn fork_for_test(&self) -> Result<Self>

pub fn session_manager_snapshot_for_test(&self) -> SessionManagerSnapshot

pub fn group_manager_snapshot_for_test(&self) -> GroupManagerSnapshot

pub fn pending_inbound_for_test(&self) -> Vec<ProtocolPendingInboundTestDebug>

pub fn known_message_author_cache_build_count_for_test(&self) -> u64

pub fn pending_decrypted_deliveries_len_for_test(&self) -> usize

impl ProtocolEngine

pub fn enable_background_history_recovery_pacing(&self)

Pace automatic blind history recovery by its measured work cost. Manual protocol drivers retain their existing per-call work bounds unless they opt in. Hosts must use group_sender_key_retry_delay when scheduling continuations; calls from other events obey the same internal work gate.

pub fn group_sender_key_retry_delay(&self) -> Duration

Earliest useful blind-search continuation. Prepared receive plans can be applied immediately; membership and ratchet validation remain mandatory.

impl ProtocolEngine

pub fn load_for_notification_preview( storage: Arc<dyn StorageAdapter>, owner_pubkey: PublicKey, device_keys: &Keys, ) -> Result<Option<Self>>

Load an ephemeral receive preview without initializing an account, loading outgoing queues, or writing a startup checkpoint. Callers must provide an isolated storage overlay for any legacy migration writes and discard the engine after use; do not finish its batch or use it to send.

impl ProtocolEngine

pub fn has_device_roster_entry_for_owner( &self, owner_pubkey: PublicKey, device_pubkey: PublicKey, ) -> bool