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