Expand description
JMAP Scene method handlers (draft-atwood-jmap-scene-00).
§Usage
Implement SceneBackend for your storage layer, then call
register_scene_handlers to wire the method names into a
jmap_server::Dispatcher:
let mut dispatcher: Dispatcher<()> = Dispatcher::new();
register_scene_handlers(&mut dispatcher, Arc::new(backend));§Scope
The SceneAsset/* methods (draft §SceneAsset Methods): standard
/get, /changes and /queryChanges; /set with the create, update
and destroy SetError conditions, glTF (model/gltf-binary) as the
mandatory-to-implement format and the maxAssetSizeBytes quota; and
/query with the draft’s default sort.
The SceneRegion/* methods (draft §SceneRegion Methods): /set with
the create, update and destroy SetError conditions, mayCreateRegion,
maxRegionsPerAccount, the binding checks through
SceneBackend::region_binding and the destroy cascade; and /query
with the draft’s default sort and accessPolicy filter check.
The SceneObject/* methods (draft §SceneObject Methods): /set with
the create, update and destroy SetError conditions, mayCreateObject,
maxObjectsPerRegion, a region-scoped acyclic scene graph at most 16
levels deep, SceneBackend::may_modify_object and the recursive
destroy; and /query with the draft’s default sort, the §Filter
Validation checks and the withinRadius and withinBounds spatial
filters over region-local positions.
SceneObject/interact (draft §SceneObject/interact): each interaction
is checked for its properties (invalidProperties), region access,
existence and the visibility set (notFound), an active avatar and
interactable (forbidden), then passed to
SceneBackend::accept_interaction, which may refuse it with
rateLimit and otherwise delivers the SceneInteractionEvent.
The SceneAvatar/* methods (draft §SceneAvatar Methods): /set create
enters a region (one avatar record per user and region, alreadyExists
with existingId when the user has a present or departed record there,
auto-eject from another region, maxAvatarsPerRegion and
SceneBackend::may_enter_region), an update that sets leftAt leaves
it or, through SceneBackend::may_eject_avatar, ejects another user,
an update that sets leftAt to null re-enters it at the spawn point,
destroy is forbidden, a displayName from
SceneBackend::reserved_display_names is forbidden, and the
backend keeps activeAvatarCount; and
/query with the draft’s default sort and §Filter Validation.
Visibility (draft §Visibility Contract, §Region Access, §Blocked-Contact
Spatial Presence): /get of SceneRegion, SceneObject and SceneAvatar
reports a record in a region the caller has no access to
(SceneBackend::may_access_region), an object outside the caller’s
visibility set (SceneBackend::is_object_visible), an avatar of a
user the caller blocked (SceneBackend::is_user_blocked) and an
avatar in a region bound to an E2EE call the caller is not in
(SceneBackend::may_see_region_avatars) in notFound, like a
missing id; SceneObject/set refuses an update or
destroy of a hidden object with notFound. The backend omits the same
records from /query and /queryChanges. activeAvatarCount is the
true count, blocked users included, as the draft says deployments
“SHOULD prefer”.
Push (draft §Push Notifications): SCENE_DATA_TYPES, the four types
that participate in RFC 8620 state changes, and push_urgency, the
§Push Urgency recommendation for a StateChange, including the
§Interaction with Chat Push rule that an avatar enter or leave already
announced by a bound Chat’s push is not sent at normal or higher.
Ephemeral subscriptions (draft-atwood-jmap-scene-wss-00
§SceneStreamEnable): SceneEphemeralSubscription holds the per-connection
subscription a SceneStreamEnable frame replaces in its entirety, with
a dynamic (RegionScope::All) or static (RegionScope::Only)
region scope and the invalidArguments check on eventTypes;
should_deliver, the per-event delivery check (active avatar,
visibility, E2EE-call avatar suppression, blocked-sender suppression);
and validate_interaction,
the check on a client-sent SceneInteractionEvent before relay.
The crate depends on RFC 8620 only; Chat and VTC bindings live in
separate binding crates, which implement
SceneBackend::has_capability and SceneBackend::region_binding.
§memory feature (reference implementation)
Enable the memory feature to expose memory::MemoryBackend, the
in-memory reference implementation of SceneBackend used by this
crate’s tests. Not production. Its API may break in any minor
release while the crate is pre-1.0.
Modules§
- query
/queryfilter evaluation and ordering for SceneAsset, SceneRegion, SceneObject and SceneAvatar (draft-atwood-jmap-scene-00 §SceneAsset/query, §SceneRegion/query, §SceneObject/query, §SceneAvatar/query).
Structs§
- Scene
Ephemeral Subscription - The ephemeral Scene subscription of one WebSocket connection.
- Scene
Stream Filter - The active filters of an enabled subscription.
Enums§
- Binding
Property - A SceneRegion binding property, the reference
SceneBackend::region_bindingis asked about (draft-atwood-jmap-scene-00 §Creating a Region, §Updating a Region). - Binding
Target - What
SceneBackend::region_bindingknows about the object a SceneRegion binding property references. - Region
Scope - Which regions a subscription covers.
- Scene
Event - A change, as seen by the user who receives the push, for which §Push Urgency recommends an urgency.
- Urgency
- The Web Push
Urgencyheader (RFC 8030 §5.3) thatpush_urgencypicks; the same typejmap-web-pushsends. The Web PushUrgencyheader (RFC 8030 §5.3), shared by every crate that sends or classifies a push:urgency-option = ("very-low" / "low" / "normal" / "high"). Variants order “in order of increasing urgency”, somaxpicks the most urgent. “A push message without the Urgency header field defaults to a value of “normal”.“
Constants§
- GLTF_
BINARY - The mandatory-to-implement visual asset media type: “The IANA media
type
model/gltf-binary(.glb) MUST be listed insupportedVisualTypes” (draft-atwood-jmap-scene-00 §Preferred Asset Format). - JMAP_
SCENE_ URI - Capability URI for
urn:ietf:params:jmap:scene. Capability URI for JMAP Scene (draft-atwood-jmap-scene-00 §Capability). - SCENE_
DATA_ TYPES - The data types that participate in the state-change mechanism.
Traits§
- Scene
Backend - Storage backend for the JMAP Scene method handlers (draft-atwood-jmap-scene-00).
Functions§
- handle_
scene_ asset_ changes - Handle
SceneAsset/changes(draft-atwood-jmap-scene-00 §SceneAsset/changes): standard RFC 8620 §5.2/changes. - handle_
scene_ asset_ get - Handle
SceneAsset/get(draft-atwood-jmap-scene-00 §SceneAsset/get): standard RFC 8620 §5.1/get. - handle_
scene_ asset_ query - Handle
SceneAsset/query(draft-atwood-jmap-scene-00 §SceneAsset/query). - handle_
scene_ asset_ query_ changes - Handle
SceneAsset/queryChanges(draft-atwood-jmap-scene-00 §SceneAsset/queryChanges). RFC 8620 §5.6: thefilterandsortare those of the original query, so the/queryrules apply here too. - handle_
scene_ asset_ set - Handle
SceneAsset/set(draft-atwood-jmap-scene-00 §SceneAsset/set). - handle_
scene_ avatar_ changes - Handle
SceneAvatar/changes(draft-atwood-jmap-scene-00 §SceneAvatar/changes): standard RFC 8620 §5.2/changes. - handle_
scene_ avatar_ get - Handle
SceneAvatar/get(draft-atwood-jmap-scene-00 §SceneAvatar/get): standard RFC 8620 §5.1/get, with an avatar in a region the caller has no access to (SceneBackend::may_access_region), of a user the caller blocked (SceneBackend::is_user_blocked) or in a region whose avatars the caller may not see (SceneBackend::may_see_region_avatars, a region bound to an E2EE call) reported asnotFound(§Region Access, §Blocked-Contact Spatial Presence, §Security Considerations). - handle_
scene_ avatar_ query - Handle
SceneAvatar/query(draft-atwood-jmap-scene-00 §SceneAvatar/query). - handle_
scene_ avatar_ query_ changes - Handle
SceneAvatar/queryChanges(draft-atwood-jmap-scene-00 §SceneAvatar/queryChanges). RFC 8620 §5.6: thefilterandsortare those of the original query, so the/queryrules apply here too. - handle_
scene_ avatar_ set - Handle
SceneAvatar/set(draft-atwood-jmap-scene-00 §SceneAvatar/set). - handle_
scene_ object_ changes - Handle
SceneObject/changes(draft-atwood-jmap-scene-00 §SceneObject/changes): standard RFC 8620 §5.2/changes. - handle_
scene_ object_ get - Handle
SceneObject/get(draft-atwood-jmap-scene-00 §SceneObject/get): standard RFC 8620 §5.1/get, with an object in a region the caller has no access to (SceneBackend::may_access_region) or outside its visibility set (SceneBackend::is_object_visible) reported asnotFound(§Visibility Contract, §Region Access). - handle_
scene_ object_ interact - Handle
SceneObject/interact. - handle_
scene_ object_ query - Handle
SceneObject/query(draft-atwood-jmap-scene-00 §SceneObject/query). - handle_
scene_ object_ query_ changes - Handle
SceneObject/queryChanges(draft-atwood-jmap-scene-00 §SceneObject/queryChanges). RFC 8620 §5.6: thefilterandsortare those of the original query, so the/queryrules apply here too. - handle_
scene_ object_ set - Handle
SceneObject/set(draft-atwood-jmap-scene-00 §SceneObject/set). - handle_
scene_ region_ changes - Handle
SceneRegion/changes(draft-atwood-jmap-scene-00 §SceneRegion/changes): standard RFC 8620 §5.2/changes. - handle_
scene_ region_ get - Handle
SceneRegion/get(draft-atwood-jmap-scene-00 §SceneRegion/get): standard RFC 8620 §5.1/get, with a region the caller has no access to (SceneBackend::may_access_region) reported asnotFound(§Region Access). OfinvitedUserIds, “The server returns the list only to callers who may update the region; for every other caller, the server returns[]” (SceneBackend::may_update_region). - handle_
scene_ region_ query - Handle
SceneRegion/query(draft-atwood-jmap-scene-00 §SceneRegion/query). - handle_
scene_ region_ query_ changes - Handle
SceneRegion/queryChanges(draft-atwood-jmap-scene-00 §SceneRegion/queryChanges). RFC 8620 §5.6: thefilterandsortare those of the original query, so the/queryrules apply here too. - handle_
scene_ region_ set - Handle
SceneRegion/set(draft-atwood-jmap-scene-00 §SceneRegion/set). - push_
urgency - The urgency for one
StateChangecoveringevents: the highest of their urgencies, orNonewheneventsis empty. - register_
scene_ handlers - Register the
SceneAsset/*,SceneRegion/*,SceneObject/*andSceneAvatar/*method handlers withdispatcher. - should_
deliver - Whether
eventmay be delivered on a connection whose subscription issubscription. - validate_
interaction - The
SceneInteractionEventto relay for a frame a client sent, orNoneto discard it (draft-atwood-jmap-scene-wss-00 §Client-to-Server Submission).