Enum Event 

pub enum Event {
    MessageSent {
        message_id: String,
        sender: String,
        recipient: String,
        content: String,
        priority: String,
        requires_ack: bool,
        timestamp: i64,
        lamport_clock: u64,
        forward_info: Option<ForwardInfoEvent>,
    },
    MessageReceived {

        message_id: String,
        sender: String,
        recipient: String,
        content: String,
        hop_count: u8,
        transport: String,
        timestamp: i64,
        lamport_clock: u64,
        reply_to_msg: Option<String>,
        reply_context: Option<Box<ReplyContextEvent>>,
        content_type: String,
        media_metadata: Option<MediaMetadata>,
        forward_info: Option<ForwardInfoEvent>,
        encrypted: bool,
        app_id: String,
    
},
    MessageDelivered {
        message_id: String,
        latency_ms: u64,
        hop_count: u8,
        transport: String,
    },
    MessageFailed {
        message_id: String,
        reason: String,
        retry_count: u32,
    },
    MessageDecryptionFailed {
        message_id: String,
        sender: String,
        code: DecryptionFailureCode,
        reason: String,
        sealed_at_ms: Option<u64>,
        session_established_at_ms: Option<u64>,
    },
    TransportSwitched {
        from: Option<String>,
        to: String,
        reason: String,
    },
    RelayPromoted {
        connection_count: usize,
        battery_level: Option<u8>,
    },
    RelayDemoted {
        reason: String,
    },
    NeighborDiscovered {
        peer_id: String,
        transport: String,
        rssi: Option<i16>,
    },
    NeighborLost {
        peer_id: String,
    },
    IdentityReady {
        address: String,
    },
    NetworkMetrics {
        neighbor_count: usize,
        relay_count: usize,
        delivery_ratio: f32,
        avg_latency_ms: u64,
    },
    FileProgress {
        file_id: String,
        chunks_sent: u32,
        total_chunks: u32,
        percentage: u8,
    },
    FileReceived {

        file_id: String,
        file_name: String,
        file_size: u64,
        sender: String,
        content_type: String,
        media_metadata: Option<MediaMetadata>,
        file_data: String,
        timestamp: Option<i64>,
        caption: Option<String>,
        reply_to_msg: Option<String>,
        reply_context: Option<Box<ReplyContextEvent>>,
        forward_info: Option<ForwardInfoEvent>,
        app_id: Option<String>,
    
},
    FileReceiveFailed {
        file_id: String,
        file_name: String,
        sender: String,
        reason: String,
    },
    MediaSent {
        file_id: String,
        content_type: String,
        recipient: String,
    },
    MediaSendFailed {
        file_id: String,
        recipient: String,
        reason: String,
    },
    MessageDeferred {
        message_id: String,
        recipient: String,
        reason: String,
        retry_count: u32,
        next_retry_at: Option<i64>,
    },
    MessageRetrying {
        message_id: String,
        recipient: String,
        retry_count: u32,
        next_retry_at: i64,
    },
    MessageUndeliverable {
        message_id: String,
        recipient: String,
        reason: String,
        file_id: Option<String>,
    },
    MediaResendRequired {
        file_id: String,
        recipient: String,
        file_name: String,
        file_size: u64,
        app_id: Option<String>,
    },
    AckEvicted {
        message_id: String,
        priority: String,
        reason: String,
    },
    FragmentAssemblyEvicted {
        message_id: String,
        completion_percent: u8,
        reason: String,
    },
    RelayDemotedBattery {
        battery_level: u8,
        min_required: u8,
    },
    SecureSessionEstablished {
        peer_id: String,
        group_id: String,
        is_session: bool,
        initiated_by_local: bool,
    },
    SecureSessionFailed {
        peer_id: String,
        reason: String,
    },
    ConvergenceDiag {
        stage: String,
        peer_id: String,
        detail: String,
    },
    WelcomeSendAttempted {
        peer_id: String,
        message_id: String,
        group_id: String,
        attempt: u32,
    },
    WelcomeSendSucceeded {
        peer_id: String,
        message_id: String,
        group_id: String,
        attempt: u32,
    },
    WelcomeSendFailed {
        peer_id: String,
        message_id: String,
        group_id: String,
        attempt: u32,
        reason_code: WelcomeReasonCode,
        transport_error: Option<String>,
        retryable: bool,
        next_retry_at: Option<i64>,
    },
    WelcomeSendExpired {
        peer_id: String,
        message_id: String,
        attempt: u32,
        reason_code: WelcomeReasonCode,
    },
    ConnectionRequestReceived {
        sender: String,
        sender_name: String,
        timestamp: i64,
        key_package: Option<Vec<u8>>,
        initial_message: Option<String>,
    },
    ConnectionRequestUndeliverable {
        recipient: String,
        message_id: String,
        reason: String,
    },
    ConnectionAccepted {
        accepted_by: String,
        accepted_by_name: String,
        timestamp: i64,
        key_package: Option<Vec<u8>>,
    },
    ConnectionRejected {
        rejected_by: String,
    },
    ConnectionRequestCancelled {
        cancelled_by: String,
    },
    GroupCreated {
        group_id: String,
        name: String,
    },
    GroupMessageReceived {
        group_id: String,
        sender: String,
        content: String,
        timestamp: String,
        message_id: String,
        reply_to_msg: Option<String>,
        forward_info: Option<ForwardInfoEvent>,
        media_metadata: Option<MediaMetadata>,
        content_type: Option<String>,
    },
    GroupMemberAdded {
        group_id: String,
        user_id: String,
        added_by: String,
        group_name: Option<String>,
        authorized: Option<bool>,
    },
    GroupMemberRemoved {
        group_id: String,
        user_id: String,
        removed_by: String,
        authorized: Option<bool>,
    },
    GroupInfo {
        group_id: String,
        name: String,
        created_by: String,
        created_at: String,
        members: Vec<GroupInfoMember>,
    },
    UserGroups {
        groups: Vec<UserGroupSummary>,
    },
    GroupError {
        reason: String,
        group_id: Option<String>,
    },
    GroupRelaySyncChanged {
        group_id: String,
        synced: bool,
        reason: String,
    },
    UsernameResolved {
        username: String,
        claims: Vec<UsernameClaim>,
        rejected: u32,
        truncated: u32,
    },
    GroupMessageSent {
        group_id: String,
        message_ids: Vec<String>,
        member_count: u32,
    },
    GroupMessagePartialFailure {
        group_id: String,
        failed_members: Vec<String>,
        succeeded_members: Vec<String>,
    },
    GroupMessageDeliveryReport {
        group_id: String,
        message_id: String,
        delivered: Vec<String>,
        pushed: Vec<String>,
        missed_reissued: Vec<String>,
    },
    GroupRichExtrasDropped {
        group_id: String,
        unknown_members: Vec<String>,
    },
    GroupUnauthorizedMembershipChange {
        group_id: String,
        committer: String,
        added: Vec<String>,
        removed: Vec<String>,
        reason: String,
        enforced: bool,
    },
    GroupEpochForkDetected {
        group_id: String,
        local_epoch: Option<u64>,
    },
    GroupEpochForkResolved {
        group_id: String,
        resolved_epoch: u64,
        failed_members: Vec<String>,
    },
    GroupRoleChanged {
        group_id: String,
        user_id: String,
        new_role: String,
        changed_by: String,
    },
    GroupRenamed {
        group_id: String,
        new_name: String,
        old_name: Option<String>,
        renamed_by: String,
    },
    ServiceDiscovered {
        query_id: String,
        service_id: String,
        version: String,
        provider_peer_id: String,
        capabilities: HashMap<String, String>,
        hop_count: u8,
    },
    ServiceRequestReceived {
        request_id: String,
        service_id: String,
        method: String,
        body: String,
        sender: String,
        encrypted: bool,
    },
    ServiceResponseReceived {
        request_id: String,
        service_id: String,
        status: String,
        body: String,
        provider_peer_id: String,
        encrypted: bool,
    },
    PresenceUpdated {
        peer_id: String,
        status: PresenceStatus,
        timestamp: i64,
        last_seen_ms: Option<i64>,
        source: PresenceSource,
    },
    TypingIndicatorReceived {
        sender: String,
        conversation_id: String,
        is_typing: bool,
        timestamp: i64,
    },
    ReadReceiptReceived {
        sender: String,
        message_ids: Vec<String>,
        timestamp: i64,
    },
    DorsScoreUpdated {
        scores: Vec<(String, f32)>,
    },
    DorsTransportSelected {
        from: Option<String>,
        transport: String,
        reason_code: DorsReasonCode,
        score: f32,
    },
    DorsTransportSwitched {
        from: Option<String>,
        to: String,
        reason_code: DorsReasonCode,
        reason_detail: Option<String>,
    },
    DorsEscalationTriggered {
        phase: DorsEscalationPhase,
        from: String,
        to: String,
        reason_code: DorsEscalationReasonCode,
        reason_detail: Option<String>,
    },
    SecurityWarning {
        peer_id: String,
        reason_code: SecurityWarningCode,
        reason: String,
    },
    MessageRelayed {
        message_id: String,
        sender: String,
        recipient: String,
        hop_count: u8,
        remaining_ttl: u8,
    },
    UserBlocked {
        user_id: String,
    },
    UserUnblocked {
        user_id: String,
    },
    DataChanged {
        space_id: String,
        doc_id: String,
        delta_bytes: u64,
    },
    DataDocRemoved {
        space_id: String,
        doc_id: String,
        by: DocRemovedBy,
    },
    DataDocSizeWarning {
        space_id: String,
        doc_id: String,
        compacted_bytes: u64,
        cap_bytes: u64,
    },
    DataAttachmentRequested {
        space_id: String,
        peer_id: String,
        hash: String,
    },
    DataAttachmentReceived {
        space_id: String,
        peer_id: String,
        hash: String,
        data: String,
    },
    DataAttachmentUnavailable {
        space_id: String,
        peer_id: String,
        hash: String,
        reason: String,
    },
    DataDocUnsyncable {
        space_id: String,
        doc_id: String,
        bytes: u64,
        reason: String,
    },
}

