jmap_scene_server/push.rs
1//! Push support for the Scene data types (draft-atwood-jmap-scene-00
2//! §Push Notifications).
3//!
4//! [`SCENE_DATA_TYPES`] names the four types that take part in the RFC
5//! 8620 §7.1 state-change mechanism. A consumer filters each `StateChange`
6//! for a subscription with [`jmap_server::state_change_for`], which applies
7//! the subscription's `types`, and picks the Web Push `Urgency` header
8//! (RFC 8030 §5.3) for it with [`push_urgency`].
9//!
10//! Coalescing rapid SceneAvatar and SceneObject mutations (§State-Change
11//! Frequency, jmap-chat-spec 77c3474 L2840-2842: the server "MAY coalesce",
12//! "for example, 1-5 seconds") needs a clock and a delivery queue, so it is
13//! the consumer's job.
14
15use jmap_scene_types::{SceneAsset, SceneAvatar, SceneObject, SceneRegion};
16
17use jmap_server::JmapObject;
18
19/// The Web Push `Urgency` header (RFC 8030 §5.3) that [`push_urgency`]
20/// picks; the same type `jmap-web-push` sends.
21pub use jmap_types::Urgency;
22
23/// The data types that participate in the state-change mechanism.
24///
25/// §State-Change Events: "All four Scene data types -- SceneRegion,
26/// SceneObject, SceneAvatar, and SceneAsset -- participate in the RFC 8620
27/// state-change mechanism".
28pub const SCENE_DATA_TYPES: &[&str] = &[
29 SceneRegion::TYPE_NAME,
30 SceneObject::TYPE_NAME,
31 SceneAvatar::TYPE_NAME,
32 SceneAsset::TYPE_NAME,
33];
34
35/// A change, as seen by the user who receives the push, for which
36/// §Push Urgency suggests an urgency (jmap-chat-spec 77c3474 L2854: the
37/// server "MAY set the `Urgency` header"; "The following urgency
38/// assignments are suggested").
39///
40/// The consumer classifies each change it is about to push; only it knows
41/// who receives the push and why the record changed.
42#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
43#[non_exhaustive]
44pub enum SceneEvent {
45 /// `SceneRegion/set destroy` of a region in which the receiving user
46 /// had SceneObject records: `high`.
47 RegionDestroyedWithOwnObjects,
48 /// A user entered or left a region the receiving user is present in:
49 /// `normal`, or `low` when `bound_chat_notified`.
50 AvatarEnterOrLeave {
51 /// A Chat push for the same join or leave in the region's bound
52 /// Chat has been or is being delivered (§Interaction with Chat
53 /// Push).
54 bound_chat_notified: bool,
55 },
56 /// Region creation or a configuration change of a region the receiving
57 /// user is an active participant in: `normal`.
58 RegionChangedForParticipant,
59 /// A region owner or deployment admin destroyed the receiving user's
60 /// SceneObject: `low`.
61 ObjectDestroyedByAdmin,
62 /// A SceneAsset change: `very-low`.
63 AssetChanged,
64 /// A SceneObject or SceneAvatar position or property update from
65 /// periodic simulation-layer reconciliation: `very-low`.
66 PositionReconciliation,
67}
68
69impl SceneEvent {
70 /// The §Push Urgency suggestion for this event.
71 ///
72 /// For an avatar enter or leave already announced by a Chat push,
73 /// §Avatar Enter and Chat Member Join says the server "SHOULD NOT set
74 /// `Urgency: normal` or higher on the SceneAvatar `StateChange`"; this
75 /// returns `low`, the highest urgency that rule leaves, so the state
76 /// change itself is not held back further.
77 pub const fn urgency(self) -> Urgency {
78 match self {
79 Self::RegionDestroyedWithOwnObjects => Urgency::High,
80 Self::AvatarEnterOrLeave {
81 bound_chat_notified: true,
82 } => Urgency::Low,
83 Self::AvatarEnterOrLeave {
84 bound_chat_notified: false,
85 }
86 | Self::RegionChangedForParticipant => Urgency::Normal,
87 Self::ObjectDestroyedByAdmin => Urgency::Low,
88 Self::AssetChanged | Self::PositionReconciliation => Urgency::VeryLow,
89 }
90 }
91}
92
93/// The urgency for one `StateChange` covering `events`: the highest of
94/// their urgencies, or `None` when `events` is empty.
95///
96/// §Push Urgency: "When a single `StateChange` event covers multiple data
97/// types with different recommended urgencies, the server SHOULD use the
98/// highest applicable urgency for the combined payload."
99///
100/// `None` means the draft recommends nothing for the payload. A consumer
101/// then omits the header, which RFC 8030 §5.3 treats as `normal`.
102pub fn push_urgency(events: impl IntoIterator<Item = SceneEvent>) -> Option<Urgency> {
103 events.into_iter().map(SceneEvent::urgency).max()
104}