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
304
305
306
307
308
309
310
311
//! JMAP Scene method handlers (draft-atwood-jmap-scene-00).
//!
//! # Usage
//!
//! Implement [`SceneBackend`] for your storage layer, then call
//! [`register_scene_handlers`] to wire the method names into a
//! [`jmap_server::Dispatcher`]:
//!
//! ```rust,no_run
//! # use std::sync::Arc;
//! # use jmap_scene_server::{SceneBackend, register_scene_handlers};
//! # use jmap_server::Dispatcher;
//! # fn example<B: SceneBackend<CallerCtx = ()> + 'static>(backend: B) {
//! let mut dispatcher: Dispatcher<()> = Dispatcher::new();
//! register_scene_handlers(&mut dispatcher, Arc::new(backend));
//! # }
//! ```
//!
//! # Scope
//!
//! The `SceneAsset/*` methods (draft §`SceneAsset` Methods): standard
//! `/get`, `/changes` and `/queryChanges`; `/set` with the create, update
//! and destroy `SetError` conditions, glTF (`model/gltf-binary`) as the
//! mandatory-to-implement format and the `maxAssetSizeBytes` quota; and
//! `/query` with the draft's default sort.
//!
//! The `SceneRegion/*` methods (draft §`SceneRegion` Methods): `/set` with
//! the create, update and destroy `SetError` conditions, `mayCreateRegion`,
//! `maxRegionsPerAccount`, the binding checks through
//! [`SceneBackend::region_binding`] and the destroy cascade; and `/query`
//! with the draft's default sort and `accessPolicy` filter check.
//!
//! The `SceneObject/*` methods (draft §`SceneObject` Methods): `/set` with
//! the create, update and destroy `SetError` conditions, `mayCreateObject`,
//! `maxObjectsPerRegion`, a region-scoped acyclic scene graph at most 16
//! levels deep, [`SceneBackend::may_modify_object`] and the recursive
//! destroy; and `/query` with the draft's default sort, the §Filter
//! Validation checks and the `withinRadius` and `withinBounds` spatial
//! filters over region-local positions.
//!
//! `SceneObject/interact` (draft §`SceneObject/interact`): each interaction
//! is checked for its properties (`invalidProperties`), region access,
//! existence and the visibility set (`notFound`), an active avatar and
//! `interactable` (`forbidden`), then passed to
//! [`SceneBackend::accept_interaction`], which may refuse it with
//! `rateLimit` and otherwise delivers the `SceneInteractionEvent`.
//!
//! `SceneRegion/broadcast` (draft §`SceneRegion/broadcast`, jmap-chat-spec
//! 93f2258), on accounts whose capability has `supportsRegionBroadcast`
//! (otherwise `unknownMethod`): each region event is checked for its
//! properties (`invalidProperties`), region access (`notFound`) and the
//! owner-or-admin rule ([`SceneBackend::may_update_region`], `forbidden`),
//! then passed to [`SceneBackend::accept_region_event`], which may refuse
//! it with `rateLimit` and otherwise delivers the `SceneRegionEvent`.
//!
//! The `SceneAvatar/*` methods (draft §`SceneAvatar` Methods): `/set` create
//! enters a region (one avatar record per user and region, `alreadyExists`
//! with `existingId` when the user has a present or departed record there,
//! auto-eject from another region, `maxAvatarsPerRegion` and
//! [`SceneBackend::may_enter_region`]), an update that sets `leftAt` leaves
//! it or, through [`SceneBackend::may_eject_avatar`], ejects another user,
//! an update that sets `leftAt` to `null` re-enters it at the spawn point,
//! destroy is `forbidden`, a `displayName` from
//! [`SceneBackend::reserved_display_names`] is `forbidden`, and the
//! backend keeps `activeAvatarCount`; and
//! `/query` with the draft's default sort and §Filter Validation.
//!
//! Visibility (draft §Visibility Contract, §Region Access, §Blocked-Contact
//! Spatial Presence): `/get` of `SceneRegion`, `SceneObject` and `SceneAvatar`
//! reports a record in a region the caller has no access to
//! ([`SceneBackend::may_access_region`]), an object outside the caller's
//! visibility set ([`SceneBackend::is_object_visible`]), an avatar of a
//! user the caller blocked ([`SceneBackend::is_user_blocked`]) and an
//! avatar in a region bound to an E2EE call the caller is not in
//! ([`SceneBackend::may_see_region_avatars`]) in `notFound`, like a
//! missing id; `SceneObject/set` refuses an update or
//! destroy of a hidden object with `notFound`. The backend omits the same
//! records from `/query` and `/queryChanges`. `activeAvatarCount` is the
//! true count, blocked users included, as the draft says deployments
//! "SHOULD prefer".
//!
//! Avatar Visibility (draft §Avatar Visibility, jmap-chat-spec 93f2258):
//! [`SceneBackend::avatar_view`] hides another user's avatar from the
//! caller ([`AvatarView::Hidden`]: `notFound` from `SceneAvatar/get` and
//! from a `SceneAvatar/set` update, no `SceneAvatarEvent`) or withholds
//! its `position`, `orientation` and `worldState` / `regionState` keys
//! ([`AvatarRedaction`]). The default shows everything. The backend applies
//! the same view in `/query` and, when it hides to protect information, in
//! `SceneAvatar/changes`.
//!
//! Push (draft §Push Notifications): [`SCENE_DATA_TYPES`], the four types
//! that participate in RFC 8620 state changes, and [`push_urgency`], the
//! §Push Urgency suggestion for a `StateChange`, including the
//! §Interaction with Chat Push rule that an avatar enter or leave already
//! announced by a bound Chat's push is not sent at `normal` or higher.
//!
//! Ephemeral subscriptions (draft-atwood-jmap-scene-wss-00
//! §`SceneStreamEnable`): [`SceneEphemeralSubscription`] holds the per-connection
//! subscription a `SceneStreamEnable` frame replaces in its entirety, with
//! a dynamic ([`RegionScope::All`]) or static ([`RegionScope::Only`])
//! region scope and the `invalidArguments` check on `eventTypes`;
//! [`should_deliver`], the per-event delivery check (active avatar,
//! visibility, E2EE-call avatar suppression, blocked-sender suppression);
//! and [`validate_interaction`],
//! the check on a client-sent `SceneInteractionEvent` before relay.
//!
//! The crate depends on RFC 8620 only; Chat and VTC bindings live in
//! separate binding crates, which implement
//! [`SceneBackend::has_capability`] and [`SceneBackend::region_binding`].
//!
//! # `websocket` feature (ephemeral events over RFC 8887)
//!
//! Enable `websocket` for the `websocket` module: the `jmap-websocket`
//! extension handler for `SceneStreamEnable` / `SceneStreamDisable` and
//! client-sent `SceneInteractionEvent` (draft-atwood-jmap-scene-wss-00) and
//! the server-wide hub the deployment publishes events to. Off by default, so
//! a deployment without the WebSocket transport does not pull in
//! `jmap-websocket`.
//!
//! # `memory` feature (reference implementation)
//!
//! Enable the `memory` feature to expose `memory::MemoryBackend`, the
//! in-memory reference implementation of [`SceneBackend`] used by this
//! crate's tests. **Not production.** Its API may break in any minor
//! release while the crate is pre-1.0.
use Arc;
use ;
/// In-memory reference implementation of [`SceneBackend`].
///
/// Gated behind `feature = "memory"`. Not production.
use scene_asset_set;
pub use ;
pub use ;
pub use ;
pub use handle_scene_region_broadcast;
pub use ;
pub use register_scene_handlers_with_history;
pub use handle_scene_object_interact;
pub use ;
pub use ;
pub use ;
/// Capability URI for `urn:ietf:params:jmap:scene`.
pub use JMAP_SCENE_URI;
/// Register the `SceneAsset/*`, `SceneRegion/*`, `SceneObject/*` and
/// `SceneAvatar/*` method handlers with `dispatcher`.
///
/// After this call the dispatcher handles `/get`, `/changes`, `/set`,
/// `/query` and `/queryChanges` of `SceneAsset`, `SceneRegion`,
/// `SceneObject` and `SceneAvatar`, `SceneObject/interact` and
/// `SceneRegion/broadcast` (which answers `unknownMethod` on an account
/// without `supportsRegionBroadcast`).
/// [`Dispatcher::register`] silently replaces an existing handler of the
/// same name, so register overrides afterwards.
///
/// This only wires dispatch. The consumer advertises [`JMAP_SCENE_URI`] in
/// its Session capabilities, with the same account-level object
/// [`SceneBackend::scene_capability`] returns.
/// Opt this crate's registered Foo/set methods in to
/// draft-ietf-jmap-conditional-02 (`ifUnchangedBy` and `atomic`;
/// docs/design/DECISIONS.md decisions 1 and 17).
///
/// Call after [`register_scene_handlers`]. Attaches [`SetSupport`] to each
/// of `SceneAsset/set`, `SceneRegion/set`, `SceneObject/set`, `SceneAvatar/set` that is registered, and skips the rest; no handler is
/// re-registered.
///
/// The dispatcher reads preconditions through each type's `/get` and runs
/// each call in the scope `backend` opens
/// ([`ConditionalBackend::begin_set`]).
/// Under `atomic` that scope must check `maxAvatarsPerRegion` on the final
/// state; the memory backend does.
/// Advertise `urn:ietf:params:jmap:conditional` only once
/// [`Dispatcher::conditional_ready`] is true for the whole dispatcher.