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}