jmap-scene-server 0.5.0

JMAP Scene method handlers (draft-atwood-jmap-scene-00 SceneAsset) — backend-agnostic, plugs into jmap-server Dispatcher
Documentation

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 std::sync::Arc;
use jmap_server::Dispatcher;
use jmap_scene_server::{memory::MemoryBackend, register_scene_handlers};

let backend = Arc::new(MemoryBackend::new());
let mut dispatcher: Dispatcher<String> = Dispatcher::new();
register_scene_handlers(&mut dispatcher, backend);

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_asset defaults to Ok(true) (fail-open, bd:JMAP-bghk). Override it, or every caller can rename and delete every asset.
  • may_update_region, may_destroy_region and region_binding also fail open: any caller may change any region, and every binding id is accepted, until you override them.
  • may_modify_object fails open too: any caller may move or delete any SceneObject until you override it.
  • may_enter_region and may_eject_avatar fail open too: no one is banned from a region and anyone may eject anyone, until you override them. Entry to an invite or space region is decided by may_access_region.
  • caller_user_id has 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 parentId index can register a faster SceneObject/set.
  • has_capability has no default. Return true only for the companion capabilities you advertise on that account.
  • Destroying a region does not end its activeCallId VTCCall, and this crate sends no VTCCall StateChange. That belongs to the Scene/VTC binding crate.
  • blob_size has no default. Return Err for a storage failure, not Ok(None), or the client sees invalidProperties and does not retry.
  • model/gltf-binary is accepted even if your capability object omits it. The draft requires you to list it.
  • "Recognized audio/image type" means any audio/* or image/* media type; there is no registry lookup.
  • The name filter is a case-insensitive substring match, as in the draft's example. The name sort ignores collation and puts assets without a name last.
  • The MemoryBackend caller context is the caller's userId String; the creator owns an asset. grant_region_access admits a user to an invite region. Its /queryChanges always returns cannotCalculateChanges.

References