Skip to main content

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}