Skip to main content

Crate jmap_scene_server

Crate jmap_scene_server 

Source
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 suggestion 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§

memorymemory
In-memory reference implementation of SceneBackend.
query
/query filter evaluation and ordering for SceneAsset, SceneRegion, SceneObject and SceneAvatar (draft-atwood-jmap-scene-00 §SceneAsset/query, §SceneRegion/query, §SceneObject/query, §SceneAvatar/query).

Structs§

SceneEphemeralSubscription
The ephemeral Scene subscription of one WebSocket connection.
SceneStreamFilter
The active filters of an enabled subscription.

Enums§

BindingProperty
A SceneRegion binding property, the reference SceneBackend::region_binding is asked about (draft-atwood-jmap-scene-00 §Creating a Region, §Updating a Region).
BindingTarget
What SceneBackend::region_binding knows about the object a SceneRegion binding property references.
RegionScope
Which regions a subscription covers.
SceneEvent
A change, as seen by the user who receives the push, for which §Push Urgency suggests an urgency (jmap-chat-spec 77c3474 L2854: the server “MAY set the Urgency header”; “The following urgency assignments are suggested”).
Urgency
The Web Push Urgency header (RFC 8030 §5.3) that push_urgency picks; the same type jmap-web-push sends. The Web Push Urgency header (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”, so max picks 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 in supportedVisualTypes” (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§

SceneBackend
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: the filter and sort are those of the original query, so the /query rules 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 as notFound (§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: the filter and sort are those of the original query, so the /query rules 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 as notFound (§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: the filter and sort are those of the original query, so the /query rules 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 as notFound (§Region Access). Of invitedUserIds, “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: the filter and sort are those of the original query, so the /query rules apply here too.
handle_scene_region_set
Handle SceneRegion/set (draft-atwood-jmap-scene-00 §SceneRegion/set).
push_urgency
The urgency for one StateChange covering events: the highest of their urgencies, or None when events is empty.
register_scene_conditional
Opt this crate’s registered Foo/set methods in to draft-ietf-jmap-conditional-02 (ifUnchangedBy and atomic; docs/design/DECISIONS.md decisions 1 and 17).
register_scene_handlers
Register the SceneAsset/*, SceneRegion/*, SceneObject/* and SceneAvatar/* method handlers with dispatcher.
register_scene_handlers_with_history
register_scene_handlers, then history-aware /get, /set, /query and /queryChanges of SceneAsset, SceneRegion and SceneObject, each wrapping the unchanged plain handler, through Dispatcher::register_history_aware (docs/design/DECISIONS.md decision 1). SceneObject/interact is not a /set and is unchanged.
should_deliver
Whether event may be delivered on a connection whose subscription is subscription.
validate_interaction
The SceneInteractionEvent to relay for a frame a client sent, or None to discard it (draft-atwood-jmap-scene-wss-00 §Client-to-Server Submission).