Events that can occur in the protocol.

Note: This type implements a custom Debug that redacts sensitive fields (message content) to prevent accidental logging of sensitive data.

Variants

MessageSent

A message was sent (queued for delivery).

Fields

message_id: String

ID of the sent message.

sender: String

Sender’s user ID.

recipient: String

Recipient’s user ID.

content: String

Content of the sent message.

priority: String

Priority of the message when sent.

requires_ack: bool

Whether the message requires an acknowledgement.

timestamp: i64

When the message was queued for delivery (wall-clock, for display).

lamport_clock: u64

Lamport logical clock value for causal ordering.

forward_info: Option<ForwardInfoEvent>

Forwarding attribution (present when this is a forwarded message).

MessageReceived

A message was received.

Fields

message_id: String

ID of the received message.

sender: String

Sender’s user ID.

recipient: String

Recipient’s user ID.

content: String

Message content.

hop_count: u8

Number of hops the message traversed.

transport: String

Transport used for final delivery.

timestamp: i64

When the message was received (wall-clock, for display).

lamport_clock: u64

Lamport logical clock value for causal ordering.

reply_to_msg: Option<String>

ID of the message this is replying to (optional).

reply_context: Option<Box<ReplyContextEvent>>

Quoted-reply context (present when this message quotes another). Boxed to keep the Event enum’s by-value size in check.

content_type: String

The type of content (text, image, video, etc.).

media_metadata: Option<MediaMetadata>

Media metadata (present for non-text content).

forward_info: Option<ForwardInfoEvent>

Forwarding attribution (present when this is a forwarded message).

encrypted: bool

true when the content arrived MLS-encrypted and was decrypted by this node; false for plaintext accepted under the require_encryption = false opt-out.

app_id: String

Application id the sender stamped on this message: its configured id, or the per-send id of a rich send.

For an instance serving several local applications, this is what routes the message to the right client. It is cleartext and unsigned on the wire, so any carrier could have rewritten it (threat model R17): route on it, never authorize on it. The engine delivers every message whatever this says.

MessageDelivered

A message was successfully delivered (ACK received).

Fields

message_id: String

ID of the delivered message.

latency_ms: u64

Milliseconds from the first transmit a carrier accepted to the acknowledgement, including any time the message then waited for the peer. Time before any carrier accepted it is not included.

hop_count: u8

Number of hops traversed.

transport: String

Transport used.

MessageFailed

A message failed to deliver.

Fields

message_id: String

ID of the failed message.

reason: String

Reason for failure.

retry_count: u32

Number of retries attempted.

MessageDecryptionFailed

An inbound encrypted message failed to decrypt on this attempt.

Advisory, not terminal, and emitted once per failed attempt. While EncryptionConfig::crypto_recovery_enabled is on (the default) a message that fails to decrypt is not delivery-ACKed, so the sender keeps retrying — and each resend of a DM is re-sealed against the peer’s current session, so a resend can actually land. Every failing attempt reports again, bounded by the sender’s ACK retry budget. Read this as “this attempt did not decrypt”; the terminal signals are Event::MessageFailed on the sender and FileReceiveFailed for media.

Fields

message_id: String

ID of the message that could not be decrypted.

sender: String

Sender’s user ID.

code: DecryptionFailureCode

Machine-readable decryption failure code.

reason: String

Clear failure reason for application handling/logging.

sealed_at_ms: Option<u64>

When the sender sealed the frame (sender clock, ms), read from the cleartext envelope. Unauthenticated: a hint for local heuristics, never for security decisions. None when the failure is not a 1:1 decrypt attempt (pending-queue drop, unparseable envelope, group).

session_established_at_ms: Option<u64>

When this device’s current session with sender was created or adopted (local clock, ms). None when there is no session, or it was established by an SDK that did not record the time. A frame sealed before this cannot have been sealed under this session, so its failure says nothing about whether the two sides agree now.

TransportSwitched

Transport was switched by DORS.

Fields

from: Option<String>

Previous transport (if any).

to: String

New transport.

reason: String

Reason for switch.

RelayPromoted

This device started acting as a relay — carrying traffic for other devices that cannot reach each other directly.

Reports observed behaviour, not capability: it fires because this device has been forwarding, so it needs no battery feed and can fire on a device that has never reported a level.

Fields

connection_count: usize

Neighbors held when this device started relaying.

battery_level: Option<u8>

Battery level at the time, or None when the host has reported none — the standing does not depend on it.

RelayDemoted

This device was demoted from relay role.

Fields

reason: String

Reason for demotion.

NeighborDiscovered

A new neighbor was discovered.

Fields

peer_id: String

The peer’s canonical user id — the same value the peer supplied as ProtocolConfig.user_id, on every transport. Valid directly as the recipient of send_message / send_connection_request.

transport: String

Transport used to discover.

rssi: Option<i16>

RSSI signal strength (if available).

NeighborLost

A neighbor was lost (disconnected).

Fields

peer_id: String

Peer ID of the lost neighbor.

IdentityReady

This device’s own address is known: MLS storage was opened and the identity key in it derived to address.

Fires once per successful initialize_mls, before any frame can be sent. address is this device’s Message.sender from here on, and what peers must be given to reach it. It is stable across restarts of the same profile, so an app that already stored it will be handed the same value rather than a new one.

