jmap-scene-server
Method handlers for the SceneAsset, SceneRegion, SceneObject and
SceneAvatar data types of the
JMAP Scene extension (draft-atwood-jmap-scene-00), backend-agnostic, for a
jmap-server Dispatcher. You supply storage through the SceneBackend
trait.
What it is
| Item | Spec |
|---|---|
handle_scene_asset_get, handle_scene_asset_changes |
§SceneAsset/get, §SceneAsset/changes (RFC 8620 §5.1, §5.2) |
handle_scene_asset_set |
§SceneAsset/set and its §SetError Conditions |
handle_scene_asset_query, handle_scene_asset_query_changes |
§SceneAsset/query, §SceneAsset/queryChanges |
GLTF_BINARY |
§Preferred Asset Format: model/gltf-binary is mandatory to implement |
handle_scene_region_get, handle_scene_region_changes |
§SceneRegion/get, §SceneRegion/changes (RFC 8620 §5.1, §5.2) |
handle_scene_region_set |
§SceneRegion/set: create, update, destroy and §SetError Conditions |
handle_scene_region_query, handle_scene_region_query_changes |
§SceneRegion/query, §SceneRegion/queryChanges |
handle_scene_object_get, handle_scene_object_changes |
§SceneObject/get, §SceneObject/changes (RFC 8620 §5.1, §5.2) |
handle_scene_object_set |
§SceneObject/set: create, update, recursive destroy and §SetError Conditions |
handle_scene_object_query, handle_scene_object_query_changes |
§SceneObject/query, §Spatial Filters, §SceneObject/queryChanges |
handle_scene_object_interact |
§SceneObject/interact: notFound, forbidden, rateLimit and invalidProperties; accepted interactions go to SceneBackend::accept_interaction |
handle_scene_avatar_get, handle_scene_avatar_changes |
§SceneAvatar/get, §SceneAvatar/changes (RFC 8620 §5.1, §5.2) |
handle_scene_avatar_set |
§SceneAvatar/set: enter, update, leave, re-enter, eject and §SetError Conditions |
handle_scene_avatar_query, handle_scene_avatar_query_changes |
§SceneAvatar/query, §SceneAvatar/queryChanges |
query::asset_matches, query::compare_assets |
§SceneAsset/query filter and sort |
query::region_matches, query::compare_regions |
§SceneRegion/query filter and sort |
query::object_matches, query::compare_objects, query::region_local_position |
§SceneObject/query filter, spatial filters and sort |
query::avatar_matches, query::compare_avatars |
§SceneAvatar/query filter, spatial filters and sort |
SceneBackend |
storage, capability objects, blob sizes, permission and binding hooks |
BindingTarget |
what a chatId/spaceId/channelId/activeCallId references |
memory::MemoryBackend (memory feature) |
in-memory reference backend |
register_scene_handlers |
wires the SceneAsset/*, SceneRegion/*, SceneObject/* (including SceneObject/interact) and SceneAvatar/* methods |
What it's for
A JMAP server that offers spatial scenes wires these handlers next to its
other extensions. The crate depends on jmap-types, jmap-server and
jmap-scene-types only. Chat and VTC lookups for the region bindings
belong to binding crates, which implement SceneBackend::has_capability
and SceneBackend::region_binding.
How to use
use Arc;
use Dispatcher;
use ;
let backend = new;
let mut dispatcher: = new;
register_scene_handlers;
Advertise urn:ietf:params:jmap:scene in your Session with the same
account-level object that SceneBackend::scene_capability returns, and
list model/gltf-binary in its supportedVisualTypes.
How it works
A create must carry blobId and mediaType and must not carry the
server-set id, accountId, size or createdAt. name, assetUri
and sha256 must be strings or null, and sha256 must be lowercase
hex. mediaType must be model/gltf-binary, a type listed in
supportedVisualTypes, or any audio/* or image/* type. Any failure
of these rules is one invalidProperties naming every offending
property. The handler then asks SceneBackend::blob_size: a missing blob
is invalidProperties naming blobId and a blob larger than maxAssetSizeBytes is overQuota.
SceneBackend::create_object assigns the ULID and applies the
deployment's account storage quota and admin-only rule atomically. The
created entry holds the five server-set properties, with ownerId from
SceneBackend::caller_user_id. An update may patch only name,
assetUri, sha256 and extension properties. Update and destroy return
notFound for an unknown id, and forbidden when
SceneBackend::may_modify_asset is false. /query defaults to
createdAt descending. The backend trait is not object-safe (generic
methods); every public type is #[non_exhaustive].
A SceneRegion create needs mayCreateRegion, a non-empty name and
bounds with min <= max on every axis; accessPolicy must be
public, invite or space, and spawnOrientation a unit quaternion
(within 1e-6). space needs urn:ietf:params:jmap:chat and a spaceId.
A non-null chatId, spaceId or channelId needs the Chat capability
and a BindingTarget::Usable answer from region_binding; otherwise it
is invalidProperties naming the property. activeCallId is not a
create property. The backend applies maxRegionsPerAccount atomically
with the insert. An update is validated as the region the patch leaves.
A non-null activeCallId needs urn:ietf:params:jmap:vtc: a missing or
ended call is invalidProperties, an inaccessible one forbidden. The
updated entry echoes the new updatedAt. Update needs
may_update_region and destroy may_destroy_region (owner or admin in
MemoryBackend). On destroy the backend removes the region's SceneObjects
and SceneAvatars. /query defaults to createdAt descending, and an
accessPolicy filter value outside the three is invalidArguments.
A SceneObject create needs mayCreateObject, a regionId naming an
existing region the caller can access (else invalidProperties naming
regionId, the same for both cases) and a finite position. scale must
be finite, orientation within 1e-3 of unit length (stored normalized;
an absent one is the identity), physicsMode one of static, dynamic,
kinematic or none, and visualRef and visualType come together.
visualType must be listed in supportedVisualTypes (or be
model/gltf-binary) and visualRef must name an uploaded blob (else
invalidProperties naming visualRef, on create and update). A parentId must name an existing object (else
invalidProperties naming parentId, on create and update) in the same
region, must not make the object its own ancestor, and must
keep every object within 16 levels; an update that re-parents counts the
moved subtree. The backend sets ownerId to the caller and applies
maxObjectsPerRegion atomically. regionId is immutable. Update and
destroy need may_modify_object (object owner, region owner or admin);
destroy removes the object's descendants too, and only the requested id
appears in destroyed. /query defaults to createdAt ascending and
returns invalidArguments without regionId in every condition, for an
unknown physicsMode, a withinRadius.radius <= 0 or a withinBounds
max below min. The spatial filters compare region-local positions:
a child's parent-relative position is mapped through its ancestors'
transforms, and the boundary is inclusive.
A SceneAvatar create enters a region. It needs a regionId naming an
existing region the caller has access to under may_access_region
(else invalidProperties naming regionId, the same error either way)
and may_enter_region, which bars banned users (else forbidden), and must not carry id, joinedAt, leftAt or another
user's userId (forbidden). The handler sets userId from
caller_user_id, displayName from avatar_display_name when absent,
and position and orientation from the region's spawn values when
absent. A supplied position must be finite, an orientation within
1e-3 of unit length (stored normalized), and visualRef and
visualType come together. In one atomic step create_object refuses
the create with alreadyExists and existingId when the user already
has an avatar in the region, present or departed, applies
maxAvatarsPerRegion to active avatars, sets leftAt on the user's
active avatar in any other region, and keeps every affected region's
activeAvatarCount. The created entry is the stored avatar. An update
of the caller's own avatar may change anything but id, regionId,
userId and joinedAt; setting leftAt leaves the region and a second
leave is invalidProperties naming leftAt. Setting leftAt to null
on a departed avatar re-enters the region (§Re-entering a Region): lost
region access is notFound, may_enter_region false is forbidden,
and a position or orientation in the same patch is
invalidProperties. The handler sets joinedAt to now and position
and orientation to the region's spawn point, and update_object
applies maxAvatarsPerRegion (overQuota), the auto-eject from other
regions and the activeAvatarCount update in the same atomic step. On
another user's avatar only an eject (leftAt, optionally worldState)
is allowed, and only when may_eject_avatar agrees; anything else is
forbidden. Destroy is always forbidden. /query defaults to
joinedAt ascending and returns invalidArguments without regionId in
every condition, for a withinRadius.radius <= 0 or a withinBounds
max below min.
Gotchas
SceneBackend::may_modify_assetdefaults toOk(true)(fail-open, bd:JMAP-bghk). Override it, or every caller can rename and delete every asset.may_update_region,may_destroy_regionandregion_bindingalso fail open: any caller may change any region, and every binding id is accepted, until you override them.may_modify_objectfails open too: any caller may move or delete any SceneObject until you override it.may_enter_regionandmay_eject_avatarfail open too: no one is banned from a region and anyone may eject anyone, until you override them. Entry to aninviteorspaceregion is decided bymay_access_region.caller_user_idhas no default. Avatar ownership is a spec rule, not a policy hook.- Re-parenting an object reads every SceneObject of the account to find
the moved subtree's height. A backend with a
parentIdindex can register a fasterSceneObject/set. has_capabilityhas no default. Returntrueonly for the companion capabilities you advertise on that account.- Destroying a region does not end its
activeCallIdVTCCall, and this crate sends no VTCCall StateChange. That belongs to the Scene/VTC binding crate. blob_sizehas no default. ReturnErrfor a storage failure, notOk(None), or the client seesinvalidPropertiesand does not retry.model/gltf-binaryis accepted even if your capability object omits it. The draft requires you to list it.- "Recognized audio/image type" means any
audio/*orimage/*media type; there is no registry lookup. - The
namefilter is a case-insensitive substring match, as in the draft's example. Thenamesort ignorescollationand puts assets without a name last. - The
MemoryBackendcaller context is the caller's userIdString; the creator owns an asset.grant_region_accessadmits a user to aninviteregion. Its/queryChangesalways returnscannotCalculateChanges.
References
- draft-atwood-jmap-scene-00 — JMAP Scene
- RFC 8620 — JMAP Core
- RFC 6838 — Media Type Specifications and Registration Procedures