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§
Sourcefn scene_capability(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
) -> impl Future<Output = Result<SceneCapability, Self::Error>> + Send
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.
Sourcefn blob_size(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
blob_id: &Id,
) -> impl Future<Output = Result<Option<u64>, 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
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.
Sourcefn 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
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
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:
- refuses with
alreadyExistsandexistingIdnaming 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 analreadyExistsSetError… withexistingIdset to the id of that record”); - refuses with
overQuotawhen the region already holdsmaxAvatarsPerRegionavatars withleftAtnull; - sets
leftAtto the newjoinedAton the user’s active avatar in any other region (“the server SHOULD setleftAton the previous avatar before creating the new one”); - keeps each affected region’s
activeAvatarCount(“Number of avatars currently present in the region”) equal to its avatars withleftAtnull, advancing theSceneRegionstate.
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.
Sourcefn 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 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.
Sourcefn destroy_object<O: SetObject + Send + Sync>(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
id: &Id,
) -> impl Future<Output = Result<(), 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
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.
Sourcefn has_capability(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
uri: &str,
) -> bool
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.
Sourcefn caller_user_id(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
) -> impl Future<Output = Result<String, Self::Error>> + Send
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.
Sourcefn supports_type<O: JmapObject>(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
) -> bool
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§
Sourcefn may_modify_asset(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
asset: &SceneAsset,
) -> impl Future<Output = Result<bool, Self::Error>> + Send
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.
Sourcefn region_binding(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
property: BindingProperty,
id: &Id,
) -> impl Future<Output = Result<BindingTarget, 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
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.
Sourcefn 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 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.
Sourcefn may_update_region(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
region: &SceneRegion,
) -> 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
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.
Sourcefn may_destroy_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
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.
Sourcefn may_modify_object(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
object: &SceneObject,
) -> 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
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.
Sourcefn avatar_display_name(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
user_id: &str,
) -> impl Future<Output = Result<String, 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
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.
Sourcefn reserved_display_names(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
) -> impl Future<Output = Result<Vec<String>, Self::Error>> + Send
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.
Sourcefn may_enter_region(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
region: &SceneRegion,
) -> impl Future<Output = Result<bool, Self::Error>> + Send
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.
Sourcefn may_eject_avatar(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
avatar: &SceneAvatar,
) -> 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
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.
Sourcefn may_access_region(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
region_id: &Id,
) -> 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
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.
Sourcefn is_object_visible(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
object: &SceneObject,
) -> 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
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.”
Sourcefn is_user_blocked(
&self,
caller: &Self::CallerCtx,
user_id: &str,
) -> 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
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).
Sourcefn may_see_region_avatars(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
region_id: &Id,
) -> 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
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.
Sourcefn avatar_view(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
avatar: &SceneAvatar,
) -> impl Future<Output = Result<AvatarView, Self::Error>> + Send
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/getreports anAvatarView::Hiddenavatar innotFoundand returns aAvatarView::Redactedone with itsAvatarRedactionapplied; the withheld properties are unreadable to a draft-ietf-jmap-conditional-02 precondition.SceneAvatar/setrefuses an update of a hidden avatar withnotFound.crate::should_deliverdrops aSceneAvatarEventabout a hidden avatar: “an event about an avatar hidden from the recipient is not delivered to that recipient”.query_objectsmust 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(andquery_changes) of a backend that hides avatars “to protect information, rather than only for blocked contacts or end-to-end encrypted calls, SHOULD answer/changesand/queryChangesfrom the caller’s view”: an avatar that becomes visible iscreated, one that becomes hidden isdestroyed, and one isupdated“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 toget_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).
Sourcefn supports_observe(&self, caller: &Self::CallerCtx) -> bool
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.
Sourcefn may_observe_region(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
region: &SceneRegion,
) -> impl Future<Output = Result<bool, Self::Error>> + Send
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).
Sourcefn observer_accounts(
&self,
caller: &Self::CallerCtx,
own_account_id: &Id,
) -> impl Future<Output = Result<Vec<Id>, Self::Error>> + Send
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.
Sourcefn set_observing(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
region_id: &Id,
observing: bool,
) -> impl Future<Output = Result<(), 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
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.
Sourcefn accept_interaction(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
event: &SceneInteractionEvent,
) -> impl Future<Output = Result<bool, Self::Error>> + Send
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.
Sourcefn accept_region_event(
&self,
caller: &Self::CallerCtx,
account_id: &Id,
event: &SceneRegionEvent,
) -> 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
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§
impl<C: MemoryCaller> SceneBackend for MemoryBackend<C>
memory only.