Fields

address: String

This device’s self-certifying address (off1…).

NetworkMetrics

Network metrics update.

Fields

neighbor_count: usize

Number of active neighbors.

relay_count: usize

Number of active relays.

delivery_ratio: f32

Message delivery ratio (0.0-1.0).

avg_latency_ms: u64

Average message latency in milliseconds.

FileProgress

File transfer progress update.

Fields

file_id: String

File identifier.

chunks_sent: u32

Number of chunks sent so far.

total_chunks: u32

Total number of chunks.

percentage: u8

Progress percentage (0-100).

FileReceived

File was completely received.

Fields

file_id: String

File identifier.

file_name: String

File name.

file_size: u64

File size in bytes.

sender: String

Sender’s user ID.

content_type: String

The content type of the media (image, video, file, etc.).

media_metadata: Option<MediaMetadata>

Media metadata from the first chunk (present for typed media).

file_data: String

Base64-encoded reassembled file data.

timestamp: Option<i64>

When the sender queued the transfer (chunk-0 outer message timestamp, wall-clock ms) — for display ordering alongside MessageReceived.timestamp. Absent only if the chunk-0 record was evicted before completion.

caption: Option<String>

Caption text from the sealed chunk-0 rich extras.

reply_to_msg: Option<String>

ID of the message this media replies to (sealed chunk-0 extras).

reply_context: Option<Box<ReplyContextEvent>>

Quoted-reply context (sealed chunk-0 extras). Boxed to keep the Event enum’s by-value size in check.

forward_info: Option<ForwardInfoEvent>

Forwarding attribution (sealed chunk-0 extras).

app_id: Option<String>

Application id the sender stamped on the transfer (chunk-0 outer message), with the meaning and the cleartext caveat of MessageReceived.app_id. Absent only if the chunk-0 record was evicted before completion, like timestamp.

FileReceiveFailed

An inbound file transfer was dropped before completion — the receiver hit a resource limit (too many concurrent transfers, per-sender quota, or the buffered-bytes budget), the reassembled file failed its integrity checks, or the transfer went stale (no chunks within the stale timeout). Terminal and fired at most once per transfer: the failed transfer’s remaining in-flight chunks are dropped silently. No FileReceived will follow for this file_id; the sender must re-send the file (under a fresh file_id) to retry.

Fields

file_id: String

File identifier.

file_name: String

File name from the chunk metadata.

sender: String

Sender’s user ID.

reason: String

Machine-readable reason the transfer was dropped.

MediaSent

All chunks of a media attachment were ACK-delivered.

Fields

file_id: String

File identifier for tracking.

content_type: String

The content type of the media.

recipient: String

Recipient’s user ID.

MediaSendFailed

An outbound media transfer was aborted before all chunks were delivered — a chunk failed to encrypt, or a chunk failed terminally in the outbox. No MediaSent will follow for this file_id; retry with a new send_media call.

Fields

file_id: String

File identifier for tracking.

recipient: String

Recipient’s user ID.

reason: String

Reason the transfer was aborted.

MessageDeferred

A message was deferred due to network conditions. The message will be retried automatically.

Fields

message_id: String

ID of the deferred message.

recipient: String

Recipient’s user ID.

Added when reason stopped rendering the transport error: the counterparty used to reach apps only inside that prose, which put an unhashed address on every telemetry record for a routine send failure. Carried as a field so the scrubber hashes it like any other actor id.

reason: String

Stable classification of the deferral, not a rendered error.

One of a fixed local vocabulary (peer_not_reachable, transport_not_connected, transport_send_failed, …). Branch on it if you must, but do not parse it for detail: the underlying error — which renders the peer — stays in the device log.

retry_count: u32

Current retry count.

next_retry_at: Option<i64>

Next retry scheduled time (Unix timestamp ms).

MessageRetrying

A retry for a previously deferred/unacked message was scheduled.

Emitted each time the retry machinery re-queues a message after a failed attempt (transport send error or ACK timeout). Non-terminal: MessageDelivered or MessageFailed still settles the message.

Fields

message_id: String

ID of the retrying message.

recipient: String

Recipient’s user ID.

retry_count: u32

Retry count this schedule corresponds to.

next_retry_at: i64

Absolute time the retry is scheduled for (Unix timestamp ms).

MessageUndeliverable

The transport layer reported the recipient unreachable for an in-flight message (e.g. the internet relay’s DeliveryError).

Non-terminal: the message stays in the outbox. A plain DM is parked — its ACK retry budget stops burning while the peer is provably offline — and is re-driven on reachability edges (transport reconnect, peer discovery, presence-online; the SDK adds parked recipients to the presence watchlist). It settles only via MessageDelivered or, at outbox-lifetime expiry, MessageFailed. Media chunks are not parked and keep the normal retry machinery. May fire multiple times for the same message_id while the recipient remains offline: a parked DM keeps an escalating reachability probe on every carrier (15s → 600s cap), and each probe that reaches the relay while the peer is still offline earns a fresh verdict and re-emits this event. Apps must treat it as a repeatable status signal, never as a terminal one. file_id is set when the message is a chunk of an outbound media transfer.

Fields

message_id: String

ID of the affected message.

recipient: String

Recipient’s user ID.

reason: String

Stable classification of the failure — recipient_unreachable on the relay-verdict path this event is normally reached by.

The transport’s own wording used to be appended here verbatim, and on the relay path that wording is written by the relay: unbounded remote text, shipped beside a recipient the telemetry scrubber hashes. It is now dropped at the boundary — kept in the device log, and on the internet path still delivered raw to apps on the bridges’ diagnostic channel.

file_id: Option<String>

Owning media transfer when the message is a media chunk.

MediaResendRequired

An outbound media transfer was in flight when the previous process died. The SDK persists only the transfer descriptor (never chunk bytes), so it cannot resume the transfer itself: the app must re-supply the file bytes via send_media with this file_id — they are checksum-validated against the original transfer.

Fields

file_id: String

File identifier of the interrupted transfer.

recipient: String

Recipient’s user ID.

file_name: String

Original file name.

file_size: u64

Total file size in bytes.

app_id: Option<String>

Per-send application id the transfer was started with, absent when it used the configured one. An instance serving several applications asks this one for the bytes.

AckEvicted

A pending ACK was evicted due to capacity constraints.

Fields

message_id: String

ID of the message whose ACK was evicted.

priority: String

Priority of the evicted message.

reason: String

Reason for eviction.

FragmentAssemblyEvicted

A fragment assembly was evicted to make room for new fragments.

Fields

message_id: String

ID of the message whose fragments were evicted.

completion_percent: u8

Completion percentage when evicted.

reason: String

Reason for eviction.

RelayDemotedBattery

Relay role was demoted due to battery constraints.

Fields

battery_level: u8

Battery level at time of demotion.

min_required: u8

Minimum required battery level.

SecureSessionEstablished

A secure MLS session was successfully established.

Fields

peer_id: String

Peer ID of the other party.

group_id: String

MLS group ID for the session.

is_session: bool

Whether this is a 1:1 session (true) or a multi-party group (false).

initiated_by_local: bool

Whether the local device initiated the session (sent the Welcome).

SecureSessionFailed

Failed to establish a secure MLS session.

Reports a failed handshake attempt, which is not the same as “the session with this peer is gone”. One case makes the difference visible: a Welcome refused for carrying an unprovable identity (SecurityWarningCode::GroupLeafIdentityUnproven, emitted alongside) is refused non-destructively, so any session already held with that peer stays live and usable. Apps must not tear down session state on this event alone.

