Skip to main content

jmap_chat_server/
outbound.rs

1//! Outbound federation events reported to
2//! [`ChatEvents::on_outbound_event`](crate::ChatEvents::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}