Skip to main content

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}