reason is diagnostic text and must not be parsed. It carries no identifier, of this peer or of anyone else: the telemetry scrubber hashes peer_id and ships reason verbatim, so every arm that fills it contributes either a fixed string or MlsError::privacy_safe_reason, never a rendered error. The full error stays in the device log at the refusal site. This is a classification, so apps get the failure class here and must look to the log for the specifics.

Fields

peer_id: String

Peer ID of the other party.

reason: String

Reason for the failure.

ConvergenceDiag

Diagnostic breadcrumb for the 1:1 MLS convergence (Welcome receive / adopt / confirm) path. Emitted so the receiver side — which otherwise produces no event until it fully establishes or loudly fails — is observable in Metro. Pure instrumentation; carries no protocol effect.

Fields

stage: String

Fixed stage label, e.g. “welcome_received” or “welcome_branch”.

peer_id: String

Peer ID this breadcrumb concerns.

detail: String

Free-form key=value context (counts, branch taken, errors).

WelcomeSendAttempted

Welcome send lifecycle entered attempted state.

Fields

peer_id: String

Peer identifier for this welcome lifecycle.

message_id: String

Welcome message identifier for lifecycle correlation.

group_id: String

MLS group identifier associated with the welcome.

attempt: u32

1-based send attempt number.

WelcomeSendSucceeded

Welcome send lifecycle reached successful sent state.

Fields

peer_id: String

Peer identifier for this welcome lifecycle.

message_id: String

Welcome message identifier for lifecycle correlation.

group_id: String

MLS group identifier associated with the welcome.

attempt: u32

1-based send attempt number.

WelcomeSendFailed

Welcome send attempt failed and may be retried.

Fields

peer_id: String

Peer identifier for this welcome lifecycle.

message_id: String

Welcome message identifier for lifecycle correlation.

group_id: String

MLS group identifier associated with the welcome.

attempt: u32

1-based send attempt number.

reason_code: WelcomeReasonCode

Machine-readable reason code.

transport_error: Option<String>

Stable classification of the transport failure, when one was recorded — never the rendered error.

Both feeders named an identifier: the platform-supplied string is the relay’s own DeliveryError prose, and the locally raised one renders a transport error that interpolates the peer. peer_id and group_id beside it are hashed, so either would have undone that. Classified at the boundary, so the persisted record holds the token too — and again at each emit as a backstop. The second pass is unreachable today (every writer overwrites the field before its emit, so no record restored from an older build can carry raw text into an event) and kept because the field is persisted and has five writers: it holds the invariant if one of them ever becomes conditional.

retryable: bool

Whether this failure will be retried.

next_retry_at: Option<i64>

Next scheduled retry timestamp in Unix ms.

WelcomeSendExpired

Welcome send lifecycle reached terminal expiry.

Fields

peer_id: String

Peer identifier for this welcome lifecycle.

message_id: String

Welcome message identifier for lifecycle correlation.

attempt: u32

Final attempt number when lifecycle expired.

reason_code: WelcomeReasonCode

Terminal machine-readable reason code.

ConnectionRequestReceived

A connection request was received from another user.

Fields

sender: String

User ID of the sender.

sender_name: String

Display name of the sender.

timestamp: i64

Timestamp of the request (Unix ms).

key_package: Option<Vec<u8>>

MLS key package data (if provided for encrypted session setup).

initial_message: Option<String>

Optional first message sent along with the request.

ConnectionRequestUndeliverable

An outbound connection request could not be delivered: the transport reported the recipient unreachable (e.g. the relay’s DeliveryError for an offline peer), or the request exhausted its ACK retry budget (in which case a generic MessageFailed also fires for the same id). This is a status signal, not proof of permanent failure — the original request may still be delivered by the retry machinery if the peer comes back online. Apps typically surface “user is offline”; a user-initiated resend can therefore arrive alongside the retried original (the recipient sees the request event again, which accept/reject flows already tolerate).

Fields

recipient: String

Recipient the request was addressed to.

message_id: String

Message id returned by send_connection_request.

reason: String

Failure reason, drawn from a fixed local vocabulary: recipient_unreachable on the transport verdict path, or max_retries_exceeded / outbox_lifetime_exceeded / outbox_capacity_exceeded on the give-up paths.

The relay’s wording is no longer appended to the first of these — it is remote-chosen text, and recipient beside it is hashed by the telemetry scrubber.

ConnectionAccepted

A previously sent connection request was accepted.

Fields

accepted_by: String

User ID of the accepting party.

accepted_by_name: String

Display name of the accepting party.

timestamp: i64

Timestamp of the acceptance (Unix ms).

key_package: Option<Vec<u8>>

MLS key package data (if provided for encrypted session setup).

ConnectionRejected

A previously sent connection request was rejected.

Fields

rejected_by: String

User ID of the rejecting party.

ConnectionRequestCancelled

A previously sent connection request was cancelled by the sender.

Fields

cancelled_by: String

User ID of the party who cancelled their request.

GroupCreated

A group was created (from relay).

Fields

group_id: String

Group identifier.

name: String

Human-readable group name.

GroupMessageReceived

A message was received in a group (from relay).

Fields

group_id: String

Group identifier.

sender: String

User ID of the sender.

content: String

Message content.

timestamp: String

ISO-8601 timestamp.

message_id: String

Unique message identifier.

reply_to_msg: Option<String>

Optional reply-to message ID.

forward_info: Option<ForwardInfoEvent>

Forwarding attribution (present when this is a forwarded message).

media_metadata: Option<MediaMetadata>

Media metadata restored from the sealed __RICH_V1__ body of a rich group message (cloud attachments — including the encryption_key/iv secrets, which only ever travel inside the group MLS ciphertext). Absent on plain group messages.

content_type: Option<String>

Content-type rendering hint from the sealed body (text, image, video, …). Absent on plain group messages.

GroupMemberAdded

A member was added to a group (from relay).

Fields

group_id: String

Group identifier.

user_id: String

User ID of the added member.

added_by: String

User ID of who performed the add.

group_name: Option<String>

Human-readable group name (present when the invitee first joins).

authorized: Option<bool>

Whether added_by was authorized to make this change.

Some(false) means the change did happen — MLS accepted the commit and the roster really has changed — but the committer was not a known admin. The membership event is still emitted because the local roster must not diverge from MLS state; see Event::GroupUnauthorizedMembershipChange for the full signal.

None (absent in JSON) means authorization was not evaluated on the path that produced this event: our own join accepted from a Welcome (there is no prior group state to judge the inviter against) and relay reconciliation frames (no authenticated committer to judge). Events from an older core also omit the field. Only Some(_) is a positive statement either way.

The judgment is made against this member’s local replica of role state, which replicates best-effort and can lag — a legitimate change may be flagged Some(false), and different members can disagree about the same commit. Do not act on it automatically.

GroupMemberRemoved

A member was removed from a group (from relay).

Fields

group_id: String

Group identifier.

user_id: String

User ID of the removed member.

removed_by: String

User ID of who performed the removal.

authorized: Option<bool>

Whether this change was authorized (None = not evaluated on this path). See Event::GroupMemberAdded::authorized. On the relay reconciliation path the judgment applies to the frame’s authenticated wire sender, which is not necessarily the removed_by named here.

GroupInfo

Group info was received (from relay).

Fields

group_id: String

Group identifier.

name: String

Human-readable group name.

created_by: String

User ID of the group creator.

created_at: String

ISO-8601 creation timestamp.

members: Vec<GroupInfoMember>

Group member list.

UserGroups

User’s groups list was received (from relay).

Fields

groups: Vec<UserGroupSummary>

List of group summaries.

GroupError

A group operation failed (from relay).

