Skip to main content

SceneBackend

Trait SceneBackend 

Source
pub trait SceneBackend: JmapBackend {
Show 29 methods // Required methods fn scene_capability( &self, caller: &Self::CallerCtx, account_id: &Id, ) -> impl Future<Output = Result<SceneCapability, Self::Error>> + Send; fn blob_size( &self, caller: &Self::CallerCtx, account_id: &Id, blob_id: &Id, ) -> impl Future<Output = Result<Option<u64>, Self::Error>> + Send; fn create_object<O, F>( &self, caller: &Self::CallerCtx, account_id: &Id, create_id: &str, build: F, ) -> impl Future<Output = Result<(Id, O), BackendSetError<Self::Error>>> + Send where O: SetObject + Send + Sync, F: FnOnce(&Id) -> O + Send; fn update_object<O: SetObject + Send + Sync>( &self, caller: &Self::CallerCtx, account_id: &Id, id: &Id, patch: O::Patch, ) -> impl Future<Output = Result<Option<O>, BackendSetError<Self::Error>>> + Send; fn destroy_object<O: SetObject + Send + Sync>( &self, caller: &Self::CallerCtx, account_id: &Id, id: &Id, ) -> impl Future<Output = Result<(), BackendSetError<Self::Error>>> + Send; fn has_capability( &self, caller: &Self::CallerCtx, account_id: &Id, uri: &str, ) -> bool; fn caller_user_id( &self, caller: &Self::CallerCtx, account_id: &Id, ) -> impl Future<Output = Result<String, Self::Error>> + Send; fn supports_type<O: JmapObject>( &self, caller: &Self::CallerCtx, account_id: &Id, ) -> bool; // Provided methods fn may_modify_asset( &self, caller: &Self::CallerCtx, account_id: &Id, asset: &SceneAsset, ) -> impl Future<Output = Result<bool, Self::Error>> + Send { ... } fn region_binding( &self, caller: &Self::CallerCtx, account_id: &Id, property: BindingProperty, id: &Id, ) -> impl Future<Output = Result<BindingTarget, Self::Error>> + Send { ... } fn channel_in_space( &self, caller: &Self::CallerCtx, account_id: &Id, channel_id: &Id, space_id: &Id, ) -> impl Future<Output = Result<bool, Self::Error>> + Send { ... } fn may_update_region( &self, caller: &Self::CallerCtx, account_id: &Id, region: &SceneRegion, ) -> impl Future<Output = Result<bool, Self::Error>> + Send { ... } fn may_destroy_region( &self, caller: &Self::CallerCtx, account_id: &Id, region: &SceneRegion, ) -> impl Future<Output = Result<bool, Self::Error>> + Send { ... } fn may_modify_object( &self, caller: &Self::CallerCtx, account_id: &Id, object: &SceneObject, ) -> impl Future<Output = Result<bool, Self::Error>> + Send { ... } fn avatar_display_name( &self, caller: &Self::CallerCtx, account_id: &Id, user_id: &str, ) -> impl Future<Output = Result<String, Self::Error>> + Send { ... } fn reserved_display_names( &self, caller: &Self::CallerCtx, account_id: &Id, ) -> impl Future<Output = Result<Vec<String>, Self::Error>> + Send { ... } fn may_enter_region( &self, caller: &Self::CallerCtx, account_id: &Id, region: &SceneRegion, ) -> impl Future<Output = Result<bool, Self::Error>> + Send { ... } fn may_eject_avatar( &self, caller: &Self::CallerCtx, account_id: &Id, avatar: &SceneAvatar, ) -> impl Future<Output = Result<bool, Self::Error>> + Send { ... } fn may_access_region( &self, caller: &Self::CallerCtx, account_id: &Id, region_id: &Id, ) -> impl Future<Output = Result<bool, Self::Error>> + Send { ... } fn is_object_visible( &self, caller: &Self::CallerCtx, account_id: &Id, object: &SceneObject, ) -> impl Future<Output = Result<bool, Self::Error>> + Send { ... } fn is_user_blocked( &self, caller: &Self::CallerCtx, user_id: &str, ) -> impl Future<Output = Result<bool, Self::Error>> + Send { ... } fn may_see_region_avatars( &self, caller: &Self::CallerCtx, account_id: &Id, region_id: &Id, ) -> impl Future<Output = Result<bool, Self::Error>> + Send { ... } fn avatar_view( &self, caller: &Self::CallerCtx, account_id: &Id, avatar: &SceneAvatar, ) -> impl Future<Output = Result<AvatarView, Self::Error>> + Send { ... } fn supports_observe(&self, caller: &Self::CallerCtx) -> bool { ... } fn may_observe_region( &self, caller: &Self::CallerCtx, account_id: &Id, region: &SceneRegion, ) -> impl Future<Output = Result<bool, Self::Error>> + Send { ... } fn observer_accounts( &self, caller: &Self::CallerCtx, own_account_id: &Id, ) -> impl Future<Output = Result<Vec<Id>, Self::Error>> + Send { ... } fn set_observing( &self, caller: &Self::CallerCtx, account_id: &Id, region_id: &Id, observing: bool, ) -> impl Future<Output = Result<(), Self::Error>> + Send { ... } fn accept_interaction( &self, caller: &Self::CallerCtx, account_id: &Id, event: &SceneInteractionEvent, ) -> impl Future<Output = Result<bool, Self::Error>> + Send { ... } fn accept_region_event( &self, caller: &Self::CallerCtx, account_id: &Id, event: &SceneRegionEvent, ) -> impl Future<Output = Result<bool, Self::Error>> + Send { ... }
}
Expand description

