Skip to main content

jmap_chat_server/
outbound.rs

1//! Outbound federation events reported to
2//! [`ChatBackend::on_outbound_event`](crate::ChatBackend::on_outbound_event).
3//!
4//! draft-atwood-jmap-chat-00 requires the server to notify other
5//! participants' servers when the owner sends a Message, retracts or edits
6//! one, adds or removes a reaction, reads a received Message, types, or
7//! changes a group Chat or their presence. The wire methods (`Peer/deliver`
8//! `message`, `edit` and `reactionUpdate`, `Peer/retract`,
9//! `Peer/groupUpdate`, `Peer/receipt`, `Peer/typing`, `Peer/presence`) are
10//! defined by
11//! draft-atwood-jmap-chat-federation-00 and implemented outside this
12//! crate. These events carry local ids (ChatContact ids, Message ids);
13//! the federation layer maps them to identity strings and sends them.
14//!
15//! An event carries only what the stored records cannot tell the backend
16//! afterwards: which members a change added, removed or re-roled, and who
17//! must be told. Everything else (`body`, `name`, the full member list)
18//! is read from the stored Message or Chat.
19
20use jmap_chat_types::{ChatMember, Reaction, ReadDisposition};
21use jmap_types::{Id, UTCDate};
22
23/// One outbound event the `Message/set`, `Chat/set`, `Chat/typing` or
24/// `PresenceStatus/set` handler reports.
25#[non_exhaustive]
26#[derive(Debug, Clone, PartialEq)]
27pub enum OutboundEvent {
28    /// The owner created a Message. draft-atwood-jmap-chat-00
29    /// §Message/set: the server sets the server-assigned fields "then
30    /// enqueues the message for outbound delivery" (`Peer/deliver`
31    /// `message`). Reported after the Message is written; the payload
32    /// fields are read from the stored Message.
33    NewMessage {
34        /// The Chat that holds the Message (`Peer/deliver` `chatId`).
35        chat_id: Id,
36        /// The Message's local id.
37        message_id: Id,
38        /// The Message's `senderMsgId` (`message.senderMsgId`).
39        sender_msg_id: Id,
40    },
41    /// The owner set `deletedForAll: true` on a Message they sent.
42    /// draft-atwood-jmap-chat-federation-00 §Peer/retract "Sender
43    /// Behavior": "the server MUST send `Peer/retract` to the server of
44    /// every other participant in the Chat." Reported after the update is
45    /// written; the payload fields are read from the stored Message
46    /// before the update.
47    Retract {
48        /// The Chat that holds the Message (`Peer/retract` `chatId`).
49        chat_id: Id,
50        /// The Message's local id.
51        message_id: Id,
52        /// The Message's `senderMsgId` (`Peer/retract` `senderMsgId`).
53        sender_msg_id: Id,
54    },
55    /// The owner edited a Message's `body`, `bodyType`, `mentions` or
56    /// `broadcastMentions`. draft-atwood-jmap-chat-00 §Editing a Message:
57    /// "Send `Peer/deliver` carrying an `edit` payload to all recipients".
58    /// Reported after the edit is written; the payload fields are read
59    /// from the stored Message.
60    Edit {
61        /// The Chat that holds the Message (`Peer/deliver` `chatId`).
62        chat_id: Id,
63        /// The Message's local id.
64        message_id: Id,
65        /// The Message's `senderMsgId` (`edit.senderMsgId`).
66        sender_msg_id: Id,
67    },
68    /// The owner added or removed one of their reactions on a Message.
69    /// draft-atwood-jmap-chat-00 §Adding and Removing Reactions: the
70    /// server "MUST propagate the reaction to all recipients via
71    /// `Peer/deliver` `reactionUpdate` payload, carrying the
72    /// `senderReactionId` as the map key", and a removal "using the same
73    /// `senderReactionId`". Reported after the update is written, one
74    /// event per `reactions/<senderReactionId>` patch key.
75    ReactionUpdate {
76        /// The Chat that holds the Message (`Peer/deliver` `chatId`).
77        chat_id: Id,
78        /// The Message's local id.
79        message_id: Id,
80        /// The Message's `senderMsgId` (`reactionUpdate.senderMsgId`).
81        sender_msg_id: Id,
82        /// The `reactions` map key (`reactionUpdate.senderReactionId`).
83        sender_reaction_id: String,
84        /// `reactionUpdate.action`.
85        action: ReactionAction,
86    },
87    /// A group Chat was created or changed (`Peer/groupUpdate`), reported
88    /// after the change is written.
89    GroupUpdate {
90        /// The group Chat (`Peer/groupUpdate` `chatId`).
91        chat_id: Id,
92        /// What changed (`Peer/groupUpdate` `action`).
93        action: GroupUpdateAction,
94        /// ChatContact ids of the members to notify, per
95        /// draft-atwood-jmap-chat-00 §Chat/set (see each
96        /// [`GroupUpdateAction`] variant). Never contains the accountId.
97        recipients: Vec<Id>,
98    },
99    /// The owner set a non-null `readAt` on a Message another participant
100    /// sent. draft-atwood-jmap-chat-federation-00 §Peer/receipt: `readAt`
101    /// "SHOULD be present when the recipient's owner has read the
102    /// message". Reported after the update is written, and only when the
103    /// owner's effective receipt-sharing preference is `true`: "If the
104    /// effective preference is `false`, the server MUST NOT invoke
105    /// `Peer/receipt`" (§Peer/receipt "Sender Behavior"). The read fields
106    /// are carried here because a `burnOnRead` Message is gone once read.
107    Receipt {
108        /// The Chat that holds the Message.
109        chat_id: Id,
110        /// The Message's local id. Under `burnOnRead` the Message has been
111        /// hard-deleted by the time the event is reported.
112        message_id: Id,
113        /// The Message's `senderMsgId` (`Peer/receipt` `senderMsgId`).
114        sender_msg_id: Id,
115        /// `Peer/receipt` `readAt`.
116        read_at: UTCDate,
117        /// `Peer/receipt` `readDisposition`, as stored: `"displayed"` when
118        /// the patch set `readAt` without it.
119        read_disposition: Option<ReadDisposition>,
120    },
121    /// The owner called `Chat/typing`. draft-atwood-jmap-chat-00
122    /// §Chat/typing: the server SHOULD deliver a `typing` push event to
123    /// each local participant other than the owner and, "For federated
124    /// Chats, the server SHOULD invoke `Peer/typing`" on each remote
125    /// participant's home server. Reported after the request is validated;
126    /// the event is never stored. The per-recipient checks belong to the
127    /// receiving side (see [`should_deliver_typing`](crate::should_deliver_typing)).
128    Typing {
129        /// The Chat (`Peer/typing` `chatId`).
130        chat_id: Id,
131        /// `Peer/typing` `typing`.
132        typing: bool,
133    },
134    /// The owner changed `presence`, `statusText` or `statusEmoji`.
135    /// draft-atwood-jmap-chat-federation-00 §Peer/subscribePresence: the
136    /// server "MAY push subsequent `Peer/presence` calls to the subscriber
137    /// whenever the owner's presence, `statusText`, or `statusEmoji`
138    /// changes". Reported after a `PresenceStatus/set` update that names
139    /// any of the three is written; the payload is read from the stored
140    /// PresenceStatus, and the subscribers are the backend's.
141    Presence,
142}
143
144/// The `action` of a [`OutboundEvent::ReactionUpdate`]
145/// (draft-atwood-jmap-chat-federation-00 §Peer/deliver `reactionUpdate`).
146#[non_exhaustive]
147#[derive(Debug, Clone, PartialEq)]
148pub enum ReactionAction {
149    /// `"add"`. The reaction (`emoji`, `customEmojiId`, `sentAt`) is read
150    /// from the stored Message's `reactions` map under the
151    /// `senderReactionId`. Also reported when the owner replaces one of
152    /// their reactions under the same key.
153    Add,
154    /// `"remove"`, with the reaction as it was stored before the removal,
155    /// since the stored Message no longer holds it. Reported only when the
156    /// key named a stored reaction.
157    Remove {
158        /// The removed reaction.
159        removed: Reaction,
160    },
161}
162
163/// The `action` of a [`OutboundEvent::GroupUpdate`]
164/// (draft-atwood-jmap-chat-federation-00 §Peer/groupUpdate).
165///
166/// One `Chat/set` update can report several actions. They come in this
167/// order: `UpdateMetadata`, `AddMembers`, `RemoveMembers`, `UpdateRoles`,
168/// then `Leave` or `Close`, so the owner's departure is last.
169#[non_exhaustive]
170#[derive(Debug, Clone, PartialEq)]
171pub enum GroupUpdateAction {
172    /// `"create"`. draft-atwood-jmap-chat-00 §Creating a Chat: the server
173    /// "MUST send `Peer/groupUpdate` to each initial member". Recipients:
174    /// the initial members.
175    Create,
176    /// `"addMembers"`, with the added members as stored. §Chat/set
177    /// `addMembers`: "the server MUST send `Peer/groupUpdate` to all
178    /// current members". Recipients: every member after the change.
179    AddMembers {
180        /// `addedMembers`.
181        added: Vec<ChatMember>,
182    },
183    /// `"removeMembers"`. §Chat/set `removeMembers`: "The server MUST
184    /// send `Peer/groupUpdate` to all remaining members and to the
185    /// removed members." Recipients: both.
186    RemoveMembers {
187        /// `removedMemberIds`.
188        removed_ids: Vec<Id>,
189    },
190    /// `"updateRoles"`, with the members whose role changed, as stored.
191    /// §Chat/set `updateMemberRoles`: "The server MUST send
192    /// `Peer/groupUpdate` to all members." Recipients: every member.
193    UpdateRoles {
194        /// `updatedRoles` (each member's `id` and new `role`).
195        updated: Vec<ChatMember>,
196    },
197    /// `"updateMetadata"`: `name`, `description` or `avatarBlobId`
198    /// changed. Recipients: every member.
199    UpdateMetadata,
200    /// `"leave"`: the owner left. §Chat/set `removeMembers`: the server
201    /// "MUST notify the other members with a `Peer/groupUpdate` of action
202    /// `"leave"`". Recipients: the remaining members.
203    Leave,
204    /// `"close"`: the owner, the last admin, left while members remain,
205    /// which closed the group. The server "MUST notify the other members
206    /// with a `Peer/groupUpdate` of action `"close"` in place of
207    /// `"leave"`". Recipients: the remaining members.
208    Close,
209}