The relay’s own wording is not carried here. __GROUP_ERROR__ is a relay answer, accepted unsigned on the relay ingest path (the bridges inject it unattributed), so its text is chosen by whoever put the frame on that socket — arbitrary content, arbitrary length, and not something this SDK can vouch for. reason is a fixed code classified locally instead; the relay’s exact text is logged on-device and reaches apps, when they want it, as the raw GroupError frame the bridges dual-emit on the server-message channel.

Fields

reason: String

Why the operation failed, from a fixed set: not_found (the relay has no such group — invite links and relay fan-out for it are dead, not merely refused), sync_denied (the relay refused to register or sync the group for this caller), or error (any other refusal).

group_id: Option<String>

Group the error concerns, when the relay scoped it. Absent for unscoped errors.

This is the group-scoping the free-text reason used to smuggle past the telemetry scrubber — as a real field it is hashed like every other group_id instead.

GroupRelaySyncChanged

The relay-side registration state of a group changed.

synced: true fires only on the relay’s positive registration acknowledgment (a GroupCreated answering a registration this device actually sent, over the Internet transport) — including the idempotent re-sync ack after a membership change. It is the signal that relay-dependent server commands for the group (invite links, server-side fan-out) can be issued. synced: false fires when that trust is revoked; reason says why. Not emitted for groups the relay was never asked about.

Fields

group_id: String

MLS group identifier.

synced: bool

Whether the relay currently holds a positively acknowledged registration for this group.

reason: String

Why the state changed: registered (relay ack), error (group-scoped relay error), removed (we were removed from the group), left (local leave), internet_dropped (Internet transport lost; re-registration re-arms on reconnect), or ack_timeout (relay never answered the registration — likely a relay without group support).

UsernameResolved

A username resolution finished, carrying every claim found.

The set is the whole point, and there is deliberately no “best” claim

Anyone may publish any username claim, so a name resolves to a set of assertions, never to an answer. Even a single-device user is a set of one. This event is emitted exactly once per resolution and carries the complete set precisely so an app cannot accidentally treat the first arrival as the winner: there is no per-claim event to race, and no ordering field to mistake for a ranking.

An app MUST let the user choose. Silently picking one claim converts a non-authoritative directory into an authoritative-looking one, which is worse than not shipping the feature: the user believes they are talking to the name, and the protocol only ever promised them a key. Present the claims, let a human confirm out of band (a QR code, a shared secret, a voice), and remember the address rather than the name.

An empty claims list is an ordinary outcome: the name may be unclaimed, the claimant offline-published to relays we do not use, or every claim we saw failed verification.

Fields

username: String

The normalized username that was resolved.

claims: Vec<UsernameClaim>

Every claim that verified, in no meaningful order.

rejected: u32

How many records were seen but rejected.

Non-zero is normal, not an error: the tag is public, anyone may publish to it, and junk arrives. Surfaced because a resolution that returns nothing while rejecting many records means something different from one that returns nothing having seen nothing, and an app showing “not found” may want to distinguish them.

truncated: u32

How many verified claims were dropped at the accumulator’s ceiling.

Separate from rejected because it is the opposite statement: these records were good and are missing anyway. Without it a crowded name renders exactly like an uncrowded one, a clean set with nothing refused, which hides the single signal that a name is being squatted at volume. Non-zero means claims is a sample and no absence in it can be trusted.

GroupMessageSent

A group message was sent to all members via mesh (MLS-encrypted fan-out).

Fields

group_id: String

MLS group identifier.

message_ids: Vec<String>

Per-member message IDs from fan-out.

member_count: u32

Number of members the message was sent to.

GroupMessagePartialFailure

A group message was only partially delivered (some members failed).

Fields

group_id: String

MLS group identifier.

failed_members: Vec<String>

Members for whom send failed.

succeeded_members: Vec<String>

Members for whom send succeeded.

GroupMessageDeliveryReport

The relay’s settled per-recipient delivery report for a group message sent via relay broadcast, after the SDK acted on it.

Fires once per broadcast whose report arrived, seconds after group_message_sent (the relay reports only when its whole fan-out has settled — correlate by message_id, never by order). Members in delivered took the message over a live relay socket; members in pushed took a device push carrying the ciphertext. Every other MLS roster member — the ones the relay reported missed and the ones it did not know about at all — has already been re-sent a per-member copy through the ordinary outbox/ACK/park delivery ladder (missed_reissued), so no app action is required; the event is delivery observability, not a failure signal. Not emitted when the report itself is lost — the SDK then re-broadcasts (bounded) and finally downgrades the whole message to per-member fan-out, which reports per-member like any mesh send.

Fields

group_id: String

MLS group identifier.

message_id: String

The logical group message id, as returned by the send and echoed by the relay.

delivered: Vec<String>

Members whose relay socket write was confirmed (a relay-side write-ack, not an end-to-end delivery ACK).

pushed: Vec<String>

Members offline at the relay who took a device push.

missed_reissued: Vec<String>

Members re-sent a per-member copy because the relay reached them neither way (or never knew them).

GroupRichExtrasDropped

Rich media metadata was dropped from an outbound group message because the group is not fully rich-capable (not every member advertised sealed rich payload support, or the local kill switch disabled it). The text was still sent; members receive it without the media attachment. Apps can use this to warn the sender that an attachment did not go through.

Fields

group_id: String

MLS group identifier.

unknown_members: Vec<String>

Members not known to parse the sealed rich payload — the ones holding the seal gate closed. Absence of knowledge and known non-support are indistinguishable here. Empty when the drop was caused by the local rich_payload_enabled kill switch instead. The SDK probes these members for their capability automatically; apps can retry the send once a later attempt stops dropping.

GroupUnauthorizedMembershipChange

An MLS membership change was applied that its committer was not authorized to make.

The change has been applied — MLS authenticated the committer as a group member and accepted the commit, and the local epoch advanced with it. The SDK’s admin model is an application-layer overlay on top of MLS (RFC 9420 leaves membership access control to the application), enforced on the sending side; refusing the change on receipt would mean refusing the merge, which permanently forks this member away from every peer that accepted it. So the change stands and is reported here instead.

This signal can false-positive. “Unauthorized” is judged against this member’s local replica of role state, which replicates best-effort (a joiner receives a point-in-time snapshot, role changes ride unreconciled mesh notifications) and can lag — so a legitimate change, e.g. a voluntary leave committed by a member whose admin role this device has not yet learned, may be reported here, and different members can disagree about the same commit.

Apps should treat this as a moderation signal for a human admin: an admin can undo the change with remove_from_group / invite_to_group. Never reverse a change automatically off a single member’s event — corroborate first. A member added this way can read all subsequent group traffic until removed.

Reports are rate-limited per (group, committer): a repeat within a short window is not re-emitted (divergent role metadata would otherwise re-fire it on every commit), but every affected Event::GroupMemberAdded / Event::GroupMemberRemoved still carries authorized: Some(false).

Known limitation: the member removed by an unauthorized Remove does not receive this event — it can no longer decrypt the commit that removed it, and it refuses to trust a non-admin’s unencrypted claim that it was removed. Only the remaining members report the removal.

Fields

group_id: String

MLS group identifier.

committer: String

The MLS-authenticated committer that made the change.

added: Vec<String>

Members the commit added, sorted. Empty for a pure removal.

removed: Vec<String>

Members the commit removed, sorted. Empty for a pure addition.

reason: String

Why the change was judged unauthorized. Currently "sender_not_admin" (the committer is not a known admin) or "affected_member_mismatch" (an admin committed, but the commit’s unencrypted framing named a different member than the MLS delta actually changed). Treat as an opaque string — values may be added.

enforced: bool

Whether the commit was refused rather than applied.

false (the default configuration) means the membership change happened and is being reported after the fact — added/removed describe real roster changes an admin can undo. true means GroupConfig::enforce_admin_commits was on and the commit was rejected before merging: no roster event accompanies this one, no membership changed locally, and added/removed describe what the commit would have done.