Storage backend for the JMAP Scene method handlers (draft-atwood-jmap-scene-00).

§Permission enforcement (backend canonical)

Per the workspace AGENTS.md “Caller identity (foundation seam)” rule the backend re-verifies every permission atomically with the mutation. The handlers apply the draft’s checks (media type, blob, size quota, the owner-or-admin rule via Self::may_modify_asset) as defense in depth.

§Changes

Unlike /get and /query, JmapReads::get_changes is not scoped to the caller. Visibility filtering “does not change the JMAP state model: each data type has one state string per account”, and /changes reports the account’s changes (draft-atwood-jmap-scene-00 §Visibility Contract). A /changes result may therefore name an id that /get then hides: “A server MAY report an object hidden from the caller in notFound from /get”. Unlike draft-atwood-jmap-graph-00, Scene does not ask /changes to omit what the caller may not read, with one exception: a backend that hides SceneAvatar records or withholds their properties to protect information (Self::avatar_view) SHOULD answer SceneAvatar/changes from the caller’s view (jmap-chat-spec 93f2258 §Avatar Visibility). get_changes receives the caller for that.

This trait is not object-safe by design (generic methods). Use Arc<impl SceneBackend> when sharing across tasks.

Required Methods§

Source

fn scene_capability( &self, caller: &Self::CallerCtx, account_id: &Id, ) -> impl Future<Output = Result<SceneCapability, Self::Error>> + Send

The account-level urn:ietf:params:jmap:scene capability object (draft-atwood-jmap-scene-00 §Account-Level Capability Object) the consumer advertises for account_id to this caller.

