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, 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}