A true here also means this device declined an epoch every accepting member advanced to, so it can no longer decrypt that group’s traffic and needs re-inviting — treat it as a partition alarm, not just a moderation signal. Note the re-invite arrives as a Welcome, which is not policy-gated, so it readmits us to the group including whatever the refused commit did; the change itself still has to be resolved separately.

GroupEpochForkDetected

An epoch fork was detected in a group — concurrent commits caused members to diverge onto different MLS branches. The deterministic leader will attempt automatic resolution via a key-update commit.

Fields

group_id: String

MLS group identifier.

local_epoch: Option<u64>

Our local epoch when the fork was detected, or None if MLS state was unavailable at detection time.

GroupEpochForkResolved

An epoch fork was successfully resolved by the leader issuing a resync commit that re-established a canonical epoch.

Members in failed_members could not be reached with the resolution commit and may still be on a forked branch — the application layer should consider re-inviting them.

Fields

group_id: String

MLS group identifier.

resolved_epoch: u64

The new canonical epoch after resolution.

failed_members: Vec<String>

Members to whom the resolution commit could not be sent. These members may still be on a forked epoch branch and may need a re-invite to rejoin the canonical group state.

GroupRoleChanged

A member’s role was changed in a group.

Fields

group_id: String

Group identifier.

user_id: String

User ID of the member whose role changed.

new_role: String

New role (e.g. “admin”, “member”).

changed_by: String

User ID of who changed the role.

GroupRenamed

A group was renamed.

Fields

group_id: String

Group identifier.

new_name: String

New group name.

old_name: Option<String>

Previous group name (if known).

renamed_by: String

User ID of who renamed the group.

ServiceDiscovered

A service was discovered on the mesh in response to a discovery query.

Fields

query_id: String

Query ID that triggered this discovery.

service_id: String

Service identifier.

version: String

Service version.

provider_peer_id: String

Peer user ID of the provider.

capabilities: HashMap<String, String>

Service capabilities.

hop_count: u8

Number of hops from the provider.

ServiceRequestReceived

A service request was received from another peer.

Fields

request_id: String

Unique request identifier.

service_id: String

Service identifier being invoked.

method: String

Method name or action.

body: String

Request body (JSON or arbitrary string).

sender: String

Peer user ID of the requester.

encrypted: bool

Whether the request arrived sealed inside the 1:1 MLS session with sender, so no device that carried it could read the body and the session authenticated sender. false means it arrived as signed plaintext, readable by every hop (threat model R9).

ServiceResponseReceived

A response to a service request was received.

Fields

request_id: String

Request identifier this response corresponds to.

service_id: String

Service identifier.

status: String

Status: “ok”, “not_found”, or “error”.

body: String

Response body.

provider_peer_id: String

Peer user ID of the provider.

encrypted: bool

Whether the response arrived sealed inside the 1:1 MLS session with the provider. false means it arrived as signed plaintext, readable by every hop (threat model R9).

PresenceUpdated

A peer’s presence status was updated.

Fields

peer_id: String

Peer whose presence changed.

status: PresenceStatus

Presence status.

timestamp: i64

Timestamp of the update (Unix ms).

last_seen_ms: Option<i64>

When the peer was last seen (Unix ms), if the source knows it — e.g. the internet relay’s PresenceStatusWithLastSeen. Absent for peer-sent __PRESENCE__ updates.

source: PresenceSource

Which channel produced this update: the internet relay’s authoritative answer, or a peer-sent self-report. Always serialized; defaults to peer when deserializing legacy events.

TypingIndicatorReceived

A typing indicator was received from a peer.

Fields

sender: String

User who is typing (or stopped typing).

conversation_id: String

Conversation identifier, echoed back verbatim from the sender.

Opaque to the SDK — never parsed or routed on. Whatever key the sender chose (conventionally a peer address for a DM, the group id for a group) arrives here unchanged.

is_typing: bool

Whether the user is currently typing.

timestamp: i64

Timestamp of the indicator (Unix ms).

ReadReceiptReceived

A read receipt was received from a peer.

Fields

sender: String

User who read the messages.

message_ids: Vec<String>

IDs of the messages that were read.

timestamp: i64

Timestamp when the messages were read (Unix ms).

DorsScoreUpdated

DORS scored all available transports for this decision cycle.

Fields

scores: Vec<(String, f32)>

Transport type and score pairs (descending by score).

DorsTransportSelected

DORS selected a transport for the current message.

Fields

from: Option<String>

Previous transport (if any); provides decision boundary context.

transport: String

Selected transport.

reason_code: DorsReasonCode

Typed reason for selection (initial vs primary selected).

score: f32

Score of the selected transport (supplemental).

DorsTransportSwitched

DORS switched from one transport to another. Emitted only when active transport actually changes after a successful send.

Fields

from: Option<String>

Previous transport (if any).

to: String

New transport (now active).

reason_code: DorsReasonCode

Stable enum-backed reason for the transition.

reason_detail: Option<String>

Optional human-readable context (e.g. “primary failed, fallback succeeded”).

DorsEscalationTriggered

DORS escalation from BLE to Wi‑Fi. Use phase to distinguish recommendation vs applied.

Fields

phase: DorsEscalationPhase

TRIGGERED = DORS decided to escalate (reason = trigger); APPLIED = fallback succeeded.

from: String

Transport we escalated from (e.g. “ble”).

to: String

Transport we escalated to (e.g. “wifiDirect”).

reason_code: DorsEscalationReasonCode

Stable enum-backed reason code.

reason_detail: Option<String>

Optional human-readable context.

SecurityWarning

A security-relevant anomaly was detected (e.g. sender spoofing, a signing key that does not derive to its claimed address, an unsigned control message).

Fields

peer_id: String

Peer ID involved in the warning.

reason_code: SecurityWarningCode

Stable machine-readable classification of the warning. Branch on this rather than parsing reason.

reason: String

Human-readable description of the security issue.

MessageRelayed

A message was relayed (forwarded for a third party).

Fields

message_id: String

ID of the relayed message.

sender: String

Original sender.

recipient: String

Intended recipient.

hop_count: u8

Current hop count after increment.

remaining_ttl: u8

Remaining TTL after decrement.

UserBlocked

A user was blocked. Emitted for local UI notification only.

Fields

user_id: String

User ID that was blocked.

UserUnblocked

A user was unblocked. Emitted for local UI notification only.

Fields

user_id: String

User ID that was unblocked.

DataChanged

A replicated document changed and the change reached storage.

Emitted after the delta is durable, never before: an application that re-renders on this event is then rendering state that survives a crash.

Fields

space_id: String

The space the document belongs to.

doc_id: String

The document that changed.

delta_bytes: u64

Size of the change that was persisted.

DataDocRemoved

A replicated document was removed from every replica of its space.

Distinct from a document merely disappearing locally: this one is a decision that travels. It fires when this device removes a document and when it learns of a removal from a peer, so an application holding the document open can close it either way.

A removal loses to a concurrent edit, so a document may come back after this fires. That arrives as an ordinary DataChanged on a document the application thought was gone, which is the honest report: the edit won, and its contents are the contents.

Fields

space_id: String

The space the document belonged to.

doc_id: String

The document that was removed.

by: DocRemovedBy

Who removed it: local for this device, peer for a removal learned from the space.

DataDocSizeWarning

A replicated document is approaching the per-document size cap.

Fires while there is still room to act. Without it the cap would be a cliff an application meets for the first time as a failed write.

Fields

space_id: String

The space the document belongs to.

doc_id: String

The document approaching the cap.

compacted_bytes: u64

Its current compacted size.

cap_bytes: u64

The cap it is measured against.

