jmap_scene_server/backend.rs
1//! SceneBackend trait and supporting types for the JMAP Scene method
2//! handlers.
3//!
4//! Read-side operations (`get_objects`, `get_state`, `get_changes`,
5//! `query_objects`, `query_changes`) are defined on the
6//! [`jmap_server::JmapBackend`] supertrait. This module adds the write
7//! operations and the deployment facts the handlers consult.
8//!
9//! The crate root re-exports this module's public items and the
10//! [`jmap_server`] backend types a downstream impl needs.
11
12use jmap_server::{BackendSetError, JmapBackend, JmapObject, SetObject};
13
14use jmap_scene_types::{
15 SceneAsset, SceneAvatar, SceneCapability, SceneInteractionEvent, SceneObject, SceneRegion,
16};
17
18/// A SceneRegion binding property, the reference
19/// [`SceneBackend::region_binding`] is asked about
20/// (draft-atwood-jmap-scene-00 §Creating a Region, §Updating a Region).
21#[non_exhaustive]
22#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
23pub enum BindingProperty {
24 /// `chatId`, a Chat (`urn:ietf:params:jmap:chat`).
25 ChatId,
26 /// `spaceId`, a Space (`urn:ietf:params:jmap:chat`).
27 SpaceId,
28 /// `channelId`, a channel of a Space (`urn:ietf:params:jmap:chat`).
29 ChannelId,
30 /// `activeCallId`, a VTCCall (`urn:ietf:params:jmap:vtc`).
31 ActiveCallId,
32}
33
34impl BindingProperty {
35 /// The SceneRegion property name, e.g. `"activeCallId"`.
36 pub fn as_str(self) -> &'static str {
37 match self {
38 Self::ChatId => "chatId",
39 Self::SpaceId => "spaceId",
40 Self::ChannelId => "channelId",
41 Self::ActiveCallId => "activeCallId",
42 }
43 }
44}
45
46/// What [`SceneBackend::region_binding`] knows about the object a
47/// SceneRegion binding property references.
48///
49/// `SceneRegion/set` maps it to the SetError the draft requires
50/// (draft-atwood-jmap-scene-00 §Creating a Region, §Updating a Region).
51#[non_exhaustive]
52#[derive(Debug, Clone, Copy, PartialEq, Eq)]
53pub enum BindingTarget {
54 /// The object exists and the caller may bind it: for `activeCallId`,
55 /// the VTCCall is not `"ended"` and the caller is a participant in or
56 /// moderator of it, or an administrator.
57 Usable,
58 /// The object does not exist; for `activeCallId`, also a VTCCall in
59 /// state `"ended"`. `SceneRegion/set` returns `invalidProperties`
60 /// naming the property.
61 Missing,
62 /// The object exists but the caller cannot access it. For `chatId`,
63 /// `spaceId` and `channelId` this is `invalidProperties` naming the
64 /// property ("if the referenced object does not exist or the caller
65 /// cannot access it"); for `activeCallId` it is `forbidden` ("and
66 /// `forbidden` if the caller lacks access").
67 Inaccessible,
68}
69
70/// Storage backend for the JMAP Scene method handlers
71/// (draft-atwood-jmap-scene-00).
72///
73/// # Permission enforcement (backend canonical)
74///
75/// Per the workspace AGENTS.md "Caller identity (foundation seam)" rule the
76/// backend re-verifies every permission atomically with the mutation. The
77/// handlers apply the draft's checks (media type, blob, size quota, the
78/// owner-or-admin rule via [`Self::may_modify_asset`]) as defense in depth.
79///
80/// # Changes
81///
82/// Unlike `/get` and `/query`, [`JmapBackend::get_changes`] is not scoped to
83/// the caller. Visibility filtering "does not change the JMAP state model:
84/// each data type has one state string per account", and `/changes` reports
85/// the account's changes (draft-atwood-jmap-scene-00 §Visibility Contract).
86/// A `/changes` result may therefore name an id that `/get` then hides: "A
87/// server MAY report an object hidden from the caller in `notFound` from
88/// `/get`". Unlike draft-atwood-jmap-graph-00, Scene does not ask `/changes`
89/// to omit what the caller may not read.
90///
91/// This trait is not object-safe by design (generic methods). Use
92/// `Arc<impl SceneBackend>` when sharing across tasks.
93pub trait SceneBackend: JmapBackend {
94 /// The account-level `urn:ietf:params:jmap:scene` capability object
95 /// (draft-atwood-jmap-scene-00 §Account-Level Capability Object) the
96 /// consumer advertises for `account_id` to this caller.
97 ///
98 /// Every `SceneAsset/*` handler reads `supportsSceneAsset` from it and
99 /// returns `unknownMethod` when it is `false`; `SceneAsset/set` also
100 /// reads `supportedVisualTypes` and `maxAssetSizeBytes`. Return the value the Session object
101 /// carries; a different value makes the handler contradict the
102 /// advertised capability. `supportedVisualTypes` "MUST include at least
103 /// `\"model/gltf-binary\"`"; the handler accepts that type whether or
104 /// not it is listed.
105 fn scene_capability(
106 &self,
107 caller: &Self::CallerCtx,
108 account_id: &jmap_types::Id,
109 ) -> impl std::future::Future<Output = Result<SceneCapability, Self::Error>> + Send;
110
111 /// The size in bytes of blob `blob_id`, or `None` if no such blob was
112 /// uploaded to `account_id` (RFC 8620 §6.1).
113 ///
114 /// `SceneAsset/set` create stores the size as the asset's `size` and
115 /// refuses a missing blob with `invalidProperties` naming `blobId`
116 /// ("`blobId` does not reference a valid blob"). There is no default: a default would invent sizes or
117 /// refuse every create. Return `Err` for a transient storage failure,
118 /// never `Ok(None)`: the handler maps `Err` to `serverFail` so the
119 /// client retries.
120 fn blob_size(
121 &self,
122 caller: &Self::CallerCtx,
123 account_id: &jmap_types::Id,
124 blob_id: &jmap_types::Id,
125 ) -> impl std::future::Future<Output = Result<Option<u64>, Self::Error>> + Send;
126
127 /// Create an object.
128 ///
129 /// The handler has validated the create against
130 /// draft-atwood-jmap-scene-00 §SceneAsset/set and filled the server-set
131 /// properties other than `id`. The backend MUST, in one atomic step,
132 /// mint a ULID `id` ("A ULID assigned at creation"), call `build(&id)`
133 /// once for the object carrying it, and store that object.
134 ///
135 /// For a `SceneAsset` the backend also enforces the deployment-defined
136 /// rules of §SetError Conditions atomically with the insert: refuse
137 /// with `overQuota` for "Account asset storage quota
138 /// exceeded", and with `forbidden` when the "Deployment restricts
139 /// shared-asset creation to administrators" and the caller is not one.
140 ///
141 /// For a `SceneRegion` the backend refuses with `overQuota` when the
142 /// account already holds `maxRegionsPerAccount` regions ("The server
143 /// MUST return `overQuota` when `maxRegionsPerAccount` would be
144 /// exceeded"), counted atomically with the insert.
145 ///
146 /// For a `SceneObject` the backend sets `ownerId` to the caller's
147 /// userId ("The userId of the user who created this object"; the
148 /// handler sends `null`) and refuses with `overQuota` when the object's
149 /// region already holds `maxObjectsPerRegion` objects ("The server MUST
150 /// return `overQuota` when `maxObjectsPerRegion` would be exceeded"),
151 /// counted atomically with the insert.
152 ///
153 /// For a `SceneAvatar` (§Entering a Region) the handler has filled
154 /// `userId` from [`Self::caller_user_id`], `position`, `orientation`,
155 /// `joinedAt` (now) and `leftAt` (`null`). In one atomic step the
156 /// backend:
157 ///
158 /// 1. refuses with `alreadyExists` and `existingId` naming the record
159 /// when the user already has an avatar in the region, present or
160 /// departed ("the server MUST NOT create a second record and MUST
161 /// return an `alreadyExists` SetError ... with `existingId` set to
162 /// the id of that record");
163 /// 2. refuses with `overQuota` when the region already holds
164 /// `maxAvatarsPerRegion` avatars with `leftAt` `null`;
165 /// 3. sets `leftAt` to the new `joinedAt` on the user's active avatar
166 /// in any other region ("the server SHOULD set `leftAt` on the
167 /// previous avatar before creating the new one");
168 /// 4. keeps each affected region's `activeAvatarCount` ("Number of
169 /// avatars currently present in the region") equal to its avatars
170 /// with `leftAt` `null`, advancing the SceneRegion state.
171 ///
172 /// Returns the assigned id and the stored object. `create_id` is the
173 /// client's creation id. Error mapping, state-counter and change-log
174 /// rules are those of the canonical `jmap-mail-server` `create_object`:
175 /// the state advances only when the create commits.
176 fn create_object<O, F>(
177 &self,
178 caller: &Self::CallerCtx,
179 account_id: &jmap_types::Id,
180 create_id: &str,
181 build: F,
182 ) -> impl std::future::Future<Output = Result<(jmap_types::Id, O), BackendSetError<Self::Error>>>
183 + Send
184 where
185 O: SetObject + Send + Sync,
186 F: FnOnce(&jmap_types::Id) -> O + Send;
187
188 /// Apply an RFC 8620 §5.3 PatchObject to an existing object.
189 ///
190 /// `Ok(Some(o))` echoes server-changed properties; `Ok(None)` means the
191 /// patch applied verbatim. Both MUST advance the state and record an
192 /// `updated` change. Unknown `id` is `notFound`; a malformed patch is
193 /// `invalidPatch`; a result that no longer decodes is
194 /// `invalidProperties`. Apply the whole patch or none of it.
195 ///
196 /// For a `SceneAvatar` whose patch sets `leftAt` to a UTCDate, the
197 /// backend refuses with `invalidProperties` naming `leftAt` when the
198 /// stored `leftAt` is already non-null ("double-leave is invalid"), and
199 /// otherwise decrements the region's `activeAvatarCount` in the same
200 /// atomic step ("The server decrements the region's
201 /// `activeAvatarCount`"), advancing the SceneRegion state.
202 ///
203 /// A patch that sets `leftAt` to `null` re-enters the region
204 /// (§Re-entering a Region); the handler has added `joinedAt` (now),
205 /// `position` and `orientation` (the region's spawn point). In the
206 /// same atomic step the backend refuses with `invalidProperties`
207 /// naming `leftAt` when the stored `leftAt` is `null`, then applies
208 /// steps 2 to 4 of [`Self::create_object`] for a `SceneAvatar`: the
209 /// `maxAvatarsPerRegion` `overQuota`, setting `leftAt` on the user's
210 /// active avatar in any other region, and the `activeAvatarCount`
211 /// update.
212 fn update_object<O: SetObject + Send + Sync>(
213 &self,
214 caller: &Self::CallerCtx,
215 account_id: &jmap_types::Id,
216 id: &jmap_types::Id,
217 patch: O::Patch,
218 ) -> impl std::future::Future<Output = Result<Option<O>, BackendSetError<Self::Error>>> + Send;
219
220 /// Destroy an object by id. Unknown `id` is `notFound`; the state
221 /// advances only when the destroy commits. The handler has already
222 /// applied the permission check.
223 ///
224 /// Destroying a `SceneRegion` "removes the SceneRegion and all
225 /// SceneObject and SceneAvatar records in it; `SceneObject/changes` and
226 /// `SceneAvatar/changes` report those records as destroyed"
227 /// (draft-atwood-jmap-scene-00 §Destroying a Region): in the same atomic
228 /// step the backend destroys every SceneObject and SceneAvatar whose
229 /// `regionId` is `id` and records each as a destroyed change of its
230 /// type. It does not end a VTCCall the
231 /// region's `activeCallId` references ("the server MUST NOT
232 /// automatically end the referenced VTCCall").
233 ///
234 /// Destroying a `SceneObject` "removes the SceneObject and all its
235 /// children (objects whose `parentId` references this object,
236 /// recursively)": in the same atomic step the backend destroys every
237 /// descendant and records each as a destroyed SceneObject change.
238 fn destroy_object<O: SetObject + Send + Sync>(
239 &self,
240 caller: &Self::CallerCtx,
241 account_id: &jmap_types::Id,
242 id: &jmap_types::Id,
243 ) -> impl std::future::Future<Output = Result<(), BackendSetError<Self::Error>>> + Send;
244
245 /// `true` if the caller may update or destroy `asset`: "Only the asset
246 /// owner or an admin may modify asset metadata"
247 /// (draft-atwood-jmap-scene-00 §SceneAsset/set Update Errors; Destroy
248 /// Errors use the "Same permission model as update").
249 ///
250 /// `SceneAsset/set` returns `forbidden` for an update or destroy when
251 /// this is `false`.
252 ///
253 /// # Default implementation
254 ///
255 /// Returns `Ok(true)`: every caller may modify every asset. This is the
256 /// workspace's fail-open posture for permission hooks (bd:JMAP-bghk);
257 /// production backends override it.
258 fn may_modify_asset(
259 &self,
260 caller: &Self::CallerCtx,
261 account_id: &jmap_types::Id,
262 asset: &SceneAsset,
263 ) -> impl std::future::Future<Output = Result<bool, Self::Error>> + Send {
264 let _ = (caller, account_id, asset);
265 async { Ok(true) }
266 }
267
268 /// `true` if the consumer advertises the capability `uri` for
269 /// `account_id`.
270 ///
271 /// The SceneRegion binding properties "are present only when the
272 /// corresponding companion capability is advertised on the same
273 /// account": `chatId`, `spaceId` and `channelId` need
274 /// `urn:ietf:params:jmap:chat`, `activeCallId` needs
275 /// `urn:ietf:params:jmap:vtc`. `SceneRegion/set` refuses a non-null
276 /// binding without its capability, and `accessPolicy` `"space"`
277 /// without `urn:ietf:params:jmap:chat`, with `invalidProperties`; a
278 /// create stores `null` for the bindings whose capability is
279 /// advertised.
280 fn has_capability(
281 &self,
282 caller: &Self::CallerCtx,
283 account_id: &jmap_types::Id,
284 uri: &str,
285 ) -> bool;
286
287 /// What the binding `property` set to `id` references, for the checks of
288 /// draft-atwood-jmap-scene-00 §Creating a Region ("the server MUST
289 /// verify that the referenced object exists and the caller has access
290 /// to it") and §Updating a Region (for `activeCallId`: "(a) the
291 /// referenced VTCCall exists, (b) its state is not `\"ended\"`, and (c)
292 /// the caller is a participant in or moderator of the referenced call,
293 /// or has deployment-defined administrative privileges").
294 ///
295 /// `SceneRegion/set` calls this for each non-null binding a create
296 /// sets or an update patches, after the capability check. The Chat and
297 /// VTC lookups live in the binding crates; this crate depends on
298 /// RFC 8620 only.
299 ///
300 /// # Default implementation
301 ///
302 /// Returns `Ok(BindingTarget::Usable)`: every reference is accepted.
303 /// This is the workspace's fail-open posture for permission hooks
304 /// (bd:JMAP-bghk); a backend that advertises Chat or VTC overrides it.
305 fn region_binding(
306 &self,
307 caller: &Self::CallerCtx,
308 account_id: &jmap_types::Id,
309 property: BindingProperty,
310 id: &jmap_types::Id,
311 ) -> impl std::future::Future<Output = Result<BindingTarget, Self::Error>> + Send {
312 let _ = (caller, account_id, property, id);
313 async { Ok(BindingTarget::Usable) }
314 }
315
316 /// `true` if `channel_id` "is a channel of the Space named by
317 /// `spaceId`" (draft-atwood-jmap-scene-00 §Updating a Region, the
318 /// binding checks).
319 ///
320 /// `SceneRegion/set` calls this when a create or an update sets
321 /// `channelId` or `spaceId` and the region as it would be after the
322 /// write has both non-null, after [`Self::region_binding`] accepted
323 /// each. `false` fails the write with `invalidProperties` naming
324 /// `channelId`.
325 ///
326 /// # Default implementation
327 ///
328 /// Returns `Ok(true)` (fail-open, bd:JMAP-bghk); a backend that
329 /// advertises Chat overrides it.
330 fn channel_in_space(
331 &self,
332 caller: &Self::CallerCtx,
333 account_id: &jmap_types::Id,
334 channel_id: &jmap_types::Id,
335 space_id: &jmap_types::Id,
336 ) -> impl std::future::Future<Output = Result<bool, Self::Error>> + Send {
337 let _ = (caller, account_id, channel_id, space_id);
338 async { Ok(true) }
339 }
340
341 /// `true` if the caller may update `region`: "Only the owner or an
342 /// admin may modify region properties" (draft-atwood-jmap-scene-00
343 /// §SceneRegion/set Update Errors).
344 ///
345 /// # Default implementation
346 ///
347 /// Returns `Ok(true)` (fail-open, bd:JMAP-bghk); production backends
348 /// override it.
349 fn may_update_region(
350 &self,
351 caller: &Self::CallerCtx,
352 account_id: &jmap_types::Id,
353 region: &SceneRegion,
354 ) -> impl std::future::Future<Output = Result<bool, Self::Error>> + Send {
355 let _ = (caller, account_id, region);
356 async { Ok(true) }
357 }
358
359 /// `true` if the caller may destroy `region`: "Only the region owner
360 /// or an admin may destroy a region" (draft-atwood-jmap-scene-00
361 /// §SceneRegion/set Destroy Errors).
362 ///
363 /// # Default implementation
364 ///
365 /// Returns `Ok(true)` (fail-open, bd:JMAP-bghk); production backends
366 /// override it.
367 fn may_destroy_region(
368 &self,
369 caller: &Self::CallerCtx,
370 account_id: &jmap_types::Id,
371 region: &SceneRegion,
372 ) -> impl std::future::Future<Output = Result<bool, Self::Error>> + Send {
373 let _ = (caller, account_id, region);
374 async { Ok(true) }
375 }
376
377 /// `true` if the caller may update or destroy `object`: "Only the
378 /// object's `ownerId`, the region owner, or a deployment-admin may
379 /// modify another user's object" (draft-atwood-jmap-scene-00
380 /// §SceneObject/set Update Errors; Destroy Errors use the "Same
381 /// permission model as update").
382 ///
383 /// `SceneObject/set` returns `forbidden` for an update or destroy when
384 /// this is `false`.
385 ///
386 /// # Default implementation
387 ///
388 /// Returns `Ok(true)` (fail-open, bd:JMAP-bghk); production backends
389 /// override it.
390 fn may_modify_object(
391 &self,
392 caller: &Self::CallerCtx,
393 account_id: &jmap_types::Id,
394 object: &SceneObject,
395 ) -> impl std::future::Future<Output = Result<bool, Self::Error>> + Send {
396 let _ = (caller, account_id, object);
397 async { Ok(true) }
398 }
399
400 /// The caller's userId: "The authenticated user identity string"
401 /// (draft-atwood-jmap-scene-00 §SceneAvatar `userId`).
402 ///
403 /// `SceneAvatar/set` stores it as a created avatar's `userId` ("The
404 /// server sets `userId` from the authenticated identity") and compares
405 /// it with an updated avatar's `userId` ("Users MUST NOT update other
406 /// users' avatars"). There is no default: the handlers cannot know the
407 /// identity.
408 fn caller_user_id(
409 &self,
410 caller: &Self::CallerCtx,
411 account_id: &jmap_types::Id,
412 ) -> impl std::future::Future<Output = Result<String, Self::Error>> + Send;
413
414 /// The `displayName` of a new avatar for `user_id` when the create
415 /// supplies none: "the server sets it from the user profile or
416 /// ChatContact when {{JMAP-CHAT}} is present".
417 ///
418 /// # Default implementation
419 ///
420 /// Returns `user_id`. A Chat binding crate or a backend with user
421 /// profiles overrides it.
422 fn avatar_display_name(
423 &self,
424 caller: &Self::CallerCtx,
425 account_id: &jmap_types::Id,
426 user_id: &str,
427 ) -> impl std::future::Future<Output = Result<String, Self::Error>> + Send {
428 let _ = (caller, account_id);
429 let name = user_id.to_owned();
430 async { Ok(name) }
431 }
432
433 /// The reserved display names (draft-atwood-jmap-scene-00 §Avatar
434 /// Identity and Impersonation, jmap-chat-spec 77c3474 L2776): "The
435 /// server MAY maintain a list of reserved display names that correspond
436 /// to system roles or administrative functions and MAY reject
437 /// `SceneAvatar/set` operations that attempt to use a reserved name with
438 /// a `SetError` of type `forbidden`." This crate rejects them by choice.
439 ///
440 /// `SceneAvatar/set` refuses a create or update whose client-supplied
441 /// `displayName` equals one of these names exactly with `forbidden`.
442 /// The comparison is case-sensitive, so list each spelling to reserve.
443 /// A name set by [`Self::avatar_display_name`] is not checked.
444 ///
445 /// # Default implementation
446 ///
447 /// Returns no names (fail-open, bd:JMAP-bghk); deployments supply
448 /// their list.
449 fn reserved_display_names(
450 &self,
451 caller: &Self::CallerCtx,
452 account_id: &jmap_types::Id,
453 ) -> impl std::future::Future<Output = Result<Vec<String>, Self::Error>> + Send {
454 let _ = (caller, account_id);
455 async { Ok(Vec::new()) }
456 }
457
458 /// `true` unless the caller is barred from entering `region`, which
459 /// it already has access to: "User is banned or ejected with a
460 /// cooldown period still active" (draft-atwood-jmap-scene-00
461 /// §Create Errors). `SceneAvatar/set` create and an update that
462 /// re-enters a region return `forbidden` when this is `false`, since
463 /// "The user already knows the region exists". Access under the
464 /// region's `accessPolicy` is [`Self::may_access_region`], not this
465 /// hook: a create without it is `invalidProperties` naming
466 /// `regionId`, a re-entry `notFound`.
467 ///
468 /// # Default implementation
469 ///
470 /// Returns `Ok(true)` (fail-open, bd:JMAP-bghk); production backends
471 /// override it.
472 fn may_enter_region(
473 &self,
474 caller: &Self::CallerCtx,
475 account_id: &jmap_types::Id,
476 region: &SceneRegion,
477 ) -> impl std::future::Future<Output = Result<bool, Self::Error>> + Send {
478 let _ = (caller, account_id, region);
479 async { Ok(true) }
480 }
481
482 /// `true` if the caller may eject `avatar`, another user's avatar:
483 /// "region owners and administrators may set `leftAt` on another
484 /// user's avatar to eject them" (draft-atwood-jmap-scene-00 §Update
485 /// Errors).
486 ///
487 /// `SceneAvatar/set` calls this only for a patch of another user's
488 /// avatar that sets `leftAt` and touches nothing else ("An eject
489 /// update patches only `leftAt`", §Avatar Permissions); `false` is
490 /// `forbidden`.
491 ///
492 /// # Default implementation
493 ///
494 /// Returns `Ok(true)` (fail-open, bd:JMAP-bghk); production backends
495 /// override it.
496 fn may_eject_avatar(
497 &self,
498 caller: &Self::CallerCtx,
499 account_id: &jmap_types::Id,
500 avatar: &SceneAvatar,
501 ) -> impl std::future::Future<Output = Result<bool, Self::Error>> + Send {
502 let _ = (caller, account_id, avatar);
503 async { Ok(true) }
504 }
505
506 /// `true` if the caller has access to region `region_id`
507 /// (draft-atwood-jmap-scene-00 §Region Access): "A user has access to a
508 /// region when its `accessPolicy` admits the user, when the user is the
509 /// region owner, when the user has deployment-defined administrative
510 /// privileges, or when the user has an active SceneAvatar in it."
511 /// `"invite"` admits "The users whose userIds are listed in
512 /// `invitedUserIds`", and "Servers MAY admit users to an `\"invite\"`
513 /// region by other mechanisms as well".
514 ///
515 /// `SceneRegion/get`, `SceneObject/get` and `SceneAvatar/get` report a
516 /// region, object or avatar in a region without access as `notFound`:
517 /// "The server SHOULD treat a request from a user without access to a
518 /// region as if the region did not exist: `notFound` for
519 /// `SceneRegion/get`, `SceneObject/get`, and `SceneAvatar/get` ... and
520 /// no results from the region in `/query`" (draft-atwood-jmap-scene-00
521 /// at 29e9a41, L2606).
522 /// `SceneRegion/set`, `SceneObject/set` and `SceneAvatar/set` report an
523 /// update or destroy of such a record as `notFound` too, never
524 /// `forbidden`. A region that no longer exists
525 /// may be treated either way.
526 ///
527 /// The handlers cannot filter a `/query` page they did not cut, so
528 /// `query_objects` should omit what `/get` would hide: "The server
529 /// SHOULD NOT include a SceneObject in a `SceneObject/get` response or
530 /// `SceneObject/query` result if the authenticated user does not have
531 /// access to the object's containing SceneRegion" (§Visibility
532 /// Contract, L2577). The same applies to SceneRegion and SceneAvatar
533 /// results (L2606).
534 ///
535 /// `query_changes` is not filtered per caller: visibility filtering
536 /// "does not change the JMAP state model: each data type has one state
537 /// string per account ... and `/changes` and `/queryChanges` report
538 /// changes for the account" (L2587). An id it reports that the caller
539 /// may not see, `/get` reports in `notFound`.
540 ///
541 /// # Default implementation
542 ///
543 /// Returns `Ok(true)` (fail-open, bd:JMAP-bghk); production backends
544 /// override it.
545 fn may_access_region(
546 &self,
547 caller: &Self::CallerCtx,
548 account_id: &jmap_types::Id,
549 region_id: &jmap_types::Id,
550 ) -> impl std::future::Future<Output = Result<bool, Self::Error>> + Send {
551 let _ = (caller, account_id, region_id);
552 async { Ok(true) }
553 }
554
555 /// `true` if `object` is in the caller's visibility set: "The server
556 /// SHOULD apply visibility filtering to limit the objects returned
557 /// based on the authenticated user's avatar position within the
558 /// region. The specific visibility algorithm is deployment-defined"
559 /// (draft-atwood-jmap-scene-00 §Visibility Contract).
560 ///
561 /// Consulted only for objects in a region the caller may access
562 /// ([`Self::may_access_region`]). `SceneObject/get` reports an object
563 /// outside the set as `notFound`, and `SceneObject/set` refuses an
564 /// update or destroy of it with `notFound`: "The server SHOULD NOT
565 /// return `forbidden`, as that would confirm the object still exists"
566 /// (L2589). `query_objects` should omit such objects as well;
567 /// `query_changes` reports changes for the account (L2587).
568 ///
569 /// # Default implementation
570 ///
571 /// Returns `Ok(true)`: "A simple deployment MAY return all objects in
572 /// the region."
573 fn is_object_visible(
574 &self,
575 caller: &Self::CallerCtx,
576 account_id: &jmap_types::Id,
577 object: &SceneObject,
578 ) -> impl std::future::Future<Output = Result<bool, Self::Error>> + Send {
579 let _ = (caller, account_id, object);
580 async { Ok(true) }
581 }
582
583 /// `true` if `user_id` is blocked on the caller's own contact list
584 /// (draft-atwood-jmap-scene-00 at 33702a5 §Blocked-Contact Spatial
585 /// Presence, L2672): "SceneAvatar records belonging to a blocked
586 /// ChatContact SHOULD be excluded from `SceneAvatar/get` responses and
587 /// `SceneAvatar/query` results delivered to the blocking user".
588 ///
589 /// The list is the caller's, whatever account the request names: the
590 /// server "removes any SceneAvatar records whose `userId` corresponds
591 /// to a ChatContact with `blocked: true` on the requesting user's
592 /// contact list" (L2676). A request on a shared region names the
593 /// region's hosting account, which holds the host's contacts, not the
594 /// requester's, so the hook takes no account id; an implementation
595 /// resolves the caller's own account from `caller`.
596 ///
597 /// Consulted only for avatars in a region the caller may access:
598 /// "Blocked-contact filtering is applied AFTER the visibility
599 /// filtering". `SceneAvatar/get` reports such an avatar exactly as a
600 /// missing one, in `notFound` ("The server SHOULD NOT return an error,
601 /// a filtered-result indicator, or any other signal", L2674);
602 /// `query_objects` should omit it as well, while `query_changes`
603 /// reports changes for the account (§Visibility Contract). The
604 /// handlers leave `activeAvatarCount` the true count, which deployments
605 /// "SHOULD prefer" (L2678).
606 ///
607 /// [`crate::should_deliver`] asks this at delivery time with the
608 /// recipient as the caller, since suppression consults "the
609 /// recipient's ChatContact records" (draft-atwood-jmap-scene-wss-00 at
610 /// 33702a5, L793-795).
611 ///
612 /// The Chat lookup (`ChatContact.blocked`) lives in the binding crate:
613 /// "Without `urn:ietf:params:jmap:chat`, there is no blocked-contact
614 /// list and this filtering does not apply."
615 ///
616 /// # Default implementation
617 ///
618 /// Returns `Ok(false)`: no one is blocked. This is the workspace's
619 /// fail-open posture for policy hooks (bd:JMAP-bghk).
620 fn is_user_blocked(
621 &self,
622 caller: &Self::CallerCtx,
623 user_id: &str,
624 ) -> impl std::future::Future<Output = Result<bool, Self::Error>> + Send {
625 let _ = (caller, user_id);
626 async { Ok(false) }
627 }
628
629 /// `true` if the caller may see the SceneAvatar records of region
630 /// `region_id` (draft-atwood-jmap-scene-00 at 6bcd9d8, L2654): "When a
631 /// SceneRegion's `activeCallId` references a VTCCall with
632 /// `e2eeEnabled` set to `true`, the server SHOULD NOT expose the
633 /// region's SceneAvatar records to users who are not participants in
634 /// the bound VTCCall: for such users it SHOULD return `notFound` for
635 /// `SceneAvatar/get`, exclude the records from `SceneAvatar/query`, and
636 /// suppress `SceneAvatarEvent` ... delivery (`entered`, `left`, and
637 /// `ejected`)."
638 ///
639 /// Consulted only for avatars in a region the caller may access
640 /// ([`Self::may_access_region`]). `SceneAvatar/get` reports the avatars
641 /// of a region answering `false` in `notFound`, and
642 /// [`crate::should_deliver`] drops their `SceneAvatarEvent`s;
643 /// `query_objects` should omit them as well, while `query_changes`
644 /// reports changes for the account (§Visibility Contract).
645 ///
646 /// The VTC lookup (`VTCCall.e2eeEnabled` and the call's participants)
647 /// lives in the binding crate, `jmap-scene-vtc-server`.
648 ///
649 /// # Default implementation
650 ///
651 /// Returns `Ok(true)`: no region hides its avatars. This is the
652 /// workspace's fail-open posture for policy hooks (bd:JMAP-bghk); a
653 /// deployment without it exposes the call's participant presence, the
654 /// limitation the draft's SHOULD leaves to it.
655 fn may_see_region_avatars(
656 &self,
657 caller: &Self::CallerCtx,
658 account_id: &jmap_types::Id,
659 region_id: &jmap_types::Id,
660 ) -> impl std::future::Future<Output = Result<bool, Self::Error>> + Send {
661 let _ = (caller, account_id, region_id);
662 async { Ok(true) }
663 }
664
665 /// Accept an interaction that passed the `SceneObject/interact`
666 /// checks, or refuse it for its rate (draft-atwood-jmap-scene-00
667 /// §SceneObject/interact).
668 ///
669 /// `event` carries the interaction and the caller's userId from
670 /// [`Self::caller_user_id`]. `Ok(false)` means "The caller has exceeded
671 /// a deployment-defined interaction rate" and the handler reports
672 /// `rateLimit`; draft-atwood-jmap-scene-wss-00 §Rate Limiting suggests
673 /// "no more than five events per user per region per second".
674 /// `Ok(true)` accepts it: count it against the rate and, when the
675 /// WebSocket capability is supported, hand `event` to the transport,
676 /// which "delivers a `SceneInteractionEvent` carrying the interaction
677 /// and the caller's userId to the WebSocket subscribers of the region",
678 /// filtered per recipient by [`crate::should_deliver`]. Counting and
679 /// delivering in this one call keeps them atomic.
680 ///
681 /// # Default implementation
682 ///
683 /// Returns `Ok(true)` and delivers nothing: no rate limit (fail-open,
684 /// bd:JMAP-bghk) and no WebSocket transport.
685 fn accept_interaction(
686 &self,
687 caller: &Self::CallerCtx,
688 account_id: &jmap_types::Id,
689 event: &SceneInteractionEvent,
690 ) -> impl std::future::Future<Output = Result<bool, Self::Error>> + Send {
691 let _ = (caller, account_id, event);
692 async { Ok(true) }
693 }
694
695 /// Per-backend capability probe: `true` if this backend supports the
696 /// JMAP object type `O` for `account_id`. Not called by the handlers;
697 /// consumers use it when assembling their Session capabilities
698 /// ("Deployments ... MAY omit support for SceneAsset methods").
699 fn supports_type<O: JmapObject>(
700 &self,
701 caller: &Self::CallerCtx,
702 account_id: &jmap_types::Id,
703 ) -> bool;
704}