1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
//! Ephemeral-stream subscription state (draft-atwood-jmap-chat-wss-00
//! §ChatStreamEnable).
//!
//! A WebSocket transport keeps one [`EphemeralSubscription`] per
//! connection, starting from [`EphemeralSubscription::default`] (nothing
//! subscribed). Each `ChatStreamEnable` frame goes through
//! [`EphemeralSubscription::replace_with`], which validates the frame
//! against the server's [`CompanionStreams`], normalizes it, and replaces
//! the whole subscription. A `ChatStreamDisable` frame resets it to the
//! default.
//!
//! Before sending a `ChatTypingEvent` to an owner's connections, the
//! transport asks [`should_deliver_typing`] whether that owner may receive
//! it. Before sending a `ChatPresenceEvent`, it asks [`project_presence`]
//! for the frame that owner may see, if any.
//!
//! # Rate limits are the deployment's job
//!
//! This crate does not rate-limit ephemeral events, and neither predicate
//! counts or times anything. The draft gives the outbound limits as SHOULD
//! rules, and the transport or deployment applies them:
//!
//! - Typing: "no more than one `ChatTypingEvent` per sender per chat per 3
//! seconds SHOULD be delivered; events above this rate MAY be silently
//! dropped" (draft-atwood-jmap-chat-wss-00 §ChatTypingEvent, L251).
//! - Presence: "no more than one `ChatPresenceEvent` per contact per 30
//! seconds SHOULD be delivered; events above this rate MAY be silently
//! dropped, but the most recent presence state SHOULD be delivered when
//! the rate window reopens" (draft-atwood-jmap-chat-wss-00
//! §ChatPresenceEvent, L298). A presence limiter therefore keeps the
//! latest dropped event per contact and sends it, after passing it
//! through [`project_presence`] again, when that contact's 30-second
//! window reopens, so the recipient is not left with stale presence.
//!
//! # Credential expiry stops ephemeral delivery
//!
//! "A server that does not close the connection when credentials expire
//! SHOULD NOT deliver further ephemeral events on that connection"
//! (draft-atwood-jmap-chat-wss-00 §Authentication and Identity, L131).
//! Neither predicate knows about credentials, so the transport checks
//! expiry itself and sends no typing or presence frame on an expired
//! connection.
use ;
use ;
use crateChatBackend;
use crateowner_is_member;
/// Which ids a subscribed data type covers.
/// The companion WebSocket capabilities the server advertises, which
/// decide whether the companion `dataTypes` values `"vtc"` and `"scene"`
/// are recognized in a `ChatStreamEnable` frame.
///
/// The default advertises neither. Per draft-atwood-jmap-chat-wss-00
/// §Enabling Ephemeral Push (L175), `"vtc"` is "recognized only when the
/// server advertises `urn:ietf:params:jmap:vtc:websocket`", and `"scene"`
/// "only when the server advertises `urn:ietf:params:jmap:scene:websocket`".
/// The ephemeral subscription of one WebSocket connection, normalized
/// from a `ChatStreamEnable` frame.
///
/// The default value subscribes to nothing, which is the state before the
/// first `ChatStreamEnable` and after a `ChatStreamDisable`.
/// Whether `event` may be delivered to the owner of `account_id`.
///
/// `account_id` is the recipient. `event.chat_id` names the recipient's
/// Chat record, and `event.sender_id` is the typing user as the recipient
/// sees it: a ChatContact id on the recipient's contact list. The
/// transport calls this once per recipient, at delivery time, and sends
/// the event to none of the recipient's connections when it returns
/// `false`. The sender is never told. The connection's `chatIds` scope
/// ([`EphemeralSubscription::typing`]) is a separate filter, checked by
/// the transport on its own.
///
/// Delivery is allowed only when all of these hold:
///
/// - `event.account_id` is `account_id` (draft-atwood-jmap-chat-wss-00
/// §ChatTypingEvent: `accountId` is "The id of the account that
/// contains the Chat").
/// - The sender is not the recipient (draft-atwood-jmap-chat-00
/// §Chat/typing: delivery goes to "each local participant in the Chat
/// other than the requesting account").
/// - The Chat exists in the recipient's account and the recipient is
/// still a member of it (draft-atwood-jmap-chat-wss-00
/// §ChatTypingEvent, L255: "Servers SHOULD verify at delivery time that
/// the owner remains a current member of the identified Chat").
/// - For a direct or group Chat, its `receiveTypingIndicators` is `true`.
/// Other kinds ignore it.
/// - The sender's ChatContact is not blocked on the recipient's contact
/// list, per [`ChatBackend::is_contact_blocked`].
///
/// # Errors
///
/// Returns the backend's error if reading the Chat, its Space or the
/// sender's blocked status fails.
pub async
/// The `ChatPresenceEvent` the owner of `account_id` may receive for
/// `event`, or `None` if it must be dropped.
///
/// `account_id` is the recipient and `event.contact_id` is the contact
/// whose presence changed, as a ChatContact id on the recipient's contact
/// list. The transport calls this once per recipient, at delivery time,
/// and sends the returned frame, or nothing, to that owner's connections.
/// The contact is never told. The connection's `contactIds` scope
/// ([`EphemeralSubscription::presence`]) is a separate filter, checked by
/// the transport on its own.
///
/// - If `event.account_id` is not `account_id`, the result is `None`
/// (same section: `accountId` is "The id of the account that contains
/// the ChatContact").
/// - If the contact is blocked on the recipient's contact list, per
/// [`ChatBackend::is_contact_blocked`], the result is `None`
/// (draft-atwood-jmap-chat-wss-00 §ChatPresenceEvent, L300: "a
/// `ChatPresenceEvent` is not delivered for a contact whose `blocked`
/// field is `true` on the owner's ChatContact record for that contact").
/// - Otherwise the result is `event` with an `"invisible"` presence
/// replaced by `"offline"` (same section, L275: "`"invisible"` is not a
/// value of this field. The server reports a contact whose presence is
/// `"invisible"` ... as `"offline"`"). Every other field is unchanged.
///
/// # Errors
///
/// Returns the backend's error if reading the contact's blocked status
/// fails.
pub async