DataAttachmentRequested

A peer asked for the bytes behind an attachment reference.

The SDK does not hold blob bytes, so it cannot answer this on its own: the application either supplies them with data_provide_attachment or says it cannot with data_decline_attachment. An application that handles neither leaves the asking peer with a reference it can see and never open, which is why declining is a first-class answer rather than silence.

Fields

space_id: String

The space the request arrived in.

peer_id: String

The peer that asked.

hash: String

Lowercase hex SHA-256 of the blob they want.

DataAttachmentReceived

Attachment bytes arrived and matched the hash that asked for them.

The bytes are handed over rather than stored: blobs never enter protocol state, so where this file lives is the application’s decision and its storage.

Fields

space_id: String

The space the attachment arrived in.

peer_id: String

The peer that supplied it.

hash: String

Lowercase hex SHA-256 of the blob, verified against these bytes.

data: String

The blob, base64.

DataAttachmentUnavailable

A fetch ended without bytes.

Either the peer answered that it no longer holds the blob, or the transfer carrying it failed. Both are ordinary: an attachment reference outlives the bytes it names, because the reference replicates and the bytes do not.

Fields

space_id: String

The space the fetch was made in.

peer_id: String

The peer that was asked.

hash: String

Lowercase hex SHA-256 that was asked for.

reason: String

Why it ended: declined (the peer answered that it no longer holds the blob), timeout, evicted (displaced by newer fetches), hash_mismatch, peer_gone (the peer was blocked, forgotten, or came back without the replication capability), or a transfer failure reason. A fixed token this crate chooses, never a peer’s words.

DataDocUnsyncable

A document cannot be replicated, in any form this protocol has.

The honest report of a real dead end rather than a warning in a log nobody reads. It fires when a document is too large for a sync frame and the peer cannot carry it over the media path either, which leaves two replicas that will not converge and no further rung to try.

Fields

space_id: String

The space the document belongs to.

doc_id: String

The document that cannot be sent.

bytes: u64

Size of the encoding that had nowhere to go.

reason: String

Why it could not be sent.

Implementations

impl Event

pub fn message_sent(message: &Message) -> Self

Creates a MessageSent event.

pub fn message_delivered( message_id: MessageId, latency_ms: u64, hop_count: u8, transport: TransportType, ) -> Self

Creates a MessageDelivered event.

