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