Every SceneAsset/* handler reads supportsSceneAsset from it and returns unknownMethod when it is false; SceneAsset/set also reads supportedVisualTypes and maxAssetSizeBytes. Return the value the Session object carries; a different value makes the handler contradict the advertised capability. supportedVisualTypes “MUST include at least \"model/gltf-binary\"”; the handler accepts that type whether or not it is listed.

Source

fn blob_size( &self, caller: &Self::CallerCtx, account_id: &Id, blob_id: &Id, ) -> impl Future<Output = Result<Option<u64>, Self::Error>> + Send

The size in bytes of blob blob_id, or None if no such blob was uploaded to account_id (RFC 8620 §6.1).

SceneAsset/set create stores the size as the asset’s size and refuses a missing blob with invalidProperties naming blobId (“blobId does not reference a valid blob”). There is no default: a default would invent sizes or refuse every create. Return Err for a transient storage failure, never Ok(None): the handler maps Err to serverFail so the client retries.

Source

fn create_object<O, F>( &self, caller: &Self::CallerCtx, account_id: &Id, create_id: &str, build: F, ) -> impl Future<Output = Result<(Id, O), BackendSetError<Self::Error>>> + Send
where O: SetObject + Send + Sync, F: FnOnce(&Id) -> O + Send,

Create an object.

The handler has validated the create against draft-atwood-jmap-scene-00 §SceneAsset/set and filled the server-set properties other than id. The backend MUST, in one atomic step, mint a ULID id (“A ULID assigned at creation”), call build(&id) once for the object carrying it, and store that object.

For a SceneAsset the backend also enforces the deployment-defined rules of §SetError Conditions atomically with the insert: refuse with overQuota for “Account asset storage quota exceeded”, and with forbidden when the “Deployment restricts shared-asset creation to administrators” and the caller is not one.

For a SceneRegion the backend refuses with overQuota when the account already holds maxRegionsPerAccount regions (“The server MUST return overQuota when maxRegionsPerAccount would be exceeded”), counted atomically with the insert.

For a SceneObject the backend sets ownerId to the caller’s userId (“The userId of the user who created this object”; the handler sends null) and refuses with overQuota when the object’s region already holds maxObjectsPerRegion objects (“The server MUST return overQuota when maxObjectsPerRegion would be exceeded”), counted atomically with the insert.

For a SceneAvatar (§Entering a Region) the handler has filled userId from Self::caller_user_id, position, orientation, joinedAt (now) and leftAt (null). In one atomic step the backend:

  1. refuses with alreadyExists and existingId naming the record when the user already has an avatar in the region, present or departed (“the server MUST NOT create a second record and MUST return an alreadyExists SetError … with existingId set to the id of that record”);
  2. refuses with overQuota when the region already holds maxAvatarsPerRegion avatars with leftAt null;
  3. sets leftAt to the new joinedAt on the user’s active avatar in any other region (“the server SHOULD set leftAt on the previous avatar before creating the new one”);
  4. keeps each affected region’s activeAvatarCount (“Number of avatars currently present in the region”) equal to its avatars with leftAt null, advancing the SceneRegion state.

Returns the assigned id and the stored object. create_id is the client’s creation id. Error mapping, state-counter and change-log rules are those of the canonical jmap-mail-server create_object: the state advances only when the create commits.

Source

fn update_object<O: SetObject + Send + Sync>( &self, caller: &Self::CallerCtx, account_id: &Id, id: &Id, patch: O::Patch, ) -> impl Future<Output = Result<Option<O>, BackendSetError<Self::Error>>> + Send

Apply an RFC 8620 §5.3 PatchObject to an existing object.

Ok(Some(o)) echoes server-changed properties; Ok(None) means the patch applied verbatim. Both MUST advance the state and record an updated change. Unknown id is notFound; a malformed patch is invalidPatch; a result that no longer decodes is invalidProperties. Apply the whole patch or none of it.

For a SceneAvatar whose patch sets leftAt to a UTCDate, the backend refuses with invalidProperties naming leftAt when the stored leftAt is already non-null (“double-leave is invalid”), and otherwise decrements the region’s activeAvatarCount in the same atomic step (“The server decrements the region’s activeAvatarCount”), advancing the SceneRegion state.

A patch that sets leftAt to null re-enters the region (§Re-entering a Region); the handler has added joinedAt (now), position and orientation (the region’s spawn point). In the same atomic step the backend refuses with invalidProperties naming leftAt when the stored leftAt is null, then applies steps 2 to 4 of Self::create_object for a SceneAvatar: the maxAvatarsPerRegion overQuota, setting leftAt on the user’s active avatar in any other region, and the activeAvatarCount update.

Source

fn destroy_object<O: SetObject + Send + Sync>( &self, caller: &Self::CallerCtx, account_id: &Id, id: &Id, ) -> impl Future<Output = Result<(), BackendSetError<Self::Error>>> + Send

Destroy an object by id. Unknown id is notFound; the state advances only when the destroy commits. The handler has already applied the permission check.

Destroying a SceneRegion “removes the SceneRegion and all SceneObject and SceneAvatar records in it; SceneObject/changes and SceneAvatar/changes report those records as destroyed” (draft-atwood-jmap-scene-00 §Destroying a Region): in the same atomic step the backend destroys every SceneObject and SceneAvatar whose regionId is id and records each as a destroyed change of its type. It does not end a VTCCall the region’s activeCallId references (“the server MUST NOT automatically end the referenced VTCCall”).

Destroying a SceneObject “removes the SceneObject and all its children (objects whose parentId references this object, recursively)”: in the same atomic step the backend destroys every descendant and records each as a destroyed SceneObject change.

Source

fn has_capability( &self, caller: &Self::CallerCtx, account_id: &Id, uri: &str, ) -> bool

true if the consumer advertises the capability uri for account_id.

The SceneRegion binding properties “are present only when the corresponding companion capability is advertised on the same account”: chatId, spaceId and channelId need urn:ietf:params:jmap:chat, activeCallId needs urn:ietf:params:jmap:vtc. SceneRegion/set refuses a non-null binding without its capability, and accessPolicy "space" without urn:ietf:params:jmap:chat, with invalidProperties; a create stores null for the bindings whose capability is advertised.

Source

fn caller_user_id( &self, caller: &Self::CallerCtx, account_id: &Id, ) -> impl Future<Output = Result<String, Self::Error>> + Send

The caller’s userId: “The authenticated user identity string” (draft-atwood-jmap-scene-00 §SceneAvatar userId).

SceneAvatar/set stores it as a created avatar’s userId (“The server sets userId from the authenticated identity”) and compares it with an updated avatar’s userId (“Users MUST NOT update other users’ avatars”). There is no default: the handlers cannot know the identity.

Source

fn supports_type<O: JmapObject>( &self, caller: &Self::CallerCtx, account_id: &Id, ) -> bool

Per-backend capability probe: true if this backend supports the JMAP object type O for account_id. Not called by the handlers; consumers use it when assembling their Session capabilities (“Deployments … MAY omit support for SceneAsset methods”).

Provided Methods§

Source

fn may_modify_asset( &self, caller: &Self::CallerCtx, account_id: &Id, asset: &SceneAsset, ) -> impl Future<Output = Result<bool, Self::Error>> + Send

true if the caller may update or destroy asset: “Only the asset owner or an admin may modify asset metadata” (draft-atwood-jmap-scene-00 §SceneAsset/set Update Errors; Destroy Errors use the “Same permission model as update”).

SceneAsset/set returns forbidden for an update or destroy when this is false.

§Default implementation

Returns Ok(true): every caller may modify every asset. This is the workspace’s fail-open posture for permission hooks (bd:JMAP-bghk); production backends override it.

Source

fn region_binding( &self, caller: &Self::CallerCtx, account_id: &Id, property: BindingProperty, id: &Id, ) -> impl Future<Output = Result<BindingTarget, Self::Error>> + Send

What the binding property set to id references, for the checks of draft-atwood-jmap-scene-00 §Creating a Region (“the server MUST verify that the referenced object exists and the caller has access to it”) and §Updating a Region (for activeCallId: “(a) the referenced VTCCall exists, (b) its state is not \"ended\", and (c) the caller is a participant in or moderator of the referenced call, or has deployment-defined administrative privileges”).

SceneRegion/set calls this for each non-null binding a create sets or an update patches, after the capability check. The Chat and VTC lookups live in the binding crates; this crate depends on RFC 8620 only.

§Default implementation

Returns Ok(BindingTarget::Usable): every reference is accepted. This is the workspace’s fail-open posture for permission hooks (bd:JMAP-bghk); a backend that advertises Chat or VTC overrides it.

Source

fn channel_in_space( &self, caller: &Self::CallerCtx, account_id: &Id, channel_id: &Id, space_id: &Id, ) -> impl Future<Output = Result<bool, Self::Error>> + Send

true if channel_id “is a channel of the Space named by spaceId” (draft-atwood-jmap-scene-00 §Updating a Region, the binding checks).

SceneRegion/set calls this when a create or an update sets channelId or spaceId and the region as it would be after the write has both non-null, after Self::region_binding accepted each. false fails the write with invalidProperties naming channelId.

§Default implementation

Returns Ok(true) (fail-open, bd:JMAP-bghk); a backend that advertises Chat overrides it.

Source

fn may_update_region( &self, caller: &Self::CallerCtx, account_id: &Id, region: &SceneRegion, ) -> impl Future<Output = Result<bool, Self::Error>> + Send

true if the caller may update region: “Only the owner or an admin may modify region properties” (draft-atwood-jmap-scene-00 §SceneRegion/set Update Errors).

The same owner-or-admin rule gates SceneRegion/broadcast and changes to SceneAvatar.regionState on the region’s avatars (jmap-chat-spec 93f2258), so those handlers ask this hook too.

§Default implementation

Returns Ok(true) (fail-open, bd:JMAP-bghk); production backends override it.

Source

fn may_destroy_region( &self, caller: &Self::CallerCtx, account_id: &Id, region: &SceneRegion, ) -> impl Future<Output = Result<bool, Self::Error>> + Send

true if the caller may destroy region: “Only the region owner or an admin may destroy a region” (draft-atwood-jmap-scene-00 §SceneRegion/set Destroy Errors).

§Default implementation

Returns Ok(true) (fail-open, bd:JMAP-bghk); production backends override it.

Source

fn may_modify_object( &self, caller: &Self::CallerCtx, account_id: &Id, object: &SceneObject, ) -> impl Future<Output = Result<bool, Self::Error>> + Send

true if the caller may update or destroy object: “Only the object’s ownerId, the region owner, or a deployment-admin may modify another user’s object” (draft-atwood-jmap-scene-00 §SceneObject/set Update Errors; Destroy Errors use the “Same permission model as update”).

SceneObject/set returns forbidden for an update or destroy when this is false.

§Default implementation

Returns Ok(true) (fail-open, bd:JMAP-bghk); production backends override it.

Source

fn avatar_display_name( &self, caller: &Self::CallerCtx, account_id: &Id, user_id: &str, ) -> impl Future<Output = Result<String, Self::Error>> + Send

The displayName of a new avatar for user_id when the create supplies none: “the server sets it from the user profile or ChatContact when {{JMAP-CHAT}} is present”.

§Default implementation

Returns user_id. A Chat binding crate or a backend with user profiles overrides it.

Source

fn reserved_display_names( &self, caller: &Self::CallerCtx, account_id: &Id, ) -> impl Future<Output = Result<Vec<String>, Self::Error>> + Send

The reserved display names (draft-atwood-jmap-scene-00 §Avatar Identity and Impersonation, jmap-chat-spec 77c3474 L2776): “The server MAY maintain a list of reserved display names that correspond to system roles or administrative functions and MAY reject SceneAvatar/set operations that attempt to use a reserved name with a SetError of type forbidden.” This crate rejects them by choice.

SceneAvatar/set refuses a create or update whose client-supplied displayName equals one of these names exactly with forbidden. The comparison is case-sensitive, so list each spelling to reserve. A name set by Self::avatar_display_name is not checked.

§Default implementation

Returns no names (fail-open, bd:JMAP-bghk); deployments supply their list.

Source

fn may_enter_region( &self, caller: &Self::CallerCtx, account_id: &Id, region: &SceneRegion, ) -> impl Future<Output = Result<bool, Self::Error>> + Send

true unless the caller is barred from entering region, which it already has access to: “User is banned or ejected with a cooldown period still active” (draft-atwood-jmap-scene-00 §Create Errors). SceneAvatar/set create and an update that re-enters a region return forbidden when this is false, since “The user already knows the region exists”. Access under the region’s accessPolicy is Self::may_access_region, not this hook: a create without it is invalidProperties naming regionId, a re-entry notFound.

§Default implementation

Returns Ok(true) (fail-open, bd:JMAP-bghk); production backends override it.

Source

fn may_eject_avatar( &self, caller: &Self::CallerCtx, account_id: &Id, avatar: &SceneAvatar, ) -> impl Future<Output = Result<bool, Self::Error>> + Send

true if the caller may eject avatar, another user’s avatar: “region owners and administrators may set leftAt on another user’s avatar to eject them” (draft-atwood-jmap-scene-00 §Update Errors).

SceneAvatar/set calls this only for a patch of another user’s avatar that sets leftAt and touches nothing else (“An eject update patches only leftAt”, §Avatar Permissions); false is forbidden.

§Default implementation

Returns Ok(true) (fail-open, bd:JMAP-bghk); production backends override it.

Source

fn may_access_region( &self, caller: &Self::CallerCtx, account_id: &Id, region_id: &Id, ) -> impl Future<Output = Result<bool, Self::Error>> + Send

true if the caller has access to region region_id (draft-atwood-jmap-scene-00 §Region Access): “A user has access to a region when its accessPolicy admits the user, when the user is the region owner, when the user has deployment-defined administrative privileges, or when the user has an active SceneAvatar in it.” "invite" admits “The users whose userIds are listed in invitedUserIds”, and “Servers MAY admit users to an \"invite\" region by other mechanisms as well”.

SceneRegion/get, SceneObject/get and SceneAvatar/get report a region, object or avatar in a region without access as notFound: “The server SHOULD treat a request from a user without access to a region as if the region did not exist: notFound for SceneRegion/get, SceneObject/get, and SceneAvatar/get … and no results from the region in /query” (draft-atwood-jmap-scene-00 at 29e9a41, L2606). SceneRegion/set, SceneObject/set and SceneAvatar/set report an update or destroy of such a record as notFound too, never forbidden. A region that no longer exists may be treated either way.

The handlers cannot filter a /query page they did not cut, so query_objects should omit what /get would hide: “The server SHOULD NOT include a SceneObject in a SceneObject/get response or SceneObject/query result if the authenticated user does not have access to the object’s containing SceneRegion” (§Visibility Contract, L2577). The same applies to SceneRegion and SceneAvatar results (L2606).

query_changes is not filtered per caller: visibility filtering “does not change the JMAP state model: each data type has one state string per account … and /changes and /queryChanges report changes for the account” (L2587). An id it reports that the caller may not see, /get reports in notFound.

§Default implementation

Returns Ok(true) (fail-open, bd:JMAP-bghk); production backends override it.

Source

fn is_object_visible( &self, caller: &Self::CallerCtx, account_id: &Id, object: &SceneObject, ) -> impl Future<Output = Result<bool, Self::Error>> + Send

true if object is in the caller’s visibility set: “The server SHOULD apply visibility filtering to limit the objects returned based on the authenticated user’s avatar position within the region. The specific visibility algorithm is deployment-defined” (draft-atwood-jmap-scene-00 §Visibility Contract).

Consulted only for objects in a region the caller may access (Self::may_access_region). SceneObject/get reports an object outside the set as notFound, and SceneObject/set refuses an update or destroy of it with notFound: “The server SHOULD NOT return forbidden, as that would confirm the object still exists” (L2589). query_objects should omit such objects as well; query_changes reports changes for the account (L2587).

§Default implementation

Returns Ok(true): “A simple deployment MAY return all objects in the region.”

Source

fn is_user_blocked( &self, caller: &Self::CallerCtx, user_id: &str, ) -> impl Future<Output = Result<bool, Self::Error>> + Send

true if user_id is blocked on the caller’s own contact list (draft-atwood-jmap-scene-00 at 33702a5 §Blocked-Contact Spatial Presence, L2672): “SceneAvatar records belonging to a blocked ChatContact SHOULD be excluded from SceneAvatar/get responses and SceneAvatar/query results delivered to the blocking user”.

The list is the caller’s, whatever account the request names: the server “removes any SceneAvatar records whose userId corresponds to a ChatContact with blocked: true on the requesting user’s contact list” (L2676). A request on a shared region names the region’s hosting account, which holds the host’s contacts, not the requester’s, so the hook takes no account id; an implementation resolves the caller’s own account from caller.

Consulted only for avatars in a region the caller may access: “Blocked-contact filtering is applied AFTER the visibility filtering”. SceneAvatar/get reports such an avatar exactly as a missing one, in notFound (“The server SHOULD NOT return an error, a filtered-result indicator, or any other signal”, L2674); query_objects should omit it as well, while query_changes reports changes for the account (§Visibility Contract). The handlers leave activeAvatarCount the true count, which deployments “SHOULD prefer” (L2678).

crate::should_deliver asks this at delivery time with the recipient as the caller, since suppression consults “the recipient’s ChatContact records” (draft-atwood-jmap-scene-wss-00 at 33702a5, L793-795).

The Chat lookup (ChatContact.blocked) lives in the binding crate: “Without urn:ietf:params:jmap:chat, there is no blocked-contact list and this filtering does not apply.”

§Default implementation

Returns Ok(false): no one is blocked. This is the workspace’s fail-open posture for policy hooks (bd:JMAP-bghk).

Source

fn may_see_region_avatars( &self, caller: &Self::CallerCtx, account_id: &Id, region_id: &Id, ) -> impl Future<Output = Result<bool, Self::Error>> + Send

true if the caller may see the SceneAvatar records of region region_id (draft-atwood-jmap-scene-00 at 6bcd9d8, L2654): “When a SceneRegion’s activeCallId references a VTCCall with e2eeEnabled set to true, the server SHOULD NOT expose the region’s SceneAvatar records to users who are not participants in the bound VTCCall: for such users it SHOULD return notFound for SceneAvatar/get, exclude the records from SceneAvatar/query, and suppress SceneAvatarEvent … delivery (entered, left, and ejected).”

Consulted only for avatars in a region the caller may access (Self::may_access_region). SceneAvatar/get reports the avatars of a region answering false in notFound, and crate::should_deliver drops their SceneAvatarEvents; query_objects should omit them as well, while query_changes reports changes for the account (§Visibility Contract).

The VTC lookup (VTCCall.e2eeEnabled and the call’s participants) lives in the binding crate, jmap-scene-vtc-server.

§Default implementation

Returns Ok(true): no region hides its avatars. This is the workspace’s fail-open posture for policy hooks (bd:JMAP-bghk); a deployment without it exposes the call’s participant presence, the limitation the draft’s SHOULD leaves to it.

Source

fn avatar_view( &self, caller: &Self::CallerCtx, account_id: &Id, avatar: &SceneAvatar, ) -> impl Future<Output = Result<AvatarView, Self::Error>> + Send

What the caller may see of avatar, another user’s avatar (draft-atwood-jmap-scene-00 at jmap-chat-spec 93f2258, §Avatar Visibility): “A server MAY also limit which SceneAvatar records, and which of their properties, each caller sees: for example, to keep opponents’ positions from players during a competitive round”. The rule is deployment-defined.

The handlers never ask about the caller’s own avatar: “A caller always sees their own avatar in full”. The hook “SHOULD NOT hide avatars, or withhold their properties, from the region owner and administrators”, which is the implementation’s to honor. It is consulted after region access, the blocked-contact filter and Self::may_see_region_avatars, which stay separate.

  • SceneAvatar/get reports an AvatarView::Hidden avatar in notFound and returns a AvatarView::Redacted one with its AvatarRedaction applied; the withheld properties are unreadable to a draft-ietf-jmap-conditional-02 precondition.
  • SceneAvatar/set refuses an update of a hidden avatar with notFound.
  • crate::should_deliver drops a SceneAvatarEvent about a hidden avatar: “an event about an avatar hidden from the recipient is not delivered to that recipient”.
  • query_objects must apply the same view, since the handlers cannot filter a page they did not cut: leave hidden avatars out and evaluate filters and sorts “against the values returned to the caller, so a spatial query cannot locate an avatar whose position is withheld”.
  • get_changes (and query_changes) of a backend that hides avatars “to protect information, rather than only for blocked contacts or end-to-end encrypted calls, SHOULD answer /changes and /queryChanges from the caller’s view”: an avatar that becomes visible is created, one that becomes hidden is destroyed, and one is updated “only when a value returned to the caller changes”. The state string stays one per account and advances “Whenever the caller’s view changes”, so push notifies the caller. The handlers pass the caller to get_changes; the per-caller log is the backend’s.

activeAvatarCount still counts hidden avatars.

§Default implementation

Returns Ok(AvatarView::Full): every avatar is visible in full, today’s behavior (fail-open, bd:JMAP-bghk).

Source

fn supports_observe(&self, caller: &Self::CallerCtx) -> bool

true if the server advertises supportsObserve in its urn:ietf:params:jmap:scene:websocket Session capability (SceneWebSocketCapability; draft-atwood-jmap-scene-wss-00 at jmap-chat-spec 93f2258).

When true, SceneRegion/set gives a created region allowObservers (default true) and observerCount (0) and accepts updates of allowObservers, and the websocket handler recognizes observe in SceneStreamEnable. When false the two region properties are refused with invalidProperties and observe is ignored: “Recognized only when the server advertises supportsObserve”. A backend that returns true must also implement Self::set_observing, so observerCount is right.

§Default implementation

Returns false: no observer subscriptions, today’s behavior.

Source

fn may_observe_region( &self, caller: &Self::CallerCtx, account_id: &Id, region: &SceneRegion, ) -> impl Future<Output = Result<bool, Self::Error>> + Send

true unless the server declines observers of region for deployment-defined policy: “A server MAY also decline observers of a region for deployment-defined policy reasons even when allowObservers is true” (jmap-chat-spec 93f2258 §SceneStreamEnable).

Asked for a region the caller has access to, when a SceneStreamEnable with observe: true lists it (false makes it one of the refused regionIds of the forbidden RequestError) and again at delivery time by crate::should_deliver for an observer without an active avatar there.

§Default implementation

Returns Ok(true) (fail-open, bd:JMAP-bghk).

Source

fn observer_accounts( &self, caller: &Self::CallerCtx, own_account_id: &Id, ) -> impl Future<Output = Result<Vec<Id>, Self::Error>> + Send

The accounts whose regions a SceneStreamEnable with observe: true may name, for a connection whose own account is own_account_id: “An id listed in regionIds matches in every account the user can access” (draft-atwood-jmap-scene-wss-00 §SceneStreamEnable).

The websocket handler looks each listed region up in each of these accounts to decide which regions are refused, and reports each listed region of each of them to Self::set_observing. Access to each region is still checked with Self::may_access_region. These are the accounts “the server chooses” for the enable-time checks; “delivery is not limited to those accounts” (draft-atwood-jmap-scene-wss-00 at jmap-chat-spec 42aed85), and the handler reports a listed region of another account from the first event for it that reaches the connection.

§Default implementation

Returns own_account_id alone. A deployment with shared regions overrides it with the accounts the caller can access.

Source

fn set_observing( &self, caller: &Self::CallerCtx, account_id: &Id, region_id: &Id, observing: bool, ) -> impl Future<Output = Result<(), Self::Error>> + Send

Record that one connection of the caller started (observing true) or stopped (false) observing region region_id of account_id (jmap-chat-spec 93f2258, observerCount).

The websocket handler calls it with true for each region a connection’s observer subscription covers, and with false when the subscription stops covering it: a new SceneStreamEnable, SceneStreamDisable or the connection closing. A region is covered when SceneStreamEnable with observe: true lists it, in each of Self::observer_accounts, and in any other account from the first event for it that reaches the connection, since “delivery is not limited to those accounts”. The handler reports a covered region whether or not the caller has access to it, it admits observers, or the caller has an avatar there at the time, because delivery checks all three again for each event. Calls are balanced per connection, so a caller with several observing connections calls true several times.

The backend keeps observerCount, counting only the reported users that delivery reaches: “While an observer subscription delivers events for a region to a user without an active avatar there, the user counts toward the region’s observerCount”, and “A user with several observing connections counts once” (jmap-chat-spec 42aed85). That is a reported user with access to the region (Self::may_access_region) and no active avatar in it, while its allowObservers is not false and Self::may_observe_region admits observers. Recount it, atomically with the change, here and whenever any of those inputs changes: one of those users enters or leaves the region with an avatar, gains or loses access (including through a change outside the region, such as a Space membership), allowObservers changes, or the observer policy changes. “Like activeAvatarCount, a change to it is a change to the SceneRegion”: record the region as updated and advance the SceneRegion state, so push sends a StateChange.

§Default implementation

Returns Ok(()) and counts nothing. That is correct only while Self::supports_observe is false, when no observer exists.

Source

fn accept_interaction( &self, caller: &Self::CallerCtx, account_id: &Id, event: &SceneInteractionEvent, ) -> impl Future<Output = Result<bool, Self::Error>> + Send

Accept an interaction that passed the SceneObject/interact checks, or refuse it for its rate (draft-atwood-jmap-scene-00 §SceneObject/interact).

event carries the interaction and the caller’s userId from Self::caller_user_id. Ok(false) means “The caller has exceeded a deployment-defined interaction rate” and the handler reports rateLimit; draft-atwood-jmap-scene-wss-00 §Rate Limiting suggests “no more than five events per user per region per second”. Ok(true) accepts it: count it against the rate and, when the WebSocket capability is supported, hand event to the transport, which “delivers a SceneInteractionEvent carrying the interaction and the caller’s userId to the WebSocket subscribers of the region”, filtered per recipient by crate::should_deliver. Counting and delivering in this one call keeps them atomic.

§Default implementation

Returns Ok(true) and delivers nothing: no rate limit (fail-open, bd:JMAP-bghk) and no WebSocket transport.

Source

fn accept_region_event( &self, caller: &Self::CallerCtx, account_id: &Id, event: &SceneRegionEvent, ) -> impl Future<Output = Result<bool, Self::Error>> + Send

Accept a region event that passed the SceneRegion/broadcast checks, or refuse it for its rate (draft-atwood-jmap-scene-00 at jmap-chat-spec 93f2258, §SceneRegion/broadcast).

The handler calls this only when the account’s SceneCapability::supports_region_broadcast is true, the caller has access to the region (Self::may_access_region) and is its owner or an administrator (Self::may_update_region: “Only the region owner and users with deployment-defined administrative privileges may broadcast to a region”). Ok(false) means “The caller has exceeded a deployment-defined rate for region events” and the handler reports rateLimit. Ok(true) accepts it: count it against the rate and, when the WebSocket capability is supported, hand event to the transport, which “delivers a SceneRegionEvent to the WebSocket subscribers of the region”, filtered per recipient by crate::should_deliver (with the websocket feature, websocket::SceneEventHub::publish).

Server-originated region events (“The server itself MAY also originate region events”) do not pass through here; the deployment publishes them to the transport directly.

§Default implementation

Returns Ok(true) and delivers nothing: no rate limit (fail-open, bd:JMAP-bghk) and no WebSocket transport.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§

Source§

impl<C: MemoryCaller> SceneBackend for MemoryBackend<C>

Available on crate feature memory only.