pub fn message_failed( message_id: MessageId, reason: &'static str, retry_count: u32, ) -> Self

Creates a MessageFailed event.

reason is &'static str for the same load-bearing reason Event::message_deferred is, and protocol::types::classify_transport_send_error returns one: the telemetry pipe forwards this field to the ingest verbatim, without the scrubber, because the classification taxonomy is the ingest’s. A String parameter makes format!("{err}") at a call site representable, and the transport layer renders the counterparty into its own error text, so that one interpolation would ship a peer address beside identifiers the same record hashes. A static string cannot carry runtime data, which makes the mistake unrepresentable rather than merely discouraged. Callers with a classified failure pass the token; callers with a fixed condition pass its literal.

pub fn message_decryption_failed( message_id: MessageId, sender: String, code: DecryptionFailureCode, reason: String, ) -> Self

Creates a MessageDecryptionFailed event.

pub fn message_decryption_failed_for_frame( message_id: MessageId, sender: String, code: DecryptionFailureCode, reason: String, sealed_at_ms: u64, session_established_at_ms: Option<u64>, ) -> Self

Creates a MessageDecryptionFailed event for a failed 1:1 decrypt, carrying the frame’s seal time and the current session’s establishment time (see the variant’s fields).

pub fn transport_switched( from: Option<TransportType>, to: TransportType, reason: String, ) -> Self

Creates a TransportSwitched event.

pub fn relay_promoted( connection_count: usize, battery_level: Option<u8>, ) -> Self

Creates a RelayPromoted event.

pub fn relay_demoted(reason: &'static str) -> Self

Creates a RelayDemoted event.

&'static str for the reason given on Event::message_failed: the telemetry pipe forwards this field raw.

pub fn neighbor_discovered( peer_id: String, transport: TransportType, rssi: Option<i16>, ) -> Self

Creates a NeighborDiscovered event.

pub fn neighbor_lost(peer_id: String) -> Self

Creates a NeighborLost event.

pub fn identity_ready(address: impl Into<String>) -> Self

Creates an IdentityReady event.

pub fn network_metrics( neighbor_count: usize, relay_count: usize, delivery_ratio: f32, avg_latency_ms: u64, ) -> Self

Creates a NetworkMetrics event.

pub fn file_progress( file_id: String, chunks_sent: u32, total_chunks: u32, ) -> Self

Creates a FileProgress event.

pub fn file_received( file_id: String, file_name: String, file_size: u64, sender: String, content_type: ContentType, media_metadata: Option<MediaMetadata>, file_data: Vec<u8>, timestamp: Option<i64>, caption: Option<String>, reply_to_msg: Option<String>, reply_context: Option<&ReplyContext>, forward_info: Option<&ForwardInfo>, app_id: Option<String>, ) -> Self

Creates a FileReceived event.

pub fn file_receive_failed( file_id: String, file_name: String, sender: String, reason: String, ) -> Self

Creates a FileReceiveFailed event.

pub fn media_sent( file_id: String, content_type: ContentType, recipient: String, ) -> Self

Creates a MediaSent event.

pub fn media_send_failed( file_id: String, recipient: String, reason: String, ) -> Self

Creates a MediaSendFailed event.

pub fn message_deferred( message_id: MessageId, recipient: String, reason: &'static str, retry_count: u32, next_retry_at: Option<i64>, ) -> Self

Creates a MessageDeferred event.

pub fn message_retrying( message_id: MessageId, recipient: String, retry_count: u32, next_retry_at: i64, ) -> Self

Creates a MessageRetrying event.

pub fn message_undeliverable( message_id: MessageId, recipient: String, reason: &'static str, file_id: Option<String>, ) -> Self

Creates a MessageUndeliverable event.

pub fn media_resend_required( file_id: String, recipient: String, file_name: String, file_size: u64, app_id: Option<String>, ) -> Self

Creates a MediaResendRequired event.

pub fn ack_evicted( message_id: MessageId, priority: &str, reason: String, ) -> Self

Creates an AckEvicted event.

pub fn fragment_assembly_evicted( message_id: String, completion_percent: u8, reason: String, ) -> Self

Creates a FragmentAssemblyEvicted event.

pub fn relay_demoted_battery(battery_level: u8, min_required: u8) -> Self

Creates a RelayDemotedBattery event.

pub fn secure_session_established( peer_id: String, group_id: String, is_session: bool, initiated_by_local: bool, ) -> Self

Creates a SecureSessionEstablished event.

pub fn secure_session_failed(peer_id: String, reason: String) -> Self

Creates a SecureSessionFailed event.

pub fn convergence_diag(stage: String, peer_id: String, detail: String) -> Self

Creates a ConvergenceDiag event (1:1 MLS convergence instrumentation).

pub fn welcome_send_attempted( peer_id: String, message_id: String, group_id: String, attempt: u32, ) -> Self

Creates a WelcomeSendAttempted event.

pub fn welcome_send_succeeded( peer_id: String, message_id: String, group_id: String, attempt: u32, ) -> Self

Creates a WelcomeSendSucceeded event.

pub fn welcome_send_failed( peer_id: String, message_id: String, group_id: String, attempt: u32, reason_code: WelcomeReasonCode, transport_error: Option<&'static str>, retryable: bool, next_retry_at: Option<i64>, ) -> Self

Creates a WelcomeSendFailed event.

pub fn welcome_send_expired( peer_id: String, message_id: String, attempt: u32, reason_code: WelcomeReasonCode, ) -> Self

Creates a WelcomeSendExpired event.

pub fn connection_request_received( sender: String, sender_name: String, timestamp: i64, key_package: Option<Vec<u8>>, initial_message: Option<String>, ) -> Self

Creates a ConnectionRequestReceived event.

pub fn connection_request_undeliverable( recipient: String, message_id: String, reason: &'static str, ) -> Self

Creates a ConnectionRequestUndeliverable event.

pub fn connection_accepted( accepted_by: String, accepted_by_name: String, timestamp: i64, key_package: Option<Vec<u8>>, ) -> Self

Creates a ConnectionAccepted event.

pub fn connection_rejected(rejected_by: String) -> Self

Creates a ConnectionRejected event.

pub fn connection_request_cancelled(cancelled_by: String) -> Self

Creates a ConnectionRequestCancelled event.

pub fn presence_updated( peer_id: String, status: PresenceStatus, timestamp: i64, ) -> Self

Creates a PresenceUpdated event for a peer-sent __PRESENCE__ self-report (source: peer).

pub fn presence_updated_with_last_seen( peer_id: String, status: PresenceStatus, timestamp: i64, last_seen_ms: Option<i64>, ) -> Self

Creates a PresenceUpdated event carrying a last-seen timestamp (relay-sourced presence, source: internet).

pub fn presence_updated_from( peer_id: String, status: PresenceStatus, timestamp: i64, last_seen_ms: Option<i64>, source: PresenceSource, ) -> Self

Creates a PresenceUpdated event for a gateway answer, naming which carrier answered.

The relay is one gateway among others now, so the source is a parameter rather than a constant. It is still not free-form: a peer-sent self-report goes through Self::presence_updated, which is the only way to produce PresenceSource::Peer, so a carrier answer can never be mislabelled as one.

pub fn typing_indicator_received( sender: String, conversation_id: String, is_typing: bool, timestamp: i64, ) -> Self

Creates a TypingIndicatorReceived event.

pub fn read_receipt_received( sender: String, message_ids: Vec<String>, timestamp: i64, ) -> Self

Creates a ReadReceiptReceived event.

pub fn group_created(group_id: String, name: String) -> Self

Creates a GroupCreated event.

pub fn group_message_received( group_id: String, sender: String, content: String, timestamp: String, message_id: String, reply_to_msg: Option<String>, forward_info: Option<ForwardInfoEvent>, media_metadata: Option<MediaMetadata>, content_type: Option<String>, ) -> Self

Creates a GroupMessageReceived event.

pub fn group_member_added( group_id: String, user_id: String, added_by: String, group_name: Option<String>, authorized: Option<bool>, ) -> Self

Creates a GroupMemberAdded event.

pub fn group_member_removed( group_id: String, user_id: String, removed_by: String, authorized: Option<bool>, ) -> Self

Creates a GroupMemberRemoved event.

pub fn group_role_changed( group_id: String, user_id: String, new_role: String, changed_by: String, ) -> Self

Creates a GroupRoleChanged event.

pub fn group_renamed( group_id: String, new_name: String, old_name: Option<String>, renamed_by: String, ) -> Self

Creates a GroupRenamed event.

pub fn group_info( group_id: String, name: String, created_by: String, created_at: String, members: Vec<GroupInfoMember>, ) -> Self

Creates a GroupInfo event.

pub fn user_groups(groups: Vec<UserGroupSummary>) -> Self

Creates a UserGroups event.

pub fn group_error(reason: String, group_id: Option<String>) -> Self

Creates a GroupError event.

reason must be a locally-minted code, never relay text — callers on the wire path get theirs from GroupErrorPayload::classify_reason.

pub fn group_relay_sync_changed( group_id: String, synced: bool, reason: &str, ) -> Self

Creates a GroupRelaySyncChanged event.

pub fn group_message_sent( group_id: String, message_ids: Vec<String>, member_count: u32, ) -> Self

Creates a GroupMessageSent event.

pub fn group_message_partial_failure( group_id: String, failed_members: Vec<String>, succeeded_members: Vec<String>, ) -> Self

Creates a GroupMessagePartialFailure event.

pub fn group_message_delivery_report( group_id: String, message_id: String, delivered: Vec<String>, pushed: Vec<String>, missed_reissued: Vec<String>, ) -> Self

Creates a GroupMessageDeliveryReport event.

pub fn group_rich_extras_dropped( group_id: String, unknown_members: Vec<String>, ) -> Self

Creates a GroupRichExtrasDropped event.

pub fn group_unauthorized_membership_change( group_id: String, committer: String, added: Vec<String>, removed: Vec<String>, reason: String, enforced: bool, ) -> Self

Creates a GroupUnauthorizedMembershipChange event.

pub fn group_epoch_fork_detected( group_id: String, local_epoch: Option<u64>, ) -> Self

Creates a GroupEpochForkDetected event.

pub fn group_epoch_fork_resolved( group_id: String, resolved_epoch: u64, failed_members: Vec<String>, ) -> Self

Creates a GroupEpochForkResolved event.

pub fn service_discovered( query_id: String, service_id: String, version: String, provider_peer_id: String, capabilities: HashMap<String, String>, hop_count: u8, ) -> Self

Creates a ServiceDiscovered event.

pub fn service_request_received( request_id: String, service_id: String, method: String, body: String, sender: String, ) -> Self

Creates a ServiceRequestReceived event for a request that arrived as signed plaintext (encrypted: false).

pub fn service_response_received( request_id: String, service_id: String, status: String, body: String, provider_peer_id: String, ) -> Self

Creates a ServiceResponseReceived event for a response that arrived as signed plaintext (encrypted: false).

pub fn dors_score_updated(scores: Vec<(String, f32)>) -> Self

Creates a DorsScoreUpdated event (DORS observability).

pub fn dors_transport_selected( from: Option<String>, transport: String, reason_code: DorsReasonCode, score: f32, ) -> Self

Creates a DorsTransportSelected event (DORS observability).

pub fn dors_transport_switched( from: Option<String>, to: String, reason_code: DorsReasonCode, reason_detail: Option<String>, ) -> Self

Creates a DorsTransportSwitched event (DORS observability). Emitted only when active transport actually changes after a successful send.

pub fn dors_escalation_triggered( phase: DorsEscalationPhase, from: String, to: String, reason_code: DorsEscalationReasonCode, reason_detail: Option<String>, ) -> Self

Creates a DorsEscalationTriggered event (DORS observability). Use phase Triggered at the DORS trigger boundary, Applied when fallback succeeds.

pub fn security_warning( peer_id: String, reason_code: SecurityWarningCode, reason: String, ) -> Self

Creates a SecurityWarning event.

pub fn message_relayed( message_id: String, sender: String, recipient: String, hop_count: u8, remaining_ttl: u8, ) -> Self

Creates a MessageRelayed event.

pub fn user_blocked(user_id: String) -> Self

Creates a UserBlocked event.

pub fn user_unblocked(user_id: String) -> Self

Creates a UserUnblocked event.

pub fn to_json(&self) -> Result<String, Error>

Converts the event to JSON.

pub fn from_json(json: &str) -> Result<Self, Error>

Parses an event from JSON.

pub fn telemetry_name(&self) -> &'static str

Returns the stable snake.dot.case telemetry name for this event.

Names are compatible with OpenTelemetry naming conventions and are considered stable across minor versions of the SDK.

Trait Implementations

impl Clone for Event

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 Event

Custom Debug implementation that redacts sensitive fields to prevent accidental logging of message content and other potentially sensitive data.

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Event

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<ServiceEvent> for Event

fn from(event: ServiceEvent) -> Self

Converts to this type from the input type.

impl Serialize for Event

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.